@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
@@ -0,0 +1,185 @@
1
+ /**
2
+ * Copyright (c) Microsoft Corporation. All rights reserved.
3
+ * Licensed under the MIT License.
4
+ */
5
+
6
+ import { ExceptionHelper } from '@microsoft/agents-activity'
7
+ import { Errors } from '../errorHelper'
8
+ import {
9
+ Storage,
10
+ StorageDeleteOptions,
11
+ StorageDeleteResults,
12
+ StorageOperationStatus,
13
+ StorageProvider,
14
+ StorageReadResults,
15
+ StorageV2,
16
+ StorageWriteMode,
17
+ StorageWriteOptions,
18
+ StorageWriteResults,
19
+ } from './storage'
20
+
21
+ /** Returns true when a storage implementation declares the V2 contract. */
22
+ export function isStorageV2 (storage: StorageProvider): storage is StorageV2 {
23
+ return storage instanceof StorageV2
24
+ }
25
+
26
+ /** Converts a supported storage implementation to the V2 contract. */
27
+ export function asStorageV2 (storage: StorageProvider): StorageV2 {
28
+ return isStorageV2(storage) ? storage : new StorageToStorageV2Adapter(storage)
29
+ }
30
+
31
+ /** Returns a successful V2 read value, maps not-found to undefined, and rejects invalid results. */
32
+ export function getStorageReadValue<T extends object> (results: StorageReadResults<T> | null | undefined, key: string): T | undefined {
33
+ const result = results?.[key]
34
+ if (result?.status === StorageOperationStatus.NotFound) return undefined
35
+ if (result?.status === StorageOperationStatus.Succeeded) return result.value
36
+ throwStorageResultError('read', key, result?.status)
37
+ }
38
+
39
+ /** Adapts the legacy storage contract to version 2 where its semantics allow it. */
40
+ class StorageToStorageV2Adapter extends StorageV2 {
41
+ constructor (private readonly storage: Storage) {
42
+ super()
43
+ }
44
+
45
+ async read<T extends object = Record<string, unknown>> (keys: string[]): Promise<StorageReadResults<T>> {
46
+ validateKeys(keys)
47
+ if (keys.length === 0) return {}
48
+
49
+ const items = await this.storage.read(keys)
50
+ return Object.fromEntries(keys.map(key => {
51
+ const value = items[key]
52
+ return [key, Object.prototype.hasOwnProperty.call(items, key)
53
+ ? { key, status: StorageOperationStatus.Succeeded, value: value as T, version: value?.eTag as string | undefined }
54
+ : { key, status: StorageOperationStatus.NotFound }]
55
+ }))
56
+ }
57
+
58
+ async write<T extends object = Record<string, unknown>> (changes: Record<string, T>, options?: StorageWriteOptions): Promise<StorageWriteResults> {
59
+ validateChanges(changes)
60
+ if (options?.mode !== undefined && options.mode !== StorageWriteMode.Upsert) {
61
+ throwUnsupportedOption('mode')
62
+ }
63
+ if (options?.ttl !== undefined) {
64
+ throwUnsupportedOption('ttl')
65
+ }
66
+ validateExpectedVersion(options?.expectedVersion)
67
+ if (Object.keys(changes).length === 0) return {}
68
+ const legacyChanges = Object.fromEntries(Object.entries(changes).map(([key, value]) => [
69
+ key,
70
+ options?.expectedVersion === undefined
71
+ ? removeLegacyETag(value)
72
+ : { ...removeLegacyETag(value), eTag: options.expectedVersion },
73
+ ]))
74
+ await this.storage.write(legacyChanges)
75
+ return Object.fromEntries(Object.keys(changes).map(key => [key, { key, status: StorageOperationStatus.Succeeded }]))
76
+ }
77
+
78
+ async delete (keys: string[], options?: StorageDeleteOptions): Promise<StorageDeleteResults> {
79
+ validateDeleteKeys(keys)
80
+ validateExpectedVersion(options?.expectedVersion)
81
+ if (options?.expectedVersion !== undefined) {
82
+ throwUnsupportedOption('expectedVersion')
83
+ }
84
+ if (keys.length === 0) return {}
85
+
86
+ await this.storage.delete(keys)
87
+ return Object.fromEntries(keys.map(key => [key, { key, status: StorageOperationStatus.Succeeded }]))
88
+ }
89
+ }
90
+
91
+ function validateKeys (keys: string[]): void {
92
+ if (!Array.isArray(keys)) {
93
+ throw ExceptionHelper.generateException(ReferenceError, Errors.StorageReadKeysRequired)
94
+ }
95
+ if (keys.some(key => typeof key !== 'string' || key.trim() === '')) {
96
+ throw ExceptionHelper.generateException(ReferenceError, Errors.StorageV2KeyRequired)
97
+ }
98
+ }
99
+
100
+ function validateDeleteKeys (keys: string[]): void {
101
+ if (!Array.isArray(keys)) {
102
+ throw ExceptionHelper.generateException(ReferenceError, Errors.StorageDeleteKeysRequired)
103
+ }
104
+ if (keys.some(key => typeof key !== 'string' || key.trim() === '')) {
105
+ throw ExceptionHelper.generateException(ReferenceError, Errors.StorageV2KeyRequired)
106
+ }
107
+ }
108
+
109
+ function validateChanges (changes: Record<string, unknown>): void {
110
+ if (changes === null || typeof changes !== 'object' || Array.isArray(changes)) {
111
+ throw ExceptionHelper.generateException(ReferenceError, Errors.StorageWriteChangesRequired)
112
+ }
113
+ if (Object.keys(changes).some(key => key.trim() === '')) {
114
+ throw ExceptionHelper.generateException(ReferenceError, Errors.StorageV2KeyRequired)
115
+ }
116
+ }
117
+
118
+ function removeLegacyETag<T> (value: T): T {
119
+ if (value === null || typeof value !== 'object' || Array.isArray(value)) return value
120
+ const { eTag: _eTag, ...withoutETag } = value as Record<string, unknown>
121
+ return withoutETag as T
122
+ }
123
+
124
+ function validateExpectedVersion (expectedVersion: string | undefined): void {
125
+ if (expectedVersion === '') {
126
+ throw ExceptionHelper.generateException(RangeError, Errors.StorageV2ExpectedVersionEmpty)
127
+ }
128
+ }
129
+
130
+ function throwUnsupportedOption (option: string): never {
131
+ throw ExceptionHelper.generateException(Error, Errors.StorageV2UnsupportedOption, undefined, { option })
132
+ }
133
+
134
+ /** Throws when a V2 write did not succeed for every requested key. */
135
+ export function assertStorageWriteSucceeded (results: StorageWriteResults | null | undefined, keys: string[]): void {
136
+ assertStorageResults('write', results, keys, new Set([StorageOperationStatus.Succeeded]))
137
+ }
138
+
139
+ /** Throws the state-specific concurrency error when a state write does not succeed. */
140
+ export function assertAgentStateWriteSucceeded (
141
+ results: StorageWriteResults | null | undefined,
142
+ key: string,
143
+ name: string
144
+ ): void {
145
+ const status = results?.[key]?.status
146
+ if (status !== StorageOperationStatus.Succeeded) {
147
+ throw ExceptionHelper.generateException(Error, Errors.AgentStateWriteConflict, undefined, {
148
+ name,
149
+ key,
150
+ status: status ?? 'missing',
151
+ })
152
+ }
153
+ }
154
+
155
+ /** Throws when a V2 delete did not complete with idempotent V1 semantics. */
156
+ export function assertStorageDeleteSucceeded (results: StorageDeleteResults | null | undefined, keys: string[]): void {
157
+ assertStorageResults(
158
+ 'delete',
159
+ results,
160
+ keys,
161
+ new Set([StorageOperationStatus.Succeeded, StorageOperationStatus.NotFound])
162
+ )
163
+ }
164
+
165
+ function assertStorageResults (
166
+ operation: 'write' | 'delete',
167
+ results: StorageWriteResults | StorageDeleteResults | null | undefined,
168
+ keys: string[],
169
+ acceptedStatuses: ReadonlySet<StorageOperationStatus>
170
+ ): void {
171
+ for (const key of keys) {
172
+ const status = results?.[key]?.status
173
+ if (status === undefined || !acceptedStatuses.has(status)) {
174
+ throwStorageResultError(operation, key, status)
175
+ }
176
+ }
177
+ }
178
+
179
+ function throwStorageResultError (operation: 'read' | 'write' | 'delete', key: string, status?: StorageOperationStatus): never {
180
+ throw ExceptionHelper.generateException(Error, Errors.StorageV2OperationFailed, undefined, {
181
+ operation,
182
+ key,
183
+ status: status ?? 'missing',
184
+ })
185
+ }