@microsoft/agents-hosting 1.9.0-beta.8.gf58e66b2ee → 1.9.1

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'

package/src/app/proactive/proactive.ts

@@ -7,7 +7,13 @@ import type { BaseAdapter } from '../../baseAdapter'
 import type { TurnContext } from '../../turnContext'
 import type { TurnState } from '../turnState'
 import type { RouteHandler } from '../routeHandler'
-import type { Storage } from '../../storage/storage'
+import type { StorageV2 } from '../../storage/storage'
+import {
+  asStorageV2,
+  assertStorageDeleteSucceeded,
+  assertStorageWriteSucceeded,
+  getStorageReadValue,
+} from '../../storage/storageCompatibility'
 import type { AgentApplication } from '../agentApplication'
 import type { ProactiveOptions } from './proactiveOptions'
 import type { CreateConversationOptions } from './createConversationOptions'
@@ -41,31 +47,31 @@ export class Proactive<TState extends TurnState> {
 
   private readonly _app: AgentApplication<TState>
   private readonly _options: ProactiveOptions
-  private readonly _storage?: Storage
+  private readonly _storage?: StorageV2
 
   constructor (app: AgentApplication<TState>, options: ProactiveOptions) {
     this._app = app
     this._options = options
-    this._storage = options.storage
+    this._storage = options.storage ? asStorageV2(options.storage) : undefined
   }
 
   private _storageKey (conversationId: string): string {
     return `${STORAGE_KEY_PREFIX}${conversationId}`
   }
 
-  private requireStorage (): Storage {
+  private requireStorage (): StorageV2 {
     if (!this._storage) {
       throw ExceptionHelper.generateException(Error, Errors.ProactiveStorageRequired)
     }
     return this._storage
   }
 
-  private requireAppStorage (): Storage {
+  private requireAppStorage (): StorageV2 {
     const storage = this._app.options.storage
     if (!storage) {
       throw ExceptionHelper.generateException(Error, Errors.ProactiveAppStorageRequired)
     }
-    return storage
+    return asStorageV2(storage)
   }
 
   // ---------------------------------------------------------------------------
@@ -120,7 +126,8 @@ export class Proactive<TState extends TurnState> {
       const key = this._storageKey(id)
       record({ conversationId: id })
       const linkedItem = await actions.link(storage, key)
-      await storage.write({ [key]: { ...linkedItem, reference: conv.reference, claims: conv.claims } })
+      const results = await storage.write({ [key]: { ...linkedItem, reference: conv.reference, claims: conv.claims } })
+      assertStorageWriteSucceeded(results, [key])
       return id
     })
   }
@@ -142,7 +149,8 @@ export class Proactive<TState extends TurnState> {
     return trace(ProactiveTraceDefinitions.getConversation, async ({ record }) => {
       record({ conversationId })
       const storageKey = this._storageKey(conversationId)
-      const stored = (await this.requireStorage().read([storageKey]))?.[storageKey]
+      const results = await this.requireStorage().read<Conversation>([storageKey])
+      const stored = getStorageReadValue(results, storageKey)
       if (!stored) {
         record({ found: false })
         return undefined
@@ -193,7 +201,9 @@ export class Proactive<TState extends TurnState> {
   async deleteConversation (conversationId: string): Promise<void> {
     return trace(ProactiveTraceDefinitions.deleteConversation, async ({ record }) => {
       record({ conversationId })
-      await this.requireStorage().delete([this._storageKey(conversationId)])
+      const key = this._storageKey(conversationId)
+      const results = await this.requireStorage().delete([key])
+      assertStorageDeleteSucceeded(results, [key])
     })
   }
 

package/src/app/proactive/proactiveOptions.ts

@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-import type { Storage } from '../../storage/storage'
+import type { StorageProvider } from '../../storage/storage'
 
 /**
  * Configuration for the proactive messaging subsystem.
@@ -14,7 +14,7 @@ export interface ProactiveOptions {
    * A warning is logged when the fallback is used.
    * Throws at initialization time if neither is configured.
    */
-  storage?: Storage
+  storage?: StorageProvider
 
   /**
    * When `true` (default), `continueConversation()` throws if any requested