Skip to content

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

🪢 fix: Keep One Code File per Sandbox Destination (#15817)

JOJOe49cb798da9d
diff --git a/api/server/services/Files/Code/crud.js b/api/server/services/Files/Code/crud.js
index eec03bd14c..8e2fec15c2 100644
--- a/api/server/services/Files/Code/crud.js
+++ b/api/server/services/Files/Code/crud.js
@@ -185,7 +185,7 @@ async function deleteCodeEnvFile(req, file) {
* @param {'default'|'stateful'} [params.executionProfile] - Trusted execution profile.
* @param {string} [params.bridgeWorkerId] - Trusted worker selected for this execution.
* @param {AbortSignal} [params.signal] - Effective cancellation signal.
- * @returns {Promise<{ storage_session_id: string; file_id: string }>}
+ * @returns {Promise<{ storage_session_id: string; file_id: string; filename: string }>}
* The codeapi storage location of the uploaded file.
* @throws {Error} If there's an error during the upload process.
*/
@@ -237,6 +237,7 @@ async function uploadCodeEnvFile({
return {
storage_session_id: result.storage_session_id,
file_id: result.files[0].fileId,
+ filename: result.files[0].filename,
};
} catch (error) {
throw wrapCodeApiUploadError(error, `Error uploading code environment file: ${error.message}`);
diff --git a/api/server/services/Files/Code/crud.spec.js b/api/server/services/Files/Code/crud.spec.js
index 6f7ead2324..811e2cf6cb 100644
--- a/api/server/services/Files/Code/crud.spec.js
+++ b/api/server/services/Files/Code/crud.spec.js
@@ -429,7 +429,11 @@ describe('Code CRUD', () => {
});
const result = await uploadCodeEnvFile(baseUploadParams);
- expect(result).toEqual({ storage_session_id: 'sess-1', file_id: 'fid-1' });
+ expect(result).toEqual({
+ storage_session_id: 'sess-1',
+ file_id: 'fid-1',
+ filename: 'data.csv',
+ });
});
it('forwards Code API auth headers on upload requests', async () => {
diff --git a/api/server/services/Files/Code/process.js b/api/server/services/Files/Code/process.js
index 0d0eebfabf..f42da0e77c 100644
--- a/api/server/services/Files/Code/process.js
+++ b/api/server/services/Files/Code/process.js
@@ -11,7 +11,6 @@ const {
flattenArtifactPath,
createAxiosInstance,
getCodeApiAuthHeaders,
- isAbortError,
getCodeApiUploadOptions,
withCodeApiRateLimit,
withCodeApiUploadRecovery,
@@ -32,11 +31,12 @@ const {
buildCodeEnvDownloadQuery,
codeExecutionHeaders,
executeWorkspaceTool,
- claimCodeDestination,
- createCodeDestinationSet,
+ selectCodeFiles,
+ getCodeFileInfo,
+ getUploadedCodeEnvFilename,
+ checkCodeFileActive: checkIfActive,
CODE_OUTPUT_PREFLIGHT_MAX_BYTES,
CODE_OUTPUT_PREFLIGHT_MAX_COUNT,
- sortCodeFilesByDestinationPriority,
normalizeArtifactDeliveryFailure,
resolveDownloadPath,
} = require('@librechat/api');
@@ -52,11 +52,8 @@ const {
EModelEndpoint,
ErrorTypes,
mergeFileConfig,
- getCodeEnvRefs,
mergeCodeEnvRef,
- getCodeEnvRefForProfile,
getEndpointFileConfig,
- resolveSandboxFilename,
} = require('librechat-data-provider');
const { filterFilesByAgentAccess } = require('~/server/services/Files/permissions');
const { createFile, getFiles, updateFile, claimCodeFile } = require('~/models');
@@ -1124,74 +1121,20 @@ const processCodeOutput = async ({
}
};
-function checkIfActive(dateString) {
- const givenDate = new Date(dateString);
- const currentDate = new Date();
- const timeDifference = currentDate - givenDate;
- const hoursPassed = timeDifference / (1000 * 60 * 60);
- return hoursPassed < 23;
+function getSessionFileInfo(ref, req, route = {}, signal) {
+ return getCodeFileInfo({
+ ref,
+ req,
+ route,
+ signal,
+ request: axios,
+ getBaseURL: getCodeBaseURL,
+ getAuthHeaders: getCodeApiAuthHeaders,
+ });
}
-/**
- * Retrieves the `lastModified` time string for a specified file from Code Execution Server.
- *
- * @param {import('librechat-data-provider').CodeEnvRef} ref - Typed pointer
- * into codeapi storage. Carries kind/id/storage_session_id/file_id;
- * codeapi resolves the sessionKey from the request's auth context.
- * @param {ServerRequest} [req] - Current authenticated request, used to mint Code API auth.
- * @param {{baseUrl?: string, executionProfile?: 'default'|'stateful', bridgeWorkerId?: string}} [route]
- * Trusted host-selected Code API route.
- * @param {AbortSignal} [signal] - Effective run cancellation signal.
- *
- * @returns {Promise<string|null>}
- * A promise that resolves to the `lastModified` time string of the file if successful, or null if there is an
- * error in initialization or fetching the info.
- */
async function getSessionInfo(ref, req, route = {}, signal) {
- try {
- signal?.throwIfAborted();
- const baseURL = route.baseUrl ?? getCodeBaseURL();
- const authHeaders = await getCodeApiAuthHeaders(req, route.bridgeWorkerId);
- signal?.throwIfAborted();
- /* `/sessions/.../objects/...` is gated by codeapi's `sessionAuth`
- * middleware (post-Phase C). The middleware reconstructs the
- * sessionKey from the URL query (`kind`/`id`/`version?`) plus the
- * requester's auth context, then matches it against the cached
- * sessionKey on the storage bucket. We have the full `codeEnvRef`
- * here, so pass kind+id (+version when skill) directly. */
- const query = buildCodeEnvDownloadQuery({
- kind: ref.kind,
- id: ref.id,
- ...(ref.kind === 'skill' ? { version: ref.version } : {}),
- });
- const response = await axios({
- method: 'get',
- url: `${baseURL}/sessions/${ref.storage_session_id}/objects/${ref.file_id}${query}`,
- headers: {
- 'User-Agent': 'LibreChat/1.0',
- ...authHeaders,
- ...(route.executionProfile
- ? codeExecutionHeaders({
- executionProfile: route.executionProfile,
- bridgeWorkerId: route.bridgeWorkerId,
- })
- : {}),
- },
- httpAgent: codeServerHttpAgent,
- httpsAgent: codeServerHttpsAgent,
- timeout: 5000,
- signal,
- });
- signal?.throwIfAborted();
-
- return response.data?.lastModified;
- } catch (error) {
- if (signal?.aborted && isAbortError(error)) {
- throw error;
- }
- logger.debug('[getSessionInfo] session lookup failed (treating as cache miss)');
- return null;
- }
+ return (await getSessionFileInfo(ref, req, route, signal))?.lastModified ?? null;
}
const getPreviewContextSuffix = (file) => {
@@ -1357,44 +1300,24 @@ const primeFiles = async (options) => {
}
const files = [];
- const sessions = new Map();
const uploadOptions = getCodeApiUploadOptions(req, executionRouteKey);
/** All stale-file reuploads in this prime share one live-turn wait cap. */
const uploadRateLimitBudget = createCodeApiRateLimitBudget(uploadOptions.retryWaitMs);
let toolContext = '';
- /* Claim order decides which record keeps the bare `/mnt/data/<name>` path
- * when several share a filename, so it is fixed here rather than inherited
- * from `getFiles`'s `updatedAt` sort — usage accounting and re-upload both
- * bump `updatedAt`, which would repoint paths between turns. `file_ids` are
- * this agent's own resources; every other candidate came from the
- * conversation and is therefore seen by every agent in the run, so shared
- * files rank first and land on the same destination whichever agent primes
- * them. */
- const orderedFiles = sortCodeFilesByDestinationPriority(dbFiles, agentResourceIds);
- const destinations = createCodeDestinationSet();
-
- /* Per-file path counters — emitted at the bottom so a single
- * grep on `[primeCodeFiles]` shows the input volume, the per-file
- * paths taken, and the final dispatch summary in one trace. */
- let skippedNoRef = 0;
+ const { selected, skippedNoRef, skippedSuperseded } = await selectCodeFiles({
+ files: dbFiles,
+ privateFileIds: agentResourceIds,
+ routeKey: executionRouteKey,
+ getFileInfo: (ref) => getSessionFileInfo(ref, req, codeApiRoute, signal),
+ concurrency: uploadOptions.concurrency,
+ signal,
+ });
let reuploadFailures = 0;
let requiredCodeFiles = 0;
const reuploadFailureCategories = new Set();
- for (let i = 0; i < orderedFiles.length; i++) {
- const file = orderedFiles[i];
- if (!file) {
- continue;
- }
-
- const ref = getCodeEnvRefForProfile(file.metadata, executionRouteKey);
- const sourceRef = ref ?? getCodeEnvRefs(file.metadata)[0]?.[1];
- if (!sourceRef) {
- skippedNoRef += 1;
- logger.debug(`[primeCodeFiles] file=${file.file_id} path=skip reason=no-codeenvref`);
- continue;
- }
+ for (const { file, ref, sourceRef, sandboxName, isActive, getUploadTime } of selected) {
requiredCodeFiles += 1;
const session_id = sourceRef.storage_session_id;
const id = sourceRef.file_id;
@@ -1415,26 +1338,9 @@ const primeFiles = async (options) => {
* codeapi can resolve sessionKey per-file (kind switch +
* tenant prefix from auth context).
*/
- const sandboxName = resolveSandboxFilename(file.filename, file.type);
- let claimedDestination;
- const getDestination = () => {
- claimedDestination ??= claimCodeDestination(destinations, sandboxName, file.file_id);
- return claimedDestination;
- };
-
- const pushFile = (overrideSessionId, overrideId) => {
- /* Claimed here rather than up front so files that never reach the
- * sandbox — no code-env ref, or a failed re-upload — do not reserve a
- * name and push a file that does reach it onto a counter. */
+ const pushFile = (overrideSessionId, overrideId, destination = sandboxName) => {
/* The sandbox holds the converted name, not the record's, so the mount path has
* to follow the same rule provisioning uploaded under. */
- const destination = getDestination();
- if (destination !== file.filename) {
- logger.debug(
- `[primeCodeFiles] file=${file.file_id} destination=${destination} ` +
- `reason=name-collision filename=${file.filename}`,
- );
- }
toolContext = appendVisibleCodeFileContext(
toolContext,
getVisibleCodeFileContextLine(file, agentResourceIds, destination),
@@ -1486,7 +1392,7 @@ const primeFiles = async (options) => {
uploadCodeEnvFile({
req: options.req,
stream,
- filename: getDestination(),
+ filename: sandboxName,
kind: sourceRef.kind,
id: sourceRef.id,
...(sourceRef.kind === 'skill' ? { version: sourceRef.version } : {}),
@@ -1499,8 +1405,8 @@ const primeFiles = async (options) => {
/**
* Use the FRESH `(storage_session_id, file_id)` from the
- * reupload response and route it through the dedupe Map, the
- * persisted record, and the in-memory `files` list. The
+ * reupload response and route it through the persisted record
+ * and the in-memory `files` list. The
* original ref captured at the top of this iteration refers
* to the old, expired/missing sandbox object — using it here
* would silently re-introduce the bug `Graph.sessions`
@@ -1515,6 +1421,7 @@ const primeFiles = async (options) => {
id: sourceRef.id,
storage_session_id: uploaded.storage_session_id,
file_id: uploaded.file_id,
+ sandboxFilename: getUploadedCodeEnvFilename(uploaded, sandboxName),
executionProfile,
...(executionRouteKey !== executionProfile ? { executionRouteKey } : {}),
...(sourceRef.kind === 'skill' ? { version: sourceRef.version } : {}),
@@ -1527,8 +1434,7 @@ const primeFiles = async (options) => {
'metadata.codeEnvRef': updatedRefs.codeEnvRef,
[`metadata.codeEnvRefs.${executionRouteKey}`]: newRef,
});
- sessions.set(newRef.storage_session_id, true);
- pushFile(newRef.storage_session_id, newRef.file_id);
+ pushFile(newRef.storage_session_id, newRef.file_id, newRef.sandboxFilename);
logger.debug(
`[primeCodeFiles] file=${file.file_id} path=reupload-success ` +
`oldSession=${session_id} newSession=${newRef.storage_session_id} newFileId=${newRef.file_id}`,
@@ -1556,14 +1462,7 @@ const primeFiles = async (options) => {
await reuploadFile();
continue;
}
- if (sessions.has(session_id)) {
- logger.debug(
- `[primeCodeFiles] file=${file.file_id} path=cache-hit-by-session storage_session_id=${session_id}`,
- );
- pushFile();
- continue;
- }
- const uploadTime = await getSessionInfo(ref, req, codeApiRoute, signal);
+ const uploadTime = await getUploadTime();
signal?.throwIfAborted();
if (!uploadTime) {
logger.debug(
@@ -1573,7 +1472,7 @@ const primeFiles = async (options) => {
await reuploadFile();
continue;
}
- if (!checkIfActive(uploadTime)) {
+ if (!isActive) {
logger.debug(
`[primeCodeFiles] file=${file.file_id} path=reupload reason=stale ` +
`uploadTime=${uploadTime} storage_session_id=${session_id}`,
@@ -1581,7 +1480,6 @@ const primeFiles = async (options) => {
await reuploadFile();
continue;
}
- sessions.set(session_id, true);
logger.debug(
`[primeCodeFiles] file=${file.file_id} path=fresh-active storage_session_id=${session_id}`,
);
@@ -1597,7 +1495,8 @@ const primeFiles = async (options) => {
const { requestId, runId } = getPrimingCorrelation(req);
logger.debug(
`[primeCodeFiles] out: returned=${files.length} ` +
- `required=${requiredCodeFiles} skippedNoRef=${skippedNoRef} reuploadFailures=${reuploadFailures}`,
+ `required=${requiredCodeFiles} skippedNoRef=${skippedNoRef} ` +
+ `skippedSuperseded=${skippedSuperseded} reuploadFailures=${reuploadFailures}`,
);
if (allRequiredResourcesFailed) {
diff --git a/api/server/services/Files/Code/process.spec.js b/api/server/services/Files/Code/process.spec.js
index c073628538..e1508e665f 100644
--- a/api/server/services/Files/Code/process.spec.js
+++ b/api/server/services/Files/Code/process.spec.js
@@ -63,8 +63,6 @@ const mockParseSandboxImageChunk = jest.fn((response) => response);
* in promise.spec.ts and the finalizePreview unit tests below). */
const passthroughWithTimeout = async (promise) => promise;
jest.mock('@librechat/api', () => {
- const http = require('http');
- const https = require('https');
return {
resolveDownloadPath: (file) => file.storageKey || file.filepath,
logAxiosError: jest.fn(),
@@ -182,44 +180,12 @@ jest.mock('@librechat/api', () => {
if (version != null) params.set('version', String(version));
return `?${params.toString()}`;
}),
- codeServerHttpAgent: new http.Agent({ keepAlive: false }),
- codeServerHttpsAgent: new https.Agent({ keepAlive: false }),
- /* Sandbox destination assignment, mirrored the same way the identity
- * helpers above are. The real policy — directory-prefix conflicts, the
- * byte cap, flattening, the hashed suffix — lives in
- * `packages/api/src/files/code/destinations.ts` under its own
- * `destinations.spec.ts`; these stubs carry just enough of its shape
- * (an identity-derived suffix, shared-then-newest ordering) for the
- * `primeFiles` tests to assert that it is wired to `name` and to the tool
- * context at all. The suffix here is the raw identity rather than a
- * digest so the expectations below read as names. */
- createCodeDestinationSet: () => new Set(),
- claimCodeDestination: (set, name, identity) => {
- const dot = name.lastIndexOf('.');
- const stem = dot > 0 ? name.slice(0, dot) : name;
- const extension = dot > 0 ? name.slice(dot) : '';
- let destination = name;
- for (let counter = 1; set.has(destination); counter++) {
- const tail = counter === 1 ? '' : `-${counter}`;
- destination = `${stem}-${identity}${tail}${extension}`;
- }
- set.add(destination);
- return destination;
- },
- sortCodeFilesByDestinationPriority: (files, privateFileIds) => {
- const isPrivate = (file) => (privateFileIds?.has(file?.file_id) ? 1 : 0);
- const contentTime = (file) =>
- Math.max(
- file?.metadata?.sourceDispatchedAt ?? 0,
- new Date(file?.createdAt ?? 0).getTime() || 0,
- );
- return [...files].sort((a, b) => {
- const scope = isPrivate(a) - isPrivate(b);
- if (scope !== 0) return scope;
- const delta = contentTime(b) - contentTime(a);
- return delta !== 0 ? delta : (a?.file_id ?? '').localeCompare(b?.file_id ?? '');
- });
- },
+ codeServerHttpAgent: jest.requireActual('@librechat/api').codeServerHttpAgent,
+ codeServerHttpsAgent: jest.requireActual('@librechat/api').codeServerHttpsAgent,
+ selectCodeFiles: jest.requireActual('@librechat/api').selectCodeFiles,
+ getCodeFileInfo: jest.requireActual('@librechat/api').getCodeFileInfo,
+ getUploadedCodeEnvFilename: jest.requireActual('@librechat/api').getUploadedCodeEnvFilename,
+ checkCodeFileActive: jest.requireActual('@librechat/api').checkCodeFileActive,
};
});
@@ -232,6 +198,7 @@ jest.mock('@librechat/data-schemas', () => ({
}));
jest.mock('@librechat/agents', () => ({
+ ...jest.requireActual('@librechat/agents'),
getCodeBaseURL: jest.fn(() => 'https://code-api.example.com'),
}));
@@ -3120,6 +3087,7 @@ describe('Code Process', () => {
storage_session_id: 'NEW_SESSION',
file_id: 'NEW_ID',
executionProfile: 'default',
+ sandboxFilename: 'sentinel.txt',
},
'metadata.codeEnvRefs.default': {
kind: 'user',
@@ -3127,6 +3095,7 @@ describe('Code Process', () => {
storage_session_id: 'NEW_SESSION',
file_id: 'NEW_ID',
executionProfile: 'default',
+ sandboxFilename: 'sentinel.txt',
},
}),
);
@@ -3791,14 +3760,17 @@ describe('Code Process', () => {
});
});
- describe('primeFiles resolves sandbox destination collisions (#15443)', () => {
+ describe('primeFiles keeps one file per sandbox destination (#15443 follow-up)', () => {
/**
- * Codeapi mounts each input at a destination derived from its `name` and
- * rejects the whole `/exec` request when two entries land on one — and a
- * rejected request never reaches the sandbox, so nothing comes back to
- * collapse the pair. Every later turn re-primes both files and fails the
- * same way, which is why one duplicate filename kills code execution for
- * the rest of the conversation.
+ * Codeapi mounts a by-ref input at the filename recorded on the stored
+ * object — the file server's Content-Disposition — and only falls back to
+ * the `name` sent in `/exec` when that header is absent. A suffixed alias
+ * for a same-name duplicate therefore lands on the bare name anyway, and
+ * the sandbox rejects the whole request as conflicting destinations; the
+ * rejection recurs on every later turn because nothing comes back to
+ * collapse the pair. `primeFiles` keeps the newest content at each stored
+ * destination, preserving aliases assigned during upload, and drops collisions — the same collapse `ToolNode.updateCodeSession`
+ * applies once results come back.
*
* Only code-generated outputs are covered by the `(filename,
* conversationId, context, tenantId)` partial unique index; uploads carry
@@ -3815,6 +3787,7 @@ describe('Code Process', () => {
createdAt,
context,
sourceDispatchedAt,
+ sandboxFilename,
}) => ({
file_id,
filename,
@@ -3826,6 +3799,7 @@ describe('Code Process', () => {
...(sourceDispatchedAt != null ? { sourceDispatchedAt } : {}),
codeEnvRef: {
kind: 'user',
+ ...(sandboxFilename ? { sandboxFilename } : {}),
id: 'user-123',
storage_session_id,
file_id: `${file_id}-sandbox`,
@@ -3853,7 +3827,163 @@ describe('Code Process', () => {
const bySession = (result) =>
Object.fromEntries(result.files.map((f) => [f.storage_session_id, f.name]));
- it('gives two uploads sharing a filename distinct destinations', async () => {
+ it.each([false, true])('keeps a provisioned alias when expired=%s', async (expired) => {
+ setupActiveSessions();
+ const upload = jest.fn().mockImplementation(async ({ filename }) => ({
+ storage_session_id: `fresh-${filename}`,
+ file_id: `fresh-${filename}`,
+ }));
+ getStrategyFunctions.mockImplementation(() => ({
+ getDownloadStream: jest.fn().mockResolvedValue('stream'),
+ handleFileUpload: upload,
+ }));
+ if (expired) mockAxios.mockResolvedValue({ data: null });
+ getFiles.mockResolvedValue([
+ codeFile({
+ file_id: 'older',
+ filename: 'rows.csv',
+ sandboxFilename: 'rows-alias.csv',
+ storage_session_id: 'old',
+ }),
+ codeFile({
+ file_id: 'newer',
+ filename: 'rows.csv',
+ sandboxFilename: 'rows.csv',
+ storage_session_id: 'new',
+ }),
+ ]);
+ const result = await prime();
+ expect(result.files.map((file) => file.name).sort()).toEqual(['rows-alias.csv', 'rows.csv']);
+ if (expired) {
+ expect(upload.mock.calls.map(([args]) => args.filename).sort()).toEqual([
+ 'rows-alias.csv',
+ 'rows.csv',
+ ]);
+ } else {
+ expect(upload).not.toHaveBeenCalled();
+ }
+ });
+
+ it('recovers a converted stale image even when its storage session has a fresh sibling', async () => {
+ const upload = jest
+ .fn()
+ .mockResolvedValue({ storage_session_id: 'recovered', file_id: 'recovered-image' });
+ getStrategyFunctions.mockImplementation(() => ({
+ getDownloadStream: jest.fn().mockResolvedValue('webp-stream'),
+ handleFileUpload: upload,
+ }));
+ mockAxios.mockImplementation(async ({ url }) => ({
+ data: url.includes('newer-sandbox')
+ ? { lastModified: new Date().toISOString(), originalFilename: 'ready.txt' }
+ : { lastModified: '2020-01-01', originalFilename: 'plot-alias.png' },
+ }));
+ getFiles.mockResolvedValue([
+ codeFile({
+ file_id: 'newer',
+ filename: 'ready.txt',
+ storage_session_id: 'shared-session',
+ createdAt: new Date('2026-01-02'),
+ }),
+ {
+ ...codeFile({
+ file_id: 'older',
+ filename: 'plot.png',
+ storage_session_id: 'shared-session',
+ createdAt: new Date('2026-01-01'),
+ }),
+ type: 'image/webp',
+ },
+ ]);
+ const result = await prime();
+ expect(upload).toHaveBeenCalledWith(
+ expect.objectContaining({ filename: 'plot-alias.webp', stream: 'webp-stream' }),
+ );
+ expect(result.files).toContainEqual(
+ expect.objectContaining({
+ name: 'plot-alias.webp',
+ id: 'recovered-image',
+ storage_session_id: 'recovered',
+ }),
+ );
+ });
+
+ it('keeps the selected live image when earlier recovery crosses the freshness cutoff', async () => {
+ const now = Date.parse('2026-09-10T12:00:00Z');
+ const clock = jest.spyOn(Date, 'now').mockReturnValue(now);
+ const upload = jest.fn().mockImplementation(async () => {
+ clock.mockReturnValue(now + 2_000);
+ return { storage_session_id: 'recovered', file_id: 'recovered-text' };
+ });
+ getStrategyFunctions.mockImplementation(() => ({
+ getDownloadStream: jest.fn().mockResolvedValue('stream'),
+ handleFileUpload: upload,
+ }));
+ mockAxios.mockImplementation(async ({ url }) => ({
+ data: url.includes('newer-sandbox')
+ ? { lastModified: '2020-01-01', originalFilename: 'ready.txt' }
+ : {
+ lastModified: new Date(now - 23 * 3_600_000 + 1_000).toISOString(),
+ originalFilename: 'plot-alias.png',
+ },
+ }));
+ getFiles.mockResolvedValue([
+ codeFile({
+ file_id: 'newer',
+ filename: 'ready.txt',
+ storage_session_id: 'text-session',
+ createdAt: new Date('2026-01-02'),
+ }),
+ {
+ ...codeFile({
+ file_id: 'older',
+ filename: 'plot.png',
+ storage_session_id: 'image-session',
+ createdAt: new Date('2026-01-01'),
+ }),
+ type: 'image/webp',
+ },
+ ]);
+ try {
+ const result = await prime();
+ expect(upload).toHaveBeenCalledTimes(1);
+ expect(result.files).toContainEqual(
+ expect.objectContaining({ name: 'plot-alias.png', id: 'older-sandbox' }),
+ );
+ } finally {
+ clock.mockRestore();
+ }
+ });
+
+ it('normalizes a recovered nested path and advertises the upload receipt name', async () => {
+ const upload = jest.fn().mockResolvedValue({
+ storage_session_id: 'recovered',
+ file_id: 'receipt-id',
+ filename: 'accepted.csv',
+ });
+ getStrategyFunctions.mockImplementation(() => ({
+ getDownloadStream: jest.fn().mockResolvedValue('stream'),
+ handleFileUpload: upload,
+ }));
+ mockAxios.mockResolvedValue({
+ data: { originalFilename: 'my dir/file.csv', lastModified: '2020-01-01' },
+ });
+ getFiles.mockResolvedValue([
+ codeFile({ file_id: 'older', filename: 'my dir/file.csv', storage_session_id: 'old' }),
+ ]);
+ const result = await prime();
+ expect(upload).toHaveBeenCalledWith(expect.objectContaining({ filename: 'file.csv' }));
+ expect(result.files).toContainEqual(
+ expect.objectContaining({ name: 'accepted.csv', id: 'receipt-id' }),
+ );
+ expect(result.toolContext).toContain('/mnt/data/accepted.csv');
+ expect(mockUpdateFile).toHaveBeenCalledWith(
+ expect.objectContaining({
+ 'metadata.codeEnvRef': expect.objectContaining({ sandboxFilename: 'accepted.csv' }),
+ }),
+ );
+ });
+
+ it('keeps only the newest of two uploads sharing a filename', async () => {
setupActiveSessions();
getFiles.mockResolvedValue([
codeFile({
@@ -3872,28 +4002,17 @@ describe('Code Process', () => {
const { files, toolContext } = await prime();
- expect(files).toHaveLength(2);
- expect(new Set(files.map((f) => f.name)).size).toBe(2);
- /* The newest record keeps the bare path: when an execution rewrote an
- * uploaded file in place, the model's next read of that path has to
- * find its own edit rather than the superseded original. */
- expect(bySession({ files })).toEqual({
- 'sess-newer': 'image.png',
- 'sess-older': 'image-older.png',
- });
+ expect(bySession({ files })).toEqual({ 'sess-newer': 'image.png' });
expect(toolContext).toContain('/mnt/data/image.png');
- /* The displaced file is advertised at the path it actually mounts on,
- * alongside the name the user knows it by. */
- expect(toolContext).toContain('/mnt/data/image-older.png');
- expect(toolContext).toContain('(uploaded as image.png)');
+ expect(toolContext).not.toContain('uploaded as');
});
- it('assigns the same destinations regardless of the order getFiles returns', async () => {
+ it('keeps the same file regardless of the order getFiles returns', async () => {
/**
* `getFiles` sorts by `updatedAt` desc by default, and usage accounting
- * and re-upload both bump `updatedAt` — so claim order cannot come from
- * the query. If it did, a path a previous turn told the model about
- * would silently point at the other file.
+ * and re-upload both bump `updatedAt` — so the survivor cannot depend on
+ * the query order, or a path the model has been reading would silently
+ * flip to the other file between turns.
*/
const older = codeFile({
file_id: 'older',
@@ -3911,19 +4030,15 @@ describe('Code Process', () => {
setupActiveSessions();
getFiles.mockResolvedValue([older, newer]);
const ascending = await prime();
-
setupActiveSessions();
getFiles.mockResolvedValue([newer, older]);
const descending = await prime();
expect(bySession(ascending)).toEqual(bySession(descending));
- expect(bySession(ascending)).toEqual({
- 'sess-newer': 'image.png',
- 'sess-older': 'image-older.png',
- });
+ expect(bySession(ascending)).toEqual({ 'sess-newer': 'image.png' });
});
- it('separates a code output from the upload whose name it reused', async () => {
+ it('lets a code output supersede the upload whose name it reused', async () => {
setupActiveSessions();
getFiles.mockResolvedValue([
codeFile({
@@ -3943,22 +4058,13 @@ describe('Code Process', () => {
const { files, toolContext } = await prime();
- expect(bySession({ files })).toEqual({
- 'sess-output': 'data.csv',
- 'sess-upload': 'data-older.csv',
- });
+ expect(bySession({ files })).toEqual({ 'sess-output': 'data.csv' });
/* The output keeps the path it wrote, so it stays out of the context
- * exactly as an undisplaced generated file does. */
- expect(toolContext).toContain('/mnt/data/data-older.csv');
+ * exactly as any other generated file does. */
expect(toolContext).not.toContain('/mnt/data/data.csv');
});
- it('advertises a generated output that a newer upload displaced', async () => {
- /**
- * The model only knows it wrote `/mnt/data/report.png`. Once a newer
- * upload takes that path, silence would leave it reading the upload or
- * failing to find its own artifact.
- */
+ it('lets a newer upload supersede the generated output at the same path', async () => {
setupActiveSessions();
getFiles.mockResolvedValue([
codeFile({
@@ -3976,9 +4082,11 @@ describe('Code Process', () => {
}),
]);
- const { toolContext } = await prime();
+ const { files, toolContext } = await prime();
- expect(toolContext).toContain('/mnt/data/report-older.png (written earlier as report.png)');
+ expect(bySession({ files })).toEqual({ 'sess-upload': 'report.png' });
+ expect(toolContext).toContain('/mnt/data/report.png');
+ expect(toolContext).not.toContain('written earlier as');
});
it('ranks a rewritten output above an upload created after it', async () => {
@@ -4002,18 +4110,15 @@ describe('Code Process', () => {
const { files } = await prime();
- expect(bySession({ files })).toEqual({
- 'sess-output': 'data.csv',
- 'sess-upload': 'data-newer.csv',
- });
+ expect(bySession({ files })).toEqual({ 'sess-output': 'data.csv' });
});
it("lets a conversation file outrank the agent's own file of the same name", async () => {
/**
* Every agent in a run primes the conversation's files plus its own, so
- * a private file taking the bare path in one agent and not in another
- * would leave two agents advertising different paths for the same
- * shared file into one mount namespace.
+ * a private file surviving in one agent and not in another would leave
+ * two agents reading different files at the same path in one mount
+ * namespace.
*/
setupActiveSessions();
getFiles.mockResolvedValue([
@@ -4038,10 +4143,72 @@ describe('Code Process', () => {
},
});
- expect(bySession({ files })).toEqual({
- 'sess-shared': 'data.csv',
- 'sess-agent': 'data-agent-own.csv',
- });
+ expect(bySession({ files })).toEqual({ 'sess-shared': 'data.csv' });
+ });
+
+ it('does not re-upload a file it drops', async () => {
+ /**
+ * The destination decision has to come before recovery: a dropped file
+ * never reaches the sandbox, so re-uploading it would only
+ * spend a round trip and, on failure, count against the run.
+ */
+ const handleFileUpload = jest.fn();
+ getStrategyFunctions.mockImplementation(() => ({
+ getDownloadStream: jest.fn(),
+ handleFileUpload,
+ }));
+ mockAxios.mockImplementation(async ({ url }) =>
+ url.includes('sess-newer')
+ ? { data: { lastModified: new Date().toISOString(), originalFilename: 'image.png' } }
+ : { data: { originalFilename: 'image.png' } },
+ );
+ getFiles.mockResolvedValue([
+ codeFile({
+ file_id: 'older',
+ filename: 'image.png',
+ storage_session_id: 'sess-older',
+ createdAt: new Date('2026-01-01T00:00:00Z'),
+ }),
+ codeFile({
+ file_id: 'newer',
+ filename: 'image.png',
+ storage_session_id: 'sess-newer',
+ createdAt: new Date('2026-01-02T00:00:00Z'),
+ }),
+ ]);
+
+ const { files } = await prime();
+
+ expect(bySession({ files })).toEqual({ 'sess-newer': 'image.png' });
+ expect(handleFileUpload).not.toHaveBeenCalled();
+ });
+
+ it('drops a file whose path sits under a claimed name', async () => {
+ /**
+ * Codeapi's conflict rule also rejects a destination that is a directory
+ * prefix of another, so `data` and `data/rows.csv` cannot both mount;
+ * the ancestor check has to run at this layer or the pair still reaches
+ * the sandbox and fails the request.
+ */
+ setupActiveSessions();
+ getFiles.mockResolvedValue([
+ codeFile({
+ file_id: 'older',
+ filename: 'data/rows.csv',
+ storage_session_id: 'sess-older',
+ createdAt: new Date('2026-01-01T00:00:00Z'),
+ }),
+ codeFile({
+ file_id: 'newer',
+ filename: 'data',
+ storage_session_id: 'sess-newer',
+ createdAt: new Date('2026-01-02T00:00:00Z'),
+ }),
+ ]);
+
+ const { files } = await prime();
+
+ expect(bySession({ files })).toEqual({ 'sess-newer': 'data' });
});
it('leaves a single file on its own filename', async () => {
diff --git a/packages/api/src/agents/resources.test.ts b/packages/api/src/agents/resources.test.ts
index fff479b146..5a016364a5 100644
--- a/packages/api/src/agents/resources.test.ts
+++ b/packages/api/src/agents/resources.test.ts
@@ -2076,6 +2076,7 @@ describe('primeResources', () => {
storage_session_id: 'sess',
file_id: 'remote',
executionProfile: 'default',
+ sandboxFilename: 'default-alias.csv',
},
codeEnvRefs: {
default: {
@@ -2084,6 +2085,7 @@ describe('primeResources', () => {
storage_session_id: 'sess',
file_id: 'remote',
executionProfile: 'default',
+ sandboxFilename: 'default-alias.csv',
},
'stateful:env1': {
kind: 'user',
@@ -2091,6 +2093,7 @@ describe('primeResources', () => {
storage_session_id: 'sess-2',
file_id: 'remote-2',
executionProfile: 'stateful',
+ sandboxFilename: 'stateful-alias.csv',
},
},
},
@@ -2110,6 +2113,10 @@ describe('primeResources', () => {
});
expect(result.provisionState?.codeEnvFiles.map((f) => f.file_id)).toContain('stale-file');
+ expect(result.provisionState?.codeEnvRecoveryNames?.get('stale-file')).toEqual({
+ name: 'default-alias.csv',
+ isTargetScope: true,
+ });
expect(staleFile.metadata?.codeEnvRef).toBeUndefined();
expect(staleFile.metadata?.codeEnvRefs?.default).toBeUndefined();
expect(staleFile.metadata?.codeEnvRefs?.['stateful:env1']).toBeDefined();
@@ -2131,6 +2138,7 @@ describe('primeResources', () => {
storage_session_id: 'sess-default',
file_id: 'remote-default',
executionProfile: 'default',
+ sandboxFilename: 'default-alias.csv',
},
'stateful:env1': {
kind: 'user',
@@ -2138,6 +2146,7 @@ describe('primeResources', () => {
storage_session_id: 'sess-2',
file_id: 'remote-2',
executionProfile: 'stateful',
+ sandboxFilename: 'stateful-alias.csv',
executionRouteKey: 'stateful:env1',
},
},
@@ -2166,6 +2175,10 @@ describe('primeResources', () => {
}),
);
expect(result.provisionState?.codeEnvFiles.map((f) => f.file_id)).toContain('stateful-stale');
+ expect(result.provisionState?.codeEnvRecoveryNames?.get('stateful-stale')).toEqual({
+ name: 'stateful-alias.csv',
+ isTargetScope: true,
+ });
expect(statefulFile.metadata?.codeEnvRefs?.['stateful:env1']).toBeUndefined();
/* Another deployment's ref is untouched: this probe never asked about it. */
expect(statefulFile.metadata?.codeEnvRefs?.default).toBeDefined();
diff --git a/packages/api/src/agents/resources.ts b/packages/api/src/agents/resources.ts
index f23eeb1bb6..6b7e0b69a6 100644
--- a/packages/api/src/agents/resources.ts
+++ b/packages/api/src/agents/resources.ts
@@ -87,6 +87,8 @@ export type TLoadCodeApiKey = (userId: string) => Promise<string>;
export type ProvisionState = {
/** Files that need uploading to the code execution environment */
codeEnvFiles: TFile[];
+ /** Names from cleared refs on this state's active route; never reusable storage pointers. */
+ codeEnvRecoveryNames?: Map<string, { name: string; isTargetScope: boolean }>;
/** Files that need embedding into the vector DB for file_search */
vectorDBFiles: TFile[];
/** Set of file_ids confirmed alive in code env (from staleness check) */
@@ -514,6 +516,7 @@ const computeProvisionState = async ({
const scopedIds = agentScopedFileIds ?? new Set<string>();
const codeEnvFiles: TFile[] = [];
+ const codeEnvRecoveryNames: NonNullable<ProvisionState['codeEnvRecoveryNames']> = new Map();
const vectorDBFiles: TFile[] = [];
for (const file of provisionable) {
@@ -545,18 +548,22 @@ const computeProvisionState = async ({
canToolResourceConsume(EToolResources.execute_code, file.type ?? '')
) {
const legacyRef = file.metadata?.codeEnvRef;
+ const routeRef = codeEnvRefForRoute(file, activeCodeRouteKey);
/* Liveness answers only for the route it was probed on, so a ref belonging to
* another deployment is never cleared on the strength of this turn's answer. */
- const isStale =
- codeEnvRefForRoute(file, activeCodeRouteKey) != null &&
- aliveFileIds != null &&
- !aliveFileIds.has(file.file_id);
+ const isStale = routeRef != null && aliveFileIds != null && !aliveFileIds.has(file.file_id);
/** Staleness must be repaired even for files that pre-categorization already
* added to execute_code resources, so the check runs before the processed
* guard. Clear both the legacy ref and its route entry, else getCodeEnvRefs
* keeps resolving the dead session over the re-provisioned one. */
if (isStale) {
+ if (routeRef?.sandboxFilename) {
+ codeEnvRecoveryNames.set(file.file_id, {
+ name: routeRef.sandboxFilename,
+ isTargetScope: hasCodeRefForRoute(file, activeCodeRouteKey, codeScope),
+ });
+ }
logger.info(
`[primeResources] Code env file expired for "${file.filename}" (${file.file_id}), will re-provision on tool use`,
);
@@ -611,6 +618,7 @@ const computeProvisionState = async ({
}
return {
codeEnvFiles,
+ codeEnvRecoveryNames,
vectorDBFiles,
aliveFileIds: aliveFileIds ?? new Set(),
agentScopedFileIds: new Set(scopedIds),
diff --git a/packages/api/src/files/code/form.spec.ts b/packages/api/src/files/code/form.spec.ts
index da8d2d815e..5b1d537fb3 100644
--- a/packages/api/src/files/code/form.spec.ts
+++ b/packages/api/src/files/code/form.spec.ts
@@ -1,7 +1,6 @@
-import { Readable } from 'stream';
import FormData from 'form-data';
-
-import { appendCodeEnvFile, getCodeEnvFileOptions } from './form';
+import { Readable } from 'stream';
+import { appendCodeEnvFile, getCodeEnvFileOptions, getCodeEnvUploadFilename } from './form';
function renderMultipartDisposition(append: (form: FormData) => void): Promise<string> {
const form = new FormData();
@@ -23,6 +22,21 @@ function renderMultipartDisposition(append: (form: FormData) => void): Promise<s
}
describe('code env FormData filenames', () => {
+ it.each([
+ ['my dir/file.csv', 'file.csv'],
+ ['safe/file.csv', 'safe/file.csv'],
+ ['分析/結果📊.csv', '分析/結果📊.csv'],
+ ['../../file.csv', 'file.csv'],
+ ])('plans the exact multipart destination for %s', async (input, expected) => {
+ const destination = getCodeEnvUploadFilename(input);
+ expect(destination).toBe(expected);
+ expect(getCodeEnvUploadFilename(destination)).toBe(destination);
+ const disposition = await renderMultipartDisposition((form) => {
+ appendCodeEnvFile(form, Readable.from(['bytes']), destination);
+ });
+ expect(disposition).toContain(`filename="${destination}"`);
+ });
+
it('uses filepath for nested filenames so form-data preserves directories', async () => {
const disposition = await renderMultipartDisposition((form) => {
appendCodeEnvFile(form, Readable.from(['x']), 'pptx/pptx.py');
diff --git a/packages/api/src/files/code/form.ts b/packages/api/src/files/code/form.ts
index 707cf72182..906bbaac9a 100644
--- a/packages/api/src/files/code/form.ts
+++ b/packages/api/src/files/code/form.ts
@@ -72,6 +72,20 @@ export function getCodeEnvFileOptions(filename: string): CodeEnvFileOptions {
return { filename: basename, filepath: normalized };
}
+/** The destination encoded by the multipart adapter, including its safe-path fallback. */
+export function getCodeEnvUploadFilename(filename: string): string {
+ const options = getCodeEnvFileOptions(filename);
+ return options.filepath ?? options.filename;
+}
+
+/** Older upload strategies may omit the receipt name; use their shared multipart normalization. */
+export function getUploadedCodeEnvFilename(
+ uploaded: { filename?: string },
+ requestedFilename: string,
+): string {
+ return uploaded.filename || getCodeEnvUploadFilename(requestedFilename);
+}
+
export function appendCodeEnvFile(
form: FormData,
stream: NodeJS.ReadableStream,
diff --git a/packages/api/src/files/code/index.ts b/packages/api/src/files/code/index.ts
index 66aef1a3dc..c587875727 100644
--- a/packages/api/src/files/code/index.ts
+++ b/packages/api/src/files/code/index.ts
@@ -7,3 +7,4 @@ export * from './form';
export * from './identity';
export * from './image';
export * from './preflight';
+export * from './priming';
diff --git a/packages/api/src/files/code/priming.spec.ts b/packages/api/src/files/code/priming.spec.ts
new file mode 100644
index 0000000000..bb30756787
--- /dev/null
+++ b/packages/api/src/files/code/priming.spec.ts
@@ -0,0 +1,292 @@
+import type { CodeEnvRef, TFile } from 'librechat-data-provider';
+import { selectCodeFiles } from './priming';
+
+const file = (id: string, name: string, ref: Partial<CodeEnvRef> = {}, time = 1): TFile =>
+ ({
+ file_id: id,
+ filename: name,
+ type: 'text/csv',
+ createdAt: new Date(time),
+ metadata: {
+ codeEnvRef: { kind: 'user', id: 'user', storage_session_id: id, file_id: id, ...ref },
+ },
+ }) as TFile;
+
+const fresh = { lastModified: new Date().toISOString() };
+
+describe('selectCodeFiles', () => {
+ it('preserves provisioned aliases across turns and reuses legacy metadata probes', async () => {
+ const getFileInfo = jest.fn(async (ref: CodeEnvRef) => ({
+ ...fresh,
+ originalFilename: ref.file_id === 'older' ? 'rows-alias.csv' : 'rows.csv',
+ }));
+ const result = await selectCodeFiles({
+ files: [file('older', 'rows.csv'), file('newer', 'rows.csv', {}, 2)],
+ routeKey: 'default',
+ getFileInfo,
+ });
+ expect(result.selected.map((f) => f.sandboxName)).toEqual(['rows.csv', 'rows-alias.csv']);
+ await Promise.all(result.selected.map((f) => f.getUploadTime()));
+ expect(getFileInfo).toHaveBeenCalledTimes(2);
+ });
+
+ it('keeps stored aliases when expired and selects the requested deployment reference', async () => {
+ const older = file('older', 'rows.csv', { sandboxFilename: 'rows-old.csv' });
+ older.metadata!.codeEnvRefs = {
+ stateful: {
+ kind: 'user',
+ id: 'user',
+ storage_session_id: 'stateful',
+ file_id: 'remote',
+ sandboxFilename: 'rows-stateful.csv',
+ executionProfile: 'stateful',
+ },
+ };
+ const getFileInfo = jest.fn(async () => null);
+ const result = await selectCodeFiles({
+ files: [older, file('newer', 'rows.csv', { sandboxFilename: 'rows.csv' }, 2)],
+ routeKey: 'stateful',
+ getFileInfo,
+ });
+ expect(result.selected.map((f) => f.sandboxName)).toEqual(['rows-stateful.csv', 'rows.csv']);
+ expect(getFileInfo).toHaveBeenCalledTimes(1);
+ expect(await result.selected[0].getUploadTime()).toBeUndefined();
+ });
+
+ it('reserves a failed newest winner without reviving the superseded copy', async () => {
+ const getFileInfo = jest.fn(async () => null);
+ const result = await selectCodeFiles({
+ files: [
+ file('older', 'rows.csv', { sandboxFilename: 'rows.csv' }),
+ file('newer', 'rows.csv', { sandboxFilename: 'rows.csv' }, 2),
+ ],
+ routeKey: 'default',
+ getFileInfo,
+ });
+ expect(result.selected.map((f) => f.file.file_id)).toEqual(['newer']);
+ expect(result.skippedSuperseded).toBe(1);
+ await result.selected[0].getUploadTime();
+ expect(getFileInfo).toHaveBeenCalledTimes(2);
+ });
+
+ it('lets an output supersede an aliased upload at its actual destination', async () => {
+ const result = await selectCodeFiles({
+ files: [
+ file('upload', 'rows.csv', { sandboxFilename: 'rows-alias.csv' }),
+ file('output', 'rows-alias.csv', {}, 2),
+ ],
+ routeKey: 'default',
+ getFileInfo: async () => fresh,
+ });
+ expect(result.selected.map((f) => f.file.file_id)).toEqual(['output']);
+ });
+
+ it('keeps shared content ahead of private resources and rejects ancestor conflicts', async () => {
+ const result = await selectCodeFiles({
+ files: [file('shared', 'data/rows.csv'), file('private', 'data', {}, 2)],
+ privateFileIds: new Set(['private']),
+ routeKey: 'default',
+ getFileInfo: async () => fresh,
+ });
+ expect(result.selected.map((f) => f.file.file_id)).toEqual(['shared']);
+ });
+
+ it('recovers distinct expired paths with a directory-prefix conflict', async () => {
+ const result = await selectCodeFiles({
+ files: [
+ file('parent', 'reports', { sandboxFilename: 'reports' }),
+ file('child', 'reports/data.csv', { sandboxFilename: 'reports/data.csv' }),
+ ],
+ routeKey: 'default',
+ getFileInfo: async () => null,
+ });
+ expect(result.selected).toHaveLength(2);
+ expect(new Set(result.selected.map((f) => f.sandboxName)).size).toBe(2);
+ });
+
+ it('recovers every expired legacy input under a distinct persisted destination', async () => {
+ const originals = [file('older', 'rows.csv'), file('newer', 'rows.csv', {}, 2)];
+ const recovered = await selectCodeFiles({
+ files: originals,
+ routeKey: 'default',
+ getFileInfo: async () => null,
+ });
+ expect(recovered.selected).toHaveLength(2);
+ expect(new Set(recovered.selected.map((f) => f.sandboxName)).size).toBe(2);
+ const restored = recovered.selected.map(({ file: original, sandboxName, sourceRef }) => ({
+ ...original,
+ metadata: { codeEnvRef: { ...sourceRef, sandboxFilename: sandboxName } },
+ }));
+ const next = await selectCodeFiles({
+ files: restored,
+ routeKey: 'default',
+ getFileInfo: async () => fresh,
+ });
+ expect(next.selected.map((f) => f.sandboxName)).toEqual(
+ recovered.selected.map((f) => f.sandboxName),
+ );
+ });
+
+ it('allocates missing legacy inputs around confirmed live aliases', async () => {
+ const result = await selectCodeFiles({
+ files: [
+ file('missing', 'rows.csv', {}, 3),
+ file('live', 'rows.csv', { sandboxFilename: 'rows.csv' }),
+ ],
+ routeKey: 'default',
+ getFileInfo: async (ref) => (ref.file_id === 'live' ? fresh : null),
+ });
+ expect(result.selected.find((f) => f.file.file_id === 'live')?.sandboxName).toBe('rows.csv');
+ expect(result.selected.find((f) => f.file.file_id === 'missing')?.sandboxName).not.toBe(
+ 'rows.csv',
+ );
+ });
+
+ it.each([false, true])(
+ 'matches recovered image bytes while retaining a live remote name (expired=%s)',
+ async (expired) => {
+ const image = { ...file('image', 'plot.png'), type: 'image/webp' };
+ const result = await selectCodeFiles({
+ files: [image],
+ routeKey: 'default',
+ getFileInfo: async () => ({
+ originalFilename: 'plot-alias.png',
+ lastModified: expired ? '2020-01-01' : fresh.lastModified,
+ }),
+ });
+ expect(result.selected[0].sandboxName).toBe(expired ? 'plot-alias.webp' : 'plot-alias.png');
+ },
+ );
+
+ it('arbitrates collisions introduced by durable image conversion before uploading', async () => {
+ const result = await selectCodeFiles({
+ files: [
+ { ...file('image', 'plot.png', {}, 1), type: 'image/webp' },
+ file('live', 'plot.webp', { sandboxFilename: 'plot.webp' }, 2),
+ ],
+ routeKey: 'default',
+ getFileInfo: async (ref) =>
+ ref.file_id === 'live'
+ ? fresh
+ : { originalFilename: 'plot.png', lastModified: '2020-01-01' },
+ });
+ expect(result.selected).toHaveLength(2);
+ expect(result.selected.find((f) => f.file.file_id === 'live')?.sandboxName).toBe('plot.webp');
+ expect(result.selected.find((f) => f.file.file_id === 'image')?.sandboxName).toMatch(
+ /^plot-.+\.webp$/,
+ );
+ });
+
+ it('keeps a missing shared input independent of each agents private files', async () => {
+ const shared = file('shared', 'rows.csv');
+ const privateFile = file('private', 'rows.csv', { sandboxFilename: 'rows.csv' }, 2);
+ const getFileInfo = async (ref: CodeEnvRef) => (ref.file_id === 'private' ? fresh : null);
+ const first = await selectCodeFiles({ files: [shared], routeKey: 'default', getFileInfo });
+ const second = await selectCodeFiles({
+ files: [shared, privateFile],
+ privateFileIds: new Set(['private']),
+ routeKey: 'default',
+ getFileInfo,
+ });
+ expect(second.selected.find((f) => f.file.file_id === 'shared')?.sandboxName).toBe(
+ first.selected[0].sandboxName,
+ );
+ });
+
+ it('keeps the freshness decision paired with the selected image destination', async () => {
+ const now = Date.parse('2026-09-10T12:00:00Z');
+ const clock = jest.spyOn(Date, 'now').mockReturnValue(now);
+ const result = await selectCodeFiles({
+ files: [{ ...file('image', 'plot.png'), type: 'image/webp' }],
+ routeKey: 'default',
+ getFileInfo: async () => ({
+ originalFilename: 'plot.png',
+ lastModified: new Date(now - 23 * 3_600_000 + 1_000).toISOString(),
+ }),
+ });
+ clock.mockReturnValue(now + 2_000);
+ expect(result.selected[0]).toMatchObject({ isActive: true, sandboxName: 'plot.png' });
+ clock.mockRestore();
+ });
+
+ it('claims alternate-route names around destinations already present in the target route', async () => {
+ const missing = file('missing', 'rows.csv', { sandboxFilename: 'rows.csv' }, 2);
+ const live = file('live', 'rows.csv', {
+ sandboxFilename: 'rows.csv',
+ executionProfile: 'stateful',
+ });
+ const result = await selectCodeFiles({
+ files: [missing, live],
+ routeKey: 'stateful',
+ getFileInfo: async () => fresh,
+ });
+ expect(result.selected).toHaveLength(2);
+ expect(result.selected.find((f) => f.file.file_id === 'live')?.sandboxName).toBe('rows.csv');
+ expect(result.selected.find((f) => f.file.file_id === 'missing')?.sandboxName).not.toBe(
+ 'rows.csv',
+ );
+ });
+
+ it.each([false, true])(
+ 'uses the multipart fallback only during recovery (expired=%s)',
+ async (expired) => {
+ const result = await selectCodeFiles({
+ files: [file('nested', 'my dir/file.csv')],
+ routeKey: 'default',
+ getFileInfo: async () => ({
+ originalFilename: 'my dir/file.csv',
+ lastModified: expired ? '2020-01-01' : fresh.lastModified,
+ }),
+ });
+ expect(result.selected[0].sandboxName).toBe(expired ? 'file.csv' : 'my dir/file.csv');
+ },
+ );
+
+ it('arbitrates recovery names after the multipart adapter flattens paths', async () => {
+ const result = await selectCodeFiles({
+ files: [
+ file('older', 'my dir/file.csv'),
+ file('newer', 'file.csv', { sandboxFilename: 'file.csv' }, 2),
+ ],
+ routeKey: 'default',
+ getFileInfo: async (ref) =>
+ ref.file_id === 'newer'
+ ? fresh
+ : { originalFilename: 'my dir/file.csv', lastModified: '2020-01-01' },
+ });
+ expect(result.selected).toHaveLength(2);
+ expect(result.selected.find((f) => f.file.file_id === 'newer')?.sandboxName).toBe('file.csv');
+ expect(result.selected.find((f) => f.file.file_id === 'older')?.sandboxName).toMatch(
+ /^file-.+\.csv$/,
+ );
+ });
+
+ it('collapses confirmed old-path duplicates before allocating converted recovery names', async () => {
+ const result = await selectCodeFiles({
+ files: [
+ { ...file('older', 'plot.png'), type: 'image/webp' },
+ { ...file('newer', 'plot.png', {}, 2), type: 'image/webp' },
+ ],
+ routeKey: 'default',
+ getFileInfo: async () => ({ originalFilename: 'plot.png', lastModified: '2020-01-01' }),
+ });
+ expect(result.selected.map((f) => f.file.file_id)).toEqual(['newer']);
+ expect(result.selected[0].sandboxName).toBe('plot.webp');
+ });
+
+ it('propagates cancellation during legacy recovery', async () => {
+ const controller = new AbortController();
+ const reason = new Error('cancelled');
+ await expect(
+ selectCodeFiles({
+ files: [file('old', 'rows.csv')],
+ routeKey: 'default',
+ signal: controller.signal,
+ getFileInfo: async () => {
+ controller.abort(reason);
+ return null;
+ },
+ }),
+ ).rejects.toBe(reason);
+ });
+});
diff --git a/packages/api/src/files/code/priming.ts b/packages/api/src/files/code/priming.ts
new file mode 100644
index 0000000000..a8b0776103
--- /dev/null
+++ b/packages/api/src/files/code/priming.ts
@@ -0,0 +1,201 @@
+import {
+ getCodeEnvRefs,
+ getCodeEnvRefForProfile,
+ resolveSandboxFilename,
+} from 'librechat-data-provider';
+import type { CodeEnvRef, TFile } from 'librechat-data-provider';
+import type { AxiosInstance } from 'axios';
+import type { CodeExecutionRoute } from '../provision/service';
+import type { ServerRequest } from '~/types';
+import {
+ claimCodeDestination,
+ createCodeDestinationSet,
+ reserveCodeDestination,
+ sortCodeFilesByDestinationPriority,
+} from './destinations';
+import {
+ codeServerHttpAgent,
+ codeServerHttpsAgent,
+ createCodeApiUploadRegistry,
+ withCodeApiUploadSlot,
+} from '~/utils/code';
+import { codeExecutionHeaders } from '~/agents/execution';
+import { buildCodeEnvDownloadQuery } from './identity';
+import { getCodeEnvUploadFilename } from './form';
+import { isAbortError } from '~/utils/errors';
+
+export interface CodeFileInfo {
+ lastModified?: string;
+ originalFilename?: string;
+}
+
+/** The object metadata endpoint reports the same original filename as the download header. */
+export async function getCodeFileInfo({
+ ref,
+ req,
+ route,
+ signal,
+ request,
+ getBaseURL,
+ getAuthHeaders,
+}: {
+ ref: CodeEnvRef;
+ req: ServerRequest;
+ route: CodeExecutionRoute & { bridgeWorkerId?: string };
+ signal?: AbortSignal;
+ request: AxiosInstance;
+ getBaseURL: () => string;
+ getAuthHeaders: (req: ServerRequest, bridgeWorkerId?: string) => Promise<Record<string, string>>;
+}): Promise<CodeFileInfo | null> {
+ try {
+ signal?.throwIfAborted();
+ const headers = await getAuthHeaders(req, route.bridgeWorkerId);
+ signal?.throwIfAborted();
+ const query = buildCodeEnvDownloadQuery(ref);
+ const response = await request<CodeFileInfo>({
+ method: 'get',
+ url: `${route.baseUrl ?? getBaseURL()}/sessions/${ref.storage_session_id}/objects/${ref.file_id}${query}`,
+ headers: {
+ 'User-Agent': 'LibreChat/1.0',
+ ...headers,
+ ...(route.executionProfile
+ ? codeExecutionHeaders({
+ executionProfile: route.executionProfile,
+ bridgeWorkerId: route.bridgeWorkerId,
+ })
+ : {}),
+ },
+ httpAgent: codeServerHttpAgent,
+ httpsAgent: codeServerHttpsAgent,
+ timeout: 5000,
+ signal,
+ });
+ signal?.throwIfAborted();
+ return response.data;
+ } catch (error) {
+ if (signal?.aborted && isAbortError(error)) {
+ throw error;
+ }
+ signal?.throwIfAborted();
+ return null;
+ }
+}
+
+/** Matches the existing 23-hour code-storage freshness window. */
+export function checkCodeFileActive(dateString: string | undefined): boolean {
+ return dateString != null && (Date.now() - new Date(dateString).getTime()) / 3_600_000 < 23;
+}
+
+interface PrimedCodeFile {
+ file: TFile;
+ ref: CodeEnvRef | undefined;
+ sourceRef: CodeEnvRef;
+ sandboxName: string;
+ isActive: boolean;
+ getUploadTime: () => Promise<string | undefined>;
+}
+
+/** Reserve actual storage destinations before recovery so a failed winner never revives stale content. */
+export async function selectCodeFiles({
+ files,
+ privateFileIds,
+ routeKey,
+ getFileInfo,
+ concurrency,
+ signal,
+}: {
+ files: Array<TFile | null | undefined>;
+ privateFileIds?: ReadonlySet<string>;
+ routeKey: string;
+ getFileInfo: (ref: CodeEnvRef) => Promise<CodeFileInfo | null>;
+ concurrency?: number;
+ signal?: AbortSignal;
+}): Promise<{ selected: PrimedCodeFile[]; skippedNoRef: number; skippedSuperseded: number }> {
+ let skippedNoRef = 0;
+ let skippedSuperseded = 0;
+ const candidates = [];
+ const registry = createCodeApiUploadRegistry();
+ for (const file of sortCodeFilesByDestinationPriority(files, privateFileIds)) {
+ if (!file) {
+ continue;
+ }
+ const ref = getCodeEnvRefForProfile(file.metadata, routeKey);
+ const sourceRef = ref ?? getCodeEnvRefs(file.metadata)[0]?.[1];
+ if (!sourceRef) {
+ skippedNoRef++;
+ continue;
+ }
+ let probe: Promise<CodeFileInfo | null> | undefined;
+ const getInfo = () =>
+ (probe ??= withCodeApiUploadSlot({
+ registry,
+ scope: routeKey,
+ concurrency,
+ signal,
+ task: () => getFileInfo(sourceRef),
+ }));
+ candidates.push({ file, ref, sourceRef, getInfo });
+ }
+ const resolved = await Promise.all(
+ candidates.map(async (candidate) => {
+ const { file, ref, sourceRef, getInfo } = candidate;
+ const info = ref ? await getInfo() : null;
+ signal?.throwIfAborted();
+ const recovering = !ref || !checkCodeFileActive(info?.lastModified);
+ const storedName = sourceRef.sandboxFilename ?? info?.originalFilename;
+ const sandboxName = storedName ?? resolveSandboxFilename(file.filename, file.type);
+ const destination = recovering
+ ? getCodeEnvUploadFilename(resolveSandboxFilename(sandboxName, file.type))
+ : sandboxName;
+ const assignRecoveryName = !ref || recovering;
+ return {
+ file,
+ ref,
+ sourceRef,
+ isActive: !recovering,
+ sandboxName: destination,
+ storedName: ref ? storedName : undefined,
+ assignRecoveryName,
+ selectionPriority:
+ (privateFileIds?.has(file.file_id) ? 2 : 0) +
+ Number(!ref || (recovering && (!storedName || destination !== storedName))),
+ getUploadTime: async () => info?.lastModified,
+ };
+ }),
+ );
+ /** Collapse confirmed source-path collisions before renaming recovery files.
+ * Distinct old paths that normalize alike are independent inputs, not superseded copies. */
+ const storedDestinations = new Set<string>();
+ const surviving = resolved.filter((candidate) => {
+ if (candidate.storedName && storedDestinations.has(candidate.storedName)) {
+ skippedSuperseded++;
+ return false;
+ }
+ if (candidate.storedName) storedDestinations.add(candidate.storedName);
+ return true;
+ });
+ /** Keep shared files independent of each agent's private set. Within each
+ * scope, guessed recovery names cannot displace a confirmed stored path. */
+ surviving.sort((a, b) => a.selectionPriority - b.selectionPriority);
+ const destinations = createCodeDestinationSet();
+ const selected: PrimedCodeFile[] = [];
+ for (const candidate of surviving) {
+ if (candidate.assignRecoveryName) {
+ selected.push({
+ ...candidate,
+ sandboxName: claimCodeDestination(
+ destinations,
+ candidate.sandboxName,
+ candidate.file.file_id,
+ ),
+ });
+ continue;
+ }
+ if (!reserveCodeDestination(destinations, candidate.sandboxName)) {
+ skippedSuperseded++;
+ continue;
+ }
+ selected.push(candidate);
+ }
+ return { selected, skippedNoRef, skippedSuperseded };
+}
diff --git a/packages/api/src/files/provision/callback.spec.ts b/packages/api/src/files/provision/callback.spec.ts
index a17dc5bb9f..8408215bce 100644
--- a/packages/api/src/files/provision/callback.spec.ts
+++ b/packages/api/src/files/provision/callback.spec.ts
@@ -149,6 +149,205 @@ describe('createProvisionFilesCallback', () => {
}
});
+ it('gives shared files consistent names across agents with private collisions', async () => {
+ const shared = makeFile({ file_id: 'shared' });
+ const own = makeFile({ file_id: 'own' });
+ const { provisionFiles, provisionToCodeEnv } = buildHarness({
+ contexts: [
+ ['agent-a', { provisionState: state([own, { ...shared }], [], ['own']) }],
+ ['agent-b', { provisionState: state([{ ...shared }], []) }],
+ ],
+ });
+
+ await Promise.all([
+ provisionFiles([Constants.EXECUTE_CODE], 'agent-a'),
+ provisionFiles([Constants.EXECUTE_CODE], 'agent-b'),
+ ]);
+
+ const calls = provisionToCodeEnv.mock.calls.map(([args]) => args);
+ expect(calls.filter(({ file }) => file.file_id === 'shared')).toHaveLength(1);
+ expect(calls.find(({ file }) => file.file_id === 'shared').sandboxFilename).toBe('data.csv');
+ expect(calls.find(({ file }) => file.file_id === 'own').sandboxFilename).not.toBe('data.csv');
+ });
+
+ it('recovers a cleared reference under its saved route name', async () => {
+ const pending = state([makeFile()], []);
+ pending.codeEnvRecoveryNames = new Map([
+ ['file-1', { name: 'saved-alias.csv', isTargetScope: true }],
+ ]);
+ const { provisionFiles, provisionToCodeEnv } = buildHarness({
+ contexts: [['agent-a', { provisionState: pending }]],
+ });
+
+ const files = await provisionFiles([Constants.EXECUTE_CODE], 'agent-a');
+
+ expect(provisionToCodeEnv).toHaveBeenCalledWith(
+ expect.objectContaining({ sandboxFilename: 'saved-alias.csv' }),
+ );
+ expect(files?.[0].name).toBe('saved-alias.csv');
+ });
+
+ it.each(['agent-a', 'agent-b'])(
+ 'shares recovery around live private paths when %s runs first',
+ async (first) => {
+ const shared = makeFile({ file_id: 'shared' });
+ const own = makeFile({
+ file_id: 'own',
+ metadata: {
+ codeEnvRef: {
+ kind: 'agent',
+ id: 'agent-a',
+ storage_session_id: 'live',
+ file_id: 'own-remote',
+ sandboxFilename: 'data.csv',
+ },
+ },
+ });
+ const { provisionFiles, provisionToCodeEnv } = buildHarness({
+ contexts: [
+ [
+ 'agent-a',
+ {
+ provisionState: state([{ ...shared }], [], ['own']),
+ tool_resources: { execute_code: { files: [own] } },
+ },
+ ],
+ ['agent-b', { provisionState: state([{ ...shared }], []) }],
+ ],
+ });
+ const a = await provisionFiles([Constants.EXECUTE_CODE], first);
+ const b = await provisionFiles(
+ [Constants.EXECUTE_CODE],
+ first === 'agent-a' ? 'agent-b' : 'agent-a',
+ );
+ expect(provisionToCodeEnv).toHaveBeenCalledTimes(1);
+ expect(a[0].name).toBe(b[0].name);
+ expect(a[0].name).not.toBe('data.csv');
+ },
+ );
+
+ it('drops superseded saved paths before assigning recovery aliases', async () => {
+ const older = makeFile({ file_id: 'older', createdAt: '2026-01-01' });
+ const newer = makeFile({ file_id: 'newer', createdAt: '2026-02-01' });
+ const pending = state([older, newer], []);
+ pending.codeEnvRecoveryNames = new Map([
+ ['older', { name: 'data.csv', isTargetScope: true }],
+ ['newer', { name: 'data.csv', isTargetScope: true }],
+ ]);
+ const { provisionFiles, provisionToCodeEnv } = buildHarness({
+ contexts: [['agent-a', { provisionState: pending }]],
+ });
+ const files = await provisionFiles([Constants.EXECUTE_CODE], 'agent-a');
+ expect(provisionToCodeEnv).toHaveBeenCalledTimes(1);
+ expect(provisionToCodeEnv).toHaveBeenCalledWith(
+ expect.objectContaining({ file: newer, sandboxFilename: 'data.csv' }),
+ );
+ expect(files).toHaveLength(1);
+ expect(pending.codeEnvFiles).toHaveLength(0);
+ });
+
+ it('does not recover old content already superseded by a live saved path', async () => {
+ const older = makeFile({ file_id: 'older', createdAt: '2026-01-01' });
+ const newer = makeFile({
+ file_id: 'newer',
+ createdAt: '2026-02-01',
+ metadata: {
+ codeEnvRef: {
+ kind: 'user',
+ id: 'user-1',
+ storage_session_id: 'live',
+ file_id: 'new-remote',
+ sandboxFilename: 'data.csv',
+ },
+ },
+ });
+ const pending = state([older], []);
+ pending.codeEnvRecoveryNames = new Map([['older', { name: 'data.csv', isTargetScope: true }]]);
+ const { provisionFiles, provisionToCodeEnv } = buildHarness({
+ contexts: [
+ [
+ 'agent-a',
+ { provisionState: pending, tool_resources: { execute_code: { files: [newer] } } },
+ ],
+ ],
+ });
+ await provisionFiles([Constants.EXECUTE_CODE], 'agent-a');
+ expect(provisionToCodeEnv).not.toHaveBeenCalled();
+ expect(pending.codeEnvFiles).toHaveLength(0);
+ });
+
+ it('keeps recoverable prefix conflicts as separate inputs', async () => {
+ const pending = state([makeFile({ file_id: 'parent' }), makeFile({ file_id: 'child' })], []);
+ pending.codeEnvRecoveryNames = new Map([
+ ['parent', { name: 'reports', isTargetScope: true }],
+ ['child', { name: 'reports/data.csv', isTargetScope: true }],
+ ]);
+ const { provisionFiles, provisionToCodeEnv } = buildHarness({
+ contexts: [['agent-a', { provisionState: pending }]],
+ });
+ const result = await provisionFiles([Constants.EXECUTE_CODE], 'agent-a');
+ expect(provisionToCodeEnv).toHaveBeenCalledTimes(2);
+ expect(result).toHaveLength(2);
+ expect(new Set(result.map((f) => f.name)).size).toBe(2);
+ });
+
+ it.each([false, true])(
+ 'aliases foreign-scope names instead of suppressing inputs (cleared=%s)',
+ async (cleared) => {
+ const foreign = makeFile({
+ file_id: 'foreign',
+ metadata: {
+ codeEnvRef: {
+ kind: 'agent',
+ id: 'another-agent',
+ storage_session_id: 'foreign-session',
+ file_id: 'foreign-remote',
+ sandboxFilename: 'data.csv',
+ },
+ },
+ });
+ const own = makeFile({ file_id: 'own' });
+ const pending = state([foreign, own], []);
+ pending.codeEnvRecoveryNames = new Map([['own', { name: 'data.csv', isTargetScope: true }]]);
+ if (cleared) {
+ foreign.metadata = {};
+ pending.codeEnvRecoveryNames.set('foreign', { name: 'data.csv', isTargetScope: false });
+ }
+ const { provisionFiles, provisionToCodeEnv } = buildHarness({
+ contexts: [['agent-a', { provisionState: pending }]],
+ });
+ const result = await provisionFiles([Constants.EXECUTE_CODE], 'agent-a');
+ expect(provisionToCodeEnv).toHaveBeenCalledTimes(2);
+ expect(new Set(result.map((f) => f.name)).size).toBe(2);
+ },
+ );
+
+ it('uses route-wide ownership priority for confirmed recovery duplicates', async () => {
+ const privateFile = makeFile({ file_id: 'private', createdAt: '2026-02-01' });
+ const shared = makeFile({ file_id: 'shared', createdAt: '2026-01-01' });
+ const a = state([{ ...privateFile }, { ...shared }], [], ['private']);
+ const b = state([{ ...privateFile }, { ...shared }], []);
+ for (const pending of [a, b])
+ pending.codeEnvRecoveryNames = new Map([
+ ['private', { name: 'data.csv', isTargetScope: true }],
+ ['shared', { name: 'data.csv', isTargetScope: true }],
+ ]);
+ const { provisionFiles, provisionToCodeEnv } = buildHarness({
+ contexts: [
+ ['agent-a', { provisionState: a }],
+ ['agent-b', { provisionState: b }],
+ ],
+ });
+ await Promise.all([
+ provisionFiles([Constants.EXECUTE_CODE], 'agent-a'),
+ provisionFiles([Constants.EXECUTE_CODE], 'agent-b'),
+ ]);
+ expect(provisionToCodeEnv).toHaveBeenCalledTimes(1);
+ expect(provisionToCodeEnv).toHaveBeenCalledWith(
+ expect.objectContaining({ file: expect.objectContaining({ file_id: 'shared' }) }),
+ );
+ });
+
it('returns the provisioned refs so the batch can inject them', async () => {
const { provisionFiles } = buildHarness({
contexts: [['agent-a', { provisionState: state([makeFile()], []) }]],
@@ -237,6 +436,52 @@ describe('createProvisionFilesCallback', () => {
);
});
+ it('reserves a stored alias when adding a file on a later turn', async () => {
+ const existing = makeFile({
+ file_id: 'existing',
+ filename: 'data.csv',
+ metadata: {
+ codeEnvRef: {
+ kind: 'user',
+ id: 'u1',
+ storage_session_id: 's1',
+ file_id: 'r1',
+ sandboxFilename: 'data-alias.csv',
+ },
+ },
+ });
+ const queued = makeFile({ file_id: 'queued', filename: 'data-alias.csv' });
+ const { provisionFiles, provisionToCodeEnv } = buildHarness({
+ contexts: [
+ [
+ 'agent-a',
+ {
+ provisionState: state([queued], []),
+ tool_resources: { execute_code: { files: [existing] } },
+ },
+ ],
+ ],
+ });
+ await provisionFiles([Constants.EXECUTE_CODE], 'agent-a');
+ expect(provisionToCodeEnv).toHaveBeenCalledWith(
+ expect.objectContaining({ sandboxFilename: expect.not.stringMatching(/^data-alias\.csv$/) }),
+ );
+ });
+
+ it('arbitrates upload names after multipart path normalization', async () => {
+ const first = makeFile({ file_id: 'first', filename: 'my dir/data.csv' });
+ const second = makeFile({ file_id: 'second', filename: 'data.csv' });
+ const { provisionFiles, provisionToCodeEnv } = buildHarness({
+ contexts: [['agent-a', { provisionState: state([first, second], []) }]],
+ });
+ await provisionFiles([Constants.EXECUTE_CODE], 'agent-a');
+ const names = provisionToCodeEnv.mock.calls.map(
+ ([args]) => (args as { sandboxFilename: string }).sandboxFilename,
+ );
+ expect(names[0]).toBe('data.csv');
+ expect(names[1]).not.toBe('data.csv');
+ });
+
it('returns the refs to every agent sharing one upload', async () => {
const shared = makeFile();
const { provisionFiles } = buildHarness({
diff --git a/packages/api/src/files/provision/callback.ts b/packages/api/src/files/provision/callback.ts
index 714cbb4ac4..462fe1beee 100644
--- a/packages/api/src/files/provision/callback.ts
+++ b/packages/api/src/files/provision/callback.ts
@@ -1,13 +1,23 @@
import { Constants } from '@librechat/agents';
import { logger } from '@librechat/data-schemas';
-import { EToolResources, resolveSandboxFilename } from 'librechat-data-provider';
+import {
+ EToolResources,
+ getCodeEnvRefForProfile,
+ resolveSandboxFilename,
+} from 'librechat-data-provider';
import type { AgentToolResources, TFile } from 'librechat-data-provider';
import type { CodeEnvFile } from '@librechat/agents';
import type { CodeEnvRefUpdate, CodeExecutionRoute, ProvisionService } from './service';
import type { ProvisionState } from '~/agents/resources';
import type { ServerRequest } from '~/types';
-import { claimCodeDestination, createCodeDestinationSet } from '~/files/code/destinations';
+import {
+ claimCodeDestination,
+ createCodeDestinationSet,
+ reserveCodeDestination,
+ sortCodeFilesByDestinationPriority,
+} from '~/files/code/destinations';
import { createCodeApiRateLimitBudget, isCodeApiRateLimitError } from '~/utils';
+import { getCodeEnvUploadFilename } from '../code/form';
import { isCodeFileToolName } from '~/agents/tools';
/** Deferred database write produced by a successful provisioning call. */
@@ -249,26 +259,75 @@ export function createProvisionFilesCallback({
? [...(ctx.pendingProvisionedCodeFiles ?? [])]
: [];
if (needsCode && provisionState.codeEnvFiles.length > 0) {
- const queuedCodeFiles = provisionState.codeEnvFiles;
+ const queuedFileIds = new Set(provisionState.codeEnvFiles.map((file) => file.file_id));
+ const liveFiles =
+ (ctx.tool_resources as Record<string, { files?: TFile[] } | undefined>)[
+ EToolResources.execute_code
+ ]?.files ?? [];
+ const routePrivateFileIds = new Set<string>();
+ for (const candidate of agentToolContexts.values()) {
+ const route =
+ candidate.codeExecutionContext?.executionRouteKey ??
+ candidate.codeExecutionContext?.executionProfile ??
+ 'default';
+ if (route !== codeRouteKey) continue;
+ for (const id of candidate.provisionState?.agentScopedFileIds ?? [])
+ routePrivateFileIds.add(id);
+ }
+ const confirmedDestinations = new Set<string>();
+ const queuedCodeFiles = sortCodeFilesByDestinationPriority(
+ [
+ ...provisionState.codeEnvFiles,
+ ...liveFiles.filter((file) => !queuedFileIds.has(file.file_id)),
+ ],
+ routePrivateFileIds,
+ )
+ .filter((file): file is TFile => {
+ if (!file) return false;
+ const ref = getCodeEnvRefForProfile(file.metadata, codeRouteKey);
+ const recovery = provisionState.codeEnvRecoveryNames?.get(file.file_id);
+ const entityId = entityIdForFile(file);
+ const isTargetScope =
+ ref != null &&
+ ref.kind === (entityId ? 'agent' : 'user') &&
+ ref.id === (entityId ?? req.user?.id);
+ let storedName = recovery?.isTargetScope ? recovery.name : undefined;
+ if (isTargetScope) storedName = ref?.sandboxFilename;
+ // Prefix conflicts are independent recoverable inputs; only equal stored paths
+ // identify superseded content. Foreign-scope refs are claimable hints too.
+ if (storedName == null) return true;
+ if (confirmedDestinations.has(storedName)) return false;
+ confirmedDestinations.add(storedName);
+ return true;
+ })
+ .filter((file) => queuedFileIds.has(file.file_id));
/** Every file in this tool-load batch shares one wait allowance. This
* prevents a large recovery set from multiplying the live-turn delay. */
const codeApiRateLimitBudget = createCodeApiRateLimitBudget(
req.config?.endpoints?.agents?.codeApiMaxRetryWaitMs,
);
const destinations = createCodeDestinationSet();
- const existingCodeFiles = (
- ctx.tool_resources as Record<string, { files?: TFile[] } | undefined>
- )[EToolResources.execute_code]?.files;
- const queuedFileIds = new Set(queuedCodeFiles.map((file) => file.file_id));
- for (const existing of existingCodeFiles ?? []) {
- if (queuedFileIds.has(existing.file_id)) {
- continue;
+ // Live storage paths are immutable. Reserve the same route-wide set for every
+ // agent so private live resources cannot give a shared recovery divergent names.
+ for (const candidateContext of agentToolContexts.values()) {
+ const candidateRoute =
+ candidateContext.codeExecutionContext?.executionRouteKey ??
+ candidateContext.codeExecutionContext?.executionProfile ??
+ 'default';
+ if (candidateRoute !== codeRouteKey) continue;
+ const existingCodeFiles = (
+ candidateContext.tool_resources as
+ | Record<string, { files?: TFile[] } | undefined>
+ | undefined
+ )?.[EToolResources.execute_code]?.files;
+ for (const existing of existingCodeFiles ?? []) {
+ if (queuedFileIds.has(existing.file_id)) continue;
+ reserveCodeDestination(
+ destinations,
+ getCodeEnvRefForProfile(existing.metadata, codeRouteKey)?.sandboxFilename ??
+ resolveSandboxFilename(existing.filename, existing.type),
+ );
}
- claimCodeDestination(
- destinations,
- resolveSandboxFilename(existing.filename, existing.type),
- existing.file_id,
- );
}
for (const existing of provisionedCodeFiles) {
claimCodeDestination(destinations, existing.name, existing.id);
@@ -277,7 +336,14 @@ export function createProvisionFilesCallback({
queuedCodeFiles.map(async (file) => {
const sandboxFilename = claimCodeDestination(
destinations,
- resolveSandboxFilename(file.filename, file.type),
+ getCodeEnvUploadFilename(
+ resolveSandboxFilename(
+ getCodeEnvRefForProfile(file.metadata, codeRouteKey)?.sandboxFilename ??
+ provisionState.codeEnvRecoveryNames?.get(file.file_id)?.name ??
+ file.filename,
+ file.type,
+ ),
+ ),
file.file_id,
);
const provisioned = await shareProvisioning(
diff --git a/packages/api/src/files/provision/service.spec.ts b/packages/api/src/files/provision/service.spec.ts
index 03b413302c..7fce0c6401 100644
--- a/packages/api/src/files/provision/service.spec.ts
+++ b/packages/api/src/files/provision/service.spec.ts
@@ -23,6 +23,7 @@ jest.mock('@librechat/agents', () => ({
import { createCodeApiUploadRegistry } from '~/utils';
import { createProvisionService } from './service';
+import { selectCodeFiles } from '../code/priming';
const req = {
user: { id: 'u1' },
@@ -132,6 +133,43 @@ describe('createProvisionService', () => {
expect.objectContaining({ filename: 'photo.webp' }),
);
expect(result.referenceSet.codeEnvRefs?.default?.file_id).toBe('remote-1');
+ expect(result.refUpdate.ref.sandboxFilename).toBe('photo.webp');
+ expect(result.referenceSet.codeEnvRef?.sandboxFilename).toBe('photo.webp');
+ });
+
+ it('persists an assigned alias and preserves it through the next priming pass', async () => {
+ const { service } = buildService();
+ const original = makeFile();
+ const result = await service.provisionToCodeEnv({
+ req,
+ file: original,
+ sandboxFilename: 'data-alias.csv',
+ });
+ const { selected } = await selectCodeFiles({
+ files: [{ ...original, metadata: { ...original.metadata, ...result.referenceSet } }],
+ routeKey: 'default',
+ getFileInfo: async () => null,
+ });
+ expect(result.refUpdate.ref.sandboxFilename).toBe('data-alias.csv');
+ expect(selected[0].sandboxName).toBe('data-alias.csv');
+ });
+
+ it('persists the adapter receipt after normalizing a nested upload name', async () => {
+ const { service, uploadCodeEnvFile } = buildService();
+ uploadCodeEnvFile.mockResolvedValue({
+ storage_session_id: 's1',
+ file_id: 'remote-1',
+ filename: 'file.csv',
+ });
+ const result = await service.provisionToCodeEnv({
+ req,
+ file: makeFile({ filename: 'my dir/file.csv' }),
+ });
+ expect(uploadCodeEnvFile).toHaveBeenCalledWith(
+ expect.objectContaining({ filename: 'file.csv' }),
+ );
+ expect(result.refUpdate.ref.sandboxFilename).toBe('file.csv');
+ expect(result.sandboxFilename).toBe('file.csv');
});
it('refuses a source whose download contract differs', async () => {
diff --git a/packages/api/src/files/provision/service.ts b/packages/api/src/files/provision/service.ts
index a557a768c1..9177588760 100644
--- a/packages/api/src/files/provision/service.ts
+++ b/packages/api/src/files/provision/service.ts
@@ -25,6 +25,7 @@ import {
getCodeApiUploadOptions,
withCodeApiUploadRecovery,
} from '~/utils';
+import { getCodeEnvUploadFilename, getUploadedCodeEnvFilename } from '../code/form';
import { buildCodeEnvIdentityParams } from '~/files/code/identity';
import { getCodeApiAuthHeaders } from '~/auth/codeapi';
import { resolveDownloadPath } from '~/storage/path';
@@ -40,6 +41,7 @@ export interface ProvisionDeps {
handleFileUpload?: (params: Record<string, unknown>) => Promise<{
storage_session_id: string;
file_id: string;
+ filename?: string;
}>;
};
uploadVectors: (params: {
@@ -265,8 +267,9 @@ export function createProvisionService({
* be re-uploaded by priming, and a deployment whose only healthy Code API is the
* configured stateful one could not provision at all. */
const executionProfile = route?.executionProfile ?? 'default';
- const sandboxFilename =
- requestedSandboxFilename ?? resolveSandboxFilename(file.filename, file.type);
+ const sandboxFilename = getCodeEnvUploadFilename(
+ resolveSandboxFilename(requestedSandboxFilename ?? file.filename, file.type),
+ );
const uploadOptions = getCodeApiUploadOptions(
req,
route?.executionRouteKey ?? route?.baseUrl ?? executionProfile,
@@ -309,6 +312,7 @@ export function createProvisionService({
/* Merge rather than overwrite: the eager upload path persists the same shape via
* mergeCodeEnvRef, so both the legacy pointer and the route-keyed map stay in sync
* and pointers for other Code API routes survive re-provisioning. */
+ const storedSandboxFilename = getUploadedCodeEnvFilename(uploaded, sandboxFilename);
const ref: CodeEnvRef = {
kind,
id,
@@ -317,6 +321,7 @@ export function createProvisionService({
executionProfile,
...(route?.executionRouteKey ? { executionRouteKey: route.executionRouteKey } : {}),
provisionedAt: Date.now(),
+ sandboxFilename: storedSandboxFilename,
};
const referenceSet = mergeCodeEnvRef(file.metadata, ref);
const routeKey = route?.executionRouteKey ?? executionProfile;
@@ -327,7 +332,7 @@ export function createProvisionService({
return {
referenceSet,
- sandboxFilename,
+ sandboxFilename: storedSandboxFilename,
refUpdate: {
file_id: file.file_id,
routeKey,
diff --git a/packages/data-provider/src/codeEnvRef.ts b/packages/data-provider/src/codeEnvRef.ts
index e330f1fc07..544088a47b 100644
--- a/packages/data-provider/src/codeEnvRef.ts
+++ b/packages/data-provider/src/codeEnvRef.ts
@@ -61,6 +61,8 @@ interface CodeEnvRefBase {
/** Epoch ms when the file was uploaded to the code env; drives the liveness
* fast-path (distinct from the usage-bumped `updatedAt`). */
provisionedAt?: number;
+ /** Actual destination used when uploading this storage object. */
+ sandboxFilename?: string;
}
export type CodeExecutionProfile = 'default' | 'stateful';
diff --git a/packages/data-schemas/src/schema/codeEnvRef.spec.ts b/packages/data-schemas/src/schema/codeEnvRef.spec.ts
new file mode 100644
index 0000000000..5eaa91bef3
--- /dev/null
+++ b/packages/data-schemas/src/schema/codeEnvRef.spec.ts
@@ -0,0 +1,16 @@
+import { model, models } from 'mongoose';
+import { codeEnvRefSchema } from './codeEnvRef';
+
+it('preserves the uploaded sandbox filename through schema serialization', () => {
+ const Ref = models.SandboxFilenameRef ?? model('SandboxFilenameRef', codeEnvRefSchema);
+ const ref = new Ref({
+ kind: 'user',
+ id: 'user',
+ storage_session_id: 'session',
+ file_id: 'file',
+ sandboxFilename: 'rows-alias.csv',
+ });
+ expect(ref.validateSync()).toBeUndefined();
+ const restored = new Ref(ref.toObject());
+ expect(restored.toObject().sandboxFilename).toBe('rows-alias.csv');
+});
diff --git a/packages/data-schemas/src/schema/codeEnvRef.ts b/packages/data-schemas/src/schema/codeEnvRef.ts
index ed442d3e44..fdeccae730 100644
--- a/packages/data-schemas/src/schema/codeEnvRef.ts
+++ b/packages/data-schemas/src/schema/codeEnvRef.ts
@@ -17,6 +17,7 @@ export const codeEnvRefSchema: Schema = new Schema(
},
executionRouteKey: { type: String },
provisionedAt: { type: Number },
+ sandboxFilename: { type: String },
},
{ _id: false },
);