✨ feat: stateful_code_sessions capability for warm Code API sandbox sessions (experimental)

api/app/clients/tools/util/handleTools.js

@@ -22,6 +22,7 @@ const {
   Permissions,
   EToolResources,
   PermissionTypes,
+  AgentCapabilities,
 } = require('librechat-data-provider');
 const {
   availableTools,
@@ -51,7 +52,7 @@ const { createFileSearchTool, primeFiles: primeSearchFiles } = require('./fileSe
 const { primeFiles: primeCodeFiles } = require('~/server/services/Files/Code/process');
 const { getUserPluginAuthValue } = require('~/server/services/PluginService');
 const { loadAuthValues } = require('~/server/services/Tools/credentials');
-const { getMCPServerTools } = require('~/server/services/Config');
+const { getMCPServerTools, checkCapability } = require('~/server/services/Config');
 const { getMCPServersRegistry } = require('~/config');
 const { getRoleByName, setMemory, deleteMemory, getFormattedMemories } = require('~/models');
 
@@ -301,10 +302,18 @@ const loadTools = async ({
         if (files?.length) {
           primedCodeFiles = files;
         }
+        /* Hedge the execute_code description toward persistence only when the
+         * admin `stateful_code_sessions` capability is on AND the agent opted
+         * in via the builder (off by default); the matching wire hint is set
+         * in the run config. Older @librechat/agents ignore the param. */
+        const statefulSessions =
+          agent?.stateful_code_sessions === true &&
+          (await checkCapability(options.req, AgentCapabilities.stateful_code_sessions));
         return createCodeExecutionTool({
           user_id: user,
           files,
           authHeaders: () => getCodeApiAuthHeaders(options.req),
+          statefulSessions,
         });
       };
       continue;

api/server/controllers/agents/client.js

@@ -744,6 +744,7 @@ class AgentClient extends BaseClient {
             : memoryConfig.agent?.provider,
         },
         codeEnvAvailable: memoryCapabilities.has(AgentCapabilities.execute_code),
+        statefulSessionsAvailable: memoryCapabilities.has(AgentCapabilities.stateful_code_sessions),
       },
       {
         getFiles: db.getFiles,

api/server/controllers/agents/openai.js

@@ -335,6 +335,9 @@ const OpenAIChatCompletionController = async (req, res) => {
           ephemeralSkillsToggle,
         }),
         codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
+        statefulSessionsAvailable: enabledCapabilities.has(
+          AgentCapabilities.stateful_code_sessions,
+        ),
         skillStates,
         defaultActiveOnShare,
         manualSkills,
@@ -412,6 +415,9 @@ const OpenAIChatCompletionController = async (req, res) => {
           defaultActiveOnShare,
           /** @see DiscoverConnectedAgentsParams.codeEnvAvailable */
           codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
+          statefulSessionsAvailable: enabledCapabilities.has(
+            AgentCapabilities.stateful_code_sessions,
+          ),
         },
         {
           getAgent: db.getAgent,

api/server/controllers/agents/responses.js

@@ -459,6 +459,9 @@ const createResponse = async (req, res) => {
           ephemeralSkillsToggle,
         }),
         codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
+        statefulSessionsAvailable: enabledCapabilities.has(
+          AgentCapabilities.stateful_code_sessions,
+        ),
         skillStates,
         defaultActiveOnShare,
         manualSkills,
@@ -536,6 +539,9 @@ const createResponse = async (req, res) => {
           defaultActiveOnShare,
           /** @see DiscoverConnectedAgentsParams.codeEnvAvailable */
           codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
+          statefulSessionsAvailable: enabledCapabilities.has(
+            AgentCapabilities.stateful_code_sessions,
+          ),
         },
         {
           getAgent: db.getAgent,

api/server/services/Endpoints/agents/addedConvo.js

@@ -54,6 +54,8 @@ const loadAddedAgent = (params) =>
  * @param {boolean} [params.codeEnvAvailable] - `execute_code` capability flag;
  *   forwarded verbatim to the added agent's `initializeAgent`. @see
  *   InitializeAgentParams.codeEnvAvailable for full semantics.
+ * @param {boolean} [params.statefulSessionsAvailable] - `stateful_code_sessions`
+ *   capability flag; forwarded verbatim alongside `codeEnvAvailable`.
  * @returns {Promise<{userMCPAuthMap: Object|undefined}>} The updated userMCPAuthMap
  */
 const processAddedConvo = async ({
@@ -79,6 +81,7 @@ const processAddedConvo = async ({
   skillStates,
   defaultActiveOnShare,
   codeEnvAvailable,
+  statefulSessionsAvailable,
   memoryAvailable,
 }) => {
   const addedConvo = endpointOption.addedConvo;
@@ -174,6 +177,7 @@ const processAddedConvo = async ({
           ephemeralSkillsToggle,
         }),
         codeEnvAvailable,
+        statefulSessionsAvailable,
         memoryAvailable,
         skillStates,
         defaultActiveOnShare,

api/server/services/Endpoints/agents/initialize.js

@@ -149,6 +149,9 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
   const enabledCapabilities = new Set(appConfig?.endpoints?.[EModelEndpoint.agents]?.capabilities);
   const skillsCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.skills);
   const codeEnvAvailable = enabledCapabilities.has(AgentCapabilities.execute_code);
+  const statefulSessionsAvailable = enabledCapabilities.has(
+    AgentCapabilities.stateful_code_sessions,
+  );
   const ephemeralSkillsToggle = req.body?.ephemeralAgent?.skills === true;
   const skillDbMethods = getSkillDbMethods();
 
@@ -405,6 +408,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
       accessibleSkillIds: primaryScopedSkillIds,
       skillAuthoringAvailable: primarySkillAuthoringAvailable,
       codeEnvAvailable,
+      statefulSessionsAvailable,
       memoryAvailable,
       skillStates,
       defaultActiveOnShare,
@@ -481,6 +485,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
       skillStates,
       defaultActiveOnShare,
       codeEnvAvailable,
+      statefulSessionsAvailable,
       memoryAvailable,
     },
     {
@@ -553,6 +558,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
     skillStates,
     defaultActiveOnShare,
     codeEnvAvailable,
+    statefulSessionsAvailable,
     memoryAvailable,
   });
 
@@ -692,6 +698,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
            *  false`, so `bash_tool` / `read_file` sandbox fallback are
            *  silently gated off even though the seed walk found it. */
           codeEnvAvailable,
+          statefulSessionsAvailable,
           memoryAvailable,
           skillStates,
           defaultActiveOnShare,

api/server/services/Files/Code/process.js

@@ -990,7 +990,7 @@ const primeFiles = async (options) => {
  * @param {ServerRequest} [params.req] - Current authenticated request, used to mint Code API auth.
  * @returns {Promise<{content: string} | null>}
  */
-async function readSandboxFile({ file_path, session_id, files, req }) {
+async function readSandboxFile({ file_path, session_id, files, runtime_session_hint, req }) {
   const baseURL = getCodeBaseURL();
   if (!baseURL) {
     return null;
@@ -1006,6 +1006,9 @@ async function readSandboxFile({ file_path, session_id, files, req }) {
   if (session_id) {
     postData.session_id = session_id;
   }
+  if (runtime_session_hint) {
+    postData.runtime_session_hint = runtime_session_hint;
+  }
   if (files && files.length > 0) {
     postData.files = files;
   }
@@ -1056,7 +1059,14 @@ async function readSandboxFile({ file_path, session_id, files, req }) {
  * @param {ServerRequest} [params.req] - Current authenticated request, used to mint Code API auth.
  * @returns {Promise<{stdout?: string, stderr?: string, session_id?: string, files?: Array<Object>} | null>}
  */
-async function writeSandboxFile({ file_path, content, session_id, files, req }) {
+async function writeSandboxFile({
+  file_path,
+  content,
+  session_id,
+  files,
+  runtime_session_hint,
+  req,
+}) {
   const baseURL = getCodeBaseURL();
   if (!baseURL) {
     return null;
@@ -1090,6 +1100,9 @@ async function writeSandboxFile({ file_path, content, session_id, files, req })
   if (session_id) {
     postData.session_id = session_id;
   }
+  if (runtime_session_hint) {
+    postData.runtime_session_hint = runtime_session_hint;
+  }
   if (files && files.length > 0) {
     postData.files = files;
   }

api/server/services/ToolService.js

@@ -1483,6 +1483,18 @@ async function loadToolsForExecution({
     enabledCapabilities?.has(AgentCapabilities.execute_code) === true &&
     agent?.tools?.includes(Tools.execute_code) === true;
 
+  /**
+   * Opt bash_tool into the hedged stateful-session description. Gated on code
+   * execution being enabled AND the admin `stateful_code_sessions` capability
+   * AND the agent's own builder opt-in; off by default. Sets prompt text only
+   * (the wire hint is set at run config). PTC keeps its stateless prompt in
+   * v1. Older @librechat/agents ignore the param.
+   */
+  const statefulCodeSessions =
+    codeExecutionEnabled &&
+    enabledCapabilities?.has(AgentCapabilities.stateful_code_sessions) === true &&
+    agent?.stateful_code_sessions === true;
+
   const isPTC =
     isPTCRequested &&
     enabledCapabilities.has(AgentCapabilities.programmatic_tools) &&
@@ -1534,6 +1546,7 @@ async function loadToolsForExecution({
     try {
       const bashTool = createBashExecutionTool({
         authHeaders: () => getCodeApiAuthHeaders(req),
+        statefulSessions: statefulCodeSessions,
       });
       allLoadedTools.push(bashTool);
     } catch (error) {

client/src/common/agents-types.ts

@@ -25,6 +25,7 @@ export type TAgentCapabilities = {
   [AgentCapabilities.memory]?: boolean;
   [AgentCapabilities.end_after_tools]?: boolean;
   [AgentCapabilities.hide_sequential_outputs]?: boolean;
+  [AgentCapabilities.stateful_code_sessions]?: boolean;
 };
 
 export type AgentForm = {

client/src/components/SidePanel/Agents/Advanced/AdvancedPanel.tsx

@@ -1,10 +1,12 @@
-import { useState } from 'react';
+import { useMemo, useState } from 'react';
 import { useFormContext } from 'react-hook-form';
 import { useToastContext } from '@librechat/client';
 import { ChevronLeft, Check, Copy } from 'lucide-react';
+import { AgentCapabilities } from 'librechat-data-provider';
 import type { AgentForm } from '~/common';
 import { sectionLabelClass, groupHeadingClass } from './ui';
 import { useAgentPanelContext } from '~/Providers';
+import StatefulSessions from './StatefulSessions';
 import OrchestrationHub from './OrchestrationHub';
 import MaxAgentSteps from './MaxAgentSteps';
 import { useLocalize } from '~/hooks';
@@ -17,7 +19,11 @@ export default function AdvancedPanel() {
   const currentAgentId = watch('id');
   const [copied, setCopied] = useState(false);
 
-  const { setActivePanel } = useAgentPanelContext();
+  const { agentsConfig, setActivePanel } = useAgentPanelContext();
+  const statefulSessionsEnabled = useMemo(
+    () => agentsConfig?.capabilities.includes(AgentCapabilities.stateful_code_sessions) ?? false,
+    [agentsConfig],
+  );
 
   const handleCopyAgentId = async () => {
     if (!currentAgentId) return;
@@ -52,6 +58,7 @@ export default function AdvancedPanel() {
         <section className="flex flex-col gap-3">
           <span className={groupHeadingClass}>{localize('com_ui_essentials')}</span>
           <MaxAgentSteps />
+          {statefulSessionsEnabled && <StatefulSessions />}
         </section>
 
         <OrchestrationHub currentAgentId={currentAgentId} />

client/src/components/SidePanel/Agents/Advanced/StatefulSessions.tsx

@@ -0,0 +1,59 @@
+import { useFormContext } from 'react-hook-form';
+import { AgentCapabilities } from 'librechat-data-provider';
+import {
+  Switch,
+  HoverCard,
+  HoverCardPortal,
+  HoverCardContent,
+  HoverCardTrigger,
+  CircleHelpIcon,
+} from '@librechat/client';
+import type { AgentForm } from '~/common';
+import { useLocalize } from '~/hooks';
+import { ESide } from '~/common';
+
+export default function StatefulSessions() {
+  const localize = useLocalize();
+  const methods = useFormContext<AgentForm>();
+  const { setValue, watch } = methods;
+
+  const enabled = watch(AgentCapabilities.stateful_code_sessions) ?? false;
+  const codeEnabled = watch(AgentCapabilities.execute_code);
+
+  const handleChange = (value: boolean) => {
+    setValue(AgentCapabilities.stateful_code_sessions, value, { shouldDirty: true });
+  };
+
+  return (
+    <HoverCard openDelay={50}>
+      <div className="flex items-center justify-between">
+        <div className="flex items-center space-x-2">
+          <div className={codeEnabled ? 'text-sm' : 'text-sm text-text-tertiary'}>
+            {localize('com_ui_stateful_sessions')}
+          </div>
+          <HoverCardTrigger>
+            <CircleHelpIcon className="h-4 w-4 text-text-tertiary" />
+          </HoverCardTrigger>
+        </div>
+        <HoverCardPortal>
+          <HoverCardContent side={ESide.Top} className="w-80">
+            <div className="space-y-2">
+              <p className="text-sm text-text-secondary">
+                {localize('com_nav_info_stateful_sessions')}
+              </p>
+            </div>
+          </HoverCardContent>
+        </HoverCardPortal>
+        <Switch
+          id="stateful-code-sessions"
+          checked={enabled && codeEnabled === true}
+          onCheckedChange={handleChange}
+          className="ml-4"
+          data-testid="stateful-code-sessions"
+          disabled={codeEnabled !== true}
+          aria-label={localize('com_ui_stateful_sessions')}
+        />
+      </div>
+    </HoverCard>
+  );
+}

client/src/components/SidePanel/Agents/AgentPanel.tsx

@@ -72,6 +72,7 @@ export function composeAgentUpdatePayload(data: AgentForm, agent_id?: string | n
     subagents,
     end_after_tools,
     hide_sequential_outputs,
+    stateful_code_sessions,
     recursion_limit,
     category,
     support_contact,
@@ -81,6 +82,11 @@ export function composeAgentUpdatePayload(data: AgentForm, agent_id?: string | n
     avatar_action: avatarActionState,
   } = data;
 
+  /* stateful_code_sessions requires Code Interpreter; force it off on save when
+   * execute_code is disabled so a stale opt-in can't silently reactivate later. */
+  const normalizedStatefulCodeSessions =
+    data.execute_code === true ? stateful_code_sessions : false;
+
   const shouldResetAvatar =
     avatarActionState === 'reset' && Boolean(agent_id) && !isEphemeralAgent(agent_id);
   const model = _model ?? '';
@@ -101,6 +107,7 @@ export function composeAgentUpdatePayload(data: AgentForm, agent_id?: string | n
       subagents,
       end_after_tools,
       hide_sequential_outputs,
+      stateful_code_sessions: normalizedStatefulCodeSessions,
       recursion_limit,
       category,
       support_contact,

client/src/components/SidePanel/Agents/AgentSelect.tsx

@@ -61,6 +61,7 @@ function AgentSelect({
         [AgentCapabilities.memory]: false,
         [AgentCapabilities.end_after_tools]: false,
         [AgentCapabilities.hide_sequential_outputs]: false,
+        [AgentCapabilities.stateful_code_sessions]: false,
       };
 
       const agentTools: string[] = [];

client/src/components/SidePanel/Agents/__tests__/AgentPanel.helpers.spec.ts

@@ -71,6 +71,26 @@ describe('composeAgentUpdatePayload', () => {
 
     expect(payload.avatar).toBeUndefined();
   });
+
+  it('forces stateful_code_sessions off when execute_code is disabled', () => {
+    const form = createForm();
+    form.execute_code = false;
+    form.stateful_code_sessions = true;
+
+    const { payload } = composeAgentUpdatePayload(form, 'agent_123');
+
+    expect(payload.stateful_code_sessions).toBe(false);
+  });
+
+  it('preserves stateful_code_sessions when execute_code is enabled', () => {
+    const form = createForm();
+    form.execute_code = true;
+    form.stateful_code_sessions = true;
+
+    const { payload } = composeAgentUpdatePayload(form, 'agent_123');
+
+    expect(payload.stateful_code_sessions).toBe(true);
+  });
 });
 
 describe('persistAvatarChanges', () => {