@microsoft/agents-hosting 1.9.0-beta.3.gb2d23c1c44 → 1.9.1

package/src/configuration/configurationSource.ts

@@ -0,0 +1,76 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/** A value accepted in a hierarchical configuration document. */
+export type ConfigurationDocumentValue =
+  | string
+  | number
+  | boolean
+  | readonly ConfigurationDocumentValue[]
+  | ConfigurationDocument
+
+/** Provider-neutral hierarchical configuration data. */
+export interface ConfigurationDocument {
+  readonly [key: string]: ConfigurationDocumentValue
+}
+
+/** Values returned by a pluggable configuration source. */
+export type ConfigurationSourceResult =
+  | Readonly<Record<string, string>>
+  | {
+    /** Canonical Agents SDK paths with raw string values. */
+    readonly format: 'canonical'
+    readonly values: Readonly<Record<string, string>>
+  }
+  | {
+    /** A hierarchical document using the shared Agents SDK schema. */
+    readonly format: 'document'
+    readonly value: Readonly<ConfigurationDocument>
+  }
+
+/**
+ * Supplies canonical or hierarchical configuration values.
+ *
+ * @remarks
+ * Sources are loaded asynchronously by {@link createConfigurationContext} or
+ * {@link preloadConfigurationSources}. Values are cached in an immutable
+ * host-scoped or process-level snapshot so existing synchronous hosting APIs
+ * can consume them during startup.
+ */
+export interface ConfigurationSource {
+  /**
+   * A unique name used to identify the source in diagnostics.
+   */
+  readonly name: string
+
+  /**
+   * Loads configuration data. A bare canonical record remains supported for
+   * compatibility; new sources should identify their representation explicitly.
+   */
+  load(): Promise<ConfigurationSourceResult>
+}
+
+/**
+ * Selects how an external source participates in configuration resolution.
+ */
+export type ConfigurationSourceMode =
+  | 'fallback'
+  | 'overrideEnvironment'
+  | 'enforce'
+
+/**
+ * Registers a configuration source with an explicit resolution mode.
+ */
+export interface ConfigurationSourceRegistration {
+  /**
+   * The source to preload.
+   */
+  readonly source: ConfigurationSource
+
+  /**
+   * The source's resolution mode.
+   */
+  readonly mode: ConfigurationSourceMode
+}

package/src/configuration/environmentConfiguration.ts

