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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/README.md +18 -10
  2. package/dist/package.json +3 -3
  3. package/dist/src/app/agentApplication.d.ts +1 -0
  4. package/dist/src/app/agentApplication.js +18 -5
  5. package/dist/src/app/agentApplication.js.map +1 -1
  6. package/dist/src/app/agentApplicationBuilder.d.ts +9 -2
  7. package/dist/src/app/agentApplicationBuilder.js +9 -0
  8. package/dist/src/app/agentApplicationBuilder.js.map +1 -1
  9. package/dist/src/app/agentApplicationOptions.d.ts +10 -4
  10. package/dist/src/app/auth/handlerStorage.d.ts +5 -3
  11. package/dist/src/app/auth/handlerStorage.js +36 -10
  12. package/dist/src/app/auth/handlerStorage.js.map +1 -1
  13. package/dist/src/app/auth/types.d.ts +2 -2
  14. package/dist/src/app/index.d.ts +1 -0
  15. package/dist/src/app/proactive/proactive.js +10 -6
  16. package/dist/src/app/proactive/proactive.js.map +1 -1
  17. package/dist/src/app/proactive/proactiveOptions.d.ts +2 -2
  18. package/dist/src/app/rateLimit.d.ts +315 -0
  19. package/dist/src/app/rateLimit.js +333 -0
  20. package/dist/src/app/rateLimit.js.map +1 -0
  21. package/dist/src/app/turnState.d.ts +6 -3
  22. package/dist/src/app/turnState.js +43 -4
  23. package/dist/src/app/turnState.js.map +1 -1
  24. package/dist/src/errorHelper.js +40 -9
  25. package/dist/src/errorHelper.js.map +1 -1
  26. package/dist/src/observability/traces.d.ts +6 -4
  27. package/dist/src/observability/traces.js +10 -9
  28. package/dist/src/observability/traces.js.map +1 -1
  29. package/dist/src/state/agentState.d.ts +8 -3
  30. package/dist/src/state/agentState.js +26 -8
  31. package/dist/src/state/agentState.js.map +1 -1
  32. package/dist/src/state/conversationState.d.ts +2 -2
  33. package/dist/src/state/conversationState.js.map +1 -1
  34. package/dist/src/state/userState.d.ts +2 -2
  35. package/dist/src/state/userState.js.map +1 -1
  36. package/dist/src/statusCodes.d.ts +5 -0
  37. package/dist/src/statusCodes.js +5 -0
  38. package/dist/src/statusCodes.js.map +1 -1
  39. package/dist/src/storage/fileStorage.d.ts +83 -71
  40. package/dist/src/storage/fileStorage.js +272 -136
  41. package/dist/src/storage/fileStorage.js.map +1 -1
  42. package/dist/src/storage/memoryStorage.d.ts +85 -62
  43. package/dist/src/storage/memoryStorage.js +240 -109
  44. package/dist/src/storage/memoryStorage.js.map +1 -1
  45. package/dist/src/storage/storage.d.ts +101 -16
  46. package/dist/src/storage/storage.js +25 -0
  47. package/dist/src/storage/storage.js.map +1 -1
  48. package/dist/src/storage/storageCompatibility.d.ts +17 -0
  49. package/dist/src/storage/storageCompatibility.js +157 -0
  50. package/dist/src/storage/storageCompatibility.js.map +1 -0
  51. package/package.json +3 -3
  52. package/src/app/agentApplication.ts +16 -0
  53. package/src/app/agentApplicationBuilder.ts +13 -2
  54. package/src/app/agentApplicationOptions.ts +11 -4
  55. package/src/app/auth/handlerStorage.ts +51 -7
  56. package/src/app/auth/types.ts +2 -2
  57. package/src/app/index.ts +7 -0
  58. package/src/app/proactive/proactive.ts +19 -9
  59. package/src/app/proactive/proactiveOptions.ts +2 -2
  60. package/src/app/rateLimit.ts +659 -0
  61. package/src/app/turnState.ts +50 -7
  62. package/src/errorHelper.ts +46 -8
  63. package/src/observability/traces.ts +8 -7
  64. package/src/state/agentState.ts +39 -13
  65. package/src/state/conversationState.ts +2 -2
  66. package/src/state/userState.ts +2 -2
  67. package/src/statusCodes.ts +6 -0
  68. package/src/storage/fileStorage.ts +289 -134
  69. package/src/storage/memoryStorage.ts +266 -109
  70. package/src/storage/storage.ts +115 -17
  71. package/src/storage/storageCompatibility.ts +185 -0
