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
🧬 feat: Re-Derive Azure Groups, Vertex AI, Custom Parameters and Spec Defaults for Config Profiles (#17399)
Danny Avila9f617fc4ad1f
diff --git a/.env.example b/.env.exampleindex 9fe1f8d087..2b6d620042 100644--- a/.env.example+++ b/.env.example@@ -250,12 +250,23 @@ NODE_MAX_OLD_SPACE_SIZE=6144# Config overrides written through the admin API (profiles and the Base profile) may reference# only the ${ENV_VAR} names librechat.yaml references, the built-in endpoint credentials# (OPENAI_API_KEY, ANTHROPIC_API_KEY, ...), and the names listed here (comma or space separated).-# Any other reference is rejected on write and resolves to nothing at runtime. Only the interface+# Any other reference is rejected on write and resolves to nothing at runtime. Vertex AI settings+# (endpoints.anthropic.vertex) may reference only the names librechat.yaml's own Vertex AI settings+# reference, because the server resolves them into the config admin reads return. Only the interface# and modelSpecs sections and these prompt fields are left unchecked, because they are used as# written: each endpoint's title, activity and reasoning-label prompts, summarization.prompt and# updatePrompt, memory.agent.instructions, and webSearch firecrawl changeTrackingOptions.prompt.# CONFIG_OVERRIDE_ENV_ALLOWLIST=MY_GATEWAY_KEY,MY_GATEWAY_URL+# Config profiles (admin config overrides) of Azure `groups`, of `endpoints.anthropic.vertex`+# (Vertex AI) and of the Azure `assistants` switch derive the served endpoints again, as+# librechat.yaml's do at startup. Off by default for this release: those overrides are stored but+# inert. A profile's Vertex AI applies only where librechat.yaml configures+# endpoints.anthropic.vertex (on or off), on its key file and region. At startup the server logs+# the config documents that hold such overrides, which of their Azure groups would not resolve,+# and which Vertex AI overrides never apply.+# CONFIG_REDERIVE_ENDPOINTS=true+# Deployment skills are loaded read-only at startup and exposed to all users# with the Skills capability enabled. Defaults to project root ./skill.# DEPLOYMENT_SKILLS_DIR=./skilldiff --git a/api/server/index.js b/api/server/index.jsindex 5b8c0bc680..0d47bf3148 100644--- a/api/server/index.js+++ b/api/server/index.js@@ -70,6 +70,7 @@ const {warnOnUnreachableDeliveryPaths,createCodeApiUploadRegistry,createRequestSanitizer,+ reportEndpointOverrides,} = require('@librechat/api');const { connectDb, indexSync } = require('~/db');const {@@ -77,6 +78,7 @@ const {sweepOrphanedPreviews,getRoleByName,seedDatabase,+ listAllConfigs,recordAuditEntry,} = require('~/models');const initializeOAuthReconnectManager = require('./services/initializeOAuthReconnectManager');@@ -95,7 +97,7 @@ const initializeMCPs = require('./services/initializeMCPs');const { configureSubagentTaskRouting } = require('./services/Endpoints/agents/subagentThreadStore');const configureSocialLogins = require('./socialLogins');const createSpaFallback = require('./utils/fallback');-const { getAppConfig } = require('./services/Config');+const { getAppConfig, rederiveEndpoints } = require('./services/Config');const staticCache = require('./utils/staticCache');const noIndex = require('./middleware/noIndex');const agentEventMethods = require('~/models');@@ -530,6 +532,14 @@ const startServer = async () => {await initializeMCPs();await initializeOAuthReconnectManager();});+ /** Logs only, so readiness never waits on reading every config document. */+ reportEndpointOverrides({+ listConfigs: () => runAsSystem(() => listAllConfigs()),+ baseYaml: appConfig?.config ?? {},+ rederiveEndpoints,+ }).catch((err) => {+ logger.error('[config] Failed to report endpoint overrides:', err);+ });await checkMigrations();const inspectFlags = process.execArgv.some((arg) => arg.startsWith('--inspect'));diff --git a/api/server/routes/admin/config.js b/api/server/routes/admin/config.jsindex 5bb1061bb3..4e21a8a836 100644--- a/api/server/routes/admin/config.js+++ b/api/server/routes/admin/config.js@@ -20,6 +20,7 @@ const {overrideCacheTtl,loadConfigModels,loadDefaultModels,+ rederiveEndpoints,getEndpointsConfig,reloadConfigCaches,resolveConfigLayers,@@ -53,6 +54,7 @@ const handlers = createAdminConfigHandlers({auditFailClosed: process.env.AUDIT_LOG_FAIL_CLOSED === 'true',overrideCacheTtlMs: overrideCacheTtl,overrideEnvAllowlist: process.env.CONFIG_OVERRIDE_ENV_ALLOWLIST,+ rederiveEndpoints,});const readHandlers = createAdminConfigReadHandlers({diff --git a/api/server/services/Config/__tests__/invalidateConfigCaches.spec.js b/api/server/services/Config/__tests__/invalidateConfigCaches.spec.jsindex 46b419a95e..dee4cbd2af 100644--- a/api/server/services/Config/__tests__/invalidateConfigCaches.spec.js+++ b/api/server/services/Config/__tests__/invalidateConfigCaches.spec.js@@ -42,6 +42,8 @@ const mockCreateConfigCacheInvalidation = jest.fn(({ clears }) => ({close: async () => undefined,}));jest.mock('@librechat/api', () => ({+ isEnabled: (value) => value === 'true',+ expandCustomEndpoint: jest.fn((endpoint) => endpoint),createAppConfigService: jest.fn(() => ({getAppConfig: jest.fn().mockResolvedValue({ availableTools: {} }),clearAppConfigCache: mockClearAppConfigCache,diff --git a/api/server/services/Config/app.js b/api/server/services/Config/app.jsindex c4230ba4c6..cd6a67aa36 100644--- a/api/server/services/Config/app.js+++ b/api/server/services/Config/app.js@@ -2,6 +2,8 @@ const mongoose = require('mongoose');const { CacheKeys } = require('librechat-data-provider');const { AppService } = require('@librechat/data-schemas');const {+ isEnabled,+ expandCustomEndpoint,createAppConfigService,clearMcpConfigCache,createCodeEnvironmentRegistry,@@ -45,7 +47,7 @@ const loadBaseConfig = async (mode) => {adminIncluded: config.includedTools,directory: paths.structuredTools,});- return AppService({ config, paths, systemTools });+ return AppService({ config, paths, systemTools, expandCustomEndpoint });};const appConfigService = createAppConfigService({@@ -56,6 +58,7 @@ const appConfigService = createAppConfigService({getApplicableConfigs: db.getApplicableConfigs,getUserPrincipals: db.getUserPrincipals,overrideEnvAllowlist: process.env.CONFIG_OVERRIDE_ENV_ALLOWLIST,+ rederiveEndpoints: isEnabled(process.env.CONFIG_REDERIVE_ENDPOINTS),augmentConfig: ({ appConfig, baseConfig, principals, options }) => {if (!options.userId) return appConfig;return mergeAccessibleCodeEnvironments({@@ -78,6 +81,7 @@ const {clearOverrideCache,reloadBaseConfig,overrideCacheTtl,+ rederiveEndpoints,} = appConfigService;// Config owns the reader; models never import this module to obtain it.@@ -127,6 +131,7 @@ module.exports = {getAppConfig,resolveConfigLayers,overrideCacheTtl,+ rederiveEndpoints,invalidateConfigCaches,reloadConfigCaches,getCodeEnvironmentRegistry,diff --git a/api/server/services/Config/loadCustomConfig.spec.js b/api/server/services/Config/loadCustomConfig.spec.jsindex f4e827590f..a243a033b5 100644--- a/api/server/services/Config/loadCustomConfig.spec.js+++ b/api/server/services/Config/loadCustomConfig.spec.js@@ -57,7 +57,7 @@ jest.mock('@librechat/data-schemas', () => {});const axios = require('axios');-const { loadYaml } = require('@librechat/api');+const { loadYaml, expandCustomEndpoint } = require('@librechat/api');const { logger } = require('@librechat/data-schemas');const { ReasoningParameterFormat, ReasoningResponseKey } = require('librechat-data-provider');const loadCustomConfig = require('./loadCustomConfig');@@ -312,7 +312,12 @@ describe('loadCustomConfig', () => {expect(result.langfuse.headers['CF-Access-Client-Secret']).toBe('gateway-credential');});- describe('parseCustomParams', () => {+ /**+ * The loader checks each custom endpoint's `customParams` and returns them as written; the+ * served copy is expanded by `expandCustomEndpoint` (AppService), so `appConfig.config` stays+ * librechat.yaml as written.+ */+ describe('customParams', () => {const mockConfig = {version: '1.0',cache: false,@@ -392,6 +397,9 @@ describe('loadCustomConfig', () => {});expect(parsedConfig.endpoints.custom[0].customParams).toEqual({+ reasoningFormat: ReasoningParameterFormat.reasoningObject,+ });+ expect(expandCustomEndpoint(parsedConfig.endpoints.custom[0]).customParams).toEqual({defaultParamsEndpoint: 'custom',reasoningFormat: ReasoningParameterFormat.reasoningObject,paramDefinitions: [],@@ -404,6 +412,9 @@ describe('loadCustomConfig', () => {});expect(parsedConfig.endpoints.custom[0].customParams).toEqual({+ reasoningKey: ReasoningResponseKey.reasoning,+ });+ expect(expandCustomEndpoint(parsedConfig.endpoints.custom[0]).customParams).toEqual({defaultParamsEndpoint: 'custom',reasoningKey: ReasoningResponseKey.reasoning,paramDefinitions: [],@@ -419,8 +430,11 @@ describe('loadCustomConfig', () => {],};+ const written = structuredClone(customParams);const parsedConfig = await loadCustomParams(customParams);- const paramDefinitions = parsedConfig.endpoints.custom[0].customParams.paramDefinitions;+ expect(parsedConfig.endpoints.custom[0].customParams).toEqual(written);+ const paramDefinitions = expandCustomEndpoint(parsedConfig.endpoints.custom[0]).customParams+ .paramDefinitions;expect(paramDefinitions).toEqual([{columnSpan: 1,@@ -470,7 +484,8 @@ describe('loadCustomConfig', () => {loadYaml.mockReturnValue(openRouterConfig);const parsedConfig = await loadCustomConfig();- expect(parsedConfig.endpoints.custom[0].customParams).toEqual({+ expect(parsedConfig.endpoints.custom[0].customParams).toBeUndefined();+ expect(expandCustomEndpoint(parsedConfig.endpoints.custom[0]).customParams).toEqual({defaultParamsEndpoint: 'openrouter',paramDefinitions: [{@@ -506,7 +521,8 @@ describe('loadCustomConfig', () => {loadYaml.mockReturnValue(openRouterConfig);const parsedConfig = await loadCustomConfig();- expect(parsedConfig.endpoints.custom[0].customParams).toMatchObject({+ expect(parsedConfig.endpoints.custom[0].customParams).toBeUndefined();+ expect(expandCustomEndpoint(parsedConfig.endpoints.custom[0]).customParams).toMatchObject({defaultParamsEndpoint: 'openrouter',paramDefinitions: [{@@ -535,7 +551,10 @@ describe('loadCustomConfig', () => {loadYaml.mockReturnValueOnce(config);const loaded = await loadCustomConfig();- expect(loaded.endpoints.custom[0].customParams.defaultParamsEndpoint).toBe('openrouter');+ expect(loaded.endpoints.custom[0].customParams.defaultParamsEndpoint).toBe('');+ expect(+ expandCustomEndpoint(loaded.endpoints.custom[0]).customParams.defaultParamsEndpoint,+ ).toBe('openrouter');});it('preserves explicit OpenRouter promptCache defaults', async () => {@@ -563,6 +582,11 @@ describe('loadCustomConfig', () => {const parsedConfig = await loadCustomConfig();expect(parsedConfig.endpoints.custom[0].customParams.paramDefinitions).toEqual([+ { key: 'promptCache', default: false },+ ]);+ expect(+ expandCustomEndpoint(parsedConfig.endpoints.custom[0]).customParams.paramDefinitions,+ ).toEqual([{columnSpan: 1,component: 'switch',diff --git a/docs/endpoint-overrides.md b/docs/endpoint-overrides.mdindex 395c20589c..77f7f0af26 100644--- a/docs/endpoint-overrides.md+++ b/docs/endpoint-overrides.md@@ -13,7 +13,8 @@ the entry by its key.## Keyed pathsA keyed path names one entry of an array merged by key (`rules.arrayMergeKeys` in-`GET /api/admin/config/meta`, today `endpoints.custom`), then optionally a path inside it:+`GET /api/admin/config/meta`, today `endpoints.custom` and `endpoints.azureOpenAI.groups`), then+optionally a path inside it:```textendpoints.custom["<name>"]@@ -160,6 +161,17 @@ cannot apply answers 400 `CONFIG_RENAME_INVALID` with `reason`:Without a hint, a renamed entry is a new entry: it keeps no key, and the tombstones stay on the oldname.+## Azure groups++`endpoints.azureOpenAI.groups` merges by `group` the same way (`features.azureGroupMergeKey`) and+takes the same keyed paths: `endpoints.azureOpenAI.groups["<group>"]` hides an inherited group,+and `endpoints.azureOpenAI.groups["<group>"].<path>` a field inside one. A group's `apiKey` and its+preview are written with the group, never by its key. The Azure clients read what the groups+resolve to, so a hidden group or field takes effect only where the deployment resolves the groups+a profile leaves (`CONFIG_REDERIVE_ENDPOINTS=true`, `features.endpointRederive`): the groups left+are resolved again, and a group that no longer resolves once a field inside it is hidden is not+served. Without it, the tombstone is stored and inert, as the profile's group overrides are.+## After upgradingBefore keyed paths, a tombstone such as `endpoints.custom["Name"]` was accepted and stored but haddiff --git a/packages/api/src/admin/config.changes.integration.spec.ts b/packages/api/src/admin/config.changes.integration.spec.tsindex 9592da35b6..ebae1e89cb 100644--- a/packages/api/src/admin/config.changes.integration.spec.ts+++ b/packages/api/src/admin/config.changes.integration.spec.ts@@ -1385,6 +1385,82 @@ describe('POST …/changes: entries librechat.yaml owns', () => {expect((await storedDocument(params.principalId))!.tombstones).toEqual(['endpoints.agents']);});+ it('skips a set or tombstone of a derived field and strips one a set above it carries', async () => {+ const params = nextParams();+ const stale = { projectId: 'x', serviceKeyFile: 'http://169.254.169.254/latest' };+ const skippedOnly = [+ { op: 'set', fieldPath: 'endpoints.anthropic.vertexConfig', value: stale },+ { op: 'tombstone', fieldPath: 'endpoints.anthropic.vertexConfig' },+ { op: 'set', fieldPath: 'endpoints.anthropic.vertexConfig.projectId', value: 'y' },+ ];+ for (const op of skippedOnly) {+ const { status, body } = await send({ ops: [op] }, params);+ expect(status).toBe(200);+ expect(body.skipped).toEqual([+ {+ opIndex: 0,+ op: op.op,+ segments: op.fieldPath.split('.'),+ reason: 'derived_path',+ },+ ]);+ expect(body.applied).toEqual([]);+ }+ expect(await storedDocument(params.principalId)).toBeNull();++ const { status, body } = await send(+ {+ ops: [+ {+ op: 'set',+ fieldPath: 'endpoints.anthropic',+ value: { titleModel: 'claude-haiku-4-5', vertexConfig: stale },+ },+ ],+ },+ params,+ );++ expect(status).toBe(200);+ expect(body.skipped).toEqual([+ {+ opIndex: 0,+ op: 'set',+ segments: ['endpoints', 'anthropic', 'vertexConfig'],+ reason: 'derived_path',+ },+ ]);+ expect(body.applied.map((ref) => ref.opIndex)).toEqual([0]);+ const stored = await storedDocument(params.principalId);+ expect(stored!.overrides).toEqual({+ endpoints: { anthropic: { titleModel: 'claude-haiku-4-5' } },+ });+ expect(stored!.tombstones).toEqual([]);+ });++ it('lets an unset clear a derived field an older server stored', async () => {+ const params = nextParams();+ await seedDocument(+ params.principalId,+ {+ endpoints: { anthropic: { titleModel: 'claude-haiku-4-5', vertexConfig: { region: 'x' } } },+ },+ [],+ );++ const { status, body } = await send(+ { ops: [{ op: 'unset', fieldPath: 'endpoints.anthropic.vertexConfig' }] },+ params,+ );++ expect(status).toBe(200);+ expect(body.skipped).toEqual([]);+ expect(body.applied.map(({ opIndex, op }) => [opIndex, op])).toEqual([[0, 'unset']]);+ expect((await storedDocument(params.principalId))!.overrides).toEqual({+ endpoints: { anthropic: { titleModel: 'claude-haiku-4-5' } },+ });+ });+it('refuses a rename under a YAML stdio server, but not an unset there', async () => {const params = nextParams();await seedDocument(diff --git a/packages/api/src/admin/config.dotted.integration.spec.ts b/packages/api/src/admin/config.dotted.integration.spec.tsindex eeacb9da17..26f1d6c749 100644--- a/packages/api/src/admin/config.dotted.integration.spec.ts+++ b/packages/api/src/admin/config.dotted.integration.spec.ts@@ -10,6 +10,8 @@ import type { ServerRequest } from '~/types/http';process.env.CREDS_KEY =process.env.CREDS_KEY ?? '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';process.env.CREDS_IV = process.env.CREDS_IV ?? '0123456789abcdef0123456789abcdef';+/** An Azure group a write stores must resolve, its `${AZURE_API_KEY}` included. */+process.env.AZURE_API_KEY = process.env.AZURE_API_KEY ?? 'test-azure-key';type DataSchemas = typeof import('@librechat/data-schemas');type Doc = Record<string, unknown>;@@ -151,7 +153,16 @@ describe('admin config writes keep dotted record keys (real sanitizer, handlersawait putOverrides(role, {endpoints: {azureOpenAI: {- groups: [{ group: 'eastus', apiKey: '${AZURE_API_KEY}', instanceName: 'east', models }],+ groups: [+ {+ group: 'eastus',+ apiKey: '${AZURE_API_KEY}',+ instanceName: 'east',+ deploymentName: 'gpt-41',+ version: '2024-10-21',+ models,+ },+ ],},},}).expect(201);@@ -372,7 +383,14 @@ describe('admin config writes on an engine that cannot store dotted keys', () =>endpoints: {azureOpenAI: {groups: [- { group: 'eastus', apiKey: '${AZURE_API_KEY}', models: { 'gpt-4.1': true } },+ {+ group: 'eastus',+ apiKey: '${AZURE_API_KEY}',+ instanceName: 'east',+ deploymentName: 'gpt-41',+ version: '2024-10-21',+ models: { 'gpt-4.1': true },+ },],},},diff --git a/packages/api/src/admin/config.integration.spec.ts b/packages/api/src/admin/config.integration.spec.tsindex 3e79f0265c..4c71688401 100644--- a/packages/api/src/admin/config.integration.spec.ts+++ b/packages/api/src/admin/config.integration.spec.ts@@ -207,6 +207,80 @@ describe('admin config writes against a real Config collection', () => {});});+ describe('fields the server derives', () => {+ const stale = { projectId: 'x', serviceKeyFile: 'http://169.254.169.254/latest' };+ const params = { principalType: ROLE, principalId: 'derived' };++ it('leaves them out of a whole-document write, a field write and a tombstone', async () => {+ const handlers = handlersFor(async () => true);+ const put = mockRes();+ await handlers.upsertConfigOverrides(+ mockReq({+ params,+ body: {+ overrides: {+ endpoints: { anthropic: { titleModel: 'claude-haiku-4-5', vertexConfig: stale } },+ },+ },+ }),+ put,+ );+ expect(put.statusCode).toBe(201);+ expect((await readStored('derived'))?.overrides).toEqual({+ endpoints: { anthropic: { titleModel: 'claude-haiku-4-5' } },+ });++ const patched = mockRes();+ await handlers.patchConfigField(+ mockReq({+ params,+ body: {+ entries: [+ { fieldPath: 'endpoints.anthropic.vertexConfig', value: stale },+ {+ fieldPath: 'endpoints.anthropic',+ value: { titleModel: 'claude-sonnet-4-6', vertexConfig: stale },+ },+ { fieldPath: 'endpoints.google', value: { vertexConfig: stale } },+ ],+ },+ }),+ patched,+ );+ expect(patched.statusCode).toBe(200);+ expect((await readStored('derived'))?.overrides).toEqual({+ endpoints: {+ anthropic: { titleModel: 'claude-sonnet-4-6' },+ google: { vertexConfig: stale },+ },+ });++ const tombstoned = mockRes();+ await handlers.tombstoneConfigField(+ mockReq({ params, body: { fieldPath: 'endpoints.anthropic.vertexConfig' } }),+ tombstoned,+ );+ expect(tombstoned.statusCode).toBe(200);+ expect((await readStored('derived'))?.tombstones ?? []).toEqual([]);+ });++ it('stores nothing from a whole-document write that holds only a derived field', async () => {+ const handlers = handlersFor(async () => true);+ const put = mockRes();+ await handlers.upsertConfigOverrides(+ mockReq({+ params,+ body: { overrides: { endpoints: { anthropic: { vertexConfig: stale } } } },+ }),+ put,+ );++ expect(put.statusCode).toBe(200);+ expect(put.body?.message).toBe('No actionable override sections provided');+ expect(await readStored('derived')).toBeNull();+ });+ });+describe('write responses', () => {const params = { principalType: ROLE, principalId: 'editors' };diff --git a/packages/api/src/admin/config.ts b/packages/api/src/admin/config.tsindex c505ec2a36..3db4dbe047 100644--- a/packages/api/src/admin/config.ts+++ b/packages/api/src/admin/config.ts@@ -1,6 +1,7 @@import {BASE_PRINCIPAL_CONFIG_SECTIONS,BASE_ONLY_CONFIG_SECTIONS,+ DERIVED_CONFIG_PATHS,configSchema,PrincipalType,PrincipalModel,@@ -67,6 +68,7 @@ import {isConfigRevisionConflict,ConfigRevisionConflictError,isConfigOverrideStateEmpty,+ isVertexConfigured,toConfigDraft,toConfigIdentityPath,renameConfigIdentityPath,@@ -113,6 +115,7 @@ import type {ConfigMutationOutcome,ConfigMutationPlan,ConfigIdentityStep,+ ConfigDerivation,ConfigEntryStep,ConfigLocation,ConfigEntryRename,@@ -179,6 +182,7 @@ import { createAdminAuditEmitter, configTarget } from './audit';import { DEFAULT_OVERRIDE_CACHE_TTL } from '~/app/service';import { getSafeErrorMetadata } from '~/utils/errors';import { mergeOverrideLayers } from '~/app/overrides';+import { expandCustomEndpoint } from '~/app/params';const UNSAFE_SEGMENTS = /(?:^|\.)(__[\w]*|constructor|prototype)(?:\.|$)/;const MAX_PATCH_ENTRIES = 100;@@ -464,6 +468,7 @@ function getPatchStepIssues(floor: Partial<TCustomConfig>,stored: ConfigRecord | null,renames: readonly ConfigEntryRename[],+ derivation: ConfigDerivation,): ConfigOverrideIssue[] {const written = steps.flatMap((step) =>'write' in step ? [[...step.write.segments]] : step.reset.map(({ segments }) => [...segments]),@@ -477,7 +482,7 @@ function getPatchStepIssues(applyPatchSteps(toConfigOverrideState(stored), steps),renames,);- return getConfigChangeIssues(candidate, floor, stored, written, lifted);+ return getConfigChangeIssues(candidate, floor, stored, written, lifted, derivation);}/** Applies a patch's steps in order to the stored document's state. */@@ -664,6 +669,8 @@ const SKIP_DESCRIPTIONS: Readonly<Record<AdminConfigSkipReason, string>> = {dedicated_section: 'dedicated tenant-wide config field %s in the generic config API',interface_permission: 'interface permission field %s — use role permissions instead',process_mcp_server: 'override of process-backed MCP server %s - configure it in librechat.yaml',+ derived_path:+ 'derived config path %s - the server derives it from the field it resolves, write that instead',};/** Logs a skipped path; `action` is how the route words it (`Stripping`, `Ignoring tombstone for`). */@@ -673,12 +680,38 @@ function logSkippedField(action: string, fieldPath: string, reason: AdminConfigS);}+/** A field the generic config API never stores a value at, and why. */+interface HeldPath {+ segments: readonly string[];+ reason: YamlHeldPath['reason'] | 'derived_path';+}++/** Fields the server derives from another one (`rules.derivedPaths`), which the merge never applies. */+const DERIVED_HELD_PATHS: readonly HeldPath[] = DERIVED_CONFIG_PATHS.map((path) => ({+ segments: path.split('.'),+ reason: 'derived_path',+}));++let writeHeldPaths: readonly HeldPath[] | undefined;++/**+ * Fields only librechat.yaml sets (`YAML_HELD_PATHS`) and derived fields: no write stores them.+ * Built on first use rather than at import, as the other readers of `YAML_HELD_PATHS` do.+ */+function getWriteHeldPaths(): readonly HeldPath[] {+ writeHeldPaths ??= [...YAML_HELD_PATHS, ...DERIVED_HELD_PATHS];+ return writeHeldPaths;+}+/*** Why a write or tombstone at `segments` is skipped because the path is, or lies inside, a field- * only librechat.yaml sets. Removing a stored value there is cleanup and is never skipped.+ * only librechat.yaml sets or one the server derives. Removing a stored value there is cleanup+ * and is never skipped.*/-function getHeldPathSkipReason(segments: readonly string[]): YamlHeldPath['reason'] | null {- return YAML_HELD_PATHS.find((held) => isSegmentPrefix(held.segments, segments))?.reason ?? null;+function getHeldPathSkipReason(segments: readonly string[]): HeldPath['reason'] | null {+ return (+ getWriteHeldPaths().find((held) => isSegmentPrefix(held.segments, segments))?.reason ?? null+ );}/** A part of a written value the API does not store, at its full location. */@@ -688,9 +721,10 @@ interface SkippedPart {}/**- * Removes the fields only librechat.yaml sets below `segments` from a value written there- * (`endpoints.agents` carrying `pullRequests.provider` or `eventDriven`), with the objects that- * leaves empty. Returns the value to store and the parts it removed.+ * Removes the fields only librechat.yaml sets, and the derived ones, below `segments` from a value+ * written there (`endpoints.agents` carrying `pullRequests.provider` or `eventDriven`,+ * `endpoints.anthropic` carrying `vertexConfig`), with the objects that leaves empty. Returns the+ * value to store and the parts it removed.*/function stripHeldPaths(segments: readonly string[],@@ -698,7 +732,7 @@ function stripHeldPaths(): { value: unknown; stripped: SkippedPart[] } {let result = value;const stripped: SkippedPart[] = [];- for (const { segments: path, reason } of YAML_HELD_PATHS) {+ for (const { segments: path, reason } of getWriteHeldPaths()) {if (path.length <= segments.length || !isSegmentPrefix(segments, path)) {continue;}@@ -962,6 +996,22 @@ export interface AdminConfigDeps {* app config service is given, so a write is judged by the policy its values resolve under.*/overrideEnvAllowlist?: string;+ /**+ * Whether the app config service derives Azure groups, Vertex AI and the Azure Assistants+ * endpoint from overrides again (`CONFIG_REDERIVE_ENDPOINTS`): `GET /meta` reports it as+ * `features.endpointRederive`, and write responses judge what a write drops by the same merge.+ */+ rederiveEndpoints?: boolean;+}++/**+ * What writes over `yaml` (librechat.yaml) are checked against beyond the schema: the custom+ * endpoint parameter definitions startup would expand (`invalid_param_definitions`), and whether+ * librechat.yaml configures the Vertex AI a write may turn on, besides the derived checks the+ * store always runs (Azure groups, Vertex AI, model spec endpoints).+ */+function getWriteDerivation(yaml: Partial<TCustomConfig> | null): ConfigDerivation {+ return { expandCustomEndpoint, vertexConfigured: isVertexConfigured(yaml) };}// ── Validation helpers ───────────────────────────────────────────────@@ -1782,7 +1832,10 @@ function getKeptKeyReentryIssues(stored,candidate,entered,- baseGroupMap: baseConfig?.endpoints?.[EModelEndpoint.azureOpenAI]?.groupMap,+ base: {+ groups: baseConfig?.config?.endpoints?.[EModelEndpoint.azureOpenAI]?.groups,+ groupMap: baseConfig?.endpoints?.[EModelEndpoint.azureOpenAI]?.groupMap,+ },}),...getBoundKeyReentryIssues({ stored, candidate, entered, baseConfig }),];@@ -2210,7 +2263,7 @@ function prepareChange(raw: unknown, index: number): PreparedRead {if (removalError) {return changeFailure(index, removalError.error, removalError.code);}- /** Unsetting a stored field only librechat.yaml sets is cleanup: only a tombstone is skipped. */+ /** Unsetting a stored held or derived field is cleanup: only a tombstone is skipped. */const skipReason =sectionSkip ?? (op === 'tombstone' ? getHeldPathSkipReason(target.segments) : null);const change: PreparedChange = {@@ -2537,6 +2590,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {auditFailClosed,overrideCacheTtlMs = DEFAULT_OVERRIDE_CACHE_TTL,overrideEnvAllowlist,+ rederiveEndpoints = false,} = deps;const envAllowlist = parseEnvAllowlist(overrideEnvAllowlist);@@ -2819,6 +2873,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {const ignored: AdminConfigIgnoredSecret[] = [];mergeOverrideLayers(baseConfig, floor ? [floor, written] : [written], {envPolicy,+ rederiveEndpoints,onRebinding: (rebinding) => {if (rebinding.layer.principalType === written.principalType &&@@ -2886,7 +2941,13 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {}try {const baseYaml: Partial<TCustomConfig> = baseConfig.config ?? {};- const overrides = getIgnoredConfigOverrides(baseYaml, stored, base ? [base] : [], baseConfig);+ const overrides = getIgnoredConfigOverrides(+ baseYaml,+ stored,+ base ? [base] : [],+ baseConfig,+ { expandCustomEndpoint, rederiveEndpoints },+ );const secrets = await reportIgnored(stored, tenantId, {baseConfig,envPolicy: getEnvPolicy(baseYaml),@@ -2910,7 +2971,9 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {* beside it. A profile can then enter its own key for an endpoint, server or service Base* defines without restating the destination, and the key is dropped again once Base, or any* layer below the profile, moves that destination. Base merges first, so nothing moves its- * keys from below.+ * keys from below. Destinations are judged as with `CONFIG_REDERIVE_ENDPOINTS` on, whatever+ * this deployment runs with, so a key entered for an Azure group while the groups are inert+ * keeps its destination once they apply.*/function bindPlannedSecrets(params: {principalType: PrincipalType;@@ -2941,6 +3004,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {};mergeOverrideLayers(params.baseConfig ?? ({} as AppConfig), [base, layer], {envPolicy: params.envPolicy,+ rederiveEndpoints: true,onRebinding: (rebinding) => {if (rebinding.binding != null &&@@ -3058,7 +3122,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {if (yaml == null) {return {};}- return base ? resolveRawConfig(yaml, [base]) : yaml;+ return base ? resolveRawConfig(yaml, [base], getWriteDerivation(yaml)) : yaml;};const outcome = await runConfigMutation<T>({@@ -3179,13 +3243,16 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {}const baseConfig = await getBaseAppConfig(user.tenantId);- const meta = buildAdminConfigMeta({- maxPatchEntries: MAX_PATCH_ENTRIES,- maxChangeOps: MAX_CONFIG_CHANGE_OPS,- maxEntryKeyLength: MAX_CONFIG_ENTRY_KEY_LENGTH,- overrideCacheTtlMs,- catalogModelsTtlMs: getCatalogModelsTtlMs(baseConfig),- });+ const meta = buildAdminConfigMeta(+ {+ maxPatchEntries: MAX_PATCH_ENTRIES,+ maxChangeOps: MAX_CONFIG_CHANGE_OPS,+ maxEntryKeyLength: MAX_CONFIG_ENTRY_KEY_LENGTH,+ overrideCacheTtlMs,+ catalogModelsTtlMs: getCatalogModelsTtlMs(baseConfig),+ },+ { rederiveEndpoints },+ );return res.status(200).json(meta);} catch (error) {logger.error('[adminConfig] getConfigMeta error:', getSafeErrorMetadata(error));@@ -3509,6 +3576,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {const issues = getConfigOverrideIssues(preserved,applyConfigTombstones(floor, storedState.tombstones),+ getWriteDerivation(yaml),);if (issues.length > 0) {return { draft: null, result: { status: 400, issues } };@@ -3866,8 +3934,14 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {/** A renamed custom endpoint's keyed tombstones move to its new name. */const entryRenames = toEntryRenames(renames.renames);const fieldIssues = hasResets- ? getPatchStepIssues(steps, floor, stored, entryRenames)- : getConfigFieldIssues(writes, floor, stored, entryRenames);+ ? getPatchStepIssues(steps, floor, stored, entryRenames, getWriteDerivation(baseYaml))+ : getConfigFieldIssues(+ writes,+ floor,+ stored,+ entryRenames,+ getWriteDerivation(baseYaml),+ );if (fieldIssues.length > 0) {return { draft: null, result: { status: 400, issues: fieldIssues } };}@@ -4548,7 +4622,14 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {* and which must not be blamed on the removal.*/const attributable = written.filter((segments) => isAcceptedOverrideSection(segments[0]));- const issues = getConfigChangeIssues(state, floor, stored, attributable);+ const issues = getConfigChangeIssues(+ state,+ floor,+ stored,+ attributable,+ [],+ getWriteDerivation(baseYaml),+ );if (issues.length > 0) {return { draft: null, result: { stop: { kind: 'issues', issues } } };}diff --git a/packages/api/src/admin/meta.spec.ts b/packages/api/src/admin/meta.spec.tsindex a850e1030d..7945be46d0 100644--- a/packages/api/src/admin/meta.spec.ts+++ b/packages/api/src/admin/meta.spec.ts@@ -21,6 +21,7 @@ import {import {Constants,PrincipalType,+ AgentCapabilities,PrincipalModel,configSchema,RerankerTypes,@@ -29,6 +30,7 @@ import {ScraperProviders,PERMISSION_SUB_KEYS,BASE_ONLY_CONFIG_PATHS,+ DERIVED_CONFIG_PATHS,BASE_ONLY_CONFIG_SECTIONS,PROCESS_MCP_SERVER_FIELDS,DEPLOYMENT_ONLY_CONFIG_PATHS,@@ -38,6 +40,7 @@ import {RUNTIME_CONFIG_INTERFACE_FIELDS,} from 'librechat-data-provider';import type {+ AdminConfigChangesResponse,AdminConfigFeatureFlag,AdminResolvedConfigResponse,AdminConfigCatalogResponse,@@ -75,6 +78,7 @@ import { resolveTitleConfig } from '~/endpoints/config';import { createAppConfigService } from '~/app/service';import { mergeOverrideLayers } from '~/app/overrides';import { createAdminConfigHandlers } from './config';+import { expandCustomEndpoint } from '~/app/params';import { createAdminRolesHandlers } from './roles';import { ConfigReloadError } from '~/app/loader';import { ADMIN_CONFIG_FEATURES } from './meta';@@ -87,6 +91,7 @@ jest.mock('@librechat/data-schemas', () => {});type Doc = Record<string, unknown>;+type AppServiceConfig = NonNullable<Parameters<typeof AppService>[0]>['config'];type ResponseBody = { config?: { overrides: Doc; revision?: string }; [key: string]: unknown };type MockRes = Response & { statusCode: number; body: ResponseBody | undefined };type MockReqInit = Omit<Partial<ServerRequest>, 'body'> & { body?: object };@@ -140,12 +145,43 @@ function createHandlers(overrides: Partial<AdminConfigDeps> = {}) {});}-async function getMeta(): Promise<{ status: number; meta: AdminConfigMeta }> {+async function getMeta(+ deps: Partial<AdminConfigDeps> = {},+): Promise<{ status: number; meta: AdminConfigMeta }> {const res = mockRes();- await createHandlers().getConfigMeta(mockReq(), res);+ await createHandlers(deps).getConfigMeta(mockReq(), res);return { status: res.statusCode, meta: res.body as AdminConfigMeta };}+/** A server with every switch a deployment can turn on, on: what `ADMIN_CONFIG_FEATURES` lists. */+const SWITCHES_ON: Partial<AdminConfigDeps> = { rederiveEndpoints: true };++/** An app config service over `config` (librechat.yaml) and stored `layers`, as the server builds it. */+function serviceOver(+ config: Doc,+ layers: ConfigRecord[],+ options: { rederiveEndpoints?: boolean } = {},+) {+ const entries = new Map<string, unknown>();+ return createAppConfigService({+ loadBaseConfig: () =>+ AppService({+ config: structuredClone(config) as AppServiceConfig,+ expandCustomEndpoint,+ }),+ setCachedTools: async () => undefined,+ getCache: () => ({+ get: async (key: string) => entries.get(key),+ set: async (key: string, value: unknown) => entries.set(key, value),+ delete: async (key: string) => entries.delete(key),+ }),+ cacheKeys: { APP_CONFIG: 'app_config' },+ getApplicableConfigs: jest.fn().mockResolvedValue(layers),+ getUserPrincipals: async () => [],+ ...options,+ });+}+async function write(handler: WriteHandler,init: MockReqInit,@@ -306,11 +342,14 @@ describe('GET /api/admin/config/meta', () => {expect(Object.keys(meta.features).sort()).toEqual(['adminTermsExempt','awaitedInvalidation',+ 'azureGroupMergeKey','azureGroupSecrets','catalogApi','changesBatch',+ 'customParamsExpansion','deterministicPrecedence','dottedKeys',+ 'endpointRederive','envAllowlist','envStatus','expectedRevision',@@ -328,6 +367,7 @@ describe('GET /api/admin/config/meta', () => {'roleRenameMovesProfile','secretRebinding','sectionAllowlist',+ 'specInterfaceRederive','webSearchStoredKeys','writeReport','yamlMcpHide',@@ -349,6 +389,7 @@ describe('GET /api/admin/config/meta', () => {'baseOnlySections','basePrincipalSections','deploymentOnlyPaths',+ 'derivedPaths','interface','overrideKeyMap','processMcpFields',@@ -360,8 +401,11 @@ describe('GET /api/admin/config/meta', () => {]);});- it('reports every admin config behaviour this server ships as on', async () => {- const { meta } = await getMeta();+ it('reports every admin config behaviour this server ships as on, switches as the deployment sets them', async () => {+ const off = await getMeta();+ const on = await getMeta(SWITCHES_ON);+ expect(off.meta.features).toEqual({ ...on.meta.features, endpointRederive: false });+ const { meta } = on;expect(meta.features).toEqual({dottedKeys: true,sectionAllowlist: true,@@ -391,6 +435,10 @@ describe('GET /api/admin/config/meta', () => {adminTermsExempt: true,keyedTombstones: true,renameHints: true,+ azureGroupMergeKey: true,+ customParamsExpansion: true,+ specInterfaceRederive: true,+ endpointRederive: true,});});@@ -428,6 +476,7 @@ describe('meta rules equal the rules the server applies', () => {expect(meta.rules.basePrincipalSections).toEqual([...BASE_PRINCIPAL_CONFIG_SECTIONS]);expect(meta.rules.baseOnlyPaths).toEqual([...BASE_ONLY_CONFIG_PATHS]);expect(meta.rules.deploymentOnlyPaths).toEqual({ ...DEPLOYMENT_ONLY_CONFIG_PATHS });+ expect(meta.rules.derivedPaths).toEqual([...DERIVED_CONFIG_PATHS]);expect(meta.rules.processMcpFields).toEqual([...PROCESS_MCP_SERVER_FIELDS]);expect(meta.rules.interface).toEqual({permissionFields: [...INTERFACE_PERMISSION_FIELDS],@@ -1386,12 +1435,15 @@ const FEATURE_PROBES: Record<AdminConfigFeatureFlag, () => Promise<boolean>> = {'endpoints.azureOpenAI.groups': [group('azure-admin-secret-key')],})['endpoints.azureOpenAI.groups'] as Doc[];const encrypted = String(stored.apiKey).startsWith('v3:');- /** The Azure client is built with the key a profile's group holds, decrypted. */+ /**+ * The Azure client is built with the key a profile's group holds, decrypted, where the merge+ * resolves a profile's groups (`endpointRederive`).+ */const runtime = resolveRuntimeConfigSecrets(mergeOverrideLayers({ config: {} } as AppConfig,[storedConfig({ endpoints: { azureOpenAI: { groups: [stored] } } })],- { envPolicy: createEnvReferencePolicy({ config: {} }) },+ { envPolicy: createEnvReferencePolicy({ config: {} }), rederiveEndpoints: true },),);const azure = runtime.endpoints?.azureOpenAI;@@ -1512,20 +1564,27 @@ const FEATURE_PROBES: Record<AdminConfigFeatureFlag, () => Promise<boolean>> = {[storedConfig({ ocr: { apiKey: '${UNLISTED_NAME}' } })],{ envPolicy: createEnvReferencePolicy({ config: {} }) },);- const refused = (res: MockRes) =>+ /** Reads return Vertex AI's derived settings resolved: only librechat.yaml's Vertex names. */+ const vertexYaml = { endpoints: { anthropic: { vertex: { projectId: '${GCP_PROJECT}' } } } };+ const vertexWrite = (value: string) =>+ patch([{ fieldPath: 'endpoints.anthropic.vertex.projectId', value }], {+ getAppConfig: jest.fn().mockResolvedValue({ config: vertexYaml }),+ });+ const vertexCredential = await vertexWrite('${OPENAI_API_KEY}');+ process.env.GCP_PROJECT = 'yaml-gcp-project';+ const vertexYamlNamed = await vertexWrite('${GCP_PROJECT}').finally(() => {+ delete process.env.GCP_PROJECT;+ });+ const refused = (res: MockRes, segments: string[]) =>res.statusCode === 400 &&JSON.stringify(res.body?.issues) ===- JSON.stringify([- {- path: res === unlisted ? 'ocr.baseURL' : 'ocr.apiKey',- segments: ['ocr', res === unlisted ? 'baseURL' : 'apiKey'],- code: 'env_reference_not_allowed',- },- ]);+ JSON.stringify([{ path: segments.join('.'), segments, code: 'env_reference_not_allowed' }]);return (- refused(unlisted) &&- refused(batch) &&+ refused(unlisted, ['ocr', 'baseURL']) &&+ refused(batch, ['ocr', 'apiKey']) &&+ refused(vertexCredential, ['endpoints', 'anthropic', 'vertex', 'projectId']) &&yamlNamed.statusCode === 200 &&+ vertexYamlNamed.statusCode === 200 &&merged.ocr?.apiKey === '');},@@ -1580,6 +1639,309 @@ const FEATURE_PROBES: Record<AdminConfigFeatureFlag, () => Promise<boolean>> = {restated.body?.ignored === undefined);},+ async azureGroupMergeKey() {+ const east = {+ group: 'east',+ apiKey: 'east-key-literal',+ instanceName: 'east',+ version: '2024-10-21',+ deploymentName: 'gpt-4o',+ models: { 'gpt-4o': true },+ };+ const yaml = { endpoints: { azureOpenAI: { groups: [east] } } };+ const base = await AppService({ config: structuredClone(yaml) as AppServiceConfig });+ const getAppConfig = jest.fn().mockResolvedValue(base);+ const mini = { group: 'east', models: { 'gpt-4o-mini': { deploymentName: 'mini' } } };+ const merged = mergeOverrideLayers(+ base,+ [storedConfig({ endpoints: { azureOpenAI: { groups: [mini] } } })],+ { envPolicy: createEnvReferencePolicy({ config: yaml }), rederiveEndpoints: true },+ );+ const indexed = await patch(+ [{ fieldPath: 'endpoints.azureOpenAI.groups.0.instanceName', value: 'elsewhere' }],+ { getAppConfig },+ );+ const duplicate = await patch(+ [+ {+ fieldPath: 'endpoints.azureOpenAI.groups',+ value: [{ ...east, group: 'west', apiKey: 'west-key-literal', instanceName: 'west' }],+ },+ ],+ { getAppConfig },+ );+ const upsert = mockRes();+ await createHandlers({ getAppConfig }).applyConfigChanges(+ mockReq({+ params: { principalType: 'role', principalId: 'r1' },+ body: {+ ops: [{ op: 'upsertEntry', fieldPath: 'endpoints.azureOpenAI.groups', entry: mini }],+ },+ }),+ upsert,+ );+ const { meta } = await getMeta();+ return (+ meta.rules.arrayMergeKeys['endpoints.azureOpenAI.groups'] === 'group' &&+ JSON.stringify(merged.endpoints?.azureOpenAI?.modelNames) === '["gpt-4o","gpt-4o-mini"]' &&+ merged.endpoints?.azureOpenAI?.groupMap?.east?.apiKey === 'east-key-literal' &&+ indexed.statusCode === 400 &&+ JSON.stringify(indexed.body?.issues).includes('indexed_merge_key_write') &&+ duplicate.statusCode === 400 &&+ JSON.stringify(duplicate.body?.issues) ===+ JSON.stringify([+ {+ path: 'endpoints.azureOpenAI.groups',+ segments: ['endpoints', 'azureOpenAI', 'groups'],+ code: 'invalid_azure_groups',+ },+ ]) &&+ upsert.statusCode === 200+ );+ },+ async customParamsExpansion() {+ const compact = {+ defaultParamsEndpoint: 'anthropic',+ paramDefinitions: [{ key: 'temperature', default: 0.2 }],+ };+ const gateway = {+ name: 'Gateway',+ apiKey: 'gateway-key-literal',+ baseURL: 'https://gateway.example.com/v1',+ models: { default: ['m1'] },+ customParams: compact,+ };+ const yaml = { endpoints: { custom: [gateway] } };+ const openRouter = {+ name: 'OpenRouter',+ apiKey: 'openrouter-key-literal',+ baseURL: 'https://openrouter.example.com/v1',+ models: { default: ['m2'] },+ };+ const layer = storedConfig({+ endpoints: {+ custom: [+ {+ name: 'Gateway',+ customParams: { defaultParamsEndpoint: 'openAI', paramDefinitions: [{ key: 'top_p' }] },+ },+ openRouter,+ ],+ },+ });+ const service = serviceOver(yaml, [layer]);+ const base = await service.getAppConfig({ baseOnly: true });+ const merged = await service.getAppConfig({ role: 'r1' });+ const served = (name: string) =>+ merged.endpoints?.custom?.find((endpoint) => endpoint.name === name)?.customParams;+ const invalid = await patch(+ [+ {+ fieldPath: 'endpoints.custom',+ value: [{ name: 'Gateway', customParams: { paramDefinitions: [{ key: 'notAParam' }] } }],+ },+ ],+ { getAppConfig: jest.fn().mockResolvedValue(base) },+ );+ return (+ JSON.stringify(base.config.endpoints?.custom?.[0]?.customParams) ===+ JSON.stringify(compact) &&+ base.endpoints?.custom?.[0]?.customParams?.paramDefinitions?.[0]?.optionType === 'custom' &&+ served('Gateway')?.defaultParamsEndpoint === 'openAI' &&+ served('Gateway')?.paramDefinitions?.[0]?.key === 'top_p' &&+ served('Gateway')?.paramDefinitions?.[0]?.component != null &&+ served('OpenRouter')?.paramDefinitions?.some((param) => param.key === 'promptCache') ===+ true &&+ invalid.statusCode === 400 &&+ JSON.stringify(invalid.body?.issues) ===+ JSON.stringify([+ {+ path: 'endpoints.custom.0.customParams',+ segments: ['endpoints', 'custom', '0', 'customParams'],+ code: 'invalid_param_definitions',+ },+ ])+ );+ },+ async specInterfaceRederive() {+ const yaml = { memory: { disabled: true } };+ const spec = { name: 'spec', label: 'Spec', preset: { endpoint: 'openAI', model: 'gpt-4o' } };+ const service = serviceOver(yaml, [+ storedConfig({ modelSpecs: { list: [spec] }, memory: { disabled: false } }),+ ]);+ const base = await service.getAppConfig({ baseOnly: true });+ const merged = await service.getAppConfig({ role: 'r1' });+ const gateway = {+ name: 'Gateway',+ apiKey: 'gateway-key',+ baseURL: 'https://gateway.example.com/v1',+ models: { default: ['m1'] },+ };+ const hidden = await serviceOver(+ {+ endpoints: { custom: [gateway] },+ modelSpecs: { list: [{ ...spec, preset: { endpoint: 'Gateway', model: 'm1' } }] },+ },+ [storedConfig({}, ['endpoints.custom'])],+ ).getAppConfig({ role: 'r1' });+ const unknown = await patch(+ [+ {+ fieldPath: 'modelSpecs.list',+ value: [{ ...spec, preset: { endpoint: 'Nowhere', model: 'm' } }],+ },+ ],+ { getAppConfig: jest.fn().mockResolvedValue(base) },+ );+ const { modelSelect, parameters, presets } = merged.interfaceConfig ?? {};+ return (+ base.interfaceConfig?.parameters === true &&+ [modelSelect, parameters, presets].every((value) => value === false) &&+ !base.endpoints?.agents?.capabilities?.includes(AgentCapabilities.memory) &&+ merged.endpoints?.agents?.capabilities?.includes(AgentCapabilities.memory) === true &&+ hidden.modelSpecs === undefined &&+ hidden.interfaceConfig?.parameters === true &&+ unknown.statusCode === 400 &&+ JSON.stringify(unknown.body?.issues) ===+ JSON.stringify([+ {+ path: 'modelSpecs.list.0.preset.endpoint',+ segments: ['modelSpecs', 'list', '0', 'preset', 'endpoint'],+ code: 'unknown_spec_endpoint',+ },+ ])+ );+ },+ async endpointRederive() {+ const east = {+ group: 'east',+ apiKey: 'east-key-literal',+ instanceName: 'east',+ version: '2024-10-21',+ deploymentName: 'gpt-4o',+ models: { 'gpt-4o': true },+ };+ const yaml = {+ endpoints: {+ anthropic: {+ vertex: {+ projectId: 'yaml-project',+ region: 'us-east5',+ serviceKeyFile: '/keys/vertex.json',+ models: ['claude-sonnet-4-6'],+ },+ },+ azureOpenAI: { groups: [east] },+ },+ };+ const layer = storedConfig({+ endpoints: {+ anthropic: {+ vertex: {+ models: ['claude-opus-4-6'],+ serviceKeyFile: 'http://169.254.169.254/key',+ region: 'elsewhere',+ },+ },+ azureOpenAI: {+ groups: [{ group: 'east', models: { 'gpt-4o-mini': { deploymentName: 'mini' } } }],+ },+ },+ });+ const served = async (rederiveEndpoints: boolean) =>+ (await serviceOver(yaml, [layer], { rederiveEndpoints }).getAppConfig({ role: 'r1' }))+ .endpoints;+ const [offEndpoints, onEndpoints] = await Promise.all([served(false), served(true)]);+ const [off, on] = [offEndpoints?.anthropic, onEndpoints?.anthropic];+ const base = await serviceOver(yaml, []).getAppConfig({ baseOnly: true });+ const skipped = mockRes();+ await createHandlers({ getAppConfig: jest.fn().mockResolvedValue(base) }).applyConfigChanges(+ mockReq({+ params: { principalType: 'role', principalId: 'r1' },+ body: {+ ops: [+ {+ op: 'set',+ fieldPath: 'endpoints.anthropic.vertex.serviceKeyFile',+ value: '/etc/other.json',+ },+ {+ op: 'set',+ fieldPath: 'endpoints.anthropic.vertexConfig',+ value: { serviceKeyFile: 'http://169.254.169.254/key' },+ },+ ],+ },+ }),+ skipped,+ );+ /** Vertex AI turned on where librechat.yaml configures none. */+ const unconfigured = await patch(+ [{ fieldPath: 'endpoints.anthropic.vertex', value: { projectId: 'p-1' } }],+ { getAppConfig: jest.fn().mockResolvedValue({ config: {} }) },+ );+ /** A variable librechat.yaml's disabled Vertex AI references, unset, once a profile enables it. */+ const unset = await patch([{ fieldPath: 'endpoints.anthropic.vertex.enabled', value: true }], {+ getAppConfig: jest.fn().mockResolvedValue({+ config: {+ endpoints: {+ anthropic: { vertex: { enabled: false, projectId: '${VERTEX_UNSET_PROJECT}' } },+ },+ },+ }),+ });+ /** A model name, sent as the deployment name as written, that only wraps a ${VAR} reference. */+ process.env.VERTEX_PROBE_PROJECT = 'probe-project';+ const wrapped = await patch(+ [+ {+ fieldPath: 'endpoints.anthropic.vertex.models',+ value: [+ '${VERTEX_PROBE_PROJECT}/../../endpoints/5678:rawPredict#${VERTEX_PROBE_PROJECT}',+ ],+ },+ ],+ {+ getAppConfig: jest.fn().mockResolvedValue({+ config: {+ endpoints: { anthropic: { vertex: { projectId: '${VERTEX_PROBE_PROJECT}' } } },+ },+ }),+ },+ ).finally(() => {+ delete process.env.VERTEX_PROBE_PROJECT;+ });+ const metaOff = (await getMeta()).meta.features.endpointRederive;+ const metaOn = (await getMeta(SWITCHES_ON)).meta.features.endpointRederive;+ return (+ metaOff === false &&+ metaOn === true &&+ JSON.stringify(off?.models) === '["claude-sonnet-4-6"]' &&+ JSON.stringify(on?.models) === '["claude-opus-4-6"]' &&+ JSON.stringify(offEndpoints?.azureOpenAI?.modelNames) === '["gpt-4o"]' &&+ JSON.stringify(onEndpoints?.azureOpenAI?.modelNames) === '["gpt-4o","gpt-4o-mini"]' &&+ on?.vertexConfig?.serviceKeyFile === '/keys/vertex.json' &&+ on?.vertexConfig?.region === 'us-east5' &&+ skipped.statusCode === 200 &&+ JSON.stringify(+ (skipped.body?.skipped as AdminConfigChangesResponse['skipped']).map(+ ({ reason }) => reason,+ ),+ ) === '["base_only_path","derived_path"]' &&+ [unset, unconfigured, wrapped].every(+ (res) =>+ res.statusCode === 400 &&+ JSON.stringify(res.body?.issues) ===+ JSON.stringify([+ {+ path: 'endpoints.anthropic.vertex',+ segments: ['endpoints', 'anthropic', 'vertex'],+ code: 'invalid_vertex_config',+ },+ ]),+ )+ );+ },async resolvedApi() {const yaml = { interface: { customWelcome: 'From YAML' } };const role = storedConfig({ interface: { customWelcome: 'From role', prompts: false } });@@ -2115,7 +2477,7 @@ describe('meta feature flags', () => {it.each(Object.keys(FEATURE_PROBES) as AdminConfigFeatureFlag[])('%s matches what the server does',async (flag) => {- const { meta } = await getMeta();+ const { meta } = await getMeta(SWITCHES_ON);expect(meta.features[flag]).toBe(ADMIN_CONFIG_FEATURES[flag]);expect(meta.features[flag]).toBe(await FEATURE_PROBES[flag]());},diff --git a/packages/api/src/admin/meta.ts b/packages/api/src/admin/meta.tsindex a8058a6c6b..2ea6b7c79e 100644--- a/packages/api/src/admin/meta.ts+++ b/packages/api/src/admin/meta.ts@@ -27,7 +27,8 @@ export function getCatalogModelsTtlMs(config: AppConfig | undefined): number {/*** The admin config behaviours this server has. A change flips its own flag when it wires the* behaviour; `meta.spec.ts` checks every flag against the behaviour itself, so a flag cannot- * claim what the server does not do, nor stay off once it does.+ * claim what the server does not do, nor stay off once it does. `endpointRederive` is reported+ * only where the deployment turns it on (`buildAdminConfigMeta`).*/export const ADMIN_CONFIG_FEATURES: Readonly<AdminConfigFeatures> = {dottedKeys: true,@@ -58,13 +59,30 @@ export const ADMIN_CONFIG_FEATURES: Readonly<AdminConfigFeatures> = {adminTermsExempt: true,keyedTombstones: true,renameHints: true,+ azureGroupMergeKey: true,+ customParamsExpansion: true,+ specInterfaceRederive: true,+ endpointRederive: true,};+/** How this server runs, for the behaviours a deployment switches on. */+export interface AdminConfigRuntime {+ /**+ * `CONFIG_REDERIVE_ENDPOINTS`: Azure groups, Vertex AI and Azure Assistants derived from+ * overrides again.+ */+ rederiveEndpoints?: boolean;+}+/*** The contract `GET /api/admin/config/meta` reports, built from the constants the server- * enforces rather than restated, so the rules a client mirrors cannot drift from them.+ * enforces rather than restated, so the rules a client mirrors cannot drift from them. A flag a+ * deployment switches on (`endpointRederive`) is on only when it is, and implemented.*/-export function buildAdminConfigMeta(limits: AdminConfigMeta['limits']): AdminConfigMeta {+export function buildAdminConfigMeta(+ limits: AdminConfigMeta['limits'],+ runtime: AdminConfigRuntime = {},+): AdminConfigMeta {return {metaVersion: 1,versions: {@@ -72,7 +90,11 @@ export function buildAdminConfigMeta(limits: AdminConfigMeta['limits']): AdminCodataProvider: DATA_PROVIDER_VERSION,configSchema: String(Constants.CONFIG_VERSION),},- features: { ...ADMIN_CONFIG_FEATURES },+ features: {+ ...ADMIN_CONFIG_FEATURES,+ endpointRederive:+ ADMIN_CONFIG_FEATURES.endpointRederive && runtime.rederiveEndpoints === true,+ },limits: { ...limits },rules: {acceptedSections: Object.keys(configSchema.shape),diff --git a/packages/api/src/admin/reentry.spec.ts b/packages/api/src/admin/reentry.spec.tsindex 0066ed4d1c..fec614fd8a 100644--- a/packages/api/src/admin/reentry.spec.ts+++ b/packages/api/src/admin/reentry.spec.ts@@ -331,6 +331,7 @@ describe('getAzureGroupReentryIssues', () => {const yamlGroupMap = {east: { apiKey: 'yaml-literal-key', instanceName: 'east', version: '2024-10-21', models: {} },};+ const yamlBase = { groups: [{ group: 'east', ...yamlGroupMap.east }], groupMap: yamlGroupMap };const group = (overrides: Record<string, unknown> = {}) => ({group: 'west',apiKey: STORED_KEY,@@ -349,7 +350,7 @@ describe('getAzureGroupReentryIssues', () => {return getAzureGroupReentryIssues({stored: document,candidate: setConfigFields(toConfigOverrideState(document), writes),- baseGroupMap: yamlGroupMap,+ base: yamlBase,entered: new Set([ENTERED_KEY]),});}@@ -373,6 +374,28 @@ describe('getAzureGroupReentryIssues', () => {expect(judge(groupsWrite(group({ version: '2025-01-01' })))).toEqual([]);});+ it("judges a partial item merged over librechat.yaml's group of its name", () => {+ const partial: StoredDocument = {+ overrides: {+ endpoints: { azureOpenAI: { groups: [{ group: 'east', apiKey: STORED_KEY }] } },+ },+ tombstones: [],+ };+ const write = (item: Record<string, unknown>) =>+ judge(groupsWrite({ group: 'east', apiKey: STORED_KEY, ...item }), partial);++ expect(write({ models: { 'gpt-4o': { deploymentName: 'gpt-4o', version: 'v' } } })).toEqual([]);+ expect(write({ instanceName: 'east' })).toEqual([]);+ expect(write({ instanceName: 'attacker' })).toEqual([+ {+ path: 'endpoints.azureOpenAI.groups.0.instanceName',+ segments: ['endpoints', 'azureOpenAI', 'groups', '0', 'instanceName'],+ code: 'secret_reentry_required',+ secretPath: 'endpoints.azureOpenAI.groups.0.apiKey',+ },+ ]);+ });+it('judges a group that does not resolve yet, so a later write cannot put the move to use', () => {const unresolved = group({ instanceName: 'attacker', deploymentName: undefined });@@ -392,7 +415,7 @@ describe('getAzureGroupReentryIssues', () => {...toConfigOverrideState(mapped),tombstones: ['endpoints.azureOpenAI.groupMap.east.instanceName'],},- baseGroupMap: yamlGroupMap,+ base: yamlBase,entered: new Set(),});@@ -427,7 +450,7 @@ describe('getAzureGroupReentryIssues', () => {...toConfigOverrideState(mapped),tombstones: ['endpoints.azureOpenAI.groups'],},- baseGroupMap: yamlGroupMap,+ base: yamlBase,entered: new Set(),});@@ -691,7 +714,7 @@ describe('a stored key bound to a destination over a lower layer', () => {value: baseURL,},]),- baseGroupMap: {},+ base: { groups: undefined, groupMap: {} },entered: new Set(),});diff --git a/packages/api/src/admin/reentry.ts b/packages/api/src/admin/reentry.tsindex 9b2de89b8c..73d914d8cb 100644--- a/packages/api/src/admin/reentry.ts+++ b/packages/api/src/admin/reentry.ts@@ -5,6 +5,7 @@ import {isSameConfigValue,resolveAzureGroups,foldConfigMergeKey,+ mergeConfigEntries,mergeConfigOverrides,applyConfigTombstones,} from '@librechat/data-schemas';@@ -271,27 +272,47 @@ function getGroupMap(azure: JsonRecord): JsonRecord {return isPlainRecord(azure.groupMap) ? azure.groupMap : {};}+/** librechat.yaml's Azure groups: as written (`groups`), and as they resolve (`groupMap`). */+export interface BaseAzureGroups {+ groups: unknown;+ groupMap: unknown;+}++const GROUPS_SEGMENTS = [...AZURE_SEGMENTS, 'groups'];++/** librechat.yaml's Azure groups under a document's tombstones. */+function getBaseUnder(base: BaseAzureGroups, document: StoredDocument | null | undefined) {+ const azure = getAtPath(+ applyConfigTombstones(+ {+ endpoints: { azureOpenAI: { groups: base.groups, groupMap: base.groupMap } },+ } as Partial<TCustomConfig>,+ document?.tombstones,+ ),+ AZURE_SEGMENTS,+ );+ return {+ groups: isPlainRecord(azure) ? azure.groups : undefined,+ groupMap: isPlainRecord(azure) ? azure.groupMap : undefined,+ };+}+/*** The Azure groups a document resolves to on its own over librechat.yaml, by name, as the merge- * resolves one layer: its `groups` replace librechat.yaml's whole when they resolve- * (`resolveAzureGroups`), else librechat.yaml's resolved groups (`baseGroupMap`) stay under its- * tombstones; its `groupMap` entries merge over either.+ * resolves one layer: its `groups` merge by `group` over librechat.yaml's and resolve+ * (`resolveAzureGroups`), else librechat.yaml's resolved groups stay under its tombstones; its+ * `groupMap` entries merge over either.*/function getEffectiveAzureGroups(document: StoredDocument | null | undefined,- baseGroupMap: unknown,+ base: BaseAzureGroups,): Map<string, JsonRecord> {const azure = getAzureSection(document?.overrides);- const resolved = Array.isArray(azure.groups) ? resolveAzureGroups(azure.groups) : undefined;- const below = resolved?.isValid- ? resolved.groupMap- : getAtPath(- applyConfigTombstones(- { endpoints: { azureOpenAI: { groupMap: baseGroupMap } } } as Partial<TCustomConfig>,- document?.tombstones,- ),- [...AZURE_SEGMENTS, 'groupMap'],- );+ const under = getBaseUnder(base, document);+ const resolved = Array.isArray(azure.groups)+ ? resolveAzureGroups(mergeConfigEntries(GROUPS_SEGMENTS, under.groups, azure.groups))+ : undefined;+ const below = resolved?.isValid ? resolved.groupMap : under.groupMap;const merged = mergeLayer(below, getGroupMap(azure));return new Map(Object.entries(isPlainRecord(merged) ? merged : {}).flatMap(([name, group]) =>@@ -300,6 +321,27 @@ function getEffectiveAzureGroups();}+/**+ * Each `groups` item a document writes, merged over librechat.yaml's group of its name as the+ * merge merges them, by name: a group as it would be sent even while the document's groups do not+ * resolve as a whole.+ */+function getMergedGroupItems(+ document: StoredDocument | null | undefined,+ base: BaseAzureGroups,+): Array<[string, JsonRecord]> {+ const items = getGroupItems(getAzureSection(document?.overrides));+ const names = new Set(+ items.flatMap((item) => (typeof item.group === 'string' ? [item.group] : [])),+ );+ return mergeConfigEntries(GROUPS_SEGMENTS, getBaseUnder(base, document).groups, items).flatMap(+ (item): Array<[string, JsonRecord]> =>+ isPlainRecord(item) && typeof item.group === 'string' && names.has(item.group)+ ? [[item.group, item]]+ : [],+ );+}+/** Every hidden group key a document stores, in `groups` and in `groupMap`. */function getStoredGroupKeys(azure: JsonRecord): string[] {return [...getGroupItems(azure), ...Object.values(getGroupMap(azure))].flatMap((group) => {@@ -328,9 +370,10 @@ function locateGroupField(azure: JsonRecord, name: string, field: string): strin* The Azure form of the re-entry rule web search and MCP keys follow: a write that keeps a* stored group key (in `groups` or `groupMap`) while changing where the group sends it must enter* the key again. Groups are compared as the document resolves them on its own over- * librechat.yaml ({@link getEffectiveAzureGroups}), and each `groups` item also as written, so- * groups that do not resolve yet cannot carry a key to a new destination for a later write to- * put to use; destinations are compared by `diffAzureGroupBinding`. A+ * librechat.yaml ({@link getEffectiveAzureGroups}), and each `groups` item also merged over+ * librechat.yaml's group of its name ({@link getMergedGroupItems}), so groups that do not resolve+ * yet cannot carry a key to a new destination for a later write to put to use; destinations are+ * compared by `diffAzureGroupBinding`. A* key counts as entered again only when the planned document holds a value the request entered;* a kept one is compared with every stored group that held the same value, so the write is* refused unless one of them sent it where the candidate does. Only keys the stored document@@ -339,25 +382,22 @@ function locateGroupField(azure: JsonRecord, name: string, field: string): strinexport function getAzureGroupReentryIssues(params: {stored: StoredDocument | null | undefined;candidate: ConfigOverrideState;- /** librechat.yaml's resolved Azure groups (`endpoints.azureOpenAI.groupMap` of the base config). */- baseGroupMap: unknown;+ /** librechat.yaml's Azure groups, as written and as resolved in the base config. */+ base: BaseAzureGroups;/** The secret values the request itself entered, encrypted. */entered: ReadonlySet<string>;}): SecretReentryIssue[] {- const { stored, candidate, baseGroupMap, entered } = params;+ const { stored, candidate, base, entered } = params;const storedAzure = getAzureSection(stored?.overrides);const held = getStoredGroupKeys(storedAzure);if (held.length === 0) {return [];}const candidateAzure = getAzureSection(candidate.overrides);- /** As the document resolves, and each `groups` item as written, which may not resolve yet. */+ /** As the document resolves, and each `groups` item merged alone, which may not resolve yet. */const candidates: Array<[string, JsonRecord]> = [- ...getEffectiveAzureGroups(candidate, baseGroupMap),- ...getGroupItems(candidateAzure).flatMap(- (item): Array<[string, JsonRecord]> =>- typeof item.group === 'string' ? [[item.group, item]] : [],- ),+ ...getEffectiveAzureGroups(candidate, base),+ ...getMergedGroupItems(candidate, base),];let origins: JsonRecord[] | undefined;const issues = new Map<string, SecretReentryIssue>();@@ -370,10 +410,10 @@ export function getAzureGroupReentryIssues(params: {) {continue;}- /** Every stored definition of a group: as it resolved, and each complete `groups` item. */+ /** Every stored definition of a group: as it resolved, and each `groups` item merged alone. */origins ??= [- ...getEffectiveAzureGroups(stored, baseGroupMap).values(),- ...getGroupItems(storedAzure),+ ...getEffectiveAzureGroups(stored, base).values(),+ ...getMergedGroupItems(stored, base).map(([, item]) => item),];const fingerprint = getAzureGroupFingerprint(group);const changes = originsdiff --git a/packages/api/src/admin/secrets.integration.spec.ts b/packages/api/src/admin/secrets.integration.spec.tsindex 8f8ae414ea..8633ecda91 100644--- a/packages/api/src/admin/secrets.integration.spec.ts+++ b/packages/api/src/admin/secrets.integration.spec.ts@@ -8,6 +8,8 @@ import type { ServerRequest } from '~/types/http';process.env.CREDS_KEY =process.env.CREDS_KEY ?? '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';process.env.CREDS_IV = process.env.CREDS_IV ?? '0123456789abcdef0123456789abcdef';+/** An Azure group a write stores must resolve, its `${AZURE_API_KEY}` included. */+process.env.AZURE_API_KEY = process.env.AZURE_API_KEY ?? 'test-azure-key';type DataSchemas = typeof import('@librechat/data-schemas');type ConfigMethods = ReturnType<DataSchemas['createMethods']>;@@ -1669,6 +1671,89 @@ describe('config secret registry — real handlers against a real Config collect]);expect(JSON.stringify(appConfig)).toContain(AZURE_KEY);});++ it("never returns the value a Base profile's Vertex AI settings would reference", async () => {+ const DEPLOYMENT_KEY = 'sk-deployment-openai-key-0123456789';+ const saved = {+ OPENAI_API_KEY: process.env.OPENAI_API_KEY,+ GCP_PROJECT: process.env.GCP_PROJECT,+ };+ process.env.OPENAI_API_KEY = DEPLOYMENT_KEY;+ process.env.GCP_PROJECT = 'yaml-gcp-project';+ try {+ const { AppService } = await import('@librechat/data-schemas');+ const { createAppConfigService } = await import('~/app/service');+ const { expandCustomEndpoint } = await import('~/app/params');+ const yaml = {+ endpoints: {+ anthropic: { vertex: { projectId: '${GCP_PROJECT}', models: ['claude-sonnet-4-6'] } },+ },+ };+ const vertex = {+ projectId: '${OPENAI_API_KEY}',+ deploymentName: '${OPENAI_API_KEY}',+ models: ['claude-opus-4-6'],+ };+ const entries = new Map<string, unknown>();+ const service = createAppConfigService({+ loadBaseConfig: () =>+ AppService({ config: structuredClone(yaml) as never, expandCustomEndpoint }),+ setCachedTools: async () => undefined,+ getCache: () => ({+ get: async (key: string) => entries.get(key),+ set: async (key: string, value: unknown) => entries.set(key, value),+ delete: async (key: string) => entries.delete(key),+ }),+ cacheKeys: { APP_CONFIG: 'app_config' },+ getApplicableConfigs: async () => [+ {+ principalType: PrincipalType.ROLE,+ principalId: basePrincipalId,+ principalModel: PrincipalModel.ROLE,+ priority: 0,+ isActive: true,+ overrides: { endpoints: { anthropic: { vertex } } },+ } as never,+ ],+ getUserPrincipals: async () => [],+ rederiveEndpoints: true,+ });+ const baseHandlers = createAdminConfigHandlers({+ listAllConfigs: async () => [],+ findConfigByPrincipal: async () => null,+ writeConfigDocument: async () => {+ throw new Error('not written in this test');+ },+ unsetConfigField: async () => null,+ deleteConfig: async () => null,+ toggleConfigActiveTracked: async () => null,+ hasConfigCapability: async () => true,+ hasAnyConfigReadAccess: async () => true,+ hasCapability: async () => true,+ getAppConfig: (options) => service.getAppConfig(options),+ });++ const res = mockRes();+ await baseHandlers.getBaseConfig(mockReq(), res);++ expect(res.statusCode).toBe(200);+ expect(JSON.stringify(res.body)).not.toContain(DEPLOYMENT_KEY);+ const vertexConfig = getAtPath(res.body!.config, 'endpoints.anthropic.vertexConfig');+ expect(vertexConfig).toMatchObject({+ projectId: 'yaml-gcp-project',+ modelNames: ['claude-opus-4-6'],+ modelDeploymentMap: { 'claude-opus-4-6': 'claude-opus-4-6' },+ });+ } finally {+ for (const [name, value] of Object.entries(saved)) {+ if (value === undefined) {+ delete process.env[name];+ } else {+ process.env[name] = value;+ }+ }+ }+ });});});@@ -2367,6 +2452,7 @@ describe('env reference allowlist on admin writes', () => {apiKey: '${AZURE_API_KEY}',instanceName: 'east-instance',version: '2024-10-21',+ deploymentName: 'gpt-4o',baseURL,models: { 'gpt-4o': true },};@@ -2382,7 +2468,15 @@ describe('env reference allowlist on admin writes', () => {{op: 'set',fieldPath: 'endpoints.azureOpenAI.groups',- value: [group, { ...group, group: 'west', instanceName: 'west-instance' }],+ value: [+ group,+ {+ ...group,+ group: 'west',+ instanceName: 'west-instance',+ models: { 'gpt-4o-west': true },+ },+ ],},],},@@ -2490,6 +2584,7 @@ describe('Azure OpenAI group keys — real handlers against a real Config collecgroup: 'east',instanceName: 'east-instance',version: '2024-10-21',+ deploymentName: 'gpt-4o',models: { 'gpt-4o': true },...(apiKey !== undefined && { apiKey }),});@@ -2519,6 +2614,64 @@ describe('Azure OpenAI group keys — real handlers against a real Config collecexpect(after![0].apiKey).toBe(stored![0].apiKey);});+ it('binds a key a profile enters for a group only Base defines, so CONFIG_REDERIVE_ENDPOINTS keeps it', async () => {+ const { resolveConfigOverrides } = await import('~/app/overrides');+ const { createEnvReferencePolicy } = await import('~/app/allowlist');+ const principalId = nextPrincipalId();+ const west = { ...group('azure-base-west-key-0001'), group: 'west', instanceName: 'west' };+ try {+ expect(+ (+ await patch(basePrincipalId, [+ { fieldPath: 'endpoints.azureOpenAI.groups', value: [west] },+ ])+ ).statusCode,+ ).toBe(200);+ /** Written while the deployment leaves the switch off: the groups do not apply yet. */+ const entered = await patch(principalId, [+ {+ fieldPath: 'endpoints.azureOpenAI.groups',+ value: [{ group: 'west', apiKey: 'azure-role-west-key-0002' }],+ },+ ]);+ expect(entered.statusCode).toBe(200);+ expect(entered.body!.ignored).toBeUndefined();++ const serveWest = async () => {+ const layers = await Promise.all([+ configMethods.findConfigByPrincipal(PrincipalType.ROLE, basePrincipalId),+ configMethods.findConfigByPrincipal(PrincipalType.ROLE, principalId),+ ]);+ const served = resolveConfigOverrides(+ { config: {} } as never,+ layers.filter((layer) => layer != null),+ { envPolicy: createEnvReferencePolicy({ config: {} }), rederiveEndpoints: true },+ ) as unknown as {+ endpoints?: { azureOpenAI?: { groupMap?: Record<string, Record<string, unknown>> } };+ };+ return served.endpoints?.azureOpenAI?.groupMap?.west;+ };++ expect(await serveWest()).toMatchObject({+ apiKey: 'azure-role-west-key-0002',+ instanceName: 'west',+ });++ /** The key stays bound to where it was entered: Base moving the group drops it. */+ const moved = { ...west, instanceName: 'elsewhere', apiKey: 'azure-base-west-key-0003' };+ expect(+ (+ await patch(basePrincipalId, [+ { fieldPath: 'endpoints.azureOpenAI.groups', value: [moved] },+ ])+ ).statusCode,+ ).toBe(200);+ expect(await serveWest()).toMatchObject({ apiKey: '', instanceName: 'elsewhere' });+ } finally {+ await mongoose.models.Config.deleteOne({ principalId: basePrincipalId });+ }+ });+describe('a stored group key kept beside a destination the write changes', () => {const KEY = 'azure-east-admin-key-00009876';/** A group the merge resolves: each model has a deployment and a version. */diff --git a/packages/api/src/admin/secrets.runtime.spec.ts b/packages/api/src/admin/secrets.runtime.spec.tsindex 6c695f8c36..d8db7dbf28 100644--- a/packages/api/src/admin/secrets.runtime.spec.ts+++ b/packages/api/src/admin/secrets.runtime.spec.ts@@ -224,7 +224,8 @@ const azureGroupMapReader: RuntimeReader = {/*** Merges a role profile that stores an Azure group in `groups`, as the admin config API stores it,* through the same override pipeline `getAppConfig` runs, and returns the key the Azure client- * options are built with: the merge resolves the profile's groups into the `groupMap` it reads.+ * options are built with: the merge resolves the profile's groups into the `groupMap` it reads,+ * where the deployment sets `CONFIG_REDERIVE_ENDPOINTS`.*/const azureGroupsReader: RuntimeReader = {module: 'packages/api/src/app/service.ts',@@ -252,6 +253,7 @@ const azureGroupsReader: RuntimeReader = {} as ConfigOverrideLayer;const resolved = resolveConfigOverrides({} as AppConfig, [layer], {envPolicy: createEnvReferencePolicy({}),+ rederiveEndpoints: true,});const azure = resolved.endpoints?.azureOpenAI;if (!azure?.groupMap || !azure.modelGroupMap) {diff --git a/packages/api/src/app/allowlist.spec.ts b/packages/api/src/app/allowlist.spec.tsindex daa096c98b..bdeea371bc 100644--- a/packages/api/src/app/allowlist.spec.ts+++ b/packages/api/src/app/allowlist.spec.ts@@ -114,6 +114,89 @@ describe('createEnvReferencePolicy', () => {).toEqual(['endpoints.custom.0.headers.K']);});+ describe('Vertex AI settings, which reads return resolved', () => {+ const vertexYaml = {+ ...yaml,+ endpoints: {+ ...yaml.endpoints,+ anthropic: {+ vertex: {+ projectId: '${GCP_PROJECT}',+ region: '${GCP_REGION}',+ serviceKeyFile: '${GOOGLE_SERVICE_KEY_FILE}',+ models: { 'claude-sonnet-4-6': { deploymentName: '${SONNET_DEPLOYMENT}' } },+ },+ },+ },+ };+ const projectId = ['endpoints', 'anthropic', 'vertex', 'projectId'];+ const deployment = [+ 'endpoints',+ 'anthropic',+ 'vertex',+ 'models',+ 'claude-opus-4-6',+ 'deploymentName',+ ];+ const keyFile = ['endpoints', 'anthropic', 'vertex', 'serviceKeyFile'];++ it('allows only the names librechat.yaml references in its own Vertex AI settings', () => {+ const policy = createEnvReferencePolicy({ config: vertexYaml, allowlist: ['EXTRA_NAME'] });++ for (const name of ['GCP_PROJECT', 'GCP_REGION', 'SONNET_DEPLOYMENT']) {+ expect(policy.allows(name, projectId)).toBe(true);+ expect(policy.allows(name, deployment)).toBe(true);+ }+ for (const name of ['OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'GATEWAY_KEY', 'EXTRA_NAME']) {+ expect(policy.allows(name, projectId)).toBe(false);+ expect(policy.allows(name, deployment)).toBe(false);+ expect(policy.allows(name, ['endpoints', 'custom', '0', 'apiKey'])).toBe(true);+ }+ expect(policy.allows('GCP_PROJECT', ['endpoints', 'anthropic', 'apiKey'])).toBe(true);+ });++ it("allows the key file's names only in the key file, which the merge keeps librechat.yaml's", () => {+ const policy = createEnvReferencePolicy({ config: vertexYaml });++ expect(policy.allows('GOOGLE_SERVICE_KEY_FILE', keyFile)).toBe(true);+ expect(policy.allows('GOOGLE_SERVICE_KEY_FILE', projectId)).toBe(false);+ expect(policy.allows('GOOGLE_SERVICE_KEY_FILE', deployment)).toBe(false);+ expect(policy.allows('GCP_PROJECT', keyFile)).toBe(true);+ });++ it('allows no reference there when librechat.yaml configures no Vertex AI', () => {+ const policy = createEnvReferencePolicy({ config: yaml });+ const layer = {+ endpoints: {+ anthropic: {+ vertex: {+ projectId: '${OPENAI_API_KEY}',+ deploymentName: 'deployment-${GATEWAY_KEY}',+ models: { 'claude-opus-4-6': { deploymentName: '${ANTHROPIC_API_KEY}' } },+ },+ },+ },+ };++ expect(getEnvReferenceIssues(layer, policy).map(({ path }) => path)).toEqual([+ 'endpoints.anthropic.vertex.projectId',+ 'endpoints.anthropic.vertex.deploymentName',+ 'endpoints.anthropic.vertex.models.claude-opus-4-6.deploymentName',+ ]);+ expect(neutralizeEnvReferences(layer, policy)).toEqual({+ endpoints: {+ anthropic: {+ vertex: {+ projectId: '',+ deploymentName: 'deployment-',+ models: { 'claude-opus-4-6': { deploymentName: '' } },+ },+ },+ },+ });+ });+ });+it('never allows an infrastructure secret, even when YAML or the extra list names it', () => {const policy = createEnvReferencePolicy({config: { ocr: { apiKey: '${CREDS_KEY}' } },diff --git a/packages/api/src/app/allowlist.ts b/packages/api/src/app/allowlist.tsindex 583f72f5f5..aa0b933418 100644--- a/packages/api/src/app/allowlist.ts+++ b/packages/api/src/app/allowlist.ts@@ -153,6 +153,38 @@ function isAzureURLTemplate(name: string, segments: readonly string[]): boolean);}+/**+ * Vertex AI's settings, which the merge resolves while deriving `vertexConfig`: admin reads of the+ * served config return its project ID, region and deployment names resolved, so a reference+ * there would show the variable's value. Only the names librechat.yaml's own Vertex AI settings+ * reference may be referenced there: values the operator set for these settings, which reads+ * show wherever Vertex AI is on, including where a profile turns on the Vertex AI librechat.yaml+ * configures off.+ */+export const ENV_VERTEX_SETTINGS_PATH: readonly string[] = [+ 'endpoints',+ EModelEndpoint.anthropic,+ 'vertex',+];++/** The Vertex AI key file, which reads never return resolved; the merge keeps librechat.yaml's. */+const VERTEX_KEY_FILE = 'serviceKeyFile';++function isVertexSettingsPath(segments: readonly string[]): boolean {+ return (+ segments.length > ENV_VERTEX_SETTINGS_PATH.length &&+ ENV_VERTEX_SETTINGS_PATH.every((segment, index) => segments[index] === segment)+ );+}++function isVertexKeyFilePath(segments: readonly string[]): boolean {+ return (+ segments.length === ENV_VERTEX_SETTINGS_PATH.length + 1 &&+ isVertexSettingsPath(segments) &&+ segments[ENV_VERTEX_SETTINGS_PATH.length] === VERTEX_KEY_FILE+ );+}+/** Splits `CONFIG_OVERRIDE_ENV_ALLOWLIST`: env names separated by commas or whitespace. */export function parseEnvAllowlist(value?: string | null): string[] {return (value ?? '').split(/[\s,]+/).filter((name) => name !== '');@@ -202,6 +234,29 @@ export function collectEnvReferenceNames(value: unknown): Set<string> {return names;}+/** The names librechat.yaml's Vertex AI settings reference: in its key file, and elsewhere. */+interface VertexReferences {+ keyFile: Set<string>;+ settings: Set<string>;+}++function collectVertexReferences(config: unknown): VertexReferences {+ const references: VertexReferences = { keyFile: new Set(), settings: new Set() };+ let vertex: unknown = config;+ for (const segment of ENV_VERTEX_SETTINGS_PATH) {+ vertex = isPlainObject(vertex) ? (vertex as Record<string, unknown>)[segment] : undefined;+ }+ visitExpandedStrings(+ vertex,+ (text, segments) => {+ const held = isVertexKeyFilePath(segments) ? references.keyFile : references.settings;+ referencedNames(text, segments).forEach((name) => held.add(name));+ },+ ENV_VERTEX_SETTINGS_PATH,+ );+ return references;+}+/*** Every env name `value` references where a reader expands it (as {@link collectEnvReferenceNames}* finds them), with the top-level sections it is referenced in.@@ -285,8 +340,10 @@ export function collectDefaultEnvReferenceSections(config: unknown): Map<string,* The allowlist: names librechat.yaml references (`config` is the raw YAML config), the* built-in endpoints' credential names and the operator's extra names, anywhere; and each* reference loading librechat.yaml introduces, at its own location- * ({@link collectLoadedReferences}). Infrastructure secrets `extractEnvVariable` never expands- * (`CREDS_KEY`, `JWT_SECRET`, ...) stay out whatever lists them.+ * ({@link collectLoadedReferences}). Vertex AI's settings ({@link ENV_VERTEX_SETTINGS_PATH})+ * allow only the names librechat.yaml's own Vertex AI settings reference, its key file's only in+ * the key file. Infrastructure secrets `extractEnvVariable` never expands (`CREDS_KEY`,+ * `JWT_SECRET`, ...) stay out whatever lists them.*/export function createEnvReferencePolicy(options: {config?: unknown;@@ -297,10 +354,17 @@ export function createEnvReferencePolicy(options: {names.add(name);}const loaded = collectLoadedReferences(options.config);+ const vertex = collectVertexReferences(options.config);+ const allowsAt = (name: string, segments: readonly string[]): boolean => {+ if (isVertexSettingsPath(segments)) {+ return (+ vertex.settings.has(name) || (isVertexKeyFilePath(segments) && vertex.keyFile.has(name))+ );+ }+ return names.has(name) || loaded.get(locationKey(segments))?.has(name) === true;+ };return {- allows: (name, segments) =>- !isSensitiveEnvVar(name) &&- (names.has(name) || loaded.get(locationKey(segments))?.has(name) === true),+ allows: (name, segments) => !isSensitiveEnvVar(name) && allowsAt(name, segments),};}diff --git a/packages/api/src/app/index.ts b/packages/api/src/app/index.tsindex e881c6f36b..b4f2fee381 100644--- a/packages/api/src/app/index.ts+++ b/packages/api/src/app/index.ts@@ -4,6 +4,8 @@ export * from './rebinding';export * from './overrides';export * from './invalidation';export * from './loader';+export { expandCustomEndpoint } from './params';+export * from './report';export * from './config';export * from './metrics';export * from './permissions';diff --git a/packages/api/src/app/loader.inference.spec.ts b/packages/api/src/app/loader.inference.spec.tsindex 4866c172bd..266d126be5 100644--- a/packages/api/src/app/loader.inference.spec.ts+++ b/packages/api/src/app/loader.inference.spec.ts@@ -6,6 +6,7 @@ import { createCustomConfigLoader, ConfigReloadError } from './loader';import { resolveAgentInferenceParameters } from '../agents/inference';import { getOpenAIConfig } from '../endpoints/openai/config';import { parseAgentInferenceInput } from '../agents/input';+import { expandCustomEndpoint } from './params';type Definition = NonNullable<NonNullable<TEndpoint['customParams']>['paramDefinitions']>[number];@@ -55,7 +56,10 @@ describe('typed inference declarations in YAML', () => {async (mode) => {const config = await load(definitions, mode);expect(config).not.toBeNull();- const endpoint = endpointSchema.parse(config?.endpoints?.custom?.[0]);+ const loaded = config?.endpoints?.custom?.[0];+ const endpoint = loaded+ ? endpointSchema.parse(expandCustomEndpoint(loaded as TEndpoint))+ : undefined;expect(endpoint?.customParams?.paramDefinitions).toMatchObject(definitions.map((definition) => ({ ...definition, optionType: 'custom' })),);@@ -128,9 +132,13 @@ describe('typed inference declarations in YAML', () => {).rejects.toThrow('invalid key');});- it('preserves existing shorthand parameter declarations', async () => {+ it('keeps shorthand parameter declarations as written, and serves them expanded', async () => {const config = await load([{ key: 'temperature', default: 0.3 }]);- expect(config?.endpoints?.custom?.[0].customParams?.paramDefinitions?.[0]).toMatchObject({+ const loaded = config?.endpoints?.custom?.[0];+ expect(loaded?.customParams?.paramDefinitions).toEqual([{ key: 'temperature', default: 0.3 }]);+ expect(+ loaded && expandCustomEndpoint(loaded as TEndpoint).customParams?.paramDefinitions?.[0],+ ).toMatchObject({key: 'temperature',type: 'number',default: 0.3,diff --git a/packages/api/src/app/loader.ts b/packages/api/src/app/loader.tsindex 47e03574d0..f8a4c8c4d8 100644--- a/packages/api/src/app/loader.ts+++ b/packages/api/src/app/loader.ts@@ -1,27 +1,20 @@import axios from 'axios';import yaml from 'js-yaml';-import { Providers } from '@librechat/agents';import { logger } from '@librechat/data-schemas';import {configSchema,- paramSettings,EModelEndpoint,EImageOutputType,getMaxSubagents,setMaxSubagents,- agentParamSettings,- validateSettingDefinitions,} from 'librechat-data-provider';import type { TCustomConfig, TEndpoint } from 'librechat-data-provider';import type { ConfigOverrideIssue } from '@librechat/data-schemas';import type { ZodIssue } from 'zod';-import { isAgentInferenceExtension } from '../agents/inference';import { checkConfigPolicyLinks } from './interface';+import { expandCustomEndpoint } from './params';import { checkConfigTheme } from './theme';-type CustomParams = NonNullable<TEndpoint['customParams']>;-type CustomParamDefinition = NonNullable<CustomParams['paramDefinitions']>[number];-export type CustomConfigLoadMode = 'startup' | 'reload';export interface CustomConfigLoadOptions {@@ -81,46 +74,6 @@ export function getConfigLoadFailure(error: unknown): ConfigLoadFailure {return { code: 'CONFIG_INVALID', issues };}-const OPENROUTER_PROMPT_CACHE_DEFAULT = {- key: 'promptCache',- default: true,-};--function includesOpenRouter(value: string | undefined): boolean {- return typeof value === 'string' && value.toLowerCase().includes(Providers.OPENROUTER);-}--function isOpenRouterEndpoint(endpoint: TEndpoint): boolean {- return includesOpenRouter(endpoint.name) || includesOpenRouter(endpoint.baseURL);-}--function shouldPreserveCustomParams(customParams: CustomParams | undefined): boolean {- const defaultEndpoint = customParams?.defaultParamsEndpoint;- return (- !!defaultEndpoint && defaultEndpoint !== 'custom' && defaultEndpoint !== Providers.OPENROUTER- );-}--function addOpenRouterDefaults(endpoint: TEndpoint): void {- if (!isOpenRouterEndpoint(endpoint) || shouldPreserveCustomParams(endpoint.customParams)) {- return;- }-- const customParams: CustomParams = endpoint.customParams ?? {- defaultParamsEndpoint: 'custom',- };- const paramDefinitions = customParams.paramDefinitions ?? [];- const hasPromptCache = paramDefinitions.some((param) => param.key === 'promptCache');-- endpoint.customParams = {- ...customParams,- defaultParamsEndpoint: Providers.OPENROUTER,- paramDefinitions: hasPromptCache- ? paramDefinitions- : [...paramDefinitions, OPENROUTER_PROMPT_CACHE_DEFAULT],- };-}-function getConfiguredMaxSubagents(config: unknown): number | undefined {if (typeof config !== 'object' || config == null || !('endpoints' in config)) {return undefined;@@ -136,58 +89,6 @@ function getConfiguredMaxSubagents(config: unknown): number | undefined {return typeof agents.maxSubagents === 'number' ? agents.maxSubagents : undefined;}-function parseCustomParams(endpointName: string | undefined, customParams: CustomParams): void {- const paramEndpoint = customParams.defaultParamsEndpoint ?? 'custom';- customParams.defaultParamsEndpoint = paramEndpoint;- const paramDefinitions = customParams.paramDefinitions ?? [];- customParams.paramDefinitions = paramDefinitions;-- const validEndpoints = new Set([- ...Object.keys(paramSettings),- ...Object.keys(agentParamSettings),- ]);- if (!validEndpoints.has(paramEndpoint)) {- throw new Error(- `defaultParamsEndpoint of "${endpointName}" endpoint is invalid. ` +- `Valid options are ${Array.from(validEndpoints).join(', ')}`,- );- }-- const regularParams = paramSettings[paramEndpoint] ?? [];- const agentParams = agentParamSettings[paramEndpoint] ?? [];- const defaultParams = regularParams.concat(agentParams);- const defaultParamsMap = new Map(- defaultParams.map((param) => [param.key, param as CustomParamDefinition]),- );- const invalidKeys = paramDefinitions- .filter((param) => !defaultParamsMap.has(param.key) && !isAgentInferenceExtension(param))- .map((param) => param.key);- if (invalidKeys.length > 0) {- throw new Error(- `paramDefinitions of "${endpointName}" endpoint contains invalid key(s). ` +- `Valid parameter keys are ${Array.from(defaultParamsMap.keys()).join(', ')}`,- );- }-- const parsedDefinitions = paramDefinitions.map((param) => ({- ...defaultParamsMap.get(param.key),- ...param,- optionType: 'custom',- })) as CustomParamDefinition[];- customParams.paramDefinitions = parsedDefinitions;-- try {- validateSettingDefinitions(- parsedDefinitions as Parameters<typeof validateSettingDefinitions>[0],- );- } catch (error) {- const message = error instanceof Error ? error.message : String(error);- throw new Error(- `Custom parameter definitions for "${endpointName}" endpoint is malformed: ${message}`,- );- }-}-function isRemoteConfigPath(configPath: string): boolean {return /^https?:\/\//.test(configPath);}@@ -365,14 +266,9 @@ export function createCustomConfigLoader({}const customConfig = loadedConfig as TCustomConfig;- const customEndpoints = (customConfig.endpoints?.custom ?? []) as TEndpoint[];- for (const endpoint of customEndpoints) {- addOpenRouterDefaults(endpoint);- }- for (const endpoint of customEndpoints) {- if (endpoint.customParams) {- parseCustomParams(endpoint.name, endpoint.customParams);- }+ /** Expanded copies are discarded: AppService serves them, and the config stays as written. */+ for (const endpoint of (customConfig.endpoints?.custom ?? []) as TEndpoint[]) {+ expandCustomEndpoint(endpoint);}if (result.data.modelSpecs) {customConfig.modelSpecs = result.data.modelSpecs;diff --git a/packages/api/src/app/overrides.ts b/packages/api/src/app/overrides.tsindex cf02fa84a8..79d9229658 100644--- a/packages/api/src/app/overrides.ts+++ b/packages/api/src/app/overrides.ts@@ -4,10 +4,11 @@ import {unsetAtPath,foldConfigMergeKey,resolveConfigLayers,- mergeConfigOverrides,+ mergeConfigOverridesWithSource,} from '@librechat/data-schemas';import type {AppConfig,+ ConfigMergeResult,ConfigOverrideLayer,AdminConfigLayerIgnored,ConfigLayersResolution,@@ -22,34 +23,37 @@ import {} from './rebinding';import { getSecretPreviewKey, resolveRuntimeConfigSecrets } from '~/admin/secrets';import { neutralizeEnvReferences } from './allowlist';+import { expandCustomEndpoint } from './params';export interface OverrideMergeOptions {/** Which `${NAME}` references values from override layers may resolve. */envPolicy: EnvReferencePolicy;/** Told about each inherited secret a layer drops for sending it somewhere new. */onRebinding?: (rebinding: SecretRebinding) => void;+ /**+ * Whether the Azure groups, Vertex AI and the Azure Assistants endpoint are derived again from+ * what the layers write (`CONFIG_REDERIVE_ENDPOINTS`); without it those overrides stay inert.+ */+ rederiveEndpoints?: boolean;}/**- * Merges database override layers into the base config under the policies that apply to- * admin-written values: each layer's disallowed `${NAME}` references resolve to nothing before it- * merges, and a secret sent anywhere but the destination it was entered for is dropped- * (`createSecretRebindingGuard`; web search keys by the merge's own rule, whose drops are- * reported the same way). The destination fingerprints stored beside secrets are read by the- * guard and left out of the result (`withoutSecretBindings`). Secrets stay as stored, so the- * result may be cached as is.+ * {@link mergeOverrideLayers}, with the librechat.yaml-shaped config the layers merge to, from+ * which the caller derives what only the final config decides.*/-export function mergeOverrideLayers(+export function mergeOverrideLayersWithSource(baseConfig: AppConfig,layers: readonly ConfigOverrideLayer[],options: OverrideMergeOptions,-): AppConfig {+): ConfigMergeResult {const neutralized = layers.map((layer) => {const overrides = neutralizeEnvReferences(layer.overrides, options.envPolicy);return overrides === layer.overrides ? layer : { ...layer, overrides };});- const { onRebinding } = options;- const merged = mergeConfigOverrides(baseConfig, neutralized, {+ const { onRebinding, rederiveEndpoints } = options;+ const { appConfig, raw } = mergeConfigOverridesWithSource(baseConfig, neutralized, {+ expandCustomEndpoint,+ rederiveEndpoints,afterLayer: createSecretRebindingGuard(onRebinding),onWebSearchKeyUnbound: ({ layer, apiKey }) =>onRebinding?.({@@ -59,7 +63,27 @@ export function mergeOverrideLayers(path: `webSearch.${apiKey}`,}),});- return withoutSecretBindings(merged);+ return { appConfig: withoutSecretBindings(appConfig), raw };+}++/**+ * Merges database override layers into the base config under the policies that apply to+ * admin-written values: each layer's disallowed `${NAME}` references resolve to nothing before it+ * merges, and a secret sent anywhere but the destination it was entered for is dropped+ * (`createSecretRebindingGuard`; web search keys by the merge's own rule, whose drops are+ * reported the same way). What startup derives from librechat.yaml is derived again for the+ * parts the layers write: custom endpoint parameters (`expandCustomEndpoint`), the agents memory+ * capability, and with `rederiveEndpoints` the Azure groups, Vertex AI and the Azure Assistants+ * endpoint. The+ * destination fingerprints stored beside secrets are read by the guard and left out of the+ * result (`withoutSecretBindings`). Secrets stay as stored, so the result may be cached as is.+ */+export function mergeOverrideLayers(+ baseConfig: AppConfig,+ layers: readonly ConfigOverrideLayer[],+ options: OverrideMergeOptions,+): AppConfig {+ return mergeOverrideLayersWithSource(baseConfig, layers, options).appConfig;}/**@@ -245,8 +269,10 @@ export function resolveOverrideLayers(});const rebindings: SecretRebinding[] = [];const unboundKeys: string[][] = [];- const { onRebinding } = options;+ const { onRebinding, rederiveEndpoints } = options;const result = resolveConfigLayers(baseConfig, neutralized, {+ expandCustomEndpoint,+ rederiveEndpoints,afterLayer: createSecretRebindingGuard((rebinding) => {rebindings.push(rebinding);onRebinding?.(rebinding);@@ -276,6 +302,7 @@ export function resolveOverrideLayers(}return {merged,+ raw: result.raw,resolved: withoutStoredSecretBindings(resolved),layers: result.layers.map(({ layer, ignored }) => ({layer: originals.get(layer) ?? layer,diff --git a/packages/api/src/app/params.spec.ts b/packages/api/src/app/params.spec.tsnew file mode 100644index 0000000000..fb56da09a9--- /dev/null+++ b/packages/api/src/app/params.spec.ts@@ -0,0 +1,164 @@+import {+ SettingTypes,+ paramSettings,+ ComponentTypes,+ agentParamSettings,+} from 'librechat-data-provider';+import type { TEndpoint } from 'librechat-data-provider';+import { expandCustomEndpoint } from './params';++/** A custom endpoint as librechat.yaml writes it, where `customParams` may be compact. */+const endpoint = (overrides: Record<string, unknown> = {}): TEndpoint =>+ ({+ name: 'Gateway',+ apiKey: '${GATEWAY_KEY}',+ baseURL: 'https://gateway.example.com/v1',+ models: { default: ['m1'] },+ ...overrides,+ }) as TEndpoint;++/** The default definition a key takes: the agent settings' over the regular ones, as expansion reads them. */+function getDefinition(defaultParamsEndpoint: string, key: string) {+ const isKey = (param: { key: string }) => param.key === key;+ return (+ agentParamSettings[defaultParamsEndpoint]?.find(isKey) ??+ paramSettings[defaultParamsEndpoint]?.find(isKey)+ );+}++describe('expandCustomEndpoint', () => {+ it('completes compact definitions from the defaults of their endpoint, as a copy', () => {+ const compact = endpoint({+ customParams: {+ defaultParamsEndpoint: 'anthropic',+ paramDefinitions: [{ key: 'temperature', default: 0.2 }],+ },+ });+ const written = structuredClone(compact);++ const expanded = expandCustomEndpoint(compact);++ expect(compact).toEqual(written);+ expect(expanded.customParams?.defaultParamsEndpoint).toBe('anthropic');+ const { range, component, type } = getDefinition('anthropic', 'temperature') ?? {};+ expect(expanded.customParams?.paramDefinitions).toEqual([+ expect.objectContaining({+ key: 'temperature',+ default: 0.2,+ optionType: 'custom',+ range,+ component,+ type,+ }),+ ]);+ expect(expanded.name).toBe('Gateway');+ });++ it('picks the defaults of the endpoint defaultParamsEndpoint names', () => {+ const forOpenAI = expandCustomEndpoint(+ endpoint({+ customParams: { defaultParamsEndpoint: 'openAI', paramDefinitions: [{ key: 'top_p' }] },+ }),+ );++ expect(forOpenAI.customParams?.paramDefinitions?.[0]).toMatchObject({+ ...getDefinition('openAI', 'top_p'),+ optionType: 'custom',+ });+ });++ it('is idempotent: expanding an expanded endpoint changes nothing', () => {+ const once = expandCustomEndpoint(+ endpoint({+ name: 'OpenRouter',+ customParams: { paramDefinitions: [{ key: 'temperature', default: 0.4 }] },+ }),+ );++ expect(expandCustomEndpoint(once)).toEqual(once);+ });++ it("adds OpenRouter's defaults by name or URL, and keeps an explicit promptCache", () => {+ const byName = expandCustomEndpoint(endpoint({ name: 'OpenRouter' }));+ const byURL = expandCustomEndpoint(endpoint({ baseURL: 'https://openrouter.ai/api/v1' }));+ const explicit = expandCustomEndpoint(+ endpoint({+ name: 'OpenRouter',+ customParams: { paramDefinitions: [{ key: 'promptCache', default: false }] },+ }),+ );++ for (const expanded of [byName, byURL]) {+ expect(expanded.customParams?.defaultParamsEndpoint).toBe('openrouter');+ expect(expanded.customParams?.paramDefinitions).toEqual([+ { ...getDefinition('openrouter', 'promptCache'), default: true, optionType: 'custom' },+ ]);+ }+ expect(explicit.customParams?.paramDefinitions).toEqual([+ { ...getDefinition('openrouter', 'promptCache'), default: false, optionType: 'custom' },+ ]);+ });++ it('leaves an OpenRouter endpoint whose defaults come from another provider alone', () => {+ const expanded = expandCustomEndpoint(+ endpoint({ name: 'OpenRouter', customParams: { defaultParamsEndpoint: 'anthropic' } }),+ );++ expect(expanded.customParams).toEqual({+ defaultParamsEndpoint: 'anthropic',+ paramDefinitions: [],+ });+ });++ it('returns an endpoint without customParams as written', () => {+ const plain = endpoint();++ expect(expandCustomEndpoint(plain)).toEqual(plain);+ expect(expandCustomEndpoint(plain)).not.toBe(plain);+ });++ it('throws for an unknown key, an unknown defaultParamsEndpoint and malformed definitions', () => {+ expect(() =>+ expandCustomEndpoint(+ endpoint({ customParams: { paramDefinitions: [{ key: 'notAParameter', default: 1 }] } }),+ ),+ ).toThrow('paramDefinitions of "Gateway" endpoint contains invalid key(s)');+ expect(() =>+ expandCustomEndpoint(endpoint({ customParams: { defaultParamsEndpoint: 'nowhere' } })),+ ).toThrow('defaultParamsEndpoint of "Gateway" endpoint is invalid');+ expect(() =>+ expandCustomEndpoint(+ endpoint({+ customParams: {+ paramDefinitions: [+ { key: 'temperature', type: 'noomba', component: 'inpoot' } as never,+ ],+ },+ }),+ ),+ ).toThrow('Custom parameter definitions for "Gateway" endpoint is malformed');+ });++ it('accepts a valid agent inference extension a provider does not define', () => {+ const expanded = expandCustomEndpoint(+ endpoint({+ customParams: {+ paramDefinitions: [+ {+ key: 'customTemperature',+ type: SettingTypes.Number,+ component: ComponentTypes.Slider,+ default: 0.5,+ range: { min: 0, max: 1, step: 0.1 },+ },+ ],+ },+ }),+ );++ expect(expanded.customParams?.paramDefinitions?.[0]).toMatchObject({+ key: 'customTemperature',+ optionType: 'custom',+ });+ });+});diff --git a/packages/api/src/app/params.ts b/packages/api/src/app/params.tsnew file mode 100644index 0000000000..40bc2b857e--- /dev/null+++ b/packages/api/src/app/params.ts@@ -0,0 +1,132 @@+import { Providers } from '@librechat/agents';+import {+ paramSettings,+ agentParamSettings,+ validateSettingDefinitions,+} from 'librechat-data-provider';+import type { TEndpoint } from 'librechat-data-provider';+import { isAgentInferenceExtension } from '~/agents/inference';++type CustomParams = NonNullable<TEndpoint['customParams']>;+type CustomParamDefinition = NonNullable<CustomParams['paramDefinitions']>[number];++const OPENROUTER_PROMPT_CACHE_DEFAULT = {+ key: 'promptCache',+ default: true,+};++function includesOpenRouter(value: string | undefined): boolean {+ return typeof value === 'string' && value.toLowerCase().includes(Providers.OPENROUTER);+}++function isOpenRouterEndpoint(endpoint: TEndpoint): boolean {+ return includesOpenRouter(endpoint.name) || includesOpenRouter(endpoint.baseURL);+}++function shouldPreserveCustomParams(customParams: CustomParams | undefined): boolean {+ const defaultEndpoint = customParams?.defaultParamsEndpoint;+ return (+ !!defaultEndpoint && defaultEndpoint !== 'custom' && defaultEndpoint !== Providers.OPENROUTER+ );+}++/**+ * OpenRouter's parameter defaults for an endpoint named for it or pointing at it, unless its+ * `customParams` take their defaults from another provider: `defaultParamsEndpoint: openrouter`+ * and a `promptCache` definition defaulting to on.+ */+function withOpenRouterDefaults(endpoint: TEndpoint): CustomParams | undefined {+ const { customParams } = endpoint;+ if (!isOpenRouterEndpoint(endpoint) || shouldPreserveCustomParams(customParams)) {+ return customParams;+ }+ const params: CustomParams = customParams ?? { defaultParamsEndpoint: 'custom' };+ const paramDefinitions = params.paramDefinitions ?? [];+ const hasPromptCache = paramDefinitions.some((param) => param.key === 'promptCache');+ return {+ ...params,+ defaultParamsEndpoint: Providers.OPENROUTER,+ paramDefinitions: hasPromptCache+ ? paramDefinitions+ : [...paramDefinitions, OPENROUTER_PROMPT_CACHE_DEFAULT],+ };+}++/**+ * Parameter definitions completed from the defaults of their `defaultParamsEndpoint`, each+ * marked as a custom option. Throws for an unknown `defaultParamsEndpoint`, a key that is neither+ * a parameter of that endpoint nor a valid agent inference extension, or definitions that do not+ * validate.+ */+function expandCustomParams(+ endpointName: string | undefined,+ customParams: CustomParams,+): CustomParams {+ const paramEndpoint = customParams.defaultParamsEndpoint ?? 'custom';+ const paramDefinitions = customParams.paramDefinitions ?? [];++ const validEndpoints = new Set([+ ...Object.keys(paramSettings),+ ...Object.keys(agentParamSettings),+ ]);+ if (!validEndpoints.has(paramEndpoint)) {+ throw new Error(+ `defaultParamsEndpoint of "${endpointName}" endpoint is invalid. ` ++ `Valid options are ${Array.from(validEndpoints).join(', ')}`,+ );+ }++ const regularParams = paramSettings[paramEndpoint] ?? [];+ const agentParams = agentParamSettings[paramEndpoint] ?? [];+ const defaultParams = regularParams.concat(agentParams);+ const defaultParamsMap = new Map(+ defaultParams.map((param) => [param.key, param as CustomParamDefinition]),+ );+ const invalidKeys = paramDefinitions+ .filter((param) => !defaultParamsMap.has(param.key) && !isAgentInferenceExtension(param))+ .map((param) => param.key);+ if (invalidKeys.length > 0) {+ throw new Error(+ `paramDefinitions of "${endpointName}" endpoint contains invalid key(s). ` ++ `Valid parameter keys are ${Array.from(defaultParamsMap.keys()).join(', ')}`,+ );+ }++ const parsedDefinitions = paramDefinitions.map((param) => ({+ ...defaultParamsMap.get(param.key),+ ...param,+ optionType: 'custom',+ })) as CustomParamDefinition[];++ try {+ validateSettingDefinitions(+ parsedDefinitions as Parameters<typeof validateSettingDefinitions>[0],+ );+ } catch (error) {+ const message = error instanceof Error ? error.message : String(error);+ throw new Error(+ `Custom parameter definitions for "${endpointName}" endpoint is malformed: ${message}`,+ );+ }++ return {+ ...customParams,+ defaultParamsEndpoint: paramEndpoint,+ paramDefinitions: parsedDefinitions,+ };+}++/**+ * A custom endpoint as the runtime serves it from its librechat.yaml form: OpenRouter's defaults+ * added for an endpoint named for it or pointing at it, and its `customParams` expanded (each+ * compact parameter definition completed from the defaults of `defaultParamsEndpoint`). Returns+ * a copy and never changes `endpoint`; expanding an expanded endpoint returns an equal one. Throws+ * when the parameter definitions are invalid, as loading librechat.yaml does.+ */+export function expandCustomEndpoint(endpoint: TEndpoint): TEndpoint {+ const customParams = withOpenRouterDefaults(endpoint);+ if (customParams == null) {+ return { ...endpoint };+ }+ return { ...endpoint, customParams: expandCustomParams(endpoint.name, customParams) };+}diff --git a/packages/api/src/app/rebinding.spec.ts b/packages/api/src/app/rebinding.spec.tsindex a2de856f52..8d9e20422e 100644--- a/packages/api/src/app/rebinding.spec.ts+++ b/packages/api/src/app/rebinding.spec.ts@@ -59,14 +59,24 @@ function baseConfig(): AppConfig {} as unknown as AppConfig;}-function merge(layers: ConfigOverrideLayer[], base = baseConfig()) {+function merge(+ layers: ConfigOverrideLayer[],+ base = baseConfig(),+ derivation: { rederiveEndpoints?: boolean } = {},+) {const rebindings: SecretRebinding[] = [];const merged = mergeConfigOverrides(base, layers, {+ ...derivation,afterLayer: createSecretRebindingGuard((rebinding) => rebindings.push(rebinding)),});return { merged, rebindings, ignored: rebindings.map(toIgnoredSecretOverride) };}+/** {@link merge} as `CONFIG_REDERIVE_ENDPOINTS` runs it: a layer's Azure groups resolved. */+function mergeGroups(layers: ConfigOverrideLayer[], base = baseConfig()) {+ return merge(layers, base, { rederiveEndpoints: true });+}+describe('createSecretRebindingGuard', () => {it('drops an inherited custom endpoint key when a layer points the endpoint elsewhere', () => {const { merged, ignored } = merge([@@ -1367,7 +1377,36 @@ describe('createSecretRebindingGuard', () => {expect(rebindings).toEqual([]);});- it("sets the Vertex AI region back to librechat.yaml's, whatever the override supplies", () => {+ it("reports nothing for Vertex AI a layer turns on, and serves it on librechat.yaml's region", () => {+ const rebindings: SecretRebinding[] = [];+ const yamlVertex = { enabled: false, region: 'europe-west1' };+ const merged = mergeConfigOverrides(+ {+ config: { endpoints: { anthropic: { vertex: yamlVertex } } },+ endpoints: { anthropic: {} },+ } as unknown as AppConfig,+ [+ layer({+ endpoints: {+ anthropic: { vertex: { enabled: true, projectId: 'p-1', region: 'evil' } },+ },+ }),+ ],+ {+ rederiveEndpoints: true,+ afterLayer: createSecretRebindingGuard((rebinding) => rebindings.push(rebinding)),+ },+ );++ expect(merged.endpoints?.anthropic?.vertexConfig).toMatchObject({+ projectId: 'p-1',+ region: 'europe-west1',+ });+ expect(rebindings).toEqual([]);+ });++ it('never applies Vertex AI settings an override writes to the resolved vertexConfig', () => {+ const base = withResolvedEndpoints();const { merged, rebindings } = merge([layer({@@ -1382,16 +1421,13 @@ describe('createSecretRebindingGuard', () => {},}),],- withResolvedEndpoints(),+ base,);- expect(merged.endpoints?.anthropic?.vertexConfig).toMatchObject({- region: 'us-east5',- projectId: 'other-project',- });- expect(rebindings.map(({ kind, path }) => [kind, path])).toEqual([- ['destination', 'endpoints.anthropic.vertexConfig.region'],- ]);+ expect(merged.endpoints?.anthropic?.vertexConfig).toEqual(+ base.endpoints?.anthropic?.vertexConfig,+ );+ expect(rebindings).toEqual([]);});});@@ -1429,25 +1465,153 @@ describe('createSecretRebindingGuard', () => {models: { 'gpt-5': true },};- it("replaces librechat.yaml's groups with the layer's, each with the key it entered", () => {- const { merged, rebindings } = merge(+ it("merges the layer's groups by group over librechat.yaml's, each with the key it entered", () => {+ const { merged, rebindings } = mergeGroups([layer({ endpoints: { azureOpenAI: { groups: [ownGroup] } } }, '__base__', 0)],azureBase(),);const azure = merged.endpoints?.azureOpenAI;- expect(Object.keys(azure?.groupMap ?? {})).toEqual(['west']);+ expect(Object.keys(azure?.groupMap ?? {})).toEqual(['east', 'west']);+ expect(azure?.groupMap?.east).toMatchObject({ apiKey: 'yaml-literal-east-key' });expect(azure?.groupMap?.west).toMatchObject({apiKey: 'v3:west-admin-key',instanceName: 'west',});- expect(azure?.modelGroupMap).toEqual({ 'gpt-5': { group: 'west' } });- expect(azure?.modelNames).toEqual(['gpt-5']);+ expect(azure?.modelGroupMap).toEqual({+ 'gpt-4o': { group: 'east' },+ 'gpt-5': { group: 'west' },+ });+ expect(azure?.modelNames).toEqual(['gpt-4o', 'gpt-5']);+ expect(rebindings).toEqual([]);+ });++ it("replaces librechat.yaml's groups with a layer's that tombstones them", () => {+ const replacing = {+ ...layer({ endpoints: { azureOpenAI: { groups: [ownGroup] } } }, '__base__', 0),+ tombstones: ['endpoints.azureOpenAI.groups'],+ };+ const { merged } = mergeGroups([replacing], azureBase());++ expect(Object.keys(merged.endpoints?.azureOpenAI?.groupMap ?? {})).toEqual(['west']);+ expect(merged.endpoints?.azureOpenAI?.modelNames).toEqual(['gpt-5']);+ });++ it('keeps the inherited key of a librechat.yaml group whose item changes only its models', () => {+ const { merged, rebindings } = mergeGroups(+ [+ layer({+ endpoints: {+ azureOpenAI: {+ groups: [{ group: 'east', models: { 'gpt-4o-mini': { deploymentName: 'mini' } } }],+ },+ },+ }),+ ],+ azureBase(),+ );++ const azure = merged.endpoints?.azureOpenAI;+ expect(azure?.groupMap?.east).toMatchObject({+ apiKey: 'yaml-literal-east-key',+ instanceName: 'east',+ models: { 'gpt-4o': true, 'gpt-4o-mini': { deploymentName: 'mini' } },+ });+ expect(azure?.modelNames).toEqual(['gpt-4o', 'gpt-4o-mini']);expect(rebindings).toEqual([]);});+ it("drops librechat.yaml's key when a partial item points its group elsewhere", () => {+ const { merged, ignored } = mergeGroups(+ [+ layer({+ endpoints: { azureOpenAI: { groups: [{ group: 'east', instanceName: 'evil' }] } },+ }),+ ],+ azureBase(),+ );++ expect(merged.endpoints?.azureOpenAI?.groupMap?.east).toMatchObject({+ apiKey: '',+ instanceName: 'evil',+ });+ expect(ignored.map(({ path }) => path)).toEqual([+ 'endpoints.azureOpenAI.groupMap.east.apiKey',+ ]);+ });++ it('drops and reports nothing without CONFIG_REDERIVE_ENDPOINTS, where the groups stay inert', () => {+ const { merged, ignored } = merge(+ [+ layer({+ endpoints: { azureOpenAI: { groups: [{ group: 'east', instanceName: 'evil' }] } },+ }),+ ],+ azureBase(),+ );++ expect(merged.endpoints?.azureOpenAI?.groupMap).toEqual(+ azureBase().endpoints?.azureOpenAI?.groupMap,+ );+ expect(ignored).toEqual([]);+ });++ it('keeps a key a lower layer dropped dropped when a later layer writes the same group', () => {+ const { merged, ignored } = mergeGroups(+ [+ layer(+ { endpoints: { azureOpenAI: { groups: [{ group: 'east', instanceName: 'evil' }] } } },+ '__base__',+ 0,+ ),+ layer({+ endpoints: {+ azureOpenAI: {+ groups: [{ group: 'east', models: { 'gpt-4o-mini': { deploymentName: 'mini' } } }],+ },+ },+ }),+ ],+ azureBase(),+ );++ expect(merged.endpoints?.azureOpenAI?.groupMap?.east).toMatchObject({+ apiKey: '',+ instanceName: 'evil',+ });+ expect(ignored.map(({ path }) => path)).toEqual([+ 'endpoints.azureOpenAI.groupMap.east.apiKey',+ ]);+ });++ it("drops a layer's own key for a group whose destination a lower layer moved", () => {+ const { merged, rebindings } = mergeGroups(+ [+ layer(+ { endpoints: { azureOpenAI: { groups: [{ group: 'east', instanceName: 'moved' }] } } },+ '__base__',+ 0,+ ),+ layer({+ endpoints: { azureOpenAI: { groups: [{ group: 'east', apiKey: 'v3:own-key' }] } },+ }),+ ],+ azureBase(),+ );++ expect(merged.endpoints?.azureOpenAI?.groupMap?.east).toMatchObject({+ apiKey: '',+ instanceName: 'moved',+ });+ expect(rebindings[rebindings.length - 1]).toMatchObject({+ kind: 'secret',+ path: 'endpoints.azureOpenAI.groupMap.east.apiKey',+ binding: expect.any(String),+ });+ });+it('keeps the key a layer enters for a librechat.yaml group it points elsewhere', () => {- const { merged, rebindings } = merge(+ const { merged, rebindings } = mergeGroups([layer({endpoints: {@@ -1468,7 +1632,7 @@ describe('createSecretRebindingGuard', () => {});it('drops the key of a group a layer resolved once a later layer points it elsewhere', () => {- const { merged, ignored } = merge(+ const { merged, ignored } = mergeGroups([layer({ endpoints: { azureOpenAI: { groups: [ownGroup] } } }, '__base__', 0),layer({ endpoints: { azureOpenAI: { groupMap: { west: { instanceName: 'evil' } } } } }),@@ -1495,7 +1659,7 @@ describe('createSecretRebindingGuard', () => {baseURL: 'https://west.openai.azure.com/openai/deployments/${DEPLOYMENT_NAME}',};const renamed = (group: Record<string, unknown>) =>- merge(+ mergeGroups([layer({ endpoints: { azureOpenAI: { groups: [group] } } }, '__base__', 0),layer({@@ -1517,7 +1681,7 @@ describe('createSecretRebindingGuard', () => {it('binds the destination options its addParams reach the client with', () => {const moved = (addParams: Record<string, unknown>) =>- merge(+ mergeGroups([layer({ endpoints: { azureOpenAI: { groups: [ownGroup] } } }, '__base__', 0),layer({ endpoints: { azureOpenAI: { groupMap: { west: { addParams } } } } }),@@ -1530,7 +1694,7 @@ describe('createSecretRebindingGuard', () => {});it('leaves groups that do not resolve unread, and what lies below in place', () => {- const { merged } = merge(+ const { merged } = mergeGroups([layer({endpoints: { azureOpenAI: { groups: [ownGroup, { ...ownGroup, group: 'w2' }] } },diff --git a/packages/api/src/app/rebinding.ts b/packages/api/src/app/rebinding.tsindex 9421b745e4..7667ebc156 100644--- a/packages/api/src/app/rebinding.ts+++ b/packages/api/src/app/rebinding.ts@@ -187,12 +187,6 @@ const DESTINATION_BINDINGS: readonly DestinationBinding[] = [secret: { key: 'apiKey', client: getSummarizationProvider, isUsed: summarizationUsesKey },fallback: getSummarizationFallback,},- /**- * `vertexConfig` is what librechat.yaml's `endpoints.anthropic.vertex` resolves to, and an- * override can write it directly. Its region is part of the API host, and the credential is- * always the deployment's service account.- */- { path: ['endpoints', 'anthropic', 'vertexConfig'], isDestination: (key) => key === 'region' },];function asRecord(value: unknown): JsonRecord | null {@@ -1348,15 +1342,21 @@ function collectBoundSecretLocations(add([...CUSTOM_ENDPOINTS, String(index)], 'apiKey', [...CUSTOM_ENDPOINTS, name, 'apiKey']);}});+ /**+ * A group's key is served, and its rebinding reported, from the `groupMap` entry the group+ * resolves to, so an item is named by that entry; one without a `group` name by its position.+ */const groups = getAt(root, AZURE_GROUPS_PATH);(Array.isArray(groups) ? groups : []).forEach((item, index) => {- if (asRecord(item) != null) {- add([...AZURE_GROUPS_PATH, String(index)], 'apiKey', [- ...AZURE_GROUPS_PATH,- String(index),- 'apiKey',- ]);+ const record = asRecord(item);+ if (record == null) {+ return;}+ const reported =+ typeof record.group === 'string'+ ? [...AZURE_GROUP_MAP_PATH, record.group, 'apiKey']+ : [...AZURE_GROUPS_PATH, String(index), 'apiKey'];+ add([...AZURE_GROUPS_PATH, String(index)], 'apiKey', reported);});for (const [group, value] of Object.entries(asRecord(getAt(root, AZURE_GROUP_MAP_PATH)) ?? {})) {if (asRecord(value) != null) {@@ -1422,7 +1422,7 @@ export function withoutStoredSecretBindings<T>(overrides: T): T {* - a secret a layer supplies is bound to the destination librechat.yaml and that layer define;* when another layer below it changed that destination, the layer's secret is dropped;* - where a reader falls back to a deployment credential when the config holds no key it uses- * (summarization, Vertex AI), the destination is set back instead: it may differ from+ * (summarization), the destination is set back instead: it may differ from* librechat.yaml's only together with a key the layer enters and the reader authenticates* with, and stays librechat.yaml's only while it receives the credential librechat.yaml sends* there. A key that another client would read than the one it was entered for is removed.@@ -1431,8 +1431,10 @@ export function withoutStoredSecretBindings<T>(overrides: T): T {* search: MCP servers (URL, transport, proxy, auth header, OAuth endpoints), custom endpoints* (base URL, `provider`, and the destination options of `addParams` and `dropParams`, matched by* the name the merge folds), OCR, speech, summarization parameters, the resolved Azure groups- * (`groupMap`, which a layer's `groups` resolve to, or which it writes directly) and the Vertex AI- * settings (`vertexConfig`) an override can write directly. Web+ * (`groupMap`, which a layer's `groups` resolve to, or which it writes directly). Vertex AI,+ * which sends the deployment's service account, is not among them: the merge derives its+ * `vertexConfig` from a layer's `vertex` on librechat.yaml's region and key file (base-only), and+ * never applies a layer's own `vertexConfig`, so no layer moves where that credential goes. Web* search keys follow the merge's own rule (`unbindWebSearchKeys`, which keeps a key over an* inherited `${VAR}` or default URL), and its drops are reported like these* (`mergeOverrideLayers`); a web search URL a layer points at another `${VAR}` without enteringdiff --git a/packages/api/src/app/report.spec.ts b/packages/api/src/app/report.spec.tsnew file mode 100644index 0000000000..8ca56c7985--- /dev/null+++ b/packages/api/src/app/report.spec.ts@@ -0,0 +1,226 @@+import { logger } from '@librechat/data-schemas';+import type { ReportedConfig } from './report';+import { getEndpointOverrideReport, reportEndpointOverrides } from './report';++const east = {+ group: 'east',+ apiKey: 'east-key',+ instanceName: 'east',+ version: '2024-10-21',+ deploymentName: 'gpt-4o',+ models: { 'gpt-4o': true },+};+const yaml = { endpoints: { azureOpenAI: { groups: [east] } } };++function config(+ principalId: string,+ overrides: Record<string, unknown>,+ extra: Partial<ReportedConfig> = {},+): ReportedConfig {+ return {+ principalType: 'role',+ principalId,+ priority: 10,+ overrides,+ ...extra,+ } as ReportedConfig;+}++describe('getEndpointOverrideReport', () => {+ it('sorts documents by what this release changes for their endpoint overrides', () => {+ const report = getEndpointOverrideReport(+ [+ config('vertex', { endpoints: { anthropic: { vertex: { enabled: false } } } }),+ config(+ 'assistants',+ { endpoints: { azureOpenAI: { assistants: true } } },+ { tenantId: 't1' },+ ),+ config('merged', {+ endpoints: {+ azureOpenAI: { groups: [{ group: 'east', models: { o3: { deploymentName: 'o3' } } }] },+ },+ }),+ /** A full copy an older admin panel stored, with the deployment names it left blank. */+ config(+ 'noise',+ { endpoints: { azureOpenAI: { groups: [{ ...east, deploymentName: '' }] } } },+ { isActive: false },+ ),+ config(+ 'replaced',+ {+ endpoints: {+ azureOpenAI: { groups: [{ ...east, group: 'west', models: { 'gpt-5': true } }] },+ },+ },+ {+ tombstones: ['endpoints.azureOpenAI.groups'],+ },+ ),+ config('plain', { interface: { customWelcome: 'hi' } }),+ config('removed', {}, { tombstones: ['endpoints.azureOpenAI.groups'] }),+ config('unvertexed', {}, { tombstones: ['endpoints.anthropic.vertex'] }),+ ],+ yaml,+ );++ expect(report).toEqual({+ rederived: ['role/assistants in tenant t1'],+ ignoredVertex: ['role/vertex', 'role/unvertexed'],+ azureGroups: ['role/merged', 'role/replaced', 'role/removed'],+ unresolvedAzureGroups: ['role/noise (inactive)'],+ });+ });++ it('lists Vertex AI overrides as applied only where librechat.yaml configures Vertex AI', () => {+ const configs = [+ config('vertex', { endpoints: { anthropic: { vertex: { models: ['m'] } } } }),+ config('unvertexed', {}, { tombstones: ['endpoints.anthropic.vertex'] }),+ ];+ const configured = (vertex: Record<string, unknown>) =>+ getEndpointOverrideReport(configs, {+ ...yaml,+ endpoints: { ...yaml.endpoints, anthropic: { vertex } },+ });++ for (const report of [configured({ projectId: 'p' }), configured({ enabled: false })]) {+ expect(report.rederived).toEqual(['role/vertex', 'role/unvertexed']);+ expect(report.ignoredVertex).toEqual([]);+ }+ });++ it("judges a profile's groups over its tenant's active Base profile, which merges first", () => {+ const review = {+ ...east,+ group: 'west-review',+ instanceName: 'west-review',+ models: { 'gpt-west-review': true },+ };+ const partial = {+ endpoints: {+ azureOpenAI: {+ groups: [+ { group: 'west-review', models: { 'gpt-west-review-2': { deploymentName: 'r2' } } },+ ],+ },+ },+ };+ const base = (extra: Partial<ReportedConfig> = {}) =>+ config('__base__', { endpoints: { azureOpenAI: { groups: [review] } } }, extra);++ const report = getEndpointOverrideReport(+ [+ base(),+ config('USER', partial),+ base({ tenantId: 't2', isActive: false }),+ config('ADMIN', partial, { tenantId: 't2' }),+ config('OTHER', partial, { tenantId: 't3' }),+ ],+ yaml,+ );++ expect(report).toEqual({+ rederived: [],+ ignoredVertex: [],+ azureGroups: ['role/__base__', 'role/USER', 'role/__base__ in tenant t2 (inactive)'],+ unresolvedAzureGroups: ['role/ADMIN in tenant t2', 'role/OTHER in tenant t3'],+ });+ });+});++describe('reportEndpointOverrides', () => {+ const vertex = config('vertex', { endpoints: { anthropic: { vertex: { models: ['m'] } } } });+ const vertexYaml = {+ endpoints: { ...yaml.endpoints, anthropic: { vertex: { projectId: 'p' } } },+ };++ const groups = config('groups', {+ endpoints: {+ azureOpenAI: { groups: [{ group: 'east', models: { o3: { deploymentName: 'o3' } } }] },+ },+ });+ const noise = config('noise', {+ endpoints: { azureOpenAI: { groups: [{ ...east, deploymentName: '' }] } },+ });++ it('warns about every override the switch would apply, Azure groups included, while it is off', async () => {+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);+ const info = jest.spyOn(logger, 'info').mockImplementation(() => logger);+ const listConfigs = jest.fn().mockResolvedValue([vertex, groups, noise]);++ await reportEndpointOverrides({ listConfigs, baseYaml: vertexYaml, rederiveEndpoints: false });++ expect(warn).toHaveBeenCalledTimes(2);+ expect(warn).toHaveBeenNthCalledWith(+ 1,+ expect.stringMatching(+ /inert until CONFIG_REDERIVE_ENDPOINTS=true.*: role\/vertex, role\/groups, role\/noise$/,+ ),+ );+ expect(warn).toHaveBeenNthCalledWith(+ 2,+ expect.stringMatching(/would leave them out.*: role\/noise$/),+ );+ expect(info).not.toHaveBeenCalled();+ warn.mockRestore();+ info.mockRestore();+ });++ it('lists the overrides it applies, and the groups it leaves out, while it is on', async () => {+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);+ const info = jest.spyOn(logger, 'info').mockImplementation(() => logger);+ const listConfigs = jest.fn().mockResolvedValue([vertex, groups, noise]);++ await reportEndpointOverrides({ listConfigs, baseYaml: vertexYaml, rederiveEndpoints: true });++ expect(info).toHaveBeenCalledWith(+ expect.stringMatching(/Applying the Vertex AI.*role\/vertex$/),+ );+ expect(info).toHaveBeenCalledWith(+ expect.stringMatching(/Applying the Azure groups.*role\/groups$/),+ );+ expect(warn).toHaveBeenCalledTimes(1);+ expect(warn).toHaveBeenCalledWith(expect.stringMatching(/^\[config\] Ignoring.*role\/noise$/));+ warn.mockRestore();+ info.mockRestore();+ });++ it.each([false, true])(+ 'warns, switch on or off (%s), of Vertex AI overrides librechat.yaml configures none for',+ async (rederiveEndpoints) => {+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);+ const info = jest.spyOn(logger, 'info').mockImplementation(() => logger);+ const listConfigs = jest.fn().mockResolvedValue([vertex]);++ const report = await reportEndpointOverrides({+ listConfigs,+ baseYaml: yaml,+ rederiveEndpoints,+ });++ expect(report?.ignoredVertex).toEqual(['role/vertex']);+ expect(warn).toHaveBeenCalledTimes(1);+ expect(warn).toHaveBeenCalledWith(+ expect.stringMatching(/librechat\.yaml configures no Vertex AI.*: role\/vertex$/),+ );+ expect(info).not.toHaveBeenCalled();+ warn.mockRestore();+ info.mockRestore();+ },+ );++ it('logs a failure to list the documents and never throws', async () => {+ const error = jest.spyOn(logger, 'error').mockImplementation(() => logger);++ await expect(+ reportEndpointOverrides({+ listConfigs: jest.fn().mockRejectedValue(new Error('db down')),+ baseYaml: {},+ rederiveEndpoints: false,+ }),+ ).resolves.toBeNull();+ expect(error).toHaveBeenCalledTimes(1);+ error.mockRestore();+ });+});diff --git a/packages/api/src/app/report.ts b/packages/api/src/app/report.tsnew file mode 100644index 0000000000..89e0c3b90f--- /dev/null+++ b/packages/api/src/app/report.ts@@ -0,0 +1,222 @@+import { EModelEndpoint } from 'librechat-data-provider';+import {+ logger,+ getAtPath,+ resolveRawConfig,+ isVertexConfigured,+ mergeConfigEntries,+ isBaseConfigPrincipal,+ applyConfigTombstones,+ resolveServedAzureGroups,+} from '@librechat/data-schemas';+import type { ConfigOverrideLayer } from '@librechat/data-schemas';+import type { TCustomConfig } from 'librechat-data-provider';++const ENDPOINTS = 'endpoints';+const AZURE_GROUPS = [ENDPOINTS, EModelEndpoint.azureOpenAI, 'groups'];+const AZURE_GROUPS_PATH = AZURE_GROUPS.join('.');+const VERTEX = [ENDPOINTS, EModelEndpoint.anthropic, 'vertex'];+/**+ * Where the overrides `CONFIG_REDERIVE_ENDPOINTS` applies sit, besides Azure `groups` and Vertex+ * AI (which it applies only where librechat.yaml configures Vertex AI).+ */+const AZURE_ASSISTANTS_PATHS = [+ [ENDPOINTS, EModelEndpoint.azureOpenAI, 'assistants'],+ [ENDPOINTS, EModelEndpoint.azureAssistants],+];++/** A stored config document, as the startup report reads it. */+export type ReportedConfig = ConfigOverrideLayer & {+ tenantId?: string | null;+ isActive?: boolean;+};++/**+ * The config documents whose endpoint overrides `CONFIG_REDERIVE_ENDPOINTS` applies, which are+ * inert without it, by description.+ */+export interface EndpointOverrideReport {+ /**+ * Documents that write or tombstone Vertex AI (`endpoints.anthropic.vertex`, where librechat.yaml+ * configures it) or the Azure Assistants switches (`endpoints.azureOpenAI.assistants`,+ * `endpoints.azureAssistants`).+ */+ rederived: string[];+ /**+ * Documents that write or tombstone Vertex AI where librechat.yaml configures none: the merge+ * never applies those overrides, whether the switch is on or off.+ */+ ignoredVertex: string[];+ /**+ * Documents whose Azure `groups`, merged by `group` over the groups below them (librechat.yaml's,+ * and the active Base profile's for any other document), resolve, or that tombstone them.+ */+ azureGroups: string[];+ /**+ * Documents whose Azure `groups` do not resolve over those groups (such as full copies an older+ * admin panel stored with blank deployment names), which the merge leaves out.+ */+ unresolvedAzureGroups: string[];+}++function describeConfig(config: ReportedConfig): string {+ const principal = `${config.principalType}/${config.principalId.toString()}`;+ const tenant = config.tenantId ? ` in tenant ${config.tenantId}` : '';+ const inactive = config.isActive === false ? ' (inactive)' : '';+ return `${principal}${tenant}${inactive}`;+}++function getGroupNames(groups: unknown[]): Set<string> {+ const names = new Set<string>();+ for (const item of groups) {+ const name = (item as { group?: unknown } | null)?.group;+ if (typeof name === 'string') {+ names.add(name);+ }+ }+ return names;+}++function getTombstones(config: ReportedConfig): string[] {+ return (config.tombstones ?? []).filter((path): path is string => typeof path === 'string');+}++/** Whether a document writes `segments`, or tombstones it or anything below it. */+function holds(config: ReportedConfig, tombstones: string[], segments: string[]): boolean {+ const path = segments.join('.');+ return (+ getAtPath(config.overrides, segments) !== undefined ||+ tombstones.some((tombstone) => tombstone === path || tombstone.startsWith(`${path}.`))+ );+}++function getTenantKey(config: ReportedConfig): string {+ return config.tenantId ?? '';+}++/**+ * Sorts the stored config documents by what `CONFIG_REDERIVE_ENDPOINTS` changes for their+ * endpoint overrides. Each document's Azure `groups` are judged as a write validates them: over+ * `baseYaml`, and for any document but the Base profile over its tenant's active Base profile too,+ * which the merge applies first.+ */+export function getEndpointOverrideReport(+ configs: readonly ReportedConfig[],+ baseYaml: Partial<TCustomConfig>,+): EndpointOverrideReport {+ const report: EndpointOverrideReport = {+ rederived: [],+ ignoredVertex: [],+ azureGroups: [],+ unresolvedAzureGroups: [],+ };+ const vertexConfigured = isVertexConfigured(baseYaml);+ const bases = new Map<string, ReportedConfig>();+ for (const config of configs) {+ if (isBaseConfigPrincipal(config) && config.isActive !== false) {+ bases.set(getTenantKey(config), config);+ }+ }+ const floors = new Map<string, Partial<TCustomConfig>>();+ const getFloor = (config: ReportedConfig): Partial<TCustomConfig> => {+ const key = getTenantKey(config);+ const base = isBaseConfigPrincipal(config) ? undefined : bases.get(key);+ if (base == null) {+ return baseYaml;+ }+ let floor = floors.get(key);+ if (floor == null) {+ floor = resolveRawConfig(baseYaml, [base]);+ floors.set(key, floor);+ }+ return floor;+ };+ for (const config of configs) {+ const description = describeConfig(config);+ const tombstones = getTombstones(config);+ const holdsVertex = holds(config, tombstones, VERTEX);+ if (holdsVertex && !vertexConfigured) {+ report.ignoredVertex.push(description);+ }+ if (+ (holdsVertex && vertexConfigured) ||+ AZURE_ASSISTANTS_PATHS.some((segments) => holds(config, tombstones, segments))+ ) {+ report.rederived.push(description);+ }+ const groups = getAtPath(config.overrides, AZURE_GROUPS);+ if (!Array.isArray(groups)) {+ if (tombstones.includes(AZURE_GROUPS_PATH)) {+ report.azureGroups.push(description);+ }+ continue;+ }+ const below = getAtPath(applyConfigTombstones(getFloor(config), tombstones), AZURE_GROUPS);+ const merged = mergeConfigEntries(AZURE_GROUPS, below, groups);+ const resolves = resolveServedAzureGroups(merged, getGroupNames(groups)).isValid;+ (resolves ? report.azureGroups : report.unresolvedAzureGroups).push(description);+ }+ return report;+}++/**+ * Logs, once at startup, the config documents whose endpoint overrides `CONFIG_REDERIVE_ENDPOINTS`+ * applies: with it, which Vertex AI, Azure Assistants and Azure `groups` overrides apply and+ * which groups do not resolve and are left out; without it, which documents hold overrides that+ * are inert until it is set, and which of their groups would not resolve then either. Either way,+ * the documents whose Vertex AI overrides never apply, because librechat.yaml configures no Vertex+ * AI. A failure to read or judge the documents is logged and never rejects.+ */+export async function reportEndpointOverrides(params: {+ listConfigs: () => Promise<readonly ReportedConfig[]>;+ baseYaml: Partial<TCustomConfig>;+ rederiveEndpoints: boolean;+}): Promise<EndpointOverrideReport | null> {+ const { listConfigs, baseYaml, rederiveEndpoints } = params;+ let report: EndpointOverrideReport;+ try {+ report = getEndpointOverrideReport(await listConfigs(), baseYaml);+ } catch (error) {+ logger.error(+ '[config] Could not report the endpoint overrides of the config documents:',+ error,+ );+ return null;+ }+ const { rederived, ignoredVertex, azureGroups, unresolvedAzureGroups } = report;+ if (ignoredVertex.length > 0) {+ logger.warn(+ `[config] Ignoring the Vertex AI overrides (endpoints.anthropic.vertex) of these config documents, because librechat.yaml configures no Vertex AI; configure it there or remove them: ${ignoredVertex.join(', ')}`,+ );+ }+ if (!rederiveEndpoints) {+ const inert = [...new Set([...rederived, ...azureGroups, ...unresolvedAzureGroups])];+ if (inert.length > 0) {+ logger.warn(+ `[config] These config documents hold Vertex AI, Azure Assistants or Azure groups overrides that are inert until CONFIG_REDERIVE_ENDPOINTS=true, which will become the default; review them before enabling it: ${inert.join(', ')}`,+ );+ }+ if (unresolvedAzureGroups.length > 0) {+ logger.warn(+ `[config] The Azure groups of these config documents do not resolve over librechat.yaml and the Base profile, so CONFIG_REDERIVE_ENDPOINTS would leave them out; rewrite or remove them: ${unresolvedAzureGroups.join(', ')}`,+ );+ }+ return report;+ }+ if (rederived.length > 0) {+ logger.info(+ `[config] Applying the Vertex AI and Azure Assistants overrides (CONFIG_REDERIVE_ENDPOINTS) of: ${rederived.join(', ')}`,+ );+ }+ if (azureGroups.length > 0) {+ logger.info(+ `[config] Applying the Azure groups (CONFIG_REDERIVE_ENDPOINTS; merged by group over librechat.yaml's and the Base profile's) of: ${azureGroups.join(', ')}`,+ );+ }+ if (unresolvedAzureGroups.length > 0) {+ logger.warn(+ `[config] Ignoring the Azure groups of these config documents, which do not resolve over librechat.yaml and the Base profile; rewrite or remove them: ${unresolvedAzureGroups.join(', ')}`,+ );+ }+ return report;+}diff --git a/packages/api/src/app/service.spec.ts b/packages/api/src/app/service.spec.tsindex 2cec1c953c..deaad44f54 100644--- a/packages/api/src/app/service.spec.ts+++ b/packages/api/src/app/service.spec.ts@@ -5,6 +5,7 @@ import {getTenantId,tenantStorage,SYSTEM_TENANT_ID,+ BASE_CONFIG_PRINCIPAL_ID,} from '@librechat/data-schemas';import type { AppConfig } from '@librechat/data-schemas';import {@@ -16,6 +17,7 @@ import {} from './service';import { loadCustomEndpointsConfig } from '~/endpoints/custom/config';import { getProviderConfig } from '~/endpoints/config/providers';+import { expandCustomEndpoint } from './params';import { ConfigReloadError } from './loader';/** Extends AppConfig with mock fields used by merge behavior tests. */@@ -2172,3 +2174,1108 @@ describe('message App budget reader composition', () => {await expect(b.getBudget()).rejects.toThrow('not been initialized');});});++describe('what getAppConfig derives again for the parts profiles write', () => {+ type Yaml = NonNullable<Parameters<typeof AppService>[0]>['config'];+ const spec = (name: string, endpoint: string) => ({+ name,+ label: name,+ preset: { endpoint, model: 'm' },+ });+ const profile = (overrides: Record<string, unknown>, tombstones: string[] = []) => ({+ principalType: PrincipalType.ROLE,+ principalId: 'USER',+ priority: 10,+ isActive: true,+ overrides,+ tombstones,+ });+ function serviceOver(+ yaml: Record<string, unknown>,+ layers: ReturnType<typeof profile>[],+ options: { rederiveEndpoints?: boolean } = {},+ ) {+ return createAppConfigService(+ createDeps({+ loadBaseConfig: () =>+ AppService({ config: structuredClone(yaml) as Yaml, expandCustomEndpoint }),+ getApplicableConfigs: jest.fn().mockResolvedValue(layers),+ ...options,+ }),+ );+ }+ const specControls = (config: AppConfig) => {+ const { modelSelect, parameters, presets } = config.interfaceConfig ?? {};+ return { modelSelect, parameters, presets };+ };+ const ON = { modelSelect: true, parameters: true, presets: true };+ const OFF = { modelSelect: false, parameters: false, presets: false };++ it('turns the spec-dependent interface controls off for a profile that adds specs', async () => {+ const added = await serviceOver({}, [+ profile({ modelSpecs: { list: [spec('s', 'openAI')] } }),+ ]).getAppConfig({ role: 'USER' });+ const withEndpoints = await serviceOver({}, [+ profile({ modelSpecs: { list: [spec('s', 'openAI')], addedEndpoints: ['openAI'] } }),+ ]).getAppConfig({ role: 'USER' });+ const explicit = await serviceOver({}, [+ profile({ modelSpecs: { list: [spec('s', 'openAI')] }, interface: { parameters: true } }),+ ]).getAppConfig({ role: 'USER' });++ expect(specControls(await serviceOver({}, []).getAppConfig({ role: 'USER' }))).toEqual(ON);+ expect(specControls(added)).toEqual(OFF);+ expect(specControls(withEndpoints)).toEqual({ ...OFF, modelSelect: true });+ expect(specControls(explicit)).toEqual({ ...OFF, parameters: true });+ });++ it('turns them back on when a profile removes every spec librechat.yaml serves', async () => {+ const yaml = { modelSpecs: { list: [spec('s', 'openAI')] } };+ const tombstoned = await serviceOver(yaml, [profile({}, ['modelSpecs'])]).getAppConfig({+ role: 'USER',+ });+ const emptied = await serviceOver(yaml, [profile({ modelSpecs: { list: [] } })]).getAppConfig({+ role: 'USER',+ });++ expect(specControls(await serviceOver(yaml, []).getAppConfig({ role: 'USER' }))).toEqual(OFF);+ expect(specControls(tombstoned)).toEqual(ON);+ expect(specControls(emptied)).toEqual(ON);+ });++ it('derives a control a profile unsets from the specs it is served', async () => {+ const yaml = {+ interface: { parameters: true, presets: true },+ modelSpecs: { list: [spec('s', 'openAI')] },+ };+ const unset = await serviceOver(yaml, [profile({}, ['interface.parameters'])]).getAppConfig({+ role: 'USER',+ });+ const unsetWithoutSpecs = await serviceOver(yaml, [+ profile({}, ['interface.parameters', 'modelSpecs']),+ ]).getAppConfig({ role: 'USER' });++ expect(specControls(await serviceOver(yaml, []).getAppConfig({ role: 'USER' }))).toEqual({+ modelSelect: false,+ parameters: true,+ presets: true,+ });+ expect(specControls(unset)).toEqual({ modelSelect: false, parameters: false, presets: true });+ expect(specControls(unsetWithoutSpecs)).toEqual(ON);+ });++ describe('a control one profile sets and another tombstones', () => {+ const above = (tombstones: string[]) => ({ ...profile({}, tombstones), priority: 20 });+ const served = async (yaml: Record<string, unknown>, layers: ReturnType<typeof profile>[]) =>+ specControls(await serviceOver(yaml, layers).getAppConfig({ role: 'USER' }));+ const withSpecs = { modelSpecs: { list: [spec('s', 'openAI')] } };++ it('derives it from the specs served once a higher profile tombstones it', async () => {+ const hidden = profile({ interface: { parameters: false, presets: false } });+ const shown = profile({ interface: { parameters: true } });+ const tombstone = above(['interface.parameters', 'interface.presets']);++ expect(await served({}, [hidden])).toEqual({ ...ON, parameters: false, presets: false });+ expect(await served({}, [hidden, tombstone])).toEqual(ON);+ expect(await served(withSpecs, [shown])).toEqual({ ...OFF, parameters: true });+ expect(await served(withSpecs, [shown, above(['interface.parameters'])])).toEqual(OFF);+ });++ it('derives it where a profile tombstones a control librechat.yaml leaves unset', async () => {+ expect(await served({}, [profile({}, ['interface.parameters'])])).toEqual(ON);+ expect(await served(withSpecs, [profile({}, ['interface.modelSelect'])])).toEqual(OFF);+ });++ it('keeps what a higher profile sets over a lower tombstone of it', async () => {+ const tombstone = profile({}, ['interface.parameters']);+ const sets = (parameters: boolean) => ({+ ...profile({ interface: { parameters } }),+ priority: 20,+ });++ expect(await served({}, [tombstone, sets(false)])).toEqual({ ...ON, parameters: false });+ expect(await served(withSpecs, [tombstone, sets(true)])).toEqual({+ ...OFF,+ parameters: true,+ });+ expect(+ await served({ ...withSpecs, interface: { parameters: true } }, [tombstone, sets(true)]),+ ).toEqual({ ...OFF, parameters: true });+ });++ it('follows the specs the profiles leave, added then tombstoned or the reverse', async () => {+ const adds = (priority: number) => ({+ ...profile({ modelSpecs: { list: [spec('s2', 'openAI')] } }),+ priority,+ });+ const tombstone = (priority: number) => ({ ...profile({}, ['modelSpecs']), priority });++ expect(await served({}, [adds(10), tombstone(20)])).toEqual(ON);+ expect(await served(withSpecs, [tombstone(10), adds(20)])).toEqual(OFF);+ });+ });++ it("turns them back on when tenant scoping hides the only endpoint a profile's specs use", async () => {+ const yaml = {+ endpoints: {+ custom: [+ {+ name: 'TenantOnly',+ tenantId: 'tenant-a',+ apiKey: 'k',+ baseURL: 'https://t',+ models: { default: ['m'] },+ },+ ],+ },+ };+ const service = serviceOver(yaml, [+ profile({ modelSpecs: { list: [spec('s', 'TenantOnly')] } }),+ ]);++ const owner = await service.getAppConfig({ role: 'USER', tenantId: 'tenant-a' });+ const other = await service.getAppConfig({ role: 'USER', tenantId: 'tenant-b' });++ expect(specControls(owner)).toEqual(OFF);+ expect(other.modelSpecs).toBeUndefined();+ expect(specControls(other)).toEqual(ON);+ });++ it('expands the parameters a profile writes, and OpenRouter defaults for an endpoint only it defines', async () => {+ const gateway = {+ name: 'Gateway',+ apiKey: 'gateway-key',+ baseURL: 'https://gateway.example.com/v1',+ models: { default: ['m1'] },+ customParams: {+ defaultParamsEndpoint: 'anthropic',+ paramDefinitions: [{ key: 'temperature', default: 0.2 }],+ },+ };+ const service = serviceOver({ endpoints: { custom: [gateway] } }, [+ profile({+ endpoints: {+ custom: [+ { name: 'Gateway', customParams: { defaultParamsEndpoint: 'openAI' } },+ {+ ...gateway,+ name: 'Router',+ baseURL: 'https://openrouter.ai/api/v1',+ customParams: undefined,+ },+ ],+ },+ }),+ ]);++ const base = await service.getAppConfig({ baseOnly: true });+ const config = await service.getAppConfig({ role: 'USER' });+ const served = (name: string) => config.endpoints?.custom?.find((entry) => entry.name === name);++ expect(base.config.endpoints?.custom?.[0]?.customParams).toEqual(gateway.customParams);+ expect(served('Gateway')?.customParams?.defaultParamsEndpoint).toBe('openAI');+ expect(served('Gateway')?.customParams?.paramDefinitions?.[0]).toMatchObject({+ key: 'temperature',+ default: 0.2,+ optionType: 'custom',+ component: 'slider',+ });+ expect(served('Router')?.customParams).toMatchObject({+ defaultParamsEndpoint: 'openrouter',+ paramDefinitions: [expect.objectContaining({ key: 'promptCache', default: true })],+ });+ });++ it('derives Vertex AI a profile writes only when the service re-derives endpoints', async () => {+ const yaml = {+ endpoints: {+ anthropic: {+ vertex: { projectId: 'yaml-project', region: 'us-east5', models: ['claude-sonnet-4-6'] },+ },+ },+ };+ const layers = [+ profile({ endpoints: { anthropic: { vertex: { models: ['claude-opus-4-6'] } } } }),+ ];+ const served = async (rederiveEndpoints: boolean) => {+ const service = serviceOver(yaml, layers, { rederiveEndpoints });+ expect(service.rederiveEndpoints).toBe(rederiveEndpoints);+ return (await service.getAppConfig({ role: 'USER' })).endpoints?.anthropic?.models;+ };++ expect(await served(false)).toEqual(['claude-sonnet-4-6']);+ expect(await served(true)).toEqual(['claude-opus-4-6']);+ });++ describe('Vertex AI settings a profile references a variable in', () => {+ const saved = { ...process.env };+ const yaml = {+ endpoints: {+ anthropic: { vertex: { projectId: '${GCP_PROJECT}', models: ['claude-sonnet-4-6'] } },+ },+ };+ const vertexOf = async (vertex: Record<string, unknown>) =>+ (+ await serviceOver(yaml, [profile({ endpoints: { anthropic: { vertex } } })], {+ rederiveEndpoints: true,+ }).getAppConfig({ role: 'USER' })+ ).endpoints?.anthropic?.vertexConfig;+ beforeEach(() => {+ process.env.OPENAI_API_KEY = 'sk-deployment-openai-key';+ process.env.GCP_PROJECT = 'yaml-gcp-project';+ });+ afterEach(() => {+ process.env = { ...saved };+ });++ it('never resolves a credential into the derived vertexConfig a read returns', async () => {+ const vertexConfig = await vertexOf({+ projectId: '${OPENAI_API_KEY}',+ deploymentName: '${OPENAI_API_KEY}',+ models: ['claude-opus-4-6'],+ });++ expect(vertexConfig?.modelNames).toEqual(['claude-opus-4-6']);+ expect(JSON.stringify(vertexConfig)).not.toContain('sk-deployment-openai-key');+ /** The reference resolves to nothing, as an unset variable: librechat.yaml's value stays. */+ expect(vertexConfig?.projectId).toBe('yaml-gcp-project');+ expect(vertexConfig?.deploymentName).toBeUndefined();+ expect(vertexConfig?.modelDeploymentMap).toEqual({ 'claude-opus-4-6': 'claude-opus-4-6' });+ });++ it("resolves the variables librechat.yaml's own Vertex AI settings reference", async () => {+ const vertexConfig = await vertexOf({+ deploymentName: '${GCP_PROJECT}',+ models: ['claude-opus-4-6'],+ });++ expect(vertexConfig?.projectId).toBe('yaml-gcp-project');+ expect(vertexConfig?.modelDeploymentMap).toEqual({ 'claude-opus-4-6': 'yaml-gcp-project' });+ });+ });++ /**+ * Every part the merge derives again, judged on what the layers leave: for each way a layer+ * changes its inputs (a set, an unset, a tombstone of the path and of each object above it, a+ * higher layer recreating what such a tombstone removed, the Base profile on either side, tenant+ * scoping), the served part is what startup derives from the librechat.yaml the layers leave+ * (`as`), or, where no librechat.yaml loads to it, the value given (`expected`).+ */+ describe('each derived part follows what the layers leave', () => {+ type Layer = ReturnType<typeof profile>;+ type Yaml = Record<string, unknown>;+ type Probe = (config: AppConfig) => unknown;+ interface Cell {+ change: string;+ layers: Layer[];+ as?: Yaml;+ expected?: unknown;+ yaml?: Yaml;+ rederiveEndpoints?: boolean;+ tenantId?: string;+ }+ const base = (overrides: Yaml = {}, tombstones: string[] = []): Layer => ({+ ...profile(overrides, tombstones),+ principalId: BASE_CONFIG_PRINCIPAL_ID,+ priority: 0,+ });+ const role = (overrides: Yaml = {}, tombstones: string[] = []): Layer =>+ profile(overrides, tombstones);+ const above = (overrides: Yaml = {}, tombstones: string[] = []): Layer => ({+ ...profile(overrides, tombstones),+ principalId: 'ADMIN',+ priority: 20,+ });+ /** `yaml` with `value` at a dotted path, or without what is there for `undefined`. */+ const at = (yaml: Yaml, path: string, value?: unknown): Yaml => {+ const [key, ...rest] = path.split('.');+ const next = { ...yaml };+ if (rest.length > 0) {+ next[key] = at((yaml[key] as Yaml | undefined) ?? {}, rest.join('.'), value);+ } else if (value === undefined) {+ delete next[key];+ } else {+ next[key] = value;+ }+ return next;+ };+ const write = (path: string, value: unknown): Yaml => at({}, path, value);++ const AZURE = 'endpoints.azureOpenAI';+ const GROUPS = `${AZURE}.groups`;+ const ASSISTANTS = `${AZURE}.assistants`;+ const ANTHROPIC = 'endpoints.anthropic';+ const VERTEX = `${ANTHROPIC}.vertex`;+ const MODELS = `${ANTHROPIC}.models`;+ const CUSTOM = 'endpoints.custom';+ const AGENTS = 'endpoints.agents';+ const east = {+ group: 'east',+ apiKey: 'east-key',+ instanceName: 'east',+ version: '2024-10-21',+ deploymentName: 'gpt-4o',+ assistants: true,+ models: { 'gpt-4o': true },+ };+ const west = {+ group: 'west',+ apiKey: 'west-key',+ instanceName: 'west',+ version: '2024-10-21',+ deploymentName: 'gpt-5',+ models: { 'gpt-5': true },+ };+ const yamlVertex = {+ projectId: 'yaml-project',+ region: 'us-east5',+ models: ['claude-sonnet-4-6'],+ };+ const profileVertex = { projectId: 'profile-project', models: ['claude-opus-4-6'] };+ /** Loads only with a default deployment name: the model name is not one path segment. */+ const namedVertex = { ...yamlVertex, models: { 'Claude Team': true } };+ const gateway = {+ name: 'Gateway',+ apiKey: 'gateway-key',+ baseURL: 'https://gateway.example.com/v1',+ models: { default: ['m1'] },+ customParams: {+ defaultParamsEndpoint: 'anthropic',+ paramDefinitions: [{ key: 'temperature', default: 0.2 }],+ },+ };+ const openAIGateway = {+ ...gateway,+ customParams: { ...gateway.customParams, defaultParamsEndpoint: 'openAI' },+ };+ const router = {+ name: 'Router',+ apiKey: 'router-key',+ baseURL: 'https://openrouter.ai/api/v1',+ models: { default: ['m1'] },+ };+ const YAML: Yaml = {+ endpoints: {+ azureOpenAI: { assistants: true, groups: [east] },+ anthropic: { models: ['claude-direct'], vertex: yamlVertex },+ custom: [gateway],+ },+ memory: { disabled: true },+ modelSpecs: { list: [spec('s', 'openAI')] },+ };+ const tenantOnly = {+ name: 'TenantOnly',+ tenantId: 'tenant-a',+ apiKey: 'tenant-key',+ baseURL: 'https://tenant.example.com/v1',+ models: { default: ['m1'] },+ };+ const TENANT_YAML: Yaml = {+ endpoints: { custom: [tenantOnly] },+ modelSpecs: { list: [spec('s', 'TenantOnly')] },+ };++ const azure: Probe = ({ endpoints }) => {+ const served = endpoints?.azureOpenAI;+ return {+ azureAssistants: endpoints?.azureAssistants != null,+ azure: served && {+ groups:+ served.groupMap &&+ Object.fromEntries(+ Object.entries(served.groupMap).map(([name, group]) => [+ name,+ { instanceName: group?.instanceName, keyed: group?.apiKey != null },+ ]),+ ),+ modelGroupMap: served.modelGroupMap,+ models: served.modelNames,+ assistantModels: served.assistantModels,+ assistantGroups: served.assistantGroups,+ assistants: Boolean(served.assistants),+ },+ };+ };+ const NO_GROUP = {+ azureAssistants: false,+ azure: {+ groups: {},+ modelGroupMap: {},+ models: [],+ assistantModels: [],+ assistantGroups: [],+ assistants: false,+ },+ };+ const anthropic: Probe = ({ endpoints }) => {+ const served = endpoints?.anthropic;+ const vertexConfig = served?.vertexConfig;+ return {+ models: served?.models,+ vertex: vertexConfig && {+ modelNames: vertexConfig.modelNames,+ projectId: vertexConfig.projectId,+ region: vertexConfig.region,+ },+ };+ };+ const customParams: Probe = ({ endpoints }) =>+ Object.fromEntries(+ (endpoints?.custom ?? []).map((entry) => [entry.name, entry.customParams ?? null]),+ );+ const agents: Probe = ({ endpoints }) =>+ endpoints?.agents && { capabilities: endpoints.agents.capabilities };+ const specsServed: Probe = (config) => ({+ list: config.modelSpecs?.list?.map(({ name, preset }) => [name, preset?.endpoint]),+ addedEndpoints: config.modelSpecs?.addedEndpoints,+ controls: specControls(config),+ });+ const SPECS = 'modelSpecs';+ const OPENAI = 'endpoints.openAI';+ /** Specs on the custom endpoint and on each built-in endpoint a layer may tombstone. */+ const SPEC_YAML = at(at(YAML, OPENAI, { titleModel: 'gpt-4o-mini' }), SPECS, {+ list: [+ spec('g', 'Gateway'),+ spec('o', 'openAI'),+ spec('az', 'azureOpenAI'),+ spec('an', 'anthropic'),+ ],+ addedEndpoints: ['Gateway', 'openAI'],+ });+ /**+ * Startup keeps an `addedEndpoints` name whose endpoint is gone; a custom endpoint the layers+ * remove also leaves it (`keyedTombstones`), and the other names stay.+ */+ const withoutGateway = (yaml: Yaml): Yaml => at(yaml, `${SPECS}.addedEndpoints`, ['openAI']);+ /** Specs only on the custom endpoint, so removing it leaves none. */+ const GATEWAY_SPECS = at(YAML, SPECS, { list: [spec('g', 'Gateway')] });+ const onSpecs = (cell: Cell): Cell => ({ yaml: SPEC_YAML, ...cell });+ /**+ * A built-in endpoint's specs stay when a layer tombstones its settings, as startup keeps+ * them for a librechat.yaml without them: the endpoint is still offered.+ */+ const builtInSpecCells = (+ [+ [OPENAI, write(`${OPENAI}.titleModel`, 'gpt-4o'), { titleModel: 'gpt-4o' }],+ [AZURE, write(GROUPS, [west]), { groups: [west] }],+ [ANTHROPIC, write(`${ANTHROPIC}.titleModel`, 'claude-x'), { titleModel: 'claude-x' }],+ ] as const+ ).flatMap(([path, recreate, recreated]): Cell[] =>+ [+ { change: `tombstone of ${path}`, layers: [role({}, [path])], as: at(SPEC_YAML, path) },+ {+ change: `Base's tombstone of ${path}, unset by the profile above`,+ layers: [base({}, [path]), role()],+ as: at(SPEC_YAML, path),+ },+ {+ change: `${path} recreated by a profile after Base tombstones it`,+ layers: [base({}, [path]), role(recreate)],+ as: at(SPEC_YAML, path, recreated),+ },+ ].map(onSpecs),+ );++ const matrix: Array<[string, Probe, Cell[]]> = [+ [+ 'Azure groups and assistants (the groupMap, model lists and the Azure Assistants endpoint)',+ azure,+ [+ {+ change: 'set by Base',+ layers: [base(write(GROUPS, [west]))],+ as: at(YAML, GROUPS, [east, west]),+ },+ {+ change: 'set by a profile over Base, merged by group',+ layers: [+ base(write(GROUPS, [west])),+ role(write(GROUPS, [{ group: 'west', models: { 'gpt-5-mini': true } }])),+ ],+ as: at(YAML, GROUPS, [+ east,+ { ...west, models: { 'gpt-5': true, 'gpt-5-mini': true } },+ ]),+ },+ {+ change: 'set by Base, unset by the profile above',+ layers: [base(write(GROUPS, [west])), role()],+ as: at(YAML, GROUPS, [east, west]),+ },+ { change: 'tombstone of the path', layers: [role({}, [GROUPS])], expected: NO_GROUP },+ {+ change: "a profile's tombstone of the path over Base's groups",+ layers: [base(write(GROUPS, [west])), role({}, [GROUPS])],+ expected: NO_GROUP,+ },+ {+ change: 'tombstone of the endpoint',+ layers: [role({}, [AZURE])],+ as: at(YAML, AZURE),+ },+ {+ change: 'tombstone of endpoints',+ layers: [role({}, ['endpoints'])],+ as: at(YAML, 'endpoints'),+ },+ {+ change: 'recreated by a profile after Base tombstones the endpoint',+ layers: [base({}, [AZURE]), role(write(`${AZURE}.titleModel`, 'gpt-4o'))],+ expected: NO_GROUP,+ },+ {+ change: 'recreated by a profile after Base tombstones endpoints',+ layers: [base({}, ['endpoints']), role(write(`${AZURE}.titleModel`, 'gpt-4o'))],+ expected: NO_GROUP,+ },+ {+ change: 'recreated by the layer that tombstones the endpoint',+ layers: [role(write(`${AZURE}.titleModel`, 'gpt-4o'), [AZURE])],+ expected: NO_GROUP,+ },+ {+ change: "recreated over a lower profile's groups by a higher profile's tombstone",+ layers: [+ role(write(GROUPS, [west])),+ above(write(`${AZURE}.titleModel`, 'x'), [AZURE]),+ ],+ expected: NO_GROUP,+ },+ {+ change: 'recreated with assistants on after a tombstone of the endpoint',+ layers: [base({}, [AZURE]), role(write(ASSISTANTS, true))],+ expected: NO_GROUP,+ },+ {+ change: 'recreated with groups after a tombstone of the endpoint',+ layers: [base({}, [AZURE]), role(write(GROUPS, [west]))],+ as: at(YAML, AZURE, { groups: [west] }),+ },+ {+ change: 'recreated with groups after a tombstone of endpoints',+ layers: [base({}, ['endpoints']), role(write(GROUPS, [west]))],+ as: at(at(YAML, 'endpoints'), AZURE, { groups: [west] }),+ },+ {+ change: 'groups Base tombstones, set again by a profile',+ layers: [base({}, [GROUPS]), role(write(GROUPS, [west]))],+ as: at(YAML, AZURE, { groups: [west] }),+ },+ {+ change: 'assistants turned off',+ layers: [role(write(ASSISTANTS, false))],+ as: at(YAML, ASSISTANTS, false),+ },+ {+ change: 'assistants tombstoned',+ layers: [role({}, [ASSISTANTS])],+ as: at(YAML, ASSISTANTS),+ },+ {+ change: 'assistants Base turns off, tombstoned by a profile',+ layers: [base(write(ASSISTANTS, false)), role({}, [ASSISTANTS])],+ as: at(YAML, ASSISTANTS),+ },+ {+ change: 'assistants Base tombstones, turned on by a profile',+ layers: [base({}, [ASSISTANTS]), role(write(ASSISTANTS, true))],+ as: YAML,+ },+ {+ change: 'switch off: a profile sets groups (inert)',+ layers: [role(write(GROUPS, [west]))],+ rederiveEndpoints: false,+ as: YAML,+ },+ {+ change: 'switch off: tombstone of the path (inert)',+ layers: [role({}, [GROUPS])],+ rederiveEndpoints: false,+ as: YAML,+ },+ {+ change: 'switch off: tombstone of the endpoint (Azure Assistants not derived)',+ layers: [role({}, [AZURE])],+ rederiveEndpoints: false,+ expected: { azure: undefined, azureAssistants: true },+ },+ {+ change: 'switch off: recreated by a profile after Base tombstones the endpoint',+ layers: [base({}, [AZURE]), role(write(`${AZURE}.titleModel`, 'gpt-4o'))],+ rederiveEndpoints: false,+ expected: { ...NO_GROUP, azureAssistants: true },+ },+ ],+ ],+ [+ 'Vertex AI and the Anthropic models (vertexConfig, endpoints.anthropic.models)',+ anthropic,+ [+ {+ change: 'set by a profile',+ layers: [role(write(`${VERTEX}.models`, ['claude-opus-4-6']))],+ as: at(YAML, `${VERTEX}.models`, ['claude-opus-4-6']),+ },+ {+ change: 'set by Base, unset by the profile above',+ layers: [base(write(`${VERTEX}.models`, ['claude-opus-4-6'])), role()],+ as: at(YAML, `${VERTEX}.models`, ['claude-opus-4-6']),+ },+ {+ change: 'turned off',+ layers: [role(write(`${VERTEX}.enabled`, false))],+ as: at(YAML, `${VERTEX}.enabled`, false),+ },+ {+ change: 'turned off by Base, tombstoned by a profile',+ layers: [base(write(`${VERTEX}.enabled`, false)), role({}, [`${VERTEX}.enabled`])],+ as: YAML,+ },+ { change: 'tombstone of the path', layers: [role({}, [VERTEX])], as: at(YAML, VERTEX) },+ {+ change: 'tombstone of one of its settings',+ layers: [role({}, [`${VERTEX}.models`])],+ as: at(YAML, `${VERTEX}.models`),+ },+ {+ change: 'tombstone of a setting it does not load without (off)',+ yaml: at(YAML, VERTEX, { ...namedVertex, deploymentName: 'claude-deploy' }),+ layers: [role({}, [`${VERTEX}.deploymentName`])],+ expected: { models: ['claude-direct'], vertex: undefined },+ },+ {+ change: 'tombstone of the endpoint',+ layers: [role({}, [ANTHROPIC])],+ as: at(YAML, ANTHROPIC),+ },+ {+ change: 'tombstone of endpoints',+ layers: [role({}, ['endpoints'])],+ as: at(YAML, 'endpoints'),+ },+ {+ change: 'recreated without Vertex AI after Base tombstones the endpoint',+ layers: [base({}, [ANTHROPIC]), role(write(`${ANTHROPIC}.titleModel`, 'claude-x'))],+ as: at(YAML, ANTHROPIC, { titleModel: 'claude-x' }),+ },+ {+ change: 'recreated with Vertex AI after Base tombstones the endpoint',+ layers: [base({}, [ANTHROPIC]), role(write(VERTEX, profileVertex))],+ as: at(YAML, ANTHROPIC, { vertex: { ...profileVertex, region: 'us-east5' } }),+ },+ {+ change: 'recreated with Vertex AI after Base tombstones endpoints',+ layers: [base({}, ['endpoints']), role(write(VERTEX, profileVertex))],+ as: at(at(YAML, 'endpoints'), VERTEX, { ...profileVertex, region: 'us-east5' }),+ },+ {+ change: "models a profile sets, over Vertex AI's",+ layers: [role(write(MODELS, ['claude-x']))],+ expected: {+ models: ['claude-x'],+ vertex: { ...yamlVertex, modelNames: yamlVertex.models, models: undefined },+ },+ },+ {+ change: 'models Base sets, tombstoned by a profile',+ layers: [base(write(MODELS, ['claude-x'])), role({}, [MODELS])],+ as: YAML,+ },+ {+ change: 'models Base tombstones, set by a profile',+ layers: [base({}, [MODELS]), role(write(MODELS, ['claude-y']))],+ expected: {+ models: ['claude-y'],+ vertex: { ...yamlVertex, modelNames: yamlVertex.models, models: undefined },+ },+ },+ {+ change: 'models Base sets, then the endpoint tombstoned and Vertex AI recreated',+ layers: [+ base(write(MODELS, ['claude-x'])),+ role(write(VERTEX, profileVertex), [ANTHROPIC]),+ ],+ as: at(YAML, ANTHROPIC, { vertex: { ...profileVertex, region: 'us-east5' } }),+ },+ {+ change: 'models Base sets, then endpoints tombstoned',+ layers: [base(write(MODELS, ['claude-x'])), role({}, ['endpoints'])],+ as: at(YAML, 'endpoints'),+ },+ {+ change: 'models Base sets, then Vertex AI tombstoned',+ layers: [base(write(MODELS, ['claude-x'])), role({}, [VERTEX])],+ as: at(at(YAML, VERTEX), MODELS, ['claude-x']),+ },+ {+ change: 'switch off: a profile sets Vertex AI (inert)',+ layers: [role(write(`${VERTEX}.models`, ['claude-opus-4-6']))],+ rederiveEndpoints: false,+ as: YAML,+ },+ ],+ ],+ [+ 'custom endpoint parameters (each endpoint served with its customParams expanded)',+ customParams,+ [+ {+ change: 'set by a profile',+ layers: [+ role(+ write(CUSTOM, [+ { name: 'Gateway', customParams: { defaultParamsEndpoint: 'openAI' } },+ ]),+ ),+ ],+ as: at(YAML, CUSTOM, [openAIGateway]),+ },+ {+ change: 'set by Base, unset by the profile above',+ layers: [+ base(+ write(CUSTOM, [+ { name: 'Gateway', customParams: { defaultParamsEndpoint: 'openAI' } },+ ]),+ ),+ role(),+ ],+ as: at(YAML, CUSTOM, [openAIGateway]),+ },+ {+ change: 'an endpoint only a profile defines',+ layers: [role(write(CUSTOM, [router]))],+ as: at(YAML, CUSTOM, [gateway, router]),+ },+ { change: 'tombstone of the list', layers: [role({}, [CUSTOM])], as: at(YAML, CUSTOM) },+ {+ change: 'tombstone of endpoints',+ layers: [role({}, ['endpoints'])],+ as: at(YAML, 'endpoints'),+ },+ {+ change: 'recreated by a profile after Base tombstones the list',+ layers: [base({}, [CUSTOM]), role(write(CUSTOM, [router]))],+ as: at(YAML, CUSTOM, [router]),+ },+ {+ change: 'recreated by a profile after Base tombstones endpoints',+ layers: [base({}, ['endpoints']), role(write(CUSTOM, [openAIGateway]))],+ as: at(at(YAML, 'endpoints'), CUSTOM, [openAIGateway]),+ },+ {+ change: "a lower profile's parameters under a higher profile's tombstone of the list",+ layers: [role(write(CUSTOM, [openAIGateway])), above({}, [CUSTOM])],+ as: at(YAML, CUSTOM),+ },+ {+ change: "tenant scoping: the tenant's own endpoint",+ yaml: at(TENANT_YAML, 'modelSpecs'),+ layers: [+ role(+ write(CUSTOM, [+ { name: 'TenantOnly', customParams: { defaultParamsEndpoint: 'anthropic' } },+ ]),+ ),+ ],+ tenantId: 'tenant-a',+ as: at(at(TENANT_YAML, 'modelSpecs'), CUSTOM, [+ { ...tenantOnly, customParams: { defaultParamsEndpoint: 'anthropic' } },+ ]),+ },+ {+ change: "tenant scoping: another tenant's endpoint stays hidden",+ yaml: at(TENANT_YAML, 'modelSpecs'),+ layers: [+ role(+ write(CUSTOM, [+ { name: 'TenantOnly', customParams: { defaultParamsEndpoint: 'anthropic' } },+ ]),+ ),+ ],+ tenantId: 'tenant-b',+ as: at(TENANT_YAML, 'modelSpecs'),+ },+ ],+ ],+ [+ 'the agents endpoint and its memory capability',+ agents,+ [+ {+ change: 'memory turned on',+ layers: [role(write('memory.disabled', false))],+ as: at(YAML, 'memory', { disabled: false }),+ },+ {+ change: 'memory Base turns on, unset by the profile above',+ layers: [base(write('memory.disabled', false)), role()],+ as: at(YAML, 'memory', { disabled: false }),+ },+ {+ change: 'memory Base turns on, memory.disabled tombstoned by a profile',+ layers: [base(write('memory.disabled', false)), role({}, ['memory.disabled'])],+ as: at(YAML, 'memory', {}),+ },+ {+ change: 'memory tombstoned',+ layers: [role({}, ['memory'])],+ as: at(YAML, 'memory'),+ },+ {+ change: 'memory Base turns on, tombstoned by a profile',+ layers: [base(write('memory.disabled', false)), role({}, ['memory'])],+ as: at(YAML, 'memory'),+ },+ {+ change: 'memory Base tombstones, turned on by a profile',+ layers: [base({}, ['memory']), role(write('memory.disabled', false))],+ as: at(YAML, 'memory', { disabled: false }),+ },+ {+ change: 'capabilities set',+ layers: [role(write(`${AGENTS}.capabilities`, ['memory', 'tools']))],+ as: at(YAML, `${AGENTS}.capabilities`, ['memory', 'tools']),+ },+ {+ change: 'capabilities Base sets, tombstoned by a profile',+ layers: [+ base(write(`${AGENTS}.capabilities`, ['tools'])),+ role({}, [`${AGENTS}.capabilities`]),+ ],+ as: YAML,+ },+ {+ change: 'tombstone of the agents endpoint',+ layers: [role({}, [AGENTS])],+ as: YAML,+ },+ {+ change: 'tombstone of endpoints',+ layers: [role({}, ['endpoints'])],+ as: at(YAML, 'endpoints'),+ },+ {+ change: 'recreated by a profile after Base tombstones the agents endpoint',+ layers: [base({}, [AGENTS]), role(write(`${AGENTS}.disableBuilder`, true))],+ as: at(YAML, AGENTS, { disableBuilder: true }),+ },+ {+ change: 'memory turned on by a profile after Base tombstones endpoints',+ layers: [base({}, ['endpoints']), role(write('memory.disabled', false))],+ as: at(at(YAML, 'endpoints'), 'memory', { disabled: false }),+ },+ ],+ ],+ [+ 'the interface controls model specs decide (modelSelect, parameters, presets)',+ specControls,+ [+ {+ change: 'set by a profile',+ layers: [role(write('interface.parameters', true))],+ as: at(YAML, 'interface', { parameters: true }),+ },+ {+ change: 'set by Base, unset by the profile above',+ layers: [base(write('interface.parameters', true)), role()],+ as: at(YAML, 'interface', { parameters: true }),+ },+ {+ change: 'set by Base, tombstoned by a profile',+ layers: [base(write('interface.parameters', true)), role({}, ['interface.parameters'])],+ as: YAML,+ },+ {+ change: 'tombstone of the interface',+ layers: [role({}, ['interface'])],+ as: YAML,+ },+ {+ change: 'tombstone of the interface without specs',+ layers: [role({}, ['interface', 'modelSpecs'])],+ as: at(YAML, 'modelSpecs'),+ },+ {+ change: 'set by Base, the interface tombstoned by a profile',+ layers: [base(write('interface.parameters', true)), role({}, ['interface'])],+ as: YAML,+ },+ {+ change: 'recreated by a profile after Base tombstones the interface',+ layers: [base({}, ['interface']), role(write('interface.customWelcome', 'hi'))],+ as: YAML,+ },+ {+ change: 'set by a profile after Base tombstones the interface',+ layers: [base({}, ['interface']), role(write('interface.parameters', true))],+ as: at(YAML, 'interface', { parameters: true }),+ },+ {+ change: 'specs tombstoned',+ layers: [role({}, ['modelSpecs'])],+ as: at(YAML, 'modelSpecs'),+ },+ {+ change: 'the spec list tombstoned',+ layers: [role({}, ['modelSpecs.list'])],+ as: at(YAML, 'modelSpecs'),+ },+ {+ change: 'specs Base tombstones, added again by a profile',+ layers: [+ base({}, ['modelSpecs']),+ role(write('modelSpecs.list', [spec('s2', 'openAI')])),+ ],+ as: YAML,+ },+ {+ change: "tenant scoping: the tenant's own specs",+ yaml: TENANT_YAML,+ layers: [role(write('interface.customWelcome', 'hi'))],+ tenantId: 'tenant-a',+ as: TENANT_YAML,+ },+ {+ change: "tenant scoping: specs of another tenant's endpoint",+ yaml: TENANT_YAML,+ layers: [role(write('interface.customWelcome', 'hi'))],+ tenantId: 'tenant-b',+ as: TENANT_YAML,+ },+ {+ change: "tenant scoping: specs of another tenant's endpoint, the interface tombstoned",+ yaml: TENANT_YAML,+ layers: [role({}, ['interface'])],+ tenantId: 'tenant-b',+ as: TENANT_YAML,+ },+ ],+ ],+ [+ 'model specs once the endpoints they name are removed (the specs served, addedEndpoints, the controls they decide)',+ specsServed,+ [+ ...[+ {+ change: 'tombstone of endpoints.custom',+ layers: [role({}, [CUSTOM])],+ as: withoutGateway(at(SPEC_YAML, CUSTOM)),+ },+ {+ change: "Base's tombstone of endpoints.custom, unset by the profile above",+ layers: [base({}, [CUSTOM]), role()],+ as: withoutGateway(at(SPEC_YAML, CUSTOM)),+ },+ {+ change: 'endpoints.custom Base adds to, tombstoned by a profile',+ layers: [base(write(CUSTOM, [router])), role({}, [CUSTOM])],+ as: withoutGateway(at(SPEC_YAML, CUSTOM)),+ },+ {+ change:+ "a profile's own endpoint and its spec under a higher profile's tombstone of endpoints.custom",+ layers: [+ role({+ ...write(CUSTOM, [router]),+ ...write(`${SPECS}.list`, [spec('r', 'Router'), spec('o', 'openAI')]),+ }),+ above({}, [CUSTOM]),+ ],+ as: at(withoutGateway(at(SPEC_YAML, CUSTOM)), `${SPECS}.list`, [+ spec('r', 'Router'),+ spec('o', 'openAI'),+ ]),+ },+ {+ change: 'endpoints.custom recreated by a profile after Base tombstones it',+ layers: [base({}, [CUSTOM]), role(write(CUSTOM, [gateway]))],+ as: SPEC_YAML,+ },+ {+ change: 'endpoints.custom recreated by the layer that tombstones it',+ layers: [role(write(CUSTOM, [gateway]), [CUSTOM])],+ as: SPEC_YAML,+ },+ {+ change: 'endpoints.custom a lower profile tombstones, recreated by a higher profile',+ layers: [role({}, [CUSTOM]), above(write(CUSTOM, [gateway]))],+ as: SPEC_YAML,+ },+ {+ change: 'tombstone of endpoints',+ layers: [role({}, ['endpoints'])],+ as: withoutGateway(at(SPEC_YAML, 'endpoints')),+ },+ {+ change: "Base's tombstone of endpoints, unset by the profile above",+ layers: [base({}, ['endpoints']), role()],+ as: withoutGateway(at(SPEC_YAML, 'endpoints')),+ },+ {+ change: 'endpoints.custom recreated by a profile after Base tombstones endpoints',+ layers: [base({}, ['endpoints']), role(write(CUSTOM, [gateway]))],+ as: at(at(SPEC_YAML, 'endpoints'), CUSTOM, [gateway]),+ },+ {+ change:+ 'endpoints.custom recreated by a higher profile after a lower one tombstones endpoints',+ layers: [role({}, ['endpoints']), above(write(CUSTOM, [gateway]))],+ as: at(at(SPEC_YAML, 'endpoints'), CUSTOM, [gateway]),+ },+ {+ change: 'switch off: tombstone of endpoints.custom',+ layers: [role({}, [CUSTOM])],+ rederiveEndpoints: false,+ as: withoutGateway(at(SPEC_YAML, CUSTOM)),+ },+ ...builtInSpecCells,+ ].map(onSpecs),+ /**+ * Where no spec is left, none is served and the controls follow, as for tenant+ * scoping: startup derives them from librechat.yaml's list before it skips specs, so+ * these compare with librechat.yaml left without the specs startup would skip.+ */+ {+ change: 'tombstone of endpoints.custom, leaving no spec',+ yaml: GATEWAY_SPECS,+ layers: [role({}, [CUSTOM])],+ as: at(at(GATEWAY_SPECS, CUSTOM), SPECS),+ },+ {+ change: "Base's tombstone of endpoints, leaving no spec",+ yaml: GATEWAY_SPECS,+ layers: [base({}, ['endpoints']), role()],+ as: at(at(GATEWAY_SPECS, 'endpoints'), SPECS),+ },+ {+ change:+ 'endpoints.custom Base tombstones, recreated by a profile: the spec served again',+ yaml: GATEWAY_SPECS,+ layers: [base({}, [CUSTOM]), role(write(CUSTOM, [gateway]))],+ as: GATEWAY_SPECS,+ },+ ],+ ],+ ];++ describe.each(matrix)('%s', (_output, probe, cells) => {+ it.each(cells.map((cell): [string, Cell] => [cell.change, cell]))(+ '%s',+ async (_change, cell) => {+ const read = async (yaml: Yaml, layers: Layer[]) =>+ probe(+ await serviceOver(yaml, layers, {+ rederiveEndpoints: cell.rederiveEndpoints ?? true,+ }).getAppConfig({ role: 'USER', tenantId: cell.tenantId }),+ );+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);+ const served = await read(cell.yaml ?? YAML, cell.layers);+ const expected = cell.as ? await read(cell.as, []) : cell.expected;+ warn.mockRestore();++ expect(served).toEqual(expected);+ },+ );+ });+ });+});diff --git a/packages/api/src/app/service.ts b/packages/api/src/app/service.tsindex 7483762f1f..db2cdcd4bb 100644--- a/packages/api/src/app/service.ts+++ b/packages/api/src/app/service.ts@@ -1,21 +1,22 @@import { createHash } from 'node:crypto';+import {+ PrincipalType,+ materializeModelSpecEndpoints,+ normalizeEndpointName,+ setMaxSubagents,+} from 'librechat-data-provider';import {logger,getTenantId,- loadDefaultInterface,tenantStorage,+ deriveSpecInterface,+ SPEC_INTERFACE_FIELDS,BASE_CONFIG_PRINCIPAL_ID,SYSTEM_TENANT_ID,} from '@librechat/data-schemas';-import {- PrincipalType,- materializeModelSpecEndpoints,- getConfigDefaults,- normalizeEndpointName,- setMaxSubagents,-} from 'librechat-data-provider';import type {AppConfig,+ SpecInterfaceField,ConfigOverrideLayer,ConfigLayerResolution,AdminConfigLayerIgnored,@@ -25,8 +26,8 @@ import type { Types } from 'mongoose';import type { CustomConfigLoadMode, ConfigLoadFailure, ConfigLoadResult } from './loader';import type { EnvReferencePolicy } from './allowlist';import type { SecretRebinding } from './rebinding';+import { resolveOverrideLayers, mergeOverrideLayersWithSource } from './overrides';import { createEnvReferencePolicy, parseEnvAllowlist } from './allowlist';-import { mergeOverrideLayers, resolveOverrideLayers } from './overrides';import { resolveRuntimeConfigSecrets } from '~/admin/secrets';import { normalizeEndpointReferences } from './references';import { getConfigLoadFailure } from './loader';@@ -262,25 +263,61 @@ function scopeCustomEndpoints(};}+/** What decides the spec-dependent interface controls: whether specs are served, and added endpoints. */+function getSpecState(modelSpecs: AppConfig['modelSpecs']): string {+ const hasSpecs = (modelSpecs?.list?.length ?? 0) > 0;+ return `${hasSpecs}:${(modelSpecs?.addedEndpoints?.length ?? 0) > 0}`;+}++/**+ * The spec-dependent interface controls a merge may have changed against `base`, whose own are+ * already derived for the specs it serves: all of them when the specs served change, else those+ * whose final librechat.yaml-shaped value (`explicit`) or served value differs from `base`'s. A+ * control a layer sets and a higher layer tombstones is back to librechat.yaml's value in+ * `explicit`, but the tombstone removed its served value, so it is derived again too.+ */+function getChangedSpecFields(+ base: AppConfig,+ merged: AppConfig,+ explicit: TCustomConfig['interface'] | undefined,+): SpecInterfaceField[] {+ if (getSpecState(base.modelSpecs) !== getSpecState(merged.modelSpecs)) {+ return [...SPEC_INTERFACE_FIELDS];+ }+ const written = base.config?.interface;+ return SPEC_INTERFACE_FIELDS.filter(+ (field) =>+ explicit?.[field] !== written?.[field] ||+ merged.interfaceConfig?.[field] !== base.interfaceConfig?.[field],+ );+}++/**+ * `config` with the interface controls model specs decide (`deriveSpecInterface`) derived for the+ * specs it serves, where `explicit` (the librechat.yaml-shaped interface) leaves them unset: the+ * `fields` given, all three by default.+ */+function withSpecInterface(+ config: AppConfig,+ explicit: TCustomConfig['interface'] | undefined,+ fields: readonly SpecInterfaceField[] = SPEC_INTERFACE_FIELDS,+): AppConfig {+ if (fields.length === 0) {+ return config;+ }+ const interfaceConfig = deriveSpecInterface(config.interfaceConfig, explicit, config.modelSpecs, {+ fields,+ });+ return interfaceConfig === config.interfaceConfig ? config : { ...config, interfaceConfig };+}+/** Re-derive only spec-dependent controls before principal overrides are applied. */-async function scopeBaseConfig(config: AppConfig, tenantId?: string): Promise<AppConfig> {+function scopeBaseConfig(config: AppConfig, tenantId?: string): AppConfig {const scoped = scopeCustomEndpoints(config, tenantId);- if (scoped.modelSpecs === config.modelSpecs || !config.interfaceConfig) {+ if (scoped.modelSpecs === config.modelSpecs) {return scoped;}- const defaults = await loadDefaultInterface({- config: { ...scoped.config, modelSpecs: scoped.modelSpecs },- configDefaults: getConfigDefaults(),- });- return {- ...scoped,- interfaceConfig: {- ...config.interfaceConfig,- modelSelect: defaults?.modelSelect,- parameters: defaults?.parameters,- presets: defaults?.presets,- },- };+ return withSpecInterface(scoped, scoped.config?.interface);}export type AppConfigPrincipal = {@@ -470,6 +507,12 @@ export interface AppConfigServiceDeps {* endpoint credentials.*/overrideEnvAllowlist?: string;+ /**+ * Whether config overrides of Azure `groups`, Vertex AI (`endpoints.anthropic.vertex`) and the+ * Azure Assistants switch derive the served endpoints again (`CONFIG_REDERIVE_ENDPOINTS=true`).+ * Off, those overrides stay inert, as before.+ */+ rederiveEndpoints?: boolean;}export interface GetAppConfigOptions {@@ -648,6 +691,8 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {reloadBaseConfig: () => Promise<ConfigLoadResult>;/** The TTL in ms this service caches per-principal merged configs for. */overrideCacheTtl: number;+ /** Whether this service derives Azure groups, Vertex AI and Azure Assistants again. */+ rederiveEndpoints: boolean;} {const {loadBaseConfig,@@ -659,6 +704,7 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {augmentConfig,overrideCacheTtl = DEFAULT_OVERRIDE_CACHE_TTL,overrideEnvAllowlist,+ rederiveEndpoints = false,} = deps;const cache = getCache(cacheKeys.APP_CONFIG);@@ -947,7 +993,7 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {const cacheTenantId = ambientTenantId ?? effectiveTenantId;const generation = getOverrideGeneration(cacheTenantId);const baseConfig = await ensureBaseConfig(refresh);- const scopedBaseConfig = await scopeBaseConfig(baseConfig, effectiveTenantId);+ const scopedBaseConfig = scopeBaseConfig(baseConfig, effectiveTenantId);const hiddenEndpoints = hiddenCustomEndpoints(baseConfig, effectiveTenantId);if (baseOnly) {return scopedBaseConfig;@@ -1027,11 +1073,16 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {try {const configs = await getApplicableConfigs(principals);if (configs.length > 0) {- const layered = mergeOverrideLayers(scopedBaseConfig, configs, {- envPolicy: getEnvPolicy(baseConfig, scopedBaseConfig, effectiveTenantId),- onRebinding: warnRebinding,- });- merged = scopeCustomEndpoints(+ const { appConfig: layered, raw } = mergeOverrideLayersWithSource(+ scopedBaseConfig,+ configs,+ {+ envPolicy: getEnvPolicy(baseConfig, scopedBaseConfig, effectiveTenantId),+ onRebinding: warnRebinding,+ rederiveEndpoints,+ },+ );+ const scopedMerge = scopeCustomEndpoints(checkOverrideTheme(scopedBaseConfig,scopeHiddenEndpointReferences(@@ -1043,6 +1094,12 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {effectiveTenantId,hiddenEndpoints,);+ /** Spec-dependent controls follow the specs served once tenant scoping has settled them. */+ merged = withSpecInterface(+ scopedMerge,+ raw.interface,+ getChangedSpecFields(scopedBaseConfig, scopedMerge, raw.interface),+ );}} catch (error) {if (failClosed) throw error;@@ -1093,6 +1150,7 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {const resolution = resolveOverrideLayers(scopedBaseConfig, configs, {envPolicy: getEnvPolicy(baseConfig, scopedBaseConfig, effectiveTenantId),onRebinding: warnRebinding,+ rederiveEndpoints,});const completed = completeEffectiveConfig(resolution.merged);const unserved = getUnservedEndpointNames(scopedBaseConfig, configs, completed);@@ -1114,9 +1172,15 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {effectiveTenantId,hiddenCustomEndpoints(checked, effectiveTenantId, hiddenEndpoints),);+ const scopedMerge = scopeCustomEndpoints(checked, effectiveTenantId, hiddenEndpoints);+ const explicit = resolution.raw.interface;return {yaml,- merged: scopeCustomEndpoints(checked, effectiveTenantId, hiddenEndpoints),+ merged: withSpecInterface(+ scopedMerge,+ explicit,+ getChangedSpecFields(scopedBaseConfig, scopedMerge, explicit),+ ),resolved,layers: resolution.layers,};@@ -1187,6 +1251,7 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {clearOverrideCache,reloadBaseConfig,overrideCacheTtl,+ rederiveEndpoints,};}diff --git a/packages/api/src/endpoints/anthropic/llm.spec.ts b/packages/api/src/endpoints/anthropic/llm.spec.tsindex e8dac7afb5..bce506a755 100644--- a/packages/api/src/endpoints/anthropic/llm.spec.ts+++ b/packages/api/src/endpoints/anthropic/llm.spec.ts@@ -859,6 +859,28 @@ describe('getLLMConfig', () => {// The specific behavior (thinking, topP/topK inclusion) depends on model pattern});});++ it('refuses a Vertex deployment name that would leave its request path segment', () => {+ const vertexCredentials = {+ [AuthKeys.GOOGLE_SERVICE_KEY]: {+ project_id: 'test-project',+ client_email: '[email protected]',+ private_key: 'test-private-key',+ },+ };+ const vertexConfig = {+ region: 'global',+ models: { 'team-model': { deploymentName: '../../endpoints/5678:rawPredict#' } },+ };+ const configFor = (model: string) => () =>+ getLLMConfig(vertexCredentials, { modelOptions: { model }, vertexConfig });++ expect(configFor('team-model')).toThrow('not a valid model ID');+ expect(configFor('../../endpoints/5678:rawPredict#')).toThrow('not a valid model ID');+ expect(configFor('claude-sonnet-4-6@20250929')().llmConfig.model).toBe(+ 'claude-sonnet-4-6@20250929',+ );+ });});});diff --git a/packages/api/src/endpoints/anthropic/llm.ts b/packages/api/src/endpoints/anthropic/llm.tsindex 8970b68e2c..e0bffe2cf7 100644--- a/packages/api/src/endpoints/anthropic/llm.ts+++ b/packages/api/src/endpoints/anthropic/llm.ts@@ -4,6 +4,7 @@ import { AnthropicClientOptions } from '@librechat/agents';import {THINKING_BINDING_BETA,THINKING_DISPLAY_UPDATES_BETA,+ VERTEX_PATH_SEGMENT_PATTERN,requestsThinkingDisplayUpdates,clampOutputConfigEffort,omitsSamplingParameters,@@ -224,6 +225,9 @@ function getLLMConfig(requestOptions.model ?? '',options.vertexConfig,);+ if (deploymentName !== '' && !VERTEX_PATH_SEGMENT_PATTERN.test(deploymentName)) {+ throw new Error('The Vertex AI deployment name for this model is not a valid model ID.');+ }requestOptions.model = deploymentName;requestOptions.createClient = () =>diff --git a/packages/api/src/endpoints/anthropic/vertex.ts b/packages/api/src/endpoints/anthropic/vertex.tsindex 2b080d0670..b4340e2b36 100644--- a/packages/api/src/endpoints/anthropic/vertex.ts+++ b/packages/api/src/endpoints/anthropic/vertex.ts@@ -125,44 +125,7 @@ function filterVertexHeaders(headers?: Record<string, string>): Record<string, sreturn Object.keys(filteredHeaders).length > 0 ? filteredHeaders : undefined;}-/**- * Gets the deployment name for a given model name from the Vertex AI configuration.- * Maps visible model names to actual deployment names (model IDs).- * @param modelName - The visible model name (e.g., "Claude Opus 4.5")- * @param vertexConfig - The Vertex AI configuration with model mappings- * @returns The deployment name to use with the API (e.g., "claude-opus-4-5@20251101")- */-export function getVertexDeploymentName(- modelName: string,- vertexConfig?: VertexAIConfigInput,-): string {- if (!vertexConfig?.models) {- // No models configuration, return model name as-is- return modelName;- }-- // If models is an array, check if modelName is in the array- if (Array.isArray(vertexConfig.models)) {- // Legacy format - no deployment mapping- return modelName;- }-- // If models is an object, look up the deployment name- const modelConfig = vertexConfig.models[modelName];-- if (!modelConfig) {- // Model not found in config, return as-is- return modelName;- }-- if (typeof modelConfig === 'boolean') {- // Model is true/false - use default deployment name or model name- return vertexConfig.deploymentName || modelName;- }-- // Model has its own deployment name- return modelConfig.deploymentName || vertexConfig.deploymentName || modelName;-}+export { getVertexDeploymentName } from 'librechat-data-provider';/*** Creates and configures a Vertex AI client for Anthropic.diff --git a/packages/api/src/endpoints/config/models.spec.ts b/packages/api/src/endpoints/config/models.spec.tsindex eea055ec9e..adc77893be 100644--- a/packages/api/src/endpoints/config/models.spec.ts+++ b/packages/api/src/endpoints/config/models.spec.ts@@ -1,4 +1,6 @@-import { AuthType, EModelEndpoint } from 'librechat-data-provider';+import { AppService } from '@librechat/data-schemas';+import { AuthType, PrincipalType, EModelEndpoint } from 'librechat-data-provider';+import type { AppConfig } from '@librechat/data-schemas';import type { ServerRequest } from '~/types';const mockValidateEndpointURL = jest.fn().mockResolvedValue(undefined);@@ -17,6 +19,8 @@ jest.mock('~/utils', () => {import { SCOPED_TOKEN_CONFIG_KEY_PREFIX } from '../keys';import { createLoadConfigModels, configuredModelList } from './models';+import { createEnvReferencePolicy } from '~/app/allowlist';+import { mergeOverrideLayers } from '~/app/overrides';describe('createLoadConfigModels – user-provided baseURL header guard', () => {const fetchModels = jest.fn().mockResolvedValue([]);@@ -353,3 +357,76 @@ describe('configuredModelList', () => {expect(configuredModelList(undefined, EModelEndpoint.anthropic)).toBeUndefined();});});++describe('createLoadConfigModels – Azure and Vertex models a profile merges', () => {+ const east = {+ group: 'east',+ apiKey: 'east-key',+ instanceName: 'east',+ version: '2024-10-21',+ deploymentName: 'gpt-4o',+ assistants: true,+ models: { 'gpt-4o': true },+ };+ const load = (config: AppConfig) =>+ createLoadConfigModels({+ getAppConfig: jest.fn(),+ getUserKeyValues: jest.fn(),+ fetchModels: jest.fn(),+ })({ user: { id: 'user-1' }, config } as unknown as ServerRequest);++ it("serves librechat.yaml's Azure models with those a profile's group adds, with re-derivation on", async () => {+ const yaml = { endpoints: { azureOpenAI: { assistants: true, groups: [east] } } };+ const base = await AppService({ config: structuredClone(yaml) });+ const merge = (rederiveEndpoints: boolean) =>+ mergeOverrideLayers(+ base,+ [+ {+ principalType: PrincipalType.ROLE,+ principalId: 'USER',+ priority: 10,+ overrides: {+ endpoints: {+ azureOpenAI: {+ groups: [+ { group: 'east', models: { 'gpt-4o-mini': { deploymentName: 'mini' } } },+ ],+ },+ },+ },+ },+ ],+ { envPolicy: createEnvReferencePolicy({ config: yaml }), rederiveEndpoints },+ );++ const models = await load(merge(true));+ const inert = await load(merge(false));+ expect(models[EModelEndpoint.azureOpenAI]).toEqual(['gpt-4o', 'gpt-4o-mini']);+ expect(models[EModelEndpoint.azureAssistants]).toEqual(['gpt-4o', 'gpt-4o-mini']);+ expect(inert[EModelEndpoint.azureOpenAI]).toEqual(['gpt-4o']);+ expect(inert[EModelEndpoint.azureAssistants]).toEqual(['gpt-4o']);+ });++ it('serves the Vertex AI models a profile writes, with re-derivation on', async () => {+ const yaml = {+ endpoints: { anthropic: { vertex: { region: 'global', models: ['claude-sonnet-4-6'] } } },+ };+ const base = await AppService({ config: structuredClone(yaml) });+ const merged = mergeOverrideLayers(+ base,+ [+ {+ principalType: PrincipalType.ROLE,+ principalId: 'USER',+ priority: 10,+ overrides: { endpoints: { anthropic: { vertex: { models: ['claude-opus-4-8'] } } } },+ },+ ],+ { envPolicy: createEnvReferencePolicy({ config: yaml }), rederiveEndpoints: true },+ );++ expect((await load(base))[EModelEndpoint.anthropic]).toEqual(['claude-sonnet-4-6']);+ expect((await load(merged))[EModelEndpoint.anthropic]).toEqual(['claude-opus-4-8']);+ });+});diff --git a/packages/api/src/index.spec.ts b/packages/api/src/index.spec.tsnew file mode 100644index 0000000000..3abe2cb770--- /dev/null+++ b/packages/api/src/index.spec.ts@@ -0,0 +1,13 @@+/**+ * Specs in the `api` workspace mock `@librechat/data-schemas` down to its logger and still load+ * this package, so loading it must not read any other data-schemas export.+ */+jest.mock('@librechat/data-schemas', () => ({+ logger: { error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn() },+}));++describe('@librechat/api entry', () => {+ it('loads where @librechat/data-schemas is mocked down to its logger', () => {+ expect(() => jest.requireActual('./index')).not.toThrow();+ });+});diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.tsindex ee83dc7ec7..6748eeea4f 100644--- a/packages/data-provider/src/config.ts+++ b/packages/data-provider/src/config.ts@@ -124,15 +124,25 @@ export const BASE_PRINCIPAL_CONFIG_SECTIONS = ['langfuse'] as const;* or tenant config document can neither change nor remove them. The pull request provider and* host decide where the deployment's token is sent, the OAuth app which credentials users grant* and which environment secret is sent with them, and the shared cache's slot count where every- * replica looks for a shared answer. The admin catalog's model-list lifetime is one value for the- * whole deployment, which `GET /api/admin/config/meta` reports. */+ * replica looks for a shared answer. Vertex AI always authenticates with the deployment's service+ * account: its key file (a path, inline JSON or a URL the server fetches) and its region, which+ * is part of the API host, stay librechat.yaml's. The admin catalog's model-list lifetime is one+ * value for the whole deployment, which `GET /api/admin/config/meta` reports. */export const BASE_ONLY_CONFIG_PATHS = ['endpoints.agents.pullRequests.provider','endpoints.agents.pullRequests.host','endpoints.agents.pullRequests.oauth','endpoints.agents.pullRequests.sharedCacheSlots',+ 'endpoints.anthropic.vertex.serviceKeyFile',+ 'endpoints.anthropic.vertex.region','endpoints.catalogModelsTtlMs',] as const;+/** Fields the server derives from another librechat.yaml field, which no config document writes:+ * the merge leaves a document's value or tombstone there out and derives them itself, and writes+ * skip them (`derived_path`). `vertexConfig` is what `endpoints.anthropic.vertex` resolves to,+ * its service key file included, which the Anthropic client loads (a path, inline JSON or a URL+ * it fetches). Each is both an override path and an AppConfig path: its section keeps its name. */+export const DERIVED_CONFIG_PATHS = ['endpoints.anthropic.vertexConfig'] as const;/** How long the admin config catalog reuses a scope's model lists unless* `endpoints.catalogModelsTtlMs` sets it: the two minutes a provider's model list is cached for. */@@ -2394,6 +2404,35 @@ export const azureEndpointSchema = zexport type TAzureConfig = Omit<z.infer<typeof azureEndpointSchema>, 'groups'> &TAzureConfigValidationResult;+/**+ * A Vertex AI location as it appears in the API host (`<region>-aiplatform.googleapis.com`):+ * letters, digits and hyphens only, so no value can name another host.+ */+export const VERTEX_REGION_PATTERN = /^[A-Za-z0-9-]+$/;++/**+ * A Vertex AI project ID or deployment (model) name, each one segment of the request path:+ * letters, digits, `.`, `_`, `:` (domain-scoped projects), `@` (model versions) and `-`, and not+ * only dots, so no value can leave its segment.+ */+export const VERTEX_PATH_SEGMENT_PATTERN = /^(?!\.+$)[A-Za-z0-9._:@-]+$/;++/**+ * A whole `${VAR}` reference to one environment variable: a name of letters, digits and+ * underscores, with nothing around it. Text that only starts with `${` and ends with `}`+ * (`${A}/x#${A}`) is not one.+ */+export const ENV_VAR_REFERENCE_PATTERN = /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/;++/** A Vertex AI setting: a value matching `pattern`, or a whole `${VAR}` reference resolved at load. */+function vertexSettingSchema(pattern: RegExp, label: string) {+ return z+ .string()+ .refine((value) => ENV_VAR_REFERENCE_PATTERN.test(value) || pattern.test(value), {+ message: `Must be a valid Vertex AI ${label} or a \${ENV_VAR} reference`,+ });+}+/*** Vertex AI model configuration - similar to Azure model config* Allows specifying deployment name for each model@@ -2401,7 +2440,7 @@ export type TAzureConfig = Omit<z.infer<typeof azureEndpointSchema>, 'groups'> &export const vertexModelConfigSchema = z.object({/** The actual model ID/deployment name used by Vertex AI API */- deploymentName: z.string().optional(),+ deploymentName: vertexSettingSchema(VERTEX_PATH_SEGMENT_PATTERN, 'deployment name').optional(),}).or(z.boolean());@@ -2415,19 +2454,43 @@ export const vertexAISchema = z.object({/** Enable Vertex AI mode for Anthropic (defaults to true when vertex config is present) */enabled: z.boolean().optional(),/** Google Cloud Project ID (optional - auto-detected from service key file if not provided) */- projectId: z.string().optional(),+ projectId: vertexSettingSchema(VERTEX_PATH_SEGMENT_PATTERN, 'project ID').optional(),/** Vertex AI region (e.g., 'us-east5', 'europe-west1') */- region: z.string().default('us-east5'),+ region: vertexSettingSchema(VERTEX_REGION_PATTERN, 'region').default('us-east5'),/** Optional: Path to service account key file */serviceKeyFile: z.string().optional(),/** Optional: Default deployment name for all models (can be overridden per model) */- deploymentName: z.string().optional(),+ deploymentName: vertexSettingSchema(VERTEX_PATH_SEGMENT_PATTERN, 'deployment name').optional(),/** Optional: Available models - can be string array or object with deploymentName mapping */models: z.union([z.array(z.string()), z.record(z.string(), vertexModelConfigSchema)]).optional(),});export type TVertexAISchema = z.infer<typeof vertexAISchema>;+/**+ * The deployment name a Vertex AI request for `modelName` sends, which the client puts in the+ * request path as written: a `models` record entry's own `deploymentName`, else the default+ * `deploymentName` for an entry that is `true` or has none, else (a `models` array, an entry set+ * to `false`, a model not listed) the model name itself.+ */+export function getVertexDeploymentName(+ modelName: string,+ vertexConfig?: Pick<TVertexAISchema, 'models' | 'deploymentName'>,+): string {+ const models = vertexConfig?.models;+ if (models == null || Array.isArray(models)) {+ return modelName;+ }+ const modelConfig = models[modelName];+ if (!modelConfig) {+ return modelName;+ }+ if (typeof modelConfig === 'boolean') {+ return vertexConfig?.deploymentName || modelName;+ }+ return modelConfig.deploymentName || vertexConfig?.deploymentName || modelName;+}+export type TVertexModelMap = Record<string, string>;/**diff --git a/packages/data-schemas/src/app/azure.ts b/packages/data-schemas/src/app/azure.tsindex 7dd2d15c5f..e711435aa9 100644--- a/packages/data-schemas/src/app/azure.ts+++ b/packages/data-schemas/src/app/azure.ts@@ -38,6 +38,41 @@ export const AZURE_RESOLVED_GROUP_FIELDS: readonly AzureResolvedGroupField[] = ['assistantGroups',];+/** The fields of a resolved Azure config its `groups` decide ({@link AZURE_RESOLVED_GROUP_FIELDS}). */+export type AzureGroupResolution = Pick<ResolvedAzureGroups, AzureResolvedGroupField>;++/** What Azure `groups` resolve to where none are left: no group, and no model or assistant. */+export function getEmptyAzureResolution(): AzureGroupResolution {+ return {+ groupMap: {},+ modelGroupMap: {},+ modelNames: [],+ assistantModels: [],+ assistantGroups: [],+ };+}++/**+ * An Azure config with each field its groups resolve to that it lacks resolved to none+ * ({@link getEmptyAzureResolution}), and the fields it lacked. An Azure endpoint is served without+ * them where a layer recreates it after a tombstone removed it with everything its groups resolved+ * to (a tombstone of the endpoint or of `endpoints`), or where only a layer defines it, without+ * groups that resolve: no groups are left for it. Their absence would read differently: the model+ * lists fall back to the environment's default Azure models, which the Azure client cannot map to+ * a group. `config` is returned itself when it lacks none.+ */+export function completeAzureResolution<T extends Partial<AzureGroupResolution>>(+ config: T,+): { config: T; completed: AzureResolvedGroupField[] } {+ const completed = AZURE_RESOLVED_GROUP_FIELDS.filter((field) => config[field] == null);+ if (completed.length === 0) {+ return { config, completed };+ }+ const empty = getEmptyAzureResolution();+ const filled = Object.fromEntries(completed.map((field) => [field, empty[field]]));+ return { config: { ...config, ...filled }, completed };+}+/*** Whether an Azure config turns `assistants` on without a model that supports them, which* `azureConfigSetup` refuses: the Azure Assistants client would have no model to default to.@@ -114,6 +149,56 @@ export function resolveAzureGroups(groups: unknown): ResolvedAzureGroups {return { ...validation, assistantModels, assistantGroups: Array.from(assistantGroups) };}+/**+ * {@link resolveAzureGroups}, also refusing groups a request could not be built from, as+ * `azureConfigSetup` refuses them in librechat.yaml at startup: a model whose group lacks the+ * instance, deployment name or version it needs, or a `${VAR}` reference no environment variable+ * answers. Only the models of `checked` groups are tried (every group's without it): groups+ * librechat.yaml alone defines passed at startup. The first such problem is added to `errors`,+ * with `isValid: false`.+ */+export function resolveServedAzureGroups(+ groups: unknown,+ checked?: ReadonlySet<string>,+): ResolvedAzureGroups {+ const resolved = resolveAzureGroups(groups);+ if (!resolved.isValid) {+ return resolved;+ }+ const { modelGroupMap, groupMap } = resolved;+ for (const modelName of resolved.modelNames) {+ const group = modelGroupMap[modelName]?.group;+ if (checked != null && (group == null || !checked.has(group))) {+ continue;+ }+ try {+ mapModelToAzureConfig({ modelName, modelGroupMap, groupMap });+ } catch (error) {+ const message = error instanceof Error ? error.message : String(error);+ return { ...resolved, isValid: false, errors: [...resolved.errors, message] };+ }+ }+ return resolved;+}++/**+ * A `groups` item as the Azure clients read it once resolved (a `groupMap` entry): its fields+ * with the defaults `validateAzureGroups` gives them, without its `group` name. Unknown fields+ * stay, so a key's companions (`apiKeyPreview`, `apiKeyBinding`) travel with it.+ */+export function toAzureGroupMapEntry(item: Record<string, unknown>): Record<string, unknown> {+ const {+ group: _group,+ instanceName = '',+ deploymentName = '',+ version = '',+ baseURL = '',+ serverless = false,+ ...rest+ } = item;+ return { ...rest, instanceName, deploymentName, version, baseURL, serverless };+}+/** The lists of a resolved Azure config that name models or groups its maps must serve. */type AzureServedList = Extract<AzureResolvedGroupField,diff --git a/packages/data-schemas/src/app/collections.ts b/packages/data-schemas/src/app/collections.tsindex 5d84eb713f..4465942c2c 100644--- a/packages/data-schemas/src/app/collections.ts+++ b/packages/data-schemas/src/app/collections.ts@@ -19,6 +19,7 @@ import { parseFieldPath, isSegmentPrefix, parseConfigPath } from './paths';*/export const ARRAY_MERGE_KEYS: Readonly<Record<string, string>> = {'endpoints.custom': 'name',+ 'endpoints.azureOpenAI.groups': 'group',};/**diff --git a/packages/data-schemas/src/app/derive.spec.ts b/packages/data-schemas/src/app/derive.spec.tsnew file mode 100644index 0000000000..79b5be20e7--- /dev/null+++ b/packages/data-schemas/src/app/derive.spec.ts@@ -0,0 +1,343 @@+import type { TEndpoint } from 'librechat-data-provider';+import {+ touchesConfig,+ withBaseOnlyValues,+ createConfigTouches,+ recordConfigTouches,+ isVertexConfigured,+ deriveVertexEndpoint,+ getDerivedConfigIssues,+} from './derive';+import logger from '~/config/winston';++const ENDPOINTS = new Set(['endpoints', 'modelSpecs']);++/** Stands in for the expander packages/api injects: refuses a definition keyed `invalid`. */+function expandCustomEndpoint(endpoint: TEndpoint): TEndpoint {+ const params = endpoint.customParams;+ if (params == null) {+ return { ...endpoint };+ }+ if (params.paramDefinitions?.some((definition) => definition.key === 'invalid')) {+ throw new Error('invalid key');+ }+ return { ...endpoint, customParams: { ...params, defaultParamsEndpoint: 'custom' } };+}++const group = (overrides: Record<string, unknown> = {}) => ({+ group: 'east',+ apiKey: 'east-key',+ instanceName: 'east',+ version: '2024-10-21',+ deploymentName: 'gpt-4o',+ models: { 'gpt-4o': true },+ ...overrides,+});++describe('getDerivedConfigIssues', () => {+ it('reports Azure groups that do not resolve, or name an unset variable, once written', () => {+ const merged = (groups: unknown[]) => ({ endpoints: { azureOpenAI: { groups } } });+ const write = (groups: unknown[]) =>+ getDerivedConfigIssues(merged(groups), merged(groups), ENDPOINTS);++ expect(write([group()])).toEqual([]);+ expect(write([group({ deploymentName: '' })])).toEqual([+ { code: 'invalid_azure_groups', path: ['endpoints', 'azureOpenAI', 'groups'] },+ ]);+ expect(write([group(), group({ group: 'west' })])).toHaveLength(1);+ expect(write([group({ apiKey: '${AZURE_UNSET_GROUP_KEY}' })])).toHaveLength(1);+ expect(getDerivedConfigIssues({}, merged([group({ deploymentName: '' })]), ENDPOINTS)).toEqual(+ [],+ );+ });++ it('checks only the written groups for unset variables', () => {+ const yaml = group({ apiKey: '${AZURE_UNSET_YAML_KEY}' });+ const written = group({ group: 'west', models: { 'gpt-5': true } });++ expect(+ getDerivedConfigIssues(+ { endpoints: { azureOpenAI: { groups: [written] } } },+ { endpoints: { azureOpenAI: { groups: [yaml, written] } } },+ ENDPOINTS,+ ),+ ).toEqual([]);+ });++ it('reports a Vertex AI setup that does not load, unless it is off', () => {+ const vertex = (settings: Record<string, unknown>) => ({+ endpoints: { anthropic: { vertex: settings } },+ });+ const check = (settings: Record<string, unknown>) =>+ getDerivedConfigIssues(vertex(settings), vertex(settings), ENDPOINTS);++ expect(check({ projectId: 'project-1', region: 'global' })).toEqual([]);+ expect(check({ projectId: '${VERTEX_UNSET_PROJECT}' })).toEqual([+ { code: 'invalid_vertex_config', path: ['endpoints', 'anthropic', 'vertex'] },+ ]);+ expect(check({ projectId: '${VERTEX_UNSET_PROJECT}', enabled: false })).toEqual([]);+ });++ it('reports a deployment or model name that only wraps ${VAR} references', () => {+ process.env.VERTEX_DERIVE_PROJECT = 'project-1';+ const wrapped =+ '${VERTEX_DERIVE_PROJECT}/../../endpoints/5678:rawPredict#${VERTEX_DERIVE_PROJECT}';+ const vertex = (settings: Record<string, unknown>) => ({+ endpoints: { anthropic: { vertex: { projectId: '${VERTEX_DERIVE_PROJECT}', ...settings } } },+ });+ const check = (settings: Record<string, unknown>) =>+ getDerivedConfigIssues(vertex(settings), vertex(settings), ENDPOINTS);+ const invalid = [{ code: 'invalid_vertex_config', path: ['endpoints', 'anthropic', 'vertex'] }];++ try {+ expect(check({ models: { 'claude-sonnet-4-6': true } })).toEqual([]);+ expect(check({ models: { 'claude-sonnet-4-6': { deploymentName: wrapped } } })).toEqual(+ invalid,+ );+ expect(check({ models: [wrapped] })).toEqual(invalid);+ } finally {+ delete process.env.VERTEX_DERIVE_PROJECT;+ }+ });++ it('reports Vertex AI turned on where librechat.yaml configures none, but not turned off', () => {+ const vertex = (settings: Record<string, unknown>) => ({+ endpoints: { anthropic: { vertex: settings } },+ });+ const check = (settings: Record<string, unknown>, vertexConfigured?: boolean) =>+ getDerivedConfigIssues(vertex(settings), vertex(settings), ENDPOINTS, { vertexConfigured });+ const usable = { projectId: 'project-1' };++ expect(check(usable, false)).toEqual([+ { code: 'invalid_vertex_config', path: ['endpoints', 'anthropic', 'vertex'] },+ ]);+ expect(check({ ...usable, enabled: false }, false)).toEqual([]);+ expect(check(usable, true)).toEqual([]);+ expect(check(usable)).toEqual([]);+ });++ it('tells whether a librechat.yaml-shaped config configures Vertex AI, on or off', () => {+ expect(isVertexConfigured({ endpoints: { anthropic: { vertex: { enabled: false } } } })).toBe(+ true,+ );+ expect(isVertexConfigured({ endpoints: { anthropic: { models: ['claude-x'] } } })).toBe(false);+ expect(isVertexConfigured(null)).toBe(false);+ });++ it('reports parameter definitions the expander refuses, for the endpoints written', () => {+ const gateway = (paramDefinitions: unknown[]) => ({+ name: 'Gateway',+ customParams: { paramDefinitions },+ });+ const merged = {+ endpoints: { custom: [gateway([{ key: 'invalid' }]), { ...gateway([]), name: 'Other' }] },+ };++ expect(+ getDerivedConfigIssues({ endpoints: { custom: [{ name: 'Gateway' }] } }, merged, ENDPOINTS, {+ expandCustomEndpoint,+ }),+ ).toEqual([+ { code: 'invalid_param_definitions', path: ['endpoints', 'custom', '0', 'customParams'] },+ ]);+ expect(+ getDerivedConfigIssues({ endpoints: { custom: [{ name: 'Other' }] } }, merged, ENDPOINTS, {+ expandCustomEndpoint,+ }),+ ).toEqual([]);+ expect(+ getDerivedConfigIssues({ endpoints: { custom: [{ name: 'Gateway' }] } }, merged, ENDPOINTS),+ ).toEqual([]);+ });++ it('reports model specs whose endpoint is neither built in nor configured', () => {+ const spec = (endpoint: string) => ({ name: endpoint, label: endpoint, preset: { endpoint } });+ const merged = {+ endpoints: { custom: [{ name: 'Ollama' }] },+ modelSpecs: {+ list: [+ spec('openAI'),+ spec('ollama'),+ spec('Nowhere'),+ spec('custom'),+ { name: 'a', preset: { agent_id: 'agent_1' } },+ ],+ },+ };++ expect(getDerivedConfigIssues({ modelSpecs: { list: [] } }, merged, ENDPOINTS)).toEqual([+ { code: 'unknown_spec_endpoint', path: ['modelSpecs', 'list', '2', 'preset', 'endpoint'] },+ { code: 'unknown_spec_endpoint', path: ['modelSpecs', 'list', '3', 'preset', 'endpoint'] },+ ]);+ expect(getDerivedConfigIssues({ modelSpecs: { list: [] } }, merged, new Set())).toEqual([]);+ });+});++describe('config touches', () => {+ it('records written keys two levels down, tombstones and custom endpoints by identity', () => {+ const touches = createConfigTouches();+ recordConfigTouches(+ touches,+ { endpoints: { anthropic: { vertex: {} }, custom: [{ name: 'ollama' }] }, memory: {} },+ ['endpoints.azureAssistants'],+ );++ expect(touchesConfig(touches, ['endpoints', 'anthropic', 'vertex'])).toBe(true);+ expect(touchesConfig(touches, ['endpoints', 'anthropic'])).toBe(true);+ expect(touchesConfig(touches, ['endpoints', 'azureAssistants', 'version'])).toBe(true);+ expect(touchesConfig(touches, ['endpoints', 'azureOpenAI'])).toBe(false);+ expect(touchesConfig(touches, ['memory'])).toBe(true);+ expect([...touches.customEndpoints]).toEqual(['ollama']);+ });+});++describe('withBaseOnlyValues', () => {+ it("sets librechat.yaml's value at each base-only path, removing what it does not set", () => {+ const raw = {+ endpoints: {+ anthropic: { vertex: { region: 'elsewhere', serviceKeyFile: 'http://x', models: ['m'] } },+ },+ };+ const yaml = { endpoints: { anthropic: { vertex: { region: 'us-east5' } } } };++ expect(withBaseOnlyValues(raw, yaml)).toEqual({+ endpoints: { anthropic: { vertex: { region: 'us-east5', models: ['m'] } } },+ });+ expect(raw.endpoints.anthropic.vertex.region).toBe('elsewhere');+ expect(withBaseOnlyValues(yaml, yaml)).toBe(yaml);+ });+});++describe('deriveVertexEndpoint', () => {+ const yamlVertex = {+ projectId: 'yaml-project',+ region: 'us-east5',+ models: ['claude-sonnet-4-6'],+ };+ const merged = {+ endpoints: {+ anthropic: {+ titleModel: 'claude-haiku-4-5',+ vertex: yamlVertex,+ models: ['claude-sonnet-4-6'],+ vertexConfig: { enabled: true, region: 'us-east5', modelNames: ['claude-sonnet-4-6'] },+ },+ },+ };+ const derive = (raw: Record<string, unknown>, modelsOverridden = false) =>+ deriveVertexEndpoint({+ merged,+ raw,+ baseYaml: { endpoints: { anthropic: { vertex: yamlVertex } } },+ modelsOverridden,+ principal: 'role/r1',+ }).endpoints.anthropic as Record<string, unknown>;++ it('derives vertexConfig and the models it serves from the YAML-shaped config', () => {+ const anthropic = derive({+ endpoints: { anthropic: { vertex: { ...yamlVertex, models: ['claude-opus-4-6'] } } },+ });++ expect(anthropic.models).toEqual(['claude-opus-4-6']);+ expect(anthropic.vertexConfig).toMatchObject({+ projectId: 'yaml-project',+ region: 'us-east5',+ modelNames: ['claude-opus-4-6'],+ });+ expect(anthropic.titleModel).toBe('claude-haiku-4-5');+ });++ it('derives nothing where librechat.yaml configures no Vertex AI, so no layer turns it on', () => {+ const unconfigured = { endpoints: { anthropic: { titleModel: 'claude-haiku-4-5' } } };+ const result = deriveVertexEndpoint({+ merged: unconfigured,+ raw: { endpoints: { anthropic: { vertex: { projectId: 'p-1', models: ['claude-x'] } } } },+ baseYaml: {},+ modelsOverridden: false,+ principal: 'role/r1',+ });++ expect(result).toBe(unconfigured);+ });++ it('lets a layer turn on the Vertex AI librechat.yaml configures off, on its region', () => {+ const anthropic = deriveVertexEndpoint({+ merged: { endpoints: { anthropic: {} } },+ raw: { endpoints: { anthropic: { vertex: { ...yamlVertex, enabled: true } } } },+ baseYaml: { endpoints: { anthropic: { vertex: { ...yamlVertex, enabled: false } } } },+ modelsOverridden: false,+ principal: 'role/r1',+ }).endpoints.anthropic as Record<string, unknown>;++ expect(anthropic.vertexConfig).toMatchObject({ enabled: true, region: 'us-east5' });+ expect(anthropic.models).toEqual(['claude-sonnet-4-6']);+ });++ it("keeps librechat.yaml's region and key file over a layer's", () => {+ const anthropic = derive({+ endpoints: {+ anthropic: { vertex: { ...yamlVertex, region: 'evil', serviceKeyFile: 'http://x/key' } },+ },+ });++ expect(anthropic.vertexConfig).toMatchObject({ region: 'us-east5', serviceKeyFile: undefined });+ });++ it('turns Vertex AI off and serves the YAML-shaped models when it is disabled or removed', () => {+ const disabled = derive({+ endpoints: { anthropic: { vertex: { ...yamlVertex, enabled: false }, models: ['claude-3'] } },+ });+ const removed = derive({ endpoints: { anthropic: {} } });++ expect(disabled.vertexConfig).toBeUndefined();+ expect(disabled.models).toEqual(['claude-3']);+ expect(removed.vertexConfig).toBeUndefined();+ expect(removed).not.toHaveProperty('models');+ });++ it('keeps models a layer set over the ones Vertex AI serves', () => {+ const anthropic = derive(+ { endpoints: { anthropic: { vertex: { ...yamlVertex, models: ['claude-opus-4-6'] } } } },+ true,+ );++ expect(anthropic.models).toEqual(['claude-sonnet-4-6']);+ expect(anthropic.vertexConfig).toMatchObject({ modelNames: ['claude-opus-4-6'] });+ });++ describe('a setup that does not load (left only by a tombstone of one of its settings)', () => {+ /** Vertex AI off: no `vertexConfig`, the YAML-shaped models, the rest as merged. */+ const off = { titleModel: 'claude-haiku-4-5', vertex: yamlVertex, models: ['claude-direct'] };+ const deriveFrom = (vertex: Record<string, unknown>) =>+ deriveVertexEndpoint({+ merged,+ raw: { endpoints: { anthropic: { vertex, models: ['claude-direct'] } } },+ baseYaml: { endpoints: { anthropic: { vertex: yamlVertex } } },+ modelsOverridden: false,+ principal: 'role/r1',+ }).endpoints.anthropic;++ it('turns Vertex AI off, with a warning, rather than keep the vertexConfig derived below', () => {+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);++ expect(deriveFrom({ projectId: '${VERTEX_UNSET_PROJECT}' })).toEqual(off);+ expect(warn).toHaveBeenCalledWith(+ expect.stringContaining('Turning Vertex AI off for role/r1'),+ );+ warn.mockRestore();+ });++ it('turns it off where a model name would leave its path segment', () => {+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);++ expect(+ deriveFrom({+ ...yamlVertex,+ deploymentName: 'claude-sonnet-4-6',+ models: ['../../endpoints/5678:rawPredict#'],+ }),+ ).toEqual(off);+ warn.mockRestore();+ });+ });+});diff --git a/packages/data-schemas/src/app/derive.ts b/packages/data-schemas/src/app/derive.tsnew file mode 100644index 0000000000..d99bef5df3--- /dev/null+++ b/packages/data-schemas/src/app/derive.ts@@ -0,0 +1,593 @@+import {+ EModelEndpoint,+ AgentCapabilities,+ BASE_ONLY_CONFIG_PATHS,+ normalizeEndpointName,+ materializeModelSpecEndpoints,+} from 'librechat-data-provider';+import type {+ TEndpoint,+ TCustomConfig,+ TAgentsEndpoint,+ TVertexAISchema,+ TVertexAIConfig,+} from 'librechat-data-provider';+import type { AppConfig } from '~/types';+import { readConfigEntryTombstone, getConfigTombstoneSegments } from './collections';+import { azureAssistantsDefaults, assistantsConfigSetup } from './assistants';+import { getAtPath, isPlainRecord, isSegmentPrefix } from './paths';+import { resolveServedAzureGroups } from './azure';+import { validateVertexConfig } from './vertex';+import { agentsConfigSetup } from './agents';+import { isMemoryEnabled } from './memory';+import logger from '~/config/winston';++type JsonRecord = Record<string, unknown>;++/**+ * What AppService derives from parts of librechat.yaml at startup, which the merge derives again+ * for the parts config overrides change, and which writes are checked against.+ */+export interface ConfigDerivation {+ /**+ * Expands a custom endpoint's `customParams` as startup does (each parameter definition+ * completed from the defaults of `defaultParamsEndpoint`, OpenRouter's defaults added) and+ * returns the expanded copy; throws when the definitions are invalid. Without it, custom+ * endpoints are served as merged and their parameter definitions are not checked.+ */+ expandCustomEndpoint?: (endpoint: TEndpoint) => TEndpoint;+ /**+ * Whether the merge derives the Azure endpoint (the `groupMap`, model lists and assistant+ * models a layer's `groups` resolve to), Vertex AI (`endpoints.anthropic.vertexConfig` and the+ * models it serves) and the Azure Assistants endpoint again from what the layers write+ * (`CONFIG_REDERIVE_ENDPOINTS`). Without it, those overrides stay inert. Writes are checked+ * either way.+ */+ rederiveEndpoints?: boolean;+ /**+ * Whether librechat.yaml configures Vertex AI (`endpoints.anthropic.vertex`, on or off;+ * {@link isVertexConfigured}). An override may turn Vertex AI on only where it does: the setup+ * runs on librechat.yaml's key file and region, and without them on the deployment's default+ * Google credentials. `false` makes an override that turns it on an `invalid_vertex_config`;+ * unset, that is not checked. The merge sets it from librechat.yaml itself.+ */+ vertexConfigured?: boolean;+}++/** Why a write leaves a derived part of the config unable to load. */+export type DerivedConfigIssueCode =+ | 'invalid_azure_groups'+ | 'invalid_vertex_config'+ | 'invalid_param_definitions'+ | 'unknown_spec_endpoint';++/** A derived check that fails, at its place in the merged librechat.yaml-shaped config. */+export interface DerivedConfigIssue {+ code: DerivedConfigIssueCode;+ path: string[];+}++/**+ * Derived issues only writes report: the merge does not strip the value they sit on. A model spec+ * whose endpoint is unknown is refused on write; at merge only that spec is left out+ * ({@link deriveServedSpecs}), not the layer's whole list.+ */+export const WRITE_ONLY_DERIVED_ISSUES: ReadonlySet<string> = new Set(['unknown_spec_endpoint']);++const ENDPOINTS = 'endpoints';+const AZURE_GROUPS = [ENDPOINTS, EModelEndpoint.azureOpenAI, 'groups'];+const ANTHROPIC = [ENDPOINTS, EModelEndpoint.anthropic];+const VERTEX = [...ANTHROPIC, 'vertex'];+const CUSTOM_ENDPOINTS = [ENDPOINTS, EModelEndpoint.custom];+const SPEC_LIST = ['modelSpecs', 'list'];++function asRecord(value: unknown): JsonRecord | undefined {+ return isPlainRecord(value) ? value : undefined;+}++function getEndpointIdentity(name: unknown): string | undefined {+ return typeof name === 'string' && name !== '' ? normalizeEndpointName(name) : undefined;+}++/** The custom endpoint identities a list names (as the merge folds them, `ollama` is `Ollama`). */+function getEndpointIdentities(items: unknown): Set<string> {+ const identities = new Set<string>();+ for (const item of Array.isArray(items) ? items : []) {+ const identity = getEndpointIdentity(asRecord(item)?.name);+ if (identity != null) {+ identities.add(identity);+ }+ }+ return identities;+}++/** The `group` names an Azure `groups` list holds. */+export function getGroupNames(groups: unknown): Set<string> {+ const names = new Set<string>();+ for (const item of Array.isArray(groups) ? groups : []) {+ const name = asRecord(item)?.group;+ if (typeof name === 'string') {+ names.add(name);+ }+ }+ return names;+}++/** Whether an override sets the value at `segments`. */+function sets(overrides: JsonRecord, segments: readonly string[]): boolean {+ return getAtPath(overrides, segments) !== undefined;+}++/** Whether a librechat.yaml-shaped config configures Vertex AI, on or off. */+export function isVertexConfigured(yaml: unknown): boolean {+ return asRecord(getAtPath(yaml, VERTEX)) != null;+}++function isUsableVertex(vertex: unknown): boolean {+ try {+ return validateVertexConfig(vertex as TVertexAISchema)?.isValid === true;+ } catch {+ return false;+ }+}++/** Whether a model spec's endpoint is one the runtime serves (`processModelSpecs`'s rule). */+function isKnownSpecEndpoint(endpoint: string, customEndpoints: ReadonlySet<string>): boolean {+ if (endpoint === EModelEndpoint.custom) {+ return false;+ }+ return (+ Object.prototype.hasOwnProperty.call(EModelEndpoint, endpoint) ||+ customEndpoints.has(normalizeEndpointName(endpoint))+ );+}++/**+ * What a write breaks in the parts AppService derives from librechat.yaml, judged on `merged`+ * (the overrides over the config they land on): Azure `groups` that do not resolve once merged by+ * `group`, or whose written groups name an environment variable that is not set+ * (`invalid_azure_groups`); a Vertex AI setup that does not load, or that turns Vertex AI on+ * where librechat.yaml configures none (`vertexConfigured: false`; `invalid_vertex_config`);+ * custom endpoint parameter definitions startup would refuse (`invalid_param_definitions`, when+ * `expandCustomEndpoint` is given); and model specs naming an endpoint that is not configured+ * (`unknown_spec_endpoint`). Each family is checked only when the overrides write it. All but+ * Azure groups also need their section to pass its schema (`validSections`), so a schema issue is+ * not reported twice; groups are always checked, since groups a merge cannot resolve stay unread.+ * Issues come back in `merged`'s terms, for the caller to attribute.+ */+export function getDerivedConfigIssues(+ overrides: JsonRecord,+ merged: JsonRecord,+ validSections: ReadonlySet<string>,+ derivation: ConfigDerivation = {},+): DerivedConfigIssue[] {+ const issues: DerivedConfigIssue[] = [];+ const groups = getAtPath(overrides, AZURE_GROUPS);+ if (+ groups !== undefined &&+ !resolveServedAzureGroups(getAtPath(merged, AZURE_GROUPS), getGroupNames(groups)).isValid+ ) {+ issues.push({ code: 'invalid_azure_groups', path: AZURE_GROUPS });+ }+ if (validSections.has(ENDPOINTS)) {+ const vertex = asRecord(getAtPath(merged, VERTEX));+ if (+ sets(overrides, VERTEX) &&+ vertex != null &&+ vertex.enabled !== false &&+ (derivation.vertexConfigured === false || !isUsableVertex(vertex))+ ) {+ issues.push({ code: 'invalid_vertex_config', path: VERTEX });+ }+ issues.push(...getParamDefinitionIssues(overrides, merged, derivation));+ }+ if (validSections.has('modelSpecs') && Array.isArray(getAtPath(overrides, SPEC_LIST))) {+ issues.push(...getSpecEndpointIssues(merged));+ }+ return issues;+}++function getParamDefinitionIssues(+ overrides: JsonRecord,+ merged: JsonRecord,+ { expandCustomEndpoint }: ConfigDerivation,+): DerivedConfigIssue[] {+ const written = getEndpointIdentities(getAtPath(overrides, CUSTOM_ENDPOINTS));+ const entries = getAtPath(merged, CUSTOM_ENDPOINTS);+ if (expandCustomEndpoint == null || written.size === 0 || !Array.isArray(entries)) {+ return [];+ }+ return entries.flatMap((entry: unknown, index): DerivedConfigIssue[] => {+ const record = asRecord(entry);+ const identity = getEndpointIdentity(record?.name);+ if (record == null || identity == null || !written.has(identity)) {+ return [];+ }+ try {+ expandCustomEndpoint(record as TEndpoint);+ return [];+ } catch {+ return [+ {+ code: 'invalid_param_definitions',+ path: [...CUSTOM_ENDPOINTS, String(index), 'customParams'],+ },+ ];+ }+ });+}++function getSpecEndpointIssues(merged: JsonRecord): DerivedConfigIssue[] {+ const modelSpecs = materializeModelSpecEndpoints(+ asRecord(merged.modelSpecs) as TCustomConfig['modelSpecs'],+ );+ const customEndpoints = getEndpointIdentities(getAtPath(merged, CUSTOM_ENDPOINTS));+ return (modelSpecs?.list ?? []).flatMap((spec, index): DerivedConfigIssue[] => {+ const endpoint: unknown = asRecord(asRecord(spec)?.preset)?.endpoint;+ if (typeof endpoint !== 'string' || isKnownSpecEndpoint(endpoint, customEndpoints)) {+ return [];+ }+ return [+ { code: 'unknown_spec_endpoint', path: [...SPEC_LIST, String(index), 'preset', 'endpoint'] },+ ];+ });+}++/**+ * The paths layers wrote or removed, for the post-merge derivation: each written section's keys+ * one or two levels down (`endpoints.azureOpenAI`, `endpoints.anthropic.vertex`), each tombstone,+ * and the custom endpoints written, by identity.+ */+export interface ConfigTouches {+ paths: string[][];+ customEndpoints: Set<string>;+}++export function createConfigTouches(): ConfigTouches {+ return { paths: [], customEndpoints: new Set() };+}++/**+ * Records what one layer wrote (`applied`, librechat.yaml keys) and the tombstones it applied: a+ * keyed tombstone (`endpoints.custom["Name"]…`) by its array, with the custom endpoint it names.+ */+export function recordConfigTouches(+ touches: ConfigTouches,+ applied: JsonRecord,+ tombstones: readonly string[],+): void {+ for (const tombstone of tombstones) {+ touches.paths.push([...getConfigTombstoneSegments(tombstone)]);+ const entry = readConfigEntryTombstone(tombstone);+ if (entry != null && isSegmentPrefix(CUSTOM_ENDPOINTS, entry.segments)) {+ touches.customEndpoints.add(entry.identity);+ }+ }+ for (const [section, value] of Object.entries(applied)) {+ const fields = asRecord(value);+ if (fields == null || Object.keys(fields).length === 0) {+ touches.paths.push([section]);+ continue;+ }+ for (const [field, child] of Object.entries(fields)) {+ const children = asRecord(child);+ if (children == null || Object.keys(children).length === 0) {+ touches.paths.push([section, field]);+ continue;+ }+ for (const key of Object.keys(children)) {+ touches.paths.push([section, field, key]);+ }+ }+ }+ for (const identity of getEndpointIdentities(getAtPath(applied, CUSTOM_ENDPOINTS))) {+ touches.customEndpoints.add(identity);+ }+}++/** Whether any recorded path is `prefix`, lies below it or contains it. */+export function touchesConfig(touches: ConfigTouches, prefix: readonly string[]): boolean {+ return touches.paths.some(+ (path) => isSegmentPrefix(prefix, path) || isSegmentPrefix(path, prefix),+ );+}++/**+ * `raw` with librechat.yaml's value at every base-only path (`BASE_ONLY_CONFIG_PATHS`) whose+ * parent object `raw` holds.+ */+export function withBaseOnlyValues<T extends JsonRecord>(raw: T, baseYaml: JsonRecord): T {+ let result: JsonRecord = raw;+ for (const path of BASE_ONLY_CONFIG_PATHS) {+ const segments = path.split('.');+ const value = getAtPath(baseYaml, segments);+ if (getAtPath(result, segments) === value) {+ continue;+ }+ result = replaceAt(result, segments, value);+ }+ return result as T;+}++/**+ * Copies objects along `segments` and sets the last one (or removes it, for `undefined`). Only an+ * object that is there is changed: a missing parent (a section a layer removed) stays missing.+ */+function replaceAt(root: JsonRecord, segments: readonly string[], value: unknown): JsonRecord {+ const [segment, ...rest] = segments;+ const next: JsonRecord = { ...root };+ if (rest.length === 0) {+ if (value === undefined) {+ delete next[segment];+ } else {+ next[segment] = value;+ }+ return next;+ }+ const child = next[segment];+ if (!isPlainRecord(child)) {+ return root;+ }+ next[segment] = replaceAt(child, rest, value);+ return next;+}++/** `merged` with one endpoint of `endpoints` set (or removed, for `undefined`), copied on the way. */+function setEndpoint<T extends { endpoints?: unknown }>(+ merged: T,+ endpoint: string,+ value: unknown,+): T {+ const next: JsonRecord = { ...asRecord(merged.endpoints) };+ if (value === undefined) {+ delete next[endpoint];+ } else {+ next[endpoint] = value;+ }+ return { ...merged, endpoints: next };+}++/**+ * The Anthropic endpoint with Vertex AI derived again from `raw` (the librechat.yaml-shaped+ * config up to this layer), as `loadEndpoints` derives it at startup: `vertexConfig` from+ * `endpoints.anthropic.vertex`, with librechat.yaml's base-only values (key file, region), and+ * the models it serves. `enabled: false`, or no `vertex` left, removes `vertexConfig` and serves+ * the `endpoints.anthropic.models` the YAML-shaped config holds (none: the provider's defaults).+ * Models a layer set, where no later layer removed them (`modelsOverridden`), stay as merged.+ * Where librechat.yaml configures no Vertex AI ({@link isVertexConfigured}) nothing is derived,+ * so no layer turns it on with the deployment's default Google credentials. A setup that does not+ * load is off too, with a warning naming `principal`: a write that would leave it so is left out+ * of the merge before it lands (`stripInvalidOverrides`), so only a tombstone of one of its+ * settings does, and what the layers leave decides, never a `vertexConfig` derived below it.+ */+export function deriveVertexEndpoint<T extends JsonRecord>(params: {+ merged: T;+ raw: JsonRecord;+ baseYaml: JsonRecord;+ modelsOverridden: boolean;+ principal: string;+}): T {+ const { merged, baseYaml, modelsOverridden, principal } = params;+ const anthropic = asRecord(getAtPath(merged, ANTHROPIC));+ if (anthropic == null || !isVertexConfigured(baseYaml)) {+ return merged;+ }+ const raw = withBaseOnlyValues(params.raw, baseYaml);+ const vertex = asRecord(getAtPath(raw, VERTEX));+ let vertexConfig: TVertexAIConfig | null = null;+ if (vertex != null && vertex.enabled !== false) {+ vertexConfig = isUsableVertex(vertex) ? validateVertexConfig(vertex as TVertexAISchema) : null;+ if (vertexConfig == null) {+ logger.warn(+ `[mergeConfigOverrides] Turning Vertex AI off for ${principal}: endpoints.anthropic.vertex does not load once its tombstones apply`,+ );+ }+ }+ const next: JsonRecord = { ...anthropic };+ if (vertexConfig == null) {+ delete next.vertexConfig;+ } else {+ next.vertexConfig = vertexConfig;+ }+ if (!modelsOverridden) {+ const models = vertexConfig?.modelNames ?? getAtPath(raw, [...ANTHROPIC, 'models']);+ if (models === undefined) {+ delete next.models;+ } else {+ next.models = models;+ }+ }+ return setEndpoint(merged, EModelEndpoint.anthropic, next);+}++/**+ * Each custom endpoint a layer wrote, with `customParams` expanded again from the+ * librechat.yaml-shaped entry the layers merged to, as startup expands librechat.yaml's: a+ * layer's compact definitions get their defaults, a `defaultParamsEndpoint` a layer changes picks+ * the defaults of the new endpoint, and an endpoint only a layer defines gets OpenRouter's+ * defaults by its name or URL. The served entry's other fields (its name, base URL, key) stay as+ * merged. Definitions that do not expand keep librechat.yaml's expanded ones (none for an endpoint+ * librechat.yaml does not define), with a warning.+ */+function expandWrittenEndpoints(+ merged: AppConfig,+ raw: JsonRecord,+ base: AppConfig,+ touches: ConfigTouches,+ expandCustomEndpoint: NonNullable<ConfigDerivation['expandCustomEndpoint']>,+): AppConfig {+ const entries = merged.endpoints?.custom;+ if (touches.customEndpoints.size === 0 || !Array.isArray(entries)) {+ return merged;+ }+ const byIdentity = (items: unknown): Map<string, JsonRecord> => {+ const found = new Map<string, JsonRecord>();+ for (const item of Array.isArray(items) ? items : []) {+ const record = asRecord(item);+ const identity = getEndpointIdentity(record?.name);+ if (record != null && identity != null) {+ found.set(identity, record);+ }+ }+ return found;+ };+ const rawEntries = byIdentity(getAtPath(raw, CUSTOM_ENDPOINTS));+ let baseEntries: Map<string, JsonRecord> | undefined;+ let changed = false;+ const next = entries.map((entry) => {+ const identity = getEndpointIdentity(entry?.name);+ if (identity == null || !touches.customEndpoints.has(identity)) {+ return entry;+ }+ const { customParams: _served, ...served } = entry;+ const compact = rawEntries.get(identity)?.customParams;+ let customParams: unknown;+ try {+ customParams = expandCustomEndpoint({+ ...served,+ ...(compact !== undefined && { customParams: compact }),+ } as TEndpoint).customParams;+ } catch {+ logger.warn(+ `[mergeConfigOverrides] Keeping librechat.yaml's customParams for endpoint "${entry.name}": the merged parameter definitions do not load`,+ );+ baseEntries ??= byIdentity(base.endpoints?.custom);+ customParams = baseEntries.get(identity)?.customParams;+ }+ changed = true;+ return (customParams === undefined ? served : { ...served, customParams }) as typeof entry;+ });+ if (!changed) {+ return merged;+ }+ return { ...merged, endpoints: { ...merged.endpoints, custom: next } };+}++/**+ * The agents endpoint's capabilities derived again, as startup derives them, when a layer wrote+ * or removed `memory` or the agents endpoint: from the YAML-shaped `endpoints.agents` (schema+ * defaults without one), without `memory` while the merged memory config is off, so a profile+ * that turns memory on gets the capability and one that turns it off loses the inert toggle.+ * Startup always serves an agents endpoint, so where a tombstone of it (or of `endpoints`) left+ * none, it is the one startup derives from what the layers leave, as a tombstone of its+ * `capabilities` serves the default capabilities.+ */+function deriveAgentCapabilities(merged: AppConfig, raw: JsonRecord): AppConfig {+ let derived: Partial<TAgentsEndpoint>;+ try {+ derived = agentsConfigSetup(raw as Partial<TCustomConfig>);+ } catch {+ return merged;+ }+ const { capabilities } = derived;+ if (!Array.isArray(capabilities)) {+ return merged;+ }+ const agents = merged.endpoints?.[EModelEndpoint.agents] ?? derived;+ const served = isMemoryEnabled(merged.memory)+ ? capabilities+ : capabilities.filter((capability) => capability !== AgentCapabilities.memory);+ return setEndpoint(merged, EModelEndpoint.agents, { ...agents, capabilities: served });+}++/**+ * The Azure Assistants endpoint derived again, as `loadEndpoints` derives it: its defaults while+ * the merged Azure endpoint turns `assistants` on, the YAML-shaped `endpoints.azureAssistants`+ * over them, and nothing when neither is left. One that does not parse stays as merged.+ */+function deriveAzureAssistants(merged: AppConfig, raw: JsonRecord, principals: string): AppConfig {+ const assistantsOn = Boolean(merged.endpoints?.[EModelEndpoint.azureOpenAI]?.assistants);+ let next: JsonRecord | undefined = assistantsOn ? azureAssistantsDefaults() : undefined;+ if (getAtPath(raw, [ENDPOINTS, EModelEndpoint.azureAssistants]) !== undefined) {+ try {+ next = assistantsConfigSetup(+ raw as Partial<TCustomConfig>,+ EModelEndpoint.azureAssistants,+ next,+ ) as JsonRecord;+ } catch {+ logger.warn(+ `[mergeConfigOverrides] Keeping endpoints.azureAssistants as merged for ${principals}: it does not parse`,+ );+ return merged;+ }+ }+ if (next === undefined && merged.endpoints?.[EModelEndpoint.azureAssistants] === undefined) {+ return merged;+ }+ return setEndpoint(merged, EModelEndpoint.azureAssistants, next);+}++/**+ * The model specs served without those whose endpoint the YAML-shaped config the layers leave+ * (`raw`) does not configure, by the rule startup leaves out librechat.yaml's+ * ({@link isKnownSpecEndpoint}, after inferring an agent spec's endpoint): a tombstone of+ * `endpoints.custom` or `endpoints` hides the specs of the custom endpoints it removes until a+ * layer defines them again, and a spec stored for an endpoint that is not configured is left out+ * on its own. Where no spec and no added endpoint is left, no spec list is served, as tenant+ * scoping and hidden endpoints leave none, so the controls specs turn off are derived without+ * them. `addedEndpoints` stays as merged, as startup keeps it: an endpoint it names that is gone+ * is simply not offered, while emptying the list would offer every endpoint (the names of custom+ * endpoints the layers remove are scoped out of it after the merge, `keyedTombstones`).+ */+function deriveServedSpecs(merged: AppConfig, raw: JsonRecord, principals: string): AppConfig {+ const modelSpecs = materializeModelSpecEndpoints(merged.modelSpecs);+ const list = modelSpecs?.list;+ if (modelSpecs == null || !Array.isArray(list) || list.length === 0) {+ return merged;+ }+ const customEndpoints = getEndpointIdentities(getAtPath(raw, CUSTOM_ENDPOINTS));+ const served = list.filter((spec) => {+ const endpoint: unknown = spec?.preset?.endpoint;+ return typeof endpoint === 'string' && isKnownSpecEndpoint(endpoint, customEndpoints);+ });+ if (served.length === list.length) {+ return merged;+ }+ logger.debug(+ `[mergeConfigOverrides] Leaving out ${list.length - served.length} model spec(s) for ${principals}: their endpoint is not configured once the layers apply`,+ );+ if (served.length > 0 || (modelSpecs.addedEndpoints?.length ?? 0) > 0) {+ return { ...merged, modelSpecs: { ...modelSpecs, list: served } };+ }+ const { modelSpecs: _hidden, ...rest } = merged;+ return rest;+}++/**+ * The derivations that follow a merge, for what its layers touched: custom endpoint parameters+ * (with `expandCustomEndpoint`), the model specs whose endpoint is still configured, the agents+ * endpoint's memory capability, and (with `rederiveEndpoints`) the Azure Assistants endpoint.+ * Untouched parts stay as merged.+ */+export function rederiveMergedConfig(params: {+ merged: AppConfig;+ raw: JsonRecord;+ base: AppConfig;+ touches: ConfigTouches;+ derivation: ConfigDerivation;+ principals: string;+}): AppConfig {+ const { raw, base, touches, derivation, principals } = params;+ let merged = params.merged;+ if (derivation.expandCustomEndpoint != null) {+ merged = expandWrittenEndpoints(merged, raw, base, touches, derivation.expandCustomEndpoint);+ }+ if (touchesConfig(touches, ['modelSpecs']) || touchesConfig(touches, CUSTOM_ENDPOINTS)) {+ merged = deriveServedSpecs(merged, raw, principals);+ }+ if (+ touchesConfig(touches, ['memory']) ||+ touchesConfig(touches, [ENDPOINTS, EModelEndpoint.agents])+ ) {+ merged = deriveAgentCapabilities(merged, raw);+ }+ if (+ derivation.rederiveEndpoints === true &&+ (touchesConfig(touches, [ENDPOINTS, EModelEndpoint.azureOpenAI]) ||+ touchesConfig(touches, [ENDPOINTS, EModelEndpoint.azureAssistants]))+ ) {+ merged = deriveAzureAssistants(merged, raw, principals);+ }+ return merged;+}diff --git a/packages/data-schemas/src/app/endpoints.ts b/packages/data-schemas/src/app/endpoints.tsindex 7a54f64342..27ab379a9c 100644--- a/packages/data-schemas/src/app/endpoints.ts+++ b/packages/data-schemas/src/app/endpoints.ts@@ -5,6 +5,7 @@ import type {TAgentsEndpoint,TAnthropicEndpoint,} from 'librechat-data-provider';+import type { ConfigDerivation } from './derive';import type { AppConfig } from '~/types';import { azureAssistantsDefaults, assistantsConfigSetup } from './assistants';import { agentsConfigSetup } from './agents';@@ -15,10 +16,13 @@ import { azureConfigSetup } from './azure';* Loads custom config endpoints* @param [config]* @param [agentsDefaults]+ * @param [expandCustomEndpoint] - Expands each custom endpoint's `customParams` into the copy+ * served, so `config` keeps them as librechat.yaml writes them.*/export const loadEndpoints = (config: Partial<TCustomConfig>,agentsDefaults?: Partial<TAgentsEndpoint>,+ expandCustomEndpoint?: ConfigDerivation['expandCustomEndpoint'],): {allowedAddresses?: string[];catalogModelsTtlMs?: number;@@ -79,12 +83,7 @@ export const loadEndpoints = (};}- const endpointKeys = [- EModelEndpoint.openAI,- EModelEndpoint.google,- EModelEndpoint.custom,- EModelEndpoint.bedrock,- ];+ const endpointKeys = [EModelEndpoint.openAI, EModelEndpoint.google, EModelEndpoint.bedrock];endpointKeys.forEach((key) => {const currentKey = key as keyof typeof endpoints;@@ -93,6 +92,13 @@ export const loadEndpoints = (}});+ const custom = endpoints?.[EModelEndpoint.custom] as TEndpoint[] | undefined;+ if (custom) {+ loadedEndpoints[EModelEndpoint.custom] = expandCustomEndpoint+ ? custom.map(expandCustomEndpoint)+ : custom;+ }+if (endpoints?.all) {/*** `DeepPartial<TCustomConfig>` widens record values to `string | undefined`diff --git a/packages/data-schemas/src/app/index.ts b/packages/data-schemas/src/app/index.tsindex 272c7ed01d..2e37c9dafd 100644--- a/packages/data-schemas/src/app/index.ts+++ b/packages/data-schemas/src/app/index.ts@@ -15,3 +15,4 @@ export * from './paths';export * from './mutations';export * from './store';export * from './changes';+export * from './derive';diff --git a/packages/data-schemas/src/app/interface.spec.ts b/packages/data-schemas/src/app/interface.spec.tsindex e914f7b8ff..bbdbfb02ef 100644--- a/packages/data-schemas/src/app/interface.spec.ts+++ b/packages/data-schemas/src/app/interface.spec.ts@@ -1,6 +1,7 @@import { getConfigDefaults, RetentionMode } from 'librechat-data-provider';import type { TCustomConfig } from 'librechat-data-provider';-import { loadDefaultInterface } from './interface';+import type { AppConfig } from '~/types';+import { loadDefaultInterface, deriveSpecInterface } from './interface';describe('loadDefaultInterface', () => {it('uses the schema default for URL auto-submit when not configured', async () => {@@ -509,3 +510,65 @@ describe('welcome screen heading and footer', () => {expect(interfaceConfig?.landingFooter).toBe(false);});});++describe('deriveSpecInterface', () => {+ const defaults = getConfigDefaults().interface;+ const specs = (list: unknown[], addedEndpoints?: string[]) =>+ ({ list, ...(addedEndpoints && { addedEndpoints }) }) as AppConfig['modelSpecs'];+ const spec = { name: 's', label: 'S', preset: { endpoint: 'openAI' } };+ const served = { modelSelect: true, parameters: true, presets: true, prompts: true };++ it('turns the spec-dependent controls off for served specs, the selector kept for addedEndpoints', () => {+ expect(deriveSpecInterface(served, undefined, specs([spec]), { defaults })).toEqual({+ modelSelect: false,+ parameters: false,+ presets: false,+ prompts: true,+ });+ expect(+ deriveSpecInterface(served, undefined, specs([spec], ['openAI']), { defaults })?.modelSelect,+ ).toBe(true);+ });++ it('turns them back on when no spec is served, a control left unset included', () => {+ const off = { modelSelect: false, parameters: false };+ const on = {+ modelSelect: defaults.modelSelect,+ parameters: defaults.parameters,+ presets: defaults.presets,+ };+ expect(deriveSpecInterface(off, undefined, specs([]), { defaults })).toEqual(on);+ expect(deriveSpecInterface(off, undefined, undefined, { defaults })).toEqual(on);+ });++ it('keeps what librechat.yaml or an override sets, and derives only the fields asked for', () => {+ const explicit = { parameters: true, presets: false };+ expect(deriveSpecInterface(served, explicit, specs([spec]), { defaults })).toEqual({+ ...served,+ modelSelect: false,+ presets: false,+ });+ expect(+ deriveSpecInterface(served, undefined, specs([spec]), { defaults, fields: ['parameters'] }),+ ).toEqual({ ...served, parameters: false });+ const settled = { modelSelect: false, parameters: false, presets: false };+ expect(deriveSpecInterface(settled, undefined, specs([spec]), { defaults })).toBe(settled);+ });++ it('derives them into a config whose interface a layer tombstoned, where none would read as off', () => {+ expect(deriveSpecInterface(undefined, undefined, undefined, { defaults })).toEqual({+ modelSelect: defaults.modelSelect,+ parameters: defaults.parameters,+ presets: defaults.presets,+ });+ expect(+ deriveSpecInterface(undefined, { parameters: true }, specs([spec]), { defaults }),+ ).toEqual({ modelSelect: false, parameters: true, presets: false });+ expect(+ deriveSpecInterface(undefined, undefined, specs([spec]), { defaults, fields: ['presets'] }),+ ).toEqual({ presets: false });+ expect(deriveSpecInterface(undefined, undefined, undefined, { defaults, fields: [] })).toBe(+ undefined,+ );+ });+});diff --git a/packages/data-schemas/src/app/interface.ts b/packages/data-schemas/src/app/interface.tsindex c9b3551eb0..8261eb77a2 100644--- a/packages/data-schemas/src/app/interface.ts+++ b/packages/data-schemas/src/app/interface.ts@@ -1,8 +1,58 @@-import { removeNullishValues } from 'librechat-data-provider';+import { getConfigDefaults, removeNullishValues } from 'librechat-data-provider';import type { TCustomConfig, TConfigDefaults } from 'librechat-data-provider';import type { AppConfig } from '~/types/app';import { isMemoryEnabled } from './memory';+/** The interface controls model specs turn off unless librechat.yaml or an override sets them. */+export const SPEC_INTERFACE_FIELDS = ['modelSelect', 'parameters', 'presets'] as const;++export type SpecInterfaceField = (typeof SPEC_INTERFACE_FIELDS)[number];++/**+ * `modelSelect`, `parameters` and `presets` as {@link loadDefaultInterface} decides them for the+ * model specs served, wherever `explicit` (the librechat.yaml-shaped interface, overrides merged+ * in) leaves them unset: with specs, the model selector stays only for `addedEndpoints` and+ * parameters and presets are off; without, each takes its default. Run on the final config, so a+ * profile that adds specs turns them off and one that removes every served spec (a tombstone, an+ * empty list, or tenant scoping) turns them back on. Only `fields` are derived (all three by+ * default). A config without an interface (a layer tombstoned it) gets one holding the fields+ * derived, which would otherwise read as off. Returns `interfaceConfig` itself when nothing+ * changes.+ */+export function deriveSpecInterface(+ interfaceConfig: AppConfig['interfaceConfig'],+ explicit: TCustomConfig['interface'] | undefined,+ modelSpecs: AppConfig['modelSpecs'],+ options: {+ fields?: readonly SpecInterfaceField[];+ defaults?: TConfigDefaults['interface'];+ } = {},+): AppConfig['interfaceConfig'] {+ const { fields = SPEC_INTERFACE_FIELDS, defaults = getConfigDefaults().interface } = options;+ const current: NonNullable<AppConfig['interfaceConfig']> = interfaceConfig ?? {};+ const hasModelSpecs = (modelSpecs?.list?.length ?? 0) > 0;+ const includesAddedEndpoints = (modelSpecs?.addedEndpoints?.length ?? 0) > 0;+ const derived: Record<SpecInterfaceField, boolean | undefined> = {+ modelSelect:+ explicit?.modelSelect ?? (hasModelSpecs ? includesAddedEndpoints : defaults.modelSelect),+ parameters: explicit?.parameters ?? (hasModelSpecs ? false : defaults.parameters),+ presets: explicit?.presets ?? (hasModelSpecs ? false : defaults.presets),+ };+ const changed = fields.filter((field) => current[field] !== derived[field]);+ if (changed.length === 0) {+ return interfaceConfig;+ }+ const next = { ...current };+ for (const field of changed) {+ if (derived[field] === undefined) {+ delete next[field];+ } else {+ next[field] = derived[field];+ }+ }+ return next;+}+/*** Loads the default interface object.* @param params - The loaded custom configuration.diff --git a/packages/data-schemas/src/app/resolution.layers.spec.ts b/packages/data-schemas/src/app/resolution.layers.spec.tsindex cb8ffa4a6b..c4fd1b3323 100644--- a/packages/data-schemas/src/app/resolution.layers.spec.ts+++ b/packages/data-schemas/src/app/resolution.layers.spec.ts@@ -408,15 +408,20 @@ describe('resolveConfigLayers', () => {expect(ignoredOf(resolution, 1)).toEqual([toIgnoredTombstone('cache', 'deployment_only_path')]);});- it('keeps Azure groups as written and reports groups the Azure clients never read', () => {+ it('keeps Azure groups as written and reports groups that do not resolve over the groups below', () => {const configs = PARITY_CASES.find(([name]) => name.startsWith('Azure groups'))![1]();- const resolution = resolveConfigLayers(appConfig, configs);+ const resolution = resolveConfigLayers(appConfig, configs, { rederiveEndpoints: true });const azure = resolution.resolved.endpoints?.azureOpenAI;- expect(azure?.groups?.map((entry) => entry.group)).toEqual(['west']);+ expect(azure?.groups?.map((entry) => entry.group)).toEqual(['east']);expect(azure).not.toHaveProperty('groupMap');expect(Object.keys(resolution.merged.endpoints?.azureOpenAI?.groupMap ?? {})).toEqual(['east']);- expect(reasons(ignoredOf(resolution, 1))).toEqual([- ['endpoints.azureOpenAI.groups', 'azure_groups_unresolved'],+ expect(ignoredOf(resolution, 1)).toEqual([+ {+ path: 'endpoints.azureOpenAI.groups',+ segments: ['endpoints', 'azureOpenAI', 'groups'],+ reason: 'invalid_override',+ code: 'invalid_azure_groups',+ },]);});diff --git a/packages/data-schemas/src/app/resolution.spec.ts b/packages/data-schemas/src/app/resolution.spec.tsindex 5440394d37..10e1e801b0 100644--- a/packages/data-schemas/src/app/resolution.spec.ts+++ b/packages/data-schemas/src/app/resolution.spec.ts@@ -1,11 +1,18 @@import { z } from 'zod';import {+ OptionTypes,PermissionTypes,SearchProviders,+ AgentCapabilities,INTERFACE_PERMISSION_FIELDS,DEPLOYMENT_ONLY_CONFIG_PATHS,} from 'librechat-data-provider';-import type { TCustomConfig, TWebSearchConfigInput } from 'librechat-data-provider';+import type {+ TEndpoint,+ DeepPartial,+ TCustomConfig,+ TWebSearchConfigInput,+} from 'librechat-data-provider';import type { AppConfig, IConfig } from '~/types';import {resolveRawConfig,@@ -31,6 +38,7 @@ import { toConfigOverrideState } from './mutations';import { applyConfigChanges } from './changes';import { loadWebSearchConfig } from './web';import { formatKeyedPath } from './paths';+import { AppService } from './service';import logger from '~/config/winston';function fakeConfig(@@ -1801,8 +1809,10 @@ describe('getConfigOverrideIssues', () => {groups: [{group: 'eastus',- apiKey: '${AZURE_KEY}',+ apiKey: 'azure-key',instanceName: 'east',+ deploymentName: 'gpt-41',+ version: '2024-10-21',models: { 'gpt-4.1': true, 'gpt-4.1-mini': { deploymentName: 'mini' } },addParams: { 'reasoning.effort': 'high' },},@@ -2117,13 +2127,14 @@ describe('getDottedSectionIssues', () => {describe('getConfigMergeRules', () => {it('names merge paths by their override (YAML) keys', () => {expect(getConfigMergeRules()).toEqual({- arrayMergeKeys: { 'endpoints.custom': 'name' },+ arrayMergeKeys: { 'endpoints.custom': 'name', 'endpoints.azureOpenAI.groups': 'group' },atomicMergePaths: ['interface.theme'],overrideKeyMap: {mcpServers: 'mcpConfig',interface: 'interfaceConfig',turnstile: 'turnstileConfig',},+ derivedPaths: ['endpoints.anthropic.vertexConfig'],});});});@@ -2604,6 +2615,13 @@ describe('mergeConfigOverrides: afterLayer', () => {});});+/** The merge as `CONFIG_REDERIVE_ENDPOINTS` runs it: a layer's Azure groups resolved. */+function mergeWithGroups(+ ...[baseConfig, configs, options]: Parameters<typeof mergeConfigOverrides>+) {+ return mergeConfigOverrides(baseConfig, configs, { rederiveEndpoints: true, ...options });+}+describe('mergeConfigOverrides: Azure groups an override writes', () => {const yamlGroup = {group: 'east',@@ -2636,20 +2654,23 @@ describe('mergeConfigOverrides: Azure groups an override writes', () => {models: { 'gpt-5': true, 'o3-mini': { deploymentName: 'o3' } },};- it('resolves them into the fields the Azure clients read, replacing what lay below', () => {- const merged = mergeConfigOverrides(base, [+ it('merges them by group over the groups below and resolves them into the fields the Azure clients read', () => {+ const merged = mergeWithGroups(base, [fakeConfig({ endpoints: { azureOpenAI: { groups: [west] } } }, 10),]);const azure = merged.endpoints?.azureOpenAI;expect(azure?.groupMap).toEqual({+ east: base.endpoints?.azureOpenAI?.groupMap?.east,west: expect.objectContaining({ apiKey: 'v3:stored-west-key', instanceName: 'west' }),});+ expect(azure?.groupMap?.east).toBe(base.endpoints?.azureOpenAI?.groupMap?.east);expect(azure?.modelGroupMap).toEqual({+ 'gpt-4o': { group: 'east' },'gpt-5': { group: 'west' },'o3-mini': { group: 'west' },});- expect(azure?.modelNames).toEqual(['gpt-5', 'o3-mini']);+ expect(azure?.modelNames).toEqual(['gpt-4o', 'gpt-5', 'o3-mini']);expect(azure?.assistantModels).toEqual(['gpt-5', 'o3-mini']);expect(azure?.assistantGroups).toEqual(['west']);expect(azure?.titleModel).toBe('gpt-4o');@@ -2657,7 +2678,7 @@ describe('mergeConfigOverrides: Azure groups an override writes', () => {});it("merges a groupMap the same layer writes over its own groups', and a later layer's over them", () => {- const merged = mergeConfigOverrides(base, [+ const merged = mergeWithGroups(base, [fakeConfig({ endpoints: { azureOpenAI: { groups: [west], groupMap: { west: { version: 'v2' } } } } },10,@@ -2672,20 +2693,42 @@ describe('mergeConfigOverrides: Azure groups an override writes', () => {});});- it("shows the layer alone with its groups in place of librechat.yaml's", () => {+ it("shows the layer alone with its groups merged over librechat.yaml's", () => {let aloneGroups: unknown;- mergeConfigOverrides(- base,- [fakeConfig({ endpoints: { azureOpenAI: { groups: [west] } } }, 10)],- {- afterLayer: (step) => {- aloneGroups = Object.keys(step.alone().endpoints?.azureOpenAI?.groupMap ?? {});- return step.merged;- },+ mergeWithGroups(base, [fakeConfig({ endpoints: { azureOpenAI: { groups: [west] } } }, 10)], {+ afterLayer: (step) => {+ aloneGroups = Object.keys(step.alone().endpoints?.azureOpenAI?.groupMap ?? {});+ return step.merged;},- );+ });- expect(aloneGroups).toEqual(['west']);+ expect(aloneGroups).toEqual(['east', 'west']);+ });++ it('leaves them and a tombstone of them inert without CONFIG_REDERIVE_ENDPOINTS', () => {+ const layers = [+ fakeConfig({ endpoints: { azureOpenAI: { groups: [west] } } }, 10),+ fakeConfig({}, 20, ['endpoints.azureOpenAI.groups'], 't20'),+ ];+ const written = mergeConfigOverrides(base, [layers[0]]);+ const tombstoned = mergeConfigOverrides(base, [layers[1]]);+ /** The served Azure endpoint without the stray `groups` the clients never read. */+ const resolved = (merged: AppConfig): Record<string, unknown> => {+ const { groups: _groups, ...azure } = (merged.endpoints?.azureOpenAI ?? {}) as Record<+ string,+ unknown+ >;+ return azure;+ };++ expect(resolved(written)).toEqual(base.endpoints?.azureOpenAI);+ expect(resolved(tombstoned)).toEqual(base.endpoints?.azureOpenAI);+ expect(resolved(mergeConfigOverrides(base, layers))).toEqual(base.endpoints?.azureOpenAI);+ expect(resolved(mergeWithGroups(base, [layers[0]])).modelNames).toEqual([+ 'gpt-4o',+ 'gpt-5',+ 'o3-mini',+ ]);});describe('a tombstone of the groups', () => {@@ -2693,7 +2736,7 @@ describe('mergeConfigOverrides: Azure groups an override writes', () => {fakeConfig({}, priority, ['endpoints.azureOpenAI.groups'], `t${priority}`);it('resolves the groups to none, so no Azure model or group is served', () => {- const merged = mergeConfigOverrides(base, [tombstone()]);+ const merged = mergeWithGroups(base, [tombstone()]);expect(merged.endpoints?.azureOpenAI).toEqual({titleModel: 'gpt-4o',@@ -2707,20 +2750,18 @@ describe('mergeConfigOverrides: Azure groups an override writes', () => {});it('creates no Azure endpoint where none is configured', () => {- const merged = mergeConfigOverrides({ config: {}, endpoints: {} } as AppConfig, [- tombstone(),- ]);+ const merged = mergeWithGroups({ config: {}, endpoints: {} } as AppConfig, [tombstone()]);expect(merged.endpoints).toEqual({});});it("lets the same layer's groups, or a later layer's, resolve in their place", () => {- const same = mergeConfigOverrides(base, [+ const same = mergeWithGroups(base, [fakeConfig({ endpoints: { azureOpenAI: { groups: [west] } } }, 10, ['endpoints.azureOpenAI.groups',]),]);- const later = mergeConfigOverrides(base, [+ const later = mergeWithGroups(base, [tombstone(10),fakeConfig({ endpoints: { azureOpenAI: { groups: [west] } } }, 20),]);@@ -2733,7 +2774,7 @@ describe('mergeConfigOverrides: Azure groups an override writes', () => {it('shows the layer alone without the groups, and removes them from the YAML floor', () => {let alone: unknown;- mergeConfigOverrides(base, [tombstone()], {+ mergeWithGroups(base, [tombstone()], {afterLayer: (step) => {alone = step.alone().endpoints?.azureOpenAI;return step.merged;@@ -2754,7 +2795,7 @@ describe('mergeConfigOverrides: Azure groups an override writes', () => {it('leaves groups that do not resolve unread, with a warning', () => {const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);- const merged = mergeConfigOverrides(base, [+ const merged = mergeWithGroups(base, [fakeConfig({ endpoints: { azureOpenAI: { groups: [west, { ...west, group: 'w2' }] } } }, 10),]);@@ -2768,6 +2809,7 @@ describe('mergeConfigOverrides: Azure groups an override writes', () => {/** As AppService resolves librechat.yaml's `assistants: true` over a group that serves them. */const assistantsBase = {...base,+ config: { endpoints: { azureOpenAI: { groups: [{ ...yamlGroup, assistants: true }] } } },endpoints: {azureOpenAI: {...base.endpoints?.azureOpenAI,@@ -2789,8 +2831,10 @@ describe('mergeConfigOverrides: Azure groups an override writes', () => {it('turns them off for groups none of whose models supports them, with a warning', () => {const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);- const merged = mergeConfigOverrides(assistantsBase, [- fakeConfig({ endpoints: { azureOpenAI: { groups: [plain] } } }, 10),+ const merged = mergeWithGroups(assistantsBase, [+ fakeConfig({ endpoints: { azureOpenAI: { groups: [plain] } } }, 10, [+ 'endpoints.azureOpenAI.groups',+ ]),]);const azure = merged.endpoints?.azureOpenAI;@@ -2805,23 +2849,25 @@ describe('mergeConfigOverrides: Azure groups an override writes', () => {});it("keeps them on when the groups serve them, or a later layer's groups serve them again", () => {- const own = mergeConfigOverrides(assistantsBase, [+ const own = mergeWithGroups(assistantsBase, [fakeConfig({ endpoints: { azureOpenAI: { groups: [west] } } }, 10),]);- const later = mergeConfigOverrides(assistantsBase, [- fakeConfig({ endpoints: { azureOpenAI: { groups: [plain] } } }, 10),+ const later = mergeWithGroups(assistantsBase, [+ fakeConfig({ endpoints: { azureOpenAI: { groups: [plain] } } }, 10, [+ 'endpoints.azureOpenAI.groups',+ ]),fakeConfig({ endpoints: { azureOpenAI: { groups: [west] } } }, 20),]);- for (const merged of [own, later]) {- expect(merged.endpoints?.azureOpenAI?.assistants).toBe(true);- expect(merged.endpoints?.azureOpenAI?.assistantModels).toEqual(['gpt-5', 'o3-mini']);- }+ expect(own.endpoints?.azureOpenAI?.assistants).toBe(true);+ expect(own.endpoints?.azureOpenAI?.assistantModels).toEqual(['gpt-4o', 'gpt-5', 'o3-mini']);+ expect(later.endpoints?.azureOpenAI?.assistants).toBe(true);+ expect(later.endpoints?.azureOpenAI?.assistantModels).toEqual(['gpt-5', 'o3-mini']);});it('turns off a layer that turns them on over models none of which supports them', () => {const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);- const merged = mergeConfigOverrides(base, [+ const merged = mergeWithGroups(base, [fakeConfig({ endpoints: { azureOpenAI: { assistants: true } } }, 10),]);@@ -2832,7 +2878,7 @@ describe('mergeConfigOverrides: Azure groups an override writes', () => {it('turns them off when the groups are tombstoned', () => {const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);- const merged = mergeConfigOverrides(assistantsBase, [+ const merged = mergeWithGroups(assistantsBase, [fakeConfig({}, 10, ['endpoints.azureOpenAI.groups']),]);@@ -2843,10 +2889,10 @@ describe('mergeConfigOverrides: Azure groups an override writes', () => {it('keeps only the assistant models an override names that a merged group serves them with', () => {const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);- const missing = mergeConfigOverrides(assistantsBase, [+ const missing = mergeWithGroups(assistantsBase, [fakeConfig({ endpoints: { azureOpenAI: { assistantModels: ['missing'] } } }, 10),]);- const mixed = mergeConfigOverrides(assistantsBase, [+ const mixed = mergeWithGroups(assistantsBase, [fakeConfig({endpoints: {@@ -2881,16 +2927,16 @@ describe('mergeConfigOverrides: Azure groups an override writes', () => {it('lists only the models a merged group serves, whatever an override writes to the lists', () => {const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);- const listed = mergeConfigOverrides(base, [+ const listed = mergeWithGroups(base, [fakeConfig({ endpoints: { azureOpenAI: { modelNames: ['missing', 'gpt-4o'] } } }, 10),]);- const unmapped = mergeConfigOverrides(base, [+ const unmapped = mergeWithGroups(base, [fakeConfig({ endpoints: { azureOpenAI: { modelGroupMap: { 'gpt-4o': { group: 'nowhere' } } } } },10,),]);- const untouched = mergeConfigOverrides(base, [+ const untouched = mergeWithGroups(base, [fakeConfig({ interface: { customWelcome: 'hi' } }, 10),]);@@ -3527,6 +3573,791 @@ describe('isAcceptedOverrideSection', () => {});});+/** librechat.yaml as AppService resolves it at startup, the base every merge below starts from. */+function loadBase(config: DeepPartial<TCustomConfig>, expand?: (endpoint: TEndpoint) => TEndpoint) {+ return AppService({ config: structuredClone(config), expandCustomEndpoint: expand });+}++describe('Azure groups merge by group', () => {+ const east = {+ group: 'east',+ apiKey: 'east-key',+ instanceName: 'east',+ version: '2024-10-21',+ deploymentName: 'gpt-4o',+ models: { 'gpt-4o': true },+ };+ const yaml = { endpoints: { azureOpenAI: { groups: [east] } } };+ const groups = (...items: Record<string, unknown>[]) => ({+ endpoints: { azureOpenAI: { groups: items } },+ });++ it('requires a unique group on every item, and refuses a write that addresses one by index', () => {+ expect(getConfigOverrideIssues(groups({ models: {} }, east, east))).toEqual(+ expect.arrayContaining([+ expect.objectContaining({+ path: 'endpoints.azureOpenAI.groups.0',+ code: 'missing_merge_key',+ }),+ expect.objectContaining({+ path: 'endpoints.azureOpenAI.groups.1',+ code: 'duplicate_merge_key',+ }),+ ]),+ );+ expect(+ getConfigFieldIssues({ 'endpoints.azureOpenAI.groups.0.instanceName': 'x' }, yaml),+ ).toEqual([+ {+ path: 'endpoints.azureOpenAI.groups',+ segments: ['endpoints', 'azureOpenAI', 'groups'],+ code: 'indexed_merge_key_write',+ },+ ]);+ });++ it('merges a partial item over the group of its name, which a write validates on', () => {+ expect(+ getConfigOverrideIssues(+ groups({ group: 'east', models: { 'gpt-4o-mini': { deploymentName: 'mini' } } }),+ yaml,+ ),+ ).toEqual([]);+ });++ it('refuses groups that do not resolve over the groups below, and leaves them out at merge', async () => {+ const duplicateModel = { ...east, group: 'west', instanceName: 'west' };+ const blankDeployment = { group: 'east', deploymentName: '' };+ const issue = [+ {+ path: 'endpoints.azureOpenAI.groups',+ segments: ['endpoints', 'azureOpenAI', 'groups'],+ code: 'invalid_azure_groups',+ },+ ];+ expect(getConfigOverrideIssues(groups(duplicateModel), yaml)).toEqual(issue);+ expect(getConfigOverrideIssues(groups(blankDeployment), yaml)).toEqual(issue);+ expect(+ getConfigOverrideIssues(groups({ ...east, apiKey: '${AZURE_UNSET_KEY_1}' }), yaml),+ ).toEqual(issue);++ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);+ const base = await loadBase(yaml);+ const merged = mergeWithGroups(base, [fakeConfig(groups(blankDeployment), 10)]);+ expect(merged.endpoints?.azureOpenAI?.groupMap).toEqual(base.endpoints?.azureOpenAI?.groupMap);+ expect(merged.endpoints?.azureOpenAI?.modelNames).toEqual(['gpt-4o']);+ expect(warn).toHaveBeenCalledWith(expect.stringContaining('invalid_azure_groups'));+ warn.mockRestore();+ });++ it('keeps groups a layer does not name, appends new ones and merges models by name', async () => {+ const base = await loadBase({+ endpoints: {+ azureOpenAI: {+ groups: [east, { ...east, group: 'north', instanceName: 'north', models: { o3: true } }],+ },+ },+ });+ const merged = mergeWithGroups(base, [+ fakeConfig(+ groups(+ { group: 'east', models: { 'gpt-4o-mini': { deploymentName: 'mini' } } },+ {+ ...east,+ group: 'west',+ instanceName: 'west',+ apiKey: 'west-key',+ models: { 'gpt-5': true },+ },+ ),+ 10,+ ),+ ]);++ const azure = merged.endpoints?.azureOpenAI;+ expect(Object.keys(azure?.groupMap ?? {})).toEqual(['east', 'north', 'west']);+ expect(azure?.groupMap?.north).toBe(base.endpoints?.azureOpenAI?.groupMap?.north);+ expect(azure?.groupMap?.east).toMatchObject({+ apiKey: 'east-key',+ models: { 'gpt-4o': true, 'gpt-4o-mini': { deploymentName: 'mini' } },+ });+ expect(azure?.modelNames).toEqual(['gpt-4o', 'gpt-4o-mini', 'o3', 'gpt-5']);+ expect(azure?.modelGroupMap?.['gpt-4o-mini']).toEqual({ group: 'east' });+ });++ it('serves what keyed tombstones leave of the groups, and leaves them inert without the switch', async () => {+ const north = {+ ...east,+ group: 'north',+ instanceName: 'north',+ apiKey: 'north-key',+ models: { o3: true, 'o3-mini': true },+ };+ const base = await loadBase({ endpoints: { azureOpenAI: { groups: [east, north] } } });+ const hidden = [fakeConfig({}, 10, ['endpoints.azureOpenAI.groups["north"]'])];++ const azure = mergeWithGroups(base, hidden).endpoints?.azureOpenAI;+ expect(Object.keys(azure?.groupMap ?? {})).toEqual(['east']);+ expect(azure?.groupMap?.east).toBe(base.endpoints?.azureOpenAI?.groupMap?.east);+ expect(azure?.modelNames).toEqual(['gpt-4o']);+ expect(azure?.modelGroupMap?.o3).toBeUndefined();++ const inside = mergeWithGroups(base, [+ fakeConfig({}, 10, ['endpoints.azureOpenAI.groups["north"].models.o3-mini']),+ ]).endpoints?.azureOpenAI;+ expect(inside?.modelNames).toEqual(['gpt-4o', 'o3']);+ expect(inside?.groupMap?.north).toMatchObject({ apiKey: 'north-key', models: { o3: true } });+ expect(inside?.groupMap?.east).toBe(base.endpoints?.azureOpenAI?.groupMap?.east);++ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);+ const unresolved = mergeWithGroups(base, [+ fakeConfig({}, 10, ['endpoints.azureOpenAI.groups["north"].instanceName']),+ ]).endpoints?.azureOpenAI;+ expect(Object.keys(unresolved?.groupMap ?? {})).toEqual(['east']);+ expect(unresolved?.modelNames).toEqual(['gpt-4o']);+ expect(warn).toHaveBeenCalledWith(expect.stringContaining('Serving none of the'));+ warn.mockRestore();++ const off = mergeConfigOverrides(base, hidden).endpoints?.azureOpenAI;+ expect(off?.groupMap).toEqual(base.endpoints?.azureOpenAI?.groupMap);+ expect(off?.modelNames).toEqual(base.endpoints?.azureOpenAI?.modelNames);+ });+});++describe('Vertex AI derived from overrides (rederiveEndpoints)', () => {+ const yaml = {+ endpoints: {+ anthropic: {+ models: ['claude-direct'],+ vertex: {+ projectId: 'yaml-project',+ region: 'us-east5',+ serviceKeyFile: '/keys/vertex.json',+ models: ['claude-sonnet-4-6'],+ },+ },+ },+ };+ const vertex = (settings: Record<string, unknown>, extra: Record<string, unknown> = {}) => ({+ endpoints: { anthropic: { vertex: settings, ...extra } },+ });+ const merge = async (+ overrides: Record<string, unknown>,+ rederiveEndpoints = true,+ tombstones?: string[],+ ) =>+ mergeConfigOverrides(await loadBase(yaml), [fakeConfig(overrides, 10, tombstones)], {+ rederiveEndpoints,+ }).endpoints?.anthropic;++ it('leaves Vertex AI overrides inert without it', async () => {+ const anthropic = await merge(vertex({ models: ['claude-opus-4-6'] }), false);++ expect(anthropic?.models).toEqual(['claude-sonnet-4-6']);+ expect(anthropic?.vertexConfig?.modelNames).toEqual(['claude-sonnet-4-6']);+ });++ it('derives the models and vertexConfig a layer writes', async () => {+ const anthropic = await merge(+ vertex({ models: ['claude-opus-4-6'], deploymentName: 'opus-deploy' }),+ );++ expect(anthropic?.models).toEqual(['claude-opus-4-6']);+ expect(anthropic?.vertexConfig).toMatchObject({+ projectId: 'yaml-project',+ region: 'us-east5',+ serviceKeyFile: '/keys/vertex.json',+ modelNames: ['claude-opus-4-6'],+ modelDeploymentMap: { 'claude-opus-4-6': 'opus-deploy' },+ });+ });++ it("keeps librechat.yaml's region and key file whatever a layer stores", async () => {+ const anthropic = await merge(+ vertex({ region: 'attacker', serviceKeyFile: 'http://169.254.169.254/key' }),+ );++ expect(anthropic?.vertexConfig).toMatchObject({+ region: 'us-east5',+ serviceKeyFile: '/keys/vertex.json',+ });+ expect(anthropic?.vertex).toMatchObject({+ region: 'us-east5',+ serviceKeyFile: '/keys/vertex.json',+ });+ });++ it('turns Vertex AI off with enabled: false or a tombstone, serving the YAML-shaped models', async () => {+ const disabled = await merge(vertex({ enabled: false }));+ const tombstoned = await merge({}, true, ['endpoints.anthropic.vertex']);++ for (const anthropic of [disabled, tombstoned]) {+ expect(anthropic?.vertexConfig).toBeUndefined();+ expect(anthropic?.models).toEqual(['claude-direct']);+ }+ });++ it("serves the models a layer sets in endpoints.anthropic.models over Vertex AI's", async () => {+ const anthropic = await merge(+ vertex({ models: ['claude-opus-4-6'] }, { models: ['claude-x'] }),+ );++ expect(anthropic?.models).toEqual(['claude-x']);+ expect(anthropic?.vertexConfig?.modelNames).toEqual(['claude-opus-4-6']);+ });++ describe('models a later layer removes', () => {+ const MODELS = 'endpoints.anthropic.models';+ const layered = async (...layers: IConfig[]) =>+ mergeConfigOverrides(await loadBase(yaml), layers, { rederiveEndpoints: true }).endpoints+ ?.anthropic;+ const setsModels = (extra: Record<string, unknown> = {}) =>+ fakeConfig({ endpoints: { anthropic: { models: ['claude-x'], ...extra } } }, 10, [], 'low');++ it("serves Vertex AI's models again once a higher layer tombstones a lower layer's", async () => {+ const anthropic = await layered(setsModels(), fakeConfig({}, 20, [MODELS], 'high'));++ expect(anthropic?.models).toEqual(['claude-sonnet-4-6']);+ expect(anthropic?.vertexConfig?.modelNames).toEqual(['claude-sonnet-4-6']);+ });++ it('derives them from the Vertex AI setup the tombstoning layer writes', async () => {+ const anthropic = await layered(+ setsModels({ vertex: { models: ['claude-haiku-4-5'] } }),+ fakeConfig(vertex({ models: ['claude-opus-4-6'] }), 20, [MODELS], 'high'),+ );++ expect(anthropic?.models).toEqual(['claude-opus-4-6']);+ expect(anthropic?.vertexConfig?.modelNames).toEqual(['claude-opus-4-6']);+ });++ it("serves Vertex AI's models where a layer tombstones librechat.yaml's", async () => {+ const anthropic = await layered(fakeConfig({}, 10, [MODELS]));++ expect(anthropic?.models).toEqual(['claude-sonnet-4-6']);+ });++ it('keeps the models a higher layer sets over a lower tombstone of them', async () => {+ const anthropic = await layered(+ fakeConfig({}, 10, [MODELS], 'low'),+ fakeConfig(+ vertex({ models: ['claude-opus-4-6'] }, { models: ['claude-y'] }),+ 20,+ [],+ 'high',+ ),+ );+ const sameLayer = await layered(+ fakeConfig(vertex({ models: ['claude-opus-4-6'] }, { models: ['claude-y'] }), 10, [MODELS]),+ );++ expect(anthropic?.models).toEqual(['claude-y']);+ expect(anthropic?.vertexConfig?.modelNames).toEqual(['claude-opus-4-6']);+ expect(sameLayer?.models).toEqual(['claude-y']);+ });++ it('keeps them inert without rederiveEndpoints, as before', async () => {+ const anthropic = mergeConfigOverrides(+ await loadBase(yaml),+ [setsModels(), fakeConfig({}, 20, [MODELS], 'high')],+ { rederiveEndpoints: false },+ ).endpoints?.anthropic;++ expect(anthropic?.models).toBeUndefined();+ });+ });++ it.each([false, true])(+ "never applies a layer's own vertexConfig (rederiveEndpoints: %s)",+ async (rederiveEndpoints) => {+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);+ const base = await loadBase(yaml);+ const written = mergeConfigOverrides(+ base,+ [+ fakeConfig(+ {+ endpoints: {+ anthropic: {+ vertexConfig: {+ serviceKeyFile: 'http://169.254.169.254/key',+ region: 'evil.example',+ },+ },+ },+ },+ 10,+ ),+ ],+ { rederiveEndpoints },+ );+ const tombstoned = mergeConfigOverrides(+ base,+ [fakeConfig({}, 10, ['endpoints.anthropic.vertexConfig'])],+ { rederiveEndpoints },+ );++ expect(written.endpoints?.anthropic?.vertexConfig).toEqual(+ base.endpoints?.anthropic?.vertexConfig,+ );+ expect(tombstoned.endpoints?.anthropic?.vertexConfig).toEqual(+ base.endpoints?.anthropic?.vertexConfig,+ );+ expect(warn).toHaveBeenCalledWith(+ expect.stringContaining('Ignoring endpoints.anthropic.vertexConfig for role/test'),+ );+ warn.mockRestore();+ },+ );++ it('refuses a setup that does not load on write, and keeps the one below at merge', async () => {+ const unset = vertex({ projectId: '${VERTEX_UNSET_PROJECT_1}' });+ expect(getConfigOverrideIssues(unset, yaml)).toEqual([+ {+ path: 'endpoints.anthropic.vertex',+ segments: ['endpoints', 'anthropic', 'vertex'],+ code: 'invalid_vertex_config',+ },+ ]);+ expect(getConfigOverrideIssues(vertex({ projectId: 'a/../b' }), yaml)).toEqual([+ expect.objectContaining({ path: 'endpoints.anthropic.vertex.projectId', code: 'custom' }),+ ]);++ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);+ const anthropic = await merge(unset);+ expect(anthropic?.vertexConfig).toMatchObject({ projectId: 'yaml-project' });+ warn.mockRestore();+ });++ describe('where librechat.yaml configures no Vertex AI', () => {+ const direct = { endpoints: { anthropic: { models: ['claude-direct'] } } };+ const usable = vertex({ projectId: 'profile-project', models: ['claude-opus-4-6'] });++ it("refuses a write that turns it on, the deployment's default Google credentials unchosen", async () => {+ const floor = resolveRawConfig(direct, []);+ const issue = {+ path: 'endpoints.anthropic.vertex',+ segments: ['endpoints', 'anthropic', 'vertex'],+ code: 'invalid_vertex_config',+ };++ expect(getConfigOverrideIssues(usable, floor, { vertexConfigured: false })).toEqual([issue]);+ expect(+ getConfigOverrideIssues(vertex({ enabled: false }), floor, { vertexConfigured: false }),+ ).toEqual([]);+ expect(getConfigOverrideIssues(usable, yaml, { vertexConfigured: true })).toEqual([]);+ });++ it('never turns it on at merge, a Base layer included, and warns of the stored override', async () => {+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);+ const base = await loadBase(direct);+ const layers = [+ fakeConfig(usable, 0, undefined, BASE_CONFIG_PRINCIPAL_ID),+ fakeConfig(vertex({ models: ['claude-x'] }), 10),+ ];+ const merged = mergeConfigOverrides(base, layers, { rederiveEndpoints: true });++ expect(merged.endpoints?.anthropic?.vertexConfig).toBeUndefined();+ expect(merged.endpoints?.anthropic?.models).toEqual(['claude-direct']);+ expect(warn).toHaveBeenCalledWith(expect.stringContaining('(invalid_vertex_config)'));+ warn.mockRestore();+ });+ });+});++describe('Azure Assistants derived from overrides (rederiveEndpoints)', () => {+ const east = {+ group: 'east',+ apiKey: 'east-key',+ instanceName: 'east',+ version: '2024-10-21',+ deploymentName: 'gpt-4o',+ assistants: true,+ models: { 'gpt-4o': true },+ };+ const yaml = { endpoints: { azureOpenAI: { groups: [east] } } };++ it('derives the Azure Assistants endpoint a layer turns on, and drops it when turned off', async () => {+ const base = await loadBase(yaml);+ const on = (rederiveEndpoints: boolean) =>+ mergeConfigOverrides(+ base,+ [fakeConfig({ endpoints: { azureOpenAI: { assistants: true } } }, 10)],+ {+ rederiveEndpoints,+ },+ );++ expect(base.endpoints?.azureAssistants).toBeUndefined();+ expect(on(false).endpoints?.azureAssistants).toBeUndefined();+ expect(on(true).endpoints?.azureAssistants).toMatchObject({+ capabilities: expect.arrayContaining(['tools', 'actions', 'code_interpreter']),+ });++ const assistantsBase = await loadBase({+ endpoints: { azureOpenAI: { ...yaml.endpoints.azureOpenAI, assistants: true } },+ });+ const off = mergeConfigOverrides(+ assistantsBase,+ [fakeConfig({ endpoints: { azureOpenAI: { assistants: false } } }, 10)],+ { rederiveEndpoints: true },+ );+ const tombstoned = mergeConfigOverrides(+ assistantsBase,+ [fakeConfig({}, 10, ['endpoints.azureOpenAI'])],+ { rederiveEndpoints: true },+ );+ expect(assistantsBase.endpoints?.azureAssistants).toBeDefined();+ expect(off.endpoints?.azureAssistants).toBeUndefined();+ expect(tombstoned.endpoints?.azureOpenAI).toBeUndefined();+ expect(tombstoned.endpoints?.azureAssistants).toBeUndefined();+ });+});++describe('custom endpoint parameters expanded for overrides', () => {+ /** Records which defaults each definition was completed from; refuses a key named `invalid`. */+ const expand = (endpoint: TEndpoint): TEndpoint => {+ const params = endpoint.customParams;+ if (params == null) {+ return endpoint.name.startsWith('OpenRouter')+ ? {+ ...endpoint,+ customParams: {+ defaultParamsEndpoint: 'openrouter',+ paramDefinitions: [+ { key: 'promptCache', default: true, optionType: OptionTypes.Custom },+ ],+ },+ }+ : { ...endpoint };+ }+ const from = params.defaultParamsEndpoint ?? 'custom';+ return {+ ...endpoint,+ customParams: {+ ...params,+ defaultParamsEndpoint: from,+ paramDefinitions: (params.paramDefinitions ?? []).map((definition) => {+ if (definition.key === 'invalid') {+ throw new Error('invalid key');+ }+ return {+ ...definition,+ label: `${from}:${definition.key}`,+ optionType: OptionTypes.Custom,+ };+ }),+ },+ };+ };+ const gateway = {+ name: 'Gateway',+ apiKey: 'gateway-key',+ baseURL: 'https://gateway.example.com/v1',+ models: { default: ['m1'] },+ customParams: {+ defaultParamsEndpoint: 'anthropic',+ paramDefinitions: [{ key: 'temperature', default: 0.2 }],+ },+ };+ const other = { ...gateway, name: 'Other' };+ const yaml = { endpoints: { custom: [gateway, other] } };+ const merge = async (custom: unknown[]) => {+ const base = await loadBase(yaml, expand);+ const merged = mergeConfigOverrides(base, [fakeConfig({ endpoints: { custom } }, 10)], {+ expandCustomEndpoint: expand,+ });+ return {+ base,+ served: (name: string) => merged.endpoints?.custom?.find((entry) => entry.name === name),+ };+ };++ it('keeps librechat.yaml as written and serves the expanded copy', async () => {+ const base = await loadBase(yaml, expand);++ expect(base.config.endpoints?.custom?.[0]).toEqual(gateway);+ expect(base.endpoints?.custom?.[0]?.customParams?.paramDefinitions).toEqual([+ { key: 'temperature', default: 0.2, label: 'anthropic:temperature', optionType: 'custom' },+ ]);+ });++ it("expands a layer's compact definitions, and leaves endpoints it does not write as they were", async () => {+ const { base, served } = await merge([+ { name: 'Gateway', customParams: { paramDefinitions: [{ key: 'top_p' }] } },+ ]);++ expect(served('Gateway')?.customParams?.paramDefinitions).toEqual([+ { key: 'top_p', label: 'anthropic:top_p', optionType: 'custom' },+ ]);+ expect(served('Other')).toEqual(base.endpoints?.custom?.[1]);+ });++ it('expands again for a defaultParamsEndpoint a layer changes, from the definitions as written', async () => {+ const { served } = await merge([+ { name: 'Gateway', customParams: { defaultParamsEndpoint: 'openAI' } },+ ]);++ expect(served('Gateway')?.customParams).toEqual({+ defaultParamsEndpoint: 'openAI',+ paramDefinitions: [+ { key: 'temperature', default: 0.2, label: 'openAI:temperature', optionType: 'custom' },+ ],+ });+ });++ it("adds defaults to an endpoint only a layer defines, and keeps librechat.yaml's for invalid ones", async () => {+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);+ const { base, served } = await merge([+ { ...gateway, name: 'OpenRouter DB', customParams: undefined },+ { name: 'Gateway', customParams: { paramDefinitions: [{ key: 'invalid' }] } },+ ]);++ expect(served('OpenRouter DB')?.customParams?.paramDefinitions).toEqual([+ { key: 'promptCache', default: true, optionType: 'custom' },+ ]);+ expect(served('Gateway')?.customParams).toEqual(base.endpoints?.custom?.[0]?.customParams);+ expect(+ getConfigOverrideIssues(+ {+ endpoints: {+ custom: [{ name: 'Gateway', customParams: { paramDefinitions: [{ key: 'invalid' }] } }],+ },+ },+ yaml,+ { expandCustomEndpoint: expand },+ ),+ ).toEqual([+ {+ path: 'endpoints.custom.0.customParams',+ segments: ['endpoints', 'custom', '0', 'customParams'],+ code: 'invalid_param_definitions',+ },+ ]);+ warn.mockRestore();+ });+});++describe('the agents memory capability follows the merged memory config', () => {+ const capabilities = (config: AppConfig) => config.endpoints?.agents?.capabilities ?? [];++ it('offers memory to a profile that turns it on, and not to one that turns it off', async () => {+ const disabledBase = await loadBase({ memory: { disabled: true } });+ const enabledBase = await loadBase({ memory: { disabled: false, personalize: true } });++ expect(capabilities(disabledBase)).not.toContain(AgentCapabilities.memory);+ expect(capabilities(enabledBase)).toContain(AgentCapabilities.memory);+ expect(+ capabilities(+ mergeConfigOverrides(disabledBase, [fakeConfig({ memory: { disabled: false } }, 10)]),+ ),+ ).toContain(AgentCapabilities.memory);+ expect(+ capabilities(+ mergeConfigOverrides(enabledBase, [fakeConfig({ memory: { disabled: true } }, 10)]),+ ),+ ).not.toContain(AgentCapabilities.memory);+ expect(+ capabilities(+ mergeConfigOverrides(disabledBase, [+ fakeConfig(+ {+ endpoints: {+ agents: { capabilities: [AgentCapabilities.memory, AgentCapabilities.tools] },+ },+ },+ 10,+ ),+ ]),+ ),+ ).toEqual([AgentCapabilities.tools]);+ });+});++describe('derived parts follow what the layers leave, set then tombstoned or the reverse', () => {+ const low = (overrides: Record<string, unknown>, tombstones: string[] = []) =>+ fakeConfig(overrides, 10, tombstones, 'low');+ const high = (overrides: Record<string, unknown>, tombstones: string[] = []) =>+ fakeConfig(overrides, 20, tombstones, 'high');+ const east = {+ group: 'east',+ apiKey: 'east-key',+ instanceName: 'east',+ version: '2024-10-21',+ deploymentName: 'gpt-4o',+ assistants: true,+ models: { 'gpt-4o': true },+ };+ const groups = (...items: Record<string, unknown>[]) => ({+ endpoints: { azureOpenAI: { groups: items } },+ });+ const GROUPS = 'endpoints.azureOpenAI.groups';++ it('the agents memory capability', async () => {+ const offBase = await loadBase({ memory: { disabled: true } });+ const onBase = await loadBase({ memory: { disabled: false, personalize: true } });+ const offers = (base: AppConfig, configs: IConfig[]) =>+ (mergeConfigOverrides(base, configs).endpoints?.agents?.capabilities ?? []).includes(+ AgentCapabilities.memory,+ );+ const on = { memory: { disabled: false } };++ expect(offers(offBase, [low(on), high({}, ['memory'])])).toBe(false);+ expect(offers(offBase, [low({}, ['memory']), high(on)])).toBe(true);+ expect(+ offers(onBase, [low({ memory: { disabled: true } }), high({}, ['memory.disabled'])]),+ ).toBe(true);+ });++ it('the Azure Assistants endpoint', async () => {+ const base = await loadBase({ endpoints: { azureOpenAI: { groups: [east] } } });+ const assistants = { endpoints: { azureOpenAI: { assistants: true } } };+ const ASSISTANTS = 'endpoints.azureOpenAI.assistants';++ expect(+ mergeWithGroups(base, [low(assistants), high({}, [ASSISTANTS])]).endpoints?.azureAssistants,+ ).toBeUndefined();+ expect(+ mergeWithGroups(base, [low({}, [ASSISTANTS]), high(assistants)]).endpoints?.azureAssistants,+ ).toBeDefined();+ });++ it('Azure groups', async () => {+ const base = await loadBase({ endpoints: { azureOpenAI: { groups: [east] } } });+ const group = (name: string, model: string) => ({+ ...east,+ group: name,+ instanceName: name,+ apiKey: `${name}-key`,+ deploymentName: model,+ models: { [model]: true },+ });+ const served = (configs: IConfig[]) => {+ const azure = mergeWithGroups(base, configs).endpoints?.azureOpenAI;+ return { groups: Object.keys(azure?.groupMap ?? {}), models: azure?.modelNames };+ };++ expect(+ served([low(groups(group('west', 'gpt-5'))), high(groups(group('north', 'o3')), [GROUPS])]),+ ).toEqual({ groups: ['north'], models: ['o3'] });+ expect(served([low({}, [GROUPS]), high(groups(group('west', 'gpt-5')))])).toEqual({+ groups: ['west'],+ models: ['gpt-5'],+ });+ });++ describe('what a layer recreates after a tombstone of an object above removed it', () => {+ const titled = { endpoints: { azureOpenAI: { titleModel: 'gpt-4o' } } };+ const noGroup = {+ titleModel: 'gpt-4o',+ groupMap: {},+ modelGroupMap: {},+ modelNames: [],+ assistantModels: [],+ assistantGroups: [],+ };++ it.each(['endpoints.azureOpenAI', 'endpoints'])(+ 'serves no Azure group from an Azure endpoint recreated without groups after a tombstone of %s',+ async (tombstone) => {+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);+ const base = await loadBase({ endpoints: { azureOpenAI: { groups: [east] } } });+ const layerings = [+ [low({}, [tombstone]), high(titled)],+ [low(titled, [tombstone])],+ [low(groups(east)), high(titled, [tombstone])],+ ];++ for (const rederiveEndpoints of [true, false]) {+ for (const layers of layerings) {+ expect(+ mergeConfigOverrides(base, layers, { rederiveEndpoints }).endpoints?.azureOpenAI,+ ).toEqual(noGroup);+ }+ }+ expect(warn).toHaveBeenCalledWith(+ expect.stringContaining('Serving no Azure group for role/low, role/high'),+ );+ expect(base.endpoints?.azureOpenAI?.modelNames).toEqual(['gpt-4o']);+ warn.mockRestore();+ },+ );++ it.each(['endpoints.agents', 'endpoints'])(+ 'serves the agents endpoint startup derives where a tombstone of %s left none',+ async (tombstone) => {+ const offBase = await loadBase({ memory: { disabled: true } });+ const onBase = await loadBase({ memory: { disabled: false, personalize: true } });+ const agents = (base: AppConfig, configs: IConfig[]) =>+ mergeConfigOverrides(base, configs).endpoints?.agents;++ expect(agents(offBase, [low({}, [tombstone])])).toEqual(offBase.endpoints?.agents);+ expect(agents(onBase, [low({}, [tombstone])])).toEqual(onBase.endpoints?.agents);+ expect(+ agents(offBase, [low({}, [tombstone]), high({ memory: { disabled: false } })]),+ ).toEqual(onBase.endpoints?.agents);+ expect(onBase.endpoints?.agents?.capabilities).toContain(AgentCapabilities.memory);+ },+ );+ });+});++describe('model spec endpoints', () => {+ const spec = (endpoint: string) => ({+ name: endpoint,+ label: endpoint,+ preset: { endpoint, model: 'm' },+ });++ const gateway = {+ name: 'Gateway',+ apiKey: 'k',+ baseURL: 'https://g',+ models: { default: ['m'] },+ };+ const yaml = {+ endpoints: { custom: [gateway] },+ modelSpecs: { list: [spec('Gateway'), spec('openAI')] },+ };+ const yamlBase = { config: yaml, modelSpecs: yaml.modelSpecs } as unknown as AppConfig;+ const served = (configs: IConfig[]) =>+ mergeConfigOverrides(yamlBase, configs).modelSpecs?.list?.map(({ name }) => name);++ it('refuses a spec for an endpoint that is not configured on write, and leaves only it out at merge', () => {+ expect(+ getConfigOverrideIssues({ modelSpecs: { list: [spec('Gateway'), spec('openAI')] } }, yaml),+ ).toEqual([]);+ expect(getConfigOverrideIssues({ modelSpecs: { list: [spec('Nowhere')] } }, yaml)).toEqual([+ {+ path: 'modelSpecs.list.0.preset.endpoint',+ segments: ['modelSpecs', 'list', '0', 'preset', 'endpoint'],+ code: 'unknown_spec_endpoint',+ },+ ]);++ expect(+ served([fakeConfig({ modelSpecs: { list: [spec('Nowhere'), spec('Gateway')] } }, 10)]),+ ).toEqual(['Gateway']);+ });++ it.each([['endpoints.custom'], ['endpoints']])(+ 'leaves out the specs of the custom endpoints a tombstone of %s removes, until a layer defines them again',+ (path) => {+ expect(served([fakeConfig({}, 10, [path])])).toEqual(['openAI']);+ expect(+ served([fakeConfig({}, 10, [path]), fakeConfig({ endpoints: { custom: [gateway] } }, 20)]),+ ).toEqual(['Gateway', 'openAI']);+ expect(+ served([+ fakeConfig({ endpoints: { custom: [{ ...gateway, name: 'Router' }] } }, 10),+ fakeConfig({ modelSpecs: { list: [spec('Router')] } }, 20),+ fakeConfig({}, 30, [path]),+ ]),+ ).toBeUndefined();+ },+ );+});+describe('issue params', () => {const firstIssue = (schema: z.ZodTypeAny, value: unknown) => {const result = schema.safeParse(value);@@ -3719,7 +4550,9 @@ describe('deployment-only paths in the merge', () => {const merged = mergeConfigOverrides(base, [fakeConfig({}, 10, ['endpoints.agents'])]) as {endpoints?: { agents?: Record<string, unknown> };};- expect(merged.endpoints?.agents).toEqual({ eventDriven: { idlePolling: true } });+ /** The rest is the agents endpoint startup derives from what the layers leave. */+ expect(merged.endpoints?.agents?.eventDriven).toEqual({ idlePolling: true });+ expect(merged.endpoints?.agents).not.toHaveProperty('recursionLimit');});it('keeps the tool filters librechat.yaml sets, so a profile cannot gate tools', () => {diff --git a/packages/data-schemas/src/app/resolution.ts b/packages/data-schemas/src/app/resolution.tsindex c387021b1a..e77d5620d3 100644--- a/packages/data-schemas/src/app/resolution.ts+++ b/packages/data-schemas/src/app/resolution.ts@@ -2,6 +2,7 @@ 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,@@ -23,6 +24,7 @@ import type {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 {@@ -39,10 +41,23 @@ import {} from './collections';import {AZURE_RESOLVED_GROUP_FIELDS,- lacksAzureAssistantModels,+ toAzureGroupMapEntry,+ completeAzureResolution,+ getEmptyAzureResolution,narrowAzureServedModels,- resolveAzureGroups,+ 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';@@ -69,6 +84,42 @@ const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);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[];@@ -115,12 +166,14 @@ const AZURE_RESOLVED_PATHS: readonly string[] = AZURE_RESOLVED_GROUP_FIELDS.map(const AZURE_GROUPS_PATH = `${AZURE_CONFIG_PATH}.groups`;/**- * The paths a tombstone removes: its own, and for Azure `groups` every field they resolve to- * (`AZURE_RESOLVED_PATHS`), which the Azure clients and model lists read in their place. A- * tombstone removes the groups whole, as a layer's own `groups` replace them.+ * 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): readonly string[] {- return path === AZURE_GROUPS_PATH ? [path, ...AZURE_RESOLVED_PATHS] : [path];+function getTombstoneRemovals(path: string, resolvesAzureGroups: boolean): readonly string[] {+ return resolvesAzureGroups && path === AZURE_GROUPS_PATH+ ? [path, ...AZURE_RESOLVED_PATHS]+ : [path];}/**@@ -135,14 +188,7 @@ function withoutAzureGroups<T extends AnyObject>(merged: T): T {if (!isPlainObject(azure)) {return merged;}- const empty: Record<AzureResolvedGroupField, object> = {- groupMap: {},- modelGroupMap: {},- modelNames: [],- assistantModels: [],- assistantGroups: [],- };- return setPath(merged, segments, { ...azure, ...empty }) as T;+ return setPath(merged, segments, { ...azure, ...getEmptyAzureResolution() }) as T;}/**@@ -174,6 +220,7 @@ export function getConfigMergeRules(): AdminConfigMergeRules {overrideKeyMap: Object.fromEntries([...OVERRIDE_SECTION_BY_APP_KEY].map(([appKey, section]) => [section, appKey]),),+ derivedPaths: [...DERIVED_CONFIG_PATHS],};}@@ -203,6 +250,29 @@ export function combineFoldedConfigEntries(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]);}@@ -1066,11 +1136,15 @@ export function getDottedSectionIssues(overrides: unknown): ConfigOverrideIssue[* 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.+ * 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')];@@ -1078,7 +1152,24 @@ export function getConfigOverrideIssues(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)) {@@ -1090,35 +1181,28 @@ export function getConfigOverrideIssues(const result = shape[section as keyof typeof shape].safeParse(merged[section]);const shapeIssues = findShapeIssues(schema, merged[section], []);const schemaIssues = result.success ? [] : expandUnionIssues(result.error.issues);- const located: Array<{ issue: ShapeIssue | SchemaIssue; params: boolean }> = [- ...shapeIssues.map((issue) => ({ issue, params: false })),- ...schemaIssues.map((issue) => ({ issue, params: true })),- ];- for (const { issue, params } of located) {- if (issue.code === 'unrecognized_keys') {- continue;- }- const issuePath: IssuePath = [section, ...issue.path];- const segments = attributeIssue(overrides, merged, issuePath);- if (- !segments ||- (segments.length < issuePath.length && !isReplacedArrayNode(overrides, segments))- ) {- continue;- }- const path = segments.join('.');- if (seen.has(path)) {- continue;+ 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, ...issue.path], issue.code, issue);}- seen.add(path);- const exact = params && segments.length === issuePath.length;- issues.push(- toIssue(- segments,- issue.code,- exact ? getConfigIssueParams(issue as SchemaIssue) : undefined,- ),- );+ }+ }+ /** 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;@@ -1156,7 +1240,7 @@ export function applyConfigTombstones(): Partial<TCustomConfig> {return (tombstones ?? []).filter((path): path is string => typeof path === 'string' && !cleared.has(path))- .flatMap(getTombstoneRemovals)+ .flatMap((path) => getTombstoneRemovals(path, true)).reduce((current, path) => deletePath(current, path), base as AnyObject);}@@ -1246,6 +1330,7 @@ export function getConfigChangeIssues(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);@@ -1253,11 +1338,13 @@ export function getConfigChangeIssues(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) =>!existing.has(getIssueLocation(issue.segments, candidateState.overrides)) ||@@ -1289,6 +1376,7 @@ export function getConfigFieldIssues(base: Partial<TCustomConfig> = {},stored?: { overrides?: unknown; tombstones?: unknown[] } | null,renames: readonly ConfigEntryRename[] = [],+ derivation: ConfigDerivation = {},): ConfigOverrideIssue[] {const writes: readonly ConfigFieldWrite[] = Array.isArray(fields)? fields@@ -1311,6 +1399,7 @@ export function getConfigFieldIssues(stored,written,getLiftedConfigTombstones(written),+ derivation,);}@@ -1365,17 +1454,22 @@ function omitPath(target: unknown, segments: string[]): unknown {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 = getConfigOverrideIssues(stripped, base);+ const issues = getIssues();if (issues.length === 0) {return stripped as AnyObject;}@@ -1408,7 +1502,7 @@ function stripInvalidOverrides(}}const failing = new Map<string, string>();- for (const issue of getConfigOverrideIssues(stripped, base)) {+ for (const issue of getIssues()) {if (!failing.has(issue.segments[0])) {failing.set(issue.segments[0], issue.code);}@@ -1492,14 +1586,15 @@ export interface ConfigMergeStep {/** The merged config with this layer applied. */merged: AppConfig;/**- * The base config with only this layer applied (its tombstones, then its overrides; its Azure- * `groups` replacing what librechat.yaml's resolved to), as if no other layer were below it.- * Computed on first call.+ * 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 {+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,@@ -1530,7 +1625,7 @@ interface FoldStep<T> {merged: T;/*** What the layer removed before its overrides landed, as AppConfig paths: its tombstones that- * applied, and the resolved Azure fields its `groups` replace.+ * applied (a tombstone of Azure `groups` with every field they resolve to).*/removed: readonly string[];}@@ -1679,46 +1774,115 @@ function withAcceptedSections(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;+}+/**- * A layer's `endpoints` override with its Azure `groups` resolved as AppService resolves- * librechat.yaml's (`resolveAzureGroups`): the Azure clients read `groupMap`, `modelGroupMap` and- * the model lists resolved with them, never `groups`. The layer's groups replace the groups below- * whole, as its `groups` array does in the YAML-shaped config, so what they resolve to replaces- * what those resolved to (the caller removes that first); a resolved field the same layer also- * writes directly merges over its own groups' (objects) or replaces it. `null` when the layer- * writes no groups, or groups that do not resolve, which then stay unread, with a warning.+ * 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.+ * - `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(- endpoints: unknown,- config: ConfigOverrideLayer,- sink?: LayerIgnoredSink,-): AnyObject | null {- if (!isPlainObject(endpoints)) {- return null;- }- const azure = endpoints[EModelEndpoint.azureOpenAI];- if (!isPlainObject(azure) || !Array.isArray(azure.groups)) {- return null;- }- const resolved = resolveAzureGroups(azure.groups);+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_CONFIG_PATH}.groups for ${describePrincipal(config)}: ${resolved.errors.join('; ')}`,+ `[mergeConfigOverrides] Ignoring ${AZURE_GROUPS_PATH} for ${describePrincipal(config)}: ${resolved.errors.join('; ')}`,);}return null;}- const next: AnyObject = { ...azure };+ 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;+ }+ const inherited = isPlainObject(belowMap[name]) ? belowMap[name].apiKey : undefined;+ groupMap[name] =+ suppliesGroupKey(item) || inherited === undefined ? 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);+ if (!suppliesGroupKey(own)) {+ delete entry.apiKey;+ delete entry.apiKeyPreview;+ delete entry.apiKeyBinding;+ }+ alone[name] = 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 = azure[field];- const derived: unknown = resolved[field];+ const own = layerAzure[field];+ const value = derived[field];next[field] =- isPlainObject(own) && isPlainObject(derived) ? deepMerge(derived, own) : (own ?? derived);+ isPlainObject(own) && isPlainObject(value) ? deepMerge(value, own) : (own ?? value);}- return { ...endpoints, [EModelEndpoint.azureOpenAI]: next };+ return {+ served: next,+ contributed: {+ ...layerAzure,+ groupMap: isPlainObject(ownMap) ? deepMerge(alone, ownMap) : alone,+ },+ };}/**@@ -1729,7 +1893,10 @@ function resolveLayerAzureGroups(* 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.+ * 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,@@ -1741,7 +1908,13 @@ function withServedAzureModels<T extends AppConfig>(return merged;}const principals = configs.map(describePrincipal).join(', ');- const { config: served, narrowed } = narrowAzureServedModels(azure);+ 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`,@@ -1753,7 +1926,7 @@ function withServedAzureModels<T extends AppConfig>(`[mergeConfigOverrides] Turning off ${AZURE_CONFIG_PATH}.assistants for ${principals}: none of the Azure models they serve supports assistants`,);}- if (narrowed.length === 0 && !assistantsOff) {+ if (completed.length === 0 && narrowed.length === 0 && !assistantsOff) {return merged;}return {@@ -1765,6 +1938,108 @@ function withServedAzureModels<T extends AppConfig>(};}+/** 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 = isKeyedConfigPath(path) ? readConfigEntryTombstone(path) : null;+ if (entry == null || entry.segments.join('.') !== AZURE_GROUPS_PATH) {+ continue;+ }+ (entry.entry.rest.length === 0 ? hidden : touched).add(entry.identity);+ }+ return { hidden, touched };+}++/** The key fields of a `groupMap` entry, which travel together. */+const AZURE_GROUP_KEY_FIELDS = ['apiKey', 'apiKeyPreview', 'apiKeyBinding'] as const;++/**+ * `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, with a warning; where none+ * is left, no group is served (`withoutAzureGroups`).+ */+function withHiddenAzureGroups<T extends AnyObject>(+ merged: T,+ raw: Partial<TCustomConfig>,+ tombstones: readonly string[],+ config: ConfigOverrideLayer,+): T {+ const { hidden, touched } = getAzureGroupTombstones(tombstones);+ const azureSegments = AZURE_CONFIG_PATH.split('.');+ const azure = getPath(merged, azureSegments);+ if ((hidden.size === 0 && touched.size === 0) || !isPlainObject(azure)) {+ return merged;+ }+ const kept = getPath(raw, AZURE_GROUPS_PATH.split('.'));+ let groups = Array.isArray(kept) ? kept.filter(isPlainObject) : [];+ let resolved = resolveServedAzureGroups(groups, touched);+ if (!resolved.isValid) {+ 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 (groups.length === 0 || !resolved.isValid) {+ return withoutAzureGroups(merged);+ }+ 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;+ }+ return setPath(merged, azureSegments, {+ ...azure,+ groupMap,+ modelGroupMap: resolved.modelGroupMap,+ modelNames: resolved.modelNames,+ assistantModels: resolved.assistantModels,+ assistantGroups: resolved.assistantGroups,+ }) as T;+}++/** 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. */@@ -1919,28 +2194,44 @@ interface FoldObservers {* `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` resolve into the fields the Azure clients read (`resolveLayerAzureGroups`).+ * `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;+ * without it, those overrides stay inert in `merged`, as before the merge derived them. 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. `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`).+ * 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 = {},-): { merged: T; raw: Partial<TCustomConfig>; webSearchWriters: WebSearchWriters } {+): 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));@@ -1949,6 +2240,8 @@ function foldConfigLayers<T extends AnyObject>(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 };@@ -1970,10 +2263,16 @@ function foldConfigLayers<T extends AnyObject>();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);}- for (const removedPath of getTombstoneRemovals(path)) {+ tombstoned.push(path);+ for (const removedPath of getTombstoneRemovals(path, resolvesAzureGroups)) {const mappedPath = remapOverridePath(removedPath);removed.push(mappedPath);merged = deleteConfigPath(merged, mappedPath);@@ -1982,22 +2281,24 @@ function foldConfigLayers<T extends AnyObject>(tracker.resolved = deleteConfigPath(tracker.resolved, mappedPath);}}- if (path === AZURE_GROUPS_PATH) {+ if (resolvesAzureGroups && path === AZURE_GROUPS_PATH) {merged = withoutAzureGroups(merged);}track?.tombstoned.push(path);recordWebSearchTombstone(webSearchWriters, path, removal);}+ if (resolvesAzureGroups) {+ merged = withHiddenAzureGroups(merged, raw, tombstoned, config);+ }}if (config.overrides && typeof config.overrides === 'object') {const remapped: AnyObject = {};const applied: AnyObject = {};- let replacesAzureGroups = false;- let writtenEndpoints: unknown;const valid = stripInvalidOverrides(config,raw,+ derivation,layerSink,track &&((issue) =>@@ -2005,7 +2306,17 @@ function foldConfigLayers<T extends AnyObject>(toLayerIgnored(issue.segments, 'invalid_override', { code: issue.code }),)),);- for (const [key, value] of Object.entries(valid)) {+ 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'));@@ -2077,29 +2388,12 @@ function foldConfigLayers<T extends AnyObject>(for (const segments of track ? getInterfacePermissionRemovals(value as AnyObject) : []) {track?.ignored.push(toLayerIgnored(segments, 'interface_permission'));}- } else if (key === 'endpoints') {- const resolved = resolveLayerAzureGroups(value, config, layerSink);- remapped[mappedKey] = resolved ?? value;- replacesAzureGroups = resolved != null;- writtenEndpoints = value;- if (track && resolved == null && hasAzureGroups(value)) {- track.ignored.push(- toLayerIgnored(AZURE_GROUPS_PATH.split('.'), 'azure_groups_unresolved'),- );- }} else {remapped[mappedKey] = value;}}- if (replacesAzureGroups) {- for (const path of AZURE_RESOLVED_PATHS) {- merged = deletePath(merged, path);- removed.push(path);- if (tracker) {- tracker.resolved = deletePath(tracker.resolved, path);- }- }- }+ const beforeOverrides = merged;+ const rawBelow = raw;if (layerSink) {for (const held of YAML_HELD_PATHS) {if (getPath(applied, [...held.segments]) !== undefined) {@@ -2115,24 +2409,84 @@ function foldConfigLayers<T extends AnyObject>(removed: false,});contributed = remapped;+ appliedOverrides = applied;if (tracker && track) {- track.contributed =- writtenEndpoints === undefined ? remapped : { ...remapped, endpoints: writtenEndpoints };+ track.contributed = remapped;tracker.resolved = deepMerge(tracker.resolved, track.contributed);}+ const layerAzure = getPath(applied, AZURE_CONFIG_PATH.split('.'));+ if (resolvesAzureGroups && isPlainObject(layerAzure) && Array.isArray(layerAzure.groups)) {+ const azureSegments = AZURE_CONFIG_PATH.split('.');+ const groupsSegments = AZURE_GROUPS_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(AZURE_GROUPS_PATH.split('.'), '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 };+ return { merged, raw, webSearchWriters, touches };}-/** Whether an `endpoints` override writes Azure `groups`. */-function hasAzureGroups(endpoints: unknown): boolean {- const azure = isPlainObject(endpoints) ? endpoints[EModelEndpoint.azureOpenAI] : undefined;- return isPlainObject(azure) && Array.isArray(azure.groups);+/** 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. */@@ -2145,6 +2499,11 @@ export interface ConfigLayerResolution {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. */@@ -2271,17 +2630,18 @@ function isSameJson(a: unknown, b: unknown): boolean {}/**- * The merge {@link mergeConfigOverrides} 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.+ * 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,-): AppConfig {- const { afterLayer } = options;+): ConfigMergeResult {+ const { afterLayer, expandCustomEndpoint, rederiveEndpoints } = options;+ const derivation: ConfigDerivation = { expandCustomEndpoint, rederiveEndpoints };const folded = foldConfigLayers({ ...baseConfig },baseConfig.config ?? {},@@ -2304,12 +2664,21 @@ function mergeLayers(},});}),+ 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@@ -2318,7 +2687,7 @@ function mergeLayers(options.onWebSearchKeyUnbound?.(binding);}: undefined;- const bound = bindWebSearchKeys(served, folded.webSearchWriters, onUnbound);+ const bound = bindWebSearchKeys(derived, folded.webSearchWriters, onUnbound);if (tracker) {for (const { layer, apiKey } of unbound) {setResolved(tracker, ['webSearch', apiKey], bound.webSearch?.[apiKey]);@@ -2329,7 +2698,10 @@ function mergeLayers(replayRuntimeStops(tracker, baseConfig);replayBaseOnlyPaths(tracker, baseConfig.config ?? {});}- return preserveBaseOnlyPaths(baseConfig, preserveRuntimeStops(baseConfig, bound));+ return {+ appConfig: preserveBaseOnlyPaths(baseConfig, preserveRuntimeStops(baseConfig, bound)),+ raw: folded.raw,+ };}/**@@ -2340,15 +2712,31 @@ function mergeLayers(* 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`).+ * 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 baseConfig;+ return { appConfig: baseConfig, raw: baseConfig.config ?? {} };}return mergeLayers(baseConfig, configs, options);}@@ -2363,8 +2751,11 @@ export function mergeConfigOverrides(* 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`), and- * the `afterLayer` policy a caller adds (the admin API replays its secret rebinding itself).+ * 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,@@ -2376,11 +2767,17 @@ export function resolveConfigLayers(layers: [],};if (!configs || configs.length === 0) {- return { merged: baseConfig, resolved: toOverrideKeys(tracker.resolved), layers: [] };- }- const merged = mergeLayers(baseConfig, configs, options, tracker);+ 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 })),};@@ -2396,12 +2793,19 @@ export function resolveConfigLayers(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).raw;+ return foldConfigLayers(+ { mcpConfig: baseYaml.mcpServers ?? null },+ baseYaml,+ configs,+ undefined,+ derivation,+ ).raw;}/**@@ -2412,14 +2816,16 @@ export function resolveRawConfig(* 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). Each location is listed once per reason and kind; nothing about a value- * is returned.+ * 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(@@ -2427,6 +2833,7 @@ export function getIgnoredConfigOverrides(baseYaml,[...below, layer],undefined,+ derivation,{sink: (source, entry) => {const key = JSON.stringify([entry.kind, entry.reason, entry.segments]);diff --git a/packages/data-schemas/src/app/service.spec.ts b/packages/data-schemas/src/app/service.spec.tsindex fa7250a86d..1021cd7d80 100644--- a/packages/data-schemas/src/app/service.spec.ts+++ b/packages/data-schemas/src/app/service.spec.ts@@ -432,3 +432,42 @@ describe('AppService memory capability', () => {);});});++describe('AppService custom endpoint parameters', () => {+ const gateway = {+ name: 'Gateway',+ apiKey: 'gateway-key',+ baseURL: 'https://gateway.example.com/v1',+ models: { default: ['m1'] },+ customParams: {+ defaultParamsEndpoint: 'anthropic',+ paramDefinitions: [{ key: 'temperature' }],+ },+ };+ const config = { endpoints: { custom: [gateway] } } as DeepPartial<TCustomConfig>;++ it('serves the custom endpoints as librechat.yaml writes them without an expander', async () => {+ const appConfig = await AppService({ config: structuredClone(config) });++ expect(appConfig.endpoints?.custom).toEqual([gateway]);+ expect(appConfig.config.endpoints?.custom).toEqual([gateway]);+ });++ it('serves expanded copies and keeps the config as librechat.yaml writes it', async () => {+ const written = structuredClone(config);+ const appConfig = await AppService({+ config: written,+ expandCustomEndpoint: (endpoint) => ({+ ...endpoint,+ customParams: { defaultParamsEndpoint: 'anthropic', paramDefinitions: [] },+ }),+ });++ expect(appConfig.endpoints?.custom?.[0]?.customParams).toEqual({+ defaultParamsEndpoint: 'anthropic',+ paramDefinitions: [],+ });+ expect(appConfig.config.endpoints?.custom?.[0]).toEqual(gateway);+ expect(written.endpoints?.custom?.[0]).toEqual(gateway);+ });+});diff --git a/packages/data-schemas/src/app/service.ts b/packages/data-schemas/src/app/service.tsindex 655e50d0dc..160c9cdd1e 100644--- a/packages/data-schemas/src/app/service.ts+++ b/packages/data-schemas/src/app/service.ts@@ -19,6 +19,7 @@ import type {TAgentsEndpoint,} from 'librechat-data-provider';import type { AppConfig, FunctionTool } from '~/types/app';+import type { ConfigDerivation } from './derive';import { loadMemoryConfig, isMemoryEnabled } from './memory';import { loadDefaultInterface } from './interface';import { loadTurnstileConfig } from './turnstile';@@ -156,8 +157,13 @@ export const AppService = async (params?: {config: DeepPartial<TCustomConfig>;paths?: Paths;systemTools?: Record<string, FunctionTool>;+ /**+ * Expands each custom endpoint's `customParams` for the served `endpoints.custom`; `config`+ * keeps them as librechat.yaml writes them.+ */+ expandCustomEndpoint?: ConfigDerivation['expandCustomEndpoint'];}): Promise<AppConfig> => {- const { config, paths, systemTools } = params || {};+ const { config, paths, systemTools, expandCustomEndpoint } = params || {};if (!config) {throw new Error('Config is required');}@@ -273,7 +279,7 @@ export const AppService = async (params?: {return appConfig;}- const loadedEndpoints = loadEndpoints(config, agentsDefaults);+ const loadedEndpoints = loadEndpoints(config, agentsDefaults, expandCustomEndpoint);stripInertMemoryCapability(loadedEndpoints[EModelEndpoint.agents]);const appConfig: AppConfig = {diff --git a/packages/data-schemas/src/app/vertex.spec.ts b/packages/data-schemas/src/app/vertex.spec.tsindex 211cb79be3..a09544e0bf 100644--- a/packages/data-schemas/src/app/vertex.spec.ts+++ b/packages/data-schemas/src/app/vertex.spec.ts@@ -1,4 +1,5 @@-import { vertexAISchema } from 'librechat-data-provider';+import { vertexAISchema, getVertexDeploymentName } from 'librechat-data-provider';+import type { TVertexAISchema } from 'librechat-data-provider';import { defaultVertexModels, validateVertexConfig } from './vertex';describe('defaultVertexModels', () => {@@ -88,3 +89,125 @@ describe('validateVertexConfig region gating', () => {expect(config?.modelNames).toEqual(['claude-opus-5', 'claude-sonnet-4-6']);});});++describe('validateVertexConfig values that would leave their place in the request', () => {+ /** Starts with `${` and ends with `}`, so it reads as one reference to a greedy pattern. */+ const WRAPPED = '${VERTEX_TEST_PROJECT}/../../endpoints/5678:rawPredict#${VERTEX_TEST_PROJECT}';++ beforeEach(() => {+ process.env.VERTEX_TEST_PROJECT = 'test-project';+ });++ afterEach(() => {+ delete process.env.VERTEX_TEST_REGION;+ delete process.env.VERTEX_TEST_PROJECT;+ delete process.env.VERTEX_TEST_DEPLOYMENT;+ });++ it('refuses a deployment or model name that only wraps ${VAR} references', () => {+ const settings: Array<Partial<TVertexAISchema>> = [+ { models: { 'claude-sonnet-4-6': { deploymentName: WRAPPED } } },+ { models: [WRAPPED] },+ { models: { [WRAPPED]: true } },+ { deploymentName: WRAPPED },+ ];+ for (const vertex of settings) {+ expect(validateVertexConfig({ region: 'us-east5', ...vertex })?.isValid).toBe(false);+ }+ });++ it('refuses a model name its requests send as written, whatever the default deployment', () => {+ const settings: Array<Partial<TVertexAISchema>> = [+ { deploymentName: 'claude-sonnet-4-6', models: ['../../endpoints/5678:rawPredict#'] },+ { deploymentName: 'claude-sonnet-4-6', models: { '../x#': false } },+ { models: { 'Claude Team': true } },+ ];+ for (const vertex of settings) {+ expect(validateVertexConfig({ region: 'us-east5', ...vertex })?.isValid).toBe(false);+ }+ expect(+ validateVertexConfig({+ region: 'us-east5',+ deploymentName: 'claude-sonnet-4-6',+ models: { 'Claude Team': true, 'Claude Opus': { deploymentName: 'claude-opus-4-6' } },+ })?.isValid,+ ).toBe(true);+ });++ it("resolves each model's own deployment name, as requests send it", () => {+ process.env.VERTEX_TEST_DEPLOYMENT = 'claude-sonnet-4-6@20250929';+ const config = validateVertexConfig({+ region: 'us-east5',+ models: { team: { deploymentName: '${VERTEX_TEST_DEPLOYMENT}' } },+ });++ expect(config?.isValid).toBe(true);+ expect(config?.modelDeploymentMap).toEqual({ team: 'claude-sonnet-4-6@20250929' });+ expect(getVertexDeploymentName('team', config ?? undefined)).toBe('claude-sonnet-4-6@20250929');++ delete process.env.VERTEX_TEST_DEPLOYMENT;+ expect(+ validateVertexConfig({+ region: 'us-east5',+ models: { team: { deploymentName: '${VERTEX_TEST_DEPLOYMENT}' } },+ })?.errors,+ ).toEqual(['Vertex AI deployment name environment variable for model "team" was not found.']);+ });++ it('refuses a region, project ID or deployment name that is not one host label or path segment', () => {+ const settings: Array<Partial<TVertexAISchema>> = [+ { region: 'evil.example.com/x#' },+ { projectId: '../other-project' },+ { deploymentName: 'claude/../../x' },+ { models: { 'claude-sonnet-4-6': { deploymentName: 'a?b' } } },+ ];+ for (const vertex of settings) {+ expect(validateVertexConfig({ region: 'us-east5', ...vertex })?.isValid).toBe(false);+ }+ });++ it('accepts the forms Vertex AI uses, and checks a ${VAR} once resolved', () => {+ expect(+ validateVertexConfig({+ region: 'europe-west1',+ projectId: 'example.com:my-project',+ models: { 'claude-sonnet-4-6': { deploymentName: 'claude-sonnet-4-6@20250929' } },+ })?.isValid,+ ).toBe(true);++ process.env.VERTEX_TEST_REGION = 'us-east5';+ expect(validateVertexConfig({ region: '${VERTEX_TEST_REGION}' })?.isValid).toBe(true);+ process.env.VERTEX_TEST_REGION = 'evil.example.com/';+ expect(validateVertexConfig({ region: '${VERTEX_TEST_REGION}' })?.isValid).toBe(false);+ });+});++describe('vertexAISchema', () => {+ it('takes a ${VAR} or a valid value for the settings that build the request URL', () => {+ expect(vertexAISchema.safeParse({ region: '${VERTEX_REGION}', projectId: 'p-1' }).success).toBe(+ true,+ );+ expect(vertexAISchema.safeParse({ region: 'us-east5/../x' }).success).toBe(false);+ expect(vertexAISchema.safeParse({ projectId: 'a/b' }).success).toBe(false);+ expect(vertexAISchema.safeParse({ deploymentName: '..' }).success).toBe(false);+ expect(vertexAISchema.safeParse({ models: { m: { deploymentName: 'x#y' } } }).success).toBe(+ false,+ );+ });++ it('takes only a whole reference to one variable as a ${VAR}', () => {+ const wrapped = '${GCP_PROJECT}/../../endpoints/5678:rawPredict#${GCP_PROJECT}';+ for (const vertex of [+ { projectId: wrapped },+ { deploymentName: wrapped },+ { region: '${GCP_REGION}.example.com/#${GCP_REGION}' },+ { models: { m: { deploymentName: wrapped } } },+ { models: { m: { deploymentName: '${GCP/../x}' } } },+ ]) {+ expect(vertexAISchema.safeParse(vertex).success).toBe(false);+ }+ expect(+ vertexAISchema.safeParse({ models: { m: { deploymentName: '${GCP_DEPLOYMENT}' } } }).success,+ ).toBe(true);+ });+});diff --git a/packages/data-schemas/src/app/vertex.ts b/packages/data-schemas/src/app/vertex.tsindex e0df779a4c..650013904e 100644--- a/packages/data-schemas/src/app/vertex.ts+++ b/packages/data-schemas/src/app/vertex.ts@@ -3,6 +3,10 @@ import {extractEnvVariable,envVarRegex,TVertexModelMap,+ VERTEX_REGION_PATTERN,+ getVertexDeploymentName,+ ENV_VAR_REFERENCE_PATTERN,+ VERTEX_PATH_SEGMENT_PATTERN,} from 'librechat-data-provider';import type {TCustomConfig,@@ -113,6 +117,81 @@ function processVertexModels(return { modelNames, modelDeploymentMap };}+/**+ * `models` with each entry's own `deploymentName` resolved, as the default one is, and the models+ * whose `${VAR}` there is not set.+ */+function resolveModelDeploymentNames(models: TVertexAISchema['models']): {+ models: TVertexAISchema['models'];+ unresolved: string[];+} {+ const unresolved: string[] = [];+ if (models == null || Array.isArray(models)) {+ return { models, unresolved };+ }+ const resolved: Record<string, TVertexModelConfig> = {};+ for (const [modelName, modelConfig] of Object.entries(models)) {+ if (modelConfig == null || typeof modelConfig !== 'object' || !modelConfig.deploymentName) {+ resolved[modelName] = modelConfig;+ continue;+ }+ const deploymentName = extractEnvVariable(modelConfig.deploymentName);+ if (envVarRegex.test(deploymentName)) {+ unresolved.push(modelName);+ }+ resolved[modelName] = { ...modelConfig, deploymentName };+ }+ return { models: resolved, unresolved };+}++/**+ * The resolved settings that would leave their place in the Vertex AI request: the region is+ * part of the API host, and the project ID and the deployment name each model's requests send+ * ({@link getVertexDeploymentName}) one segment of its path. A configured value still holding a+ * whole `${VAR}` is reported as unresolved on its own; a model name is sent as written, never+ * resolved, so it must be a segment itself.+ */+function getVertexValueErrors({+ region,+ projectId,+ deploymentName: defaultDeploymentName,+ models,+ modelNames,+}: {+ region: string;+ projectId?: string;+ deploymentName?: string;+ models: TVertexAISchema['models'];+ modelNames: string[];+}): string[] {+ const errors: string[] = [];+ const isSegment = (value: string) =>+ ENV_VAR_REFERENCE_PATTERN.test(value) || VERTEX_PATH_SEGMENT_PATTERN.test(value);+ if (!ENV_VAR_REFERENCE_PATTERN.test(region) && !VERTEX_REGION_PATTERN.test(region)) {+ errors.push('Vertex AI region may contain only letters, digits and hyphens.');+ }+ if (projectId && !isSegment(projectId)) {+ errors.push('Vertex AI projectId is not a valid project ID.');+ }+ if (defaultDeploymentName && !isSegment(defaultDeploymentName)) {+ errors.push('Vertex AI deploymentName is not a valid deployment name.');+ }+ for (const modelName of modelNames) {+ const deploymentName = getVertexDeploymentName(modelName, {+ models,+ deploymentName: defaultDeploymentName,+ });+ const isValid =+ deploymentName === modelName+ ? VERTEX_PATH_SEGMENT_PATTERN.test(modelName)+ : isSegment(deploymentName);+ if (!isValid) {+ errors.push(`Vertex AI deployment name for model "${modelName}" is not valid.`);+ }+ }+ return errors;+}+/*** Validates and processes Vertex AI configuration* @param vertexConfig - The Vertex AI configuration object@@ -161,13 +240,30 @@ export function validateVertexConfig();}+ const { models, unresolved } = resolveModelDeploymentNames(vertexConfig.models);+ for (const modelName of unresolved) {+ errors.push(+ `Vertex AI deployment name environment variable for model "${modelName}" was not found.`,+ );+ }+// Process models and create deployment mappingconst { modelNames, modelDeploymentMap } = processVertexModels(- vertexConfig.models,+ models,defaultDeploymentName,region,);+ errors.push(+ ...getVertexValueErrors({+ region,+ projectId,+ deploymentName: defaultDeploymentName,+ models,+ modelNames,+ }),+ );+// Note: projectId is optional - if not provided, it will be auto-detected from the service key fileconst isValid = errors.length === 0;@@ -178,7 +274,7 @@ export function validateVertexConfig(region,serviceKeyFile,deploymentName: defaultDeploymentName,- models: vertexConfig.models,+ models,modelNames,modelDeploymentMap,isValid,diff --git a/packages/data-schemas/src/types/admin.ts b/packages/data-schemas/src/types/admin.tsindex 3980398006..5d7ffb5dec 100644--- a/packages/data-schemas/src/types/admin.ts+++ b/packages/data-schemas/src/types/admin.ts@@ -377,9 +377,13 @@ export type AdminConfigChangesRequest = AdminConfigWritePrecondition & {* for an MCP server `librechat.yaml` runs as a local process, whose configuration overrides* never change. A write to a path inside such a server is refused instead (400* `PROCESS_MCP_SERVER_OVERRIDE`).+ * - `derived_path`: a field the server derives from another one (`rules.derivedPaths`:+ * `endpoints.anthropic.vertexConfig`, from `endpoints.anthropic.vertex`), which the merge never+ * applies from an override. A `set` or `tombstone` there is skipped; an `unset` clears a value+ * an older server stored.** Removing a stored value (DELETE `/fields`, an `unset` change) is cleanup and is never skipped- * for `base_only_path`, `deployment_only_path` or `process_mcp_server`.+ * for `base_only_path`, `deployment_only_path`, `process_mcp_server` or `derived_path`.*/export type AdminConfigSkipReason =| 'base_only_section'@@ -387,7 +391,8 @@ export type AdminConfigSkipReason =| 'deployment_only_path'| 'dedicated_section'| 'interface_permission'- | 'process_mcp_server';+ | 'process_mcp_server'+ | 'derived_path';/*** Why a stored override, tombstone, change or part of one (at its own `segments`) has no effect@@ -403,7 +408,7 @@ export type AdminConfigSkipReason =* - `invalid`: a value that fails validation where the merge applies it, so the value beneath* stays (stored before validation existed, or valid only over other layers).* - `unknown_section`: a top-level key `configSchema` does not define (`sectionAllowlist`).- * - `base_only_section`, `dedicated_section`, `interface_permission`: as in+ * - `base_only_section`, `dedicated_section`, `interface_permission`, `derived_path`: as in* {@link AdminConfigSkipReason}, for a value or tombstone already stored.*/export type AdminConfigIgnoreReason =@@ -414,7 +419,8 @@ export type AdminConfigIgnoreReason =| 'unknown_section'| 'base_only_section'| 'dedicated_section'- | 'interface_permission';+ | 'interface_permission'+ | 'derived_path';/*** A credential the runtime merge leaves out of a document's layer, or a destination it sets back,@@ -522,6 +528,8 @@ export type AdminConfigChangeErrorResponse = {* - `invalid_theme`: an `interface.theme` the client would reject; `librechat.yaml`'s applies.* - `tenant_hidden`: a custom endpoint `librechat.yaml` scopes to another tenant, or a model* spec that uses one.+ * - `derived_path`: a field the server derives from another one (`rules.derivedPaths`), which the+ * merge never applies from a layer, value or tombstone.*/export type AdminConfigLayerIgnoreReason =| 'unknown_section'@@ -539,7 +547,8 @@ export type AdminConfigLayerIgnoreReason =| 'destination_restored'| 'env_reference_not_allowed'| 'invalid_theme'- | 'tenant_hidden';+ | 'tenant_hidden'+ | 'derived_path';/*** Part of a layer the merge does not apply as written. `segments` locate it in librechat.yaml@@ -816,12 +825,14 @@ export type AdminConfigEnvStatusResponse = {* rule (`secretRebinding`) applies to those.* - `azureGroupSecrets`: `endpoints.azureOpenAI.groups[].apiKey` is stored encrypted with* `apiKeyPreview`, matched across writes by `group` (omit it to keep it), left out of reads- * and decrypted for the Azure clients, which use it: the merge resolves a profile's `groups`- * as AppService resolves librechat.yaml's, into the `groupMap`, `modelGroupMap`, model list- * and assistant models the clients read. A profile's `groups` replace the groups below whole,- * as its array does, and a tombstone of `groups` removes everything they resolve to; groups- * that do not resolve (a duplicate group or model, a model without a deployment or version)- * stay unread, with a warning. The merged model lists name only models a merged group serves:+ * and decrypted for the Azure clients, which use it where the merge resolves a profile's+ * `groups` (`endpointRederive`, `CONFIG_REDERIVE_ENDPOINTS=true`): as AppService resolves+ * librechat.yaml's, into the `groupMap`, `modelGroupMap`, model list and assistant models the+ * clients read. Without it, a profile's `groups` and a tombstone of them are stored but inert.+ * A profile's `groups` merge by `group` over the groups below (`azureGroupMergeKey`), and a+ * tombstone of `groups` removes everything they resolve to; groups that do not resolve (a+ * duplicate group or model, a model without a deployment or version) stay unread, with a+ * warning. The merged model lists name only models a merged group serves:* a `modelNames`, `assistantModels` or `assistantGroups` an override writes directly is* narrowed to them, with a warning. When none of the models the merge leaves supports* assistants, `assistants` is off for that profile, with a warning, rather than on without a@@ -858,10 +869,13 @@ export type AdminConfigEnvStatusResponse = {* search and Langfuse keys, which are stored encrypted and sent as entered, so a `${...}`* inside one is part of the key (a whole `${VAR}` reference there is still checked). Custom* endpoint, Azure group and MCP credentials are expanded by their clients once decrypted and- * stay checked. At runtime an unlisted reference in a stored override resolves to nothing. The- * allowlist decides which names a value may reference, not where the value is sent: an allowed- * name may appear in any value, a URL, a header or a key beside a host of the writer's- * choosing.+ * stay checked. Vertex AI's settings (`endpoints.anthropic.vertex`) are narrower: the merge+ * resolves them into the `vertexConfig` reads return (`endpointRederive`), so they may+ * reference only the names librechat.yaml's own Vertex AI settings reference (those of its key+ * file only in `serviceKeyFile`), whatever else the allowlist holds. At runtime an unlisted+ * reference in a stored override resolves to nothing. The allowlist decides which names a+ * value may reference, not where the value is sent: an allowed name may appear in any value, a+ * URL, a header or a key beside a host of the writer's choosing.* - `secretRebinding`: the merge drops a credential a layer would send somewhere it was not* entered for: an inherited one whose destination the layer changes without entering it again,* or the layer's own one whose destination a layer below changed (MCP servers, custom@@ -990,6 +1004,65 @@ export type AdminConfigEnvStatusResponse = {* `target_not_written`, `source_still_written` (the write keeps `previousName`; swap names with* `/changes` `rename` ops), `duplicate_source` (two hints rename one entry), `duplicate_target`* or `invalid_name`. A `/changes` `rename` of a custom endpoint moves its keyed tombstones too.+ * - `azureGroupMergeKey`: `endpoints.azureOpenAI.groups` merges by `group`+ * (`rules.arrayMergeKeys`), as `endpoints.custom` merges by `name`: a profile's group merges+ * over the group of that name below it (its models by name), a new one is added, and groups it+ * does not name stay. Every item needs a unique `group` (`missing_merge_key`,+ * `duplicate_merge_key`); a write addressing an item by index answers 400+ * `indexed_merge_key_write`; `/changes` takes `upsertEntry`, `removeEntry` and `rename` on+ * `endpoints.azureOpenAI.groups`, and a keyed path (`keyedTombstones`) names a group by its+ * `group`: `endpoints.azureOpenAI.groups["name"]` hides an inherited group, or a path inside it,+ * and the merge resolves the groups left again (with `endpointRederive`; a group that no longer+ * resolves once a path inside it is hidden is not served). To replace librechat.yaml's groups,+ * tombstone `groups` and write the profile's own. A write whose groups, merged that way over librechat.yaml and Base,+ * do not resolve (a duplicate model, a model without a deployment name or version, a group+ * without its instance, or a written group's `${VAR}` that is not set) answers 400+ * `CONFIG_OVERRIDE_INVALID` with `invalid_azure_groups` at `endpoints.azureOpenAI.groups`;+ * stored groups that do not resolve are left out of the merge, with a warning. Writes are+ * checked this way whether or not the groups apply yet: the merge serves them only with+ * `endpointRederive`.+ * - `customParamsExpansion`: a custom endpoint's `customParams` are expanded for the runtime+ * from its librechat.yaml form, for librechat.yaml and every profile that writes the endpoint:+ * compact `paramDefinitions` (`{ key, default }`) get the defaults of `defaultParamsEndpoint`,+ * a changed `defaultParamsEndpoint` picks the new endpoint's, and an endpoint named for or+ * pointing at OpenRouter gets OpenRouter's defaults, a profile's own included. GET `/base`+ * returns librechat.yaml's `config` as written (compact), and `endpoints.custom` expanded.+ * Definitions startup would refuse (an unknown key or `defaultParamsEndpoint`, malformed+ * settings) answer 400 `CONFIG_OVERRIDE_INVALID` with `invalid_param_definitions` at the+ * endpoint's `customParams`; stored ones are left out of the merge, with a warning.+ * - `specInterfaceRederive`: the interface controls model specs decide (`modelSelect`,+ * `parameters`, `presets`) follow the model specs a principal is served, where neither+ * librechat.yaml nor a profile sets them: a profile that adds specs turns them off (the model+ * selector stays on with `addedEndpoints`), and one that removes every spec (a tombstone, an+ * empty list, or tenant scoping) turns them back on. A model spec whose endpoint the layers+ * leave unconfigured (a tombstone of `endpoints.custom` or `endpoints` removing the custom+ * endpoint it names) is not served, as startup skips librechat.yaml's, until a layer defines the+ * endpoint again; built-in endpoints keep their specs. A profile that turns `memory` on or off,+ * or changes the agents endpoint, has the agents `memory` capability derived again, so it is+ * offered only while memory is on. A model spec whose `preset.endpoint` is neither a built-in+ * endpoint nor a configured custom endpoint answers 400 `CONFIG_OVERRIDE_INVALID` with+ * `unknown_spec_endpoint` at that field.+ * - `endpointRederive`: on only where the deployment sets `CONFIG_REDERIVE_ENDPOINTS=true` (off+ * by default for one release; it becomes the default after). Then a profile's Azure `groups`+ * resolve into what the Azure clients read (`azureGroupSecrets`, `azureGroupMergeKey`), a+ * tombstone of them leaves the profile no Azure group, and a profile's+ * `endpoints.anthropic.vertex` derives the Vertex AI setup and the Anthropic models it serves,+ * as librechat.yaml's does at startup: `enabled: false` turns Vertex AI off for the profile and+ * serves the YAML-shaped `endpoints.anthropic.models`, and models a profile sets in+ * `endpoints.anthropic.models` stay over Vertex's. A profile that turns Azure `assistants` on+ * or off, or tombstones the Azure endpoint, gets the Azure Assistants endpoint derived again.+ * Off, those overrides are stored but inert, and checked on write all the same. Whether on or+ * off, `vertex.serviceKeyFile` and `vertex.region` stay librechat.yaml's+ * (`rules.baseOnlyPaths`): the merge ignores them wherever stored, and a change batch skips and+ * reports a write of them. The merge never applies a profile's `endpoints.anthropic.vertexConfig`+ * (what `vertex` resolves to, as GET `/base` shows it), value or tombstone, and writes skip it+ * (`rules.derivedPaths`, `derived_path`). A profile may turn Vertex AI on only where+ * librechat.yaml configures `endpoints.anthropic.vertex` (on or off), whose key file and region+ * it runs on. A Vertex AI setup that does not load (an unset `${VAR}`, a region, project ID or+ * deployment name that would leave its place in the request URL, a model name sent as written+ * that would, or one turned on where librechat.yaml configures none) answers 400 `CONFIG_OVERRIDE_INVALID` with+ * `invalid_vertex_config` at `endpoints.anthropic.vertex`, and a stored one is left out of the+ * merge, with a warning.*/export type AdminConfigFeatureFlag =| 'dottedKeys'@@ -1019,7 +1092,11 @@ export type AdminConfigFeatureFlag =| 'issueParams'| 'adminTermsExempt'| 'keyedTombstones'- | 'renameHints';+ | 'renameHints'+ | 'azureGroupMergeKey'+ | 'customParamsExpansion'+ | 'specInterfaceRederive'+ | 'endpointRederive';export type AdminConfigFeatures = Record<AdminConfigFeatureFlag, boolean>;@@ -1058,6 +1135,13 @@ export type AdminConfigMergeRules = {atomicMergePaths: string[];/** Override sections the resolved config (`GET /base`) holds under another name. */overrideKeyMap: Record<string, string>;+ /**+ * Fields the resolved config (`GET /base`) holds that the server derives from other fields+ * (`endpoints.anthropic.vertexConfig`, from `endpoints.anthropic.vertex`): the merge never+ * applies an override's value or tombstone there, `POST …/changes` skips a `set` or `tombstone`+ * of one (`derived_path`), and PUT, PATCH and the tombstone route leave them out.+ */+ derivedPaths: string[];};export type AdminConfigRules = AdminConfigMergeRules & {