@microsoft/agents-hosting 1.9.0-beta.18.g6b8111bba5 → 1.9.0-beta.20.g0c48a31a21

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

@@ -45,19 +45,6 @@ export interface StoreItems {
      */
     [key: string]: any;
 }
-/**
- * Options for writing items to storage.
- */
-export interface StorageWriteOptions {
-    /**
-     * Optional time to live, in seconds, for written items.
-     *
-     * @remarks
-     * When set, storage providers should stop returning the written items after
-     * this duration has elapsed. Values must be finite numbers greater than zero.
-     */
-    ttl?: number;
-}
 /**
  * A factory function to generate storage keys based on the conversation context.
  *
@@ -70,7 +57,7 @@ export interface StorageWriteOptions {
  */
 export type StorageKeyFactory = (context: TurnContext) => string | Promise<string>;
 /**
- * Defines the interface for storage operations in the Agents platform.
+ * Defines the version 1 interface for storage operations in the Agents platform.
  *
  * @remarks
  * Storage providers persist state data across conversation turns, enabling
@@ -79,7 +66,9 @@ export type StorageKeyFactory = (context: TurnContext) => string | Promise<strin
  *
  * 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.
+ * in-memory and remote storage providers. New implementations should use
+ * {@link StorageV2}; this V1 interface remains supported by
+ * {@link StorageProvider} through a compatibility adapter.
  */
 export interface Storage {
     /**
@@ -97,7 +86,7 @@ export interface Storage {
      * @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, options?: StorageWriteOptions) => Promise<void>;
+    write: (changes: StoreItem) => Promise<void>;
     /**
      * Deletes store items from storage.
      *
@@ -106,3 +95,99 @@ export interface Storage {
      */
     delete: (keys: string[]) => Promise<void>;
 }
+/**
+ * The result of a version 2 storage read operation.
+ *
+ * A result is returned for every requested key. `value` and `version` are
+ * available when `status` is {@link StorageOperationStatus.Succeeded}.
+ */
+export interface StorageReadResult<T extends object = Record<string, unknown>> {
+    key: string;
+    status: StorageOperationStatus;
+    value?: T;
+    version?: string;
+}
+/**
+ * The result of a version 2 storage write operation.
+ */
+export interface StorageWriteResult {
+    key: string;
+    status: StorageOperationStatus;
+    version?: string;
+}
+/**
+ * The result of a version 2 storage delete operation.
+ */
+export interface StorageDeleteResult {
+    key: string;
+    status: StorageOperationStatus;
+    version?: string;
+}
+/** A keyed set of storage read results. */
+export type StorageReadResults<T extends object = Record<string, unknown>> = Record<string, StorageReadResult<T>>;
+/** A keyed set of storage write results. */
+export type StorageWriteResults = Record<string, StorageWriteResult>;
+/** A keyed set of storage delete results. */
+export type StorageDeleteResults = Record<string, StorageDeleteResult>;
+/** The outcome of one version 2 storage operation. */
+export declare enum StorageOperationStatus {
+    Succeeded = "succeeded",
+    NotFound = "notFound",
+    Conflict = "conflict",
+    ConditionNotMet = "conditionNotMet"
+}
+/** The write mode for a version 2 storage operation. */
+export declare enum StorageWriteMode {
+    Upsert = "upsert",
+    CreateOnly = "createOnly",
+    Replace = "replace"
+}
+/** Options applied to every item in a version 2 write operation. */
+export interface StorageWriteOptions {
+    /**
+     * Optional time to live, in seconds, for written items.
+     *
+     * When set, storage providers stop returning the written items after this
+     * duration has elapsed. Values must be finite numbers greater than zero.
+     */
+    ttl?: number;
+    mode?: StorageWriteMode;
+    expectedVersion?: string;
+}
+/** Options applied to every item in a version 2 delete operation. */
+export interface StorageDeleteOptions {
+    expectedVersion?: string;
+}
+/**
+ * The version 2 storage contract.
+ *
+ * This does not extend {@link Storage}: JavaScript cannot overload methods by
+ * return type at runtime. V2 providers are exposed as separately named classes.
+ */
+export declare abstract class StorageV2 {
+    /**
+     * Reads stored values and returns one result for every requested key.
+     *
+     * @param keys The keys to read. An empty array is valid.
+     * @returns Keyed results containing a value and storage version when found.
+     */
+    abstract read<T extends object = Record<string, unknown>>(keys: string[]): Promise<StorageReadResults<T>>;
+    /**
+     * Writes values with optional create, replace, or version conditions.
+     *
+     * @param changes Values indexed by their storage keys.
+     * @param options Conditions applied to every value in the batch.
+     * @returns One result for every supplied key.
+     */
+    abstract write<T extends object = Record<string, unknown>>(changes: Record<string, T>, options?: StorageWriteOptions): Promise<StorageWriteResults>;
+    /**
+     * Deletes values with an optional version condition.
+     *
+     * @param keys The keys to delete. An empty array is valid.
+     * @param options Conditions applied to every key in the batch.
+     * @returns One result for every supplied key.
+     */
+    abstract delete(keys: string[], options?: StorageDeleteOptions): Promise<StorageDeleteResults>;
+}
+/** A storage implementation supported by public hosting interfaces. */
+export type StorageProvider = Storage | StorageV2;

