@microsoft/agents-hosting 0.6.1 → 0.6.16-gc874f0c9d8

package/dist/src/state/agentStatePropertyAccesor.js

@@ -6,58 +6,178 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentStatePropertyAccessor = void 0;
 /**
- * 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
  */
 class AgentStatePropertyAccessor {
     /**
      * 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(state, name) {
         this.state = state;
         this.name = name;
     }
     /**
-     * Deletes the property from the state.
+     * Deletes the property from the state storage.
+     *
+     * 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.
      *
-     * This removes the property from the state object but does not automatically
-     * persist the change to storage. Call state.saveChanges() afterwards to
-     * persist changes.
+     * @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, customKey) {
         const obj = await this.state.load(context, false, customKey);
@@ -66,16 +186,70 @@ class AgentStatePropertyAccessor {
         }
     }
     /**
-     * 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.
+     *
+     * @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");
+     *
+     * // 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 };
+     * }
      *
-     * 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.
+     * const userProfile = userState.createProperty<UserProfile>("profile");
+     * const profile = await userProfile.get(context, {
+     *   name: "Anonymous",
+     *   preferences: { theme: "light", notifications: true }
+     * });
+     * ```
      *
-     * @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 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, defaultValue, customKey) {
         const obj = await this.state.load(context, false, customKey);
@@ -88,15 +262,72 @@ class AgentStatePropertyAccessor {
         return obj[this.name];
     }
     /**
-     * Sets the value of the property in the state.
+     * Sets the value of the property in state storage.
+     *
+     * 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.
      *
-     * 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.
+     * **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, value, customKey) {
         const obj = await this.state.load(context, false, customKey);

package/dist/src/state/agentStatePropertyAccesor.js.map

@@ -1 +1 @@
-{"version":3,"file":"agentStatePropertyAccesor.js","sourceRoot":"","sources":["../../../src/state/agentStatePropertyAccesor.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAuEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAa,0BAA0B;IACrC;;;;;OAKG;IACH,YAAgC,KAAiB,EAAkB,IAAY;QAA/C,UAAK,GAAL,KAAK,CAAY;QAAkB,SAAI,GAAJ,IAAI,CAAQ;IAAI,CAAC;IAEpF;;;;;;;;;;OAUG;IACH,KAAK,CAAC,MAAM,CAAE,OAAoB,EAAE,SAAqB;QACvD,MAAM,GAAG,GAAQ,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,CAAA;QACjE,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACzD,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACvB,CAAC;IACH,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,GAAG,CAAE,OAAoB,EAAE,YAAgB,EAAE,SAAqB;QACtE,MAAM,GAAG,GAAQ,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,CAAA;QACjE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YACxF,MAAM,KAAK,GACT,OAAO,YAAY,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC;gBAC7D,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;gBAC1C,CAAC,CAAC,YAAY,CAAA;YAClB,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAA;QACxB,CAAC;QAED,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACvB,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,GAAG,CAAE,OAAoB,EAAE,KAAQ,EAAE,SAAqB;QAC9D,MAAM,GAAG,GAAQ,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,CAAA;QACjE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAA;IACxB,CAAC;CACF;AAnED,gEAmEC"}
+{"version":3,"file":"agentStatePropertyAccesor.js","sourceRoot":"","sources":["../../../src/state/agentStatePropertyAccesor.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAuEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8GG;AACH,MAAa,0BAA0B;IACrC;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAAgC,KAAiB,EAAkB,IAAY;QAA/C,UAAK,GAAL,KAAK,CAAY;QAAkB,SAAI,GAAJ,IAAI,CAAQ;IAAI,CAAC;IAEpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACH,KAAK,CAAC,MAAM,CAAE,OAAoB,EAAE,SAAqB;QACvD,MAAM,GAAG,GAAQ,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,CAAA;QACjE,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACzD,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACvB,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiEG;IACH,KAAK,CAAC,GAAG,CAAE,OAAoB,EAAE,YAAgB,EAAE,SAAqB;QACtE,MAAM,GAAG,GAAQ,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,CAAA;QACjE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YACxF,MAAM,KAAK,GACT,OAAO,YAAY,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC;gBAC7D,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;gBAC1C,CAAC,CAAC,YAAY,CAAA;YAClB,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAA;QACxB,CAAC;QAED,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACvB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmEG;IACH,KAAK,CAAC,GAAG,CAAE,OAAoB,EAAE,KAAQ,EAAE,SAAqB;QAC9D,MAAM,GAAG,GAAQ,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,CAAA;QACjE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAA;IACxB,CAAC;CACF;AA3ND,gEA2NC"}

package/dist/src/statusCodes.d.ts

@@ -2,57 +2,87 @@
  * Copyright (c) Microsoft Corporation. All rights reserved.
  * 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 declare 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/dist/src/statusCodes.js

@@ -5,58 +5,88 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StatusCodes = void 0;
+/**
+ * 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.
+ */
 var StatusCodes;
 (function (StatusCodes) {
     /**
      * The request has succeeded.
+     * Standard response for successful HTTP requests.
      */
     StatusCodes[StatusCodes["OK"] = 200] = "OK";
     /**
      * 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.
      */
     StatusCodes[StatusCodes["CREATED"] = 201] = "CREATED";
     /**
      * Indicates multiple options for the resource that the client may follow.
+     * Used when there are multiple possible responses or resource locations available.
      */
     StatusCodes[StatusCodes["MULTIPLE_CHOICES"] = 300] = "MULTIPLE_CHOICES";
     /**
      * 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.
      */
     StatusCodes[StatusCodes["BAD_REQUEST"] = 400] = "BAD_REQUEST";
     /**
      * 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.
      */
     StatusCodes[StatusCodes["UNAUTHORIZED"] = 401] = "UNAUTHORIZED";
     /**
      * 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.
      */
     StatusCodes[StatusCodes["NOT_FOUND"] = 404] = "NOT_FOUND";
     /**
      * 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.
      */
     StatusCodes[StatusCodes["METHOD_NOT_ALLOWED"] = 405] = "METHOD_NOT_ALLOWED";
     /**
      * 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.
      */
     StatusCodes[StatusCodes["CONFLICT"] = 409] = "CONFLICT";
     /**
      * 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.
      */
     StatusCodes[StatusCodes["PRECONDITION_FAILED"] = 412] = "PRECONDITION_FAILED";
     /**
      * 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.
      */
     StatusCodes[StatusCodes["UPGRADE_REQUIRED"] = 426] = "UPGRADE_REQUIRED";
     /**
      * 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.
      */
     StatusCodes[StatusCodes["INTERNAL_SERVER_ERROR"] = 500] = "INTERNAL_SERVER_ERROR";
     /**
      * 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.
      */
     StatusCodes[StatusCodes["NOT_IMPLEMENTED"] = 501] = "NOT_IMPLEMENTED";
     /**
      * 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.
      */
     StatusCodes[StatusCodes["BAD_GATEWAY"] = 502] = "BAD_GATEWAY";
 })(StatusCodes || (exports.StatusCodes = StatusCodes = {}));

package/dist/src/statusCodes.js.map

@@ -1 +1 @@
-{"version":3,"file":"statusCodes.js","sourceRoot":"","sources":["../../src/statusCodes.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,IAAY,WAiEX;AAjED,WAAY,WAAW;IACrB;;OAEG;IACH,2CAAQ,CAAA;IAER;;OAEG;IACH,qDAAa,CAAA;IAEb;;OAEG;IACH,uEAAsB,CAAA;IAEtB;;OAEG;IACH,6DAAiB,CAAA;IAEjB;;OAEG;IACH,+DAAkB,CAAA;IAElB;;OAEG;IACH,yDAAe,CAAA;IAEf;;OAEG;IACH,2EAAwB,CAAA;IAExB;;OAEG;IACH,uDAAc,CAAA;IAEd;;OAEG;IACH,6EAAyB,CAAA;IAEzB;;OAEG;IACH,uEAAsB,CAAA;IAEtB;;OAEG;IACH,iFAA2B,CAAA;IAE3B;;OAEG;IACH,qEAAqB,CAAA;IAErB;;OAEG;IACH,6DAAiB,CAAA;AACnB,CAAC,EAjEW,WAAW,2BAAX,WAAW,QAiEtB"}
+{"version":3,"file":"statusCodes.js","sourceRoot":"","sources":["../../src/statusCodes.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH;;;;;;GAMG;AACH,IAAY,WAwFX;AAxFD,WAAY,WAAW;IACrB;;;OAGG;IACH,2CAAQ,CAAA;IAER;;;OAGG;IACH,qDAAa,CAAA;IAEb;;;OAGG;IACH,uEAAsB,CAAA;IAEtB;;;;OAIG;IACH,6DAAiB,CAAA;IAEjB;;;;OAIG;IACH,+DAAkB,CAAA;IAElB;;;;OAIG;IACH,yDAAe,CAAA;IAEf;;;;OAIG;IACH,2EAAwB,CAAA;IAExB;;;;OAIG;IACH,uDAAc,CAAA;IAEd;;;;OAIG;IACH,6EAAyB,CAAA;IAEzB;;;;OAIG;IACH,uEAAsB,CAAA;IAEtB;;;;OAIG;IACH,iFAA2B,CAAA;IAE3B;;;;OAIG;IACH,qEAAqB,CAAA;IAErB;;;;OAIG;IACH,6DAAiB,CAAA;AACnB,CAAC,EAxFW,WAAW,2BAAX,WAAW,QAwFtB"}

package/dist/src/storage/fileStorage.d.ts

@@ -1,9 +1,106 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
 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 declare class FileStorage implements Storage {
     private _folder;
     private _stateFile;
+    /**
+     * 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);
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
 }