🧪 feat: Add LIBRECHAT_CODE_DEFAULT_PROFILE to Run Chat Code on the Stateful Profile

[TomasPalsson]

Pull Request

Summary

Deployments whose Code Interpreter runs only the stateful profile reject every code request from an Agent that has not switched on stateful sessions, and from every normal chat with the Code toggle on. Users see "Failed to provision 1 file(s) to the code environment" (409 from the service) and the turn dies. Today the only way out is flipping the toggle on every Agent, which does nothing for normal chats.

This PR adds one deployment setting, LIBRECHAT_CODE_DEFAULT_PROFILE (default | stateful, default default). With stateful, saved Agents with the toggle off or unset, normal chats with Code on, added-conversation Agents and subagents all run on the stateful profile, and code-output downloads with no named profile follow it. Unset or default behaves exactly as today.

How it works

packages/api/src/code/config.ts parses the setting (trimmed, case-sensitive, an unknown value counts as unset and warns once). isStatefulDefaultEligible in packages/api/src/code/agent.ts decides whether it applies to an Agent, and every gate that read stateful_code_sessions === true now reads stateful_code_sessions === true || <eligible>, keeping its existing capability check:

• resolveAgentCodeFlags (packages/api/src/code/agent.ts), which ToolService and both agent initialisers already delegate to
• subagent routing (packages/api/src/code/inheritance.ts)
• the legacy tool factory (api/app/clients/tools/util/handleTools.js)

The setting applies only when the stateful_code_sessions capability is on, the Agent has execute_code, its code machine is not an attached environment (or an id that matches no configured environment), and its stateful scope is allowed by statefulCodeSessions.allowedEnvironments. optsOutOfAttachedCodeEnvironment is unchanged.

Downloads: GET /api/files/code/download/... with no execution_profile uses the setting only when the capability is on; an explicit valid value still wins. createDownloadFallback now writes execution_profile=default for default-profile runs when the setting is stateful, so those links stay on the default service.

Agent builder: the agents endpoint config now carries codeDefaultProfile. When it is stateful, the Run Code dialog hides the "Stateful code sessions" switch (it would read off while code runs stateful), shows the stateful options directly under a "Stateful code sessions" heading styled like the dialog's "User control" heading (role="group", aria-labelledby), and sets the form value on (not dirty) so saving stores what runs. No new strings; without the setting the dialog is unchanged.

Type of change

• New feature (non-breaking change which adds functionality)
• Documentation update (.env.example)

Testing

Run on this branch (base a7e6cc89f on dev; merges cleanly with current dev):

• packages/api: npx jest src/code src/files/provision/callback.spec.ts src/agents/__tests__/initialize.test.ts — 1100 passed, 1 skipped (pre-existing); npx tsc --noEmit -p tsconfig.json exit 0; npm run build exit 0
• client: npx jest src/components/SidePanel/Agents — 711 passed (new CodeSettings.statefulDefault.spec.tsx); packages/api src/endpoints/config — 109 passed (new endpoints.codeDefaultProfile.spec.ts); client tsc --noEmit exit 0
• api: npx jest server/routes/files/files.test.js app/clients/tools/util/handleTools.test.js server/services/Endpoints/agents/initialize.spec.js server/services/Endpoints/agents/addedConvo.spec.js server/services/Files/Code/process.spec.js — 418 passed
• eslint and prettier --check on every changed file: clean
• New tests cover each criterion (unset parity, saved Agent with toggle off, normal chat, added Agent, subagent, provisioning label, downloads, capability off, attached and missing machines, disallowed scope, bad values); the gate tests were checked to fail with the new term removed.

Not run: a live deployment. We are verifying on a stateful-only staging deployment next.

Risk / compatibility

• Unset or default: every changed expression reduces to the existing one; the download route makes no extra capability call.
• Env setting rather than librechat.yaml: it describes the deployment's Code Interpreter (like LIBRECHAT_CODE_BASEURL_STATEFUL), not per-endpoint behaviour.
• With stateful, Agents on an attached machine, on an unconfigured machine id, or whose stateful scope is not allowed keep their saved setting.
• Fallback download links created before the setting is turned on carry no profile and resolve to stateful afterwards.

Checklist

• My code adheres to this project's style guidelines
• I have performed a self-review of my own code
• I have commented in any complex areas of my code
• I have made pertinent documentation changes: 📝 docs: Document LIBRECHAT_CODE_DEFAULT_PROFILE for stateful-only code deployments docs#830
• My changes do not introduce new warnings
• I have written tests demonstrating that my changes are effective or that my feature works
• Local unit tests pass with my changes

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.