🔍 fix: Warn When interface.webSearch Blocks Native Search (#16708)

* fix: Warn When interface.webSearch Blocks Native Search in Model Specs

interface.webSearch syncs the WEB_SEARCH permission, which also gates
provider-native search since #15875. A deployment that set it to false to
hide LibreChat's search tool silently lost native search on its model
specs. Startup now names the affected specs, describes the native-only
configuration, and notes that removing the key keeps the stored permission.

Related to #16673

* fix: Warn When a Stored Role Denies Native Search With interface.webSearch Unset
This commit is contained in:
Marco Beretta 2026-10-03 23:14:56 +02:00 • committed by GitHub
parent 179ff350ec
commit 46d73974b8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 190 additions and 1 deletions

View file

@ -0,0 +1,80 @@
import { expect, test } from '@playwright/test';
import { logger } from '@librechat/data-schemas';
import { Permissions, PermissionTypes } from 'librechat-data-provider';
import type { IRole, AppConfig } from '@librechat/data-schemas';
import { updateInterfacePermissions } from '../../../../packages/api/src/app/permissions';
/**
* Startup runs `updateInterfacePermissions` once against the stored USER and ADMIN roles.
* It is called here in-process with stubbed role reads and writes, so no shared role
* document of this run is changed while other specs are using it.
*/
const nativeSpec = { name: 'gpt-native', label: 'GPT', preset: { web_search: true } };
const plainSpec = { name: 'plain', label: 'Plain', preset: {} };
async function startupWarnings({
webSearch,
list = [nativeSpec],
storedUse,
}: {
webSearch?: boolean;
list?: unknown[];
storedUse?: boolean;
}): Promise<string[]> {
const config = { interface: webSearch === undefined ? {} : { webSearch } };
const appConfig = {
config,
interfaceConfig: { webSearch },
modelSpecs: { list },
} as unknown as AppConfig;
const getRoleByName = async (name: string) =>
storedUse === undefined
? null
: ({
name,
permissions: { [PermissionTypes.WEB_SEARCH]: { [Permissions.USE]: storedUse } },
} as unknown as IRole);
const messages: string[] = [];
const original = logger.warn;
logger.warn = ((message: unknown) => {
messages.push(String(message));
return logger;
}) as typeof logger.warn;
try {
await updateInterfacePermissions({
appConfig,
getRoleByName,
updateAccessPermissions: async () => undefined,
});
} finally {
logger.warn = original;
}
return messages.filter((message) => message.includes('provider-native web search'));
}
test.describe('native web search startup warning', () => {
test('an operator who sets interface.webSearch false is told which native search specs it blocks @scenario:explicit-websearch-false-warns-native-search-specs', async () => {
const warnings = await startupWarnings({ webSearch: false });
expect(warnings).toHaveLength(1);
expect(warnings[0]).toContain('`interface.webSearch: false` denies');
expect(warnings[0]).toContain('gpt-native');
expect(warnings[0]).toContain('endpoints.agents.capabilities');
expect(warnings[0]).toContain('UPGRADING.md');
});
test('an operator who removed interface.webSearch is told the stored role still blocks native search @scenario:stored-websearch-denial-warns-when-key-unset', async () => {
const warnings = await startupWarnings({ storedUse: false });
expect(warnings).toHaveLength(1);
expect(warnings[0]).toContain('stored role permission keeps denying');
expect(warnings[0]).toContain('gpt-native');
});
test('startup stays silent when web search is allowed or no spec requests native search @scenario:allowed-websearch-or-no-native-specs-stays-silent', async () => {
expect(await startupWarnings({ webSearch: true })).toHaveLength(0);
expect(await startupWarnings({})).toHaveLength(0);
expect(await startupWarnings({ webSearch: true, storedUse: false })).toHaveLength(0);
expect(await startupWarnings({ webSearch: false, list: [plainSpec] })).toHaveLength(0);
});
});

View file

@ -1,4 +1,4 @@
import { loadDefaultInterface } from '@librechat/data-schemas';
import { logger, loadDefaultInterface } from '@librechat/data-schemas';
import {
SystemRoles,
Permissions,
@ -3062,3 +3062,69 @@ describe('updateInterfacePermissions - web search recovery', () => {
expect(grants()).toEqual([false, false]);
});
});
describe('updateInterfacePermissions - native web search warning', () => {
const nativeSpec = { name: 'gpt-native', label: 'GPT', preset: { web_search: true } };
const run = async (webSearch: boolean | undefined, list: unknown[] = [nativeSpec]) => {
const config = { interface: webSearch === undefined ? {} : { webSearch } };
const configDefaults = { interface: {} } as TConfigDefaults;
const interfaceConfig = await loadDefaultInterface({ config, configDefaults });
const appConfig = { config, interfaceConfig, modelSpecs: { list } } as unknown as AppConfig;
await updateInterfacePermissions({
appConfig,
getRoleByName: mockGetRoleByName,
updateAccessPermissions: mockUpdateAccessPermissions,
});
};
const nativeWarnings = () =>
warnSpy.mock.calls.filter(([message]) =>
String(message).includes('provider-native web search'),
);
let warnSpy: jest.SpyInstance;
beforeEach(() => {
jest.clearAllMocks();
mockGetRoleByName.mockResolvedValue(null);
warnSpy = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
});
afterEach(() => {
warnSpy.mockRestore();
});
it('warns when interface.webSearch: false blocks model specs that request native search', async () => {
await run(false);
const warnings = nativeWarnings();
expect(warnings).toHaveLength(1);
expect(warnings[0][0]).toContain('`interface.webSearch: false` denies');
expect(warnings[0][0]).toContain('gpt-native');
expect(warnings[0][0]).toContain('endpoints.agents.capabilities');
});
it('warns when the key is unset but a stored role still denies WEB_SEARCH', async () => {
mockGetRoleByName.mockImplementation(async (roleName: string) => ({
name: roleName,
permissions: { [PermissionTypes.WEB_SEARCH]: { [Permissions.USE]: false } },
}));
await run(undefined);
const warnings = nativeWarnings();
expect(warnings).toHaveLength(1);
expect(warnings[0][0]).toContain('stored role permission keeps denying');
expect(warnings[0][0]).toContain(SystemRoles.USER);
});
it('does not warn when web search is allowed or no spec requests native search', async () => {
await run(true);
await run(undefined);
await run(false, [{ name: 'plain', label: 'Plain', preset: {} }]);
mockGetRoleByName.mockImplementation(async (roleName: string) => ({
name: roleName,
permissions: { [PermissionTypes.WEB_SEARCH]: { [Permissions.USE]: false } },
}));
await run(true);
expect(nativeWarnings()).toHaveLength(0);
});
});

