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

package/dist/src/configuration/configuration.js

@@ -0,0 +1,836 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigurationContext = void 0;
+exports.createConfigurationLayer = createConfigurationLayer;
+exports.freezeConfigurationLayer = freezeConfigurationLayer;
+exports.mergeConfigurationLayers = mergeConfigurationLayers;
+exports.suggestConfigurationPath = suggestConfigurationPath;
+exports.setConfigurationValue = setConfigurationValue;
+exports.isConfigurationInputError = isConfigurationInputError;
+exports.isInvalidConfigurationValueError = isInvalidConfigurationValueError;
+exports.createConfigurationContext = createConfigurationContext;
+exports.preloadConfigurationSources = preloadConfigurationSources;
+exports.getConfigurationSnapshot = getConfigurationSnapshot;
+exports.resetConfigurationSourcesForTest = resetConfigurationSourcesForTest;
+const agents_activity_1 = require("@microsoft/agents-activity");
+const errorHelper_1 = require("../errorHelper");
+const env_1 = require("../utils/env");
+const jsonFileConfigurationSource_1 = require("./jsonFileConfigurationSource");
+const modes = ['fallback', 'overrideEnvironment', 'enforce'];
+const authParsers = {
+    authType: asString,
+    tenantId: asString,
+    clientId: asString,
+    clientSecret: asString,
+    certPemFile: asString,
+    certKeyFile: asString,
+    connectionName: asString,
+    federatedClientId: asString,
+    authorityEndpoint: asString,
+    scopes: asList,
+    altBlueprintConnectionName: asString,
+    WIDAssertionFile: asString,
+    federatedTokenFile: asString,
+    idpmResource: asString,
+    azureRegion: asString,
+    sendX5C: asBoolean,
+    msalRetryCount: asNonNegativeInteger,
+    sidecarBaseUrl: asString,
+    serviceName: asString,
+    blueprintServiceName: asString,
+    bypassLocalNetworkRestriction: asBoolean,
+    // Superset field: the JavaScript millisecond form parses here. A document
+    // string is the .NET-only TimeSpan form and is rejected by
+    // dotNetOnlyTimeSpanSettings below, not by this parser.
+    requestTimeout: asPositiveInteger,
+    retryCount: asNonNegativeInteger,
+    issuers: asList,
+    validateIssuer: asBoolean
+};
+const cloudAdapterParsers = {
+    emitStackTrace: asBoolean,
+    validateServiceUrl: asBoolean
+};
+const connectionMapParsers = {
+    serviceUrl: asString,
+    audience: asString,
+    connection: asString
+};
+const outboundHostValidatorParsers = {
+    enabled: asBoolean,
+    includeDefaultMicrosoftHosts: asBoolean,
+    hosts: asList
+};
+const authorizationParsers = {
+    type: asString,
+    azureBotOAuthConnectionName: asString,
+    title: asString,
+    text: asString,
+    invalidSignInRetryMessage: asString,
+    invalidSignInRetryMessageFormat: asString,
+    invalidSignInRetryMaxExceededMessage: asString,
+    oboConnectionName: asString,
+    enableSso: asBoolean,
+    invalidSignInRetryMax: asNonNegativeInteger,
+    oboScopes: asList,
+    altBlueprintConnectionName: asString,
+    scopes: asList
+};
+const authPropertyAliases = {
+    alternateblueprintconnectionname: 'altBlueprintConnectionName',
+    ficclientid: 'federatedClientId',
+    authority: 'authorityEndpoint',
+    scope: 'scopes'
+};
+const authorizationPropertyAliases = {
+    alternateblueprintconnectionname: 'altBlueprintConnectionName'
+};
+const dotNetOnlyConnectionSettings = new Set([
+    'certificatethumbprint',
+    'certificatesubjectname',
+    'certificatestorelocation',
+    'certificatestorename',
+    'validcertificateonly'
+]);
+const dotNetOnlyAuthorizationSettings = new Set([
+    'cancelsignincommands',
+    'endoninvalidmessage',
+    'showsigninlink',
+    'signincancelledmessage',
+    'teamssignininprogressmessage',
+    'timeout'
+]);
+// Connection settings that are a JS/.NET superset: JavaScript accepts the
+// positive-integer millisecond form, while a document string is the
+// .NET-only TimeSpan representation and is rejected as unsupported rather
+// than as a generic invalid value. Canonical (environment) string values are
+// unaffected, since every canonical value is a string regardless of runtime.
+const dotNetOnlyTimeSpanSettings = new Set([
+    'requesttimeout'
+]);
+let state = { kind: 'uninitialized' };
+const contextSnapshots = new WeakMap();
+let instantiateConfigurationContext;
+/**
+ * An immutable, host-scoped set of resolved external configuration sources.
+ *
+ * @remarks
+ * Create instances with {@link createConfigurationContext}. The context is
+ * intentionally opaque; consumers pass it through their named options.
+ */
+class ConfigurationContext {
+    constructor() {
+        this.configurationContextBrand = undefined;
+    }
+}
+exports.ConfigurationContext = ConfigurationContext;
+(() => {
+    instantiateConfigurationContext = () => new ConfigurationContext();
+})();
+function asString(value) {
+    return value;
+}
+function asBoolean(value) {
+    return (0, env_1.parseBooleanEnv)(value);
+}
+function asInteger(value) {
+    const normalized = value.trim();
+    if (!/^-?\d+$/.test(normalized)) {
+        return undefined;
+    }
+    const parsed = Number.parseInt(normalized, 10);
+    return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+function asNonNegativeInteger(value) {
+    const parsed = asInteger(value);
+    return parsed !== undefined && parsed >= 0 ? parsed : undefined;
+}
+function asPositiveInteger(value) {
+    const parsed = asInteger(value);
+    return parsed !== undefined && parsed > 0 ? parsed : undefined;
+}
+function asList(value) {
+    return value.includes(',')
+        ? value.split(',').map(item => item.trim()).filter(Boolean)
+        : value.split(/\s+/).filter(Boolean);
+}
+function createConfigurationLayer() {
+    return {
+        connections: new Map(),
+        connectionsMap: new Map(),
+        cloudAdapterOptions: {},
+        outboundHostValidator: {},
+        agentApplication: {
+            userAuthorization: {
+                handlers: new Map()
+            }
+        }
+    };
+}
+function emptySnapshot() {
+    return Object.freeze({
+        fallback: freezeConfigurationLayer(createConfigurationLayer()),
+        overrideEnvironment: freezeConfigurationLayer(createConfigurationLayer()),
+        enforce: freezeConfigurationLayer(createConfigurationLayer())
+    });
+}
+function freezeConfigurationLayer(layer) {
+    return Object.freeze({
+        connections: new Map([...layer.connections].map(([lookup, connection]) => [
+            lookup,
+            Object.freeze({
+                id: connection.id,
+                settings: freezeRecord(connection.settings)
+            })
+        ])),
+        connectionsMap: new Map([...layer.connectionsMap].map(([index, item]) => [
+            index,
+            Object.freeze({ ...item })
+        ])),
+        cloudAdapterOptions: Object.freeze({ ...layer.cloudAdapterOptions }),
+        outboundHostValidator: Object.freeze({
+            ...layer.outboundHostValidator,
+            ...(layer.outboundHostValidator.hosts === undefined
+                ? {}
+                : { hosts: Object.freeze([...layer.outboundHostValidator.hosts]) })
+        }),
+        agentApplication: Object.freeze({
+            userAuthorization: Object.freeze({
+                handlers: new Map([...layer.agentApplication.userAuthorization.handlers].map(([lookup, handler]) => [
+                    lookup,
+                    Object.freeze({ id: handler.id, settings: freezeRecord(handler.settings) })
+                ]))
+            })
+        })
+    });
+}
+function mergeConfigurationLayers(...layers) {
+    var _a, _b;
+    const merged = createConfigurationLayer();
+    for (const layer of layers) {
+        for (const connection of layer.connections.values()) {
+            const lookup = connection.id.toLowerCase();
+            const current = merged.connections.get(lookup);
+            merged.connections.set(lookup, {
+                id: (_a = current === null || current === void 0 ? void 0 : current.id) !== null && _a !== void 0 ? _a : connection.id,
+                settings: {
+                    ...current === null || current === void 0 ? void 0 : current.settings,
+                    ...connection.settings
+                }
+            });
+        }
+        for (const [index, item] of layer.connectionsMap) {
+            ;
+            merged.connectionsMap.set(index, {
+                ...merged.connectionsMap.get(index),
+                ...item
+            });
+        }
+        Object.assign(merged.cloudAdapterOptions, layer.cloudAdapterOptions);
+        Object.assign(merged.outboundHostValidator, layer.outboundHostValidator);
+        const mergedHandlers = merged.agentApplication.userAuthorization.handlers;
+        for (const handler of layer.agentApplication.userAuthorization.handlers.values()) {
+            const lookup = handler.id.toLowerCase();
+            const current = mergedHandlers.get(lookup);
+            mergedHandlers.set(lookup, {
+                id: (_b = current === null || current === void 0 ? void 0 : current.id) !== null && _b !== void 0 ? _b : handler.id,
+                settings: {
+                    ...current === null || current === void 0 ? void 0 : current.settings,
+                    ...handler.settings
+                }
+            });
+        }
+    }
+    return freezeConfigurationLayer(merged);
+}
+function freezeRecord(record) {
+    return Object.freeze(Object.fromEntries(Object.entries(record).map(([key, value]) => [
+        key,
+        Array.isArray(value) ? Object.freeze([...value]) : value
+    ])));
+}
+const canonicalRoots = [
+    'connections',
+    'connectionsMap',
+    'cloudAdapterOptions',
+    'outboundHostValidator',
+    'agentApplication'
+];
+/**
+ * Suggests a canonical path by correcting only fixed schema segments.
+ * Dynamic connection/handler IDs and route indexes are preserved verbatim.
+ */
+function suggestConfigurationPath(path) {
+    var _a, _b;
+    const parts = path.split('.');
+    const root = findCanonicalSegment(parts[0], canonicalRoots);
+    if (!root) {
+        return undefined;
+    }
+    let suggested;
+    if (parts.length === 1) {
+        suggested = [root];
+    }
+    else if (root === 'connections' && parts.length === 3) {
+        const settings = findCanonicalSegment(parts[2], ['settings']);
+        if (settings) {
+            suggested = [root, parts[1], settings];
+        }
+    }
+    else if (root === 'connections' && parts.length >= 4) {
+        const settingsIndex = parts.length - 2;
+        const settings = findCanonicalSegment(parts[settingsIndex], ['settings']);
+        const property = findCanonicalProperty((_a = parts.at(-1)) !== null && _a !== void 0 ? _a : '', authParsers, authPropertyAliases);
+        if (settings && property && settingsIndex > 1) {
+            suggested = [root, ...parts.slice(1, settingsIndex), settings, property];
+        }
+    }
+    else if (root === 'connectionsMap' && parts.length === 3 && /^\d+$/.test(parts[1])) {
+        const property = findCanonicalProperty(parts[2], connectionMapParsers);
+        if (property) {
+            suggested = [root, parts[1], property];
+        }
+    }
+    else if (root === 'cloudAdapterOptions' && parts.length === 2) {
+        const property = findCanonicalProperty(parts[1], cloudAdapterParsers);
+        if (property) {
+            suggested = [root, property];
+        }
+    }
+    else if (root === 'outboundHostValidator' && parts.length === 2) {
+        const property = findCanonicalProperty(parts[1], outboundHostValidatorParsers);
+        if (property) {
+            suggested = [root, property];
+        }
+    }
+    else if (root === 'agentApplication' && parts.length === 2) {
+        const userAuthorization = findCanonicalSegment(parts[1], ['userAuthorization']);
+        if (userAuthorization) {
+            suggested = [root, userAuthorization];
+        }
+    }
+    else if (root === 'agentApplication' && parts.length === 3) {
+        const userAuthorization = findCanonicalSegment(parts[1], ['userAuthorization']);
+        const handlers = findCanonicalSegment(parts[2], ['handlers']);
+        if (userAuthorization && handlers) {
+            suggested = [root, userAuthorization, handlers];
+        }
+    }
+    else if (root === 'agentApplication' && parts.length === 5) {
+        const userAuthorization = findCanonicalSegment(parts[1], ['userAuthorization']);
+        const handlers = findCanonicalSegment(parts[2], ['handlers']);
+        const settings = findCanonicalSegment(parts[4], ['settings']);
+        if (userAuthorization && handlers && settings) {
+            suggested = [root, userAuthorization, handlers, parts[3], settings];
+        }
+    }
+    else if (root === 'agentApplication' && parts.length >= 6) {
+        const settingsIndex = parts.length - 2;
+        const userAuthorization = findCanonicalSegment(parts[1], ['userAuthorization']);
+        const handlers = findCanonicalSegment(parts[2], ['handlers']);
+        const settings = findCanonicalSegment(parts[settingsIndex], ['settings']);
+        const property = findCanonicalProperty((_b = parts.at(-1)) !== null && _b !== void 0 ? _b : '', authorizationParsers, authorizationPropertyAliases);
+        if (userAuthorization && handlers && settings && property && settingsIndex > 3) {
+            suggested = [
+                root,
+                userAuthorization,
+                handlers,
+                ...parts.slice(3, settingsIndex),
+                settings,
+                property
+            ];
+        }
+    }
+    const result = suggested === null || suggested === void 0 ? void 0 : suggested.join('.');
+    return result && result.toLowerCase() !== path.toLowerCase() ? result : undefined;
+}
+function findCanonicalSegment(value, candidates) {
+    var _a;
+    if (!value) {
+        return undefined;
+    }
+    return (_a = candidates.find(candidate => candidate.toLowerCase() === value.toLowerCase())) !== null && _a !== void 0 ? _a : (0, env_1.suggestClosest)(value, candidates, 4);
+}
+function findCanonicalProperty(value, parsers, aliases = {}) {
+    const alias = aliases[value.toLowerCase()];
+    return alias !== null && alias !== void 0 ? alias : findCanonicalSegment(value, Object.keys(parsers));
+}
+function invalidConfigurationPath(path, sourceName) {
+    const suggestion = suggestConfigurationPath(path);
+    const definition = suggestion
+        ? {
+            ...errorHelper_1.Errors.InvalidConfigurationPath,
+            description: `${errorHelper_1.Errors.InvalidConfigurationPath.description} Did you mean \`${suggestion}\`?`
+        }
+        : errorHelper_1.Errors.InvalidConfigurationPath;
+    return agents_activity_1.ExceptionHelper.generateException(Error, definition, undefined, { path, sourceName });
+}
+function parseValue(parsers, property, value, path, sourceName, format, aliases = {}, allowExtension = false) {
+    const lookup = property.toLowerCase();
+    const aliasedKey = format === 'canonical' ? undefined : aliases[lookup];
+    const key = aliasedKey !== null && aliasedKey !== void 0 ? aliasedKey : Object.keys(parsers).find(candidate => candidate.toLowerCase() === lookup);
+    if (!key) {
+        if (format === 'canonical' && aliases[lookup]) {
+            throw invalidConfigurationPath(path, sourceName);
+        }
+        if (allowExtension) {
+            validateDynamicSegment(property, path, sourceName);
+            const extensionValue = format === 'document'
+                ? parseExtensionValue(value)
+                : typeof value === 'string' ? value : undefined;
+            if (extensionValue !== undefined) {
+                return { key: property, value: extensionValue };
+            }
+            throw agents_activity_1.ExceptionHelper.generateException(TypeError, errorHelper_1.Errors.InvalidConfigurationValue, undefined, { path, sourceName });
+        }
+        throw invalidConfigurationPath(path, sourceName);
+    }
+    const parser = parsers[key];
+    const parsed = format === 'document'
+        ? parseDocumentValue(parser, value)
+        : typeof value === 'string' ? parser(value) : undefined;
+    if (parsed === undefined) {
+        if (key === 'validateIssuer') {
+            throw agents_activity_1.ExceptionHelper.generateException(TypeError, errorHelper_1.Errors.InvalidBooleanConfigurationValue, undefined, { path, sourceName });
+        }
+        if (format === 'document' && typeof value === 'string' && dotNetOnlyTimeSpanSettings.has(lookup)) {
+            unsupportedRuntimeField(path, sourceName);
+        }
+        throw agents_activity_1.ExceptionHelper.generateException(TypeError, errorHelper_1.Errors.InvalidConfigurationValue, undefined, { path, sourceName });
+    }
+    function parseDocumentValue(parser, value) {
+        if (parser === asString) {
+            return typeof value === 'string' ? value : undefined;
+        }
+        if (parser === asBoolean) {
+            return typeof value === 'boolean' ? value : undefined;
+        }
+        if (parser === asInteger) {
+            return typeof value === 'number' && Number.isSafeInteger(value) ? value : undefined;
+        }
+        if (parser === asNonNegativeInteger) {
+            return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+        }
+        if (parser === asPositiveInteger) {
+            return typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+        }
+        if (parser === asList) {
+            return Array.isArray(value) &&
+                value.every(item => typeof item === 'string' && item.trim().length > 0)
+                ? [...value]
+                : undefined;
+        }
+        return undefined;
+    }
+    return { key, value: parsed };
+}
+function parseExtensionValue(value) {
+    if (typeof value === 'string' || typeof value === 'boolean' ||
+        (typeof value === 'number' && Number.isSafeInteger(value))) {
+        return value;
+    }
+    if (Array.isArray(value) &&
+        value.every(item => typeof item === 'string' && item.trim().length > 0)) {
+        return [...value];
+    }
+    return undefined;
+}
+function validateDynamicSegment(segment, path, sourceName) {
+    if (['__proto__', 'constructor', 'prototype'].includes(segment.toLowerCase())) {
+        throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.InvalidConfigurationPath, undefined, { path, sourceName });
+    }
+}
+function setConfigurationValue(target, path, rawValue, sourceName, format) {
+    var _a;
+    const parts = path.split('.');
+    const authConnectionMatch = /^connections\.(.+)\.settings\.([^.]+)$/.exec(path);
+    if (authConnectionMatch) {
+        const [, id, property] = authConnectionMatch;
+        validateDynamicSegment(id, path, sourceName);
+        const parsed = parseValue(authParsers, property, rawValue, path, sourceName, format, authPropertyAliases, true);
+        const current = ensureConnection(target, id);
+        current.settings[parsed.key] = parsed.value;
+        return;
+    }
+    if (parts.length === 3 && parts[0] === 'connectionsMap' && /^\d+$/.test(parts[1])) {
+        const index = Number.parseInt(parts[1], 10);
+        const parsed = parseValue(connectionMapParsers, parts[2], rawValue, path, sourceName, format);
+        const current = { ...((_a = target.connectionsMap.get(index)) !== null && _a !== void 0 ? _a : {}) };
+        current[parsed.key] = parsed.value;
+        target.connectionsMap.set(index, current);
+        return;
+    }
+    if (parts.length === 2 && parts[0] === 'cloudAdapterOptions') {
+        const parsed = parseValue(cloudAdapterParsers, parts[1], rawValue, path, sourceName, format);
+        target.cloudAdapterOptions[parsed.key] = parsed.value;
+        return;
+    }
+    if (parts.length === 2 && parts[0] === 'outboundHostValidator') {
+        const parsed = parseValue(outboundHostValidatorParsers, parts[1], rawValue, path, sourceName, format);
+        if (parsed.key === 'hosts') {
+            ;
+            target.outboundHostValidator.hosts = parsed.value;
+        }
+        else {
+            ;
+            target.outboundHostValidator[parsed.key] = parsed.value;
+        }
+        return;
+    }
+    const authorizationHandlerMatch = /^agentApplication\.userAuthorization\.handlers\.(.+)\.settings\.([^.]+)$/.exec(path);
+    if (authorizationHandlerMatch) {
+        const [, id, property] = authorizationHandlerMatch;
+        validateDynamicSegment(id, path, sourceName);
+        const parsed = parseValue(authorizationParsers, property, rawValue, path, sourceName, format, authorizationPropertyAliases, true);
+        const current = ensureAuthorizationHandler(target, id);
+        current.settings[parsed.key] = parsed.value;
+        return;
+    }
+    throw invalidConfigurationPath(path, sourceName);
+}
+function ensureConnection(target, id) {
+    var _a;
+    const connections = target.connections;
+    const lookup = id.toLowerCase();
+    const connection = (_a = connections.get(lookup)) !== null && _a !== void 0 ? _a : { id, settings: {} };
+    connections.set(lookup, connection);
+    return connection;
+}
+function ensureAuthorizationHandler(target, id) {
+    var _a;
+    const handlers = target.agentApplication.userAuthorization.handlers;
+    const lookup = id.toLowerCase();
+    const handler = (_a = handlers.get(lookup)) !== null && _a !== void 0 ? _a : { id, settings: {} };
+    handlers.set(lookup, handler);
+    return handler;
+}
+function isConfigurationInputError(error) {
+    const code = error === null || error === void 0 ? void 0 : error.code;
+    return code === errorHelper_1.Errors.InvalidConfigurationPath.code ||
+        isInvalidConfigurationValueError(error) ||
+        code === errorHelper_1.Errors.UnsupportedRuntimeConfigurationField.code;
+}
+function isInvalidConfigurationValueError(error) {
+    const code = error === null || error === void 0 ? void 0 : error.code;
+    return code === errorHelper_1.Errors.InvalidConfigurationValue.code ||
+        code === errorHelper_1.Errors.InvalidBooleanConfigurationValue.code;
+}
+function asDocumentObject(value, path, sourceName) {
+    if (value === null || Array.isArray(value) || typeof value !== 'object') {
+        throw agents_activity_1.ExceptionHelper.generateException(TypeError, errorHelper_1.Errors.InvalidConfigurationValue, undefined, { path, sourceName });
+    }
+    return value;
+}
+function uniqueEntries(value, path, sourceName) {
+    const normalized = new Set();
+    return Object.entries(value).map(([key, entryValue]) => {
+        const lookup = key.toLowerCase();
+        if (normalized.has(lookup)) {
+            throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.InvalidConfigurationPath, undefined, {
+                path: path ? `${path}.${key}` : key,
+                sourceName
+            });
+        }
+        normalized.add(lookup);
+        return [key, entryValue];
+    });
+}
+function unsupportedRuntimeField(path, sourceName) {
+    throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.UnsupportedRuntimeConfigurationField, undefined, { path, sourceName });
+}
+function compileDocument(target, document, sourceName) {
+    for (const [section, sectionValue] of uniqueEntries(document, '', sourceName)) {
+        switch (section.toLowerCase()) {
+            case 'connections':
+                compileDocumentConnections(target, sectionValue, section, sourceName);
+                break;
+            case 'connectionsmap':
+                compileDocumentConnectionsMap(target, sectionValue, section, sourceName);
+                break;
+            case 'cloudadapteroptions':
+                compileDocumentLeafObject(target, sectionValue, section, sourceName, 'cloudAdapterOptions');
+                break;
+            case 'outboundhostvalidator':
+                compileDocumentLeafObject(target, sectionValue, section, sourceName, 'outboundHostValidator');
+                break;
+            case 'agentapplication':
+                compileDocumentAgentApplication(target, sectionValue, section, sourceName);
+                break;
+            default:
+                // Shared appsettings files may contain unrelated host configuration.
+                if (suggestConfigurationPath(section)) {
+                    throw invalidConfigurationPath(section, sourceName);
+                }
+                break;
+        }
+    }
+}
+function compileDocumentConnections(target, value, path, sourceName) {
+    const connections = asDocumentObject(value, path, sourceName);
+    for (const [id, definitionValue] of uniqueEntries(connections, path, sourceName)) {
+        validateDynamicSegment(id, `${path}.${id}`, sourceName);
+        const definition = asDocumentObject(definitionValue, `${path}.${id}`, sourceName);
+        ensureConnection(target, id);
+        let settingsFound = false;
+        for (const [key, entryValue] of uniqueEntries(definition, `${path}.${id}`, sourceName)) {
+            const entryPath = `${path}.${id}.${key}`;
+            if (key.toLowerCase() === 'settings') {
+                settingsFound = true;
+                compileDocumentLeafObject(target, entryValue, entryPath, sourceName, `connections.${id}.settings`);
+            }
+            else if (key.toLowerCase() === 'assembly' || key.toLowerCase() === 'type') {
+                unsupportedRuntimeField(entryPath, sourceName);
+            }
+            else {
+                throw invalidConfigurationPath(entryPath, sourceName);
+            }
+        }
+        if (!settingsFound) {
+            throw agents_activity_1.ExceptionHelper.generateException(TypeError, errorHelper_1.Errors.InvalidConfigurationValue, undefined, {
+                path: `${path}.${id}.settings`,
+                sourceName
+            });
+        }
+    }
+}
+function compileDocumentConnectionsMap(target, value, path, sourceName) {
+    if (!Array.isArray(value)) {
+        throw agents_activity_1.ExceptionHelper.generateException(TypeError, errorHelper_1.Errors.InvalidConfigurationValue, undefined, { path, sourceName });
+    }
+    value.forEach((item, index) => {
+        compileDocumentLeafObject(target, item, `${path}.${index}`, sourceName, `connectionsMap.${index}`);
+    });
+}
+function compileDocumentAgentApplication(target, value, path, sourceName) {
+    const application = asDocumentObject(value, path, sourceName);
+    for (const [key, entryValue] of uniqueEntries(application, path, sourceName)) {
+        const entryPath = `${path}.${key}`;
+        if (key.toLowerCase() !== 'userauthorization') {
+            if (suggestConfigurationPath(entryPath)) {
+                throw invalidConfigurationPath(entryPath, sourceName);
+            }
+            continue;
+        }
+        const authorization = asDocumentObject(entryValue, entryPath, sourceName);
+        for (const [authorizationKey, authorizationValue] of uniqueEntries(authorization, entryPath, sourceName)) {
+            const authorizationPath = `${entryPath}.${authorizationKey}`;
+            if (authorizationKey.toLowerCase() === 'handlers') {
+                compileDocumentAuthorizationHandlers(target, authorizationValue, authorizationPath, sourceName);
+            }
+            else if (suggestConfigurationPath(authorizationPath)) {
+                throw invalidConfigurationPath(authorizationPath, sourceName);
+            }
+            else {
+                unsupportedRuntimeField(authorizationPath, sourceName);
+            }
+        }
+    }
+}
+function compileDocumentAuthorizationHandlers(target, value, path, sourceName) {
+    const handlers = asDocumentObject(value, path, sourceName);
+    for (const [id, definitionValue] of uniqueEntries(handlers, path, sourceName)) {
+        validateDynamicSegment(id, `${path}.${id}`, sourceName);
+        const definition = asDocumentObject(definitionValue, `${path}.${id}`, sourceName);
+        ensureAuthorizationHandler(target, id);
+        let settingsFound = false;
+        for (const [key, entryValue] of uniqueEntries(definition, `${path}.${id}`, sourceName)) {
+            const entryPath = `${path}.${id}.${key}`;
+            if (key.toLowerCase() === 'settings') {
+                settingsFound = true;
+                compileDocumentLeafObject(target, entryValue, entryPath, sourceName, `agentApplication.userAuthorization.handlers.${id}.settings`);
+            }
+            else if (key.toLowerCase() === 'assembly' || key.toLowerCase() === 'type') {
+                unsupportedRuntimeField(entryPath, sourceName);
+            }
+            else {
+                throw invalidConfigurationPath(entryPath, sourceName);
+            }
+        }
+        if (!settingsFound) {
+            throw agents_activity_1.ExceptionHelper.generateException(TypeError, errorHelper_1.Errors.InvalidConfigurationValue, undefined, {
+                path: `${path}.${id}.settings`,
+                sourceName
+            });
+        }
+    }
+}
+function compileDocumentLeafObject(target, value, path, sourceName, canonicalPrefix) {
+    var _a, _b;
+    const record = asDocumentObject(value, path, sourceName);
+    const normalizedProperties = new Set();
+    for (const [key, entryValue] of uniqueEntries(record, path, sourceName)) {
+        const lookup = key.toLowerCase();
+        if (canonicalPrefix.startsWith('connections.') && dotNetOnlyConnectionSettings.has(lookup)) {
+            unsupportedRuntimeField(`${path}.${key}`, sourceName);
+        }
+        if (canonicalPrefix.startsWith('agentApplication.userAuthorization.handlers.') &&
+            dotNetOnlyAuthorizationSettings.has(lookup)) {
+            unsupportedRuntimeField(`${path}.${key}`, sourceName);
+        }
+        const normalizedProperty = canonicalPrefix.startsWith('connections.')
+            ? (_a = authPropertyAliases[lookup]) !== null && _a !== void 0 ? _a : lookup : canonicalPrefix.startsWith('agentApplication.userAuthorization.handlers.')
+            ? (_b = authorizationPropertyAliases[lookup]) !== null && _b !== void 0 ? _b : lookup : lookup;
+        const normalizedLookup = normalizedProperty.toLowerCase();
+        if (normalizedProperties.has(normalizedLookup)) {
+            throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.InvalidConfigurationPath, undefined, {
+                path: `${path}.${key}`,
+                sourceName
+            });
+        }
+        normalizedProperties.add(normalizedLookup);
+        setConfigurationValue(target, `${canonicalPrefix}.${key}`, entryValue, sourceName, 'document');
+    }
+}
+function compileSourceResult(target, result, sourceName) {
+    if (result !== null &&
+        typeof result === 'object' &&
+        !Array.isArray(result) &&
+        !('format' in result) &&
+        Object.values(result).every(value => typeof value === 'string')) {
+        compileCanonicalEntries(target, Object.entries(result), sourceName);
+        return;
+    }
+    if ((result === null || result === void 0 ? void 0 : result.format) === 'canonical' && result.values !== null && typeof result.values === 'object' && !Array.isArray(result.values)) {
+        compileCanonicalEntries(target, Object.entries(result.values), sourceName);
+        return;
+    }
+    if ((result === null || result === void 0 ? void 0 : result.format) === 'document' && result.value !== null && typeof result.value === 'object' && !Array.isArray(result.value)) {
+        compileDocument(target, result.value, sourceName);
+        return;
+    }
+    throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.InvalidConfigurationSourceResult, undefined, { sourceName });
+}
+function compileCanonicalEntries(target, entries, sourceName) {
+    const destinations = new Set();
+    for (const [path, value] of entries) {
+        const destination = normalizeCanonicalDestination(path);
+        if (destinations.has(destination)) {
+            const definition = {
+                ...errorHelper_1.Errors.InvalidConfigurationPath,
+                description: 'Configuration source `{sourceName}` returned duplicate canonical destination `{path}`.'
+            };
+            throw agents_activity_1.ExceptionHelper.generateException(Error, definition, undefined, { path, sourceName });
+        }
+        destinations.add(destination);
+        setConfigurationValue(target, path, value, sourceName, 'canonical');
+    }
+}
+function normalizeCanonicalDestination(path) {
+    var _a;
+    const parts = path.split('.').map(part => part.toLowerCase());
+    if (parts[0] === 'connectionsmap' && /^\d+$/.test((_a = parts[1]) !== null && _a !== void 0 ? _a : '')) {
+        parts[1] = Number.parseInt(parts[1], 10).toString();
+    }
+    return parts.join('.');
+}
+async function loadConfigurationSnapshot(registrations) {
+    const names = new Set();
+    for (const { source, mode } of registrations) {
+        if (!source.name.trim()) {
+            throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.ConfigurationSourceNameRequired);
+        }
+        if (!modes.includes(mode)) {
+            throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.InvalidConfigurationSourceMode, undefined, { sourceName: source.name, mode: String(mode) });
+        }
+        if (names.has(source.name)) {
+            throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.DuplicateConfigurationSource, undefined, { sourceName: source.name });
+        }
+        names.add(source.name);
+    }
+    const settled = await Promise.allSettled(registrations.map(async (registration) => {
+        try {
+            return {
+                ...registration,
+                result: await registration.source.load()
+            };
+        }
+        catch (cause) {
+            throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.ConfigurationSourceLoadFailed, (0, jsonFileConfigurationSource_1.isSafeJsonFileConfigurationError)(cause) ? cause : undefined, { sourceName: registration.source.name });
+        }
+    }));
+    const loaded = settled.map(result => {
+        if (result.status === 'rejected') {
+            throw result.reason;
+        }
+        return result.value;
+    });
+    const mutable = Object.fromEntries(modes.map(mode => [mode, createConfigurationLayer()]));
+    for (const { source, mode, result } of loaded) {
+        compileSourceResult(mutable[mode], result, source.name);
+    }
+    return Object.freeze(Object.fromEntries(modes.map(mode => [mode, freezeConfigurationLayer(mutable[mode])])));
+}
+/**
+ * Loads configuration sources into a new immutable, host-scoped context.
+ *
+ * @param registrations Configuration sources and their explicit resolution modes.
+ * @returns A context that can be shared by consumers belonging to one host.
+ */
+async function createConfigurationContext(registrations) {
+    const snapshot = await loadConfigurationSnapshot(registrations);
+    const context = Object.freeze(instantiateConfigurationContext());
+    contextSnapshots.set(context, snapshot);
+    return context;
+}
+/**
+ * Preloads external configuration sources into an immutable process-level snapshot.
+ *
+ * @remarks
+ * Call this function once, before constructing configuration consumers such as
+ * `CloudAdapter` or `AgentApplication`. Sources in the same mode are applied in
+ * registration order, with later values winning.
+ *
+ * @param registrations Configuration sources and their explicit resolution modes.
+ */
+async function preloadConfigurationSources(registrations) {
+    if (state.kind === 'loading') {
+        throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.ConfigurationPreloadInProgress);
+    }
+    if (state.kind === 'ready') {
+        throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.ConfigurationAlreadyPreloaded);
+    }
+    if (state.kind === 'consumed') {
+        throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.ConfigurationAlreadyConsumed);
+    }
+    state = { kind: 'loading' };
+    try {
+        state = {
+            kind: 'ready',
+            snapshot: await loadConfigurationSnapshot(registrations)
+        };
+    }
+    catch (cause) {
+        state = { kind: 'uninitialized' };
+        throw cause;
+    }
+}
+function getConfigurationSnapshot(context) {
+    if (context) {
+        const snapshot = contextSnapshots.get(context);
+        if (!snapshot) {
+            throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.InvalidConfigurationContext);
+        }
+        return snapshot;
+    }
+    if (state.kind === 'loading') {
+        throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.ConfigurationPreloadInProgress);
+    }
+    if (state.kind === 'uninitialized') {
+        const snapshot = emptySnapshot();
+        state = { kind: 'consumed', snapshot };
+        return snapshot;
+    }
+    if (state.kind === 'ready') {
+        state = { kind: 'consumed', snapshot: state.snapshot };
+        return state.snapshot;
+    }
+    return state.snapshot;
+}
+function resetConfigurationSourcesForTest() {
+    state = { kind: 'uninitialized' };
+}
+//# sourceMappingURL=configuration.js.map