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: Strict Opt-In Skills Activation per Agent (#12823)
Danny Avila596f806f6026
diff --git a/api/server/controllers/agents/__tests__/openai.spec.js b/api/server/controllers/agents/__tests__/openai.spec.jsindex 7fb41697e9..7638fc2e35 100644--- a/api/server/controllers/agents/__tests__/openai.spec.js+++ b/api/server/controllers/agents/__tests__/openai.spec.js@@ -41,6 +41,9 @@ jest.mock('@librechat/api', () => ({createChunk: jest.fn().mockReturnValue({}),buildToolSet: jest.fn().mockReturnValue(new Set()),scopeSkillIds: jest.fn().mockImplementation((ids) => ids),+ resolveAgentScopedSkillIds: jest+ .fn()+ .mockImplementation(({ accessibleSkillIds }) => accessibleSkillIds),loadSkillStates: jest.fn().mockResolvedValue({ skillStates: {}, defaultActiveOnShare: false }),sendFinalChunk: jest.fn(),createSafeUser: jest.fn().mockReturnValue({ id: 'user-123' }),diff --git a/api/server/controllers/agents/__tests__/responses.unit.spec.js b/api/server/controllers/agents/__tests__/responses.unit.spec.jsindex 9b760b7076..e5569fbbf5 100644--- a/api/server/controllers/agents/__tests__/responses.unit.spec.js+++ b/api/server/controllers/agents/__tests__/responses.unit.spec.js@@ -42,6 +42,9 @@ jest.mock('@librechat/api', () => ({}),buildToolSet: jest.fn().mockReturnValue(new Set()),scopeSkillIds: jest.fn().mockImplementation((ids) => ids),+ resolveAgentScopedSkillIds: jest+ .fn()+ .mockImplementation(({ accessibleSkillIds }) => accessibleSkillIds),loadSkillStates: jest.fn().mockResolvedValue({ skillStates: {}, defaultActiveOnShare: false }),createSafeUser: jest.fn().mockReturnValue({ id: 'user-123' }),initializeAgent: jest.fn().mockResolvedValue({diff --git a/api/server/controllers/agents/openai.js b/api/server/controllers/agents/openai.jsindex 9d98600ef7..7d2395b09f 100644--- a/api/server/controllers/agents/openai.js+++ b/api/server/controllers/agents/openai.js@@ -13,26 +13,26 @@ const {createRun,createChunk,buildToolSet,- scopeSkillIds,loadSkillStates,sendFinalChunk,createSafeUser,validateRequest,initializeAgent,getBalanceConfig,+ injectSkillPrimes,extractManualSkills,createErrorResponse,recordCollectedUsage,getTransactionsConfig,resolveRecursionLimit,+ discoverConnectedAgents,+ getRemoteAgentPermissions,createToolExecuteHandler,buildNonStreamingResponse,createOpenAIStreamTracker,+ resolveAgentScopedSkillIds,createOpenAIContentAggregator,- injectSkillPrimes,isChatCompletionValidationFailure,- discoverConnectedAgents,- getRemoteAgentPermissions,} = require('@librechat/api');const {buildSummarizationHandlers,@@ -283,10 +283,12 @@ const OpenAIChatCompletionController = async (req, res) => {endpointOption,allowedProviders,isInitialAgent: true,- accessibleSkillIds: scopeSkillIds(+ accessibleSkillIds: resolveAgentScopedSkillIds({+ agent,accessibleSkillIds,- ephemeralSkillsToggle ? undefined : agent.skills,- ),+ skillsCapabilityEnabled,+ ephemeralSkillsToggle,+ }),codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),skillStates,defaultActiveOnShare,diff --git a/api/server/controllers/agents/responses.js b/api/server/controllers/agents/responses.jsindex 08ca17bde5..b2805fc19f 100644--- a/api/server/controllers/agents/responses.js+++ b/api/server/controllers/agents/responses.js@@ -12,8 +12,8 @@ const {const {createRun,buildToolSet,- scopeSkillIds,loadSkillStates,+ resolveAgentScopedSkillIds,createSafeUser,initializeAgent,getBalanceConfig,@@ -413,10 +413,12 @@ const createResponse = async (req, res) => {endpointOption,allowedProviders,isInitialAgent: true,- accessibleSkillIds: scopeSkillIds(+ accessibleSkillIds: resolveAgentScopedSkillIds({+ agent,accessibleSkillIds,- ephemeralSkillsToggle ? undefined : agent.skills,- ),+ skillsCapabilityEnabled,+ ephemeralSkillsToggle,+ }),codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),skillStates,defaultActiveOnShare,diff --git a/api/server/services/Endpoints/agents/initialize.js b/api/server/services/Endpoints/agents/initialize.jsindex 367a8adb45..939a0a7ff6 100644--- a/api/server/services/Endpoints/agents/initialize.js+++ b/api/server/services/Endpoints/agents/initialize.js@@ -1,7 +1,6 @@const { logger } = require('@librechat/data-schemas');const { createContentAggregator } = require('@librechat/agents');const {- scopeSkillIds,loadSkillStates,initializeAgent,primeInvokedSkills,@@ -10,6 +9,7 @@ const {GenerationJobManager,getCustomEndpointConfig,discoverConnectedAgents,+ resolveAgentScopedSkillIds,} = require('@librechat/api');const {ResourceType,@@ -115,9 +115,12 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {const toolEndCallback = createToolEndCallback({ req, res, artifactPromises, streamId });/** Query accessible skill IDs once per run (shared across all agents).- * Skills activate when the admin capability is enabled AND either:- * - the per-conversation toggle is on (ephemeral), OR- * - the agent has stored skills (scoped by scopeSkillIds later). */+ * Skills activate under strict opt-in semantics — see+ * `resolveAgentScopedSkillIds` for the per-agent activation predicate:+ * - Ephemeral agent → per-conversation skills badge toggle (full catalog).+ * - Persisted agent → `agent.skills_enabled === true`. Optional+ * `agent.skills` allowlist narrows the catalog; empty/undefined+ * allowlist with the toggle on = full accessible catalog. */const enabledCapabilities = new Set(appConfig?.endpoints?.[EModelEndpoint.agents]?.capabilities);const skillsCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.skills);const codeEnvAvailable = enabledCapabilities.has(AgentCapabilities.execute_code);@@ -259,6 +262,13 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {*/const manualSkills = extractManualSkills(req.body);+ const primaryScopedSkillIds = resolveAgentScopedSkillIds({+ agent: primaryAgent,+ accessibleSkillIds,+ skillsCapabilityEnabled,+ ephemeralSkillsToggle,+ });+const primaryConfig = await initializeAgent({req,@@ -271,10 +281,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {endpointOption,allowedProviders,isInitialAgent: true,- accessibleSkillIds: scopeSkillIds(- accessibleSkillIds,- ephemeralSkillsToggle ? undefined : primaryAgent.skills,- ),+ accessibleSkillIds: primaryScopedSkillIds,codeEnvAvailable,skillStates,defaultActiveOnShare,@@ -340,7 +347,12 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {conversationId,parentMessageId,computeAccessibleSkillIds: (agent) =>- scopeSkillIds(accessibleSkillIds, ephemeralSkillsToggle ? undefined : agent.skills),+ resolveAgentScopedSkillIds({+ agent,+ accessibleSkillIds,+ skillsCapabilityEnabled,+ ephemeralSkillsToggle,+ }),skillStates,defaultActiveOnShare,codeEnvAvailable,@@ -544,10 +556,12 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {parentMessageId,endpointOption: { ...endpointOption, endpoint: EModelEndpoint.agents },allowedProviders,- accessibleSkillIds: scopeSkillIds(+ accessibleSkillIds: resolveAgentScopedSkillIds({+ agent,accessibleSkillIds,- ephemeralSkillsToggle ? undefined : agent.skills,- ),+ skillsCapabilityEnabled,+ ephemeralSkillsToggle,+ }),skillStates,defaultActiveOnShare,},diff --git a/client/src/common/agents-types.ts b/client/src/common/agents-types.tsindex 8a018e8fcb..7313812ec5 100644--- a/client/src/common/agents-types.ts+++ b/client/src/common/agents-types.ts@@ -40,6 +40,7 @@ export type AgentForm = {/** Per-tool configuration options (deferred loading, allowed callers, etc.) */tool_options?: AgentToolOptions;skills?: string[];+ skills_enabled?: boolean;provider?: AgentProvider | OptionWithIcon;/** @deprecated Use edges instead */agent_ids?: string[];diff --git a/client/src/components/Chat/Input/SkillsCommand.tsx b/client/src/components/Chat/Input/SkillsCommand.tsxindex aec1d1b80c..9105c780a3 100644--- a/client/src/components/Chat/Input/SkillsCommand.tsx+++ b/client/src/components/Chat/Input/SkillsCommand.tsx@@ -96,31 +96,33 @@ function SkillsCommandContent({const agentsMap = useAgentsMapContext();const { isActive } = useSkillActiveState();- /* Resolve the per-agent skill scope. Mirrors backend `scopeSkillIds` for- the happy path: no `skills` field → no scope, `[]` → opt-out, non-empty- → intersection. Ephemeral agent ids (null/undefined/placeholder strings- that don't begin with `agent_`) are unscoped — they correspond to- conversations without a persisted agent and are intentionally absent- from the agents map. While the map is still hydrating we pass through- (undefined → full catalog): the backend enforces scope at turn time, so- there's no security benefit to flashing an empty popover, and the map- typically lands well before the first open. Once the map is authoritative- but the agent isn't in it (deleted, or VIEW revoked mid-session), we fail- closed — scope is unresolvable and the full catalog would be misleading.- `agentId` is threaded in as a prop so this component stays memoizable- and skips re-renders on unrelated conversation-shape changes. */+ /* Resolve the per-agent skill scope. Mirrors backend+ `resolveAgentScopedSkillIds`: ephemeral agents always see the full+ catalog (picking any skill flips `ephemeralAgent.skills = true` and+ activates for the turn); persisted agents gate on the builder's+ `skills_enabled` master toggle — off or unset means opt-out, on with+ an empty allowlist means full catalog, on with a non-empty allowlist+ means narrow to those ids. Persisted agents fail closed during the+ `agentsMap` hydration window so the user cannot pick a skill the+ backend will then refuse, and again when the map is authoritative+ but the agent isn't in it (deleted, or VIEW revoked mid-session).+ `agentId` is threaded in as a prop so this component stays+ memoizable. */const agentSkillIds = useMemo<string[] | null | undefined>(() => {if (!agentId || isEphemeralAgent(agentId)) {return undefined;}if (!agentsMap) {- return undefined;+ return [];}const agent = agentsMap[agentId];if (!agent) {return [];}- return agent.skills;+ if (agent.skills_enabled !== true) {+ return [];+ }+ return Array.isArray(agent.skills) && agent.skills.length > 0 ? agent.skills : undefined;}, [agentId, agentsMap]);const { data, isLoading, isError, fetchNextPage, hasNextPage, isFetchingNextPage } =diff --git a/client/src/components/Chat/Input/__tests__/SkillsCommand.spec.tsx b/client/src/components/Chat/Input/__tests__/SkillsCommand.spec.tsxindex 064688552e..53ec6388f7 100644--- a/client/src/components/Chat/Input/__tests__/SkillsCommand.spec.tsx+++ b/client/src/components/Chat/Input/__tests__/SkillsCommand.spec.tsx@@ -225,7 +225,7 @@ describe('SkillsCommand', () => {expect(mockSetShowSkillsPopover).toHaveBeenCalledWith(false);});- it('narrows the list to the agent-configured scope when agent.skills is set', async () => {+ it('narrows the list to the agent-configured scope when agent.skills is set and skills_enabled is true', async () => {mockUseSkillsInfiniteQuery.mockReturnValue({data: twoSkillsResponse,isLoading: false,@@ -235,7 +235,7 @@ describe('SkillsCommand', () => {isFetchingNextPage: false,});mockUseAgentsMapContext.mockReturnValue({- agent_1: { id: 'agent_1', skills: ['2'] },+ agent_1: { id: 'agent_1', skills: ['2'], skills_enabled: true },});const textAreaRef = makeTextarea('$');@@ -253,7 +253,7 @@ describe('SkillsCommand', () => {expect(await screen.findByRole('button', { name: /Style Guide/i })).toBeInTheDocument();});- it('shows nothing when the agent has an empty skills array (explicit opt-out)', () => {+ it('shows nothing when the agent has skills_enabled:false, regardless of allowlist', () => {mockUseSkillsInfiniteQuery.mockReturnValue({data: twoSkillsResponse,isLoading: false,@@ -263,7 +263,7 @@ describe('SkillsCommand', () => {isFetchingNextPage: false,});mockUseAgentsMapContext.mockReturnValue({- agent_1: { id: 'agent_1', skills: [] },+ agent_1: { id: 'agent_1', skills: ['1', '2'], skills_enabled: false },});const textAreaRef = makeTextarea('$');@@ -280,7 +280,7 @@ describe('SkillsCommand', () => {expect(screen.queryByRole('button', { name: /Style Guide/i })).toBeNull();});- it('shows the full ACL catalog when the agent has no skills field configured', async () => {+ it('hides all skills for a persisted agent with skills_enabled undefined (default off)', async () => {mockUseSkillsInfiniteQuery.mockReturnValue({data: twoSkillsResponse,isLoading: false,@@ -303,8 +303,38 @@ describe('SkillsCommand', () => {/>,);+ /* Mirrors backend `resolveAgentScopedSkillIds`: persisted agents are+ off by default; the builder's `skills_enabled` master toggle is+ the only signal that activates skills for the agent. */+ expect(screen.queryByRole('button', { name: /Brand Guidelines/i })).toBeNull();+ expect(screen.queryByRole('button', { name: /Style Guide/i })).toBeNull();+ });++ it('shows the full catalog for a persisted agent with skills_enabled:true and empty allowlist', async () => {+ mockUseSkillsInfiniteQuery.mockReturnValue({+ data: twoSkillsResponse,+ isLoading: false,+ isError: false,+ fetchNextPage: jest.fn(),+ hasNextPage: false,+ isFetchingNextPage: false,+ });+ mockUseAgentsMapContext.mockReturnValue({+ agent_1: { id: 'agent_1', skills_enabled: true },+ });++ const textAreaRef = makeTextarea('$');+ render(+ <SkillsCommand+ index={0}+ textAreaRef={textAreaRef}+ conversationId={CONVO_ID}+ agentId="agent_1"+ />,+ );+expect(await screen.findByRole('button', { name: /Brand Guidelines/i })).toBeInTheDocument();- expect(await screen.findByRole('button', { name: /Style Guide/i })).toBeInTheDocument();+ expect(screen.getByRole('button', { name: /Style Guide/i })).toBeInTheDocument();});it('treats an ephemeral agent id as unscoped and shows the full ACL catalog', async () => {@@ -334,7 +364,7 @@ describe('SkillsCommand', () => {expect(await screen.findByRole('button', { name: /Style Guide/i })).toBeInTheDocument();});- it('shows the full ACL catalog while the agents map is hydrating (backend still gates the turn)', async () => {+ it('fails closed for persisted agents while the agents map is hydrating', async () => {mockUseSkillsInfiniteQuery.mockReturnValue({data: twoSkillsResponse,isLoading: false,@@ -355,11 +385,12 @@ describe('SkillsCommand', () => {/>,);- /* Hydration race: map not yet loaded. Pass through to full catalog —- the backend scopes at turn time and blanking the popover during- sub-second hydration is worse UX for no security benefit. */- expect(await screen.findByRole('button', { name: /Brand Guidelines/i })).toBeInTheDocument();- expect(await screen.findByRole('button', { name: /Style Guide/i })).toBeInTheDocument();+ /* Hydration race: agents map not yet loaded. Without `skills_enabled`+ visibility we cannot prove the persisted agent opted in, so fail+ closed; otherwise the user can pick a skill the backend will then+ refuse for the turn. */+ expect(screen.queryByRole('button', { name: /Brand Guidelines/i })).toBeNull();+ expect(screen.queryByRole('button', { name: /Style Guide/i })).toBeNull();});it('fails closed when the agent id is set but missing from the agents map', () => {diff --git a/client/src/components/SidePanel/Agents/AgentConfig.tsx b/client/src/components/SidePanel/Agents/AgentConfig.tsxindex 8495da8027..2ee88a59c8 100644--- a/client/src/components/SidePanel/Agents/AgentConfig.tsx+++ b/client/src/components/SidePanel/Agents/AgentConfig.tsx@@ -1,6 +1,6 @@import React, { useState, useMemo, useCallback } from 'react';import { X } from 'lucide-react';-import { useToastContext } from '@librechat/client';+import { Switch, useToastContext } from '@librechat/client';import { Controller, useWatch, useFormContext } from 'react-hook-form';import {EModelEndpoint,@@ -72,8 +72,20 @@ export default function AgentConfig() {const agent = useWatch({ control, name: 'agent' });const tools = useWatch({ control, name: 'tools' });const skills = useWatch({ control, name: 'skills' });+ const skillsActive = useWatch({ control, name: 'skills_enabled' });const agent_id = useWatch({ control, name: 'id' });+ let skillsHintKey:+ | 'com_ui_skills_disabled_hint'+ | 'com_ui_skills_enabled_allowlist_hint'+ | 'com_ui_skills_enabled_all_hint' = 'com_ui_skills_disabled_hint';+ if (skillsActive === true) {+ skillsHintKey =+ (skills ?? []).length > 0+ ? 'com_ui_skills_enabled_allowlist_hint'+ : 'com_ui_skills_enabled_all_hint';+ }+const {codeEnabled,toolsEnabled,@@ -340,10 +352,32 @@ export default function AgentConfig() {{showSkills && (<div className="mb-4">- <label className="text-token-text-primary mb-2 block text-sm font-medium">- {localize('com_ui_skills')}- </label>- <div>+ <div className="mb-2 flex items-center justify-between">+ <label+ htmlFor="skills_enabled"+ className="text-token-text-primary block text-sm font-medium"+ >+ {localize('com_ui_skills')}+ </label>+ <Controller+ name="skills_enabled"+ control={control}+ render={({ field }) => (+ <Switch+ id="skills_enabled"+ checked={field.value === true}+ onCheckedChange={(value: boolean) => field.onChange(Boolean(value))}+ data-testid="skills_enabled"+ aria-label={localize('com_ui_skills_enable_toggle')}+ />+ )}+ />+ </div>+ <p className="mb-2 text-xs text-text-secondary">{localize(skillsHintKey)}</p>+ <div+ className={skillsActive === true ? undefined : 'pointer-events-none opacity-50'}+ aria-disabled={skillsActive !== true}+ ><div className="mb-1">{(skills ?? []).map((skillId) => {const skillName = skillsMap.get(skillId);@@ -368,6 +402,7 @@ export default function AgentConfig() {}}className="ml-2 flex-shrink-0 text-text-secondary transition-colors hover:text-text-primary"aria-label={localize('com_ui_remove_skill_var', { 0: skillName })}+ disabled={skillsActive !== true}><X className="h-4 w-4" aria-hidden="true" /></button>@@ -381,6 +416,7 @@ export default function AgentConfig() {onClick={() => setShowSkillDialog(true)}className="btn btn-neutral border-token-border-light relative h-9 w-full rounded-lg font-medium"aria-haspopup="dialog"+ disabled={skillsActive !== true}><div className="flex w-full items-center justify-center gap-2">{localize('com_ui_add_skills')}diff --git a/client/src/components/SidePanel/Agents/AgentPanel.tsx b/client/src/components/SidePanel/Agents/AgentPanel.tsxindex 5096551b83..97ed8743ee 100644--- a/client/src/components/SidePanel/Agents/AgentPanel.tsx+++ b/client/src/components/SidePanel/Agents/AgentPanel.tsx@@ -77,6 +77,7 @@ export function composeAgentUpdatePayload(data: AgentForm, agent_id?: string | nsupport_contact,tool_options,skills,+ skills_enabled,avatar_action: avatarActionState,} = data;@@ -105,6 +106,7 @@ export function composeAgentUpdatePayload(data: AgentForm, agent_id?: string | nsupport_contact,tool_options,skills,+ skills_enabled,...(shouldResetAvatar ? { avatar: null } : {}),},provider,diff --git a/client/src/components/SidePanel/Agents/AgentSelect.tsx b/client/src/components/SidePanel/Agents/AgentSelect.tsxindex 1fbaa1f989..bf0978c153 100644--- a/client/src/components/SidePanel/Agents/AgentSelect.tsx+++ b/client/src/components/SidePanel/Agents/AgentSelect.tsx@@ -115,6 +115,11 @@ function AgentSelect({return;}+ if (name === 'skills_enabled' && typeof value === 'boolean') {+ formValues[name] = value;+ return;+ }+if (name === 'edges' && Array.isArray(value)) {formValues[name] = value;return;diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.jsonindex 6a17f85260..757d571150 100644--- a/client/src/locales/en/translation.json+++ b/client/src/locales/en/translation.json@@ -1546,7 +1546,11 @@"com_ui_skills_always_apply_invoked": "Auto-applied skills","com_ui_skills_always_apply_pin_title": "Always-applied skill (auto-primed on every turn)","com_ui_skills_command_placeholder": "Select a Skill by name",+ "com_ui_skills_disabled_hint": "Skills are off for this agent. Enable to allow the model to use your skills catalog.","com_ui_skills_empty": "No skills yet",+ "com_ui_skills_enable_toggle": "Enable skills for this agent",+ "com_ui_skills_enabled_all_hint": "Enabled. The full accessible catalog is available; narrow it below if you want to limit which skills this agent can use.",+ "com_ui_skills_enabled_allowlist_hint": "Enabled. Limited to the skills selected below.","com_ui_skills_load_error": "Failed to load skills","com_ui_skills_manual_invoked": "Manually invoked skills","com_ui_skills_queued": "Skills queued for next submission",diff --git a/packages/api/src/agents/__tests__/skills.test.ts b/packages/api/src/agents/__tests__/skills.test.tsindex b56b28667a..08b9c08bad 100644--- a/packages/api/src/agents/__tests__/skills.test.ts+++ b/packages/api/src/agents/__tests__/skills.test.ts@@ -31,6 +31,7 @@ import { HumanMessage, AIMessage } from '@langchain/core/messages';import {scopeSkillIds,resolveSkillActive,+ resolveAgentScopedSkillIds,injectSkillCatalog,buildSkillPrimeMessage,resolveManualSkills,@@ -293,6 +294,176 @@ describe('scopeSkillIds', () => {});});+describe('resolveAgentScopedSkillIds', () => {+ const makeId = () => new Types.ObjectId();+ const persistedAgent = (+ skills?: string[],+ skills_enabled?: boolean,+ ): { id: string; skills?: string[]; skills_enabled?: boolean } => ({+ id: 'agent_persisted_1',+ skills,+ skills_enabled,+ });+ const ephemeralAgent = (+ skills?: string[],+ ): { id: string; skills?: string[]; skills_enabled?: boolean } => ({+ id: 'ephemeral_convo_xyz',+ skills,+ });++ it('returns [] when the skills capability is disabled, even with every other signal on', () => {+ const a = makeId();+ expect(+ resolveAgentScopedSkillIds({+ agent: persistedAgent([a.toString()], true),+ accessibleSkillIds: [a],+ skillsCapabilityEnabled: false,+ ephemeralSkillsToggle: true,+ }),+ ).toEqual([]);+ });++ it('returns [] when accessibleSkillIds is empty', () => {+ expect(+ resolveAgentScopedSkillIds({+ agent: ephemeralAgent(),+ accessibleSkillIds: [],+ skillsCapabilityEnabled: true,+ ephemeralSkillsToggle: true,+ }),+ ).toEqual([]);+ });++ describe('ephemeral agent', () => {+ it('returns [] when the skills badge toggle is off', () => {+ const a = makeId();+ expect(+ resolveAgentScopedSkillIds({+ agent: ephemeralAgent(),+ accessibleSkillIds: [a],+ skillsCapabilityEnabled: true,+ ephemeralSkillsToggle: false,+ }),+ ).toEqual([]);+ });++ it('returns the full accessible catalog when the skills badge toggle is on', () => {+ const a = makeId();+ const b = makeId();+ const scoped = resolveAgentScopedSkillIds({+ agent: ephemeralAgent(),+ accessibleSkillIds: [a, b],+ skillsCapabilityEnabled: true,+ ephemeralSkillsToggle: true,+ });+ expect(scoped).toHaveLength(2);+ expect(scoped.map((o) => o.toString()).sort()).toEqual([a.toString(), b.toString()].sort());+ });++ it('ignores any `skills` field on an ephemeral agent (toggle is the only signal)', () => {+ const a = makeId();+ expect(+ resolveAgentScopedSkillIds({+ agent: ephemeralAgent([a.toString()]),+ accessibleSkillIds: [a],+ skillsCapabilityEnabled: true,+ ephemeralSkillsToggle: false,+ }),+ ).toEqual([]);+ });+ });++ describe('persisted agent', () => {+ it('returns [] when `skills_enabled` is undefined (default / never toggled)', () => {+ const a = makeId();+ expect(+ resolveAgentScopedSkillIds({+ agent: persistedAgent([a.toString()], undefined),+ accessibleSkillIds: [a],+ skillsCapabilityEnabled: true,+ ephemeralSkillsToggle: false,+ }),+ ).toEqual([]);+ });++ it('returns [] when `skills_enabled` is false, even if an allowlist is set', () => {+ const a = makeId();+ expect(+ resolveAgentScopedSkillIds({+ agent: persistedAgent([a.toString()], false),+ accessibleSkillIds: [a],+ skillsCapabilityEnabled: true,+ ephemeralSkillsToggle: false,+ }),+ ).toEqual([]);+ });++ it('returns full accessible catalog when `skills_enabled` is true and allowlist is undefined', () => {+ const a = makeId();+ const b = makeId();+ const scoped = resolveAgentScopedSkillIds({+ agent: persistedAgent(undefined, true),+ accessibleSkillIds: [a, b],+ skillsCapabilityEnabled: true,+ ephemeralSkillsToggle: false,+ });+ expect(scoped).toHaveLength(2);+ expect(scoped.map((o) => o.toString()).sort()).toEqual([a.toString(), b.toString()].sort());+ });++ it('returns full accessible catalog when `skills_enabled` is true and allowlist is empty', () => {+ const a = makeId();+ const b = makeId();+ const scoped = resolveAgentScopedSkillIds({+ agent: persistedAgent([], true),+ accessibleSkillIds: [a, b],+ skillsCapabilityEnabled: true,+ ephemeralSkillsToggle: false,+ });+ expect(scoped).toHaveLength(2);+ });++ it('returns intersection when `skills_enabled` is true and allowlist overlaps accessible set', () => {+ const a = makeId();+ const b = makeId();+ const c = makeId();+ const scoped = resolveAgentScopedSkillIds({+ agent: persistedAgent([a.toString(), c.toString()], true),+ accessibleSkillIds: [a, b, c],+ skillsCapabilityEnabled: true,+ ephemeralSkillsToggle: false,+ });+ expect(scoped).toHaveLength(2);+ expect(scoped.map((o) => o.toString()).sort()).toEqual([a.toString(), c.toString()].sort());+ });++ it('is unaffected by the ephemeral toggle — the persisted config is authoritative', () => {+ const a = makeId();+ const b = makeId();+ const scoped = resolveAgentScopedSkillIds({+ agent: persistedAgent([a.toString()], true),+ accessibleSkillIds: [a, b],+ skillsCapabilityEnabled: true,+ ephemeralSkillsToggle: true,+ });+ expect(scoped).toHaveLength(1);+ expect(scoped[0].toString()).toBe(a.toString());+ });++ it('still returns [] when `skills_enabled` is missing even if the ephemeral toggle is on', () => {+ const a = makeId();+ expect(+ resolveAgentScopedSkillIds({+ agent: persistedAgent(undefined, undefined),+ accessibleSkillIds: [a],+ skillsCapabilityEnabled: true,+ ephemeralSkillsToggle: true,+ }),+ ).toEqual([]);+ });+ });+});+describe('resolveSkillActive', () => {const makeSkill = (author: Types.ObjectId) => ({ _id: new Types.ObjectId(), author });diff --git a/packages/api/src/agents/skills.ts b/packages/api/src/agents/skills.tsindex c5ecd39eb9..2a0b88c1a1 100644--- a/packages/api/src/agents/skills.ts+++ b/packages/api/src/agents/skills.ts@@ -1,5 +1,6 @@import { logger } from '@librechat/data-schemas';import { HumanMessage } from '@langchain/core/messages';+import { isEphemeralAgentId } from 'librechat-data-provider';import { formatSkillCatalog, SkillToolDefinition } from '@librechat/agents';import type { LCToolRegistry, LCTool, InjectedMessage } from '@librechat/agents';import type { BaseMessage } from '@langchain/core/messages';@@ -101,6 +102,11 @@ export function isSkillPrimeMessage(msg: unknown): boolean {* the full catalog fallback.* - non-empty array of skill `_id` hex strings → intersection of accessible IDs* and agent-configured IDs.+ *+ * @internal Building block for {@link resolveAgentScopedSkillIds}; runtime+ * call sites should prefer the resolver so the activation predicate+ * (`skillsCapabilityEnabled`, ephemeral toggle, persisted `skills_enabled`)+ * is enforced uniformly.*/export function scopeSkillIds(accessibleSkillIds: Types.ObjectId[],@@ -116,6 +122,52 @@ export function scopeSkillIds(return accessibleSkillIds.filter((oid) => agentSet.has(oid.toString()));}+export interface ResolveAgentScopedSkillIdsParams {+ /** Agent being initialized. Reads `id`, `skills`, and `skills_enabled`. */+ agent: Pick<Agent, 'id' | 'skills' | 'skills_enabled'>;+ /** Full set of skill IDs the user can VIEW (pre-scoped by ACL). */+ accessibleSkillIds: Types.ObjectId[];+ /** Admin capability: `AgentCapabilities.skills` on the agents endpoint. */+ skillsCapabilityEnabled: boolean;+ /** Per-conversation skills badge toggle (`req.body.ephemeralAgent.skills`). */+ ephemeralSkillsToggle: boolean;+}++/**+ * Strict opt-in resolver for per-agent skill scope. Activation requires an+ * explicit signal from the user or the agent author:+ * - Ephemeral agent → the skills badge toggle for this conversation.+ * Toggle ON = full accessible catalog; OFF = no skills.+ * - Persisted agent → the builder's `skills_enabled` master switch.+ * Enabled + empty allowlist = full catalog; enabled + non-empty+ * allowlist = narrow to those ids; disabled (or undefined) = no skills.+ *+ * When not activated, returns `[]` so `injectSkillCatalog`,+ * `resolveManualSkills`, and `resolveAlwaysApplySkills` all no-op.+ *+ * Without this gate, an `agent.skills` of `undefined` on a persisted agent+ * would fall through to the "full catalog" branch of `scopeSkillIds`,+ * exposing the skill tool on runs where the author never opted in.+ */+export function resolveAgentScopedSkillIds(+ params: ResolveAgentScopedSkillIdsParams,+): Types.ObjectId[] {+ const { agent, accessibleSkillIds, skillsCapabilityEnabled, ephemeralSkillsToggle } = params;+ if (!skillsCapabilityEnabled || accessibleSkillIds.length === 0) {+ return [];+ }+ if (isEphemeralAgentId(agent.id)) {+ return ephemeralSkillsToggle ? scopeSkillIds(accessibleSkillIds, undefined) : [];+ }+ if (agent.skills_enabled !== true) {+ return [];+ }+ if (!Array.isArray(agent.skills) || agent.skills.length === 0) {+ return scopeSkillIds(accessibleSkillIds, undefined);+ }+ return scopeSkillIds(accessibleSkillIds, agent.skills);+}+export interface ResolveSkillActiveParams {/** Skill being evaluated. Only `_id` and `author` matter for resolution. */skill: { _id: Types.ObjectId | string; author: Types.ObjectId | string };diff --git a/packages/api/src/agents/validation.ts b/packages/api/src/agents/validation.tsindex 877614bf95..30b1da7d09 100644--- a/packages/api/src/agents/validation.ts+++ b/packages/api/src/agents/validation.ts@@ -99,6 +99,7 @@ export const agentBaseSchema = z.object({model_parameters: z.record(z.unknown()).optional(),tools: z.array(z.string()).optional(),skills: z.array(z.string()).optional(),+ skills_enabled: z.boolean().optional(),/** @deprecated Use edges instead */agent_ids: z.array(z.string()).optional(),edges: z.array(graphEdgeSchema).optional(),diff --git a/packages/data-provider/src/schemas.ts b/packages/data-provider/src/schemas.tsindex 9b52e3711d..c9f35d5d4b 100644--- a/packages/data-provider/src/schemas.ts+++ b/packages/data-provider/src/schemas.ts@@ -293,11 +293,12 @@ export const defaultAgentFormValues = {name: '',email: '',},- /** `undefined` = not configured, full catalog applies. `[]` = explicitly none.- * Keeping this `undefined` ensures a brand-new agent (where the user never- * interacted with the skills UI) does not accidentally persist "explicit none"- * on first save — removeNullishValues strips the field server-side. */+ /** Optional allowlist. Only applies when `skills_enabled === true`.+ * Empty/undefined + enabled = full catalog; non-empty + enabled = narrow to ids. */skills: undefined as string[] | undefined,+ /** Master toggle for skill use on this agent. `true` activates skills+ * (full catalog unless `skills` narrows it). Anything else = inactive. */+ skills_enabled: undefined as boolean | undefined,/** `undefined` = feature disabled by default (no subagent tool injected). */subagents: undefined as| { enabled?: boolean; allowSelf?: boolean; agent_ids?: string[] }diff --git a/packages/data-provider/src/types/assistants.ts b/packages/data-provider/src/types/assistants.tsindex 402a6de2af..b222c718ed 100644--- a/packages/data-provider/src/types/assistants.ts+++ b/packages/data-provider/src/types/assistants.ts@@ -288,8 +288,11 @@ export type Agent = {support_contact?: SupportContact;/** Per-tool configuration options (deferred loading, allowed callers, etc.) */tool_options?: AgentToolOptions;- /** Skill ObjectIds the agent can invoke — phase 2 wiring in AgentConfig. */+ /** Optional allowlist of skill ObjectIds. Only applies when `skills_enabled`. */skills?: string[];+ /** Master toggle for skill use on this agent. `true` = active (full catalog unless+ * `skills` narrows it). `false`/undefined = inactive (no skills available). */+ skills_enabled?: boolean;/** Subagent spawning configuration — isolated-context child agents. */subagents?: AgentSubagentsConfig;};@@ -318,6 +321,7 @@ export type AgentCreateParams = {| 'support_contact'| 'tool_options'| 'skills'+ | 'skills_enabled'| 'subagents'>;@@ -344,6 +348,7 @@ export type AgentUpdateParams = {| 'support_contact'| 'tool_options'| 'skills'+ | 'skills_enabled'| 'subagents'>;diff --git a/packages/data-schemas/src/methods/agent.ts b/packages/data-schemas/src/methods/agent.tsindex f09bf8460b..0ca518262b 100644--- a/packages/data-schemas/src/methods/agent.ts+++ b/packages/data-schemas/src/methods/agent.ts@@ -712,8 +712,11 @@ export function createAgentMethods(mongoose: typeof import('mongoose'), deps: Agsupport_contact: 1,is_promoted: 1,/* Needed so the client can scope the `$` skill popover to each agent's- configured catalog without refetching the full agent document. */+ configured catalog without refetching the full agent document. The+ master toggle is required alongside the allowlist so the popover can+ distinguish "enabled with full catalog" from "disabled". */skills: 1,+ skills_enabled: 1,}).sort({ updatedAt: -1, _id: 1 });if (isPaginated && normalizedLimit) {diff --git a/packages/data-schemas/src/schema/agent.ts b/packages/data-schemas/src/schema/agent.tsindex a6d893d628..33e1a92d6f 100644--- a/packages/data-schemas/src/schema/agent.ts+++ b/packages/data-schemas/src/schema/agent.ts@@ -48,6 +48,10 @@ const agentSchema = new Schema<IAgent>(type: [String],default: undefined,},+ skills_enabled: {+ type: Boolean,+ default: undefined,+ },tool_kwargs: {type: [{ type: Schema.Types.Mixed }],},diff --git a/packages/data-schemas/src/types/agent.ts b/packages/data-schemas/src/types/agent.tsindex f10b0ffe76..416112141d 100644--- a/packages/data-schemas/src/types/agent.ts+++ b/packages/data-schemas/src/types/agent.ts@@ -28,6 +28,7 @@ export interface IAgent extends Omit<Document, 'model'> {recursion_limit?: number;tools?: string[];skills?: string[];+ skills_enabled?: boolean;tool_kwargs?: Array<unknown>;actions?: string[];author: Types.ObjectId;