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

package/src/errorHelper.ts

@@ -448,6 +448,14 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'MSAL returned an unparsable response body'
   },
 
+  /**
+   * Error thrown when a security-sensitive boolean configuration value is invalid.
+   */
+  InvalidBooleanConfigurationValue: {
+    code: -120394,
+    description: 'Configuration source "{sourceName}" returned an invalid boolean for "{path}". Expected one of true/false/1/0.'
+  },
+
   FailedToAcquireTokenUsingCertificate: {
     code: -120395,
     description: 'Failed to acquire token using certificate'
@@ -578,11 +586,11 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
   },
 
   /**
-     * Error thrown when authorization option is not available in app options.
+     * Error thrown when no authorization handlers were resolved.
      */
   AuthorizationOptionNotAvailable: {
     code: -120530,
-    description: 'The Application.authorization property is unavailable because no authorization options were configured.'
+    description: 'The Application.authorization property is unavailable because no authorization handlers were resolved.'
   },
 
   /**
@@ -790,14 +798,60 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'Changes are required when writing.'
   },
 
-  /**
-     * Error thrown when storage option is not available in app options.
-     */
+  /** Error thrown when a V2 storage key is empty or whitespace. */
+  StorageV2KeyRequired: {
+    code: -120703,
+    description: 'Storage V2 keys must be non-empty strings.'
+  },
+
+  /** Error thrown when the legacy storage adapter cannot honor a V2 option. */
+  StorageV2UnsupportedOption: {
+    code: -120704,
+    description: 'The legacy storage adapter does not support the V2 storage option "{option}".'
+  },
+
+  /** Error thrown when an empty V2 storage version token is provided. */
+  StorageV2ExpectedVersionEmpty: {
+    code: -120706,
+    description: 'Storage V2 expectedVersion cannot be empty.'
+  },
+
+  /** Error thrown when a V2 storage operation returns a failed or missing result. */
+  StorageV2OperationFailed: {
+    code: -120707,
+    description: 'Storage V2 {operation} failed for key "{key}" with status "{status}".'
+  },
+
+  /** Error thrown when a V2 value is not a non-array object. */
+  StorageV2ValueRequired: {
+    code: -120708,
+    description: 'Storage V2 values must be non-null, non-array objects.'
+  },
+
+  /** Error thrown when keys are required for storage delete operations. */
+  StorageDeleteKeysRequired: {
+    code: -120709,
+    description: 'Keys are required when deleting.'
+  },
+
+  /** Error thrown when storage option is not available in app options. */
   StorageOptionNotAvailable: {
     code: -120710,
     description: "The 'storage' option is not available in the app options. Ensure that the app is properly configured.",
   },
 
+  /** Error thrown when a V2 write mode is not supported. */
+  StorageV2WriteModeUnsupported: {
+    code: -120711,
+    description: 'Storage V2 write mode "{mode}" is not supported.'
+  },
+
+  /** Error thrown when another turn saved state after this turn loaded it. */
+  AgentStateWriteConflict: {
+    code: -120712,
+    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."
+  },
+
   /**
      * Error thrown when state is not loaded.
      */
@@ -1043,6 +1097,90 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'The Entra Agent ID sidecar returned an unsupported authorization scheme `{scheme}`. Only the Bearer scheme is supported'
   },
 