package/dist/src/storage/storage.js

@@ -4,4 +4,29 @@
  * Licensed under the MIT License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageV2 = exports.StorageWriteMode = exports.StorageOperationStatus = void 0;
+/** The outcome of one version 2 storage operation. */
+var StorageOperationStatus;
+(function (StorageOperationStatus) {
+    StorageOperationStatus["Succeeded"] = "succeeded";
+    StorageOperationStatus["NotFound"] = "notFound";
+    StorageOperationStatus["Conflict"] = "conflict";
+    StorageOperationStatus["ConditionNotMet"] = "conditionNotMet";
+})(StorageOperationStatus || (exports.StorageOperationStatus = StorageOperationStatus = {}));
+/** The write mode for a version 2 storage operation. */
+var StorageWriteMode;
+(function (StorageWriteMode) {
+    StorageWriteMode["Upsert"] = "upsert";
+    StorageWriteMode["CreateOnly"] = "createOnly";
+    StorageWriteMode["Replace"] = "replace";
+})(StorageWriteMode || (exports.StorageWriteMode = StorageWriteMode = {}));
+/**
+ * The version 2 storage contract.
+ *
+ * This does not extend {@link Storage}: JavaScript cannot overload methods by
+ * return type at runtime. V2 providers are exposed as separately named classes.
+ */
+class StorageV2 {
+}
+exports.StorageV2 = StorageV2;
 //# sourceMappingURL=storage.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../../src/storage/storage.ts"],"names":[],"mappings":";AAAA;;;GAGG"}
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../../src/storage/storage.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AA+IH,sDAAsD;AACtD,IAAY,sBAKX;AALD,WAAY,sBAAsB;IAChC,iDAAuB,CAAA;IACvB,+CAAqB,CAAA;IACrB,+CAAqB,CAAA;IACrB,6DAAmC,CAAA;AACrC,CAAC,EALW,sBAAsB,aAAtB,sBAAsB,GAAtB,sBAAsB,QAKjC;AAED,wDAAwD;AACxD,IAAY,gBAIX;AAJD,WAAY,gBAAgB;IAC1B,qCAAiB,CAAA;IACjB,6CAAyB,CAAA;IACzB,uCAAmB,CAAA;AACrB,CAAC,EAJW,gBAAgB,aAAhB,gBAAgB,GAAhB,gBAAgB,QAI3B;AAoBD;;;;;GAKG;AACH;CA0BC"}

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

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { StorageDeleteResults, StorageProvider, StorageReadResults, StorageV2, StorageWriteResults } from './storage';
+/** Returns true when a storage implementation declares the V2 contract. */
+export declare function isStorageV2(storage: StorageProvider): storage is StorageV2;
+/** Converts a supported storage implementation to the V2 contract. */
+export declare function asStorageV2(storage: StorageProvider): StorageV2;
+/** Returns a successful V2 read value, maps not-found to undefined, and rejects invalid results. */
+export declare function getStorageReadValue<T extends object>(results: StorageReadResults<T> | null | undefined, key: string): T | undefined;
+/** Throws when a V2 write did not succeed for every requested key. */
+export declare function assertStorageWriteSucceeded(results: StorageWriteResults | null | undefined, keys: string[]): void;
+/** Throws the state-specific concurrency error when a state write does not succeed. */
+export declare function assertAgentStateWriteSucceeded(results: StorageWriteResults | null | undefined, key: string, name: string): void;
+/** Throws when a V2 delete did not complete with idempotent V1 semantics. */
+export declare function assertStorageDeleteSucceeded(results: StorageDeleteResults | null | undefined, keys: string[]): void;