@@ -0,0 +1,377 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+  ConfigurationLayer,
+  createConfigurationLayer,
+  freezeConfigurationLayer,
+  isConfigurationInputError,
+  isInvalidConfigurationValueError,
+  setConfigurationValue,
+  suggestConfigurationPath
+} from './configuration'
+import { debug } from '@microsoft/agents-telemetry'
+import {
+  envParser,
+  envParserUtils,
+  parseBooleanEnv,
+  suggestClosest
+} from '../utils/env'
+import { ConnectionKeys, ConnectionMapKeys } from '../auth/settings'
+
+const CONNECTIONS = 'CONNECTIONS'
+const CONNECTIONS_MAP = 'CONNECTIONSMAP'
+const CLOUD_ADAPTER_OPTIONS = 'CLOUDADAPTEROPTIONS'
+const OUTBOUND_HOST_VALIDATOR = 'OUTBOUNDHOSTVALIDATOR'
+const AGENT_APPLICATION = 'AGENTAPPLICATION'
+const CLOUD_ADAPTER_OPTIONS_ENV_PREFIX = 'CloudAdapterOptions__'
+const warnedCloudAdapterKeys = new Set<string>()
+const cloudAdapterLogger = debug('agents:cloud-adapter')
+const authLogger = debug('agents:authConfiguration')
+const connectionMapParser = envParser<ConnectionMapKeys>({
+  serviceUrl: envParserUtils.bypass,
+  audience: envParserUtils.bypass,
+  connection: envParserUtils.bypass
+})
+const cloudAdapterOptionsParser = envParser<'emitStackTrace' | 'validateServiceUrl'>({
+  emitStackTrace: envParserUtils.bypass,
+  validateServiceUrl: envParserUtils.bypass
+})
+
+interface ModernEnvironmentOptions {
+  readonly reportCloudAdapterDiagnostics?: boolean
+}
+
+/**
+ * Binds the supported schema-shaped `__` environment variables to the
+ * canonical hierarchical configuration model.
+ */
+export function loadModernEnvironmentConfiguration (
+  env: NodeJS.ProcessEnv = process.env,
+  options: ModernEnvironmentOptions = {}
+): ConfigurationLayer {
+  const layer = createConfigurationLayer()
+  const indexedHosts = new Map<number, string>()
+
+  for (const [key, value] of Object.entries(env)) {
+    if (!value?.trim()) {
+      continue
+    }
+
+    const parts = key.split('__')
+    const root = parts[0]?.toUpperCase()
+    if (root === CONNECTIONS) {
+      bindConnection(layer, parts, value, key, options.reportCloudAdapterDiagnostics === true)
+    } else if (root === CONNECTIONS_MAP) {
+      bindConnectionMap(layer, parts, value, key, options.reportCloudAdapterDiagnostics === true)
+    } else if (root === CLOUD_ADAPTER_OPTIONS) {
+      bindCloudAdapterOptions(layer, parts, value, key, options.reportCloudAdapterDiagnostics === true)
+    } else if (root === OUTBOUND_HOST_VALIDATOR) {
+      bindOutboundHostValidator(
+        layer,
+        parts,
+        value,
+        key,
+        indexedHosts,
+        options.reportCloudAdapterDiagnostics === true
+      )
+    } else if (root === AGENT_APPLICATION) {
+      bindAuthorizationHandler(layer, parts, value, key, options.reportCloudAdapterDiagnostics === true)
+    } else if (options.reportCloudAdapterDiagnostics === true) {
+      const canonicalRoot = suggestConfigurationPath(parts[0] ?? '')
+      const suggestedRoot = canonicalRoot
+        ? canonicalRoot.charAt(0).toUpperCase() + canonicalRoot.slice(1)
+        : undefined
+      if (suggestedRoot) {
+        emitHierarchySuggestion(key, [suggestedRoot, ...parts.slice(1)].join('__'), true)
+      }
+    }
+  }
+
+  if (indexedHosts.size > 0) {
+    const configured = [...layer.outboundHostValidator.hosts ?? []]
+    for (const [, host] of [...indexedHosts].sort(([left], [right]) => left - right)) {
+      configured.push(host)
+    }
+    ;(layer.outboundHostValidator as { hosts?: readonly string[] }).hosts = configured
+  }
+
+  return freezeConfigurationLayer(layer)
+}
+
+function bindConnection (
+  layer: ConfigurationLayer,
+  parts: string[],
+  value: string,
+  sourceName: string,
+  reportDiagnostics: boolean
+): void {
+  const format = 'Connections__<id>__Settings__<property>'
+  if (parts[2]?.toUpperCase() !== 'SETTINGS') {
+    if (reportDiagnostics && suggestClosest(parts[2] ?? '', ['Settings'], 4)) {
+      emitHierarchySuggestion(sourceName, [parts[0], parts[1], 'Settings', ...parts.slice(3)].join('__'), true)
+    }
+    return
+  }
+  if (parts.length !== 4) {
+    authLogger.warn(`Invalid connection environment variable: ${sourceName}. Expected format: ${format}.`)
+    return
+  }
+  if (!parts[1]?.trim()) {
+    authLogger.warn(`Invalid connection <id> in environment variable: ${sourceName}. Expected format: ${format}.`)
+    return
+  }
+  if (!parts[3]?.trim()) {
+    authLogger.warn(`Invalid connection <property> in environment variable: ${sourceName}. Expected format: ${format}.`)
+    return
+  }
+
+  const property = parts[3] as ConnectionKeys
+  const lookup = property.toLowerCase()
+  if (lookup === 'ficclientid') {
+    authLogger.warn('Connections__<id>__Settings__FICClientId is deprecated, please use Connections__<id>__Settings__FederatedClientId instead.')
+  } else if (lookup === 'authority') {
+    authLogger.warn('Connections__<id>__Settings__Authority is deprecated, please use Connections__<id>__Settings__AuthorityEndpoint instead.')
+  } else if (lookup === 'scope') {
+    authLogger.warn('Connections__<id>__Settings__Scope is deprecated, please use Connections__<id>__Settings__Scopes instead.')
+  } else if (lookup !== 'alternateblueprintconnectionname' && reportDiagnostics) {
+    const suggestedProperty = suggestedLeaf(
+      `connections.${parts[1]}.settings.${property}`
+    )
+    if (suggestedProperty) {
+      emitHierarchySuggestion(
+        sourceName,
+        [parts[0], parts[1], parts[2], suggestedProperty].join('__'),
+        false
+      )
+    }
+  }
+  trySet(
+    layer,
+    `connections.${parts[1]}.settings.${property}`,
+    normalizeConnectionEnvironmentValue(property, value),
+    sourceName,
+    lookup === 'validateissuer'
+  )
+}
+
+function bindConnectionMap (
+  layer: ConfigurationLayer,
+  parts: string[],
+  value: string,
+  sourceName: string,
+  reportDiagnostics: boolean
+): void {
+  const format = 'ConnectionsMap__<index>__<property>'
+  if (parts.length !== 3) {
+    authLogger.warn(`Invalid connection map environment variable: ${sourceName}. Expected format: ${format}.`)
+    return
+  }
+  if (!/^\d+$/.test(parts[1])) {
+    authLogger.warn(`Invalid connection map <index> in environment variable: ${sourceName}. Expected format: ${format}, where <index> is a number.`)
+    return
+  }
+  if (!parts[2]?.trim()) {
+    authLogger.warn(`Invalid connection map <property> in environment variable: ${sourceName}. Expected format: ${format}.`)
+    return
+  }
+  const parsed = connectionMapParser.parse(parts[2] as ConnectionMapKeys, value)
+  if (parsed.key) {
+    trySet(layer, `connectionsMap.${parts[1]}.${parsed.key}`, parsed.value, sourceName)
+  } else if (reportDiagnostics) {
+    const suggestedProperty = suggestedLeaf(`connectionsMap.${parts[1]}.${parts[2]}`)
+    if (suggestedProperty) {
+      emitHierarchySuggestion(
+        sourceName,
+        [parts[0], parts[1], suggestedProperty].join('__'),
+        true
+      )
+    }
+  }
+}
+
+function bindCloudAdapterOptions (
+  layer: ConfigurationLayer,
+  parts: string[],
+  value: string,
+  sourceName: string,
+  reportDiagnostics: boolean
+): void {
+  if (parts.length !== 2 || !parts[1]?.trim()) {
+    return
+  }
+  const property = parts[1]
+  const parsed = cloudAdapterOptionsParser.parse(
+    property as Parameters<typeof cloudAdapterOptionsParser.parse>[0],
+    value
+  )
+  if (!parsed.key) {
+    if (reportDiagnostics) {
+      const suggestion = suggestClosest(property, cloudAdapterOptionsParser.keys, 4)
+      const hint = suggestion ? ` Did you mean "${CLOUD_ADAPTER_OPTIONS_ENV_PREFIX}${suggestion}"?` : ''
+      emitCloudAdapterWarning(sourceName, `Unknown CloudAdapterOptions env var: ${sourceName} (ignored).${hint}`)
+    }
+    return
+  }
+  if (parseBooleanEnv(parsed.value) === undefined) {
+    if (reportDiagnostics) {
+      emitCloudAdapterWarning(
+        `${sourceName}=${value}`,
+        `Ignored ${sourceName}=${value}; expected one of true/false/1/0.`
+      )
+    }
+    return
+  }
+  trySet(layer, `cloudAdapterOptions.${parsed.key}`, parsed.value, sourceName)
+}
+
+function bindOutboundHostValidator (
+  layer: ConfigurationLayer,
+  parts: string[],
+  value: string,
+  sourceName: string,
+  indexedHosts: Map<number, string>,
+  reportDiagnostics: boolean
+): void {
+  if (parts.length === 3 && /^\d+$/.test(parts[2])) {
+    if (parts[1]?.toUpperCase() === 'HOSTS') {
+      indexedHosts.set(Number.parseInt(parts[2], 10), value.trim())
+    } else if (reportDiagnostics && suggestClosest(parts[1] ?? '', ['Hosts'], 4)) {
+      emitHierarchySuggestion(
+        sourceName,
+        [parts[0], 'Hosts', parts[2]].join('__'),
+        true
+      )
+    }
+    return
+  }
+  if (parts.length !== 2 || !parts[1]?.trim()) {
+    return
+  }
+  if (reportDiagnostics) {
+    const suggestedProperty = suggestedLeaf(`outboundHostValidator.${parts[1]}`)
+    if (suggestedProperty) {
+      emitHierarchySuggestion(sourceName, [parts[0], suggestedProperty].join('__'), true)
+    }
+  }
+  trySet(layer, `outboundHostValidator.${parts[1]}`, value, sourceName)
+}
+
+function bindAuthorizationHandler (
+  layer: ConfigurationLayer,
+  parts: string[],
+  value: string,
+  sourceName: string,
+  reportDiagnostics: boolean
+): void {
+  const settingsIndex = parts.length - 2
+  const userAuthorization = suggestClosest(parts[1] ?? '', ['UserAuthorization'], 4)
+  const handlers = suggestClosest(parts[2] ?? '', ['Handlers'], 4)
+  const settings = suggestClosest(parts[settingsIndex] ?? '', ['Settings'], 4)
+  const handlerId = parts.slice(3, settingsIndex).join('__')
+  const property = parts.at(-1) ?? ''
+  if (parts.length < 6 ||
+    parts[1]?.toUpperCase() !== 'USERAUTHORIZATION' ||
+    parts[2]?.toUpperCase() !== 'HANDLERS' ||
+    parts[settingsIndex]?.toUpperCase() !== 'SETTINGS' ||
+    !handlerId.trim() ||
+    !property.trim()) {
+    if (reportDiagnostics && parts.length >= 6 && userAuthorization && handlers && settings) {
+      emitHierarchySuggestion(
+        sourceName,
+        [parts[0], userAuthorization, handlers, ...parts.slice(3, settingsIndex), settings, property].join('__'),
+        true
+      )
+    }
+    return
+  }
+
+  if (reportDiagnostics && property.toLowerCase() !== 'alternateblueprintconnectionname') {
+    const suggestedProperty = suggestedLeaf(
+      `agentApplication.userAuthorization.handlers.${handlerId}.settings.${property}`
+    )
+    if (suggestedProperty) {
+      emitHierarchySuggestion(
+        sourceName,
+        [parts[0], parts[1], parts[2], ...parts.slice(3, settingsIndex), parts[settingsIndex], suggestedProperty].join('__'),
+        false
+      )
+    }
+  }
+  trySet(
+    layer,
+    `agentApplication.userAuthorization.handlers.${handlerId}.settings.${property}`,
+    normalizeAuthorizationEnvironmentValue(property, value),
+    sourceName
+  )
+}
+
+function normalizeConnectionEnvironmentValue (property: ConnectionKeys, value: string): string {
+  const lookup = property.toLowerCase()
+  if (lookup === 'sendx5c' || lookup === 'bypasslocalnetworkrestriction') {
+    return String(value === 'true')
+  }
+  if (lookup === 'msalretrycount' || lookup === 'requesttimeout' || lookup === 'retrycount') {
+    const parsed = Number.parseInt(value, 10)
+    return Number.isFinite(parsed) ? String(parsed) : value
+  }
+  return value
+}
+
+function normalizeAuthorizationEnvironmentValue (property: string, value: string): string {
+  const lookup = property.toLowerCase()
+  if (lookup === 'enablesso') {
+    return String(value !== 'false')
+  }
+  if (lookup === 'invalidsigninretrymax') {
+    const parsed = Number.parseInt(value)
+    return Number.isFinite(parsed) ? String(parsed) : value
+  }
+  return value
+}
+
+function trySet (
+  layer: ConfigurationLayer,
+  path: string,
+  value: string,
+  sourceName: string,
+  throwOnInvalidValue = false
+): void {
+  try {
+    setConfigurationValue(layer, path, value, sourceName, 'environment')
+  } catch (error) {
+    if (!isConfigurationInputError(error)) {
+      throw error
+    }
+    if (throwOnInvalidValue && isInvalidConfigurationValueError(error)) {
+      throw error
+    }
+    // Existing environment binders ignore unknown and invalid values.
+  }
+}
+
+function emitCloudAdapterWarning (key: string, message: string): void {
+  if (warnedCloudAdapterKeys.has(key)) {
+    return
+  }
+  warnedCloudAdapterKeys.add(key)
+  console.warn(`[agents:cloud-adapter] ${message}`)
+  cloudAdapterLogger.warn(message)
+}
+
+function suggestedLeaf (canonicalPath: string): string | undefined {
+  return suggestConfigurationPath(canonicalPath)?.split('.').at(-1)
+}
+
+function emitHierarchySuggestion (
+  key: string,
+  suggestion: string,
+  ignored: boolean
+): void {
+  emitCloudAdapterWarning(
+    key,
+    `${ignored ? 'Ignored unknown' : 'Unrecognized'} configuration environment variable: ${key}. Did you mean "${suggestion}"?`
+  )
+}

