@microsoft/agents-hosting 0.6.1 → 0.6.11

package/src/oauth/userTokenClient.ts

@@ -3,7 +3,7 @@
 
 import axios, { AxiosInstance } from 'axios'
 import { ConversationReference } from '@microsoft/agents-activity'
-import { debug } from '../logger'
+import { debug } from '@microsoft/agents-activity/src/logger'
 import { normalizeTokenExchangeState } from '../activityWireCompat'
 import { AadResourceUrls, SignInResource, TokenExchangeRequest, TokenOrSinginResourceResponse, TokenResponse, TokenStatus } from './userTokenClient.types'
 import { getProductInfo } from '../getProductInfo'

package/src/state/agentState.ts

@@ -7,7 +7,7 @@ import { Storage, StorageKeyFactory, StoreItem } from '../storage/storage'
 import { TurnContext } from '../turnContext'
 import { createHash } from 'node:crypto'
 import { AgentStatePropertyAccessor } from './agentStatePropertyAccesor'
-import { debug } from '../logger'
+import { debug } from '@microsoft/agents-activity/src/logger'
 
 const logger = debug('agents:state')
 

package/src/state/agentStatePropertyAccesor.ts

@@ -73,56 +73,176 @@ export interface StatePropertyAccessor<T = any> {
 }
 
 /**
- * Provides typed access to an Agent state property with automatic state loading.
+ * Provides typed access to an Agent state property with automatic state loading and persistence management.
  *
- * The AgentStatePropertyAccessor simplifies working with state by abstracting
- * the details of loading state from storage and manipulating specific properties.
- * It automatically handles:
+ * @remarks
+ * 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:
  *
- * - 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
+ * - **Lazy Loading**: State is loaded from storage only when first accessed
+ * - **Type Safety**: Full TypeScript support with generic type parameters
+ * - **Default Values**: Automatic deep cloning of default values to prevent reference issues
+ * - **Memory Management**: Efficient in-memory caching with explicit persistence control
+ * - **Custom Keys**: Support for custom storage keys for advanced scenarios
  *
- * Property accessors are created through the {@link AgentState.createProperty} method:
+ * ## Key Features
  *
+ * ### Type Safety
+ * The accessor provides compile-time type checking when using TypeScript:
  * ```typescript
- * // Create a property accessor for a user profile
+ * interface UserProfile {
+ *   name: string;
+ *   preferences: { theme: string; language: string };
+ * }
  * const userProfile = userState.createProperty<UserProfile>("userProfile");
+ * ```
+ *
+ * ### Automatic Default Value Handling
+ * When a property doesn't exist, default values are automatically cloned and stored:
+ * ```typescript
+ * // If userProfile doesn't exist, the default will be cloned and saved
+ * const profile = await userProfile.get(context, {
+ *   name: "Anonymous",
+ *   preferences: { theme: "light", language: "en" }
+ * });
+ * ```
+ *
+ * ### Explicit Persistence Control
+ * Changes are kept in memory until explicitly persisted:
+ * ```typescript
+ * // Modify the state
+ * const counter = await counterProperty.get(context, 0);
+ * await counterProperty.set(context, counter + 1);
+ *
+ * // Changes are only in memory at this point
+ * // Persist to storage
+ * await userState.saveChanges(context);
+ * ```
  *
- * // Get the profile with a default if not exists
- * const profile = await userProfile.get(context, { name: "", preferences: {} });
+ * ## Usage Examples
  *
- * // Update a value
+ * ### Basic Usage
+ * ```typescript
+ * // Create a property accessor
+ * const userProfile = userState.createProperty<UserProfile>("userProfile");
+ *
+ * // Get with default value
+ * const profile = await userProfile.get(context, {
+ *   name: "",
+ *   preferences: { theme: "light", language: "en" }
+ * });
+ *
+ * // Modify the profile
  * profile.preferences.theme = "dark";
  *
- * // Save the change
+ * // Save the changes
  * await userProfile.set(context, profile);
+ * await userState.saveChanges(context); // Persist to storage
+ * ```
+ *
+ * ### Working with Primitive Types
+ * ```typescript
+ * const counterProperty = userState.createProperty<number>("counter");
  *
- * // Later, call userState.saveChanges(context) to persist to storage
+ * // Increment counter
+ * const currentCount = await counterProperty.get(context, 0);
+ * await counterProperty.set(context, currentCount + 1);
+ * await userState.saveChanges(context);
  * ```
  *
- * @typeParam T The type of the property being accessed
+ * ### Conditional Logic
+ * ```typescript
+ * const settingsProperty = userState.createProperty<Settings>("settings");
+ *
+ * // Check if property exists
+ * const settings = await settingsProperty.get(context);
+ * if (settings === undefined) {
+ *   // Property doesn't exist, initialize with defaults
+ *   await settingsProperty.set(context, getDefaultSettings());
+ * }
+ * ```
+ *
+ * ### Custom Storage Keys
+ * ```typescript
+ * // Store state with a custom key for multi-tenant scenarios
+ * const customKey = { key: `tenant_${tenantId}` };
+ * const tenantData = await dataProperty.get(context, defaultData, customKey);
+ * await dataProperty.set(context, updatedData, customKey);
+ * ```
+ *
+ * ## Important Notes
+ *
+ * - **Thread Safety**: This class is not thread-safe. Ensure proper synchronization in concurrent scenarios.
+ * - **Memory Usage**: State objects are kept in memory until the context is disposed.
+ * - **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
  */
 export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccessor<T> {
   /**
    * Creates a new instance of AgentStatePropertyAccessor.
    *
-   * @param state The agent state object that will contain this property
-   * @param name The name of the property in the state object
+   * @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
+   * const userProfile = userState.createProperty<UserProfile>("userProfile");
+   *
+   * // Direct construction (not recommended)
+   * const accessor = new AgentStatePropertyAccessor<UserProfile>(userState, "userProfile");
+   * ```
    */
   constructor (protected readonly state: AgentState, public readonly name: string) { }
 
   /**
-   * Deletes the property from the state.
+   * Deletes the property from the state storage.
    *
-   * This removes the property from the state object but does not automatically
-   * persist the change to storage. Call state.saveChanges() afterwards to
-   * persist changes.
+   * 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
+   * `state.saveChanges(context)` afterwards to persist the deletion.
+   *
+   * @remarks
+   * - If the property doesn't exist, this operation is a no-op
+   * - 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.
    *
-   * @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
+   *
+   * @example
+   * ```typescript
+   * const userSettings = userState.createProperty<UserSettings>("settings");
+   *
+   * // Delete the user settings
+   * await userSettings.delete(context);
+   *
+   * // Persist the deletion to storage
+   * await userState.saveChanges(context);
+   *
+   * // Verify deletion
+   * const settings = await userSettings.get(context); // Returns undefined
+   * ```
+   *
+   * @example Custom key usage
+   * ```typescript
+   * const tenantKey = { key: `tenant_${tenantId}` };
+   * 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)
@@ -132,16 +252,70 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
   }
 
   /**
-   * Gets the value of the property from the state.
+   * Retrieves the value of the property from state storage.
+   *
+   * This method provides intelligent default value handling:
+   * - If the property exists, its value is returned
+   * - If the property doesn't exist and a default value is provided, the default is deep cloned,
+   *   stored in state, and returned
+   * - If the property doesn't exist and no default is provided, `undefined` is returned
+   *
+   * @remarks
+   * **Deep Cloning**: Default values are deep cloned using JSON serialization to prevent
+   * reference sharing issues. This means:
+   * - Functions, symbols, and circular references will be lost
+   * - Dates become strings (use Date constructor to restore)
+   * - Complex objects with prototypes lose their prototype chain
+   *
+   * **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.
    *
-   * 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.
+   * @returns A promise that resolves to the property value, the cloned default value, or `undefined`
    *
-   * @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
+   * @example Basic usage
+   * ```typescript
+   * const counterProperty = userState.createProperty<number>("counter");
+   *
+   * // Get with default value
+   * const count = await counterProperty.get(context, 0);
+   * console.log(count); // 0 if property doesn't exist, otherwise the stored value
+   * ```
+   *
+   * @example Complex object with default
+   * ```typescript
+   * interface UserProfile {
+   *   name: string;
+   *   preferences: { theme: string; notifications: boolean };
+   * }
+   *
+   * const userProfile = userState.createProperty<UserProfile>("profile");
+   * const profile = await userProfile.get(context, {
+   *   name: "Anonymous",
+   *   preferences: { theme: "light", notifications: true }
+   * });
+   * ```
+   *
+   * @example Checking for existence
+   * ```typescript
+   * const profile = await userProfile.get(context);
+   * if (profile === undefined) {
+   *   console.log("Profile has not been set yet");
+   * } else {
+   *   console.log(`Welcome back, ${profile.name}!`);
+   * }
+   * ```
+   *
+   * @example Custom key usage
+   * ```typescript
+   * 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)
@@ -157,15 +331,72 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
   }
 
   /**
-   * Sets the value of the property in the state.
+   * Sets the value of the property in state storage.
    *
-   * 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.
+   * 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
+   * `state.saveChanges(context)` afterwards to persist the changes.
+   *
+   * @remarks
+   * **Memory vs Storage**: Changes are immediately reflected in memory and will be
+   * available to subsequent `get()` calls within the same context, but are not
+   * persisted to storage until `saveChanges()` is called.
+   *
+   * **Value References**: The exact value reference is stored (no cloning occurs).
+   * Ensure you don't modify objects after setting them unless you intend for those
+   * changes to be reflected in state.
+   *
+   * **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.
    *
-   * @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
+   *
+   * @example Basic usage
+   * ```typescript
+   * const counterProperty = userState.createProperty<number>("counter");
+   *
+   * // Set a new value
+   * await counterProperty.set(context, 42);
+   *
+   * // Persist to storage
+   * await userState.saveChanges(context);
+   * ```
+   *
+   * @example Complex object
+   * ```typescript
+   * const userProfile = userState.createProperty<UserProfile>("profile");
+   *
+   * const newProfile: UserProfile = {
+   *   name: "John Doe",
+   *   preferences: { theme: "dark", notifications: false }
+   * };
+   *
+   * await userProfile.set(context, newProfile);
+   * await userState.saveChanges(context);
+   * ```
+   *
+   * @example Incremental updates
+   * ```typescript
+   * // Get current value, modify, then set
+   * const settings = await settingsProperty.get(context, getDefaultSettings());
+   * settings.theme = "dark";
+   * settings.lastUpdated = new Date();
+   *
+   * await settingsProperty.set(context, settings);
+   * await userState.saveChanges(context);
+   * ```
+   *
+   * @example Custom key usage
+   * ```typescript
+   * const tenantKey = { key: `tenant_${tenantId}` };
+   * 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/statusCodes.ts

@@ -3,69 +3,99 @@
  * Licensed under the MIT License.
  */
 
+/**
+ * HTTP status codes enumeration for agent hosting responses.
+ *
+ * This enum provides a comprehensive set of HTTP status codes commonly used
+ * in agent hosting scenarios, including success, redirection, client error,
+ * and server error status codes.
+ */
 export enum StatusCodes {
   /**
    * The request has succeeded.
+   * Standard response for successful HTTP requests.
    */
   OK = 200,
 
   /**
    * The request has been fulfilled and resulted in a new resource being created.
+   * Typically returned when a new agent, conversation, or resource is successfully created.
    */
   CREATED = 201,
 
   /**
    * Indicates multiple options for the resource that the client may follow.
+   * Used when there are multiple possible responses or resource locations available.
    */
   MULTIPLE_CHOICES = 300,
 
   /**
    * The server cannot or will not process the request due to a client error.
+   * Returned when the request contains invalid syntax, malformed parameters,
+   * or violates agent hosting protocol requirements.
    */
   BAD_REQUEST = 400,
 
   /**
    * The request requires user authentication.
+   * Indicates that the client must authenticate itself to get the requested response.
+   * Common in agent scenarios requiring valid authentication tokens or credentials.
    */
   UNAUTHORIZED = 401,
 
   /**
    * The requested resource could not be found.
+   * Returned when the specified agent, conversation, or endpoint does not exist
+   * or is not accessible with the current permissions.
    */
   NOT_FOUND = 404,
 
   /**
    * The request method is not allowed for the requested resource.
+   * Indicates that the HTTP method used is not supported for the specific
+   * agent endpoint or resource being accessed.
    */
   METHOD_NOT_ALLOWED = 405,
 
   /**
    * The request could not be completed due to a conflict with the current state of the resource.
+   * Common when attempting to create duplicate resources or when agent state
+   * conflicts prevent the operation from completing.
    */
   CONFLICT = 409,
 
   /**
    * The server does not meet one of the preconditions specified by the client.
+   * Returned when conditional requests fail, such as when required headers
+   * or agent capabilities are not present or valid.
    */
   PRECONDITION_FAILED = 412,
 
   /**
    * The client should switch to a different protocol.
+   * Used to indicate that the agent hosting service requires a protocol upgrade
+   * or different communication method to fulfill the request.
    */
   UPGRADE_REQUIRED = 426,
 
   /**
    * The server encountered an unexpected condition that prevented it from fulfilling the request.
+   * Generic error message when an unexpected agent hosting error occurs
+   * and no more specific message is suitable.
    */
   INTERNAL_SERVER_ERROR = 500,
 
   /**
    * The server does not support the functionality required to fulfill the request.
+   * Returned when the agent hosting service does not implement the requested
+   * feature or capability.
    */
   NOT_IMPLEMENTED = 501,
 
   /**
    * The server received an invalid response from the upstream server.
+   * Common when agent hosting services depend on external services
+   * that return invalid or malformed responses.
    */
   BAD_GATEWAY = 502,
 }

package/src/storage/fileStorage.ts

@@ -1,10 +1,69 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
 import path from 'path'
 import fs from 'fs'
 import { Storage, StoreItem } from './storage'
 
+/**
+ * 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.
+ * This implementation is suitable for development scenarios, local testing, and single-instance
+ * deployments where shared state across multiple instances is not required.
+ *
+ * The storage format is a simple key-value JSON object where keys are strings and values
+ * can be any JSON-serializable data. All operations are synchronous file I/O operations
+ * wrapped in Promise interfaces to match the Storage contract.
+ *
+ * @example
+ * ```typescript
+ * const storage = new FileStorage('./data');
+ *
+ * // Write some data
+ * await storage.write({
+ *   'user123': { name: 'John', lastSeen: new Date().toISOString() },
+ *   'conversation456': { turn: 5, context: 'discussing weather' }
+ * });
+ *
+ * // Read specific keys
+ * const data = await storage.read(['user123']);
+ * console.log(data.user123); // { name: 'John', lastSeen: '...' }
+ *
+ * // Delete data
+ * await storage.delete(['conversation456']);
+ * ```
+ *
+ * @warning
+ * This implementation does not provide:
+ * - Thread safety for concurrent access
+ * - Optimistic concurrency control (eTag support)
+ * - Atomic operations across multiple keys
+ * - Scale for large datasets
+ *
+ * For production scenarios requiring these features, consider using
+ * database-backed storage implementations instead.
+ */
 export class FileStorage implements Storage {
   private _folder: string
   private _stateFile: Record<string, string>
+
+  /**
+   * 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
+   *
+   * @remarks
+   * The constructor performs the following initialization steps:
+   * 1. Creates the target folder if it doesn't exist (including parent directories)
+   * 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
     if (!fs.existsSync(folder)) {
@@ -17,6 +76,19 @@ export class FileStorage implements Storage {
     this._stateFile = JSON.parse(data)
   }
 
+  /**
+   * Reads store items from the filesystem 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) => {
       if (!keys || keys.length === 0) {
@@ -34,6 +106,20 @@ export class FileStorage implements Storage {
     })
   }
 
+  /**
+   * Writes store items to the filesystem storage.
+   *
+   * @param changes Object containing key-value pairs to write to storage
+   * @returns Promise that resolves when the write operation completes
+   *
+   * @remarks
+   * This method updates both the in-memory cache and writes the entire state
+   * 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.
+   */
   write (changes: StoreItem) : Promise<void> {
     const keys = Object.keys(changes)
     for (const key of keys) {
@@ -43,6 +129,19 @@ export class FileStorage implements Storage {
     return Promise.resolve()
   }
 
+  /**
+   * Deletes store items from the filesystem storage.
+   *
+   * @param keys Array of keys to delete from storage
+   * @returns Promise that resolves when the delete operation completes
+   *
+   * @throws ReferenceError if keys array is empty or undefined
+   *
+   * @remarks
+   * 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) => {
       if (!keys || keys.length === 0) {

package/src/storage/memoryStorage.ts

@@ -4,13 +4,14 @@
  */
 
 import { Storage, StoreItem } from './storage'
-import { debug } from '../logger'
+import { debug } from '@microsoft/agents-activity/src/logger'
 
 const logger = debug('agents:memory-storage')
 
 /**
  * A simple in-memory storage provider that implements the Storage interface.
  *
+ * @remarks
  * 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
@@ -18,7 +19,7 @@ const logger = debug('agents:memory-storage')
  * - 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
+ * can be used as a singleton through the {@link MemoryStorage.getSingleInstance | getSingleInstance() method} to
  * share state across different parts of an application.
  */
 export class MemoryStorage implements Storage {

package/src/storage/storage.ts

@@ -48,6 +48,7 @@ export type StorageKeyFactory = (context: TurnContext) => string | Promise<strin
 /**
  * Defines the interface for storage operations in the Agents platform.
  *
+ * @remarks
  * 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.

package/src/transcript/transcriptLoggerMiddleware.ts

@@ -3,7 +3,7 @@ import { ResourceResponse } from '../connector-client'
 import { Middleware } from '../middlewareSet'
 import { TranscriptLogger } from './transcriptLogger'
 import { Activity, ActivityEventNames, ActivityTypes, ConversationReference, RoleTypes } from '@microsoft/agents-activity'
-import { debug } from '../logger'
+import { debug } from '@microsoft/agents-activity/src/logger'
 
 const appLogger = debug('agents:rest-client')
 

package/src/turnContext.ts

@@ -51,6 +51,7 @@ export interface TurnContext {}
 /**
  * Represents the context for a single turn in a conversation between a user and an agent.
  *
+ * @remarks
  * 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