@microsoft/agents-hosting 0.2.9-g361635b71c → 0.2.14

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

@@ -4,47 +4,81 @@
  */
 import { Storage, StoreItem } from './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 declare class MemoryStorage implements Storage {
     private memory;
     private static instance;
+    /**
+     * Counter used to generate unique eTags for stored items
+     */
     private etag;
     /**
      * 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(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;
     /**
      * 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
      */
     read(keys: string[]): Promise<StoreItem>;
     /**
      * 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
      */
     write(changes: StoreItem): Promise<void>;
     /**
      * 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
      */
     delete(keys: string[]): Promise<void>;
     /**
-     * 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;
 }

package/dist/src/storage/memoryStorage.js

@@ -8,19 +8,38 @@ exports.MemoryStorage = void 0;
 const logger_1 = require("../logger");
 const logger = (0, logger_1.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.
  */
 class MemoryStorage {
     /**
      * 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(memory = {}) {
         this.memory = memory;
+        /**
+         * Counter used to generate unique eTags for stored items
+         */
         this.etag = 1;
     }
     /**
-     * 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() {
         if (!MemoryStorage.instance) {
@@ -30,9 +49,10 @@ class MemoryStorage {
     }
     /**
      * 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) {
         if (!keys || keys.length === 0) {
@@ -50,9 +70,15 @@ class MemoryStorage {
     }
     /**
      * 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) {
         if (!changes || changes.length === 0) {
@@ -77,8 +103,9 @@ class MemoryStorage {
     }
     /**
      * 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) {
         logger.info(`Deleting keys: ${keys.join(', ')}`);
@@ -87,9 +114,16 @@ class MemoryStorage {
         }
     }
     /**
-     * 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
      */
     saveItem(key, item) {
         const clone = Object.assign({}, item, { eTag: (this.etag++).toString() });

package/dist/src/storage/memoryStorage.js.map

@@ -1 +1 @@
-{"version":3,"file":"memoryStorage.js","sourceRoot":"","sources":["../../../src/storage/memoryStorage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"memoryStorage.js","sourceRoot":"","sources":["../../../src/storage/memoryStorage.ts"],"names":[],"mappings":"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"}

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

@@ -4,44 +4,74 @@
  */
 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 {
+    /**
+     * 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>;
     /**
      * 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>;
     /**
      * 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>;
 }

package/dist/src/turnContext.d.ts

@@ -5,19 +5,34 @@ import { TurnContextStateCollection } from './turnContextStateCollection';
 import { AttachmentInfo } from './connector-client/attachmentInfo';
 import { AttachmentData } from './connector-client/attachmentData';
 /**
- * Defines a handler for sending activities.
+ * Defines a handler for processing and sending activities.
+ * Used for middleware that needs to intercept or modify activities being sent.
+ *
+ * @param context The current turn context
+ * @param activities The activities being sent
+ * @param next Function to call to continue the middleware chain
  */
 export type SendActivitiesHandler = (context: TurnContext, activities: Activity[], next: () => Promise<ResourceResponse[]>) => Promise<ResourceResponse[]>;
 /**
  * Defines a handler for updating an activity.
+ * Used for middleware that needs to intercept or modify activity updates.
+ *
+ * @param context The current turn context
+ * @param activity The activity being updated
+ * @param next Function to call to continue the middleware chain
  */
 export type UpdateActivityHandler = (context: TurnContext, activity: Activity, next: () => Promise<void>) => Promise<void>;
 /**
  * Defines a handler for deleting an activity.
+ * Used for middleware that needs to intercept or handle activity deletions.
+ *
+ * @param context The current turn context
+ * @param reference Reference to the activity being deleted
+ * @param next Function to call to continue the middleware chain
  */
 export type DeleteActivityHandler = (context: TurnContext, reference: ConversationReference, next: () => Promise<void>) => Promise<void>;
 /**
- * Key for the agent callback handler.
+ * Key for the agent callback handler in TurnState collection.
  */
 export declare const AgentCallbackHandlerKey = "agentCallbackHandler";
 /**
@@ -26,7 +41,20 @@ export declare const AgentCallbackHandlerKey = "agentCallbackHandler";
 export interface TurnContext {
 }
 /**
- * Represents the context object for a turn of an Agent.
+ * Represents the context for a single turn in a conversation between a user and an agent.
+ *
+ * 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
+ * - A state collection for storing information during the turn
+ * - Methods for sending, updating, and deleting activities
+ * - Middleware hooks for intercepting activity operations
+ *
+ * The TurnContext object is created by the adapter when an activity is received
+ * and is passed to the agent's logic to process the turn. It maintains information
+ * about the conversation and provides methods to send responses.
+ *
+ * This class follows the builder pattern for registering middleware handlers.
  */
 export declare class TurnContext {
     private readonly _adapter?;
@@ -40,121 +68,179 @@ export declare class TurnContext {
     private readonly _locale;
     /**
      * Initializes a new instance of the TurnContext class.
-     * @param adapterOrContext The adapter or context for the turn.
-     * @param request The activity for the turn.
+     *
+     * @param adapterOrContext The adapter that created this context, or another TurnContext to clone
+     * @param request The activity for the turn (required when first parameter is an adapter)
      */
     constructor(adapterOrContext: BaseAdapter, request: Activity);
     constructor(adapterOrContext: TurnContext);
     /**
-     * A list of buffered reply activities.
+     * A list of reply activities that are buffered until the end of the turn.
+     *
+     * This is primarily used with the 'expectReplies' delivery mode where all
+     * activities during a turn are collected and returned as a single response.
      */
     readonly bufferedReplyActivities: Activity[];
     /**
-     * Sends a trace activity.
-     * @param name The name of the trace activity.
-     * @param value The value of the trace activity.
-     * @param valueType The value type of the trace activity.
-     * @param label The label of the trace activity.
-     * @returns The resource response.
+     * Sends a trace activity for debugging purposes.
+     *
+     * Trace activities are typically used for debugging and are only visible in
+     * channels that support them, like the Bot Framework Emulator.
+     *
+     * @param name The name/category of the trace
+     * @param value The value/data to include in the trace
+     * @param valueType Optional type name for the value
+     * @param label Optional descriptive label for the trace
+     * @returns A promise that resolves to the resource response or undefined
      */
     sendTraceActivity(name: string, value?: any, valueType?: string, label?: string): Promise<ResourceResponse | undefined>;
     /**
-     * Sends an activity.
-     * @param activityOrText The activity or text to send.
-     * @param speak The text to speak.
-     * @param inputHint The input hint.
-     * @returns The resource response.
+     * Sends an activity to the sender of the incoming activity.
+     *
+     * This is the primary method used to respond to the user. It automatically
+     * addresses the response to the correct conversation and recipient using
+     * information from the incoming activity.
+     *
+     * @param activityOrText The activity to send or a string for a simple message
+     * @param speak Optional text to be spoken by the agent
+     * @param inputHint Optional input hint to indicate if the agent is expecting input
+     * @returns A promise that resolves to the resource response or undefined
      */
     sendActivity(activityOrText: string | Activity, speak?: string, inputHint?: string): Promise<ResourceResponse | undefined>;
     /**
-     * Sends multiple activities.
-     * @param activities The activities to send.
-     * @returns The resource responses.
+     * Sends multiple activities to the sender of the incoming activity.
+     *
+     * This method applies conversation references to each activity and
+     * emits them through the middleware chain before sending them to
+     * the adapter.
+     *
+     * @param activities The array of activities to send
+     * @returns A promise that resolves to an array of resource responses
      */
     sendActivities(activities: Activity[]): Promise<ResourceResponse[]>;
     /**
-     * Updates an activity.
-     * @param activity The activity to update.
-     * @returns A promise representing the asynchronous operation.
+     * Updates an existing activity in the conversation.
+     *
+     * This can be used to edit previously sent activities, for example to
+     * update the content of an adaptive card or change a message.
+     *
+     * @param activity The activity to update with its ID specified
+     * @returns A promise that resolves when the activity has been updated
      */
     updateActivity(activity: Activity): Promise<void>;
     /**
-     * Deletes an activity.
-     * @param idOrReference The ID or reference of the activity to delete.
-     * @returns A promise representing the asynchronous operation.
+     * Deletes an activity from the conversation.
+     *
+     * @param idOrReference The ID of the activity to delete or a conversation reference
+     * @returns A promise that resolves when the activity has been deleted
      */
     deleteActivity(idOrReference: string | ConversationReference): Promise<void>;
     /**
-     * Uploads an attachment.
-     * @param conversationId The conversation ID.
-     * @param attachmentData The attachment data.
-     * @returns The resource response.
+     * Uploads an attachment to the conversation.
+     *
+     * @param conversationId The ID of the conversation
+     * @param attachmentData The attachment data to upload
+     * @returns A promise that resolves to the resource response
      */
     uploadAttachment(conversationId: string, attachmentData: AttachmentData): Promise<ResourceResponse>;
     /**
-     * Gets attachment information.
-     * @param attachmentId The attachment ID.
-     * @returns The attachment information.
+     * Gets information about an attachment.
+     *
+     * @param attachmentId The ID of the attachment
+     * @returns A promise that resolves to the attachment information
      */
     getAttachmentInfo(attachmentId: string): Promise<AttachmentInfo>;
     /**
-     * Gets an attachment.
-     * @param attachmentId The attachment ID.
-     * @param viewId The view ID.
-     * @returns The readable stream of the attachment.
+     * Gets the content of an attachment.
+     *
+     * @param attachmentId The ID of the attachment
+     * @param viewId The view to get
+     * @returns A promise that resolves to a readable stream of the attachment content
      */
     getAttachment(attachmentId: string, viewId: string): Promise<NodeJS.ReadableStream>;
     /**
-     * Registers a handler for sending activities.
-     * @param handler The handler to register.
-     * @returns The current TurnContext instance.
+     * Registers a handler for intercepting and processing activities being sent.
+     *
+     * This method follows a middleware pattern, allowing multiple handlers to
+     * be chained together. Handlers can modify activities or inject new ones.
+     *
+     * @param handler The handler to register
+     * @returns The current TurnContext instance for chaining
      */
     onSendActivities(handler: SendActivitiesHandler): this;
     /**
-     * Registers a handler for updating activities.
-     * @param handler The handler to register.
-     * @returns The current TurnContext instance.
+     * Registers a handler for intercepting activity updates.
+     *
+     * @param handler The handler to register
+     * @returns The current TurnContext instance for chaining
      */
     onUpdateActivity(handler: UpdateActivityHandler): this;
     /**
-     * Registers a handler for deleting activities.
-     * @param handler The handler to register.
-     * @returns The current TurnContext instance.
+     * Registers a handler for intercepting activity deletions.
+     *
+     * @param handler The handler to register
+     * @returns The current TurnContext instance for chaining
      */
     onDeleteActivity(handler: DeleteActivityHandler): this;
     /**
      * Copies the properties of this TurnContext to another TurnContext.
-     * @param context The context to copy to.
+     *
+     * Used internally when cloning contexts.
+     *
+     * @param context The context to copy to
+     * @protected
      */
     protected copyTo(context: TurnContext): void;
     /**
-     * Gets the adapter for the turn.
+     * Gets the adapter that created this context.
+     *
+     * The adapter is responsible for sending and receiving activities
+     * to and from the user's channel.
      */
     get adapter(): BaseAdapter;
     /**
-     * Gets the activity for the turn.
+     * Gets the incoming activity that started this turn.
+     *
+     * This is the activity that was received from the user or channel
+     * and triggered the creation of this context.
      */
     get activity(): Activity;
     /**
-     * Gets or sets whether the turn has responded.
+     * Gets or sets whether the turn has sent a response to the user.
+     *
+     * This is used to track whether the agent has responded to the user's
+     * activity. Once set to true, it cannot be set back to false.
      */
     get responded(): boolean;
     set responded(value: boolean);
     /**
      * Gets or sets the locale for the turn.
+     *
+     * The locale affects language-dependent operations like
+     * formatting dates or numbers.
      */
     get locale(): string | undefined;
     set locale(value: string | undefined);
     /**
-     * Gets the turn state collection.
+     * Gets the turn state collection for storing data during the turn.
+     *
+     * The turn state collection provides a dictionary-like interface
+     * for storing arbitrary data that needs to be accessible during
+     * the processing of the current turn.
      */
     get turnState(): TurnContextStateCollection;
     /**
-     * Emits events to the registered handlers.
-     * @param handlers The handlers to emit to.
-     * @param arg The argument to pass to the handlers.
-     * @param next The next function to call.
-     * @returns The result of the handlers.
+     * Emits events to registered middleware handlers.
+     *
+     * This internal method implements the middleware pattern, allowing
+     * handlers to be chained together with each having the option to
+     * short-circuit the chain.
+     *
+     * @param handlers Array of handlers to execute
+     * @param arg The argument to pass to each handler
+     * @param next The function to execute at the end of the middleware chain
+     * @returns A promise that resolves to the result from the handlers or next function
+     * @private
      */
     private emit;
 }