package/src/configuration/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export {
+  ConfigurationContext,
+  createConfigurationContext,
+  preloadConfigurationSources
+} from './configuration'
+export { createJsonFileConfigurationSource } from './jsonFileConfigurationSource'
+export type {
+  ConfigurationDocument,
+  ConfigurationDocumentValue,
+  ConfigurationSource,
+  ConfigurationSourceMode,
+  ConfigurationSourceRegistration,
+  ConfigurationSourceResult
+} from './configurationSource'

package/src/configuration/jsonFileConfigurationSource.ts

@@ -0,0 +1,74 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { readFile } from 'node:fs/promises'
+import { Errors } from '../errorHelper'
+import { ConfigurationDocument, ConfigurationSource } from './configurationSource'
+
+const safeErrors = new WeakSet<Error>()
+
+/**
+ * Creates a configuration source that loads a hierarchical Agents SDK
+ * configuration document from a JSON file.
+ *
+ * @param filePath Path to the JSON configuration file.
+ * @returns A configuration source for use with `createConfigurationContext`
+ * or `preloadConfigurationSources`.
+ */
+export function createJsonFileConfigurationSource (filePath: string): ConfigurationSource {
+  return {
+    name: filePath,
+    async load () {
+      let contents: string
+      try {
+        contents = await readFile(filePath, 'utf8')
+      } catch {
+        const error = ExceptionHelper.generateException(
+          Error,
+          Errors.JsonConfigurationFileReadFailed,
+          undefined,
+          { filePath }
+        )
+        safeErrors.add(error)
+        throw error
+      }
+
+      let value: unknown
+      try {
+        value = JSON.parse(contents)
+      } catch {
+        const error = ExceptionHelper.generateException(
+          SyntaxError,
+          Errors.InvalidJsonConfigurationFile,
+          undefined,
+          { filePath }
+        )
+        safeErrors.add(error)
+        throw error
+      }
+
+      if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        const error = ExceptionHelper.generateException(
+          TypeError,
+          Errors.JsonConfigurationDocumentRequired,
+          undefined,
+          { filePath }
+        )
+        safeErrors.add(error)
+        throw error
+      }
+
+      return {
+        format: 'document',
+        value: value as ConfigurationDocument
+      }
+    }
+  }
+}
+
+export function isSafeJsonFileConfigurationError (error: unknown): error is Error {
+  return error instanceof Error && safeErrors.has(error)
+}