package/dist/src/storage/storageCompatibility.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isStorageV2 = isStorageV2;
+exports.asStorageV2 = asStorageV2;
+exports.getStorageReadValue = getStorageReadValue;
+exports.assertStorageWriteSucceeded = assertStorageWriteSucceeded;
+exports.assertAgentStateWriteSucceeded = assertAgentStateWriteSucceeded;
+exports.assertStorageDeleteSucceeded = assertStorageDeleteSucceeded;
+const agents_activity_1 = require("@microsoft/agents-activity");
+const errorHelper_1 = require("../errorHelper");
+const storage_1 = require("./storage");
+/** Returns true when a storage implementation declares the V2 contract. */
+function isStorageV2(storage) {
+    return storage instanceof storage_1.StorageV2;
+}
+/** Converts a supported storage implementation to the V2 contract. */
+function asStorageV2(storage) {
+    return isStorageV2(storage) ? storage : new StorageToStorageV2Adapter(storage);
+}
+/** Returns a successful V2 read value, maps not-found to undefined, and rejects invalid results. */
+function getStorageReadValue(results, key) {
+    const result = results === null || results === void 0 ? void 0 : results[key];
+    if ((result === null || result === void 0 ? void 0 : result.status) === storage_1.StorageOperationStatus.NotFound)
+        return undefined;
+    if ((result === null || result === void 0 ? void 0 : result.status) === storage_1.StorageOperationStatus.Succeeded)
+        return result.value;
+    throwStorageResultError('read', key, result === null || result === void 0 ? void 0 : result.status);
+}
+/** Adapts the legacy storage contract to version 2 where its semantics allow it. */
+class StorageToStorageV2Adapter extends storage_1.StorageV2 {
+    constructor(storage) {
+        super();
+        this.storage = storage;
+    }
+    async read(keys) {
+        validateKeys(keys);
+        if (keys.length === 0)
+            return {};
+        const items = await this.storage.read(keys);
+        return Object.fromEntries(keys.map(key => {
+            const value = items[key];
+            return [key, Object.prototype.hasOwnProperty.call(items, key)
+                    ? { key, status: storage_1.StorageOperationStatus.Succeeded, value: value, version: value === null || value === void 0 ? void 0 : value.eTag }
+                    : { key, status: storage_1.StorageOperationStatus.NotFound }];
+        }));
+    }
+    async write(changes, options) {
+        validateChanges(changes);
+        if ((options === null || options === void 0 ? void 0 : options.mode) !== undefined && options.mode !== storage_1.StorageWriteMode.Upsert) {
+            throwUnsupportedOption('mode');
+        }
+        if ((options === null || options === void 0 ? void 0 : options.ttl) !== undefined) {
+            throwUnsupportedOption('ttl');
+        }
+        validateExpectedVersion(options === null || options === void 0 ? void 0 : options.expectedVersion);
+        if (Object.keys(changes).length === 0)
+            return {};
+        const legacyChanges = Object.fromEntries(Object.entries(changes).map(([key, value]) => [
+            key,
+            (options === null || options === void 0 ? void 0 : options.expectedVersion) === undefined
+                ? removeLegacyETag(value)
+                : { ...removeLegacyETag(value), eTag: options.expectedVersion },
+        ]));
+        await this.storage.write(legacyChanges);
+        return Object.fromEntries(Object.keys(changes).map(key => [key, { key, status: storage_1.StorageOperationStatus.Succeeded }]));
+    }
+    async delete(keys, options) {
+        validateDeleteKeys(keys);
+        validateExpectedVersion(options === null || options === void 0 ? void 0 : options.expectedVersion);
+        if ((options === null || options === void 0 ? void 0 : options.expectedVersion) !== undefined) {
+            throwUnsupportedOption('expectedVersion');
+        }
+        if (keys.length === 0)
+            return {};
+        await this.storage.delete(keys);
+        return Object.fromEntries(keys.map(key => [key, { key, status: storage_1.StorageOperationStatus.Succeeded }]));
+    }
+}
+function validateKeys(keys) {
+    if (!Array.isArray(keys)) {
+        throw agents_activity_1.ExceptionHelper.generateException(ReferenceError, errorHelper_1.Errors.StorageReadKeysRequired);
+    }
+    if (keys.some(key => typeof key !== 'string' || key.trim() === '')) {
+        throw agents_activity_1.ExceptionHelper.generateException(ReferenceError, errorHelper_1.Errors.StorageV2KeyRequired);
+    }
+}
+function validateDeleteKeys(keys) {
+    if (!Array.isArray(keys)) {
+        throw agents_activity_1.ExceptionHelper.generateException(ReferenceError, errorHelper_1.Errors.StorageDeleteKeysRequired);
+    }
+    if (keys.some(key => typeof key !== 'string' || key.trim() === '')) {
+        throw agents_activity_1.ExceptionHelper.generateException(ReferenceError, errorHelper_1.Errors.StorageV2KeyRequired);
+    }
+}
+function validateChanges(changes) {
+    if (changes === null || typeof changes !== 'object' || Array.isArray(changes)) {
+        throw agents_activity_1.ExceptionHelper.generateException(ReferenceError, errorHelper_1.Errors.StorageWriteChangesRequired);
+    }
+    if (Object.keys(changes).some(key => key.trim() === '')) {
+        throw agents_activity_1.ExceptionHelper.generateException(ReferenceError, errorHelper_1.Errors.StorageV2KeyRequired);
+    }
+}
+function removeLegacyETag(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return value;
+    const { eTag: _eTag, ...withoutETag } = value;
+    return withoutETag;
+}
+function validateExpectedVersion(expectedVersion) {
+    if (expectedVersion === '') {
+        throw agents_activity_1.ExceptionHelper.generateException(RangeError, errorHelper_1.Errors.StorageV2ExpectedVersionEmpty);
+    }
+}
+function throwUnsupportedOption(option) {
+    throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.StorageV2UnsupportedOption, undefined, { option });
+}
+/** Throws when a V2 write did not succeed for every requested key. */
+function assertStorageWriteSucceeded(results, keys) {
+    assertStorageResults('write', results, keys, new Set([storage_1.StorageOperationStatus.Succeeded]));
+}
+/** Throws the state-specific concurrency error when a state write does not succeed. */
+function assertAgentStateWriteSucceeded(results, key, name) {
+    var _a;
+    const status = (_a = results === null || results === void 0 ? void 0 : results[key]) === null || _a === void 0 ? void 0 : _a.status;
+    if (status !== storage_1.StorageOperationStatus.Succeeded) {
+        throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.AgentStateWriteConflict, undefined, {
+            name,
+            key,
+            status: status !== null && status !== void 0 ? status : 'missing',
+        });
+    }
+}
+/** Throws when a V2 delete did not complete with idempotent V1 semantics. */
+function assertStorageDeleteSucceeded(results, keys) {
+    assertStorageResults('delete', results, keys, new Set([storage_1.StorageOperationStatus.Succeeded, storage_1.StorageOperationStatus.NotFound]));
+}
+function assertStorageResults(operation, results, keys, acceptedStatuses) {
+    var _a;
+    for (const key of keys) {
+        const status = (_a = results === null || results === void 0 ? void 0 : results[key]) === null || _a === void 0 ? void 0 : _a.status;
+        if (status === undefined || !acceptedStatuses.has(status)) {
+            throwStorageResultError(operation, key, status);
+        }
+    }
+}
+function throwStorageResultError(operation, key, status) {
+    throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.StorageV2OperationFailed, undefined, {
+        operation,
+        key,
+        status: status !== null && status !== void 0 ? status : 'missing',
+    });
+}
+//# sourceMappingURL=storageCompatibility.js.map

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

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@microsoft/agents-hosting",
-  "version": "1.9.0-beta.18.g6b8111bba5",
+  "version": "1.9.0-beta.20.g0c48a31a21",
   "homepage": "https://github.com/microsoft/Agents-for-js",
   "repository": {
     "type": "git",
@@ -21,8 +21,8 @@
   "dependencies": {
     "@azure/core-auth": "1.10.1",
     "@azure/msal-node": "5.6.0",
-    "@microsoft/agents-activity": "1.9.0-beta.18.g6b8111bba5",
-    "@microsoft/agents-telemetry": "1.9.0-beta.18.g6b8111bba5",
+    "@microsoft/agents-activity": "1.9.0-beta.20.g0c48a31a21",
+    "@microsoft/agents-telemetry": "1.9.0-beta.20.g0c48a31a21",
     "jsonwebtoken": "9.0.3",
     "jwks-rsa": "4.0.1",
     "zod": "3.25.75"

package/src/app/agentApplication.ts

@@ -20,6 +20,7 @@ import { TranscriptLoggerMiddleware } from '../transcript'
 import { CloudAdapter } from '../cloudAdapter'
 import { Authorization, UserAuthorization, AuthorizationManager } from './auth'
 import { Proactive } from './proactive'
+import { AgentApplicationRateLimiter } from './rateLimit'
 import { JwtPayload } from 'jsonwebtoken'
 import { trace, debug, redactString } from '@microsoft/agents-telemetry'
 import { AgentApplicationTraceDefinitions } from '../observability'
@@ -104,6 +105,7 @@ export class AgentApplication<TState extends TurnState> {
   private readonly _proactive?: Proactive<TState>
   protected readonly _extensions: AgentExtension<TState>[] = []
   private readonly _adaptiveCards: AdaptiveCardsActions<TState>
+  private readonly _rateLimiter?: AgentApplicationRateLimiter
 
   /**
    * Creates a new instance of AgentApplication.
@@ -141,6 +143,7 @@ export class AgentApplication<TState extends TurnState> {
       longRunningMessages: options?.longRunningMessages !== undefined ? options.longRunningMessages : false,
       removeRecipientMention: options?.removeRecipientMention !== undefined ? options.removeRecipientMention : true,
       transcriptLogger: options?.transcriptLogger || undefined,
+      rateLimit: options?.rateLimit || undefined,
     }
 
     this._adaptiveCards = new AdaptiveCardsActions<TState>(this)
@@ -158,6 +161,10 @@ export class AgentApplication<TState extends TurnState> {
 
     this._adapter.setAgentName(this._options.agentName)
 
+    if (this._options.rateLimit && this._options.rateLimit.length > 0) {
+      this._rateLimiter = new AgentApplicationRateLimiter(this._options.rateLimit, this._options.storage)
+    }
+
     // Create Proactive whenever proactive options are explicitly configured or a storage
     // backend is available — no explicit `proactive` option is required.
     if (this._options.proactive !== undefined || this._options.storage !== undefined) {
@@ -206,6 +213,7 @@ export class AgentApplication<TState extends TurnState> {
       fileDownloaders: this._options.fileDownloaders ? 'configured' : undefined,
       turnStateFactory: options?.turnStateFactory ? 'custom' : 'default',
       adaptiveCardsOptions: this._options.adaptiveCardsOptions,
+      rateLimitRules: this._options.rateLimit?.length,
     })
   }
 
@@ -672,6 +680,14 @@ export class AgentApplication<TState extends TurnState> {
    * ```
    */
   public async runInternal (turnContext: TurnContext): Promise<boolean> {
+    if (this._rateLimiter) {
+      const rateLimitDecision = await this._rateLimiter.shouldAllowTurn(turnContext)
+      if (!rateLimitDecision.allowed) {
+        await this._rateLimiter.handleThrottledTurn(turnContext, rateLimitDecision.rule!, rateLimitDecision.result!)
+        return false
+      }
+    }
+
     const { authorized, context } = await this.handleAuthorization(turnContext)
 
     if (!authorized) {

package/src/app/agentApplicationBuilder.ts

@@ -3,11 +3,12 @@
  * Licensed under the MIT License.
  */
 
-import { Storage } from '../storage'
+import { StorageProvider } from '../storage'
 import { AgentApplication } from './agentApplication'
 import { AgentApplicationOptions } from './agentApplicationOptions'
 import { AuthorizationOptions } from './auth/types'
 import { ProactiveOptions } from './proactive'
+import { RateLimitRule } from './rateLimit'
 import { TurnState } from './turnState'
 import { TypingOptions } from './agentApplicationOptions'
 
@@ -31,7 +32,7 @@ export class AgentApplicationBuilder<TState extends TurnState = TurnState> {
    * @param storage The storage implementation to use
    * @returns This builder instance for chaining
    */
-  public withStorage (storage: Storage): this {
+  public withStorage (storage: StorageProvider): this {
     this._options.storage = storage
     return this
   }
@@ -86,6 +87,16 @@ export class AgentApplicationBuilder<TState extends TurnState = TurnState> {
     return this
   }
 
+  /**
+   * Configures rate limit rules for incoming turns.
+   * @param rules The rate limit rules to apply
+   * @returns This builder instance for chaining
+   */
+  public withRateLimit (rules: RateLimitRule[]): this {
+    this._options.rateLimit = rules
+    return this
+  }
+
   /**
    * Builds and returns a new AgentApplication instance configured with the provided options.
    * @returns A new AgentApplication instance

package/src/app/agentApplicationOptions.ts

@@ -4,7 +4,7 @@
  */
 
 import { CloudAdapter } from '../cloudAdapter'
-import { Storage } from '../storage'
+import { StorageProvider } from '../storage'
 import { TranscriptLogger } from '../transcript'
 import { AdaptiveCardsOptions } from './adaptiveCards'
 import { InputFileDownloader } from './inputFileDownloader'
@@ -13,6 +13,7 @@ import { HeaderPropagationDefinition } from '../headerPropagation'
 import { AuthorizationOptions } from './auth/types'
 import { Connections } from '../auth/connections'
 import { ProactiveOptions } from './proactive'
+import { RateLimitRule } from './rateLimit'
 import { ConfigurationContext } from '../configuration/configuration'
 
 /**
@@ -79,12 +80,12 @@ export interface AgentApplicationOptions<TState extends TurnState> {
 
   /**
    * The storage mechanism for persisting conversation and user state across turns.
-   * This can be any implementation of the Storage interface, such as memory storage
-   * for development or blob storage for production scenarios.
+   * This can be a legacy Storage implementation, a StorageV2 implementation,
+   * or a built-in storage provider.
    *
    * @default undefined (no persistence)
    */
-  storage?: Storage;
+  storage?: StorageProvider;
 
   /**
    * Whether to start a typing indicator timer when the bot begins processing a message.
@@ -208,4 +209,10 @@ export interface AgentApplicationOptions<TState extends TurnState> {
    * When provided, `app.proactive` will be available.
    */
   proactive?: ProactiveOptions
+
+  /**
+   * Optional. Rate limit rules for incoming turns.
+   * When omitted or empty, no rate limiting is applied.
+   */
+  rateLimit?: RateLimitRule[]
 }

package/src/app/auth/handlerStorage.ts

@@ -5,10 +5,19 @@
 
 import { ActiveAuthorizationHandler } from './types'
 import { TurnContext } from '../../turnContext'
-import { Storage } from '../../storage'
+import { StorageProvider, StorageV2 } from '../../storage'
+import {
+  asStorageV2,
+  assertStorageDeleteSucceeded,
+  assertStorageWriteSucceeded,
+  getStorageReadValue,
+} from '../../storage/storageCompatibility'
 import { ExceptionHelper } from '@microsoft/agents-activity'
 import { Errors } from '../../errorHelper'
 
+// Version metadata only bridges reads and writes in one turn. Cloned contexts share turnState.
+const HANDLER_STORAGE_VERSIONS = Symbol('handlerStorageVersions')
+
 /**
  * Storage manager for handler state.
  */
@@ -18,7 +27,11 @@ export class HandlerStorage<TActiveHandler extends ActiveAuthorizationHandler =
    * @param storage The storage provider.
    * @param context The turn context.
    */
-  constructor (private storage: Storage, private context: TurnContext) { }
+  private readonly storage: StorageV2
+
+  constructor (storage: StorageProvider, private context: TurnContext) {
+    this.storage = asStorageV2(storage)
+  }
 
   /**
    * Gets the unique key for a handler session.
@@ -36,15 +49,23 @@ export class HandlerStorage<TActiveHandler extends ActiveAuthorizationHandler =
    * Reads the active handler state from storage.
    */
   public async read (): Promise<TActiveHandler | undefined> {
-    const ongoing = await this.storage.read([this.key])
-    return ongoing?.[this.key]
+    const ongoing = await this.storage.read<TActiveHandler>([this.key])
+    const value = getStorageReadValue(ongoing, this.key)
+    this.version = ongoing[this.key]?.version
+    return value
   }
 
   /**
    * Writes handler state to storage.
    */
-  public write (data: TActiveHandler) : Promise<void> {
-    return this.storage.write({ [this.key]: data })
+  public async write (data: TActiveHandler) : Promise<void> {
+    const { eTag: _eTag, ...value } = data
+    const results = await this.storage.write(
+      { [this.key]: value },
+      this.version === undefined ? undefined : { expectedVersion: this.version }
+    )
+    assertStorageWriteSucceeded(results, [this.key])
+    this.version = results[this.key]?.version
   }
 
   /**
@@ -52,7 +73,9 @@ export class HandlerStorage<TActiveHandler extends ActiveAuthorizationHandler =
    */
   public async delete (): Promise<void> {
     try {
-      await this.storage.delete([this.key])
+      const results = await this.storage.delete([this.key])
+      assertStorageDeleteSucceeded(results, [this.key])
+      this.version = undefined
     } catch (error) {
       if (error instanceof Error && 'code' in error && error.code === 404) {
         return
@@ -60,4 +83,25 @@ export class HandlerStorage<TActiveHandler extends ActiveAuthorizationHandler =
       throw error
     }
   }
+
+  private get version (): string | undefined {
+    return this.context.turnState.get<Map<string, string>>(HANDLER_STORAGE_VERSIONS)?.get(this.key)
+  }
+
+  private set version (value: string | undefined) {
+    let versions = this.context.turnState.get<Map<string, string>>(HANDLER_STORAGE_VERSIONS)
+    if (value === undefined) {
+      versions?.delete(this.key)
+      if (versions?.size === 0) {
+        this.context.turnState.delete(HANDLER_STORAGE_VERSIONS)
+      }
+      return
+    }
+
+    if (!versions) {
+      versions = new Map<string, string>()
+      this.context.turnState.set(HANDLER_STORAGE_VERSIONS, versions)
+    }
+    versions.set(this.key, value)
+  }
 }

package/src/app/auth/types.ts

@@ -4,7 +4,7 @@
  */
 
 import { Activity } from '@microsoft/agents-activity'
-import { Storage, StoreItem } from '../../storage'
+import { StorageProvider, StoreItem } from '../../storage'
 import { TurnContext } from '../../turnContext'
 import { AgenticAuthorizationOptions, AzureBotAuthorizationOptions } from './handlers'
 import { TokenResponse } from '../../oauth'
@@ -97,7 +97,7 @@ export interface AuthorizationHandlerSettings {
   /**
    * Storage instance for persisting handler state.
    */
-  storage: Storage
+  storage: StorageProvider
   /**
    * Connections instance for managing authentication connections.
    */

package/src/app/index.ts

@@ -28,3 +28,10 @@ export * from './streaming/streamingResponse'
 export * from './streaming/citation'
 export * from './teamsAttachmentDownloader'
 export * from './proactive'
+export type {
+  RateLimitMessageFactory,
+  RateLimitResult,
+  RateLimitRule,
+  RateLimitScope,
+  RateLimitStorageErrorBehavior
+} from './rateLimit'