Skip to content

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

🧬 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.example
index 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=./skill
diff --git a/api/server/index.js b/api/server/index.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.md
index 395c20589c..77f7f0af26 100644
--- a/docs/endpoint-overrides.md
+++ b/docs/endpoint-overrides.md
@@ -13,7 +13,8 @@ the entry by its key.
## Keyed paths
A 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:
```text
endpoints.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 old
name.
+## 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 upgrading
Before keyed paths, a tombstone such as `endpoints.custom["Name"]` was accepted and stored but had
diff --git a/packages/api/src/admin/config.changes.integration.spec.ts b/packages/api/src/admin/config.changes.integration.spec.ts
index 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.ts
index 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, handlers
await 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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']): AdminCo
dataProvider: 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.ts
index 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.ts
index 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): strin
export 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 = origins
diff --git a/packages/api/src/admin/secrets.integration.spec.ts b/packages/api/src/admin/secrets.integration.spec.ts
index 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 collec
group: '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 collec
expect(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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 entering
diff --git a/packages/api/src/app/report.spec.ts b/packages/api/src/app/report.spec.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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, s
return 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 = z
export 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 mapping
const { 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 file
const 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.ts
index 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 & {