@@ -3,7 +3,14 @@
3
3
  * Licensed under the MIT License.
4
4
  */
5
5
 
6
- import { Storage, StoreItems } from '../storage'
6
+ import { StorageOperationStatus, StorageProvider, StorageReadResults, StorageWriteMode, StoreItems } from '../storage'
7
+ import {
8
+ asStorageV2,
9
+ assertAgentStateWriteSucceeded,
10
+ assertStorageDeleteSucceeded,
11
+ getStorageReadValue,
12
+ isStorageV2,
13
+ } from '../storage/storageCompatibility'
7
14
  import { AppMemory } from './appMemory'
8
15
  import { TurnStateEntry } from './turnStateEntry'
9
16
  import { TurnContext } from '../turnContext'
@@ -73,6 +80,8 @@ export class TurnState<
73
80
  TUserState = DefaultUserState
74
81
  > implements AppMemory {
75
82
  private _scopes: Record<string, TurnStateEntry> = {}
83
+ private _versions: Record<string, string | undefined> = {}
84
+ private _missingStorageKeys = new Set<string>()
76
85
  private _isLoaded = false
77
86
  private _loadingPromise?: Promise<boolean>
78
87
 
@@ -256,7 +265,7 @@ export class TurnState<
256
265
  * @param force - If true, forces a reload from storage even if state is already loaded
257
266
  * @returns Promise that resolves to true if state was loaded, false if it was already loaded
258
267
  */
259
- public load (context: TurnContext, storage?: Storage, force: boolean = false): Promise<boolean> {
268
+ public load (context: TurnContext, storage?: StorageProvider, force: boolean = false): Promise<boolean> {
260
269
  if (this._isLoaded && !force) {
261
270
  return Promise.resolve(false)
262
271
  }
@@ -274,13 +283,21 @@ export class TurnState<
274
283
  }
275
284
  }
276
285
 
277
- const items = storage ? await storage.read(keys) : {}
286
+ const items: StorageReadResults<Record<string, unknown>> | undefined = storage
287
+ ? await asStorageV2(storage).read<Record<string, unknown>>(keys)
288
+ : undefined
278
289
 
279
290
  for (const key in scopes) {
280
291
  if (Object.prototype.hasOwnProperty.call(scopes, key)) {
281
292
  const storageKey = scopes[key]
282
- const value = items[storageKey]
293
+ const value = storage ? getStorageReadValue(items, storageKey) : undefined
283
294
  this._scopes[key] = new TurnStateEntry(value, storageKey)
295
+ this._versions[storageKey] = items?.[storageKey]?.version
296
+ if (items?.[storageKey]?.status === StorageOperationStatus.NotFound) {
297
+ this._missingStorageKeys.add(storageKey)
298
+ } else {
299
+ this._missingStorageKeys.delete(storageKey)
300
+ }
284
301
  }
285
302
  }
286
303
 
@@ -311,7 +328,7 @@ export class TurnState<
311
328
  * @remarks
312
329
  * Only changed scopes will be persisted.
313
330
  */
314
- public async save (context: TurnContext, storage?: Storage): Promise<void> {
331
+ public async save (context: TurnContext, storage?: StorageProvider): Promise<void> {
315
332
  if (!this._isLoaded && this._loadingPromise) {
316
333
  await this._loadingPromise
317
334
  }
@@ -346,12 +363,34 @@ export class TurnState<
346
363
 
347
364
  if (storage) {
348
365
  const promises: Promise<void>[] = []
366
+ const storageV2 = asStorageV2(storage)
349
367
  if (changes) {
350
- promises.push(storage.write(changes))
368
+ for (const [key, value] of Object.entries(changes)) {
369
+ const expectedVersion = this._versions[key]
370
+ const options = expectedVersion !== undefined
371
+ ? { expectedVersion }
372
+ : isStorageV2(storage) && this._missingStorageKeys.has(key)
373
+ ? { mode: StorageWriteMode.CreateOnly }
374
+ : undefined
375
+ promises.push(storageV2.write(
376
+ { [key]: value },
377
+ options
378
+ ).then(results => {
379
+ assertAgentStateWriteSucceeded(results, key, this.getStorageScopeName(key))
380
+ this._versions[key] = results?.[key]?.version
381
+ this._missingStorageKeys.delete(key)
382
+ }))
383
+ }
351
384
  }
352
385
 
353
386
  if (deletions) {
354
- promises.push(storage.delete(deletions))
387
+ promises.push(storageV2.delete(deletions).then(results => {
388
+ assertStorageDeleteSucceeded(results, deletions)
389
+ for (const key of deletions) {
390
+ delete this._versions[key]
391
+ this._missingStorageKeys.delete(key)
392
+ }
393
+ }))
355
394
  }
356
395
 
357
396
  if (promises.length > 0) {
@@ -360,6 +399,10 @@ export class TurnState<
360
399
  }
361
400
  }
362
401
 
402
+ private getStorageScopeName (storageKey: string): string {
403
+ return Object.entries(this._scopes).find(([, entry]) => entry.storageKey === storageKey)?.[0] ?? this.constructor.name
404
+ }
405
+
363
406
  /**
364
407
  * Computes the storage keys for each scope based on the turn context.
365
408
  *
@@ -798,22 +798,60 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
798
798
  description: 'Changes are required when writing.'
799
799
  },
800
800
 
801
- /**
802
- * Error thrown when a storage TTL value is invalid.
803
- */
804
- InvalidStorageTtl: {
801
+ /** Error thrown when a V2 storage key is empty or whitespace. */
802
+ StorageV2KeyRequired: {
805
803
  code: -120703,
806
- description: 'StorageWriteOptions.ttl must be a finite number greater than zero.'
804
+ description: 'Storage V2 keys must be non-empty strings.'
807
805
  },
808
806
 
809
- /**
810
- * Error thrown when storage option is not available in app options.
811
- */
807
+ /** Error thrown when the legacy storage adapter cannot honor a V2 option. */
808
+ StorageV2UnsupportedOption: {
809
+ code: -120704,
810
+ description: 'The legacy storage adapter does not support the V2 storage option "{option}".'
811
+ },
812
+
813
+ /** Error thrown when an empty V2 storage version token is provided. */
814
+ StorageV2ExpectedVersionEmpty: {
815
+ code: -120706,
816
+ description: 'Storage V2 expectedVersion cannot be empty.'
817
+ },
818
+
819
+ /** Error thrown when a V2 storage operation returns a failed or missing result. */
820
+ StorageV2OperationFailed: {
821
+ code: -120707,
822
+ description: 'Storage V2 {operation} failed for key "{key}" with status "{status}".'
823
+ },
824
+
825
+ /** Error thrown when a V2 value is not a non-array object. */
826
+ StorageV2ValueRequired: {
827
+ code: -120708,
828
+ description: 'Storage V2 values must be non-null, non-array objects.'
829
+ },
830
+
831
+ /** Error thrown when keys are required for storage delete operations. */
832
+ StorageDeleteKeysRequired: {
833
+ code: -120709,
834
+ description: 'Keys are required when deleting.'
835
+ },
836
+
837
+ /** Error thrown when storage option is not available in app options. */
812
838
  StorageOptionNotAvailable: {
813
839
  code: -120710,
814
840
  description: "The 'storage' option is not available in the app options. Ensure that the app is properly configured.",
815
841
  },
816
842
 
843
+ /** Error thrown when a V2 write mode is not supported. */
844
+ StorageV2WriteModeUnsupported: {
845
+ code: -120711,
846
+ description: 'Storage V2 write mode "{mode}" is not supported.'
847
+ },
848
+
849
+ /** Error thrown when another turn saved state after this turn loaded it. */
850
+ AgentStateWriteConflict: {
851
+ code: -120712,
852
+ description: "AgentState '{name}' could not save key '{key}' because another turn updated the state first (status: {status}). This turn's state changes were not saved."
853
+ },
854
+
817
855
  /**
818
856
  * Error thrown when state is not loaded.
819
857
  */
@@ -5,7 +5,8 @@ import { SpanNames, trace } from '@microsoft/agents-telemetry'
5
5
  import { HostingMetrics } from './metrics'
6
6
  import { Activity, ConversationReference } from '@microsoft/agents-activity'
7
7
  import { HandlerStorage } from '../app/auth/handlerStorage'
8
- import type { Storage } from '../storage'
8
+ import type { StorageProvider } from '../storage'
9
+ import { asStorageV2 } from '../storage/storageCompatibility'
9
10
 
10
11
  export const AgentApplicationTraceDefinitions = {
11
12
  run: trace.define({
@@ -279,8 +280,8 @@ export const ProactiveTraceDefinitions = {
279
280
  conversationId: '',
280
281
  },
281
282
  actions: ({ span }) => ({
282
- async link (storage: Storage, key: string) {
283
- const item = (await storage.read([key]))?.[key] ?? {}
283
+ async link (storage: StorageProvider, key: string) {
284
+ const item = ((await asStorageV2(storage).read([key]))?.[key]?.value ?? {}) as { __link?: unknown }
284
285
  return link(span, item)
285
286
  }
286
287
  }),
@@ -333,8 +334,8 @@ export const ProactiveTraceDefinitions = {
333
334
  activityType: '',
334
335
  },
335
336
  actions: ({ span }) => ({
336
- async link (storage: Storage, key: string) {
337
- const item = (await storage.read([key]))?.[key] ?? {}
337
+ async link (storage: StorageProvider, key: string) {
338
+ const item = ((await asStorageV2(storage).read([key]))?.[key]?.value ?? {}) as { __link?: unknown }
338
339
  link(span, item)
339
340
  }
340
341
  }),
@@ -367,8 +368,8 @@ export const ProactiveTraceDefinitions = {
367
368
  hasAutoSignIn: false,
368
369
  },
369
370
  actions: ({ span }) => ({
370
- async link (storage: Storage, key: string) {
371
- const item = (await storage.read([key]))?.[key] ?? {}
371
+ async link (storage: StorageProvider, key: string) {
372
+ const item = ((await asStorageV2(storage).read([key]))?.[key]?.value ?? {}) as { __link?: unknown }
372
373
  link(span, item)
373
374
  }
374
375
  }),
@@ -3,7 +3,14 @@
3
3
  * Licensed under the MIT License.
4
4
  */
5
5
 
6
- import { Storage, StorageKeyFactory, StoreItem } from '../storage/storage'
6
+ import { StorageKeyFactory, StorageOperationStatus, StorageProvider, StorageV2, StorageWriteMode, StoreItem } from '../storage/storage'
7
+ import {
8
+ asStorageV2,
9
+ assertAgentStateWriteSucceeded,
10
+ assertStorageDeleteSucceeded,
11
+ getStorageReadValue,
12
+ isStorageV2,
13
+ } from '../storage/storageCompatibility'
7
14
  import { TurnContext } from '../turnContext'
8
15
  import { createHash } from 'node:crypto'
9
16
  import { AgentStatePropertyAccessor } from './agentStatePropertyAccesor'
@@ -26,6 +33,10 @@ export interface CachedAgentState {
26
33
  * Hash of the state used to detect changes
27
34
  */
28
35
  hash: string;
36
+ /** Version returned when the state was loaded, used to reject stale V2 writes. */
37
+ version?: string;
38
+ /** Whether the state was not found when it was loaded. */
39
+ isNew?: boolean;
29
40
  }
30
41
 
31
42
  /**
@@ -62,13 +73,17 @@ export interface CustomKey {
62
73
  export class AgentState {
63
74
  private readonly stateKey = Symbol('state')
64
75
 
76
+ private get internalStorage (): StorageV2 {
77
+ return asStorageV2(this.storage)
78
+ }
79
+
65
80
  /**
66
81
  * Creates a new instance of AgentState.
67
82
  *
68
83
  * @param storage The storage provider used to persist state between turns
69
84
  * @param storageKey A factory function that generates keys for storing state data
70
85
  */
71
- constructor (protected storage: Storage, protected storageKey: StorageKeyFactory) { }
86
+ constructor (protected storage: StorageProvider, protected storageKey: StorageKeyFactory) {}
72
87
 
73
88
  /**
74
89
  * Creates a property accessor for the specified property.
@@ -101,11 +116,15 @@ export class AgentState {
101
116
  if (force || !cached || !cached.state) {
102
117
  const key: string = await this.getStorageOrCustomKey(customKey, context)
103
118
  logger.info(`Reading storage with key ${key}`)
104
- const storedItem = await this.storage.read([key])
105
-
106
- const state: any = storedItem[key] || {}
119
+ const storedItems = await this.internalStorage.read<Record<string, any>>([key])
120
+ const state: any = getStorageReadValue(storedItems, key) ?? {}
107
121
  const hash: string = this.calculateChangeHash(state)
108
- context.turnState.set(this.stateKey, { state, hash })
122
+ context.turnState.set(this.stateKey, {
123
+ state,
124
+ hash,
125
+ version: storedItems[key]?.version,
126
+ isNew: storedItems[key]?.status === StorageOperationStatus.NotFound,
127
+ })
109
128
 
110
129
  return state
111
130
  }
@@ -130,15 +149,21 @@ export class AgentState {
130
149
  if (!cached) {
131
150
  cached = { state: {}, hash: '' }
132
151
  }
133
- cached.state.eTag = '*'
134
- const changes: StoreItem = {} as StoreItem
135
-
136
152
  const key: string = await this.getStorageOrCustomKey(customKey, context)
137
153
 
138
- changes[key] = cached.state
139
-
140
154
  logger.info(`Writing storage with key ${key}`)
141
- await this.storage.write(changes)
155
+ const results = await this.internalStorage.write(
156
+ { [key]: cached.state },
157
+ cached.version !== undefined
158
+ ? { expectedVersion: cached.version }
159
+ : cached.isNew && isStorageV2(this.storage)
160
+ ? { mode: StorageWriteMode.CreateOnly }
161
+ : undefined
162
+ )
163
+ assertAgentStateWriteSucceeded(results, key, this.constructor.name)
164
+ const result = results[key]
165
+ cached.version = result.version
166
+ cached.isNew = false
142
167
  cached.hash = this.calculateChangeHash(cached.state)
143
168
  context.turnState.set(this.stateKey, cached)
144
169
  }
@@ -195,7 +220,8 @@ export class AgentState {
195
220
  }
196
221
  const key = await this.getStorageOrCustomKey(customKey, context)
197
222
  logger.info(`Deleting storage with key ${key}`)
198
- await this.storage.delete([key])
223
+ const results = await this.internalStorage.delete([key])
224
+ assertStorageDeleteSucceeded(results, [key])
199
225
  }
200
226
 
201
227
  /**
@@ -4,7 +4,7 @@
4
4
  */
5
5
 
6
6
  import { AgentState } from './agentState'
7
- import { Storage } from '../storage/storage'
7
+ import { StorageProvider } from '../storage/storage'
8
8
  import { TurnContext } from '../turnContext'
9
9
  import { Activity, ExceptionHelper } from '@microsoft/agents-activity'
10
10
  import { Errors } from '../errorHelper'
@@ -17,7 +17,7 @@ export class ConversationState extends AgentState {
17
17
  * Creates a new instance of ConversationState.
18
18
  * @param storage The storage provider.
19
19
  */
20
- constructor (storage: Storage, private readonly namespace: string = '') {
20
+ constructor (storage: StorageProvider, private readonly namespace: string = '') {
21
21
  super(storage, (context: TurnContext) => {
22
22
  const key: string = this.getStorageKey(context)
23
23
 
@@ -4,7 +4,7 @@
4
4
  */
5
5
 
6
6
  import { AgentState } from './agentState'
7
- import { Storage } from '../storage/storage'
7
+ import { StorageProvider } from '../storage/storage'
8
8
  import { TurnContext } from '../turnContext'
9
9
  import { Activity, ExceptionHelper } from '@microsoft/agents-activity'
10
10
  import { Errors } from '../errorHelper'
@@ -17,7 +17,7 @@ export class UserState extends AgentState {
17
17
  * Creates a new instance of UserState.
18
18
  * @param storage The storage provider.
19
19
  */
20
- constructor (storage: Storage, private readonly namespace: string = '') {
20
+ constructor (storage: StorageProvider, private readonly namespace: string = '') {
21
21
  super(storage, (context: TurnContext) => {
22
22
  const key: string = this.getStorageKey(context)
23
23
 
@@ -78,6 +78,12 @@ export enum StatusCodes {
78
78
  */
79
79
  UPGRADE_REQUIRED = 426,
80
80
 
81
+ /**
82
+ * The user has sent too many requests in a given amount of time.
83
+ * Used when rate limiting or throttling prevents a turn from being processed.
84
+ */
85
+ TOO_MANY_REQUESTS = 429,
86
+
81
87
  /**
82
88
  * The server encountered an unexpected condition that prevented it from fulfilling the request.
83
89
  * Generic error message when an unexpected agent hosting error occurs