View file

@ -67,6 +67,35 @@ function hasExplicitConfig(
}
}
/**
* `WEB_SEARCH.USE` gates provider-native search (the `web_search` model parameter) as well as
* LibreChat's `web_search` tool. Warns when model specs ask for native search that a role's
* effective permission blocks, whether `interface.webSearch: false` sets it or a stored role keeps it.
*/
function warnNativeWebSearchDenied(
appConfig: AppConfig,
deniedRoles: string[],
isExplicitlyConfigured: boolean,
): void {
if (deniedRoles.length === 0) {
return;
}
const specs = (appConfig.modelSpecs?.list ?? [])
.filter((spec) => spec.preset?.web_search === true)
.map((spec) => spec.name);
if (specs.length === 0) {
return;
}
const source = isExplicitlyConfigured
? '`interface.webSearch: false` denies'
: '`interface.webSearch` is not set, and the stored role permission keeps denying';
logger.warn(
`Model specs request provider-native web search (\`preset.web_search: true\`), but ${source} the \`WEB_SEARCH\` permission for roles ${deniedRoles.join(', ')}, which also blocks native search: ${specs.join(', ')}. ` +
"To offer native search without LibreChat's search tool, set `interface.webSearch: true` and remove `web_search` from `endpoints.agents.capabilities`. " +
'Removing `interface.webSearch` alone keeps the stored role permission; set it explicitly or update the role in the admin settings. See "Native-only web search" in UPGRADING.md.',
);
}
export async function updateInterfacePermissions({
appConfig,
getRoleByName,
@ -124,6 +153,7 @@ export async function updateInterfacePermissions({
};
const defaults = getConfigDefaults().interface;
const webSearchDeniedRoles: string[] = [];
// Permission precedence order:
// 1. Explicit user configuration (from librechat.yaml)
@ -767,9 +797,22 @@ export async function updateInterfacePermissions({
}
}
const webSearchUse =
permissionsToUpdate[PermissionTypes.WEB_SEARCH]?.[Permissions.USE] ??
existingPermissions?.[PermissionTypes.WEB_SEARCH]?.[Permissions.USE];
if (webSearchUse === false) {
webSearchDeniedRoles.push(roleName);
}
// Update permissions if any need updating
if (Object.keys(permissionsToUpdate).length > 0) {
await updateAccessPermissions(roleName, permissionsToUpdate, existingRole);
}
}
warnNativeWebSearchDenied(
appConfig,
webSearchDeniedRoles,
hasExplicitConfig(interfaceConfig, PermissionTypes.WEB_SEARCH),
);
}