Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
📕 fix: Explain Native Web Search Permission Denials (#16691)
lia-by-librechat[bot]0c5e1ce67f38
diff --git a/UPGRADING.md b/UPGRADING.mdindex aecd00630c..fdeaafc82e 100644--- a/UPGRADING.md+++ b/UPGRADING.md@@ -1,5 +1,47 @@# Upgrading LibreChat+## Native-only web search after v0.8.8-rc2++Since v0.8.8-rc3 (#15875), `WEB_SEARCH.USE` authorizes both LibreChat's+external search pipeline and provider-native search. `interface.webSearch: false`+sets that permission to `false` for `USER` and `ADMIN`. Removing the YAML field+preserves the stored denial; it does not restore the default grant.++For native search without LibreChat's external pipeline:++1. Explicitly set `interface.webSearch: true` and restart the API to restore+ `USER` and `ADMIN` grants. This enables both roles, not just the affected user.+ For selective access or custom roles, leave the field unset and enable+ `WEB_SEARCH.USE` only for the intended roles in the permissions editor.+2. Remove only `web_search` from your explicit `endpoints.agents.capabilities`+ list, preserving the other capabilities. Omitting the list restores defaults,+ including external search. This capability does not control native search.+3. In each relevant model specification, keep top-level `webSearch: false` for+ the external tool and `preset.web_search: true` for native search. Keep+ `preset.useResponsesApi: true` for OpenAI-compatible native search.+4. Saved agents use their own model parameters. Enable native Web Search there.+5. Reload the client and verify the effective role permission and provider search+ request. Responses API being enabled alone does not mean search is allowed.++Example fields to merge into an existing configuration:++```yaml+interface:+ webSearch: true # Shared role grant, including native search.+endpoints:+ agents:+ # Preserve your existing list; remove only web_search.+ capabilities: [deferred_tools, execute_code, file_search, artifacts, subagents, actions, context, skills, memory, ask_user_question, tools, chain, ocr]+```++An explicit YAML grant is reapplied on restart. After recovery, remove the field+if the permissions editor should own future role changes. Stored grants and+denials are preserved when the field is absent. No role reset is required.++The composer palette and its pinned chips share the external capability gate in+the updated composer. In v0.8.8, an old pinned Search badge may remain visible after+external search is disabled; the backend still refuses to load that tool (#16673).+## Redis streaming now coalesces deltas by defaultRedis-backed streams now batch model and tool-argument deltas in a **25 ms**diff --git a/client/src/components/SidePanel/Agents/ModelPanel.test.tsx b/client/src/components/SidePanel/Agents/ModelPanel.test.tsxindex ddf506b4de..bb5c7a118d 100644--- a/client/src/components/SidePanel/Agents/ModelPanel.test.tsx+++ b/client/src/components/SidePanel/Agents/ModelPanel.test.tsx@@ -10,10 +10,14 @@ import type { UseFormReturn } from 'react-hook-form';import type { AgentForm } from '~/common';import ModelPanel from './ModelPanel';+const mockWebSearchAllowed = jest.fn(() => true);+const mockStartupConfig = jest.fn<Partial<TStartupConfig>, []>(() => ({}));jest.mock('@librechat/client', () => ({- Alert: ({ children }: { children: React.ReactNode }) => <div role="alert">{children}</div>,+ Alert: ({ children, role = 'alert' }: React.HTMLAttributes<HTMLDivElement>) => (+ <div role={role}>{children}</div>+ ),Button: ({ children, onClick, type }: React.ButtonHTMLAttributes<HTMLButtonElement>) => (<button type={type} onClick={onClick}>{children}@@ -72,7 +76,7 @@ jest.mock('~/Providers', () => ({jest.mock('~/hooks', () => ({useLocalize: () => (key: string) => key,- useHasAccess: () => true,+ useHasAccess: () => mockWebSearchAllowed(),}));jest.mock('~/utils', () => ({@@ -127,6 +131,61 @@ describe('ModelPanel', () => {beforeEach(() => {localStorage.clear();mockStartupConfig.mockReturnValue({});+ mockWebSearchAllowed.mockReturnValue(true);+ });++ it('explains a denied native search control without changing saved model parameters', () => {+ mockWebSearchAllowed.mockReturnValue(false);+ const formRef: React.MutableRefObject<UseFormReturn<AgentForm> | null> = { current: null };+ const parameters = { web_search: true, useResponsesApi: true };+ const { getByRole, queryByRole, rerender } = render(+ <TestForm+ defaultProvider={EModelEndpoint.openAI}+ defaultModel="gpt-4o"+ defaultModelParameters={parameters}+ formRef={formRef}+ models={{ [EModelEndpoint.openAI]: ['gpt-4o'] }}+ modelsReady={true}+ />,+ );++ expect(getByRole('status')).toHaveTextContent('com_ui_native_web_search_denied');+ expect(formRef.current?.getValues('model_parameters')).toEqual(parameters);++ mockWebSearchAllowed.mockReturnValue(true);+ rerender(+ <TestForm+ defaultProvider={EModelEndpoint.openAI}+ defaultModel="gpt-4o"+ defaultModelParameters={parameters}+ formRef={formRef}+ models={{ [EModelEndpoint.openAI]: ['gpt-4o'] }}+ modelsReady={true}+ />,+ );+ expect(queryByRole('status')).toBeNull();+ expect(formRef.current?.getValues('model_parameters')).toEqual(parameters);+ });++ it('explains why native search is unavailable even before the agent requests it', () => {+ mockWebSearchAllowed.mockReturnValue(false);+ const { getByRole } = render(+ <TestForm+ defaultProvider={EModelEndpoint.openAI}+ defaultModel="gpt-4o"+ models={{ [EModelEndpoint.openAI]: ['gpt-4o'] }}+ modelsReady={true}+ />,+ );+ expect(getByRole('status')).toHaveTextContent('com_ui_native_web_search_denied');+ });++ it('does not show a search warning for a provider without native search', () => {+ mockWebSearchAllowed.mockReturnValue(false);+ const { queryByRole } = render(+ <TestForm defaultProvider="removed-provider" models={{}} modelsReady={true} />,+ );+ expect(queryByRole('status')).toBeNull();});it('disables model selection until the model catalogue is ready', () => {diff --git a/client/src/components/SidePanel/Agents/ModelPanel.tsx b/client/src/components/SidePanel/Agents/ModelPanel.tsxindex a86ed63f67..8e6b480f39 100644--- a/client/src/components/SidePanel/Agents/ModelPanel.tsx+++ b/client/src/components/SidePanel/Agents/ModelPanel.tsx@@ -88,6 +88,10 @@ export default function ModelPanel({/** The rendered set omits role-gated controls; `parameterSettings.parameters`* stays complete so the pruning effect below still recognises them. */const { visibleParameters: parameters } = parameterSettings;+ const webSearchBlocked =+ !webSearchAllowed &&+ (modelParameters?.web_search === true ||+ parameterSettings.parameters.some((parameter) => parameter.key === 'web_search'));/*** Prunes `model_parameters` entries that no longer have a visible control (e.g. a@@ -266,6 +270,11 @@ export default function ModelPanel({)}</div></div>+ {webSearchBlocked && (+ <Alert variant="warning" role="status">+ {localize('com_ui_native_web_search_denied')}+ </Alert>+ )}{/* Model Parameters */}{parameters && (<div className="h-auto max-w-full">diff --git a/client/src/hooks/Input/__tests__/usePaletteEntries.spec.tsx b/client/src/hooks/Input/__tests__/usePaletteEntries.spec.tsxindex ce119895b4..fba0850222 100644--- a/client/src/hooks/Input/__tests__/usePaletteEntries.spec.tsx+++ b/client/src/hooks/Input/__tests__/usePaletteEntries.spec.tsx@@ -204,6 +204,30 @@ describe('usePaletteEntries', () => {expect(codeInterpreter.setIsPinned).toHaveBeenCalledWith(false);});+ it.each([false, true])(+ 'withholds restored pinned search (active=%s) from both the palette and prompt bar when its capability is disabled',+ (active) => {+ const webSearch = toggle(active, true);+ mockContext = { ...fullContext(), webSearch };+ const { result, rerender } = entries();+ expect(result.current.find((item) => item.key === 'builtin:web_search')).toEqual(+ expect.objectContaining({ pinned: true, active }),+ );++ mockCapabilities = { ...allCapabilities, webSearchEnabled: false };+ rerender();+ expect(keysOf(result)).not.toContain('builtin:web_search');+ expect(webSearch.setIsPinned).not.toHaveBeenCalled();+ expect(webSearch.debouncedChange).not.toHaveBeenCalled();++ mockCapabilities = { ...allCapabilities };+ rerender();+ expect(result.current.find((item) => item.key === 'builtin:web_search')).toEqual(+ expect.objectContaining({ pinned: true, active }),+ );+ },+ );+describe('the two gates on every tool', () => {it.each([[PermissionTypes.WEB_SEARCH, 'builtin:web_search'],diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.jsonindex e693f8998d..5ab840ff30 100644--- a/client/src/locales/en/translation.json+++ b/client/src/locales/en/translation.json@@ -3194,6 +3194,7 @@"com_ui_wakeup_task_finished": "Background task finished","com_ui_wakeup_tasks_finished": "{{0}} background tasks finished","com_ui_wakeup_view_activity": "View activity",+ "com_ui_native_web_search_denied": "Your role does not allow web search, including provider-native search. Ask an administrator to enable your Web Search permission.","com_ui_web_search": "Web Search","com_ui_web_search_cohere_key": "Enter Cohere API Key","com_ui_web_search_firecrawl_url": "Firecrawl API URL (optional)",diff --git a/librechat.example.yaml b/librechat.example.yamlindex 8c3599edc6..c01ff4eccf 100644--- a/librechat.example.yaml+++ b/librechat.example.yaml@@ -775,6 +775,8 @@ endpoints:# skills:# maxCatalogSkills: 20# # (optional) Agent Capabilities available to all users. Omit the ones you wish to exclude. Defaults to list below.+ # # web_search controls only LibreChat's external pipeline, not provider-native search.+ # # Both require WEB_SEARCH.USE, seeded by interface.webSearch. See UPGRADING.md.# capabilities: ["deferred_tools", "execute_code", "file_search", "web_search", "artifacts", "subagents", "actions", "context", "skills", "memory", "ask_user_question", "tools", "chain", "ocr"]# # The following capabilities are opt-in and must be added explicitly:# # "programmatic_tools", "stateful_code_sessions", "run_in_background", "tool_intents"diff --git a/packages/api/src/agents/__tests__/initialize.test.ts b/packages/api/src/agents/__tests__/initialize.test.tsindex 3319102e3f..50b4a05c4f 100644--- a/packages/api/src/agents/__tests__/initialize.test.ts+++ b/packages/api/src/agents/__tests__/initialize.test.ts@@ -34,6 +34,7 @@ jest.mock('@librechat/agents', () => ({import { Providers } from '@librechat/agents';import { createHash } from 'node:crypto';+import { logger } from '@librechat/data-schemas';import { createRepositoryInstructionLoader } from '../../code/instructions';import {Tools,@@ -5237,6 +5238,10 @@ describe('initializeAgent — authorized run file snapshots', () => {describe('initializeAgent — provider-native web search role gate', () => {const OPENAI_SEARCH = { type: 'web_search' };+ beforeEach(() => {+ jest.clearAllMocks();+ });+const roleWithWebSearch = (use: boolean) =>jest.fn().mockResolvedValue({name: 'USER',@@ -5320,6 +5325,34 @@ describe('initializeAgent — provider-native web search role gate', () => {expect(result.tools).not.toContainEqual(OPENAI_SEARCH);});+ it('keeps native search when the external pipeline capability is disabled', async () => {+ const getRoleByName = roleWithWebSearch(true);+ const result = await run({+ getRoleByName,+ params: {+ req: {+ ...roleGatedReq(),+ config: { endpoints: { agents: { capabilities: [AgentCapabilities.file_search] } } },+ } as ServerRequest,+ },+ });++ expect(result.tools).toContainEqual(OPENAI_SEARCH);+ expect(getRoleByName).toHaveBeenCalledTimes(1);+ expect(logger.warn).not.toHaveBeenCalledWith(expect.stringContaining('Restore the role grant'));+ });++ it('explains a blocked native request even when the caller supplies the denial', async () => {+ const result = await run({+ params: { resolveWebSearchGrant: jest.fn().mockResolvedValue(false) },+ });++ expect(result.tools).not.toContainEqual(OPENAI_SEARCH);+ expect(logger.warn).toHaveBeenCalledWith(+ expect.stringContaining('removing interface.webSearch does not reset stored permissions'),+ );+ });+it('reads no role when the built config turns no native search on', async () => {const getRoleByName = roleWithWebSearch(false);const resolveWebSearchGrant = jest.fn().mockResolvedValue(false);diff --git a/packages/api/src/agents/initialize.ts b/packages/api/src/agents/initialize.tsindex 63b0f19ae8..f294c6a8f9 100644--- a/packages/api/src/agents/initialize.ts+++ b/packages/api/src/agents/initialize.ts@@ -1506,9 +1506,10 @@ export async function initializeAgent(resolve: params.resolveWebSearchGrant,getRoleByName: db.getRoleByName,}));- if (webSearchDenied && stripWebSearchPlugin(llmConfig) > 0) {- logger.debug(- `[initializeAgent] Removed the OpenRouter web search plugin; role denies WEB_SEARCH.`,+ if (webSearchDenied) {+ stripWebSearchPlugin(llmConfig);+ logger.warn(+ '[initializeAgent] Provider-native web search was requested but blocked by WEB_SEARCH.USE. Restore the role grant explicitly; removing interface.webSearch does not reset stored permissions.',);}const tokensModel =diff --git a/packages/api/src/app/permissions.spec.ts b/packages/api/src/app/permissions.spec.tsindex f99a9d02a1..36743d4a5d 100644--- a/packages/api/src/app/permissions.spec.ts+++ b/packages/api/src/app/permissions.spec.ts@@ -7,7 +7,7 @@ import {PermissionTypes,} from 'librechat-data-provider';import type { TConfigDefaults, TCustomConfig } from 'librechat-data-provider';-import type { AppConfig } from '@librechat/data-schemas';+import type { AppConfig, IRole } from '@librechat/data-schemas';import { updateInterfacePermissions } from './permissions';const mockUpdateAccessPermissions = jest.fn();@@ -3005,3 +3005,60 @@ describe('updateInterfacePermissions - permissions', () => {}});});++describe('updateInterfacePermissions - web search recovery', () => {+ it('preserves a stored denial on omission and restores it only with an explicit grant', async () => {+ const roles = new Map(+ [SystemRoles.USER, SystemRoles.ADMIN].map((name) => [+ name,+ { name, permissions: { [PermissionTypes.WEB_SEARCH]: { [Permissions.USE]: true } } },+ ]),+ );+ const getRoleByName = jest.fn(async (name: string) => roles.get(name as SystemRoles) as IRole);+ const updateAccessPermissions = jest.fn<+ ReturnType<Parameters<typeof updateInterfacePermissions>[0]['updateAccessPermissions']>,+ Parameters<Parameters<typeof updateInterfacePermissions>[0]['updateAccessPermissions']>+ >(async (name, updates) => {+ const role = roles.get(name as SystemRoles);+ const grant = updates[PermissionTypes.WEB_SEARCH]?.[Permissions.USE];+ if (role && grant !== undefined) {+ role.permissions[PermissionTypes.WEB_SEARCH][Permissions.USE] = grant;+ }+ });+ const sync = async (webSearch?: boolean) => {+ updateAccessPermissions.mockClear();+ const config = { interface: webSearch === undefined ? {} : { webSearch } };+ const interfaceConfig = await loadDefaultInterface({+ config,+ configDefaults: { interface: {} } as TConfigDefaults,+ });+ await updateInterfacePermissions({+ appConfig: { config, interfaceConfig } as unknown as AppConfig,+ getRoleByName,+ updateAccessPermissions,+ });+ };+ const grants = () =>+ [...roles.values()].map(+ (role) => role.permissions[PermissionTypes.WEB_SEARCH][Permissions.USE],+ );+ const expectPreserved = () => {+ for (const [, updates] of updateAccessPermissions.mock.calls) {+ expect(updates).not.toHaveProperty(PermissionTypes.WEB_SEARCH);+ }+ };++ await sync(false);+ expect(grants()).toEqual([false, false]);+ await sync();+ expect(grants()).toEqual([false, false]);+ expectPreserved();+ await sync(true);+ expect(grants()).toEqual([true, true]);+ await sync();+ expect(grants()).toEqual([true, true]);+ expectPreserved();+ await sync(false);+ expect(grants()).toEqual([false, false]);+ });+});