+  // ============================================================================
+  // Configuration Source Errors (-120812 to -120827)
+  // ============================================================================
+
+  ConfigurationAlreadyConsumed: {
+    code: -120812,
+    description: 'Configuration sources must be preloaded before the first configuration consumer is created.'
+  },
+
+  ConfigurationSourceNameRequired: {
+    code: -120813,
+    description: 'Configuration source name must be a non-empty string.'
+  },
+
+  DuplicateConfigurationSource: {
+    code: -120814,
+    description: 'Configuration source name `{sourceName}` is registered more than once.'
+  },
+
+  ConfigurationSourceLoadFailed: {
+    code: -120815,
+    description: 'Configuration source `{sourceName}` failed to load.'
+  },
+
+  InvalidConfigurationPath: {
+    code: -120816,
+    description: 'Configuration source `{sourceName}` returned unsupported canonical path `{path}`.'
+  },
+
+  InvalidConfigurationValue: {
+    code: -120817,
+    description: 'Configuration source `{sourceName}` returned an invalid value for canonical path `{path}`.'
+  },
+
+  ConfigurationPreloadInProgress: {
+    code: -120818,
+    description: 'Another configuration preload is already in progress.'
+  },
+
+  InvalidConnectionMapEntry: {
+    code: -120819,
+    description: 'Connection map entry at index {index} must define both serviceUrl and connection.'
+  },
+
+  ConfigurationAlreadyPreloaded: {
+    code: -120820,
+    description: 'Configuration sources have already been preloaded for this process.'
+  },
+
+  UnsupportedRuntimeConfigurationField: {
+    code: -120821,
+    description: 'Configuration source `{sourceName}` returned field `{path}`, which is not supported by the JavaScript SDK.'
+  },
+
+  InvalidConfigurationSourceResult: {
+    code: -120822,
+    description: 'Configuration source `{sourceName}` returned an invalid source result.'
+  },
+
+  InvalidConfigurationContext: {
+    code: -120823,
+    description: 'The configuration context is invalid. Create contexts with createConfigurationContext().'
+  },
+
+  InvalidConfigurationSourceMode: {
+    code: -120824,
+    description: 'Configuration source `{sourceName}` uses unsupported mode `{mode}`. Use `fallback`, `overrideEnvironment`, or `enforce`.'
+  },
+
+  JsonConfigurationFileReadFailed: {
+    code: -120825,
+    description: 'JSON configuration file `{filePath}` could not be read.'
+  },
+
+  InvalidJsonConfigurationFile: {
+    code: -120826,
+    description: 'JSON configuration file `{filePath}` does not contain valid JSON.'
+  },
+
+  JsonConfigurationDocumentRequired: {
+    code: -120827,
+    description: 'JSON configuration file `{filePath}` must contain an object at the document root.'
+  },
+
   // ============================================================================
   // Application Configuration Errors (-120850 to -120902)
   // ============================================================================

package/src/index.ts

@@ -8,6 +8,7 @@ export { authorizeJWT, buildJwksUri, clearJwksClients } from './auth/jwt-middlew
 
 export * from './app'
 export * from './cards'
+export * from './configuration'
 export * from './connector-client'
 export { Errors as HostingErrors } from './errorHelper'
 export * from './invoke'

package/src/observability/traces.ts

@@ -5,7 +5,8 @@ import { SpanNames, trace } from '@microsoft/agents-telemetry'
 import { HostingMetrics } from './metrics'
 import { Activity, ConversationReference } from '@microsoft/agents-activity'
 import { HandlerStorage } from '../app/auth/handlerStorage'