package/src/createCloudAdapter.ts

@@ -7,6 +7,7 @@ import { ActivityHandler } from './activityHandler'
 import { AgentApplication } from './app/agentApplication'
 import { AuthConfiguration } from './auth/authConfiguration'
 import { CloudAdapter } from './cloudAdapter'
+import { ConfigurationContext } from './configuration/configuration'
 import { HeaderPropagationDefinition } from './headerPropagation'
 import { TurnState } from './app/turnState'
 
@@ -18,15 +19,40 @@ export interface CloudAdapterResult {
   headerPropagation: HeaderPropagationDefinition | undefined
 }
 
+/**
+ * Options accepted by {@link createCloudAdapter} when creating a new `CloudAdapter` for an agent
+ * that does not already own one.
+ *
+ * @remarks
+ * This is the single named options type shared by the `@microsoft/agents-hosting-express` and
+ * `@microsoft/agents-hosting-fastify` convenience APIs (`createAgentRequestHandler`,
+ * `startServer`, and the Fastify plugin) so every hosting entry point resolves auth and
+ * constructs a `CloudAdapter` through the same path.
+ */
+export interface CreateCloudAdapterOptions {
+  /**
+   * Optional host-scoped external configuration used to resolve the authentication
+   * configuration and runtime options of a newly created `CloudAdapter` (e.g. `emitStackTrace`,
+   * `validateServiceUrl`, outbound host validation).
+   *
+   * For an `AgentApplication`, this defaults to `agent.options.configurationContext` when
+   * omitted. A plain `ActivityHandler` has no built-in context, so it must be supplied here to
+   * participate in host-scoped configuration.
+   */
+  configurationContext?: ConfigurationContext
+}
+
 /**
  * Creates a CloudAdapter for the given agent.
  *
- * If the agent is an AgentApplication with a pre-configured adapter, that adapter is reused.
- * Otherwise, a new CloudAdapter is created.
+ * An `AgentApplication`'s pre-configured adapter is always reused when available, preserving
+ * its identity, middleware, connection manager, and runtime policy. The auth configuration is
+ * used only when a new adapter must be created.
  *
  * @param agent - The AgentApplication or ActivityHandler instance.
- * @param authConfig - Optional auth configuration used when creating a new CloudAdapter.
- * If the agent already has an adapter, that adapter is reused and this value is ignored.
+ * @param authConfig - Optional auth configuration used when creating a new adapter. If the
+ * application already owns an adapter, this value does not replace or reconfigure it.
+ * @param options - Optional additional settings, such as a host-scoped {@link ConfigurationContext}.
  * @returns An object containing the CloudAdapter and optional header propagation configuration.
  *
  * @example
@@ -42,15 +68,32 @@ export interface CloudAdapterResult {
  */
 export const createCloudAdapter = (
   agent: AgentApplication<TurnState<any, any>> | ActivityHandler,
-  authConfig?: AuthConfiguration
+  authConfig?: AuthConfiguration,
+  options?: CreateCloudAdapterOptions
 ): CloudAdapterResult => {
+  const configurationContext = options?.configurationContext ??
+    (agent instanceof AgentApplication ? agent.options.configurationContext : undefined)
+
   if (agent instanceof ActivityHandler) {
-    return { adapter: new CloudAdapter(authConfig), headerPropagation: undefined }
+    return {
+      adapter: new CloudAdapter(
+        authConfig,
+        undefined,
+        undefined,
+        { configurationContext }
+      ),
+      headerPropagation: undefined
+    }
   }
 
-  // AgentApplication: reuse its pre-configured adapter when present, otherwise create one.
-  // headerPropagation is an application-level option, so read it regardless of adapter source.
+  // Preserve the application-owned processing adapter regardless of host authorization settings.
+  // Hosting integrations perform their independent inbound authorization stage before processing.
   const headerPropagation = agent.options?.headerPropagation
-  const adapter = agent.adapter ?? new CloudAdapter(authConfig)
+  const adapter = agent.adapter ?? new CloudAdapter(
+    authConfig,
+    undefined,
+    undefined,
+    { configurationContext }
+  )
   return { adapter, headerPropagation }
 }