Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🛡️ feat: Let Admins Restrict Stateful Workspace Scopes (#14910)
Danny Avila57ea1137f66d
diff --git a/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js b/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.jsindex eda065cdf4..ceb1abb3ac 100644--- a/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js+++ b/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js@@ -1817,6 +1817,43 @@ describe('ResumableAgentController resume metadata', () => {);});+ it('preserves a stateful scope policy denial in the durable initialization error', async () => {+ const policyError = Object.assign(+ new Error('Stateful code environment is not allowed by this deployment: conversation'),+ {+ code: ErrorTypes.STATEFUL_CODE_ENVIRONMENT_NOT_ALLOWED,+ status: 403,+ statusCode: 403,+ },+ );+ const initializeClient = jest.fn().mockRejectedValue(policyError);+ const req = {+ user: { id: 'user-123' },+ body: {+ text: 'Run code.',+ messageId: 'user-msg',+ clientRequestId: 'req-abc',+ conversationId: 'conversation-123',+ endpointOption: { endpoint: 'agents', modelOptions: { model: 'gpt-4.1' } },+ },+ config: {},+ };+ const res = createResumableResponse();++ await AgentController(req, res, jest.fn(), initializeClient, null);++ expect(res.status).toHaveBeenCalledWith(200);+ expect(mockGenerationJobManager.completeJob).toHaveBeenCalledWith(+ 'conversation-123',+ JSON.stringify({+ status: 403,+ code: ErrorTypes.STATEFUL_CODE_ENVIRONMENT_NOT_ALLOWED,+ error: 'Stateful code environment is not allowed by this deployment: conversation',+ }),+ 1000,+ );+ });+it('returns a recovery conflict when the atomic store rejects changed source content', async () => {const mismatch = new Error('recovery mismatch');mismatch.code = 'RECOVERY_PAYLOAD_MISMATCH';diff --git a/api/server/controllers/agents/request.js b/api/server/controllers/agents/request.jsindex 2dbe305609..ce1bdf5db9 100644--- a/api/server/controllers/agents/request.js+++ b/api/server/controllers/agents/request.js@@ -50,15 +50,23 @@ function sendGenerationJson(res, status, body, generationProtocolVersion) {return res.status(status).json({ ...body, generationProtocolVersion });}-function getResourceRecoveryFailure(error) {- if (error?.code !== ErrorTypes.RESOURCE_RECOVERY_REQUIRED) {- return null;+function getInitializationFailure(error) {+ if (error?.code === ErrorTypes.RESOURCE_RECOVERY_REQUIRED) {+ return {+ status: 409,+ code: ErrorTypes.RESOURCE_RECOVERY_REQUIRED,+ error: error.message || 'Attached resources must be restored before retrying.',+ };}+ const candidateStatus = error?.status ?? error?.statusCode;+ if (!Number.isInteger(candidateStatus) || candidateStatus < 400 || candidateStatus >= 600) {+ return null;+ }return {- status: 409,- code: ErrorTypes.RESOURCE_RECOVERY_REQUIRED,- error: error.message || 'Attached resources must be restored before retrying.',+ status: candidateStatus,+ ...(typeof error?.code === 'string' ? { code: error.code } : {}),+ error: error?.message || 'Failed to start generation',};}@@ -1831,7 +1839,7 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTit});} catch (error) {logger.error('[ResumableAgentController] Initialization error:', error);- const resourceRecoveryFailure = getResourceRecoveryFailure(error);+ const initializationFailure = getInitializationFailure(error);try {if (!res.headersSent) {if (error?.code === 'GENERATION_PREDECESSOR_MISMATCH') {@@ -1872,11 +1880,11 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTit},generationProtocolVersion,);- } else if (resourceRecoveryFailure) {+ } else if (initializationFailure) {sendGenerationJson(res,- resourceRecoveryFailure.status,- resourceRecoveryFailure,+ initializationFailure.status,+ initializationFailure,generationProtocolVersion,);} else {@@ -1907,8 +1915,8 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTit// and the concurrency slot leaks — so swallow its error. (A failed completeJob did not// finalize anything, so releasing afterward can't let it abort a later replacement.)if (jobCreatedAt != null) {- const initializationError = resourceRecoveryFailure- ? JSON.stringify(resourceRecoveryFailure)+ const initializationError = initializationFailure+ ? JSON.stringify(initializationFailure): error.message || 'Failed to start generation';await GenerationJobManager.completeJob(streamId, initializationError, jobCreatedAt).catch((completeErr) => {diff --git a/api/server/controllers/agents/v1.js b/api/server/controllers/agents/v1.jsindex 3f6b4c5f53..6fc7450d61 100644--- a/api/server/controllers/agents/v1.js+++ b/api/server/controllers/agents/v1.js@@ -35,6 +35,7 @@ const {actionDelimiter,AgentCapabilities,EModelEndpoint,+ resolveAllowedStatefulCodeEnvironments,removeNullishValues,} = require('librechat-data-provider');const {@@ -201,6 +202,28 @@ const isSubagentsCapabilityEnabled = (req) => {return capabilities.includes(AgentCapabilities.subagents);};+/** Reject a newly selected stateful workspace scope that the deployment owner+ * has excluded. Disabled sessions and unrelated edits remain saveable so an+ * allowlist tightening never silently rewrites or strands an existing agent. */+const validateStatefulCodeEnvironment = (req, res, enabled, environment) => {+ if (enabled !== true) {+ return true;+ }++ const allowedEnvironments = resolveAllowedStatefulCodeEnvironments(+ req.config?.endpoints?.[EModelEndpoint.agents]?.statefulCodeSessions?.allowedEnvironments,+ );+ const resolvedEnvironment = environment ?? 'user';+ if (allowedEnvironments.includes(resolvedEnvironment)) {+ return true;+ }++ res.status(403).json({+ error: `Stateful code environment is not allowed by this deployment: ${resolvedEnvironment}`,+ });+ return false;+};+/*** Filters tools to only include those the user is authorized to use.* MCP tools must match the exact format `{toolName}_mcp_{serverName}` (exactly 2 segments).@@ -400,6 +423,17 @@ const createAgentHandler = async (req, res) => {const validatedData = agentCreateSchema.parse(req.body);const { tools = [], ...agentData } = removeNullishValues(validatedData);+ if (+ !validateStatefulCodeEnvironment(+ req,+ res,+ agentData.stateful_code_sessions,+ agentData.stateful_code_environment,+ )+ ) {+ return;+ }+if (agentData.model_parameters && typeof agentData.model_parameters === 'object') {agentData.model_parameters = removeNullishValues(sanitizeModelParameters(agentData.model_parameters),@@ -678,6 +712,46 @@ const updateAgentHandler = async (req, res) => {// Preserve explicit null for avatar to allow resetting the avatarconst { avatar: avatarField, _id, ...rest } = validatedData;const updateData = removeNullishValues(rest);+ let existingAgent;++ const includesStatefulConfiguration =+ updateData.stateful_code_sessions !== undefined ||+ updateData.stateful_code_environment !== undefined;+ const includesToolsConfiguration = Array.isArray(updateData.tools);+ if (includesStatefulConfiguration || includesToolsConfiguration) {+ existingAgent = await db.getAgent({ id });+ if (!existingAgent) {+ return res.status(404).json({ error: 'Agent not found' });+ }++ const statefulConfigurationChanged =+ (updateData.stateful_code_sessions !== undefined &&+ (updateData.stateful_code_sessions === true) !==+ (existingAgent.stateful_code_sessions === true)) ||+ (updateData.stateful_code_environment !== undefined &&+ (updateData.stateful_code_environment ?? 'user') !==+ (existingAgent.stateful_code_environment ?? 'user'));+ const activatesCodeExecution =+ includesToolsConfiguration &&+ updateData.tools.includes(Tools.execute_code) &&+ existingAgent.tools?.includes(Tools.execute_code) !== true;+ if (statefulConfigurationChanged || activatesCodeExecution) {+ const effectiveStatefulSessions =+ updateData.stateful_code_sessions ?? existingAgent.stateful_code_sessions;+ const effectiveStatefulEnvironment =+ updateData.stateful_code_environment ?? existingAgent.stateful_code_environment;+ if (+ !validateStatefulCodeEnvironment(+ req,+ res,+ effectiveStatefulSessions,+ effectiveStatefulEnvironment,+ )+ ) {+ return;+ }+ }+ }if (updateData.model_parameters && typeof updateData.model_parameters === 'object') {updateData.model_parameters = removeNullishValues(@@ -750,7 +824,7 @@ const updateAgentHandler = async (req, res) => {// Convert OCR to context in incoming updateDataconvertOcrToContextInPlace(updateData);- const existingAgent = await db.getAgent({ id });+ existingAgent ??= await db.getAgent({ id });if (!existingAgent) {return res.status(404).json({ error: 'Agent not found' });@@ -964,6 +1038,16 @@ const duplicateAgentHandler = async (req, res) => {id: newAgentId,author: userId,});+ if (+ !validateStatefulCodeEnvironment(+ req,+ res,+ newAgentData.stateful_code_sessions,+ newAgentData.stateful_code_environment,+ )+ ) {+ return;+ }newAgentData.edges = replaceEdgeSourceId(newAgentData.edges, id, newAgentId);newAgentData.edges = replaceEdgeSourceId(newAgentData.edges, '', newAgentId);@@ -1498,6 +1582,17 @@ const revertAgentVersionHandler = async (req, res) => {}const revertVersion = existingAgent.versions?.[version_index];+ if (+ revertVersion &&+ !validateStatefulCodeEnvironment(+ req,+ res,+ revertVersion.stateful_code_sessions,+ revertVersion.stateful_code_environment,+ )+ ) {+ return;+ }const storedRevertEdges = Array.isArray(revertVersion?.edges) ? revertVersion.edges : [];const revertEdges = replaceEdgeSourceId(storedRevertEdges, '', id);const hasLegacyEdgeSource = storedRevertEdges.some((edge) =>diff --git a/api/server/controllers/agents/v1.spec.js b/api/server/controllers/agents/v1.spec.jsindex 67000ea4b3..cec5412f69 100644--- a/api/server/controllers/agents/v1.spec.js+++ b/api/server/controllers/agents/v1.spec.js@@ -3,6 +3,7 @@ const { nanoid } = require('nanoid');const { v4: uuidv4 } = require('uuid');const { agentSchema, aclEntrySchema, fileSchema, userSchema } = require('@librechat/data-schemas');const {+ Tools,FileSources,PermissionBits,PrincipalModel,@@ -181,6 +182,28 @@ describe('Agent Controllers - Mass Assignment Protection', () => {});describe('createAgentHandler', () => {+ test('rejects a stateful environment excluded by deployment policy', async () => {+ mockReq.config = {+ endpoints: {+ agents: {+ statefulCodeSessions: { allowedEnvironments: ['user'] },+ },+ },+ };+ mockReq.body = {+ name: 'Disallowed Stateful Agent',+ provider: 'openai',+ model: 'gpt-4',+ stateful_code_sessions: true,+ stateful_code_environment: 'conversation',+ };++ await createAgentHandler(mockReq, mockRes);++ expect(mockRes.status).toHaveBeenCalledWith(403);+ expect(await Agent.countDocuments()).toBe(0);+ });+test('should create agent with allowed fields only', async () => {const validData = {name: 'Test Agent',@@ -801,6 +824,83 @@ describe('Agent Controllers - Mass Assignment Protection', () => {expect(agentInDb.name).toBe('Updated Agent');});+ test('rejects selecting a stateful environment excluded by deployment policy', async () => {+ mockReq.user.id = existingAgentAuthorId.toString();+ mockReq.params.id = existingAgentId;+ mockReq.config = {+ endpoints: {+ agents: {+ statefulCodeSessions: { allowedEnvironments: ['user'] },+ },+ },+ };+ mockReq.body = {+ stateful_code_sessions: true,+ stateful_code_environment: 'conversation',+ };++ await updateAgentHandler(mockReq, mockRes);++ expect(mockRes.status).toHaveBeenCalledWith(403);+ const agentInDb = await Agent.findOne({ id: existingAgentId });+ expect(agentInDb.stateful_code_sessions).not.toBe(true);+ });++ test('allows unrelated edits to an existing scope after policy is tightened', async () => {+ await Agent.updateOne(+ { id: existingAgentId },+ { stateful_code_sessions: true, stateful_code_environment: 'conversation' },+ );+ mockReq.user.id = existingAgentAuthorId.toString();+ mockReq.params.id = existingAgentId;+ mockReq.config = {+ endpoints: {+ agents: {+ statefulCodeSessions: { allowedEnvironments: ['user'] },+ },+ },+ };+ mockReq.body = {+ name: 'Still editable',+ stateful_code_sessions: true,+ stateful_code_environment: 'conversation',+ };++ await updateAgentHandler(mockReq, mockRes);++ expect(mockRes.status).not.toHaveBeenCalledWith(403);+ const agentInDb = await Agent.findOne({ id: existingAgentId });+ expect(agentInDb.name).toBe('Still editable');+ expect(agentInDb.stateful_code_environment).toBe('conversation');+ });++ test('rejects reactivating code execution with a retained disallowed scope', async () => {+ await Agent.updateOne(+ { id: existingAgentId },+ {+ tools: [],+ stateful_code_sessions: true,+ stateful_code_environment: 'conversation',+ },+ );+ mockReq.user.id = existingAgentAuthorId.toString();+ mockReq.params.id = existingAgentId;+ mockReq.config = {+ endpoints: {+ agents: {+ statefulCodeSessions: { allowedEnvironments: ['user'] },+ },+ },+ };+ mockReq.body = { tools: [Tools.execute_code] };++ await updateAgentHandler(mockReq, mockRes);++ expect(mockRes.status).toHaveBeenCalledWith(403);+ const agentInDb = await Agent.findOne({ id: existingAgentId });+ expect(agentInDb.tools).not.toContain(Tools.execute_code);+ });+test('should sanitize corrupt numeric model_parameters on update', async () => {mockReq.user.id = existingAgentAuthorId.toString();mockReq.params.id = existingAgentId;diff --git a/api/server/routes/agents/v1.js b/api/server/routes/agents/v1.jsindex 233839dcf4..6812dde46c 100644--- a/api/server/routes/agents/v1.js+++ b/api/server/routes/agents/v1.js@@ -46,7 +46,7 @@ router.get('/categories', v1.getAgentCategories);* @param {AgentCreateParams} req.body - The agent creation parameters.* @returns {Agent} 201 - Success response - application/json*/-router.post('/', checkAgentCreate, v1.createAgent);+router.post('/', checkAgentCreate, configMiddleware, v1.createAgent);/*** Retrieves basic agent information (VIEW permission required).@@ -108,6 +108,7 @@ router.get(router.patch('/:id',checkAgentCreate,+ configMiddleware,canAccessAgentResource({requiredPermission: PermissionBits.EDIT,resourceIdParam: 'id',@@ -124,6 +125,7 @@ router.patch(router.post('/:id/duplicate',checkAgentCreate,+ configMiddleware,canAccessAgentResource({requiredPermission: PermissionBits.EDIT,resourceIdParam: 'id',@@ -157,6 +159,7 @@ router.delete(router.post('/:id/revert',checkAgentCreate,+ configMiddleware,canAccessAgentResource({requiredPermission: PermissionBits.EDIT,resourceIdParam: 'id',diff --git a/api/server/routes/user.js b/api/server/routes/user.jsindex 90f247cd36..4107e410c7 100644--- a/api/server/routes/user.js+++ b/api/server/routes/user.js@@ -28,7 +28,7 @@ const updateUserPreferences = createUserPreferencesHandler({router.use('/settings', settings);router.get('/', requireJwtAuth, getUserController);-router.patch('/preferences', requireJwtAuth, updateUserPreferences);+router.patch('/preferences', requireJwtAuth, configMiddleware, updateUserPreferences);router.get('/terms', requireJwtAuth, getTermsStatusController);router.post('/terms/accept', requireJwtAuth, acceptTermsController);router.post('/plugins', requireJwtAuth, updateUserPluginsController);diff --git a/api/server/services/Endpoints/agents/initialize.js b/api/server/services/Endpoints/agents/initialize.jsindex a75683a4b8..5110a8b7bd 100644--- a/api/server/services/Endpoints/agents/initialize.js+++ b/api/server/services/Endpoints/agents/initialize.js@@ -20,6 +20,7 @@ const {buildAgentContextAttachmentsByAgentId,collectCodeExecutionProfileRoutes,getLazySubagentConfigId,+ createStatefulCodeEnvironmentPolicyError,} = require('@librechat/api');const {Permissions,@@ -34,6 +35,7 @@ const {MAX_SUBAGENT_GRAPH_NODES,MAX_SUBAGENT_RUN_CONFIGS,isEphemeralAgentId,+ resolveAllowedStatefulCodeEnvironments,} = require('librechat-data-provider');const {createToolEndCallback,@@ -194,6 +196,9 @@ const initializeClient = async ({const statefulSessionsAvailable = enabledCapabilities.has(AgentCapabilities.stateful_code_sessions,);+ const allowedStatefulCodeEnvironments = resolveAllowedStatefulCodeEnvironments(+ appConfig?.endpoints?.[EModelEndpoint.agents]?.statefulCodeSessions?.allowedEnvironments,+ );const ephemeralSkillsToggle = req.body?.ephemeralAgent?.skills === true;const skillDbMethods = getSkillDbMethods();@@ -807,26 +812,36 @@ const initializeClient = async ({),);- const toLazySubagentMetadata = (agent) => ({- id: agent.id,- name: agent.name,- description: agent.description,- provider: agent.provider,- model: agent.model,- model_parameters: { model: agent.model_parameters?.model },- recursion_limit: agent.recursion_limit,- subagents: agent.subagents,- configId: getLazySubagentConfigId(agent),- codeEnvAvailable:- codeEnvAvailable === true && agent.tools?.includes(Tools.execute_code) === true,- statefulCodeSessions:+ const toLazySubagentMetadata = (agent) => {+ const statefulCodeSessions =statefulSessionsAvailable === true &&codeEnvAvailable === true &&agent.stateful_code_sessions === true &&- agent.tools?.includes(Tools.execute_code) === true,- statefulCodeEnvironment: agent.stateful_code_environment,- includeReasoningHistory: getIncludeReasoningHistory(agent),- });+ agent.tools?.includes(Tools.execute_code) === true;+ const statefulCodeEnvironment = agent.stateful_code_environment ?? 'user';+ if (+ statefulCodeSessions &&+ !allowedStatefulCodeEnvironments.includes(statefulCodeEnvironment)+ ) {+ throw createStatefulCodeEnvironmentPolicyError(statefulCodeEnvironment);+ }+ return {+ id: agent.id,+ name: agent.name,+ description: agent.description,+ provider: agent.provider,+ model: agent.model,+ model_parameters: { model: agent.model_parameters?.model },+ recursion_limit: agent.recursion_limit,+ subagents: agent.subagents,+ configId: getLazySubagentConfigId(agent),+ codeEnvAvailable:+ codeEnvAvailable === true && agent.tools?.includes(Tools.execute_code) === true,+ statefulCodeSessions,+ statefulCodeEnvironment,+ includeReasoningHistory: getIncludeReasoningHistory(agent),+ };+ };const loadSubagentMetadata = async (agentId) => {if (skippedAgentIds.has(agentId)) return null;diff --git a/api/server/services/Endpoints/agents/initialize.spec.js b/api/server/services/Endpoints/agents/initialize.spec.jsindex a8ff3840f1..2152892fe8 100644--- a/api/server/services/Endpoints/agents/initialize.spec.js+++ b/api/server/services/Endpoints/agents/initialize.spec.js@@ -62,7 +62,11 @@ jest.mock('~/server/services/ToolService', () => ({loadAgentTools: jest.fn(),loadToolsForExecution: (...args) => mockLoadToolsForExecution(...args),isFatalAgentInitializationError: (error) =>- ['AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE', 'resource_recovery_required'].includes(error?.code),+ [+ 'AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE',+ 'resource_recovery_required',+ 'stateful_code_environment_not_allowed',+ ].includes(error?.code),}));jest.mock('~/server/controllers/ModelController', () => ({@@ -859,6 +863,42 @@ describe('initializeClient — subagent loading', () => {expect(agentClientArgs.agentConfigs.has(SUBAGENT_ID)).toBe(false);});+ it('rejects a disallowed lazy subagent scope before exposing it for prewarm', async () => {+ const subAgent = await createAgent({+ id: SUBAGENT_ID,+ name: 'Disallowed Stateful Subagent',+ provider: 'openai',+ model: 'gpt-4',+ author: new mongoose.Types.ObjectId(),+ tools: ['execute_code'],+ stateful_code_sessions: true,+ stateful_code_environment: 'conversation',+ });+ await grantView(subAgent);+ mockInitializeAgent.mockResolvedValue(+ makePrimaryConfig({+ subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },+ }),+ );+ const req = makeSubagentReq();+ req.config.endpoints.agents.capabilities.push('execute_code', 'stateful_code_sessions');+ req.config.endpoints.agents.statefulCodeSessions = { allowedEnvironments: ['user'] };++ await expect(+ initializeClient({+ req,+ res: {},+ signal: new AbortController().signal,+ endpointOption: makeEndpointOption(),+ }),+ ).rejects.toMatchObject({+ code: ErrorTypes.STATEFUL_CODE_ENVIRONMENT_NOT_ALLOWED,+ });++ expect(agentClientArgs).toBeUndefined();+ expect(mockInitializeAgent).toHaveBeenCalledTimes(1);+ });+it('omits a descriptor when its metadata lookup fails without aborting the primary run', async () => {const primaryConfig = makePrimaryConfig({subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },diff --git a/client/src/components/Nav/Settings/StatefulWorkspaceDefault.tsx b/client/src/components/Nav/Settings/StatefulWorkspaceDefault.tsxindex 2d2f2c5857..4057336614 100644--- a/client/src/components/Nav/Settings/StatefulWorkspaceDefault.tsx+++ b/client/src/components/Nav/Settings/StatefulWorkspaceDefault.tsx@@ -7,18 +7,34 @@ import {SelectTrigger,useToastContext,} from '@librechat/client';-+import {+ STATEFUL_CODE_ENVIRONMENTS,+ resolveAllowedStatefulCodeEnvironments,+ resolveStatefulCodeEnvironment,+} from 'librechat-data-provider';import type { StatefulCodeEnvironment } from 'librechat-data-provider';import { useGetUserQuery, useUpdateUserPreferencesMutation } from '~/data-provider';-import { useLocalize } from '~/hooks';+import { useGetAgentsConfig, useLocalize } from '~/hooks';const FALLBACK_ENVIRONMENT: StatefulCodeEnvironment = 'user';+const ENVIRONMENT_LABELS = {+ user: 'com_ui_stateful_code_environment_user',+ 'agent-user': 'com_ui_stateful_code_environment_agent_user',+ conversation: 'com_ui_stateful_code_environment_conversation',+} as const;export default function StatefulWorkspaceDefault() {const localize = useLocalize();const { showToast } = useToastContext();const { data: user } = useGetUserQuery();- const savedEnvironment = user?.personalization?.statefulCodeEnvironment ?? FALLBACK_ENVIRONMENT;+ const { agentsConfig } = useGetAgentsConfig();+ const configuredEnvironments = agentsConfig?.statefulCodeSessions?.allowedEnvironments;+ const allowedEnvironments = resolveAllowedStatefulCodeEnvironments(configuredEnvironments);+ const savedPreference = user?.personalization?.statefulCodeEnvironment;+ const savedEnvironment =+ savedPreference ??+ resolveStatefulCodeEnvironment(FALLBACK_ENVIRONMENT, configuredEnvironments) ??+ FALLBACK_ENVIRONMENT;const [environment, setEnvironment] = useState<StatefulCodeEnvironment>(savedEnvironment);useEffect(() => {@@ -36,6 +52,9 @@ export default function StatefulWorkspaceDefault() {const handleChange = (value: string) => {const statefulCodeEnvironment = value as StatefulCodeEnvironment;+ if (!allowedEnvironments.includes(statefulCodeEnvironment)) {+ return;+ }setEnvironment(statefulCodeEnvironment);mutation.mutate({ statefulCodeEnvironment });};@@ -61,13 +80,18 @@ export default function StatefulWorkspaceDefault() {<SelectValue /></SelectTrigger><SelectContent>- <SelectItem value="user">{localize('com_ui_stateful_code_environment_user')}</SelectItem>- <SelectItem value="agent-user">- {localize('com_ui_stateful_code_environment_agent_user')}- </SelectItem>- <SelectItem value="conversation">- {localize('com_ui_stateful_code_environment_conversation')}- </SelectItem>+ {STATEFUL_CODE_ENVIRONMENTS.filter(+ (candidate) =>+ allowedEnvironments.includes(candidate) || candidate === savedEnvironment,+ ).map((candidate) => (+ <SelectItem+ key={candidate}+ value={candidate}+ disabled={!allowedEnvironments.includes(candidate)}+ >+ {localize(ENVIRONMENT_LABELS[candidate])}+ </SelectItem>+ ))}</SelectContent></Select></div>diff --git a/client/src/components/Nav/Settings/__tests__/StatefulWorkspaceDefault.spec.tsx b/client/src/components/Nav/Settings/__tests__/StatefulWorkspaceDefault.spec.tsxindex adfe650432..9e3773a5d3 100644--- a/client/src/components/Nav/Settings/__tests__/StatefulWorkspaceDefault.spec.tsx+++ b/client/src/components/Nav/Settings/__tests__/StatefulWorkspaceDefault.spec.tsx@@ -5,6 +5,7 @@ import StatefulWorkspaceDefault from '../StatefulWorkspaceDefault';const mockMutate = jest.fn();const mockShowToast = jest.fn();+let mockAllowedEnvironments: Array<'user' | 'agent-user' | 'conversation'> | undefined;jest.mock('@librechat/client', () => ({Select: ({@@ -30,14 +31,33 @@ jest.mock('@librechat/client', () => ({SelectTrigger: ({ children }: { children: ReactNode }) => children,SelectValue: () => null,SelectContent: ({ children }: { children: ReactNode }) => children,- SelectItem: ({ value, children }: { value: string; children: ReactNode }) => (- <option value={value}>{children}</option>+ SelectItem: ({+ value,+ children,+ disabled,+ }: {+ value: string;+ children: ReactNode;+ disabled?: boolean;+ }) => (+ <option value={value} disabled={disabled}>+ {children}+ </option>),useToastContext: () => ({ showToast: mockShowToast }),}));jest.mock('~/hooks', () => ({useLocalize: () => (key: string) => key,+ useGetAgentsConfig: () => ({+ agentsConfig: {+ capabilities: ['stateful_code_sessions'],+ statefulCodeSessions:+ mockAllowedEnvironments == null+ ? undefined+ : { allowedEnvironments: mockAllowedEnvironments },+ },+ }),}));jest.mock('~/data-provider', () => ({@@ -53,6 +73,7 @@ jest.mock('~/data-provider', () => ({describe('StatefulWorkspaceDefault', () => {beforeEach(() => {mockMutate.mockClear();+ mockAllowedEnvironments = undefined;});it('shows the saved user preference', () => {@@ -71,4 +92,20 @@ describe('StatefulWorkspaceDefault', () => {expect(mockMutate).toHaveBeenCalledWith({ statefulCodeEnvironment: 'conversation' });});++ it('only enables deployment-allowed scopes while preserving the saved value', () => {+ mockAllowedEnvironments = ['user'];++ render(<StatefulWorkspaceDefault />);++ expect(+ screen.getByRole('option', { name: 'com_ui_stateful_code_environment_user' }),+ ).toBeEnabled();+ expect(+ screen.getByRole('option', { name: 'com_ui_stateful_code_environment_agent_user' }),+ ).toBeDisabled();+ expect(+ screen.queryByRole('option', { name: 'com_ui_stateful_code_environment_conversation' }),+ ).not.toBeInTheDocument();+ });});diff --git a/client/src/components/SidePanel/Agents/Advanced/StatefulSessions.tsx b/client/src/components/SidePanel/Agents/Advanced/StatefulSessions.tsxindex 4fce6a8633..77d6445e59 100644--- a/client/src/components/SidePanel/Agents/Advanced/StatefulSessions.tsx+++ b/client/src/components/SidePanel/Agents/Advanced/StatefulSessions.tsx@@ -1,5 +1,10 @@import { useFormContext } from 'react-hook-form';-import { AgentCapabilities } from 'librechat-data-provider';+import {+ AgentCapabilities,+ STATEFUL_CODE_ENVIRONMENTS,+ resolveStatefulCodeEnvironment,+ resolveAllowedStatefulCodeEnvironments,+} from 'librechat-data-provider';import {Switch,Select,@@ -15,25 +20,38 @@ import {} from '@librechat/client';import type { StatefulCodeEnvironment } from 'librechat-data-provider';import type { AgentForm } from '~/common';-import { useAuthContext, useLocalize } from '~/hooks';+import { useAuthContext, useGetAgentsConfig, useLocalize } from '~/hooks';import { ESide } from '~/common';+const ENVIRONMENT_LABELS = {+ user: 'com_ui_stateful_code_environment_user',+ 'agent-user': 'com_ui_stateful_code_environment_agent_user',+ conversation: 'com_ui_stateful_code_environment_conversation',+} as const;+export default function StatefulSessions() {const localize = useLocalize();const { user } = useAuthContext();+ const { agentsConfig } = useGetAgentsConfig();const methods = useFormContext<AgentForm>();const { setValue, watch } = methods;const enabled = watch(AgentCapabilities.stateful_code_sessions) ?? false;const codeEnabled = watch(AgentCapabilities.execute_code);const environment = watch('stateful_code_environment') ?? 'user';+ const configuredEnvironments = agentsConfig?.statefulCodeSessions?.allowedEnvironments;+ const allowedEnvironments = resolveAllowedStatefulCodeEnvironments(configuredEnvironments);const handleChange = (value: boolean) => {setValue(AgentCapabilities.stateful_code_sessions, value, { shouldDirty: true });- if (value && !watch('stateful_code_environment')) {+ const currentEnvironment = watch('stateful_code_environment');+ if (value && (!currentEnvironment || !allowedEnvironments.includes(currentEnvironment))) {setValue('stateful_code_environment',- user?.personalization?.statefulCodeEnvironment ?? 'user',+ resolveStatefulCodeEnvironment(+ user?.personalization?.statefulCodeEnvironment ?? 'user',+ configuredEnvironments,+ ) ?? 'user',{ shouldDirty: true },);}@@ -81,25 +99,28 @@ export default function StatefulSessions() {</label><Selectvalue={environment}- onValueChange={(value) =>- setValue('stateful_code_environment', value as StatefulCodeEnvironment, {- shouldDirty: true,- })- }+ onValueChange={(value) => {+ const nextEnvironment = value as StatefulCodeEnvironment;+ if (allowedEnvironments.includes(nextEnvironment)) {+ setValue('stateful_code_environment', nextEnvironment, { shouldDirty: true });+ }+ }}><SelectTrigger id="stateful-code-environment" data-testid="stateful-code-environment"><SelectValue /></SelectTrigger><SelectContent>- <SelectItem value="user">- {localize('com_ui_stateful_code_environment_user')}- </SelectItem>- <SelectItem value="agent-user">- {localize('com_ui_stateful_code_environment_agent_user')}- </SelectItem>- <SelectItem value="conversation">- {localize('com_ui_stateful_code_environment_conversation')}- </SelectItem>+ {STATEFUL_CODE_ENVIRONMENTS.filter(+ (candidate) => allowedEnvironments.includes(candidate) || candidate === environment,+ ).map((candidate) => (+ <SelectItem+ key={candidate}+ value={candidate}+ disabled={!allowedEnvironments.includes(candidate)}+ >+ {localize(ENVIRONMENT_LABELS[candidate])}+ </SelectItem>+ ))}</SelectContent></Select><p className="text-xs text-text-tertiary">diff --git a/client/src/components/SidePanel/Agents/AgentPanel.tsx b/client/src/components/SidePanel/Agents/AgentPanel.tsxindex 99e8938374..4dc9226015 100644--- a/client/src/components/SidePanel/Agents/AgentPanel.tsx+++ b/client/src/components/SidePanel/Agents/AgentPanel.tsx@@ -11,6 +11,7 @@ import {ResourceType,EModelEndpoint,PermissionBits,+ resolveStatefulCodeEnvironment,isAssistantsEndpoint,} from 'librechat-data-provider';import type { Agent, AgentUpdateParams } from 'librechat-data-provider';@@ -286,7 +287,11 @@ export default function AgentPanel() {setCurrentAgentId,agent_id: current_agent_id,} = useAgentPanelContext();- const defaultStatefulCodeEnvironment = user?.personalization?.statefulCodeEnvironment ?? 'user';+ const defaultStatefulCodeEnvironment =+ resolveStatefulCodeEnvironment(+ user?.personalization?.statefulCodeEnvironment ?? 'user',+ agentsConfig?.statefulCodeSessions?.allowedEnvironments,+ ) ?? 'user';const { onSelect: onSelectAgent } = useSelectAgent();diff --git a/client/src/components/SidePanel/Agents/DeleteButton.tsx b/client/src/components/SidePanel/Agents/DeleteButton.tsxindex fba6059975..93da129175 100644--- a/client/src/components/SidePanel/Agents/DeleteButton.tsx+++ b/client/src/components/SidePanel/Agents/DeleteButton.tsx@@ -1,6 +1,7 @@import { memo } from 'react';import { useFormContext } from 'react-hook-form';import { useRecoilValue, useSetRecoilState } from 'recoil';+import { resolveStatefulCodeEnvironment } from 'librechat-data-provider';import {Label,Button,@@ -12,9 +13,9 @@ import {} from '@librechat/client';import type { Agent, AgentCreateParams } from 'librechat-data-provider';import type { UseMutationResult } from '@tanstack/react-query';+import { useAuthContext, useGetAgentsConfig, useLocalize } from '~/hooks';import { logger, getDefaultAgentFormValues } from '~/utils';import { useDeleteAgentMutation } from '~/data-provider';-import { useAuthContext, useLocalize } from '~/hooks';import { isEphemeralAgent } from '~/common';import store from '~/store';@@ -29,6 +30,7 @@ function DeleteButton({}) {const localize = useLocalize();const { user } = useAuthContext();+ const { agentsConfig } = useGetAgentsConfig();const { reset } = useFormContext();const { showToast } = useToastContext();const setConversation = useSetRecoilState(store.conversationByIndex(0));@@ -54,7 +56,14 @@ function DeleteButton({const firstAgent = updatedList[0] as Agent | undefined;if (!firstAgent) {setCurrentAgentId(undefined);- reset(getDefaultAgentFormValues(user?.personalization?.statefulCodeEnvironment ?? 'user'));+ reset(+ getDefaultAgentFormValues(+ resolveStatefulCodeEnvironment(+ user?.personalization?.statefulCodeEnvironment ?? 'user',+ agentsConfig?.statefulCodeSessions?.allowedEnvironments,+ ) ?? 'user',+ ),+ );setConversation((prev) => (prev ? { ...prev, agent_id: '' } : prev));return;}diff --git a/librechat.example.yaml b/librechat.example.yamlindex 7be6cdc698..493ba92060 100644--- a/librechat.example.yaml+++ b/librechat.example.yaml@@ -503,6 +503,9 @@ endpoints:# # The following capabilities are opt-in and must be added explicitly:# # "programmatic_tools", "stateful_code_sessions", "run_in_background", "tool_intents"# # "stateful_code_sessions" is highly experimental and may change substantially.+ # # (optional) Limit the workspace scopes users may select. Omit to allow all three.+ # statefulCodeSessions:+ # allowedEnvironments: ["user", "agent-user", "conversation"]# # "run_in_background" makes Code Interpreter tools eligible by default and enables per-tool MCP opt-in.# # "tool_intents" enables live model-written labels for native tools and opted-in MCP tools.# # (optional) Require user approval before matching tool calls. Disabled by default.diff --git a/packages/api/src/agents/__tests__/initialize.test.ts b/packages/api/src/agents/__tests__/initialize.test.tsindex fb0ff6de28..8138eb2e04 100644--- a/packages/api/src/agents/__tests__/initialize.test.ts+++ b/packages/api/src/agents/__tests__/initialize.test.ts@@ -110,6 +110,7 @@ jest.mock('../resources', () => ({}));import { initializeAgent } from '../initialize';+import { isFatalAgentInitializationError } from '../errors';const realUtils = jest.requireActual<typeof import('~/utils')>('~/utils');@@ -1782,6 +1783,74 @@ describe('initializeAgent — execute_code capability expansion', () => {}});+ it('rejects a stateful environment excluded by deployment policy', async () => {+ const { agent, req, res, loadTools, db } = createMocks();+ agent.tools = ['execute_code'];+ agent.stateful_code_sessions = true;+ agent.stateful_code_environment = 'conversation';+ req.config = {+ endpoints: {+ [EModelEndpoint.agents]: {+ statefulCodeSessions: { allowedEnvironments: ['user'] },+ },+ },+ } as NonNullable<typeof req.config>;++ let error;+ try {+ await initializeAgent(+ {+ req,+ res,+ agent,+ loadTools,+ endpointOption: { endpoint: EModelEndpoint.agents },+ allowedProviders: new Set([Providers.OPENAI]),+ isInitialAgent: true,+ codeEnvAvailable: true,+ statefulSessionsAvailable: true,+ },+ db,+ );+ } catch (caught) {+ error = caught;+ }++ expect(error).toMatchObject({+ code: ErrorTypes.STATEFUL_CODE_ENVIRONMENT_NOT_ALLOWED,+ message: 'Stateful code environment is not allowed by this deployment: conversation',+ });+ expect(isFatalAgentInitializationError(error)).toBe(true);+ expect(loadTools).not.toHaveBeenCalled();+ });++ it('uses an explicit stateful environment allowlist when req.config is unavailable', async () => {+ const { agent, req, res, loadTools, db } = createMocks();+ agent.tools = ['execute_code'];+ agent.stateful_code_sessions = true;+ agent.stateful_code_environment = 'conversation';+ req.config = undefined;++ await expect(+ initializeAgent(+ {+ req,+ res,+ agent,+ loadTools,+ endpointOption: { endpoint: EModelEndpoint.agents },+ allowedProviders: new Set([Providers.OPENAI]),+ isInitialAgent: true,+ codeEnvAvailable: true,+ statefulSessionsAvailable: true,+ allowedStatefulCodeEnvironments: ['user'],+ },+ db,+ ),+ ).rejects.toMatchObject({ code: ErrorTypes.STATEFUL_CODE_ENVIRONMENT_NOT_ALLOWED });+ expect(loadTools).not.toHaveBeenCalled();+ });+it('upgrades read_file to the skill-aware description when active skills are in scope', async () => {const { agent, req, res, loadTools, db } = createMocks();agent.tools = ['execute_code'];diff --git a/packages/api/src/agents/errors.spec.ts b/packages/api/src/agents/errors.spec.tsindex b2c88a25c7..e75982b3af 100644--- a/packages/api/src/agents/errors.spec.ts+++ b/packages/api/src/agents/errors.spec.ts@@ -2,12 +2,13 @@ import { ErrorTypes } from 'librechat-data-provider';import { AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE, isFatalAgentInitializationError } from './errors';describe('isFatalAgentInitializationError', () => {- it.each([ErrorTypes.RESOURCE_RECOVERY_REQUIRED, AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE])(- 'classifies %s as fatal',- (code) => {- expect(isFatalAgentInitializationError({ code })).toBe(true);- },- );+ it.each([+ ErrorTypes.RESOURCE_RECOVERY_REQUIRED,+ ErrorTypes.STATEFUL_CODE_ENVIRONMENT_NOT_ALLOWED,+ AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE,+ ])('classifies %s as fatal', (code) => {+ expect(isFatalAgentInitializationError({ code })).toBe(true);+ });it('allows skill-added MCP tools to fall back while keeping resource recovery fatal', () => {const options = { allowExpectedMCPFallback: true };diff --git a/packages/api/src/agents/errors.ts b/packages/api/src/agents/errors.tsindex b1809a094d..bb3e6aef49 100644--- a/packages/api/src/agents/errors.ts+++ b/packages/api/src/agents/errors.ts@@ -2,6 +2,17 @@ import { ErrorTypes } from 'librechat-data-provider';export const AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE = 'AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE';+export function createStatefulCodeEnvironmentPolicyError(environment: string): Error {+ return Object.assign(+ new Error(`Stateful code environment is not allowed by this deployment: ${environment}`),+ {+ code: ErrorTypes.STATEFUL_CODE_ENVIRONMENT_NOT_ALLOWED,+ status: 403,+ statusCode: 403,+ },+ );+}+export interface FatalAgentInitializationOptions {/*** Skill `allowed-tools` may add an MCP tool beyond the agent's configured@@ -31,6 +42,7 @@ export function isFatalAgentInitializationError(const code = getErrorCode(error);return (code === ErrorTypes.RESOURCE_RECOVERY_REQUIRED ||+ code === ErrorTypes.STATEFUL_CODE_ENVIRONMENT_NOT_ALLOWED ||(code === AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE && options.allowExpectedMCPFallback !== true));}diff --git a/packages/api/src/agents/initialize.ts b/packages/api/src/agents/initialize.tsindex c38d96260d..7e49a30a91 100644--- a/packages/api/src/agents/initialize.ts+++ b/packages/api/src/agents/initialize.ts@@ -9,6 +9,7 @@ import {paramEndpoints,isAgentsEndpoint,AgentCapabilities,+ resolveAllowedStatefulCodeEnvironments,replaceSpecialVars,providerEndpointMap,} from 'librechat-data-provider';@@ -20,6 +21,7 @@ import type {TFile,Agent,TUser,+ StatefulCodeEnvironment,} from 'librechat-data-provider';import type { GenericTool, LCToolRegistry, ToolMap, LCTool } from '@librechat/agents';import type { IMongoFile, FileOwnerScope } from '@librechat/data-schemas';@@ -67,9 +69,12 @@ import {registerFileAuthoringTools,isFileAuthoringToolDefinition,} from './tools';+import {+ createStatefulCodeEnvironmentPolicyError,+ isFatalAgentInitializationError,+} from './errors';import { registerMemoryTools, memoryToolUsageGuard } from './memory';import { applyIntentLabels, sanitizeIntentLabels } from './intent';-import { isFatalAgentInitializationError } from './errors';import { applyBackgroundToolCalls } from './background';import { filterFilesByEndpointConfig } from '~/files';import { generateArtifactsPrompt } from '~/prompts';@@ -478,6 +483,8 @@ export interface InitializeAgentParams {toolIntentsAvailable?: boolean;/** Whether stateful code sessions are available (stateful_code_sessions capability enabled) */statefulSessionsAvailable?: boolean;+ /** Explicit deployment allowlist for request types that do not carry LibreChat config on req. */+ allowedStatefulCodeEnvironments?: readonly StatefulCodeEnvironment[];/** Whether inline memory tools are available (memory capability enabled, memory* configured, and the user permitted). When true and the agent lists the `memory`* capability, `set_memory` + `delete_memory` are registered for the LLM. */@@ -723,6 +730,15 @@ export async function initializeAgent(params.statefulSessionsAvailable === true &&agent.stateful_code_sessions === true;const statefulCodeEnvironment = normalizeStatefulCodeEnvironment(agent.stateful_code_environment);+ if (effectiveStatefulSessions) {+ const allowedStatefulCodeEnvironments = resolveAllowedStatefulCodeEnvironments(+ params.allowedStatefulCodeEnvironments ??+ req.config?.endpoints?.[EModelEndpoint.agents]?.statefulCodeSessions?.allowedEnvironments,+ );+ if (!allowedStatefulCodeEnvironments.includes(statefulCodeEnvironment)) {+ throw createStatefulCodeEnvironmentPolicyError(statefulCodeEnvironment);+ }+ }const codeExecutionContext = resolveCodeExecutionContext({statefulSessions: effectiveStatefulSessions,environment: statefulCodeEnvironment,diff --git a/packages/api/src/agents/openai/service.spec.ts b/packages/api/src/agents/openai/service.spec.tsindex 48892e627f..75bcf09172 100644--- a/packages/api/src/agents/openai/service.spec.ts+++ b/packages/api/src/agents/openai/service.spec.ts@@ -1,3 +1,4 @@+import { ErrorTypes } from 'librechat-data-provider';import type { ChatCompletionDependencies } from './service';import { createAgentChatCompletion } from './service';@@ -140,4 +141,50 @@ describe('createAgentChatCompletion - MCP permission user propagation', () => {});expect(runArgs.appConfig).not.toHaveProperty('interfaceConfig');});++ it('forwards the stateful environment allowlist from appConfig to agent initialization', async () => {+ deps.appConfig = {+ endpoints: {+ agents: {+ capabilities: ['execute_code', 'stateful_code_sessions'],+ statefulCodeSessions: { allowedEnvironments: ['user', 'agent-user'] },+ },+ },+ } as never;++ await createAgentChatCompletion(createMockReq({ id: 'user-123' }), createMockRes(), deps);++ expect(deps.initializeAgent).toHaveBeenCalledWith(+ expect.objectContaining({+ codeEnvAvailable: true,+ statefulSessionsAvailable: true,+ allowedStatefulCodeEnvironments: ['user', 'agent-user'],+ }),+ );+ });++ it('preserves stateful scope policy status and code in an initialization error response', async () => {+ const policyError = Object.assign(+ new Error('Stateful code environment is not allowed by this deployment: conversation'),+ {+ code: ErrorTypes.STATEFUL_CODE_ENVIRONMENT_NOT_ALLOWED,+ status: 403,+ statusCode: 403,+ },+ );+ (deps.initializeAgent as jest.Mock).mockRejectedValueOnce(policyError);+ const res = createMockRes();++ await createAgentChatCompletion(createMockReq({ id: 'user-123' }), res, deps);++ expect(res.status).toHaveBeenCalledWith(403);+ expect(res.json).toHaveBeenCalledWith({+ error: {+ message: policyError.message,+ type: 'invalid_request_error',+ param: null,+ code: ErrorTypes.STATEFUL_CODE_ENVIRONMENT_NOT_ALLOWED,+ },+ });+ });});diff --git a/packages/api/src/agents/openai/service.ts b/packages/api/src/agents/openai/service.tsindex ebc8122916..193e8fa92f 100644--- a/packages/api/src/agents/openai/service.ts+++ b/packages/api/src/agents/openai/service.ts@@ -20,6 +20,7 @@*/import { nanoid } from 'nanoid';import { AgentCapabilities } from 'librechat-data-provider';+import type { StatefulCodeEnvironment } from 'librechat-data-provider';import type { Response as ServerResponse, Request } from 'express';import type {ChatCompletionResponse,@@ -155,6 +156,8 @@ interface InitializeAgentParams {* in-repo controllers; absent / `undefined` disables the feature.*/statefulSessionsAvailable?: boolean;+ /** Deployment allowlist carried explicitly because this route's Request has no req.config. */+ allowedStatefulCodeEnvironments?: readonly StatefulCodeEnvironment[];/*** Whether the admin-level `run_in_background` capability is enabled.* Gates `applyBackgroundToolCalls` in `initializeAgent` (the injected@@ -475,6 +478,16 @@ export async function createAgentChatCompletion(* also carries each agent's trusted stateful endpoint/profile selection* into tool loading and prewarming. */const statefulSessionsAvailable = capabilityEnabled(AgentCapabilities.stateful_code_sessions);+ const allowedStatefulCodeEnvironments =+ agentsConfig != null && typeof agentsConfig === 'object'+ ? (+ agentsConfig as {+ statefulCodeSessions?: {+ allowedEnvironments?: readonly StatefulCodeEnvironment[];+ };+ }+ ).statefulCodeSessions?.allowedEnvironments+ : undefined;/** Same gate as the in-repo controllers: without it, agents that opted* tools in via tool_options.run_in_background silently lose the* background param + poll tool on this route. */@@ -498,6 +511,7 @@ export async function createAgentChatCompletion(isInitialAgent: true,codeEnvAvailable,statefulSessionsAvailable,+ allowedStatefulCodeEnvironments,backgroundToolsAvailable,toolIntentsAvailable,});@@ -637,7 +651,27 @@ export async function createAgentChatCompletion(writeSSE(res, '[DONE]');res.end();} else {- sendErrorResponse(res, 500, errorMessage, 'server_error');+ const candidateStatus =+ error != null && typeof error === 'object'+ ? ((error as { status?: unknown; statusCode?: unknown }).status ??+ (error as { statusCode?: unknown }).statusCode)+ : undefined;+ const statusCode =+ typeof candidateStatus === 'number' &&+ Number.isInteger(candidateStatus) &&+ candidateStatus >= 400 &&+ candidateStatus < 600+ ? candidateStatus+ : 500;+ const errorType =+ statusCode >= 400 && statusCode < 500 ? 'invalid_request_error' : 'server_error';+ const errorCode =+ error != null &&+ typeof error === 'object' &&+ typeof (error as { code?: unknown }).code === 'string'+ ? (error as { code: string }).code+ : null;+ sendErrorResponse(res, statusCode, errorMessage, errorType, errorCode);}}}diff --git a/packages/api/src/endpoints/config/endpoints.spec.ts b/packages/api/src/endpoints/config/endpoints.spec.tsindex e0155fe323..fdeb341f17 100644--- a/packages/api/src/endpoints/config/endpoints.spec.ts+++ b/packages/api/src/endpoints/config/endpoints.spec.ts@@ -175,6 +175,30 @@ describe('createEndpointsConfigService', () => {expect(result?.[EModelEndpoint.agents]?.allowedProviders).toEqual(['openAI', 'anthropic']);});+ it('exposes the deployment stateful environment allowlist', async () => {+ const deps = createMockDeps({+ loadDefaultEndpointsConfig: jest.fn().mockResolvedValue({+ [EModelEndpoint.agents]: { userProvide: false, order: 0 },+ }),+ getAppConfig: jest.fn().mockResolvedValue(+ appConfig({+ endpoints: {+ [EModelEndpoint.agents]: {+ statefulCodeSessions: { allowedEnvironments: ['user', 'agent-user'] },+ },+ },+ }),+ ),+ });+ const { getEndpointsConfig } = createEndpointsConfigService(deps);++ const result = await getEndpointsConfig(fakeReq());++ expect(result?.[EModelEndpoint.agents]?.statefulCodeSessions).toEqual({+ allowedEnvironments: ['user', 'agent-user'],+ });+ });+it('merges bedrock availableRegions', async () => {const deps = createMockDeps({loadDefaultEndpointsConfig: jest.fn().mockResolvedValue({diff --git a/packages/api/src/endpoints/config/endpoints.ts b/packages/api/src/endpoints/config/endpoints.tsindex fd9e8c3018..b7f58985fe 100644--- a/packages/api/src/endpoints/config/endpoints.ts+++ b/packages/api/src/endpoints/config/endpoints.ts@@ -70,13 +70,14 @@ export function createEndpointsConfigService(deps: EndpointsConfigDeps): {}if (mergedConfig[EModelEndpoint.agents] && appConfig?.endpoints?.[EModelEndpoint.agents]) {- const { disableBuilder, capabilities, allowedProviders } =+ const { disableBuilder, capabilities, allowedProviders, statefulCodeSessions } =appConfig.endpoints[EModelEndpoint.agents];mergedConfig[EModelEndpoint.agents] = {...mergedConfig[EModelEndpoint.agents],allowedProviders,disableBuilder,capabilities,+ statefulCodeSessions,};}diff --git a/packages/api/src/user/preferences.spec.ts b/packages/api/src/user/preferences.spec.tsindex d33ff364fc..004cdd0d3e 100644--- a/packages/api/src/user/preferences.spec.ts+++ b/packages/api/src/user/preferences.spec.ts@@ -69,6 +69,27 @@ describe('createUserPreferencesHandler', () => {expect(response.statusCode).toBe(400);});+ it('rejects a valid scope excluded by deployment policy', async () => {+ const updateStatefulCodeEnvironment = jest.fn();+ const handler = createUserPreferencesHandler({ updateStatefulCodeEnvironment });+ const response = createResponse();+ const request = createRequest({ statefulCodeEnvironment: 'conversation' }) as Parameters<+ typeof handler+ >[0];+ request.config = {+ endpoints: {+ agents: {+ statefulCodeSessions: { allowedEnvironments: ['user', 'agent-user'] },+ },+ },+ } as NonNullable<typeof request.config>;++ await handler(request, response as Response);++ expect(updateStatefulCodeEnvironment).not.toHaveBeenCalled();+ expect(response.statusCode).toBe(403);+ });+it('requires an authenticated user', async () => {const updateStatefulCodeEnvironment = jest.fn();const handler = createUserPreferencesHandler({ updateStatefulCodeEnvironment });diff --git a/packages/api/src/user/preferences.ts b/packages/api/src/user/preferences.tsindex 780db1f9d0..bc0c81b521 100644--- a/packages/api/src/user/preferences.ts+++ b/packages/api/src/user/preferences.ts@@ -1,8 +1,12 @@import { logger } from '@librechat/data-schemas';-import { STATEFUL_CODE_ENVIRONMENTS } from 'librechat-data-provider';+import {+ STATEFUL_CODE_ENVIRONMENTS,+ resolveAllowedStatefulCodeEnvironments,+} from 'librechat-data-provider';import type { StatefulCodeEnvironment } from 'librechat-data-provider';import type { IUser } from '@librechat/data-schemas';-import type { Request, Response } from 'express';+import type { Response } from 'express';+import type { ServerRequest } from '~/types';interface UserPreferencesBody {statefulCodeEnvironment?: string;@@ -12,7 +16,8 @@ function isStatefulCodeEnvironment(value: string): value is StatefulCodeEnvironmreturn STATEFUL_CODE_ENVIRONMENTS.some((environment) => environment === value);}-type UserPreferencesRequest = Request<unknown, unknown, UserPreferencesBody> & {+type UserPreferencesRequest = Omit<ServerRequest, 'body' | 'user'> & {+ body: UserPreferencesBody;user?: IUser;};@@ -39,6 +44,15 @@ export function createUserPreferencesHandler(});}+ const allowedEnvironments = resolveAllowedStatefulCodeEnvironments(+ req.config?.endpoints?.agents?.statefulCodeSessions?.allowedEnvironments,+ );+ if (!allowedEnvironments.includes(environment)) {+ return res.status(403).json({+ message: `statefulCodeEnvironment is not allowed by this deployment: ${environment}`,+ });+ }+try {const updatedUser = await deps.updateStatefulCodeEnvironment(userId, environment);if (!updatedUser) {diff --git a/packages/data-provider/specs/config-schemas.spec.ts b/packages/data-provider/specs/config-schemas.spec.tsindex 58b32f7da2..d81b2ea491 100644--- a/packages/data-provider/specs/config-schemas.spec.ts+++ b/packages/data-provider/specs/config-schemas.spec.ts@@ -405,6 +405,27 @@ describe('endpointSchema addParams validation', () => {});describe('agentsEndpointSchema', () => {+ it('accepts a non-empty stateful code environment allowlist', () => {+ const result = agentsEndpointSchema.safeParse({+ statefulCodeSessions: { allowedEnvironments: ['user', 'agent-user'] },+ });++ expect(result.success).toBe(true);+ });++ it('rejects empty or unknown stateful code environment allowlists', () => {+ expect(+ agentsEndpointSchema.safeParse({+ statefulCodeSessions: { allowedEnvironments: [] },+ }).success,+ ).toBe(false);+ expect(+ agentsEndpointSchema.safeParse({+ statefulCodeSessions: { allowedEnvironments: ['agent'] },+ }).success,+ ).toBe(false);+ });+it('does not accept baseURL', () => {const result = agentsEndpointSchema.safeParse({baseURL: 'https://example.com',diff --git a/packages/data-provider/specs/stateful-code.spec.ts b/packages/data-provider/specs/stateful-code.spec.tsnew file mode 100644index 0000000000..866a853ea7--- /dev/null+++ b/packages/data-provider/specs/stateful-code.spec.ts@@ -0,0 +1,24 @@+import {+ STATEFUL_CODE_ENVIRONMENTS,+ resolveStatefulCodeEnvironment,+ resolveAllowedStatefulCodeEnvironments,+} from '../src/types/assistants';++describe('stateful code environment policy', () => {+ it('allows every environment when deployment configuration is omitted', () => {+ expect(resolveAllowedStatefulCodeEnvironments()).toEqual(STATEFUL_CODE_ENVIRONMENTS);+ });++ it('returns configured environments in stable UI order', () => {+ expect(resolveAllowedStatefulCodeEnvironments(['conversation', 'user'])).toEqual([+ 'user',+ 'conversation',+ ]);+ });++ it('falls back to the first allowed environment when a preference is unavailable', () => {+ expect(resolveStatefulCodeEnvironment('user', ['agent-user', 'conversation'])).toBe(+ 'agent-user',+ );+ });+});diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.tsindex 66a589e415..96a23396a3 100644--- a/packages/data-provider/src/config.ts+++ b/packages/data-provider/src/config.ts@@ -9,6 +9,7 @@ import {eReasoningResponseKeySchema,} from './schemas';import { ComponentTypes, SettingTypes, OptionTypes } from './generate';+import { STATEFUL_CODE_ENVIRONMENTS } from './stateful-code';import { specsConfigSchema, TSpecsConfig } from './models';import { REFILL_INTERVAL_UNITS } from './balance';import { fileConfigSchema } from './file-config';@@ -1004,6 +1005,13 @@ export const agentsEndpointSchema = baseEndpointSchema.array(z.nativeEnum(AgentCapabilities)).optional().default(defaultAgentCapabilities),+ /** Controls which workspace-sharing scopes users may select for stateful code sessions.+ * Omit this block to preserve the legacy behavior of allowing every scope. */+ statefulCodeSessions: z+ .object({+ allowedEnvironments: z.array(z.enum(STATEFUL_CODE_ENVIRONMENTS)).min(1),+ })+ .optional(),skills: z.object({maxCatalogSkills: z.number().int().min(1).max(100).optional(),@@ -2722,6 +2730,10 @@ export enum ErrorTypes {* Required CodeAPI resources could not be restored before model invocation.*/RESOURCE_RECOVERY_REQUIRED = 'resource_recovery_required',+ /**+ * Agent selected a stateful Code API workspace scope disabled by the deployment.+ */+ STATEFUL_CODE_ENVIRONMENT_NOT_ALLOWED = 'stateful_code_environment_not_allowed',/*** Invalid Agent Provider (excluded by Admin)*/diff --git a/packages/data-provider/src/stateful-code.ts b/packages/data-provider/src/stateful-code.tsnew file mode 100644index 0000000000..1288ba0171--- /dev/null+++ b/packages/data-provider/src/stateful-code.ts@@ -0,0 +1,24 @@+export const STATEFUL_CODE_ENVIRONMENTS = ['user', 'agent-user', 'conversation'] as const;+export type StatefulCodeEnvironment = (typeof STATEFUL_CODE_ENVIRONMENTS)[number];++/** Resolve a deployment allowlist in stable UI order. An omitted value preserves+ * the backward-compatible behavior where every environment is available. */+export function resolveAllowedStatefulCodeEnvironments(+ configured?: readonly StatefulCodeEnvironment[] | null,+): StatefulCodeEnvironment[] {+ if (configured == null) {+ return [...STATEFUL_CODE_ENVIRONMENTS];+ }++ const configuredSet = new Set(configured);+ return STATEFUL_CODE_ENVIRONMENTS.filter((environment) => configuredSet.has(environment));+}++/** Keep an allowed preference, otherwise select the first deployment-allowed scope. */+export function resolveStatefulCodeEnvironment(+ preferred: StatefulCodeEnvironment | null | undefined,+ configured?: readonly StatefulCodeEnvironment[] | null,+): StatefulCodeEnvironment | undefined {+ const allowed = resolveAllowedStatefulCodeEnvironments(configured);+ return preferred != null && allowed.includes(preferred) ? preferred : allowed[0];+}diff --git a/packages/data-provider/src/types.ts b/packages/data-provider/src/types.tsindex 5f3d81ffd9..6e67a03517 100644--- a/packages/data-provider/src/types.ts+++ b/packages/data-provider/src/types.ts@@ -544,6 +544,9 @@ export type TConfig = {disableBuilder?: boolean;retrievalModels?: string[];capabilities?: string[];+ statefulCodeSessions?: {+ allowedEnvironments: StatefulCodeEnvironment[];+ };customParams?: {defaultParamsEndpoint?: string;reasoningFormat?: ReasoningParameterFormat;diff --git a/packages/data-provider/src/types/assistants.ts b/packages/data-provider/src/types/assistants.tsindex fadda72394..c6da929e30 100644--- a/packages/data-provider/src/types/assistants.ts+++ b/packages/data-provider/src/types/assistants.ts@@ -1,9 +1,16 @@import type { OpenAPIV3 } from 'openapi-types';import type { AssistantsEndpoint, AgentProvider, MemoryScope } from 'src/schemas';+import type { StatefulCodeEnvironment } from '../stateful-code';import type { Agents, GraphEdge } from './agents';import type { ContentTypes } from './runs';import type { TFile } from './files';import { ArtifactModes } from 'src/artifacts';+export {+ STATEFUL_CODE_ENVIRONMENTS,+ resolveStatefulCodeEnvironment,+ resolveAllowedStatefulCodeEnvironments,+} from '../stateful-code';+export type { StatefulCodeEnvironment } from '../stateful-code';export type Schema = OpenAPIV3.SchemaObject & { description?: string };export type Reference = OpenAPIV3.ReferenceObject & { description?: string };@@ -538,9 +545,6 @@ export enum AnnotationTypes {FILE_PATH = 'file_path',}-export const STATEFUL_CODE_ENVIRONMENTS = ['user', 'agent-user', 'conversation'] as const;-export type StatefulCodeEnvironment = (typeof STATEFUL_CODE_ENVIRONMENTS)[number];-export enum StepStatus {IN_PROGRESS = 'in_progress',CANCELLED = 'cancelled',