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
import type { StatefulCodeEnvironment } from 'librechat-data-provider';
import type { CodeExecutionContext } from './execution';
import {
markSandboxReady,
maybePrewarmCodeSandbox,
resetSandboxStateForTests,
shouldSignalSandboxStart,
} from './prewarm';
type PrewarmParams = Parameters<typeof maybePrewarmCodeSandbox>[0];
interface TestAgent {
id: string;
statefulCodeSessions?: boolean;
statefulCodeEnvironment?: StatefulCodeEnvironment;
codeExecutionContext?: CodeExecutionContext;
subagentAgentConfigs?: TestAgent[];
lazySubagentConfigs?: TestAgent[];
}
const req = { user: { id: 'user-1' } } as PrewarmParams['req'];
const statefulAgent: TestAgent = { id: 'agent_stateful', statefulCodeSessions: true };
const plainAgent: TestAgent = { id: 'agent_plain', statefulCodeSessions: false };
function agents(...list: TestAgent[]): PrewarmParams['agents'] {
return list as PrewarmParams['agents'];
}
function flushAsync(): Promise<void> {
return new Promise((resolve) => setImmediate(resolve));
}
function mockResponse(init: { ok: boolean; status: number }): Response {
return { ...init, arrayBuffer: async () => new ArrayBuffer(0) } as Response;
}
describe('maybePrewarmCodeSandbox', () => {
let fetchMock: jest.SpyInstance;
beforeEach(async () => {
await resetSandboxStateForTests();
process.env.LIBRECHAT_CODE_BASEURL = 'http://code.test/v1';
process.env.LIBRECHAT_CODE_BASEURL_STATEFUL = 'http://code-stateful.test/v1';
delete process.env.CODE_SANDBOX_PREWARM;
delete process.env.CODE_SANDBOX_COLD_AFTER_MS;
delete process.env.CODEAPI_JWT_ENABLED;
delete process.env.CODEAPI_AUTH_PROVIDER;
fetchMock = jest
.spyOn(globalThis, 'fetch')
.mockResolvedValue(mockResponse({ ok: true, status: 200 }));
});
afterEach(() => {
fetchMock.mockRestore();
jest.useRealTimers();
delete process.env.LIBRECHAT_CODE_BASEURL;
delete process.env.LIBRECHAT_CODE_BASEURL_STATEFUL;
});
it('does nothing when no reachable agent has stateful sessions', async () => {
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(plainAgent) });
await flushAsync();
expect(fetchMock).not.toHaveBeenCalled();
await expect(shouldSignalSandboxStart('convo-1')).resolves.toBe(false);
});
it('does nothing without a conversationId', async () => {
maybePrewarmCodeSandbox({ req, conversationId: null, agents: agents(statefulAgent) });
await flushAsync();
expect(fetchMock).not.toHaveBeenCalled();
});
it('respects the CODE_SANDBOX_PREWARM=false kill switch', async () => {
process.env.CODE_SANDBOX_PREWARM = 'false';
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(statefulAgent) });
await flushAsync();
expect(fetchMock).not.toHaveBeenCalled();
});
it('fires one stateful-profile exec with the default user environment and marks ready', async () => {
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(statefulAgent) });
await flushAsync();
expect(fetchMock).toHaveBeenCalledTimes(1);
const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
expect(url).toBe('http://code-stateful.test/v1/exec');
expect(init.headers).toEqual(
expect.objectContaining({ 'X-CodeAPI-Expected-Profile': 'stateful' }),
);
expect(JSON.parse(init.body as string)).toEqual({
lang: 'bash',
code: 'true',
runtime_session_hint: 'v2:user:b5729fb0e3ca12e7a61ff6857b99d98e',
});
await expect(shouldSignalSandboxStart('convo-1')).resolves.toBe(false);
});
it('does not prewarm an attached environment that leases a single worker', async () => {
const attachedAgent: TestAgent = {
id: 'agent_attached',
statefulCodeSessions: true,
codeExecutionContext: {
baseUrl: 'http://attached-code.test/v1',
codeSessionKey: 'execute_code:stateful:attached',
executionProfile: 'stateful',
runtimeSessionHint: 'v3:attached:conversation:abc',
statefulSessions: true,
environmentId: 'e2e-vm',
environmentType: 'attached',
},
};
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(attachedAgent) });
await flushAsync();
expect(fetchMock).not.toHaveBeenCalled();
await expect(shouldSignalSandboxStart('convo-1')).resolves.toBe(false);
});
it('walks subagent configs for the stateful gate', async () => {
const parent = { id: 'agent_parent', subagentAgentConfigs: [statefulAgent] };
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(parent) });
await flushAsync();
expect(fetchMock).toHaveBeenCalledTimes(1);
});
it('walks lazy subagents and deduplicates user-scoped environments', async () => {
const parent = {
id: 'agent_parent',
statefulCodeSessions: true,
lazySubagentConfigs: [statefulAgent],
};
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(parent) });
await flushAsync();
expect(fetchMock).toHaveBeenCalledTimes(1);
});
it('prewarms distinct per-agent environments independently', async () => {
const first: TestAgent = {
id: 'agent-1',
statefulCodeSessions: true,
statefulCodeEnvironment: 'agent-user',
};
const second: TestAgent = {
id: 'agent-2',
statefulCodeSessions: true,
statefulCodeEnvironment: 'agent-user',
};
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(first, second) });
await flushAsync();
expect(fetchMock).toHaveBeenCalledTimes(2);
const hints = fetchMock.mock.calls.map(
([, init]) => JSON.parse(init.body).runtime_session_hint,
);
expect(hints).toEqual(
expect.arrayContaining([
'v2:agent-user:9cf1605ead4951d96f711e1b3db86642',
'v2:agent-user:f2a396a5aa5e99ce8e423f5ba6c323a3',
]),
);
});
it('does not share prewarm cache entries between authenticated users', async () => {
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(statefulAgent) });
await flushAsync();
const otherReq = { user: { id: 'user-2' } } as PrewarmParams['req'];
maybePrewarmCodeSandbox({
req: otherReq,
conversationId: 'convo-2',
agents: agents(statefulAgent),
});
await flushAsync();
expect(fetchMock).toHaveBeenCalledTimes(2);
const hints = fetchMock.mock.calls.map(
([, init]) => JSON.parse(init.body).runtime_session_hint,
);
expect(new Set(hints).size).toBe(2);
});
it('keeps the conversation start signal active until every selected environment is warm', async () => {
const resolvers: Array<(response: Response) => void> = [];
fetchMock.mockImplementation(
() =>
new Promise<Response>((resolve) => {
resolvers.push(resolve);
}),
);
const first = {
id: 'agent-1',
statefulCodeSessions: true,
statefulCodeEnvironment: 'agent-user' as const,
};
const second = {
id: 'agent-2',
statefulCodeSessions: true,
statefulCodeEnvironment: 'agent-user' as const,
};
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(first, second) });
await flushAsync();
expect(resolvers).toHaveLength(2);
await expect(shouldSignalSandboxStart('convo-1')).resolves.toBe(true);
resolvers[0](mockResponse({ ok: true, status: 200 }));
await flushAsync();
await expect(shouldSignalSandboxStart('convo-1')).resolves.toBe(true);
resolvers[1](mockResponse({ ok: true, status: 200 }));
await flushAsync();
await expect(shouldSignalSandboxStart('convo-1')).resolves.toBe(false);
});
it('does not refire while the warm marker is fresh', async () => {
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(statefulAgent) });
await flushAsync();
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(statefulAgent) });
await flushAsync();
expect(fetchMock).toHaveBeenCalledTimes(1);
});
it('prewarms a replacement route even when its runtime session hint is unchanged', async () => {
const context = (executionRouteKey: string, baseUrl: string): TestAgent => ({
id: `agent-${executionRouteKey}`,
statefulCodeSessions: true,
codeExecutionContext: {
baseUrl,
codeSessionKey: `execute_code:${executionRouteKey}`,
executionProfile: 'stateful',
executionRouteKey,
runtimeSessionHint: 'v3:stable:user:scope',
statefulSessions: true,
environmentType: 'managed',
},
});
maybePrewarmCodeSandbox({
req,
conversationId: 'convo-1',
agents: agents(context(`stateful:${'a'.repeat(32)}`, 'https://old-code.example.com')),
});
await flushAsync();
maybePrewarmCodeSandbox({
req,
conversationId: 'convo-2',
agents: agents(context(`stateful:${'b'.repeat(32)}`, 'https://new-code.example.com')),
});
await flushAsync();
expect(fetchMock).toHaveBeenCalledTimes(2);
expect(fetchMock.mock.calls.map(([url]) => url)).toEqual([
'https://old-code.example.com/exec',
'https://new-code.example.com/exec',
]);
});
it('does not refire while a prewarm is in flight', async () => {
fetchMock.mockImplementation(() => new Promise(() => undefined));
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(statefulAgent) });
await flushAsync();
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(statefulAgent) });
await flushAsync();
expect(fetchMock).toHaveBeenCalledTimes(1);
});
it('keeps a second conversation cold while it joins an in-flight user prewarm', async () => {
fetchMock.mockImplementation(() => new Promise(() => undefined));
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(statefulAgent) });
await flushAsync();
maybePrewarmCodeSandbox({ req, conversationId: 'convo-2', agents: agents(statefulAgent) });
await flushAsync();
expect(fetchMock).toHaveBeenCalledTimes(1);
await expect(shouldSignalSandboxStart('convo-1')).resolves.toBe(true);
await expect(shouldSignalSandboxStart('convo-2')).resolves.toBe(true);
});
it('refires once the warm marker has expired', async () => {
jest.useFakeTimers({ doNotFake: ['setImmediate'] });
jest.setSystemTime(new Date('2026-07-13T00:00:00Z'));
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(statefulAgent) });
await flushAsync();
expect(fetchMock).toHaveBeenCalledTimes(1);
jest.setSystemTime(new Date('2026-07-13T01:00:00Z'));
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(statefulAgent) });
await flushAsync();
expect(fetchMock).toHaveBeenCalledTimes(2);
});
it('prewarms again after a short cold-after window even within the fire cooldown', async () => {
jest.useFakeTimers({ doNotFake: ['setImmediate'] });
jest.setSystemTime(new Date('2026-07-13T00:00:00Z'));
process.env.CODE_SANDBOX_COLD_AFTER_MS = '30000';
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(statefulAgent) });
await flushAsync();
expect(fetchMock).toHaveBeenCalledTimes(1);
jest.setSystemTime(new Date('2026-07-13T00:00:45Z'));
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(statefulAgent) });
await flushAsync();
expect(fetchMock).toHaveBeenCalledTimes(2);
});
it('signals while a prewarm is in flight and stops after it completes', async () => {
let resolveFetch: ((value: Response) => void) | undefined;
fetchMock.mockImplementation(
() =>
new Promise<Response>((resolve) => {
resolveFetch = resolve;
}),
);
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(statefulAgent) });
await flushAsync();
await expect(shouldSignalSandboxStart('convo-1')).resolves.toBe(true);
resolveFetch?.(mockResponse({ ok: true, status: 200 }));
await flushAsync();
await expect(shouldSignalSandboxStart('convo-1')).resolves.toBe(false);
});
it('keeps signaling when the prewarm request fails, without throwing', async () => {
fetchMock.mockRejectedValue(new Error('boom'));
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(statefulAgent) });
await flushAsync();
await expect(shouldSignalSandboxStart('convo-1')).resolves.toBe(true);
});
it('treats a non-2xx prewarm response as a failure', async () => {
fetchMock.mockResolvedValue(mockResponse({ ok: false, status: 503 }));
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(statefulAgent) });
await flushAsync();
await expect(shouldSignalSandboxStart('convo-1')).resolves.toBe(true);
});
it('does not mark the sandbox ready when the 2xx body fails to drain', async () => {
fetchMock.mockResolvedValue({
ok: true,
status: 200,
arrayBuffer: async () => {
throw new Error('body aborted');
},
} as unknown as Response);
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(statefulAgent) });
await flushAsync();
await expect(shouldSignalSandboxStart('convo-1')).resolves.toBe(true);
});
});
describe('shouldSignalSandboxStart / markSandboxReady', () => {
beforeEach(async () => {
await resetSandboxStateForTests();
process.env.LIBRECHAT_CODE_BASEURL_STATEFUL = 'http://code-stateful.test/v1';
delete process.env.CODE_SANDBOX_PREWARM;
delete process.env.CODE_SANDBOX_COLD_AFTER_MS;
});
afterEach(() => {
jest.useRealTimers();
delete process.env.LIBRECHAT_CODE_BASEURL_STATEFUL;
});
it('never signals for untracked conversations (stateless deployments)', async () => {
await expect(shouldSignalSandboxStart('never-seen')).resolves.toBe(false);
await expect(shouldSignalSandboxStart(null)).resolves.toBe(false);
await expect(shouldSignalSandboxStart(undefined)).resolves.toBe(false);
});
it('stops signaling after a real tool call marks the sandbox ready', async () => {
const fetchMock = jest
.spyOn(globalThis, 'fetch')
.mockImplementation(() => new Promise(() => undefined));
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(statefulAgent) });
await flushAsync();
await expect(shouldSignalSandboxStart('convo-1')).resolves.toBe(true);
await markSandboxReady('convo-1');
await expect(shouldSignalSandboxStart('convo-1')).resolves.toBe(false);
fetchMock.mockRestore();
});
it('never signals when the kill switch is on, even with an in-flight prewarm', async () => {
const fetchMock = jest
.spyOn(globalThis, 'fetch')
.mockImplementation(() => new Promise(() => undefined));
maybePrewarmCodeSandbox({ req, conversationId: 'convo-1', agents: agents(statefulAgent) });
await flushAsync();
process.env.CODE_SANDBOX_PREWARM = 'false';
await expect(shouldSignalSandboxStart('convo-1')).resolves.toBe(false);
fetchMock.mockRestore();
});
});