Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
import {
BASE_PRINCIPAL_CONFIG_SECTIONS,
BASE_ONLY_CONFIG_SECTIONS,
BASE_ONLY_CONFIG_PATHS,
DERIVED_CONFIG_PATHS,
DEPLOYMENT_ONLY_CONFIG_PATHS,
INTERFACE_PERMISSION_FIELDS,
RUNTIME_CONFIG_INTERFACE_FIELDS,
PERMISSION_SUB_KEYS,
isProcessMCPServerConfig,
EModelEndpoint,
configSchema,
} from 'librechat-data-provider';
import type { TCustomConfig } from 'librechat-data-provider';
import type {
AdminConfigLayerIgnoreReason,
AdminConfigIgnoredOverride,
AdminConfigIgnoreReason,
AdminConfigLayerIgnored,
AdminConfigMergeRules,
ConfigIssueParams,
TWebSearchKeys,
AppConfig,
Config,
} from '~/types';
import type { ConfigEntryRename, ConfigFieldWrite } from './mutations';
import type { ConfigDerivation, ConfigTouches } from './derive';
import type { ConfigEntryLocation } from './collections';
import type { AzureResolvedGroupField } from './azure';
import {
MERGE_KEY_FOLDS,
ARRAY_MERGE_KEYS,
OVERRIDE_KEY_MAP,
remapOverridePath,
foldConfigMergeKey,
isConfigEntryAt,
readConfigEntryTombstone,
getConfigEntryIdentity,
getConfigArrayMergeKey,
getConfigMergeArrayPath,
} from './collections';
import {
AZURE_RESOLVED_GROUP_FIELDS,
toAzureGroupMapEntry,
completeAzureResolution,
getEmptyAzureResolution,
narrowAzureServedModels,
lacksAzureAssistantModels,
resolveServedAzureGroups,
} from './azure';
import {
getGroupNames,
isVertexConfigured,
createConfigTouches,
recordConfigTouches,
deriveVertexEndpoint,
rederiveMergedConfig,
getDerivedConfigIssues,
WRITE_ONLY_DERIVED_ISSUES,
} from './derive';
import { setConfigFields, toConfigOverrideState, renameConfigEntriesTombstones } from './mutations';
import { parseFieldPath, isDotFreePath, isSegmentPrefix, isKeyedConfigPath } from './paths';
import { isBaseConfigPrincipal, sortByConfigPrecedence } from './precedence';
import { webSearchPairedFields, unbindWebSearchKeys } from './web';
import logger from '~/config/winston';
type AnyObject = { [key: string]: unknown };
/** The parts of a principal's config document the merge reads, whichever store returned it. */
export type ConfigOverrideLayer = Pick<Config, 'principalType' | 'priority' | 'overrides'> & {
principalId: { toString(): string };
tombstones?: readonly unknown[];
/** The document's identity: the last tie-break of merge precedence. */
_id?: { toString(): string } | null;
};
const MAX_MERGE_DEPTH = 10;
const ARRAY_INDEX = /^(?:0|[1-9]\d*)$/;
/** Schemas whose children the path walk cannot see, so the stored value decides their shape. */
const OPAQUE_SCHEMA_TYPES = new Set(['any', 'unknown', 'intersection']);
const MAX_STRIP_PASSES = 16;
const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
/** Filters are a fail-closed security boundary even during mixed-package rollouts. */
const BASE_ONLY_OVERRIDE_SECTIONS = new Set<string>(['filters', ...BASE_ONLY_CONFIG_SECTIONS]);
const BASE_PRINCIPAL_OVERRIDE_SECTIONS = new Set<string>(BASE_PRINCIPAL_CONFIG_SECTIONS);
/** {@link DERIVED_CONFIG_PATHS}, the paths AppService derives and no layer writes, as segments. */
const DERIVED_PATH_SEGMENTS: ReadonlyArray<readonly string[]> = DERIVED_CONFIG_PATHS.map((path) =>
path.split('.'),
);
/** Whether a path (override or AppConfig keys) is a derived path or lies inside one. */
export function isDerivedConfigPath(segments: readonly string[]): boolean {
return DERIVED_PATH_SEGMENTS.some((path) => isSegmentPrefix(path, segments));
}
/**
* A layer's overrides without the values it holds at derived paths (`DERIVED_CONFIG_PATHS`), each
* told to `report` or, without one, warned about; the same object when it holds none.
*/
function withoutDerivedPaths(
overrides: AnyObject,
principal: string,
report?: (segments: readonly string[]) => void,
): AnyObject {
let result = overrides;
for (const path of DERIVED_PATH_SEGMENTS) {
if (getPath(result, [...path]) === undefined) {
continue;
}
if (report) {
report(path);
} else {
logger.warn(
`[mergeConfigOverrides] Ignoring ${path.join('.')} for ${principal}: it is derived from librechat.yaml, not written`,
);
}
result = omitPath(result, [...path]) as AnyObject;
}
return result;
}
/** A field only librechat.yaml sets, as YAML key segments, and why the merge keeps its value. */
export interface YamlHeldPath {
segments: readonly string[];
reason: Extract<AdminConfigIgnoreReason, 'base_only_path' | 'deployment_only_path'>;
}
/**
* Every field the merge sets back to librechat.yaml's value whatever a layer stores or
* tombstones there: `BASE_ONLY_CONFIG_PATHS`, which per-request code reads from the merged
* config, and `DEPLOYMENT_ONLY_CONFIG_PATHS`, read at startup or from librechat.yaml itself.
*/
export const YAML_HELD_PATHS: readonly YamlHeldPath[] = [
...BASE_ONLY_CONFIG_PATHS.map(
(path): YamlHeldPath => ({ segments: path.split('.'), reason: 'base_only_path' }),
),
...Object.keys(DEPLOYMENT_ONLY_CONFIG_PATHS).map(
(path): YamlHeldPath => ({ segments: path.split('.'), reason: 'deployment_only_path' }),
),
];
/** Told about each stored override or tombstone of `layer` that a fold leaves out. */
type IgnoredSink = (layer: ConfigOverrideLayer, entry: AdminConfigIgnoredOverride) => void;
/** {@link IgnoredSink} bound to the layer being folded. */
type LayerIgnoredSink = (entry: AdminConfigIgnoredOverride) => void;
function toIgnored(
segments: readonly string[],
reason: AdminConfigIgnoreReason,
kind: AdminConfigIgnoredOverride['kind'],
): AdminConfigIgnoredOverride {
return { path: segments.join('.'), segments: [...segments], reason, kind };
}
/** Where the resolved Azure config sits in an AppConfig. */
const AZURE_CONFIG_PATH = `endpoints.${EModelEndpoint.azureOpenAI}`;
/** The resolved Azure fields a layer's `groups` replace, as AppConfig paths. */
const AZURE_RESOLVED_PATHS: readonly string[] = AZURE_RESOLVED_GROUP_FIELDS.map(
(field) => `${AZURE_CONFIG_PATH}.${field}`,
);
/** Azure `groups`, as a librechat.yaml path (the same in an AppConfig). */
const AZURE_GROUPS_PATH = `${AZURE_CONFIG_PATH}.groups`;
/**
* The paths a tombstone removes: its own, and for Azure `groups`, where the merge resolves them
* (`resolvesAzureGroups`), every field they resolve to (`AZURE_RESOLVED_PATHS`), which the Azure
* clients and model lists read in their place.
*/
function getTombstoneRemovals(path: string, resolvesAzureGroups: boolean): readonly string[] {
return resolvesAzureGroups && path === AZURE_GROUPS_PATH
? [path, ...AZURE_RESOLVED_PATHS]
: [path];
}
/**
* `merged` with its Azure groups resolved to none, when it has an Azure endpoint: every field the
* groups resolve to stays, empty, so the Azure clients and model lists serve no group. Their
* absence would read differently: the model lists fall back to the environment's default Azure
* models, which the Azure client, configured by librechat.yaml, cannot map to a group.
*/
function withoutAzureGroups<T extends AnyObject>(merged: T): T {
const segments = AZURE_CONFIG_PATH.split('.');
const azure = getPath(merged, segments);
if (!isPlainObject(azure)) {
return merged;
}
return setPath(merged, segments, { ...azure, ...getEmptyAzureResolution() }) as T;
}
/**
* Object-valued paths an override replaces whole instead of merging into. A theme
* definition is one coherent value: merging two would keep the base theme's modes,
* brands and tokens under the override's name. Uses AppConfig key names.
*/
const ATOMIC_MERGE_PATHS = new Set<string>(['interfaceConfig.theme']);
/** AppConfig key → the override (YAML) section merged into it, the inverse of `OVERRIDE_KEY_MAP`. */
const OVERRIDE_SECTION_BY_APP_KEY = new Map<string, string>(
Object.entries(OVERRIDE_KEY_MAP).flatMap(([section, appKey]) =>
appKey ? [[appKey, section]] : [],
),
);
function toOverridePath(appConfigPath: string): string {
const [first, ...rest] = appConfigPath.split('.');
return [OVERRIDE_SECTION_BY_APP_KEY.get(first) ?? first, ...rest].join('.');
}
/** The merge rules in override (YAML) key names, for clients that plan writes the way they merge. */
export function getConfigMergeRules(): AdminConfigMergeRules {
return {
arrayMergeKeys: Object.fromEntries(
Object.entries(ARRAY_MERGE_KEYS).map(([path, key]) => [toOverridePath(path), key]),
),
atomicMergePaths: [...ATOMIC_MERGE_PATHS].map(toOverridePath),
overrideKeyMap: Object.fromEntries(
[...OVERRIDE_SECTION_BY_APP_KEY].map(([appKey, section]) => [section, appKey]),
),
derivedPaths: [...DERIVED_CONFIG_PATHS],
};
}
function isSafePath(path: string): boolean {
const segments = path.split('.');
if (
path.length === 0 ||
path.startsWith('.') ||
path.endsWith('.') ||
path.includes('..') ||
segments.some((segment) => segment.length === 0 || UNSAFE_KEYS.has(segment))
) {
return false;
}
return true;
}
/**
* `combineFoldedConfigItems` for the merged-by-key array at an override (YAML) path: stored
* items naming one entry in two spellings, combined as the runtime merge combines them.
*/
export function combineFoldedConfigEntries(
segments: readonly string[],
items: unknown[],
): unknown[] {
const arrayPath = getConfigMergeArrayPath(segments);
return arrayPath === undefined ? items : combineFoldedConfigItems(arrayPath, items);
}
/**
* `items` merged over `below` as the merge merges the merged-by-key array at an override (YAML)
* path (`endpoints.custom` by `name`, `endpoints.azureOpenAI.groups` by `group`): matched items
* deep-merged, others kept, new ones appended. At any other path, or over no array, `items`.
*/
export function mergeConfigEntries(
segments: readonly string[],
below: unknown,
items: readonly unknown[],
): unknown[] {
const arrayPath = getConfigMergeArrayPath(segments);
if (arrayPath === undefined || !Array.isArray(below)) {
return [...items];
}
return mergeArrayByKey(
below,
items as AnyObject[],
ARRAY_MERGE_KEYS[arrayPath],
segments.length - 1,
arrayPath,
);
}
function isBaseOnlyOverridePath(path: string): boolean {
return BASE_ONLY_OVERRIDE_SECTIONS.has(path.split('.')[0]);
}
/**
* Removes a path from `target`, stopping at arrays. A keyed path (`endpoints.custom["Name"]`)
* reaches into an array merged by key instead: it removes every entry whose key has the same
* identity (`Ollama` and `ollama` alike), or with a path inside the entry, that path from each
* of them. Any other path holding `["` is split on its dots, as before keyed paths existed, so a
* stored tombstone of a record key such as an MCP server named `a["b"]` keeps hiding it.
*/
function deletePath<T extends AnyObject>(target: T, path: string): T {
const entry = isKeyedConfigPath(path) ? readConfigEntryTombstone(path) : null;
if (entry) {
return deleteEntryPath(target, entry);
}
if (!isSafePath(path)) {
return target;
}
const segments = path.split('.');
const result = { ...target } as AnyObject;
let cursor: AnyObject = result;
for (let index = 0; index < segments.length - 1; index++) {
const segment = segments[index];
const value = cursor[segment];
if (value == null || typeof value !== 'object' || Array.isArray(value)) {
return result as T;
}
const cloned = { ...(value as AnyObject) };
cursor[segment] = cloned;
cursor = cloned;
}
delete cursor[segments[segments.length - 1]];
return result as T;
}
function deleteEntryPath<T extends AnyObject>(target: T, location: ConfigEntryLocation): T {
const segments = [...location.segments];
const items = getPath(target, segments);
if (!Array.isArray(items) || !items.some((item) => isConfigEntryAt(location, item))) {
return target;
}
const inside = location.entry.rest.join('.');
const next =
inside === ''
? items.filter((item) => !isConfigEntryAt(location, item))
: items.map((item) =>
isConfigEntryAt(location, item) ? deletePath(item as AnyObject, inside) : item,
);
return setPath(target, segments, next) as T;
}
function deleteConfigPath<T extends AnyObject>(target: T, path: string): T {
const [section, serverName] = path.split('.');
if (section !== 'mcpConfig') {
return deletePath(target, path);
}
const mcpConfig = target.mcpConfig;
if (mcpConfig == null || typeof mcpConfig !== 'object' || Array.isArray(mcpConfig)) {
return deletePath(target, path);
}
const servers = mcpConfig as AnyObject;
if (serverName != null) {
return isProcessMCPServerConfig(servers[serverName]) ? target : deletePath(target, path);
}
const processServers = Object.fromEntries(
Object.entries(servers).filter(([, serverConfig]) => isProcessMCPServerConfig(serverConfig)),
);
if (Object.keys(processServers).length === 0) {
return deletePath(target, path);
}
return { ...target, mcpConfig: processServers } as T;
}
/** The identity an item of the merged-by-key array at `arrayPath` matches on. */
function getMergeKey(item: AnyObject, keyField: string, arrayPath: string): unknown {
const key = item[keyField];
return typeof key === 'string' ? foldConfigMergeKey(arrayPath, key) : key;
}
/**
* Combines the items of a stored merged-by-key array that name one item in more than one
* spelling of its folded key (`Ollama` and `ollama`): merged in document order, later fields
* winning, at the first one's position. A document stored before names were folded kept such
* items apart, and the runtime took requests' `baseURL` and key from the first while serving
* the later one's metadata, so the combined item keeps what each contributed instead of losing
* the earlier one as a duplicate. A key repeated in only one spelling is left as is (the last
* item applies). Returns the same array when nothing combines.
*/
export function combineFoldedConfigItems(arrayPath: string, items: unknown[]): unknown[] {
const keyField = ARRAY_MERGE_KEYS[arrayPath];
if (!keyField || !hasOwn(MERGE_KEY_FOLDS, arrayPath)) {
return items;
}
const groups = new Map<string, { spellings: Set<string>; indexes: number[] }>();
items.forEach((item, index) => {
const key = isPlainObject(item) ? item[keyField] : undefined;
if (typeof key !== 'string' || key === '') {
return;
}
const identity = MERGE_KEY_FOLDS[arrayPath](key);
const group = groups.get(identity) ?? { spellings: new Set<string>(), indexes: [] };
group.spellings.add(key);
group.indexes.push(index);
groups.set(identity, group);
});
const depth = arrayPath.split('.').length;
const combined = new Map<number, AnyObject>();
const absorbed = new Set<number>();
for (const { spellings, indexes } of groups.values()) {
if (spellings.size < 2) {
continue;
}
const [first, ...rest] = indexes;
const merged = rest.reduce<AnyObject>(
(item, index) => deepMerge(item, items[index] as AnyObject, depth, arrayPath),
items[first] as AnyObject,
);
combined.set(first, merged);
rest.forEach((index) => absorbed.add(index));
}
if (combined.size === 0) {
return items;
}
return items.flatMap((item, index) => (absorbed.has(index) ? [] : [combined.get(index) ?? item]));
}
/** `combineFoldedConfigItems` over every folded array of a stored overrides document. */
function combineStoredFoldedItems(overrides: unknown, principal: string, quiet = false): unknown {
let result = overrides;
for (const arrayPath of Object.keys(MERGE_KEY_FOLDS)) {
const segments = arrayPath.split('.');
const items = getPath(result, segments);
if (!Array.isArray(items)) {
continue;
}
const combined = combineFoldedConfigItems(arrayPath, items);
if (combined === items) {
continue;
}
if (!quiet) {
logger.warn(
`[mergeConfigOverrides] Combining "${arrayPath}" items that name one entry in different spellings for ${principal}; a write of this list must name each entry once`,
);
}
result = setPath(result, segments, combined);
}
return result;
}
function mergeArrayByKey(
target: AnyObject[],
source: AnyObject[],
keyField: string,
depth: number,
path: string,
): AnyObject[] {
const sourceByKey = new Map<unknown, AnyObject>();
for (const item of source) {
if (item != null && typeof item === 'object') {
const key = getMergeKey(item, keyField, path);
// Source items without a key value are skipped: no stable identity
// for matching or appending. (Keyless target items are preserved as-is below.)
if (key != null) {
sourceByKey.set(key, item);
}
}
}
const result: AnyObject[] = [];
const seen = new Set<unknown>();
// Pass the array container path (not a per-element path) so item
// properties build paths like 'endpoints.custom.baseURL' for any
// nested ARRAY_MERGE_KEYS lookups. A matched item keeps the spelling of
// its key the layer beneath gave it: an override `ollama` modifies the
// YAML `Ollama`, which stays the entry's name.
for (const item of target) {
if (item != null && typeof item === 'object') {
const key = getMergeKey(item, keyField, path);
const override = key != null ? sourceByKey.get(key) : undefined;
if (override) {
result.push({ ...deepMerge(item, override, depth + 1, path), [keyField]: item[keyField] });
seen.add(key);
} else {
result.push({ ...item });
}
} else {
result.push(item);
}
}
for (const key of sourceByKey.keys()) {
if (!seen.has(key)) {
result.push(deepMerge({} as AnyObject, sourceByKey.get(key)!, depth + 1, path));
}
}
return result;
}
function deepMerge<T extends AnyObject>(target: T, source: AnyObject, depth = 0, path = ''): T {
const result = { ...target } as AnyObject;
for (const key of Object.keys(source)) {
if (UNSAFE_KEYS.has(key)) {
continue;
}
const currentPath = path ? `${path}.${key}` : key;
const sourceVal = source[key];
const targetVal = result[key];
if (
depth < MAX_MERGE_DEPTH &&
!ATOMIC_MERGE_PATHS.has(currentPath) &&
sourceVal != null &&
typeof sourceVal === 'object' &&
!Array.isArray(sourceVal) &&
targetVal != null &&
typeof targetVal === 'object' &&
!Array.isArray(targetVal)
) {
result[key] = deepMerge(
targetVal as AnyObject,
sourceVal as AnyObject,
depth + 1,
currentPath,
);
} else if (
depth < MAX_MERGE_DEPTH &&
Array.isArray(sourceVal) &&
Array.isArray(targetVal) &&
ARRAY_MERGE_KEYS[currentPath]
) {
result[key] = mergeArrayByKey(
targetVal as AnyObject[],
sourceVal as AnyObject[],
ARRAY_MERGE_KEYS[currentPath],
depth,
currentPath,
);
} else if (
typeof sourceVal === 'boolean' &&
targetVal != null &&
typeof targetVal === 'object' &&
!Array.isArray(targetVal) &&
RUNTIME_CONFIG_INTERFACE_FIELDS.has(key)
) {
// A runtime-config interface field (e.g. schedules) toggled by a boolean
// override is a runtime enable/disable, not a replacement of its config. Fold
// the boolean into the `use` flag so inherited object-form limits (maxPerUser,
// minIntervalMinutes, ...) survive instead of collapsing to global defaults.
result[key] = { ...(targetVal as AnyObject), use: sourceVal };
} else if (
typeof targetVal === 'boolean' &&
sourceVal != null &&
typeof sourceVal === 'object' &&
!Array.isArray(sourceVal) &&
RUNTIME_CONFIG_INTERFACE_FIELDS.has(key)
) {
// Symmetric case: an OBJECT override (e.g. tuning maxPerUser) on top of a
// BOOLEAN base must inherit the base's enable state unless it sets `use`
// explicitly — otherwise setting a limit on a globally-disabled feature
// (`schedules: false`) would silently re-enable it.
result[key] = { use: targetVal, ...(sourceVal as AnyObject) };
} else {
result[key] = sourceVal;
}
}
return result as T;
}
export type ConfigOverrideIssue = {
/** Dot-path of the override node the issue is attributed to, in YAML (`TCustomConfig`) keys. */
path: string;
/** The same location as keys, unambiguous when a record key itself contains a dot. */
segments: string[];
/**
* A stable, machine-readable reason: a zod issue code (`invalid_type`, `custom`, ...),
* `unknown_section`, `missing_merge_key`, `duplicate_merge_key`, `indexed_merge_key_write`,
* `union_dropped_key`, `dotted_key`, or `invalid_document`. Schema messages are not carried
* because they can echo the submitted values.
*/
code: string;
/**
* What the schema expected, for a zod issue attributed to the exact node that failed
* (`getConfigIssueParams`); absent when the issue is reported on an ancestor the override
* supplies, where the bound would describe a node the override did not write.
*/
params?: ConfigIssueParams;
};
type IssuePath = Array<string | number>;
function isPlainObject(value: unknown): value is AnyObject {
return value != null && typeof value === 'object' && !Array.isArray(value);
}
function hasOwn(target: object, key: string): boolean {
return Object.prototype.hasOwnProperty.call(target, key);
}
/**
* Whether `key` is a top-level section an override may hold: one `configSchema` defines.
* Anything else names runtime state the merge would otherwise reach (`paths`, the raw-YAML
* `config`, the AppService aliases `interfaceConfig`/`mcpConfig`/`turnstileConfig`), so it is
* rejected on write and ignored at merge. Unknown keys inside a known section stay accepted.
*/
export function isAcceptedOverrideSection(key: string): boolean {
return hasOwn(configSchema.shape, key);
}
function toIssue(
segments: string[],
code: string,
params?: ConfigIssueParams,
): ConfigOverrideIssue {
return params
? { path: segments.join('.'), segments, code, params }
: { path: segments.join('.'), segments, code };
}
type IssuePrimitive = string | number | boolean | null;
const CUSTOM_REASON = /^[a-z][a-z0-9_]*$/;
function isIssuePrimitive(value: unknown): value is IssuePrimitive {
return (
value === null ||
typeof value === 'string' ||
typeof value === 'boolean' ||
(typeof value === 'number' && Number.isFinite(value))
);
}
/** A numeric bound as JSON can carry it: a date as epoch milliseconds, never a bigint. */
function toIssueNumber(value: unknown): number | undefined {
if (value instanceof Date) {
const time = value.getTime();
return Number.isFinite(time) ? time : undefined;
}
return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
}
/** The bound fields of a `too_small` or `too_big` issue, always with `inclusive`, `exact`, `type`. */
function getBoundParams(
bound: 'minimum' | 'maximum',
value: unknown,
issue: { inclusive?: boolean; exact?: boolean; origin: string },
): ConfigIssueParams {
const number = toIssueNumber(value);
return {
...(number !== undefined && { [bound]: number }),
inclusive: issue.inclusive ?? false,
exact: issue.exact ?? false,
type: issue.origin,
};
}
/** Expected-type names that the reported contract spells differently from zod. */
const EXPECTED_TYPE_NAMES: Record<string, string> = {
int: 'integer',
record: 'object',
tuple: 'array',
};
/** String-format names that the reported contract spells as the check that failed. */
const STRING_FORMAT_NAMES: Record<string, string> = {
starts_with: 'startsWith',
ends_with: 'endsWith',
};
/** The kind of the submitted value, by name only, so the value itself is never reported. */
function getReceivedType(input: unknown, expected: string): string {
if (input === null) {
return 'null';
}
if (Array.isArray(input)) {
return 'array';
}
if (input instanceof Date) {
return 'date';
}
if (input instanceof Map) {
return 'map';
}
if (input instanceof Set) {
return 'set';
}
if (typeof input !== 'number') {
return typeof input;
}
if (Number.isNaN(input)) {
return 'nan';
}
return expected === 'int' && !Number.isInteger(input) ? 'float' : 'number';
}
/** Whether a union issue is the discriminator mismatch of a discriminated union. */
function isDiscriminatorIssue(issue: SchemaIssue): issue is SchemaIssue & { options: unknown[] } {
return (
issue.code === 'invalid_union' &&
issue.discriminator != null &&
Array.isArray((issue as { options?: unknown }).options)
);
}
/**
* The stable code an issue is reported under. Codes keep the names the override contract was
* published with, so a zod release that renames its issue codes does not change the response.
*/
export function getConfigIssueCode(issue: SchemaIssue): string {
if (issue.code === 'invalid_value') {
return issue.values.length === 1 ? 'invalid_literal' : 'invalid_enum_value';
}
if (issue.code === 'invalid_format') {
return 'invalid_string';
}
return isDiscriminatorIssue(issue) ? 'invalid_union_discriminator' : issue.code;
}
/**
* The parts of a zod issue that describe the schema rather than the submitted value, by an
* allowlist per issue code: expected types and literals, accepted options, numeric bounds, the
* failed string check, a multiple, and a refinement's stable `reason`. A value the client sent
* is never copied (only the name of its type, no literal or enum value, no message), so the
* result is safe to return. `undefined` when the issue carries none of these.
*/
export function getConfigIssueParams(issue: SchemaIssue): ConfigIssueParams | undefined {
let params: ConfigIssueParams | undefined;
switch (issue.code) {
case 'invalid_type':
params = {
expected: EXPECTED_TYPE_NAMES[issue.expected] ?? issue.expected,
...('input' in issue && { received: getReceivedType(issue.input, issue.expected) }),
};
break;
case 'invalid_value': {
const [expected] = issue.values;
if (issue.values.length > 1) {
params = { options: issue.values.filter(isIssuePrimitive) };
} else {
params = isIssuePrimitive(expected) ? { expected } : undefined;
}
break;
}
case 'invalid_union':
params = isDiscriminatorIssue(issue)
? { options: issue.options.filter(isIssuePrimitive) }
: undefined;
break;
case 'too_small':
params = getBoundParams('minimum', issue.minimum, issue);
break;
case 'too_big':
params = getBoundParams('maximum', issue.maximum, issue);
break;
case 'invalid_format':
params = { validation: STRING_FORMAT_NAMES[issue.format] ?? issue.format };
break;
case 'not_multiple_of': {
const multipleOf = toIssueNumber(issue.divisor);
params = multipleOf !== undefined ? { multipleOf } : undefined;
break;
}
case 'custom': {
const reason: unknown = issue.params?.reason;
params = typeof reason === 'string' && CUSTOM_REASON.test(reason) ? { reason } : undefined;
break;
}
default:
params = undefined;
}
return params && Object.keys(params).length > 0 ? params : undefined;
}
/**
* The override item an issue path segment names: by the merge key for merged-by-key arrays
* (the merged index differs from the override's; the last item with a key is the one merged), by index, or by `id` for refinements that
* address an item by its identifier.
*/
function findItemIndex(
node: unknown[],
key: string,
keyField: string | undefined,
mergedItem: unknown,
arrayPath: string,
): number {
if (keyField) {
if (!isPlainObject(mergedItem)) {
return -1;
}
const mergedKey = getMergeKey(mergedItem, keyField, arrayPath);
for (let index = node.length - 1; index >= 0; index--) {
const item = node[index];
if (isPlainObject(item) && getMergeKey(item, keyField, arrayPath) === mergedKey) {
return index;
}
}
return -1;
}
if (/^\d+$/.test(key)) {
return Number(key);
}
return node.findIndex((item) => isPlainObject(item) && item.id === key);
}
/**
* The override node an issue in the merged config belongs to: the deepest node the
* overrides supply on the issue's path. Items of merged-by-key arrays are matched by their
* key, since the merged index differs from the override's. `undefined` means the overrides
* did not supply anything on the path, so the issue is the base's own.
*/
function attributeIssue(
overrides: AnyObject,
merged: AnyObject,
issuePath: IssuePath,
): string[] | undefined {
const segments: string[] = [];
let node: unknown = overrides;
let mergedNode: unknown = merged;
for (const part of issuePath) {
const key = String(part);
if (Array.isArray(node)) {
const arrayPath = segments.join('.');
const keyField = hasOwn(ARRAY_MERGE_KEYS, arrayPath)
? ARRAY_MERGE_KEYS[arrayPath]
: undefined;
const mergedItem = Array.isArray(mergedNode) ? mergedNode[Number(key)] : undefined;
const index = findItemIndex(node, key, keyField, mergedItem, arrayPath);
if (keyField && index < 0) {
return undefined;
}
if (!Number.isInteger(index) || index < 0 || index >= node.length) {
break;
}
segments.push(String(index));
node = node[index];
mergedNode = Array.isArray(mergedNode)
? mergedNode[keyField ? Number(key) : index]
: undefined;
continue;
}
if (!isPlainObject(node) || !hasOwn(node, key)) {
break;
}
segments.push(key);
node = node[key];
mergedNode = isPlainObject(mergedNode) ? mergedNode[key] : undefined;
}
return segments.length > 0 ? segments : undefined;
}
/**
* Whether the override node at `segments` is final: at or inside an array the merge replaces
* (any array not merged by key), so no other layer can supply what it leaves out.
*/
function isReplacedArrayNode(overrides: AnyObject, segments: string[]): boolean {
let node: unknown = overrides;
for (let index = 0; index < segments.length; index++) {
node = Array.isArray(node)
? node[Number(segments[index])]
: (node as AnyObject)[segments[index]];
const path = segments.slice(0, index + 1).join('.');
if (Array.isArray(node) && !hasOwn(ARRAY_MERGE_KEYS, path)) {
return true;
}
}
return false;
}
/**
* Items of a merged-by-key array must be objects with their own key: the merge drops any
* other item (or keeps it as is when nothing lies beneath the array). A repeated key is
* reported on the earlier items: the last one is what the merge keeps.
*/
function getMergeKeyIssues(overrides: AnyObject): ConfigOverrideIssue[] {
return Object.entries(ARRAY_MERGE_KEYS).flatMap(([arrayPath, keyField]) => {
const segments = arrayPath.split('.');
let node: unknown = overrides;
for (const segment of segments) {
node = isPlainObject(node) && hasOwn(node, segment) ? node[segment] : undefined;
}
if (!Array.isArray(node)) {
return [];
}
const lastIndex = new Map<unknown, number>();
node.forEach(
(item, index) =>
isPlainObject(item) && lastIndex.set(getMergeKey(item, keyField, arrayPath), index),
);
return node.flatMap((item, index) => {
if (!isPlainObject(item) || typeof item[keyField] !== 'string' || item[keyField] === '') {
return [toIssue([...segments, String(index)], 'missing_merge_key')];
}
return lastIndex.get(getMergeKey(item, keyField, arrayPath)) === index
? []
: [toIssue([...segments, String(index)], 'duplicate_merge_key')];
});
});
}
type SchemaIssue = NonNullable<
ReturnType<typeof configSchema.safeParse>['error']
>['issues'][number];
/** A zod issue path as an override path; config keys are never symbols. */
function toIssuePath(path: readonly PropertyKey[]): IssuePath {
return path.filter((segment): segment is string | number => typeof segment !== 'symbol');
}
/**
* Unwrap record-key failures and select the closest union branch by issue count, then depth.
* Nested issues have relative paths, so each wrapper's path is prepended before recursing.
*/
function expandSchemaIssues(issues: SchemaIssue[], depth = 0): SchemaIssue[] {
return issues.flatMap((issue) => {
if (depth >= MAX_MERGE_DEPTH) {
return [issue];
}
if (issue.code === 'invalid_key') {
return expandSchemaIssues(
issue.issues.map((keyIssue) => ({
...keyIssue,
path: [...issue.path, ...keyIssue.path],
})),
depth + 1,
);
}
if (issue.code !== 'invalid_union') {
return [issue];
}
const branches = (issue.errors as SchemaIssue[][]).map((branch) =>
branch.map((branchIssue) => ({ ...branchIssue, path: [...issue.path, ...branchIssue.path] })),
);
const closest = branches.reduce<SchemaIssue[] | undefined>((best, branch) => {
if (!best || branch.length < best.length) {
return branch;
}
const depthOf = (list: SchemaIssue[]) => Math.max(0, ...list.map((i) => i.path.length));
return branch.length === best.length && depthOf(branch) > depthOf(best) ? branch : best;
}, undefined);
return closest && closest.length > 0 ? expandSchemaIssues(closest, depth + 1) : [issue];
});
}
/** The parts of a zod schema the shape walk reads, without depending on zod. */
type SchemaNode = {
def: {
type: string;
innerType?: SchemaNode;
in?: SchemaNode;
out?: SchemaNode;
getter?: () => SchemaNode;
element?: SchemaNode;
valueType?: SchemaNode;
left?: SchemaNode;
right?: SchemaNode;
options?: SchemaNode[];
};
shape?: Record<string, SchemaNode>;
safeParse: (value: unknown) => { success: boolean };
};
/** The side of a pipe that validates the value: the input, unless it only preprocesses. */
function getPipeSchema(node: SchemaNode): SchemaNode | undefined {
const { in: input, out } = node.def;
return input?.def.type === 'transform' ? out : input;
}
/** The schema beneath optional, nullable, default, transform, preprocess and lazy wrappers. */
function unwrapSchema(schema: SchemaNode): SchemaNode {
let node = schema;
for (let depth = 0; depth < MAX_MERGE_DEPTH; depth++) {
const inner =
node.def.innerType ??
(node.def.type === 'pipe' ? getPipeSchema(node) : undefined) ??
node.def.getter?.();
if (!inner) {
break;
}
node = inner;
}
return node;
}
/** The schema one segment below `node`, through objects, records, arrays and union options. */
function getChildSchema(node: SchemaNode, segment: string, depth = 0): SchemaNode | undefined {
const inner = unwrapSchema(node);
const { type } = inner.def;
if (type === 'object' && inner.shape) {
return hasOwn(inner.shape, segment) ? inner.shape[segment] : undefined;
}
if (type === 'record') {
return inner.def.valueType;
}
if (type === 'array') {
return ARRAY_INDEX.test(segment) ? inner.def.element : undefined;
}
if (type === 'union' && inner.def.options && depth < MAX_MERGE_DEPTH) {
for (const option of inner.def.options.values()) {
const child = getChildSchema(option, segment, depth + 1);
if (child) {
return child;
}
}
}
return undefined;
}
/** Whether {@link getChildSchema} reaches `segment` below `node` through an array. */
function isArrayStep(node: SchemaNode, segment: string, depth = 0): boolean {
const inner = unwrapSchema(node);
const { type } = inner.def;
if (type === 'array') {
return true;
}
if (type !== 'union' || !inner.def.options || depth >= MAX_MERGE_DEPTH) {
return false;
}
for (const option of inner.def.options.values()) {
if (getChildSchema(option, segment, depth + 1)) {
return isArrayStep(option, segment, depth + 1);
}
}
return false;
}
/**
* The `configSchema` node an override (YAML) path names (`undefined` when the schema does not
* define it), and whether the path continues past an array on the way. Below a field of a
* known section that the schema does not define (a key it does not know, or what an
* intersection or `any` holds), the stored value decides the shape, so an index segment there
* is taken to name an array element. Only steps from index `from` of `segments` on count toward
* `throughArray`, so a path inside an array entry can be judged on the entry's own arrays.
*/
function resolveConfigSchemaPath(
segments: readonly string[],
from = 0,
): {
node?: SchemaNode;
throughArray: boolean;
} {
const [section, ...rest] = segments;
const shape = configSchema.shape as unknown as Record<string, SchemaNode>;
if (section === undefined || !hasOwn(shape, section)) {
return { throughArray: false };
}
let node: SchemaNode | undefined = shape[section];
let throughArray = false;
for (let index = 0; index < rest.length; index++) {
const segment = rest[index];
/** `from` counts in `segments`, where `rest[index]` is `segments[index + 1]`. */
const counts = index + 1 >= from;
if (!node || OPAQUE_SCHEMA_TYPES.has(unwrapSchema(node).def.type)) {
node = undefined;
throughArray = throughArray || (counts && ARRAY_INDEX.test(segment));
continue;
}
throughArray = throughArray || (counts && isArrayStep(node, segment));
node = getChildSchema(node, segment);
}
return { node, throughArray };
}
/**
* Whether an override (YAML) path names a record in `configSchema`: an object whose keys are
* names the operator chooses (`mcpServers`, a `headers` map, `inferenceProfiles`), so one key
* can be renamed to another without changing what the value means. Fixed-shape objects are not
* records.
*/
export function isConfigRecordPath(segments: readonly string[]): boolean {
const { node } = resolveConfigSchemaPath(segments);
return node != null && unwrapSchema(node).def.type === 'record';
}
/**
* Whether an override (YAML) path continues past an array of `configSchema`, or may: it names
* an element of the array or a path inside one, or has an index segment below a field of a
* known section the schema does not define. A tombstone there hides nothing, because the merge
* removes inherited values from objects only (a whole array can be hidden).
*/
export function isConfigArrayItemPath(segments: readonly string[]): boolean {
return resolveConfigSchemaPath(segments).throughArray;
}
/**
* {@link isConfigArrayItemPath} for a path inside an entry of the merged-by-key array at
* `segments`: whether `rest` continues past an array of the entry's own schema (`models.default.0`),
* which a keyed tombstone cannot hide part of either.
*/
export function isConfigEntryArrayItemPath(
segments: readonly string[],
rest: readonly string[],
): boolean {
return resolveConfigSchemaPath([...segments, '0', ...rest], segments.length + 1).throughArray;
}
/**
* The combined fixed shape of an intersection of objects (`a.and(b)`), or `undefined` when a
* side is not an object, so nothing is judged on a shape the walk cannot see whole.
*/
function getIntersectionShape(node: SchemaNode, depth = 0): Record<string, SchemaNode> | undefined {
if (depth >= MAX_MERGE_DEPTH || !node.def.left || !node.def.right) {
return undefined;
}
const [left, right] = [node.def.left, node.def.right].map((side) => {
const inner = unwrapSchema(side);
return inner.def.type === 'intersection' ? getIntersectionShape(inner, depth + 1) : inner.shape;
});
return left && right ? { ...left, ...right } : undefined;
}
/** Whether a schema accepts arbitrary keys at this level (a record, or a union with one). */
function isRecordSchema(schema: SchemaNode): boolean {
const node = unwrapSchema(schema);
const { type, options } = node.def;
if (type === 'record') {
return true;
}
return type === 'union' && options != null && [...options.values()].some(isRecordSchema);
}
type ShapeIssue = { code: 'union_dropped_key' | 'dotted_key'; path: IssuePath };
function toDottedKeyIssues(value: AnyObject, path: IssuePath): ShapeIssue[] {
return Object.keys(value)
.filter((key) => key.includes('.'))
.map((key): ShapeIssue => ({ code: 'dotted_key', path: [...path, key] }));
}
/**
* The walk of an object with a fixed shape: a key holding a dot can only be a mistaken
* path (`{ 'webSearch.serperApiKey': ... }`), which the schema strips as unknown and the secret
* registry never sees, so it is reported instead of stored as an inert literal key.
*/
function findObjectShapeIssues(
shape: Record<string, SchemaNode>,
value: AnyObject,
path: IssuePath,
depth: number,
): ShapeIssue[] {
return Object.keys(value).flatMap((key): ShapeIssue[] => {
if (key.includes('.')) {
return [{ code: 'dotted_key', path: [...path, key] }];
}
return hasOwn(shape, key)
? findShapeIssues(shape[key], value[key], [...path, key], depth + 1)
: [];
});
}
/**
* What a schema walk finds that parsing does not report:
* - `union_dropped_key`: an object parses with the first union option that accepts it, and
* that option strips keys it does not define, so a key another option defines (and would
* type-check) is kept raw in the stored override but never validated.
* - `dotted_key`: a key holding a dot where the schema has a fixed shape. Dots are only
* meaningful in record keys (model names such as `gpt-4.1`, Bedrock inference profiles, MIME
* types, header names), which a record keeps as one segment.
*
* Keys no schema node defines are unknown keys and stay accepted.
*/
function findShapeIssues(
schema: SchemaNode,
value: unknown,
path: IssuePath,
depth = 0,
): ShapeIssue[] {
if (depth >= MAX_MERGE_DEPTH) {
return [];
}
const node = unwrapSchema(schema);
const { type } = node.def;
if (type === 'object' && node.shape && isPlainObject(value)) {
return findObjectShapeIssues(node.shape, value, path, depth);
}
if (type === 'intersection' && isPlainObject(value)) {
const shape = getIntersectionShape(node);
return shape ? findObjectShapeIssues(shape, value, path, depth) : [];
}
if (type === 'array' && node.def.element && Array.isArray(value)) {
const item = node.def.element;
return value.flatMap((entry, index) =>
findShapeIssues(item, entry, [...path, index], depth + 1),
);
}
if (type === 'record' && node.def.valueType && isPlainObject(value)) {
const entrySchema = node.def.valueType;
return Object.entries(value).flatMap(([key, entry]) =>
findShapeIssues(entrySchema, entry, [...path, key], depth + 1),
);
}
if (type !== 'union' || !node.def.options || !isPlainObject(value)) {
return [];
}
const options = [...node.def.options.values()];
const accepted = options.find((option) => option.safeParse(value).success);
if (!accepted) {
/** A strict option fails on the dotted key itself, and parsing reports it only as unrecognized. */
return isRecordSchema(node) ? [] : toDottedKeyIssues(value, path);
}
const acceptedShape = unwrapSchema(accepted).shape;
const defined = new Set(
options.flatMap((option) => Object.keys(unwrapSchema(option).shape ?? {})),
);
const dropped: ShapeIssue[] = acceptedShape
? Object.keys(value)
.filter((key) => !hasOwn(acceptedShape, key) && defined.has(key))
.map((key): ShapeIssue => ({ code: 'union_dropped_key', path: [...path, key] }))
: [];
return [...dropped, ...findShapeIssues(accepted, value, path, depth + 1)];
}
/**
* Top-level override keys are section names, never paths: a dotted one would be stored as an
* inert literal key, outside the secret registry and every per-section rule.
*/
export function getDottedSectionIssues(overrides: unknown): ConfigOverrideIssue[] {
if (!isPlainObject(overrides)) {
return [];
}
return Object.keys(overrides)
.filter((key) => key.includes('.'))
.map((key) => toIssue([key], 'dotted_key'));
}
/**
* Checks config overrides the way they apply: merged over `base` (YAML-shaped), each
* section they touch parsed with its `configSchema` schema, and every failure attributed
* to the override node that caused it. Unions, refinements, required fields and defaults
* are therefore judged on the merged result, not on the patch alone. An issue caused only
* by leaving something out (a required or related field another layer may supply) is not
* reported, except inside an array the merge replaces, where nothing can supply it. A top-level
* key that is not a `configSchema` section is reported as `unknown_section` (or as `dotted_key`
* alone when it holds a dot); keys the schema does not define inside a known section are
* accepted unchanged, and a key holding a dot is a `dotted_key` issue unless it sits where the
* schema has a record. Sections that pass their schema are also checked for what AppService
* derives from them (`getDerivedConfigIssues`): Azure groups that do not resolve, a Vertex AI
* setup that does not load, custom endpoint parameter definitions (with
* `derivation.expandCustomEndpoint`) and model spec endpoints.
*/
export function getConfigOverrideIssues(
overrides: unknown,
base: Partial<TCustomConfig> = {},
derivation: ConfigDerivation = {},
): ConfigOverrideIssue[] {
if (!isPlainObject(overrides)) {
return [toIssue([], 'invalid_document')];
}
const merged = deepMerge(base as AnyObject, overrides);
const issues = [...getDottedSectionIssues(overrides), ...getMergeKeyIssues(overrides)];
const seen = new Set(issues.map((issue) => issue.path));
const report = (issuePath: IssuePath, code: string, schemaIssue?: SchemaIssue) => {
const segments = attributeIssue(overrides, merged, issuePath);
if (
!segments ||
(segments.length < issuePath.length && !isReplacedArrayNode(overrides, segments))
) {
return;
}
const path = segments.join('.');
if (seen.has(path)) {
return;
}
seen.add(path);
const exact = schemaIssue != null && segments.length === issuePath.length;
issues.push(toIssue(segments, code, exact ? getConfigIssueParams(schemaIssue) : undefined));
};
const shape = configSchema.shape;
const validSections = new Set<string>();
for (const section of Object.keys(overrides)) {
if (!hasOwn(shape, section)) {
if (!seen.has(section)) {
issues.push(toIssue([section], 'unknown_section'));
}
continue;
}
const schema = shape[section as keyof typeof shape] as unknown as SchemaNode;
const result = shape[section as keyof typeof shape].safeParse(merged[section], {
reportInput: true,
});
const shapeIssues = findShapeIssues(schema, merged[section], []);
const schemaIssues = result.success ? [] : expandSchemaIssues(result.error.issues);
if (result.success && shapeIssues.length === 0) {
validSections.add(section);
}
for (const issue of shapeIssues) {
report([section, ...issue.path], issue.code);
}
for (const issue of schemaIssues) {
if (issue.code !== 'unrecognized_keys') {
report([section, ...toIssuePath(issue.path)], getConfigIssueCode(issue), issue);
}
}
}
/** A derived check that fails over a value the schema already faulted adds nothing to that issue. */
const faulted = issues.map((issue) => issue.segments);
for (const { path, code } of getDerivedConfigIssues(
overrides,
merged,
validSections,
derivation,
)) {
if (!faulted.some((segments) => isSegmentPrefix(path, segments))) {
report(path, code);
}
}
return issues;
}
/** Sets a path without mutating, replacing whatever is in the way. */
function setPath(target: unknown, segments: string[], value: unknown): unknown {
if (segments.length === 0) {
return value;
}
const [segment, ...rest] = segments;
if (Array.isArray(target) && /^\d+$/.test(segment)) {
const next = [...target];
next[Number(segment)] = setPath(next[Number(segment)], rest, value);
return next;
}
const next: AnyObject = isPlainObject(target) ? { ...target } : {};
next[segment] = setPath(next[segment], rest, value);
return next;
}
function isRelatedPath(a: string[], b: string[]): boolean {
const length = Math.min(a.length, b.length);
return a.slice(0, length).every((segment, index) => segment === b[index]);
}
/**
* The base a principal's override lands on: `base` without the paths the principal
* tombstones, except those in `cleared` (tombstones the pending write removes).
*/
export function applyConfigTombstones(
base: Partial<TCustomConfig>,
tombstones: unknown[] | undefined,
cleared: Set<string> = new Set(),
): Partial<TCustomConfig> {
return (tombstones ?? [])
.filter((path): path is string => typeof path === 'string' && !cleared.has(path))
.flatMap((path) => getTombstoneRemovals(path, true))
.reduce((current, path) => deletePath(current, path), base as AnyObject);
}
/**
* An item of a merged-by-key array is identified by its key, not its position: a write by index
* can rename the stored item, which the runtime merge then treats as a new one. Reports the
* array once for any write that addresses inside it by position.
*/
export function getIndexedMergeKeyIssues(
written: ReadonlyArray<readonly string[]>,
): ConfigOverrideIssue[] {
return Object.keys(ARRAY_MERGE_KEYS).flatMap((arrayPath) => {
const arraySegments = arrayPath.split('.');
return written.some(
(segments) =>
segments.length > arraySegments.length && isRelatedPath([...segments], arraySegments),
)
? [toIssue(arraySegments, 'indexed_merge_key_write')]
: [];
});
}
function hasMergeKey(item: unknown, keyField: string): boolean {
return isPlainObject(item) && typeof item[keyField] === 'string' && item[keyField] !== '';
}
/**
* Where an issue sits in `overrides`, in a form that survives entries moving: an item of a
* merged-by-key array is named by its key's identity (`getConfigEntryIdentity`), or (without
* one) by its place among the keyless items, rather than by its index. Removing one entry
* shifts the ones after it, and their issues must still match the ones the stored document
* already had.
*/
function getIssueLocation(segments: readonly string[], overrides: unknown): string {
const location: Array<string | { key: unknown } | { keyless: number }> = [];
let node: unknown = overrides;
for (let index = 0; index < segments.length; index++) {
const segment = segments[index];
const keyField = Array.isArray(node)
? getConfigArrayMergeKey(segments.slice(0, index))
: undefined;
if (Array.isArray(node) && keyField) {
const position = Number(segment);
const item: unknown = node[position];
location.push(
hasMergeKey(item, keyField)
? {
key: getConfigEntryIdentity(
segments.slice(0, index),
(item as AnyObject)[keyField] as string,
),
}
: {
keyless: node.slice(0, position).filter((other) => !hasMergeKey(other, keyField))
.length,
},
);
node = item;
continue;
}
location.push(segment);
if (Array.isArray(node)) {
node = node[Number(segment)];
} else {
node = isPlainObject(node) && hasOwn(node, segment) ? node[segment] : undefined;
}
}
return JSON.stringify(location);
}
/**
* Checks a principal's next override document in its final state: `candidate` merged over
* `base` without the candidate's tombstones, so a batch that tombstones a field and sets its
* replacement is judged on the end result rather than step by step. An issue is reported when
* it touches a `written` path (in either direction), or when the change introduced it
* elsewhere (a related field the change made invalid); issues the stored document already had
* (at the same location, entries of merged-by-key arrays matched by key) are left to merge
* time so they do not block an unrelated change.
*
* A derived issue the merge copes with on its own (`WRITE_ONLY_DERIVED_ISSUES`: a model spec
* whose endpoint is not configured, which the merge leaves out) is reported only where the change
* writes, never as one it introduced elsewhere: hiding or removing the endpoint a stored spec
* selects takes the spec with it, as the single-field routes let it.
*
* The stored document is judged on the base its own tombstones leave, so an issue that a
* removed tombstone brings back counts as new. `lifted` names stored tombstones to treat as
* already removed there: tombstones the change replaced with values of its own.
*/
export function getConfigChangeIssues(
candidate: { overrides?: unknown; tombstones?: unknown[] },
base: Partial<TCustomConfig>,
stored: { overrides?: unknown; tombstones?: unknown[] } | null | undefined,
written: ReadonlyArray<readonly string[]>,
lifted: Iterable<string> = [],
derivation: ConfigDerivation = {},
): ConfigOverrideIssue[] {
const candidateState = toConfigOverrideState(candidate);
const storedState = toConfigOverrideState(stored);
const existing = new Set(
getConfigOverrideIssues(
storedState.overrides,
applyConfigTombstones(base, storedState.tombstones, new Set(lifted)),
derivation,
).map((issue) => getIssueLocation(issue.segments, storedState.overrides)),
);
return getConfigOverrideIssues(
candidateState.overrides,
applyConfigTombstones(base, candidateState.tombstones),
derivation,
).filter((issue) => {
const touched = written.some((segments) => isRelatedPath(issue.segments, [...segments]));
if (touched || WRITE_ONLY_DERIVED_ISSUES.has(issue.code)) {
return touched;
}
return !existing.has(getIssueLocation(issue.segments, candidateState.overrides));
});
}
/**
* Checks field writes on top of the principal's stored config, building the result with the
* same transform the write stores (`setConfigFields`): each path set in order, and the
* tombstones those paths clear removed. `fields` is either a map of dotted field paths or a
* list of segment writes (which can address keys that contain dots). A path the stored
* document cannot take (below a scalar, or a named key of an array) throws a
* `ConfigPathError`. See {@link getConfigChangeIssues} for which issues are reported.
*
* A tombstone a write replaces with its own value counts as lifted for the stored document
* too, so a client that sends one field per request can switch a union's shape (set the new
* field, then reset the old ones). A tombstone a deeper write clears as a side effect does
* not: setting `memory.agent.enabled` under a hidden `memory.agent` brings the inherited agent
* back, and a conflict with the stored fields is reported instead of being dropped at merge.
* Nor does a keyed tombstone, which a write never clears by its spelled path
* (`getPathClearedTombstones`): a segment `custom["Name"]` is a key of that spelling.
*
* `renames` are the entry renames the write carries out (a `renames` hint), which move the keyed
* tombstones of each old entry key to its new one (`renameConfigEntryTombstones`).
*/
export function getConfigFieldIssues(
fields: Record<string, unknown> | readonly ConfigFieldWrite[],
base: Partial<TCustomConfig> = {},
stored?: { overrides?: unknown; tombstones?: unknown[] } | null,
renames: readonly ConfigEntryRename[] = [],
derivation: ConfigDerivation = {},
): ConfigOverrideIssue[] {
const writes: readonly ConfigFieldWrite[] = Array.isArray(fields)
? fields
: Object.entries(fields).map(([fieldPath, value]) => ({
segments: parseFieldPath(fieldPath),
value,
}));
const written = writes.map(({ segments }) => [...segments]);
const indexed = getIndexedMergeKeyIssues(written);
if (indexed.length > 0) {
return indexed;
}
const candidate = renameConfigEntriesTombstones(
setConfigFields(toConfigOverrideState(stored), writes),
renames,
);
return getConfigChangeIssues(
candidate,
base,
stored,
written,
getLiftedConfigTombstones(written),
derivation,
);
}
/**
* The stored tombstones writes at `written` replace with their own values, as
* {@link getConfigFieldIssues} lifts them: each dot-free path, unless its spelling reads as a
* keyed tombstone, which a write never clears by its spelled path.
*/
export function getLiftedConfigTombstones(written: readonly (readonly string[])[]): string[] {
return written.flatMap((segments) => {
const path = segments.join('.');
return isDotFreePath(segments) && readConfigEntryTombstone(path) == null ? [path] : [];
});
}
function omitPath(target: unknown, segments: string[]): unknown {
const [segment, ...rest] = segments;
if (Array.isArray(target)) {
const index = Number(segment);
if (!Number.isInteger(index) || index < 0 || index >= target.length) {
return target;
}
const next = [...target];
if (rest.length === 0) {
next.splice(index, 1);
} else {
next[index] = omitPath(next[index], rest);
}
return next;
}
if (!isPlainObject(target) || !hasOwn(target, segment)) {
return target;
}
const next = { ...target };
const child = rest.length === 0 ? undefined : omitPath(next[segment], rest);
/** A node its repairs emptied supplies nothing, so the value beneath it stays instead. */
const emptied = child != null && typeof child === 'object' && Object.keys(child).length === 0;
if (rest.length === 0 || emptied) {
delete next[segment];
} else {
next[segment] = child;
}
return next;
}
/**
* Drops the override nodes that make the merged config fail `configSchema`, so an invalid
* stored value (written before write-time validation, by an older server, or one that only
* fails once layered over other overrides) leaves the value beneath it in place. A layer
* is not judged on what it leaves out, since a layer that merges after it may supply it.
*/
function stripInvalidOverrides(
config: ConfigOverrideLayer,
base: Partial<TCustomConfig>,
derivation: ConfigDerivation,
sink?: LayerIgnoredSink,
onStripped?: (issue: ConfigOverrideIssue) => void,
): AnyObject {
const principal = `${config.principalType}/${config.principalId}`;
let stripped: unknown = combineStoredFoldedItems(config.overrides, principal, sink != null);
const getIssues = () =>
getConfigOverrideIssues(stripped, base, derivation).filter(
(issue) => !WRITE_ONLY_DERIVED_ISSUES.has(issue.code),
);
/**
* Removing a field can make a related field it supplies fail, so check again while
* removals make progress. If they stop, only the sections that still fail are dropped.
*/
for (let pass = 0; pass < MAX_STRIP_PASSES; pass++) {
const issues = getIssues();
if (issues.length === 0) {
return stripped as AnyObject;
}
if (issues.some((issue) => issue.segments.length === 0)) {
if (sink) {
sink(toIgnored([], 'invalid', 'override'));
} else {
logger.warn(
`[mergeConfigOverrides] Ignoring malformed overrides document for ${principal}`,
);
}
onStripped?.(toIssue([], issues.find((issue) => issue.segments.length === 0)?.code ?? ''));
return {};
}
const before = stripped;
for (let index = issues.length - 1; index >= 0; index--) {
const { path, segments, code } = issues[index];
if (sink) {
sink(toIgnored(segments, 'invalid', 'override'));
} else {
logger.warn(
`[mergeConfigOverrides] Ignoring invalid override "${path}" for ${principal} (${code})`,
);
}
stripped = omitPath(stripped, segments);
onStripped?.(issues[index]);
}
if (stripped === before) {
break;
}
}
const failing = new Map<string, string>();
for (const issue of getIssues()) {
if (!failing.has(issue.segments[0])) {
failing.set(issue.segments[0], issue.code);
}
}
if (sink) {
failing.forEach((_code, section) => sink(toIgnored([section], 'invalid', 'override')));
} else {
logger.warn(
`[mergeConfigOverrides] Ignoring still-invalid sections ${[...failing.keys()].join(', ')} for ${principal}`,
);
}
for (const [section, code] of failing) {
onStripped?.(toIssue([section], code));
}
return Object.fromEntries(
Object.entries(stripped as AnyObject).filter(([section]) => !failing.has(section)),
);
}
/**
* A layer's `mcpServers` without the servers `current` (the merged MCP config below it) runs as
* a local process, or that the override would turn into one; `onDropped` is told each name.
*/
function filterMCPServerOverrides(
value: unknown,
current: unknown,
onDropped?: (serverName: string) => void,
): AnyObject {
if (value == null || typeof value !== 'object' || Array.isArray(value)) {
return {};
}
const currentServers =
current != null && typeof current === 'object' && !Array.isArray(current)
? (current as AnyObject)
: {};
const filtered: AnyObject = {};
for (const [serverName, serverOverride] of Object.entries(value)) {
const currentServer = currentServers[serverName];
if (
serverOverride == null ||
typeof serverOverride !== 'object' ||
Array.isArray(serverOverride)
) {
if (!isProcessMCPServerConfig(currentServer)) {
filtered[serverName] = serverOverride;
} else {
onDropped?.(serverName);
}
continue;
}
const baseServer =
currentServer != null && typeof currentServer === 'object' && !Array.isArray(currentServer)
? (currentServer as AnyObject)
: {};
const resolved = deepMerge(baseServer, serverOverride as AnyObject);
if (!isProcessMCPServerConfig(resolved)) {
filtered[serverName] = serverOverride;
} else {
onDropped?.(serverName);
}
}
return filtered;
}
/** One layer's step through {@link mergeConfigOverrides}, as `afterLayer` sees it. */
export interface ConfigMergeStep {
layer: ConfigOverrideLayer;
/** The base config the merge started from, before any layer. */
base: AppConfig;
/** The merged config before this layer applied its tombstones and overrides. */
below: AppConfig;
/**
* What the layer's overrides contributed, under AppConfig section names (`mcpConfig`,
* `interfaceConfig`, ...), after invalid, base-only and filtered values were removed.
*/
applied: Readonly<Record<string, unknown>>;
/** The merged config with this layer applied. */
merged: AppConfig;
/**
* The base config with only this layer applied (its tombstones, then its overrides; where the
* merge resolves Azure groups, each group it names as its item resolves over librechat.yaml's
* group of that name, its key only where the layer supplies one), as if no other layer were
* below it. Computed on first call.
*/
alone: () => AppConfig;
}
export interface MergeConfigOverridesOptions extends ConfigDerivation {
/**
* Runs after each layer merges; the config it returns is what the next layer merges onto. A
* caller uses it to apply a policy that depends on what a layer inherited and what it changed,
* such as dropping an inherited credential the layer sends somewhere new.
*/
afterLayer?: (step: ConfigMergeStep) => AppConfig;
/**
* Told about each stored web search key the merge withholds from the URL it was not entered
* for, with the layer whose write moved it: the URL's writer when it is the later layer, and
* otherwise the key's own. When given, it reports these instead of the merge's own warning.
*/
onWebSearchKeyUnbound?: (unbound: WebSearchKeyUnbound) => void;
}
/** A stored web search key the merge withholds, and the layer whose write caused it. */
export interface WebSearchKeyUnbound {
layer: ConfigOverrideLayer;
url: TWebSearchKeys;
apiKey: TWebSearchKeys;
}
/** One layer's step through {@link foldConfigLayers}, from which `ConfigMergeStep` is built. */
interface FoldStep<T> {
layer: ConfigOverrideLayer;
below: T;
/** What the layer's overrides contributed, under AppConfig section names. */
applied: AnyObject;
merged: T;
/**
* What the layer removed before its overrides landed, as AppConfig paths: its tombstones that
* applied (a tombstone of Azure `groups` with every field they resolve to).
*/
removed: readonly string[];
}
/** The override document that last set or removed a paired web search field, and its merge position. */
interface WebSearchWriter {
config: ConfigOverrideLayer;
order: number;
removed: boolean;
}
type WebSearchWriters = Map<TWebSearchKeys, WebSearchWriter>;
const WEB_SEARCH_TOMBSTONE_PREFIX = 'webSearch.';
/** Records `writer` for each paired web search field its applied overrides set. */
function recordWebSearchWrites(
writers: WebSearchWriters,
section: unknown,
writer: WebSearchWriter,
): void {
if (!isPlainObject(section)) {
return;
}
for (const field of webSearchPairedFields) {
if (hasOwn(section, field)) {
writers.set(field, writer);
}
}
}
/** Records `writer` for each paired web search field an applied tombstone removes. */
function recordWebSearchTombstone(
writers: WebSearchWriters,
path: string,
writer: WebSearchWriter,
): void {
if (path === 'webSearch') {
for (const field of webSearchPairedFields) {
writers.set(field, writer);
}
return;
}
if (!path.startsWith(WEB_SEARCH_TOMBSTONE_PREFIX)) {
return;
}
const field = path.slice(WEB_SEARCH_TOMBSTONE_PREFIX.length) as TWebSearchKeys;
if (webSearchPairedFields.includes(field)) {
writers.set(field, writer);
}
}
function describeLayer(writer?: WebSearchWriter): string {
return writer ? `${writer.config.principalType}/${writer.config.principalId}` : 'the base config';
}
/**
* Withholds each stored web search key whose URL a layer other than the key's
* own decides (`unbindWebSearchKeys`), so a layer that overrides only a URL
* never sends on a key it cannot read. `writers` lists the override document
* behind each field; unlisted fields come from the base config.
*/
function bindWebSearchKeys(
merged: AppConfig,
writers: WebSearchWriters,
onUnbound?: MergeConfigOverridesOptions['onWebSearchKeyUnbound'],
): AppConfig {
const { webSearch, unbound } = unbindWebSearchKeys(
merged.webSearch,
(field) => writers.get(field)?.order,
);
if (unbound.length === 0) {
return merged;
}
for (const { url, apiKey } of unbound) {
const urlWriter = writers.get(url);
const keyWriter = writers.get(apiKey);
if (onUnbound) {
const cause = (urlWriter?.order ?? -1) > (keyWriter?.order ?? -1) ? urlWriter : keyWriter;
if (cause) {
onUnbound({ layer: cause.config, url, apiKey });
}
continue;
}
logger.warn(
`[mergeConfigOverrides] Ignoring webSearch.${apiKey} from ${describeLayer(keyWriter)}: ` +
`webSearch.${url} is ${urlWriter?.removed ? 'removed' : 'set'} by ${describeLayer(urlWriter)}. ` +
'Store the key in the same config as the URL.',
);
}
return { ...merged, webSearch };
}
function describePrincipal(config: ConfigOverrideLayer): string {
return `${config.principalType}/${config.principalId}`;
}
/**
* The document with only what the merge may apply: override keys and tombstones under a
* top-level section `configSchema` defines. Anything else was stored before writes were
* checked (or by another writer) and would reach runtime state no override may set, so it is
* dropped here, which neutralizes it without a migration. One warning per document.
*/
function withAcceptedSections(
config: ConfigOverrideLayer,
sink?: LayerIgnoredSink,
): ConfigOverrideLayer {
const ignored = new Set<string>();
let overrides = config.overrides;
if (isPlainObject(overrides)) {
const accepted: AnyObject = {};
for (const [key, value] of Object.entries(overrides)) {
if (isAcceptedOverrideSection(key)) {
accepted[key] = value;
} else {
ignored.add(key);
sink?.(toIgnored([key], 'unknown_section', 'override'));
}
}
overrides = accepted as Partial<TCustomConfig>;
}
let tombstones = config.tombstones;
if (Array.isArray(tombstones)) {
tombstones = tombstones.filter((path) => {
if (typeof path !== 'string') {
return false;
}
const section = path.split('.')[0];
if (isAcceptedOverrideSection(section)) {
return true;
}
ignored.add(section);
sink?.(toIgnored(path.split('.'), 'unknown_section', 'tombstone'));
return false;
});
}
if (ignored.size === 0) {
return config;
}
if (sink) {
return { ...config, overrides, tombstones };
}
logger.warn(
`[mergeConfigOverrides] Ignoring unknown config sections ${[...ignored].join(', ')} for ${describePrincipal(config)}`,
);
return { ...config, overrides, tombstones };
}
/** What a layer's Azure `groups` resolve to: what the merge serves, and what the layer itself contributed. */
interface LayerAzureResolution {
/** The merged Azure endpoint with the fields its groups decide resolved again. */
served: AnyObject;
/**
* The layer's own Azure override with `groupMap` holding each group it names as its item
* resolves over librechat.yaml's group of that name alone, the key only where the layer
* supplies one: what the rebinding guard compares a layer's own key with (`alone()`).
*/
contributed: AnyObject;
}
/** Whether a groups item supplies its own `apiKey` rather than inheriting the group's. */
function suppliesGroupKey(item: AnyObject | undefined): boolean {
return item != null && hasOwn(item, 'apiKey') && item.apiKey !== undefined;
}
/** The key fields of a `groupMap` entry, which travel together. */
const AZURE_GROUP_KEY_FIELDS = ['apiKey', 'apiKeyPreview', 'apiKeyBinding'] as const;
/** A `groupMap` entry without its key fields. */
function withoutGroupKey(entry: AnyObject): AnyObject {
const next: AnyObject = { ...entry };
for (const field of AZURE_GROUP_KEY_FIELDS) {
delete next[field];
}
return next;
}
/**
* A layer's Azure `groups` resolved as AppService resolves librechat.yaml's
* (`resolveServedAzureGroups`), merged by `group` over the groups below (the YAML-shaped config
* up to the layer, `belowGroups`), as its `groups` array merges in that config: a group it names
* merges over the group of that name (models by name), and a new one is added. The Azure clients
* read `groupMap`, `modelGroupMap` and the model lists, never `groups`, so those are what change:
* - `groupMap`: each group the layer names is resolved again; every other group keeps the entry
* below, as the merge left it. A named group keeps the key below unless the layer supplies one,
* so a key a lower layer's merge dropped stays dropped, and a group the config below does not
* serve (one a lower layer's tombstone left unable to resolve) has none: its YAML-shaped item
* still holds the key below it, which no layer below sends anywhere.
* - `modelGroupMap` and the model lists: resolved from all the merged groups.
* A resolved field the layer also writes directly merges over them (objects) or replaces them.
* `null` when the merged groups do not resolve: the layer's groups then stay unread, with a
* warning.
*/
function resolveLayerAzureGroups(params: {
layerAzure: AnyObject;
groups: AnyObject[];
belowGroups: unknown;
yamlGroups: unknown;
served: AnyObject;
below: unknown;
config: ConfigOverrideLayer;
sink?: LayerIgnoredSink;
}): LayerAzureResolution | null {
const { layerAzure, groups, belowGroups, yamlGroups, served, below, config, sink } = params;
const mergeOver = (lower: unknown): AnyObject[] =>
Array.isArray(lower) ? mergeArrayByKey(lower, groups, 'group', 2, AZURE_GROUPS_PATH) : groups;
const resolved = resolveServedAzureGroups(mergeOver(belowGroups), getGroupNames(groups));
if (!resolved.isValid) {
if (sink) {
sink(toIgnored(AZURE_GROUPS_PATH.split('.'), 'invalid', 'override'));
} else {
logger.warn(
`[mergeConfigOverrides] Ignoring ${AZURE_GROUPS_PATH} for ${describePrincipal(config)}: ${resolved.errors.join('; ')}`,
);
}
return null;
}
const items = new Map<string, AnyObject>();
for (const item of groups) {
if (typeof item.group === 'string') {
items.set(item.group, item);
}
}
const belowMap = isPlainObject(below) && isPlainObject(below.groupMap) ? below.groupMap : {};
const groupMap: AnyObject = { ...belowMap };
for (const [name, item] of items) {
const entry = resolved.groupMap[name] as AnyObject | undefined;
if (entry == null) {
continue;
}
if (suppliesGroupKey(item)) {
groupMap[name] = entry;
continue;
}
const inherited = isPlainObject(belowMap[name]) ? belowMap[name].apiKey : undefined;
groupMap[name] =
inherited === undefined ? withoutGroupKey(entry) : { ...entry, apiKey: inherited };
}
const alone: AnyObject = {};
for (const item of mergeOver(yamlGroups)) {
const name = item.group;
const own = typeof name === 'string' ? items.get(name) : undefined;
if (own == null || typeof name !== 'string') {
continue;
}
const entry = toAzureGroupMapEntry(item);
alone[name] = suppliesGroupKey(own) ? entry : withoutGroupKey(entry);
}
const ownMap = layerAzure.groupMap;
const derived: Record<AzureResolvedGroupField, unknown> = {
groupMap,
modelGroupMap: resolved.modelGroupMap,
modelNames: resolved.modelNames,
assistantModels: resolved.assistantModels,
assistantGroups: resolved.assistantGroups,
};
const next: AnyObject = { ...served };
for (const field of AZURE_RESOLVED_GROUP_FIELDS) {
const own = layerAzure[field];
const value = derived[field];
next[field] =
isPlainObject(own) && isPlainObject(value) ? deepMerge(value, own) : (own ?? value);
}
return {
served: next,
contributed: {
...layerAzure,
groupMap: isPlainObject(ownMap) ? deepMerge(alone, ownMap) : alone,
},
};
}
/**
* `merged` with the Azure model lists narrowed to what its groups serve
* (`narrowAzureServedModels`), and Azure assistants turned off when none of the models it serves
* supports them (`lacksAzureAssistantModels`), a combination `azureConfigSetup` refuses in
* librechat.yaml. A list an override writes directly, or one whose groups a later layer replaced
* or tombstoned, could otherwise name a model no group serves, and groups without an assistant
* model under an inherited `assistants: true` would leave the Azure Assistants client no model to
* default to. Judged on the merged result, so a later layer whose groups serve assistants keeps
* them on. An Azure endpoint the layers leave without the fields its groups resolve to (one a
* layer recreates after a tombstone of it or of `endpoints`) serves no group
* (`completeAzureResolution`), with or without `rederiveEndpoints`: nothing of what the removed
* groups resolved to survives the tombstone.
*/
function withServedAzureModels<T extends AppConfig>(
merged: T,
configs: readonly ConfigOverrideLayer[],
): T {
const endpoints = merged.endpoints;
const azure = endpoints?.[EModelEndpoint.azureOpenAI];
if (!endpoints || !azure) {
return merged;
}
const principals = configs.map(describePrincipal).join(', ');
const { config: complete, completed } = completeAzureResolution(azure);
if (completed.length > 0) {
logger.warn(
`[mergeConfigOverrides] Serving no Azure group for ${principals}: the ${AZURE_CONFIG_PATH} they leave has no groups that resolve`,
);
}
const { config: served, narrowed } = narrowAzureServedModels(complete);
if (narrowed.length > 0) {
logger.warn(
`[mergeConfigOverrides] Leaving out of ${narrowed.map((field) => `${AZURE_CONFIG_PATH}.${field}`).join(', ')} for ${principals} the Azure models and groups no merged group serves`,
);
}
const assistantsOff = lacksAzureAssistantModels(served);
if (assistantsOff) {
logger.warn(
`[mergeConfigOverrides] Turning off ${AZURE_CONFIG_PATH}.assistants for ${principals}: none of the Azure models they serve supports assistants`,
);
}
if (completed.length === 0 && narrowed.length === 0 && !assistantsOff) {
return merged;
}
return {
...merged,
endpoints: {
...endpoints,
[EModelEndpoint.azureOpenAI]: assistantsOff ? { ...served, assistants: false } : served,
},
};
}
/** A keyed tombstone of an Azure group (`endpoints.azureOpenAI.groups["g"]`, or a path inside it). */
function readAzureGroupTombstone(path: string): ConfigEntryLocation | null {
const entry = isKeyedConfigPath(path) ? readConfigEntryTombstone(path) : null;
return entry != null && entry.segments.join('.') === AZURE_GROUPS_PATH ? entry : null;
}
/** Whether a tombstone removes Azure groups and nothing else: the whole list, or a keyed one. */
function isAzureGroupsTombstone(path: string): boolean {
return path === AZURE_GROUPS_PATH || readAzureGroupTombstone(path) != null;
}
/** The Azure groups a layer's keyed tombstones name (`endpoints.azureOpenAI.groups["g"]`), whole or not. */
function getAzureGroupTombstones(tombstones: readonly string[]): {
hidden: Set<string>;
touched: Set<string>;
} {
const hidden = new Set<string>();
const touched = new Set<string>();
for (const path of tombstones) {
const entry = readAzureGroupTombstone(path);
if (entry != null) {
(entry.entry.rest.length === 0 ? hidden : touched).add(entry.identity);
}
}
return { hidden, touched };
}
/** {@link withHiddenAzureGroups}' result: the served config, and the groups it no longer serves. */
interface HiddenAzureGroups<T> {
merged: T;
/** The groups with a path hidden inside them that the groups left do not let resolve. */
unresolved: ReadonlySet<string>;
}
/**
* `merged` once a layer's keyed tombstones of Azure groups (`tombstones`) applied, where the merge
* resolves Azure groups: the groups the YAML-shaped config keeps (`raw`) resolved again, as a
* layer's own groups are (`resolveLayerAzureGroups`). A hidden group leaves `groupMap`, and
* `modelGroupMap` and the model lists are resolved from the groups left. A group with a path
* hidden inside it is resolved again from what it keeps, with the key below it, which a tombstone
* never supplies; every other group keeps the entry below. Where the groups left do not resolve,
* the groups with a path hidden inside them are served no more either (`unresolved`, judged on
* `raw` alone, with a warning unless `quiet`); where none is left, no group is served
* (`withoutAzureGroups`).
*/
function withHiddenAzureGroups<T extends AnyObject>(
merged: T,
raw: Partial<TCustomConfig>,
tombstones: readonly string[],
config: ConfigOverrideLayer,
quiet = false,
): HiddenAzureGroups<T> {
const { hidden, touched } = getAzureGroupTombstones(tombstones);
if (hidden.size === 0 && touched.size === 0) {
return { merged, unresolved: new Set() };
}
const azureSegments = AZURE_CONFIG_PATH.split('.');
const azure = getPath(merged, azureSegments);
const kept = getPath(raw, AZURE_GROUPS_PATH.split('.'));
let groups = Array.isArray(kept) ? kept.filter(isPlainObject) : [];
let resolved = resolveServedAzureGroups(groups, touched);
const unresolved = resolved.isValid ? new Set<string>() : touched;
if (!resolved.isValid) {
if (!quiet && isPlainObject(azure)) {
logger.warn(
`[mergeConfigOverrides] Serving none of the ${AZURE_GROUPS_PATH} ${[...touched].join(', ')} for ${describePrincipal(config)}: they do not resolve once its tombstones apply: ${resolved.errors.join('; ')}`,
);
}
groups = groups.filter((item) => typeof item.group !== 'string' || !touched.has(item.group));
resolved = resolveServedAzureGroups(groups, new Set());
}
if (!isPlainObject(azure)) {
return { merged, unresolved };
}
if (groups.length === 0 || !resolved.isValid) {
return { merged: withoutAzureGroups(merged), unresolved };
}
const belowMap = isPlainObject(azure.groupMap) ? azure.groupMap : {};
const groupMap: AnyObject = {};
for (const [name, entry] of Object.entries(resolved.groupMap)) {
const below = belowMap[name];
if (!touched.has(name) && isPlainObject(below)) {
groupMap[name] = below;
continue;
}
const next: AnyObject = { ...(entry as AnyObject) };
for (const field of AZURE_GROUP_KEY_FIELDS) {
if (isPlainObject(below) && below[field] !== undefined) {
next[field] = below[field];
} else {
delete next[field];
}
}
groupMap[name] = next;
}
const next = setPath(merged, azureSegments, {
...azure,
groupMap,
modelGroupMap: resolved.modelGroupMap,
modelNames: resolved.modelNames,
assistantModels: resolved.assistantModels,
assistantGroups: resolved.assistantGroups,
}) as T;
return { merged: next, unresolved };
}
/** What {@link foldConfigLayers} leaves: the served config, the YAML-shaped one, and what layers wrote. */
interface FoldResult<T> {
merged: T;
raw: Partial<TCustomConfig>;
webSearchWriters: WebSearchWriters;
touches: ConfigTouches;
}
/** Where Vertex AI sits in librechat.yaml (and, unresolved, in an AppConfig). */
const VERTEX_SEGMENTS = ['endpoints', EModelEndpoint.anthropic, 'vertex'];
/** The Anthropic models a layer serves over Vertex AI's. */
const ANTHROPIC_MODELS_SEGMENTS = ['endpoints', EModelEndpoint.anthropic, 'models'];
/** Whether a tombstone path removes Azure `groups`: the groups, or an object holding them. */
function removesAzureGroups(path: string): boolean {
return AZURE_GROUPS_PATH === path || AZURE_GROUPS_PATH.startsWith(`${path}.`);
}
/** What a tracked fold records about one layer (`resolveConfigLayers`). */
interface LayerTrack {
/** The document as given. */
layer: ConfigOverrideLayer;
/** The document the fold read: `layer` with only accepted sections (`withAcceptedSections`). */
accepted: ConfigOverrideLayer;
/**
* What its overrides contributed to the YAML-shaped result, under AppConfig section names:
* invalid, base-only and filtered values removed, Azure `groups` as written.
*/
contributed: AnyObject;
/** The tombstones the fold applied, in librechat.yaml keys. */
tombstoned: string[];
ignored: AdminConfigLayerIgnored[];
}
/**
* A fold's record of the YAML-shaped result and of what each layer could not apply. `resolved`
* is `librechat.yaml` folded exactly as `merged` is (same tombstones, filters, merge keys and
* atomic paths), kept under AppConfig section names (`interfaceConfig`, `mcpConfig`, ...) so the
* merge rules address it as they address `merged`.
*/
interface FoldTracker {
resolved: AnyObject;
layers: LayerTrack[];
}
function toLayerIgnored(
segments: readonly string[],
reason: AdminConfigLayerIgnoreReason,
extra?: Pick<AdminConfigLayerIgnored, 'code' | 'tombstone'>,
): AdminConfigLayerIgnored {
return { path: segments.join('.'), segments: [...segments], reason, ...extra };
}
/** A reason both a write's `ignored` and a resolution's layer list give. */
type SharedIgnoreReason = AdminConfigIgnoreReason & AdminConfigLayerIgnoreReason;
/**
* Where an ignored tombstone sits: its path as stored, which DELETE `/fields` takes, and its
* segments, with a keyed tombstone's entry named by its key, as write responses name a
* credential in one.
*/
function getTombstoneLocation(path: string): { path: string; segments: string[] } {
const entry = isKeyedConfigPath(path) ? readConfigEntryTombstone(path) : null;
return {
path,
segments: entry ? [...entry.segments, entry.entry.key, ...entry.entry.rest] : path.split('.'),
};
}
/** `tree` with its top-level keys in AppConfig names (`interface` → `interfaceConfig`, ...). */
function toAppConfigKeys(tree: Partial<TCustomConfig>): AnyObject {
const result: AnyObject = {};
for (const [key, value] of Object.entries(tree)) {
if (value !== undefined) {
result[OVERRIDE_KEY_MAP[key as keyof typeof OVERRIDE_KEY_MAP] ?? key] = value;
}
}
return result;
}
/** `tree` with its top-level keys back in librechat.yaml names. */
function toOverrideKeys(tree: AnyObject): Partial<TCustomConfig> {
const result: AnyObject = {};
for (const [key, value] of Object.entries(tree)) {
if (value !== undefined) {
result[OVERRIDE_SECTION_BY_APP_KEY.get(key) ?? key] = value;
}
}
return result as Partial<TCustomConfig>;
}
/** Starts a layer's record with the sections `withAcceptedSections` left out of it. */
function startLayerTrack(
tracker: FoldTracker,
layer: ConfigOverrideLayer,
accepted: ConfigOverrideLayer,
): LayerTrack {
const ignored: AdminConfigLayerIgnored[] = [];
if (accepted !== layer) {
if (isPlainObject(layer.overrides)) {
for (const key of Object.keys(layer.overrides)) {
if (!isAcceptedOverrideSection(key)) {
ignored.push(toLayerIgnored([key], 'unknown_section'));
}
}
}
for (const path of Array.isArray(layer.tombstones) ? layer.tombstones : []) {
if (typeof path === 'string' && !isAcceptedOverrideSection(path.split('.')[0])) {
ignored.push(toLayerIgnored(path.split('.'), 'unknown_section', { tombstone: true }));
}
}
}
const track: LayerTrack = { layer, accepted, contributed: {}, tombstoned: [], ignored };
tracker.layers.push(track);
return track;
}
/** The interface fields and sub-keys the permission filter removes from an interface override. */
function getInterfacePermissionRemovals(value: AnyObject): string[][] {
const removed: string[][] = [];
for (const [field, fieldVal] of Object.entries(value)) {
if (!INTERFACE_PERMISSION_FIELDS.has(field)) {
continue;
}
if (isPlainObject(fieldVal)) {
for (const sub of Object.keys(fieldVal)) {
if (PERMISSION_SUB_KEYS.has(sub)) {
removed.push(['interface', field, sub]);
}
}
} else if (!RUNTIME_CONFIG_INTERFACE_FIELDS.has(field)) {
removed.push(['interface', field]);
}
}
return removed;
}
/**
* Reports what a tombstone leaves in place: a field only librechat.yaml sets, at or below the
* tombstone (the whole tombstone) or below it where the base config has a value the merge puts
* back (`isHeldValueSet`), and the MCP servers librechat.yaml runs as local processes (`merged`
* is the config below the layer).
*/
function reportTombstoneHeld(
path: string,
merged: AnyObject,
isHeldValueSet: (held: YamlHeldPath) => boolean,
sink: LayerIgnoredSink,
): void {
const segments = path.split('.');
for (const held of YAML_HELD_PATHS) {
if (isSegmentPrefix(held.segments, segments)) {
sink(toIgnored(segments, held.reason, 'tombstone'));
} else if (isSegmentPrefix(segments, held.segments) && isHeldValueSet(held)) {
sink(toIgnored(held.segments, held.reason, 'tombstone'));
}
}
const servers = merged.mcpConfig;
if (segments[0] !== 'mcpServers' || !isPlainObject(servers)) {
return;
}
const names = segments.length > 1 ? [segments[1]] : Object.keys(servers);
for (const name of names) {
if (isProcessMCPServerConfig(servers[name])) {
const location = segments.length > 1 ? segments : ['mcpServers', name];
sink(toIgnored(location, 'process_mcp_server', 'tombstone'));
}
}
}
/** What a fold reports beside its result (`foldConfigLayers`). */
interface FoldObservers {
/** Told about each stored override or tombstone a layer's fold leaves out. */
sink?: IgnoredSink;
/**
* For the `sink`: whether the merge puts back a held field below a tombstone; by default,
* whether the initial raw config (librechat.yaml) sets it.
*/
isHeldValueSet?: (held: YamlHeldPath) => boolean;
/** Keeps the YAML-shaped result and each layer's unapplied parts. */
tracker?: FoldTracker;
}
/**
* Folds override layers, in merge precedence order (`compareConfigPrecedence`), into
* `merged`, the served config, and `raw`, the YAML-shaped config each layer is validated on
* before it lands (`stripInvalidOverrides`). `merged` starts as any object whose `mcpConfig`
* is the MCP servers config of `raw`, because the process-MCP filter reads it. A layer's Azure
* `groups` always merge by `group` over the groups below in `raw`. With
* `options.rederiveEndpoints`, they also resolve into the fields the Azure clients read
* (`resolveLayerAzureGroups`), a tombstone of them removes those fields, and a layer that writes
* or removes `endpoints.anthropic.vertex`, or removes `endpoints.anthropic.models`, has Vertex AI
* derived again (`deriveVertexEndpoint`), keeping the models a layer set only while no later
* layer has removed them, and a tombstone inside a group that leaves it unable to resolve is
* reported (`azure_groups_unresolved`);
* without it, those overrides stay inert in `merged`, as before the merge derived them, and a
* layer's Azure groups and its tombstones of them are reported (`endpoint_rederive_off`). Layers
* are judged with `vertexConfigured` taken from `initialRaw`, librechat.yaml.
* `webSearchWriters` names the layer behind each paired web search field, by its position in
* that order, and `touches` what the layers wrote and removed. `afterLayer` runs after each layer
* lands, and the next layer folds onto what it returns. With a `sink`, the fold tells it what of
* each stored layer it leaves out (`getIgnoredConfigOverrides`); with a `tracker`, it also keeps
* the YAML-shaped result the served config corresponds to, and what of each layer it did not
* apply (`resolveConfigLayers`).
*/
function foldConfigLayers<T extends AnyObject>(
initial: T,
initialRaw: Partial<TCustomConfig>,
configs: readonly ConfigOverrideLayer[],
afterLayer?: (step: FoldStep<T>) => T,
options: ConfigDerivation = {},
{
sink,
tracker,
isHeldValueSet = (held) => getPath(initialRaw, [...held.segments]) !== undefined,
}: FoldObservers = {},
): FoldResult<T> {
const derivation: ConfigDerivation = {
...options,
vertexConfigured: isVertexConfigured(initialRaw),
};
const sorted = sortByConfigPrecedence(configs);
let merged = initial;
let raw = initialRaw;
const webSearchWriters: WebSearchWriters = new Map();
const touches = createConfigTouches();
const resolvesAzureGroups = derivation.rederiveEndpoints === true;
let anthropicModelsSet = false;
for (let order = 0; order < sorted.length; order++) {
const source = sorted[order];
const layerSink: LayerIgnoredSink | undefined = sink && ((entry) => sink(source, entry));
const config = withAcceptedSections(source, layerSink);
const track = tracker && startLayerTrack(tracker, source, config);
const below = merged;
let contributed: AnyObject = {};
const removed: string[] = [];
const tombstoned: string[] = [];
let appliedOverrides: AnyObject = {};
const isBasePrincipal = isBaseConfigPrincipal(config);
if (Array.isArray(config.tombstones)) {
const removal: WebSearchWriter = { config, order, removed: true };
for (const path of config.tombstones) {
if (typeof path !== 'string') {
continue;
}
if (isBaseOnlyOverridePath(path)) {
layerSink?.(toIgnored(path.split('.'), 'base_only_section', 'tombstone'));
track?.ignored.push(
toLayerIgnored(path.split('.'), 'base_only_section', { tombstone: true }),
);
continue;
}
if (!isBasePrincipal && BASE_PRINCIPAL_OVERRIDE_SECTIONS.has(path.split('.')[0])) {
layerSink?.(toIgnored(path.split('.'), 'dedicated_section', 'tombstone'));
track?.ignored.push(
toLayerIgnored(path.split('.'), 'base_principal_section', { tombstone: true }),
);
continue;
}
if (isDerivedConfigPath(path.split('.'))) {
layerSink?.(toIgnored(path.split('.'), 'derived_path', 'tombstone'));
track?.ignored.push(toLayerIgnored(path.split('.'), 'derived_path', { tombstone: true }));
continue;
}
if (layerSink) {
reportTombstoneHeld(path, merged, isHeldValueSet, layerSink);
}
tombstoned.push(path);
for (const removedPath of getTombstoneRemovals(path, resolvesAzureGroups)) {
const mappedPath = remapOverridePath(removedPath);
removed.push(mappedPath);
merged = deleteConfigPath(merged, mappedPath);
raw = deletePath(raw as AnyObject, removedPath) as Partial<TCustomConfig>;
if (tracker) {
tracker.resolved = deleteConfigPath(tracker.resolved, mappedPath);
}
}
if (resolvesAzureGroups && path === AZURE_GROUPS_PATH) {
merged = withoutAzureGroups(merged);
}
track?.tombstoned.push(path);
recordWebSearchTombstone(webSearchWriters, path, removal);
}
const reportTombstone = (path: string, reason: SharedIgnoreReason) => {
const location = getTombstoneLocation(path);
layerSink?.({ ...location, reason, kind: 'tombstone' });
track?.ignored.push({ ...location, reason, tombstone: true });
};
if (resolvesAzureGroups) {
const hidden = withHiddenAzureGroups(merged, raw, tombstoned, config, layerSink != null);
merged = hidden.merged;
for (const path of tombstoned) {
const entry = readAzureGroupTombstone(path);
if (
entry != null &&
entry.entry.rest.length > 0 &&
hidden.unresolved.has(entry.identity)
) {
reportTombstone(path, 'azure_groups_unresolved');
}
}
} else {
for (const path of tombstoned.filter(isAzureGroupsTombstone)) {
reportTombstone(path, 'endpoint_rederive_off');
}
}
}
if (config.overrides && typeof config.overrides === 'object') {
const remapped: AnyObject = {};
const applied: AnyObject = {};
const valid = stripInvalidOverrides(
config,
raw,
derivation,
layerSink,
track &&
((issue) =>
track.ignored.push(
toLayerIgnored(issue.segments, 'invalid_override', { code: issue.code }),
)),
);
const writable = withoutDerivedPaths(
valid,
describePrincipal(config),
layerSink || track
? (segments) => {
layerSink?.(toIgnored(segments, 'derived_path', 'override'));
track?.ignored.push(toLayerIgnored(segments, 'derived_path'));
}
: undefined,
);
for (const [key, value] of Object.entries(writable)) {
if (BASE_ONLY_OVERRIDE_SECTIONS.has(key)) {
layerSink?.(toIgnored([key], 'base_only_section', 'override'));
track?.ignored.push(toLayerIgnored([key], 'base_only_section'));
continue;
}
if (!isBasePrincipal && BASE_PRINCIPAL_OVERRIDE_SECTIONS.has(key)) {
layerSink?.(toIgnored([key], 'dedicated_section', 'override'));
track?.ignored.push(toLayerIgnored([key], 'base_principal_section'));
continue;
}
applied[key] = value;
const mappedKey = OVERRIDE_KEY_MAP[key as keyof typeof OVERRIDE_KEY_MAP] ?? key;
if (mappedKey === 'mcpConfig') {
remapped[mappedKey] = filterMCPServerOverrides(
value,
merged[mappedKey],
layerSink &&
((name) => layerSink(toIgnored([key, name], 'process_mcp_server', 'override'))),
);
/** A server the filter removed must not complete a later layer's partial of it. */
applied[key] = remapped[mappedKey];
if (track && isPlainObject(value)) {
for (const name of Object.keys(value)) {
if (!hasOwn(remapped[mappedKey] as AnyObject, name)) {
track.ignored.push(toLayerIgnored([key, name], 'process_mcp_server'));
}
}
}
} else if (
key === 'interface' &&
value != null &&
typeof value === 'object' &&
!Array.isArray(value)
) {
const filtered: AnyObject = {};
for (const [field, fieldVal] of Object.entries(value as AnyObject)) {
if (!INTERFACE_PERMISSION_FIELDS.has(field)) {
filtered[field] = fieldVal;
} else if (
fieldVal != null &&
typeof fieldVal === 'object' &&
!Array.isArray(fieldVal)
) {
// Composite permission field (e.g. mcpServers): strip permission
// sub-keys but preserve UI-only sub-keys like placeholder/trustCheckbox.
const uiOnly: AnyObject = {};
for (const [sub, subVal] of Object.entries(fieldVal as AnyObject)) {
if (!PERMISSION_SUB_KEYS.has(sub)) {
uiOnly[sub] = subVal;
} else {
layerSink?.(toIgnored([key, field, sub], 'interface_permission', 'override'));
}
}
if (Object.keys(uiOnly).length > 0) {
filtered[field] = uiOnly;
}
} else if (RUNTIME_CONFIG_INTERFACE_FIELDS.has(field)) {
// Dual-purpose field: the boolean form is a runtime disable, not a
// permission toggle, so preserve it (e.g. schedules: false).
filtered[field] = fieldVal;
} else {
// other boolean permission fields (e.g. runCode: false) are fully stripped
layerSink?.(toIgnored([key, field], 'interface_permission', 'override'));
}
}
if (Object.keys(filtered).length > 0) {
remapped[mappedKey] = filtered;
}
for (const segments of track ? getInterfacePermissionRemovals(value as AnyObject) : []) {
track?.ignored.push(toLayerIgnored(segments, 'interface_permission'));
}
} else {
remapped[mappedKey] = value;
}
}
const beforeOverrides = merged;
const rawBelow = raw;
if (layerSink) {
for (const held of YAML_HELD_PATHS) {
if (getPath(applied, [...held.segments]) !== undefined) {
layerSink(toIgnored(held.segments, held.reason, 'override'));
}
}
}
merged = deepMerge(merged, remapped);
raw = deepMerge(raw as AnyObject, applied) as Partial<TCustomConfig>;
recordWebSearchWrites(webSearchWriters, applied.webSearch, {
config,
order,
removed: false,
});
contributed = remapped;
appliedOverrides = applied;
if (tracker && track) {
track.contributed = remapped;
tracker.resolved = deepMerge(tracker.resolved, track.contributed);
}
const layerAzure = getPath(applied, AZURE_CONFIG_PATH.split('.'));
const groupsSegments = AZURE_GROUPS_PATH.split('.');
if (!resolvesAzureGroups && isPlainObject(layerAzure) && Array.isArray(layerAzure.groups)) {
layerSink?.(toIgnored(groupsSegments, 'endpoint_rederive_off', 'override'));
track?.ignored.push(toLayerIgnored(groupsSegments, 'endpoint_rederive_off'));
}
if (resolvesAzureGroups && isPlainObject(layerAzure) && Array.isArray(layerAzure.groups)) {
const azureSegments = AZURE_CONFIG_PATH.split('.');
const resolution = resolveLayerAzureGroups({
layerAzure,
groups: layerAzure.groups.filter(isPlainObject),
belowGroups: getPath(rawBelow, groupsSegments),
yamlGroups: tombstoned.some(removesAzureGroups)
? undefined
: getPath(initialRaw, groupsSegments),
served: (getPath(merged, azureSegments) as AnyObject | undefined) ?? {},
below: getPath(beforeOverrides, azureSegments),
config,
sink: layerSink,
});
if (resolution) {
merged = setPath(merged, azureSegments, resolution.served) as T;
contributed = setPath(remapped, azureSegments, resolution.contributed) as AnyObject;
} else {
track?.ignored.push(toLayerIgnored(groupsSegments, 'azure_groups_unresolved'));
}
}
}
recordConfigTouches(touches, appliedOverrides, tombstoned);
const anthropicModelsRemoved = tombstoned.some((path) =>
isRelatedPath(path.split('.'), ANTHROPIC_MODELS_SEGMENTS),
);
anthropicModelsSet =
getPath(appliedOverrides, ANTHROPIC_MODELS_SEGMENTS) !== undefined ||
(anthropicModelsSet && !anthropicModelsRemoved);
if (
derivation.rederiveEndpoints === true &&
(anthropicModelsRemoved ||
getPath(appliedOverrides, VERTEX_SEGMENTS) !== undefined ||
tombstoned.some((path) => isRelatedPath(path.split('.'), VERTEX_SEGMENTS)))
) {
const derived = deriveVertexEndpoint({
merged,
raw: raw as AnyObject,
baseYaml: initialRaw as AnyObject,
modelsOverridden: anthropicModelsSet,
principal: describePrincipal(config),
});
if (derived !== merged) {
merged = derived;
const anthropicSegments = ['endpoints', EModelEndpoint.anthropic];
contributed = setPath(
contributed,
anthropicSegments,
getPath(derived, anthropicSegments),
) as AnyObject;
}
}
if (afterLayer) {
merged = afterLayer({ layer: config, below, applied: contributed, merged, removed });
}
}
return { merged, raw, webSearchWriters, touches };
}
/** A config merged from override layers, and the librechat.yaml-shaped config they merge to. */
export interface ConfigMergeResult {
appConfig: AppConfig;
/**
* librechat.yaml with the applied layers merged over it, keys as librechat.yaml names them: what
* the next layer would be validated on, and what derived values are derived from.
*/
raw: Partial<TCustomConfig>;
}
/** One layer of {@link resolveConfigLayers}: the document as given, and what the merge left out. */
export interface ConfigLayerResolution {
layer: ConfigOverrideLayer;
ignored: AdminConfigLayerIgnored[];
}
/** {@link resolveConfigLayers}' result. */
export interface ConfigLayersResolution {
/** Exactly what {@link mergeConfigOverrides} returns for the same arguments. */
merged: AppConfig;
/**
* The librechat.yaml-shaped config the fold leaves, as {@link mergeConfigOverridesWithSource}
* returns it: what a caller derives the parts only the final config decides from.
*/
raw: Partial<TCustomConfig>;
/** The same merge in librechat.yaml shape: `baseConfig.config` with every layer folded in. */
resolved: Partial<TCustomConfig>;
/** Every layer, in merge precedence order. */
layers: ConfigLayerResolution[];
}
/** The layers of a tracked fold whose contribution holds a value at `segments` (AppConfig keys). */
function getWriters(tracker: FoldTracker, segments: readonly string[]): LayerTrack[] {
return tracker.layers.filter((track) => getPath(track.contributed, [...segments]) !== undefined);
}
/**
* The layers of a tracked fold that applied a tombstone at or under `path` (librechat.yaml keys),
* or with `ancestors`, above it as well: a tombstone of `endpoints.agents` removes
* `endpoints.agents.pullRequests.host` with the rest.
*/
function getTombstoners(tracker: FoldTracker, path: string, ancestors: boolean): LayerTrack[] {
return tracker.layers.filter((track) =>
track.tombstoned.some(
(tombstone) =>
tombstone === path ||
tombstone.startsWith(`${path}.`) ||
(ancestors && path.startsWith(`${tombstone}.`)),
),
);
}
/** Sets or removes (`undefined`) the value at `segments` of the tracker's resolved tree. */
function setResolved(tracker: FoldTracker, segments: readonly string[], value: unknown): void {
tracker.resolved =
value === undefined
? deletePath(tracker.resolved, segments.join('.'))
: (setPath(tracker.resolved, [...segments], value) as AnyObject);
}
/**
* Replays on the YAML-shaped result what {@link withServedAzureModels} did to the served config:
* an Azure model list a layer wrote directly, narrowed to what the merged groups serve, and
* `assistants` turned off when none of them supports assistants.
*/
function replayAzureServed(tracker: FoldTracker, before: AppConfig, after: AppConfig): void {
const segments = AZURE_CONFIG_PATH.split('.');
const served = getPath(after, segments);
const resolved = getPath(tracker.resolved, segments);
if (served === getPath(before, segments) || !isPlainObject(served) || !isPlainObject(resolved)) {
return;
}
for (const field of ['assistants', 'modelNames', 'assistantModels', 'assistantGroups']) {
if (!hasOwn(resolved, field) || isSameJson(resolved[field], served[field])) {
continue;
}
setResolved(tracker, [...segments, field], served[field]);
const writers =
field === 'assistants'
? getWriters(tracker, segments)
: getWriters(tracker, [...segments, field]);
for (const track of writers) {
track.ignored.push(toLayerIgnored([...segments, field], 'azure_unserved'));
}
}
}
/**
* Replays on the YAML-shaped result what {@link preserveRuntimeStops} did to the served config:
* an interface feature the base config turns off stays off, in the shape the layers left it, or
* `false` where a tombstone removed it. Each layer that wrote it or tombstoned it, or anything
* above or below it, is told.
*/
function replayRuntimeStops(tracker: FoldTracker, baseConfig: AppConfig): void {
const baseInterface = (baseConfig as unknown as AnyObject).interfaceConfig;
const resolvedInterface = tracker.resolved.interfaceConfig;
if (!isPlainObject(baseInterface) || !isPlainObject(resolvedInterface)) {
return;
}
for (const key of RUNTIME_CONFIG_INTERFACE_FIELDS) {
if (!isRuntimeDisabled(baseInterface[key]) || isRuntimeDisabled(resolvedInterface[key])) {
continue;
}
const current = resolvedInterface[key];
setResolved(
tracker,
['interfaceConfig', key],
isPlainObject(current) ? { ...current, use: false } : false,
);
const segments = ['interface', key];
for (const track of getWriters(tracker, ['interfaceConfig', key])) {
track.ignored.push(toLayerIgnored(segments, 'runtime_stop'));
}
for (const track of getTombstoners(tracker, segments.join('.'), true)) {
track.ignored.push(toLayerIgnored(segments, 'runtime_stop', { tombstone: true }));
}
}
}
/**
* Replays on the YAML-shaped result what {@link preserveBaseOnlyPaths} did to the served config:
* each field only librechat.yaml sets (`YAML_HELD_PATHS`: base-only and deployment-only) keeps
* the value `librechat.yaml` gives it. A layer is told when it wrote one, tombstoned one or
* anything below it, or tombstoned anything above one `librechat.yaml` sets, as write responses
* tell it (`base_only_path`, `deployment_only_path`).
*/
function replayBaseOnlyPaths(tracker: FoldTracker, baseYaml: Partial<TCustomConfig>): void {
for (const { segments, reason } of YAML_HELD_PATHS) {
const path = segments.join('.');
const appSegments = remapOverridePath(path).split('.');
const value = getPath(baseYaml, [...segments]);
const writers = getWriters(tracker, appSegments);
const tombstoners = getTombstoners(tracker, path, value !== undefined);
if (writers.length === 0 && tombstoners.length === 0) {
continue;
}
setResolved(tracker, appSegments, value);
for (const track of writers) {
track.ignored.push(toLayerIgnored(segments, reason));
}
for (const track of tombstoners) {
track.ignored.push(toLayerIgnored(segments, reason, { tombstone: true }));
}
}
}
function isSameJson(a: unknown, b: unknown): boolean {
return JSON.stringify(a) === JSON.stringify(b);
}
/**
* The merge {@link mergeConfigOverridesWithSource} runs, and with a `tracker` the YAML-shaped
* result and each layer's unapplied parts, replaying on that result each step the served config
* takes after the fold.
*/
function mergeLayers(
baseConfig: AppConfig,
configs: readonly ConfigOverrideLayer[],
options: MergeConfigOverridesOptions,
tracker?: FoldTracker,
): ConfigMergeResult {
const { afterLayer, expandCustomEndpoint, rederiveEndpoints } = options;
const derivation: ConfigDerivation = { expandCustomEndpoint, rederiveEndpoints };
const folded = foldConfigLayers(
{ ...baseConfig },
baseConfig.config ?? {},
configs,
afterLayer &&
(({ layer, below, applied, merged, removed }) => {
let alone: AppConfig | undefined;
return afterLayer({
layer,
base: baseConfig,
below,
applied,
merged,
alone: () => {
alone ??= deepMerge(
removed.reduce((current, path) => deleteConfigPath(current, path), { ...baseConfig }),
applied,
);
return alone;
},
});
}),
derivation,
{ tracker },
);
const served = withServedAzureModels(folded.merged, configs);
if (tracker) {
replayAzureServed(tracker, folded.merged, served);
}
const derived = rederiveMergedConfig({
merged: served,
raw: folded.raw as AnyObject,
base: baseConfig,
touches: folded.touches,
derivation,
principals: configs.map(describePrincipal).join(', '),
});
const unbound: WebSearchKeyUnbound[] = [];
const onUnbound =
tracker || options.onWebSearchKeyUnbound
? (binding: WebSearchKeyUnbound) => {
unbound.push(binding);
options.onWebSearchKeyUnbound?.(binding);
}
: undefined;
const bound = bindWebSearchKeys(derived, folded.webSearchWriters, onUnbound);
if (tracker) {
for (const { layer, apiKey } of unbound) {
setResolved(tracker, ['webSearch', apiKey], bound.webSearch?.[apiKey]);
tracker.layers
.find((track) => track.accepted === layer)
?.ignored.push(toLayerIgnored(['webSearch', apiKey], 'secret_rebinding'));
}
replayRuntimeStops(tracker, baseConfig);
replayBaseOnlyPaths(tracker, baseConfig.config ?? {});
}
return {
appConfig: preserveBaseOnlyPaths(baseConfig, preserveRuntimeStops(baseConfig, bound)),
raw: folded.raw,
};
}
/**
* Merge DB config overrides into a base AppConfig.
*
* Configs merge in precedence order (`compareConfigPrecedence`): Base first, then ascending
* priority, then role < group < user, then document identity; the last layer wins. Each
* config's `overrides` is deep-merged into the base config in that order. A stored web search
* key is dropped when a layer other than its own decides the URL it is sent to, the Azure model
* lists name only models the merged groups serve, and Azure assistants none of those supports
* are turned off (`withServedAzureModels`). What AppService derives from the parts layers wrote
* is derived again (`rederiveMergedConfig`): custom endpoint parameters (with
* `expandCustomEndpoint`), the agents endpoint's memory capability, and with `rederiveEndpoints`
* the Azure groups, Vertex AI and the Azure Assistants endpoint.
*/
export function mergeConfigOverrides(
baseConfig: AppConfig,
configs: readonly ConfigOverrideLayer[],
options: MergeConfigOverridesOptions = {},
): AppConfig {
return mergeConfigOverridesWithSource(baseConfig, configs, options).appConfig;
}
/**
* {@link mergeConfigOverrides}, with the librechat.yaml-shaped config the layers merge to, from
* which a caller derives what only the final config decides (such as the interface defaults
* model specs turn off, once tenant scoping has settled which specs are served).
*/
export function mergeConfigOverridesWithSource(
baseConfig: AppConfig,
configs: readonly ConfigOverrideLayer[],
options: MergeConfigOverridesOptions = {},
): ConfigMergeResult {
if (!configs || configs.length === 0) {
return { appConfig: baseConfig, raw: baseConfig.config ?? {} };
}
return mergeLayers(baseConfig, configs, options);
}
/**
* {@link mergeConfigOverrides}, and what it amounts to in librechat.yaml shape: `resolved` is
* `baseConfig.config` (the raw librechat.yaml) with each layer's tombstones and overrides folded
* in under the merge's own rules (precedence, merge keys, atomic paths, accepted, base-only and
* Base-only sections, invalid-override stripping, process MCP servers, the interface permission
* filter), followed by the steps the served config takes after the fold: Azure model lists the
* merged groups do not serve, web search keys withheld from a URL another layer decides, runtime
* stops and base-only fields. Each layer lists what of it the merge does not apply as written.
*
* Not replayed, because they are AppService derivations librechat.yaml never holds: the fields
* Azure `groups` resolve to (`groupMap`, `modelNames`, ...; `resolved` keeps the `groups`), what
* `rederiveMergedConfig` derives again (expanded custom parameters, Vertex AI, the agents
* capabilities, the Azure Assistants endpoint, and the model specs whose endpoint the layers
* leave), and the `afterLayer` policy a caller adds (the admin API replays its secret rebinding
* itself).
*/
export function resolveConfigLayers(
baseConfig: AppConfig,
configs: readonly ConfigOverrideLayer[],
options: MergeConfigOverridesOptions = {},
): ConfigLayersResolution {
const tracker: FoldTracker = {
resolved: toAppConfigKeys(baseConfig.config ?? {}),
layers: [],
};
if (!configs || configs.length === 0) {
return {
merged: baseConfig,
raw: baseConfig.config ?? {},
resolved: toOverrideKeys(tracker.resolved),
layers: [],
};
}
const { appConfig: merged, raw } = mergeLayers(baseConfig, configs, options, tracker);
return {
merged,
raw,
resolved: toOverrideKeys(tracker.resolved),
layers: tracker.layers.map(({ layer, ignored }) => ({ layer, ignored })),
};
}
/**
* The YAML-shaped config `configs` resolve to on top of `baseYaml`: exactly the value
* {@link mergeConfigOverrides} validates the next layer on, with the same precedence order,
* tombstones, base-only and dedicated-section filtering, invalid-override stripping and
* process-MCP filtering. It is a validation floor, not the served config (no AppService
* derivation runs on it).
*/
export function resolveRawConfig(
baseYaml: Partial<TCustomConfig>,
configs: readonly ConfigOverrideLayer[],
derivation: ConfigDerivation = {},
): Partial<TCustomConfig> {
if (configs.length === 0) {
return baseYaml;
}
/** AppService serves `mcpServers` as `mcpConfig` unchanged (or `null`), and the fold reads it there. */
return foldConfigLayers(
{ mcpConfig: baseYaml.mcpServers ?? null },
baseYaml,
configs,
undefined,
derivation,
).raw;
}
/**
* What the merge leaves out of `layer`'s stored overrides and tombstones, each at its own
* location: the parts no merge applies (unknown, base-only and dedicated sections, interface
* permissions, MCP servers librechat.yaml runs as processes), the values it sets back to
* librechat.yaml's (base-only and deployment-only fields), and the values that fail validation
* where it applies them. Judged exactly as the merge folds the layer over `baseYaml`
* (librechat.yaml) and the layers in `below` (those that merge first, such as the active Base),
* through the same steps. A field below a tombstone counts as put back when librechat.yaml sets
* it or `resolved`, the AppConfig librechat.yaml resolves to, holds it (defaults included), with
* the checks `derivation` adds (`getConfigOverrideIssues`). Each location is listed once per
* reason and kind; nothing about a value is returned.
*/
export function getIgnoredConfigOverrides(
baseYaml: Partial<TCustomConfig>,
layer: ConfigOverrideLayer,
below: readonly ConfigOverrideLayer[] = [],
resolved?: AppConfig,
derivation: ConfigDerivation = {},
): AdminConfigIgnoredOverride[] {
const found = new Map<string, AdminConfigIgnoredOverride>();
foldConfigLayers(
{ mcpConfig: baseYaml.mcpServers ?? null },
baseYaml,
[...below, layer],
undefined,
derivation,
{
sink: (source, entry) => {
const key = JSON.stringify([entry.kind, entry.reason, entry.segments]);
if (source === layer && !found.has(key)) {
found.set(key, entry);
}
},
isHeldValueSet: (held) =>
getPath(baseYaml, [...held.segments]) !== undefined ||
(resolved != null &&
getPath(resolved, remapOverridePath(held.segments.join('.')).split('.')) !== undefined),
},
);
return [...found.values()];
}
function getPath(target: unknown, segments: string[]): unknown {
let current = target;
for (const segment of segments) {
if (!isPlainObject(current)) return undefined;
current = current[segment];
}
return current;
}
/**
* Puts back the base value of every field only librechat.yaml sets (`YAML_HELD_PATHS`: the
* base-only and deployment-only paths), whatever an override set or a tombstone removed on the
* way, so every reader of the merged config sees the operator's value.
*/
function preserveBaseOnlyPaths<T extends AppConfig>(baseConfig: AppConfig, merged: T): T {
let result: unknown = merged;
for (const held of YAML_HELD_PATHS) {
const segments = remapOverridePath(held.segments.join('.')).split('.');
const value = getPath(baseConfig, segments);
if (getPath(result, segments) !== value) result = setPath(result, segments, value);
}
return result as T;
}
/** Whether a runtime-config interface field reads as OFF in either of its two shapes:
* boolean `false`, or the object form with `use: false`. Exported so runtime gates
* (e.g. the schedule engine's global stop) apply the same semantics as the merge. */
export function isRuntimeDisabled(value: unknown): boolean {
if (value === false) {
return true;
}
return (
value != null &&
typeof value === 'object' &&
!Array.isArray(value) &&
(value as AnyObject).use === false
);
}
/**
* Re-applies a BASE-level runtime stop after all overrides are merged.
*
* A deployment that turns a runtime feature off is not making a preference an override
* can outrank: the service reads the base value and keeps refusing writes, so an
* override that only flips the client's view produces a panel whose every action fails.
*
* Applied here rather than inside the merge deliberately. The merge folds overrides in
* precedence order into an ACCUMULATED value, so a guard there compares against whatever
* the previous override left — which let an EARLIER `false` block a LATER `true` and broke
* last-layer-wins. Overrides still order normally among themselves; only the base stop is
* non-negotiable.
*/
function preserveRuntimeStops<T extends AppConfig>(baseConfig: AppConfig, merged: T): T {
const baseInterface = (baseConfig as unknown as AnyObject).interfaceConfig as
| AnyObject
| undefined;
const mergedInterface = (merged as unknown as AnyObject).interfaceConfig as AnyObject | undefined;
if (baseInterface == null || mergedInterface == null) {
return merged;
}
let patched: AnyObject | undefined;
for (const key of RUNTIME_CONFIG_INTERFACE_FIELDS) {
if (!isRuntimeDisabled(baseInterface[key]) || isRuntimeDisabled(mergedInterface[key])) {
continue;
}
const current = mergedInterface[key];
patched ??= { ...mergedInterface };
patched[key] =
current != null && typeof current === 'object' && !Array.isArray(current)
? { ...(current as AnyObject), use: false }
: false;
}
if (patched == null) {
return merged;
}
return { ...(merged as unknown as AnyObject), interfaceConfig: patched } as unknown as T;
}