-import type { Storage } from '../storage'
+import type { StorageProvider } from '../storage'
+import { asStorageV2 } from '../storage/storageCompatibility'
 
 export const AgentApplicationTraceDefinitions = {
   run: trace.define({
@@ -279,8 +280,8 @@ export const ProactiveTraceDefinitions = {
       conversationId: '',
     },
     actions: ({ span }) => ({
-      async link (storage: Storage, key: string) {
-        const item = (await storage.read([key]))?.[key] ?? {}
+      async link (storage: StorageProvider, key: string) {
+        const item = ((await asStorageV2(storage).read([key]))?.[key]?.value ?? {}) as { __link?: unknown }
         return link(span, item)
       }
     }),
@@ -333,8 +334,8 @@ export const ProactiveTraceDefinitions = {
       activityType: '',
     },
     actions: ({ span }) => ({
-      async link (storage: Storage, key: string) {
-        const item = (await storage.read([key]))?.[key] ?? {}
+      async link (storage: StorageProvider, key: string) {
+        const item = ((await asStorageV2(storage).read([key]))?.[key]?.value ?? {}) as { __link?: unknown }
         link(span, item)
       }
     }),
@@ -367,8 +368,8 @@ export const ProactiveTraceDefinitions = {
       hasAutoSignIn: false,
     },
     actions: ({ span }) => ({
-      async link (storage: Storage, key: string) {
-        const item = (await storage.read([key]))?.[key] ?? {}
+      async link (storage: StorageProvider, key: string) {
+        const item = ((await asStorageV2(storage).read([key]))?.[key]?.value ?? {}) as { __link?: unknown }
         link(span, item)
       }
     }),

package/src/outboundHostValidator.ts

@@ -3,7 +3,12 @@
  * Licensed under the MIT License.
  */
 
-import { parseBooleanEnv } from './utils/env'
+import {
+  ConfigurationContext,
+  getConfigurationSnapshot
+} from './configuration/configuration'
+import { loadModernEnvironmentConfiguration } from './configuration/environmentConfiguration'
+import { mergeDefined } from './utils'
 
 /** Hosts used by Microsoft channel callbacks and hosted attachments. */
 const DEFAULT_MICROSOFT_HOSTS = Object.freeze([
@@ -17,11 +22,11 @@ const DEFAULT_MICROSOFT_HOSTS = Object.freeze([
   'blob.core.windows.net'
 ])
 
-const OUTBOUND_HOST_VALIDATOR_ENV_PREFIX = 'OutboundHostValidator__'
-const OUTBOUND_HOST_VALIDATOR_ENV_PREFIX_UPPER = OUTBOUND_HOST_VALIDATOR_ENV_PREFIX.toUpperCase()
-
 /** Configuration for the shared outbound-host allowlist. */
 export interface OutboundHostValidatorOptions {
+  /** Optional host-scoped external configuration. */
+  configurationContext?: ConfigurationContext
+
   /** Enables allowlist enforcement. Defaults to `false`. */
   enabled?: boolean
 
@@ -56,14 +61,17 @@ export class OutboundHostValidator implements OutboundUrlPolicy {
   private readonly suffixes: ReadonlySet<string>
 
   public constructor (options: OutboundHostValidatorOptions = {}) {
-    this.enabled = options.enabled ?? false
+    const resolved = options.configurationContext
+      ? resolveOutboundHostValidatorOptions(options)
+      : options
+    this.enabled = resolved.enabled ?? false
 
     const suffixes = new Set<string>()
-    if (options.includeDefaultMicrosoftHosts ?? true) {
+    if (resolved.includeDefaultMicrosoftHosts ?? true) {
       for (const host of DEFAULT_MICROSOFT_HOSTS) suffixes.add(host)
     }
 
-    for (const host of options.hosts ?? []) {
+    for (const host of resolved.hosts ?? []) {
       const normalized = normalizeConfiguredHost(host)
       if (normalized) suffixes.add(normalized)
     }
@@ -93,47 +101,32 @@ export class OutboundHostValidator implements OutboundUrlPolicy {
  * indexed values such as `Hosts__0`, `Hosts__1`, and so on.
  */
 export function loadOutboundHostValidatorOptionsFromEnv (): OutboundHostValidatorOptions {
-  const result: OutboundHostValidatorOptions = {}
-  const indexedHosts = new Map<number, string>()
-  const hosts: string[] = []
-
-  for (const [envKey, rawValue] of Object.entries(process.env)) {
-    const upperKey = envKey.toUpperCase()
-    if (!upperKey.startsWith(OUTBOUND_HOST_VALIDATOR_ENV_PREFIX_UPPER)) continue
-
-    const property = envKey.substring(OUTBOUND_HOST_VALIDATOR_ENV_PREFIX.length)
-    const upperProperty = property.toUpperCase()
-
-    if (upperProperty === 'ENABLED') {
-      const value = parseBooleanEnv(rawValue)
-      if (value !== undefined) result.enabled = value
-    } else if (upperProperty === 'INCLUDEDEFAULTMICROSOFTHOSTS') {
-      const value = parseBooleanEnv(rawValue)
-      if (value !== undefined) result.includeDefaultMicrosoftHosts = value
-    } else if (upperProperty === 'HOSTS' && rawValue) {
-      hosts.push(...rawValue.split(',').map(host => host.trim()).filter(Boolean))
-    } else {
-      const match = /^HOSTS__(\d+)$/i.exec(property)
-      if (match && rawValue?.trim()) indexedHosts.set(Number(match[1]), rawValue.trim())
-    }
-  }
-
-  for (const [, host] of [...indexedHosts.entries()].sort(([left], [right]) => left - right)) {
-    hosts.push(host)
-  }
-  if (hosts.length > 0) result.hosts = hosts
+  return { ...loadModernEnvironmentConfiguration().outboundHostValidator }
+}
 
-  return result
+/** Creates a validator using the shared configuration precedence. */
+export function createOutboundHostValidator (options: OutboundHostValidatorOptions = {}): OutboundHostValidator {
+  return new OutboundHostValidator(resolveOutboundHostValidatorOptions(options))
 }
 
-/** Creates the default validator, with explicit settings overriding the environment. */
-export function createOutboundHostValidator (options?: OutboundHostValidatorOptions): OutboundHostValidator {
+function resolveOutboundHostValidatorOptions (
+  options: OutboundHostValidatorOptions
+): OutboundHostValidatorOptions {
+  const external = getConfigurationSnapshot(options.configurationContext)
   const fromEnv = loadOutboundHostValidatorOptionsFromEnv()
-  return new OutboundHostValidator({
-    enabled: options?.enabled ?? fromEnv.enabled,
-    includeDefaultMicrosoftHosts: options?.includeDefaultMicrosoftHosts ?? fromEnv.includeDefaultMicrosoftHosts,
-    hosts: options?.hosts ?? fromEnv.hosts
-  })
+  const direct: OutboundHostValidatorOptions = {}
+  if (options.enabled !== undefined) direct.enabled = options.enabled
+  if (options.includeDefaultMicrosoftHosts !== undefined) {
+    direct.includeDefaultMicrosoftHosts = options.includeDefaultMicrosoftHosts
+  }
+  if (options.hosts !== undefined) direct.hosts = options.hosts
+  return mergeDefined<OutboundHostValidatorOptions>(
+    external.fallback.outboundHostValidator,
+    fromEnv,
+    external.overrideEnvironment.outboundHostValidator,
+    direct,
+    external.enforce.outboundHostValidator
+  )
 }
 
 function getUrlHost (input: string | URL | null | undefined): string | undefined {

package/src/state/agentState.ts

@@ -3,7 +3,14 @@
  * Licensed under the MIT License.
  */
 
-import { Storage, StorageKeyFactory, StoreItem } from '../storage/storage'
+import { StorageKeyFactory, StorageOperationStatus, StorageProvider, StorageV2, StorageWriteMode, StoreItem } from '../storage/storage'
+import {
+  asStorageV2,
+  assertAgentStateWriteSucceeded,
+  assertStorageDeleteSucceeded,
+  getStorageReadValue,
+  isStorageV2,
+} from '../storage/storageCompatibility'
 import { TurnContext } from '../turnContext'
 import { createHash } from 'node:crypto'
 import { AgentStatePropertyAccessor } from './agentStatePropertyAccesor'
@@ -26,6 +33,10 @@ export interface CachedAgentState {
    * Hash of the state used to detect changes
    */
   hash: string;
+  /** Version returned when the state was loaded, used to reject stale V2 writes. */
+  version?: string;
+  /** Whether the state was not found when it was loaded. */
+  isNew?: boolean;
 }
 
 /**
@@ -62,13 +73,17 @@ export interface CustomKey {
 export class AgentState {
   private readonly stateKey = Symbol('state')
 
+  private get internalStorage (): StorageV2 {
+    return asStorageV2(this.storage)
+  }
+
   /**
    * Creates a new instance of AgentState.
    *
    * @param storage The storage provider used to persist state between turns
    * @param storageKey A factory function that generates keys for storing state data
    */
-  constructor (protected storage: Storage, protected storageKey: StorageKeyFactory) { }
+  constructor (protected storage: StorageProvider, protected storageKey: StorageKeyFactory) {}
 
   /**
    * Creates a property accessor for the specified property.
@@ -101,11 +116,15 @@ export class AgentState {
     if (force || !cached || !cached.state) {
       const key: string = await this.getStorageOrCustomKey(customKey, context)
       logger.info(`Reading storage with key ${key}`)
-      const storedItem = await this.storage.read([key])
-
-      const state: any = storedItem[key] || {}
+      const storedItems = await this.internalStorage.read<Record<string, any>>([key])
+      const state: any = getStorageReadValue(storedItems, key) ?? {}
       const hash: string = this.calculateChangeHash(state)
-      context.turnState.set(this.stateKey, { state, hash })
+      context.turnState.set(this.stateKey, {
+        state,
+        hash,
+        version: storedItems[key]?.version,
+        isNew: storedItems[key]?.status === StorageOperationStatus.NotFound,
+      })
 
       return state
     }
@@ -130,15 +149,21 @@ export class AgentState {
       if (!cached) {
         cached = { state: {}, hash: '' }
       }
-      cached.state.eTag = '*'
-      const changes: StoreItem = {} as StoreItem
-
       const key: string = await this.getStorageOrCustomKey(customKey, context)
 
-      changes[key] = cached.state
-
       logger.info(`Writing storage with key ${key}`)
-      await this.storage.write(changes)
+      const results = await this.internalStorage.write(
+        { [key]: cached.state },
+        cached.version !== undefined
+          ? { expectedVersion: cached.version }
+          : cached.isNew && isStorageV2(this.storage)
+            ? { mode: StorageWriteMode.CreateOnly }
+            : undefined
+      )
+      assertAgentStateWriteSucceeded(results, key, this.constructor.name)
+      const result = results[key]
+      cached.version = result.version
+      cached.isNew = false
       cached.hash = this.calculateChangeHash(cached.state)
       context.turnState.set(this.stateKey, cached)
     }
@@ -195,7 +220,8 @@ export class AgentState {
     }
     const key = await this.getStorageOrCustomKey(customKey, context)
     logger.info(`Deleting storage with key ${key}`)
-    await this.storage.delete([key])
+    const results = await this.internalStorage.delete([key])
+    assertStorageDeleteSucceeded(results, [key])
   }
 
   /**

package/src/state/conversationState.ts

@@ -4,7 +4,7 @@
  */
 
 import { AgentState } from './agentState'
-import { Storage } from '../storage/storage'
+import { StorageProvider } from '../storage/storage'
 import { TurnContext } from '../turnContext'
 import { Activity, ExceptionHelper } from '@microsoft/agents-activity'
 import { Errors } from '../errorHelper'
@@ -17,7 +17,7 @@ export class ConversationState extends AgentState {
    * Creates a new instance of ConversationState.
    * @param storage The storage provider.
    */
-  constructor (storage: Storage, private readonly namespace: string = '') {
+  constructor (storage: StorageProvider, private readonly namespace: string = '') {
     super(storage, (context: TurnContext) => {
       const key: string = this.getStorageKey(context)
 

package/src/state/userState.ts

@@ -4,7 +4,7 @@
  */
 
 import { AgentState } from './agentState'
-import { Storage } from '../storage/storage'
+import { StorageProvider } from '../storage/storage'
 import { TurnContext } from '../turnContext'
 import { Activity, ExceptionHelper } from '@microsoft/agents-activity'
 import { Errors } from '../errorHelper'
@@ -17,7 +17,7 @@ export class UserState extends AgentState {
     * Creates a new instance of UserState.
     * @param storage The storage provider.
     */
-  constructor (storage: Storage, private readonly namespace: string = '') {
+  constructor (storage: StorageProvider, private readonly namespace: string = '') {
     super(storage, (context: TurnContext) => {
       const key: string = this.getStorageKey(context)
 

package/src/statusCodes.ts

@@ -78,6 +78,12 @@ export enum StatusCodes {
    */
   UPGRADE_REQUIRED = 426,
 
+  /**
+   * The user has sent too many requests in a given amount of time.
+   * Used when rate limiting or throttling prevents a turn from being processed.
+   */
+  TOO_MANY_REQUESTS = 429,
+
   /**
    * The server encountered an unexpected condition that prevented it from fulfilling the request.
    * Generic error message when an unexpected agent hosting error occurs