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
// Configurable file size limit for tests - use a getter so it can be changed per test
const fileSizeLimitConfig = { value: 20 * 1024 * 1024 }; // Default 20MB
// Mock librechat-data-provider with configurable file size limit
jest.mock('librechat-data-provider', () => {
const actual = jest.requireActual('librechat-data-provider');
return {
...actual,
mergeFileConfig: jest.fn((config) => {
const merged = actual.mergeFileConfig(config);
// Override the serverFileSizeLimit with our test value
return {
...merged,
get serverFileSizeLimit() {
return fileSizeLimitConfig.value;
},
};
}),
getEndpointFileConfig: jest.fn((options) => {
const config = actual.getEndpointFileConfig(options);
// Override fileSizeLimit with our test value
return {
...config,
get fileSizeLimit() {
return fileSizeLimitConfig.value;
},
};
}),
};
});
const { ErrorTypes, FileContext, ResourceType } = require('librechat-data-provider');
// Mock uuid
jest.mock('uuid', () => ({
v4: jest.fn(() => 'mock-uuid-1234'),
}));
// Mock axios — process.js now uses createAxiosInstance() from @librechat/api
const mockAxios = jest.fn();
mockAxios.post = jest.fn();
mockAxios.isAxiosError = jest.fn(() => false);
const mockClassifyCodeArtifact = jest.fn(() => 'other');
const mockExtractCodeArtifactRawText = jest.fn(() => null);
const mockExtractCodeArtifactInspectionText = jest.fn(async () => ({
text: null,
complete: false,
}));
const mockExtractCodeArtifactText = jest.fn(async () => null);
const mockExecuteWorkspaceTool = jest.fn();
const mockGetExtractedTextFormat = jest.fn((_name, _mime, text) => (text == null ? null : 'text'));
/* `hasOfficeHtmlPath` gates the persist-then-render split: when true, processCodeOutput
* returns `{ file, finalize }` with the file persisted at `status: 'pending'`
* and `finalize` runs the background extraction. Default false here so the
* legacy single-phase tests below (txt/png/etc) exercise the inline path
* unchanged. The dedicated office/finalize describe block toggles it on. */
const mockHasOfficeHtmlPath = jest.fn(() => false);
/* Stands in for the real chunk parser so a transport test can decide what
* one `/exec` response means without reaching into `packages/api`. */
const mockParseSandboxImageChunk = jest.fn((response) => response);
/* Pass-through `withTimeout`: tests don't drive timeouts here (those live
* in promise.spec.ts and the finalizePreview unit tests below). */
const passthroughWithTimeout = async (promise) => promise;
jest.mock('@librechat/api', () => {
return {
withFileProvisioning: jest.requireActual('@librechat/api').withFileProvisioning,
confirmFileProvision: jest.requireActual('@librechat/api').confirmFileProvision,
processCodeOutput: jest.requireActual('@librechat/api').processCodeOutput,
createSandboxTextReader: jest.requireActual('@librechat/api').createSandboxTextReader,
prepareCodeOutputBufferForInspection:
jest.requireActual('@librechat/api').prepareCodeOutputBufferForInspection,
getCodeFileContextLine: jest.requireActual('@librechat/api').getCodeFileContextLine,
appendCodeFileContextLine: jest.requireActual('@librechat/api').appendCodeFileContextLine,
resolveDownloadPath: (file) => file.storageKey || file.filepath,
logAxiosError: jest.fn(),
/* Behaviourally identical to the real predicate in
* `packages/api/src/files/code/errors.ts`, which owns the contract and
* its own spec. Inlined because this factory replaces the whole module
* and `requireActual` here would load the entire package. */
isMissingSandboxPathError: (reason) =>
/no such file or directory|cannot access|cannot find the path|enoent/i.test(reason),
getBasePath: jest.fn(() => ''),
sanitizeArtifactPath: jest.fn((name) => name),
flattenArtifactPath: jest.fn((name) => name.replace(/\//g, '__')),
createAxiosInstance: jest.fn(() => mockAxios),
normalizeArtifactDeliveryFailure: (value) =>
value?.code === 'artifact_delivery_failed'
? {
code: value.code,
status: value.status,
attempted: value.attempted,
delivered: value.delivered,
failed: value.failed,
}
: undefined,
executeWorkspaceTool: (...args) => mockExecuteWorkspaceTool(...args),
getCodeApiAuthHeaders: jest.fn(async () => ({})),
isAbortError: (error) =>
error?.name === 'AbortError' || error?.code === 'ABORT_ERR' || error?.code === 'ERR_CANCELED',
/* Windowing, sizing and rate-limit policy are real code in
* `packages/api` with their own tests (`files/code/image.spec.ts`,
* `utils/code.spec.ts`). These stand-ins are deliberately inert
* passthroughs — they assert nothing about that behavior, so the
* transport tests below cover only what this file still owns. */
createCodeApiRateLimitBudget: jest.fn(() => ({
limitMs: 20_000,
waitedMs: 0,
activeWaitEnds: new Set(),
})),
getCodeApiUploadOptions: jest.fn(() => ({
scope: 'default:user-123',
concurrency: 3,
retryWaitMs: 20_000,
})),
withCodeApiRateLimit: jest.fn(async ({ attempt }) => {
try {
return await attempt();
} catch (error) {
if (error?.response?.status !== 429) {
throw error;
}
return attempt();
}
}),
withCodeApiUploadRecovery: jest.fn(async ({ openSource, upload }) => {
try {
return await upload(await openSource());
} catch (error) {
if (error?.response?.status !== 429) {
throw error;
}
return upload(await openSource());
}
}),
buildSandboxImageReaderCode: jest.fn(
({ filePath, limit, offset, chunkBytes }) =>
`read ${filePath} ${limit} ${offset} ${chunkBytes}`,
),
parseSandboxImageChunk: jest.fn((response) => mockParseSandboxImageChunk(response)),
readWindowedSandboxImage: jest.fn(({ readChunk }) => readChunk({ code: 'read-one-window' })),
getCodeExecutionBaseUrl: jest.fn((profile) =>
profile === 'stateful' ? 'https://code-stateful.example.com' : 'https://code-api.example.com',
),
CODE_API_EXPECTED_PROFILE_HEADER: 'X-CodeAPI-Expected-Profile',
codeExecutionHeaders: ({ executionProfile, bridgeWorkerId }) => ({
'X-CodeAPI-Expected-Profile': executionProfile,
...(bridgeWorkerId ? { 'X-LibreChat-Code-Worker-ID': bridgeWorkerId } : {}),
}),
withTimeout: (...args) => passthroughWithTimeout(...args),
hasOfficeHtmlPath: (...args) => mockHasOfficeHtmlPath(...args),
/**
* Arrow-function indirection (vs. a direct `jest.fn()` reference) so
* tests can per-case `mockReturnValueOnce` / `mockImplementationOnce`
* on `mockClassifyCodeArtifact` / `mockExtractCodeArtifactText`.
* `jest.mock(...)` is hoisted above the outer `const` declarations
* at parse time, so a direct reference here would capture
* `undefined`; the arrow defers the binding to call time. The
* direct-`jest.fn()` mocks below stay constant per file.
*/
classifyCodeArtifact: (...args) => mockClassifyCodeArtifact(...args),
extractCodeArtifactRawText: (...args) => mockExtractCodeArtifactRawText(...args),
extractCodeArtifactInspectionText: (...args) => mockExtractCodeArtifactInspectionText(...args),
extractCodeArtifactText: (...args) => mockExtractCodeArtifactText(...args),
getBoundedCodeOutputByteLimit: (configured) =>
typeof configured === 'number' && Number.isFinite(configured) && configured > 0
? Math.min(configured, 64 * 1024 * 1024)
: 64 * 1024 * 1024,
CODE_OUTPUT_PREFLIGHT_MAX_BYTES: 64 * 1024 * 1024,
CODE_OUTPUT_PREFLIGHT_MAX_COUNT: 10,
/* `processCodeOutput` derives the `textFormat` trust flag for
* `IMongoFile` from this helper — Codex P1 review on PR #12934.
* The mock returns 'text' for non-null extractor output and null
* otherwise so the downstream `file.textFormat` field is set to
* a believable shape without modeling the office-HTML branch
* (the dispatcher under test isn't exercising that path). Per-
* test overrides via `mockGetExtractedTextFormat.mockReturnValue`
* if a case needs to assert the 'html' value. */
getExtractedTextFormat: (...args) => mockGetExtractedTextFormat(...args),
getStorageMetadata: jest.fn(() => ({})),
/* Identity helpers mirror codeapi's validator. The real impl
* lives in `packages/api/src/files/code/identity.ts` with its
* own dedicated `identity.spec.ts`; here we just stub the
* download-query builder since `processCodeOutput` calls it on
* every output download. */
buildCodeEnvDownloadQuery: jest.fn(({ kind, id, version }) => {
const params = new URLSearchParams({ kind, id });
if (version != null) params.set('version', String(version));
return `?${params.toString()}`;
}),
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,
};
});
jest.mock('@librechat/data-schemas', () => ({
logger: {
warn: jest.fn(),
debug: jest.fn(),
error: jest.fn(),
},
}));
jest.mock('@librechat/agents', () => ({
...jest.requireActual('@librechat/agents'),
getCodeBaseURL: jest.fn(() => 'https://code-api.example.com'),
}));
// Mock models
const mockClaimCodeFile = jest.fn();
const mockCommitCodeFile = jest.fn();
const mockUpdateFile = jest.fn();
const mockAcquireFileProvision = jest.fn(async () => true);
const mockReleaseFileProvision = jest.fn(async () => true);
const mockCommitFileProvision = jest.fn();
let mockProvisionRecovery;
jest.mock('~/server/services/Files/operations', () => ({
getFileStorage: () => ({
recovery: mockProvisionRecovery,
acquireFileProvision: (...args) => mockAcquireFileProvision(...args),
releaseFileProvision: (...args) => mockReleaseFileProvision(...args),
commitFileProvision: (...args) => mockCommitFileProvision(...args),
}),
}));
jest.mock('~/models', () => ({
createFile: jest.fn().mockResolvedValue({}),
getFiles: jest.fn(),
updateFile: mockUpdateFile,
acquireFileProvision: (...args) => mockAcquireFileProvision(...args),
releaseFileProvision: (...args) => mockReleaseFileProvision(...args),
commitFileProvision: (...args) => mockCommitFileProvision(...args),
claimCodeFile: (...args) => mockClaimCodeFile(...args),
commitCodeFile: mockCommitCodeFile,
}));
// Mock permissions (must be before process.js import)
jest.mock('~/server/services/Files/permissions', () => ({
filterFilesByAgentAccess: jest.fn((options) => Promise.resolve(options.files)),
}));
// Mock strategy functions
jest.mock('~/server/services/Files/strategies', () => ({
getStrategyFunctions: jest.fn(),
}));
// Mock convertImage
jest.mock('~/server/services/Files/images/convert', () => ({
convertImage: jest.fn(),
}));
jest.mock('~/server/services/Files/retention', () => ({
getRetentionExpiry: jest.fn(() => ({})),
}));
// Mock determineFileType
jest.mock('~/server/utils', () => ({
determineFileType: jest.fn(),
}));
const http = require('http');
const https = require('https');
const { createFile, getFiles } = require('~/models');
const { getRetentionExpiry } = require('~/server/services/Files/retention');
const { getStrategyFunctions } = require('~/server/services/Files/strategies');
const { convertImage } = require('~/server/services/Files/images/convert');
const { determineFileType } = require('~/server/utils');
const { logger } = require('@librechat/data-schemas');
const {
codeServerHttpAgent,
codeServerHttpsAgent,
getCodeApiAuthHeaders,
getStorageMetadata,
} = require('@librechat/api');
const {
processCodeOutput,
prepareCodeOutputForInspection,
getSessionInfo,
readSandboxFile,
readWorkspaceFile,
searchWorkspace,
listWorkspaceFiles,
writeWorkspaceFile,
previewWorkspaceEdit,
editWorkspaceFile,
readSandboxImage,
writeSandboxFile,
primeFiles,
} = require('./process');
describe('Code Process', () => {
const mockReq = {
user: { id: 'user-123' },
config: {
fileConfig: {},
fileStrategy: 'local',
imageOutputType: 'webp',
},
};
const baseParams = {
req: mockReq,
id: 'file-id-123',
name: 'test-file.txt',
apiKey: 'test-api-key',
toolCallId: 'tool-call-123',
conversationId: 'conv-123',
messageId: 'msg-123',
session_id: 'session-123',
};
beforeEach(() => {
jest.clearAllMocks();
mockProvisionRecovery = jest.requireActual('@librechat/api').createFileProvisionRecovery();
mockAcquireFileProvision.mockReset().mockResolvedValue(true);
mockReleaseFileProvision.mockReset().mockResolvedValue(true);
mockCommitFileProvision
.mockReset()
.mockImplementation(async ({ claim, code, output, releaseOnly }) => {
if (releaseOnly) return true;
if (output) return mockCommitCodeFile(output.file, output.sourceDispatchedAt);
const result = await mockUpdateFile({
file_id: claim.file_id,
'metadata.codeEnvRef': code.legacyRef ?? code.ref,
[`metadata.codeEnvRefs.${code.routeKey}`]: code.ref,
});
return result !== null && result !== false;
});
fileSizeLimitConfig.value = 20 * 1024 * 1024;
// Default mock: atomic claim returns a new file record (no existing file)
mockClaimCodeFile.mockResolvedValue({
file_id: 'mock-uuid-1234',
user: 'user-123',
});
getFiles.mockResolvedValue(null);
createFile.mockResolvedValue({});
mockCommitCodeFile.mockReset();
mockCommitCodeFile.mockResolvedValue(true);
getStrategyFunctions.mockReturnValue({
saveBuffer: jest.fn().mockResolvedValue('/uploads/mock-file-path.txt'),
});
determineFileType.mockResolvedValue({ mime: 'text/plain' });
});
describe('code output inspection preflight', () => {
it('derives file content from downloaded bytes without persisting anything', async () => {
const buffer = Buffer.from('safe raw content');
mockAxios.mockResolvedValue({ data: buffer });
mockClassifyCodeArtifact.mockReturnValueOnce('utf8-text');
mockExtractCodeArtifactRawText.mockReturnValueOnce('safe raw content');
mockExtractCodeArtifactInspectionText.mockResolvedValueOnce({
text: 'safe extracted content',
complete: true,
});
const prepared = await prepareCodeOutputForInspection(baseParams);
expect(prepared).toEqual({
buffer,
extractedTextComplete: true,
file: {
name: 'test-file.txt',
filename: 'test-file.txt',
type: 'text/plain',
content: 'safe raw content',
extractedText: 'safe extracted content',
},
});
expect(mockClaimCodeFile).not.toHaveBeenCalled();
expect(mockCommitCodeFile).not.toHaveBeenCalled();
expect(getStrategyFunctions).not.toHaveBeenCalled();
});
it('persists the exact preflight buffer without downloading it again', async () => {
const preparedBuffer = Buffer.from('already inspected');
await processCodeOutput({ ...baseParams, preparedBuffer });
expect(mockAxios).not.toHaveBeenCalled();
expect(mockClaimCodeFile).toHaveBeenCalledTimes(1);
expect(mockCommitCodeFile).toHaveBeenCalledTimes(1);
});
it('does not overwrite a reused output when its storage claim is denied', async () => {
mockClaimCodeFile.mockResolvedValue({ file_id: 'existing-output', user: 'user-123' });
mockAcquireFileProvision.mockResolvedValueOnce(false);
const saveBuffer = jest.fn();
getStrategyFunctions.mockReturnValue({ saveBuffer });
await processCodeOutput({ ...baseParams, preparedBuffer: Buffer.from('new output') });
expect(saveBuffer).not.toHaveBeenCalled();
expect(mockCommitCodeFile).not.toHaveBeenCalled();
expect(mockReleaseFileProvision).not.toHaveBeenCalled();
});
it('holds regenerated output storage through primary write and full record commit', async () => {
mockClaimCodeFile.mockResolvedValue({
file_id: 'existing-output',
user: 'user-123',
messageId: 'original-message',
});
let finishWrite;
const writing = new Promise((resolve) => {
finishWrite = resolve;
});
const saveBuffer = jest.fn(async () => {
expect(mockAcquireFileProvision).toHaveBeenCalledTimes(1);
await writing;
return '/uploads/existing-output.txt';
});
getStrategyFunctions.mockReturnValue({ saveBuffer });
const pending = processCodeOutput({
...baseParams,
preparedBuffer: Buffer.from('new output'),
});
await new Promise((resolve) => setImmediate(resolve));
expect(saveBuffer).toHaveBeenCalledTimes(1);
expect(mockReleaseFileProvision).not.toHaveBeenCalled();
finishWrite();
const result = await pending;
expect(result.file.file_id).toBe('existing-output');
expect(result.file.messageId).toBe(baseParams.messageId);
expect(mockCommitCodeFile).toHaveBeenCalledWith(
expect.objectContaining({ messageId: 'original-message' }),
undefined,
);
expect(mockCommitFileProvision).toHaveBeenCalledWith(
expect.objectContaining({
output: expect.objectContaining({
file: expect.objectContaining({ file_id: 'existing-output' }),
}),
}),
);
expect(mockReleaseFileProvision).toHaveBeenCalledWith(
mockAcquireFileProvision.mock.calls[0][0],
);
});
it('enforces a caller-provided aggregate inspection budget while downloading', async () => {
mockAxios.mockResolvedValue({ data: Buffer.from('too large') });
await expect(
prepareCodeOutputForInspection({
...baseParams,
maxBytes: 4,
}),
).rejects.toThrow('Generated file exceeds the 4-byte transport limit');
expect(mockAxios).toHaveBeenCalledWith(
expect.objectContaining({
maxContentLength: 4,
maxBodyLength: 4,
}),
);
expect(mockClaimCodeFile).not.toHaveBeenCalled();
expect(mockCommitCodeFile).not.toHaveBeenCalled();
});
it('extracts text bytes even when the generated filename spoofs an image extension', async () => {
const buffer = Buffer.from('PRIVATE-SECRET');
mockAxios.mockResolvedValue({ data: buffer });
determineFileType.mockResolvedValueOnce(undefined);
mockClassifyCodeArtifact.mockReturnValueOnce('utf8-text');
mockExtractCodeArtifactRawText.mockReturnValueOnce('PRIVATE-SECRET');
mockExtractCodeArtifactInspectionText.mockResolvedValueOnce({
text: 'PRIVATE-SECRET',
complete: true,
});
const prepared = await prepareCodeOutputForInspection({
...baseParams,
name: 'secret.png',
});
expect(mockExtractCodeArtifactRawText).toHaveBeenCalledWith(buffer, 'utf8-text');
expect(prepared.file).toMatchObject({
name: 'secret.png',
type: 'text/plain',
content: 'PRIVATE-SECRET',
extractedText: 'PRIVATE-SECRET',
});
});
it('returns the explicit bounded fallback without a second download or persistence', async () => {
const result = await processCodeOutput({
...baseParams,
downloadFallback: true,
});
expect(result.file).toMatchObject({
filename: 'test-file.txt',
filepath: '/api/files/code/download/session-123/file-id-123',
});
expect(mockAxios).not.toHaveBeenCalled();
expect(mockClaimCodeFile).not.toHaveBeenCalled();
expect(mockCommitCodeFile).not.toHaveBeenCalled();
});
});
describe('published run artifacts', () => {
const scope = {
userId: 'user-123',
conversationId: 'conv-123',
runId: 'parent-run',
executionId: 'child-run',
agentId: 'child-agent',
sourceFileId: 'file-id-123',
};
const provenance = {
runId: scope.runId,
executionId: scope.executionId,
agentId: scope.agentId,
sourceFileId: scope.sourceFileId,
parentExecutionId: 'parent-execution',
publishedAt: '2026-09-11T16:00:00.000Z',
inputFileIds: ['input-pdf'],
};
it('stores the existing output pipeline result through the publication boundary', async () => {
const publish = jest.fn(async ({ file }) => ({
...file,
file_id: 'published-id',
user: scope.userId,
conversationId: scope.conversationId,
context: FileContext.run_artifact,
metadata: { ...file.metadata, runFile: provenance },
}));
const discard = jest.fn();
const result = await processCodeOutput({
...baseParams,
preparedBuffer: Buffer.from('report data'),
publication: { scope, provenance, publish, find: jest.fn(), discard },
});
expect(result.file).toMatchObject({
file_id: 'published-id',
filename: baseParams.name,
context: FileContext.run_artifact,
metadata: { runFile: provenance },
});
expect(publish).toHaveBeenCalledWith(expect.objectContaining({ scope, provenance }));
expect(mockClaimCodeFile).not.toHaveBeenCalled();
expect(mockCommitCodeFile).not.toHaveBeenCalled();
expect(discard).not.toHaveBeenCalled();
});
it('finalizes office previews against the canonical published file identity', async () => {
mockHasOfficeHtmlPath.mockReturnValueOnce(true);
const publish = jest.fn(async ({ file }) => ({
...file,
file_id: 'published-office-id',
user: scope.userId,
conversationId: scope.conversationId,
context: FileContext.run_artifact,
metadata: { ...file.metadata, runFile: provenance },
}));
const result = await processCodeOutput({
...baseParams,
name: 'report.csv',
preparedBuffer: Buffer.from('a,b\n1,2'),
publication: { scope, provenance, publish, find: jest.fn(), discard: jest.fn() },
});
expect(result.file.file_id).toBe('published-office-id');
expect(result.file.status).toBe('pending');
await result.finalize();
expect(require('~/models').updateFile).toHaveBeenCalledWith(
expect.objectContaining({ file_id: 'published-office-id' }),
{ previewRevision: result.previewRevision },
);
});
it('cleans a stored publication attempt when classification fails before metadata commit', async () => {
const { createRunArtifactPublisher } = jest.requireActual('@librechat/api');
const discard = jest.fn(async () => undefined);
const publishRunArtifactFile = jest.fn();
mockClassifyCodeArtifact.mockImplementationOnce(() => {
throw new Error('Classification failed after storage');
});
const publish = createRunArtifactPublisher({
claimRunArtifactFile: async () => ({ file_id: 'published-id' }),
publishRunArtifactFile,
findRunArtifactFile: async () => null,
processCodeOutput: (input) => processCodeOutput({ ...input, req: mockReq }),
prepare: async () => Buffer.from('report data'),
discard,
finalize: jest.fn(),
});
await expect(
publish({
scope,
provenance,
artifact: { id: baseParams.id, name: baseParams.name, sessionId: baseParams.session_id },
}),
).rejects.toThrow('durable storage');
expect(publishRunArtifactFile).not.toHaveBeenCalled();
expect(discard).toHaveBeenCalledWith(
expect.objectContaining({
file_id: 'mock-uuid-1234',
filepath: '/uploads/mock-file-path.txt',
metadata: undefined,
}),
);
expect(discard).toHaveBeenCalledTimes(1);
});
it('cleans a generated image cancelled after conversion without publishing it', async () => {
const { createRunArtifactPublisher } = jest.requireActual('@librechat/api');
const controller = new AbortController();
const discard = jest.fn(async () => undefined);
const publishRunArtifactFile = jest.fn();
convertImage.mockImplementationOnce(async () => {
controller.abort(new Error('Publication generation expired'));
return { filepath: '/uploads/generated.webp', bytes: 12, width: 2, height: 2 };
});
const publish = createRunArtifactPublisher({
claimRunArtifactFile: async () => ({ file_id: 'published-id' }),
publishRunArtifactFile,
findRunArtifactFile: async () => null,
processCodeOutput: (input) => processCodeOutput({ ...input, req: mockReq }),
prepare: async () => Buffer.from('image data'),
discard,
finalize: jest.fn(),
});
await expect(
publish({
scope,
provenance,
artifact: { id: baseParams.id, name: 'generated.png', sessionId: baseParams.session_id },
signal: controller.signal,
}),
).rejects.toThrow('generation expired');
expect(publishRunArtifactFile).not.toHaveBeenCalled();
expect(discard).toHaveBeenCalledWith(
expect.objectContaining({
filepath: '/uploads/generated.webp',
file_id: 'mock-uuid-1234',
metadata: undefined,
}),
);
expect(discard).toHaveBeenCalledTimes(1);
});
});
describe('atomic file claim (via processCodeOutput)', () => {
it('should reuse file_id from existing record via atomic claim', async () => {
mockClaimCodeFile.mockResolvedValue({
file_id: 'existing-file-id',
filename: 'test-file.txt',
usage: 2,
createdAt: '2024-01-01T00:00:00.000Z',
});
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
const { file: result } = await processCodeOutput(baseParams);
expect(mockClaimCodeFile).toHaveBeenCalledWith({
filename: 'test-file.txt',
conversationId: 'conv-123',
file_id: 'mock-uuid-1234',
user: 'user-123',
sourceDispatchedAt: expect.any(Number),
});
expect(result.file_id).toBe('existing-file-id');
expect(result.usage).toBe(3);
expect(result.createdAt).toBe('2024-01-01T00:00:00.000Z');
});
it('should create new file when no existing file found', async () => {
mockClaimCodeFile.mockResolvedValue({
file_id: 'mock-uuid-1234',
user: 'user-123',
});
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
const { file: result } = await processCodeOutput(baseParams);
expect(result.file_id).toBe('mock-uuid-1234');
expect(result.usage).toBe(1);
expect(getRetentionExpiry).toHaveBeenCalledWith(baseParams.req);
});
it('skips the file when the claim is newer than the background run (stale-harvest guard)', async () => {
/* A newer run owns the filename slot and the (filename, conversationId)
* unique index leaves stale bytes nowhere to live — the detached
* harvest must not overwrite fresh content. */
mockClaimCodeFile.mockResolvedValue({
file_id: 'existing-file-id',
filename: 'test-file.txt',
messageId: 'newer-run-msg',
updatedAt: '2024-01-02T00:00:00.000Z',
});
mockAxios.mockResolvedValue({ data: Buffer.alloc(100) });
const result = await processCodeOutput({
...baseParams,
freshClaimAfter: new Date('2024-01-01T00:00:00.000Z').getTime(),
});
expect(result).toBeNull();
expect(mockCommitCodeFile).not.toHaveBeenCalled();
});
it('still reuses the claim when it predates the background run', async () => {
mockClaimCodeFile.mockResolvedValue({
file_id: 'existing-file-id',
filename: 'test-file.txt',
updatedAt: '2024-01-01T00:00:00.000Z',
});
mockCommitCodeFile.mockResolvedValue(true);
mockAxios.mockResolvedValue({ data: Buffer.alloc(100) });
const { file: result } = await processCodeOutput({
...baseParams,
freshClaimAfter: new Date('2024-01-02T00:00:00.000Z').getTime(),
});
expect(result.file_id).toBe('existing-file-id');
expect(mockCommitCodeFile).toHaveBeenCalledWith(
expect.objectContaining({ file_id: 'existing-file-id' }),
new Date('2024-01-02T00:00:00.000Z').getTime(),
);
});
it('skips when a newer task holds an unwritten claim (insert stamp, no updatedAt yet)', async () => {
/* A newer task claimed the filename but its content write is still in
* flight: the claim-insert stamp alone must trip the guard. */
mockClaimCodeFile.mockResolvedValue({
file_id: 'existing-file-id',
filename: 'test-file.txt',
metadata: {
sourceDispatchedAt: new Date('2024-01-02T00:00:00.000Z').getTime(),
},
});
mockAxios.mockResolvedValue({ data: Buffer.alloc(100) });
const result = await processCodeOutput({
...baseParams,
freshClaimAfter: new Date('2024-01-01T00:00:00.000Z').getTime(),
});
expect(result).toBeNull();
expect(mockCommitCodeFile).not.toHaveBeenCalled();
});
it('omits output when the commit boundary rejects an overtaken claim', async () => {
mockClaimCodeFile.mockResolvedValue({
file_id: 'mock-uuid-1234',
user: 'user-123',
});
mockCommitCodeFile.mockResolvedValue(false);
mockAxios.mockResolvedValue({ data: Buffer.alloc(100) });
const result = await processCodeOutput({
...baseParams,
freshClaimAfter: new Date('2024-01-01T00:00:00.000Z').getTime(),
});
expect(result).toBeNull();
expect(mockCommitCodeFile).toHaveBeenCalledWith(
expect.objectContaining({
file_id: 'mock-uuid-1234',
metadata: expect.objectContaining({
sourceDispatchedAt: new Date('2024-01-01T00:00:00.000Z').getTime(),
}),
}),
new Date('2024-01-01T00:00:00.000Z').getTime(),
);
});
it('commits when the conditional write matches (ownership held through the write)', async () => {
mockClaimCodeFile.mockResolvedValue({
file_id: 'existing-file-id',
filename: 'test-file.txt',
updatedAt: '2024-01-01T00:00:00.000Z',
});
mockCommitCodeFile.mockResolvedValueOnce(true);
mockAxios.mockResolvedValue({ data: Buffer.alloc(100) });
const { file: result } = await processCodeOutput({
...baseParams,
freshClaimAfter: new Date('2024-01-02T00:00:00.000Z').getTime(),
});
expect(result.file_id).toBe('existing-file-id');
});
it('lets a newer task overwrite an OLDER task that wrote late (writer dispatch order wins)', async () => {
/* Old task (dispatched Jan 1) settled late and wrote at Jan 3;
* this task was dispatched Jan 2. Wall-clock updatedAt is newer
* than our dispatch, but the WRITER is older — overwrite. */
mockClaimCodeFile.mockResolvedValue({
file_id: 'existing-file-id',
filename: 'test-file.txt',
updatedAt: '2024-01-03T00:00:00.000Z',
metadata: {
sourceDispatchedAt: new Date('2024-01-01T00:00:00.000Z').getTime(),
},
});
mockCommitCodeFile.mockResolvedValue(true);
mockAxios.mockResolvedValue({ data: Buffer.alloc(100) });
const { file: result } = await processCodeOutput({
...baseParams,
freshClaimAfter: new Date('2024-01-02T00:00:00.000Z').getTime(),
});
expect(result.file_id).toBe('existing-file-id');
expect(result.metadata.sourceDispatchedAt).toBe(
new Date('2024-01-02T00:00:00.000Z').getTime(),
);
});
});
describe('processCodeOutput', () => {
it('forwards Code API auth headers when downloading generated output', async () => {
getCodeApiAuthHeaders.mockResolvedValueOnce({ Authorization: 'Bearer codeapi-token' });
mockAxios.mockResolvedValue({ data: Buffer.alloc(100) });
await processCodeOutput(baseParams);
expect(getCodeApiAuthHeaders).toHaveBeenCalledWith(mockReq, undefined);
expect(mockAxios).toHaveBeenCalledWith(
expect.objectContaining({
method: 'get',
headers: expect.objectContaining({
Authorization: 'Bearer codeapi-token',
'User-Agent': 'LibreChat/1.0',
}),
}),
);
});
describe('image file processing', () => {
it('should process image files using convertImage', async () => {
const imageParams = { ...baseParams, name: 'chart.png' };
const imageBuffer = Buffer.alloc(500);
mockAxios.mockResolvedValue({ data: imageBuffer });
const convertedFile = {
filepath: '/uploads/converted-image.webp',
bytes: 400,
};
convertImage.mockResolvedValue(convertedFile);
const { file: result } = await processCodeOutput(imageParams);
expect(convertImage).toHaveBeenCalledWith(
mockReq,
imageBuffer,
'high',
'mock-uuid-1234.png',
);
expect(result.type).toBe('image/webp');
expect(result.context).toBe(FileContext.execute_code);
expect(result.filename).toBe('chart.png');
});
it('persists tenantId on image code output records when present', async () => {
const tenantReq = { ...mockReq, user: { ...mockReq.user, tenantId: 'tenantA' } };
const imageBuffer = Buffer.alloc(500);
mockAxios.mockResolvedValue({ data: imageBuffer });
convertImage.mockResolvedValue({
filepath: '/t/tenantA/images/user-123/mock-uuid-1234.webp',
});
await processCodeOutput({
...baseParams,
req: tenantReq,
name: 'chart.png',
});
expect(mockClaimCodeFile).toHaveBeenCalledWith(
expect.objectContaining({ tenantId: 'tenantA' }),
);
expect(mockCommitCodeFile).toHaveBeenCalledWith(
expect.objectContaining({ tenantId: 'tenantA' }),
undefined,
);
});
it('should update existing image file with cache-busted filepath', async () => {
const imageParams = { ...baseParams, name: 'chart.png' };
mockClaimCodeFile.mockResolvedValue({
file_id: 'existing-img-id',
usage: 1,
createdAt: '2024-01-01T00:00:00.000Z',
});
const imageBuffer = Buffer.alloc(500);
mockAxios.mockResolvedValue({ data: imageBuffer });
convertImage.mockResolvedValue({ filepath: '/images/user-123/existing-img-id.webp' });
const { file: result } = await processCodeOutput(imageParams);
expect(convertImage).toHaveBeenCalledWith(
mockReq,
imageBuffer,
'high',
'existing-img-id.png',
);
expect(result.file_id).toBe('existing-img-id');
expect(result.usage).toBe(2);
expect(result.filepath).toMatch(/^\/images\/user-123\/existing-img-id\.webp\?v=\d+$/);
expect(logger.debug).toHaveBeenCalledWith(
expect.stringContaining('Updating existing file'),
);
});
});
describe('non-image file processing', () => {
it('should process non-image files using saveBuffer', async () => {
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
const mockSaveBuffer = jest.fn().mockResolvedValue('/uploads/saved-file.txt');
getStrategyFunctions.mockReturnValue({ saveBuffer: mockSaveBuffer });
determineFileType.mockResolvedValue({ mime: 'text/plain' });
const { file: result } = await processCodeOutput(baseParams);
expect(mockSaveBuffer).toHaveBeenCalledWith({
userId: 'user-123',
buffer: smallBuffer,
fileName: 'mock-uuid-1234__test-file.txt',
basePath: 'uploads',
});
expect(result.type).toBe('text/plain');
expect(result.filepath).toBe('/uploads/saved-file.txt');
expect(result.bytes).toBe(100);
});
it.each([
[
'slides.pptx',
'application/vnd.openxmlformats-officedocument.presentationml.presentation',
],
['sheet.xlsx', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'],
[
'document.docx',
'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
],
])('preserves stored metadata for code-generated office file %s', async (name, mime) => {
const cloudfrontReq = {
...mockReq,
user: { ...mockReq.user, tenantId: 'tenantA' },
config: { ...mockReq.config, fileStrategy: 'cloudfront' },
};
const smallBuffer = Buffer.alloc(100);
const filepath = `https://cdn.example.com/r/us-east-2/t/tenantA/uploads/user-123/mock-uuid-1234__${name}`;
const storageKey = `r/us-east-2/t/tenantA/uploads/user-123/mock-uuid-1234__${name}`;
mockAxios.mockResolvedValue({ data: smallBuffer });
determineFileType.mockResolvedValue({ mime });
mockHasOfficeHtmlPath.mockReturnValueOnce(true);
getStorageMetadata.mockReturnValueOnce({ storageKey, storageRegion: 'us-east-2' });
const mockSaveBuffer = jest.fn().mockResolvedValue(filepath);
getStrategyFunctions.mockReturnValue({ saveBuffer: mockSaveBuffer });
const { file: result, finalize } = await processCodeOutput({
...baseParams,
req: cloudfrontReq,
name,
});
expect(mockSaveBuffer).toHaveBeenCalledWith(
expect.objectContaining({
userId: 'user-123',
basePath: 'uploads',
tenantId: 'tenantA',
}),
);
expect(result).toMatchObject({
file_id: 'mock-uuid-1234',
user: 'user-123',
tenantId: 'tenantA',
source: 'cloudfront',
filename: name,
filepath,
storageKey,
storageRegion: 'us-east-2',
status: 'pending',
});
expect(mockCommitCodeFile).toHaveBeenCalledWith(
expect.objectContaining({
file_id: 'mock-uuid-1234',
user: 'user-123',
tenantId: 'tenantA',
source: 'cloudfront',
storageKey,
storageRegion: 'us-east-2',
}),
undefined,
);
expect(typeof finalize).toBe('function');
});
it('passes and persists tenantId for non-image code output records', async () => {
const tenantReq = { ...mockReq, user: { ...mockReq.user, tenantId: 'tenantA' } };
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
const mockSaveBuffer = jest
.fn()
.mockResolvedValue('/t/tenantA/uploads/user-123/mock-file-path.txt');
getStrategyFunctions.mockReturnValue({ saveBuffer: mockSaveBuffer });
await processCodeOutput({
...baseParams,
req: tenantReq,
});
expect(mockClaimCodeFile).toHaveBeenCalledWith(
expect.objectContaining({ tenantId: 'tenantA' }),
);
expect(mockSaveBuffer).toHaveBeenCalledWith(
expect.objectContaining({ tenantId: 'tenantA' }),
);
expect(mockCommitCodeFile).toHaveBeenCalledWith(
expect.objectContaining({ tenantId: 'tenantA' }),
undefined,
);
});
it('preserves nested directory paths in the DB record while flattening the storage key', async () => {
/* Regression test for the silent-data-loss path: when codeapi reports a
* file with a nested name like "test_folder/test_file.txt", LibreChat
* used to feed it through `sanitizeFilename` (basename-only), which
* persisted "test_file.txt" to the DB and made the file un-locatable on
* the next prime() (cat /mnt/data/test_folder/test_file.txt would
* 404). The fix: keep the path on the DB record (so primeFiles can
* place it back at the same nested location), but flatten it for the
* storage key (saveBuffer strategies key by single component). */
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
const mockSaveBuffer = jest.fn().mockResolvedValue('/uploads/saved.txt');
getStrategyFunctions.mockReturnValue({ saveBuffer: mockSaveBuffer });
const { file: result } = await processCodeOutput({
...baseParams,
name: 'test_folder/test_file.txt',
});
// Storage key flattens `/` to `__` so on-disk strategies don't
// accidentally create real subdirectories under uploads/.
expect(mockSaveBuffer).toHaveBeenCalledWith(
expect.objectContaining({
fileName: 'mock-uuid-1234__test_folder__test_file.txt',
}),
);
// DB row keeps the nested path verbatim — that's what primeFiles
// ships back to the sandbox on the next turn.
expect(result.filename).toBe('test_folder/test_file.txt');
// Claim is also keyed by the path-preserving name so the
// (filename, conversationId) compound key stays consistent.
expect(mockClaimCodeFile).toHaveBeenCalledWith(
expect.objectContaining({ filename: 'test_folder/test_file.txt' }),
);
});
it('passes a NAME_MAX-aware budget to flattenArtifactPath when composing the storage key', async () => {
/* Codex review P1: per-segment caps on the path-preserving form
* aren't enough — once the segments are joined with `__` for the
* storage key, deeply-nested or moderately long paths can still
* exceed filesystem NAME_MAX (255) and cause `ENAMETOOLONG` in
* saveBuffer. processCodeOutput must pass a file_id-aware budget
* to flattenArtifactPath so the cap holds end-to-end. The unit
* tests in `packages/api/src/utils/files.spec.ts` cover the
* truncation logic itself; this test covers the integration. */
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
const mockSaveBuffer = jest.fn().mockResolvedValue('/uploads/saved.bin');
getStrategyFunctions.mockReturnValue({ saveBuffer: mockSaveBuffer });
const flattenSpy = require('@librechat/api').flattenArtifactPath;
flattenSpy.mockClear();
await processCodeOutput({ ...baseParams, name: 'a/b/c.csv' });
// The handler should call flattenArtifactPath with both the
// safeName AND a budget = NAME_MAX (255) minus the prefix
// (`${file_id}__`). file_id mock is `mock-uuid-1234` (14 chars),
// so the budget should be 255 - 14 - 2 = 239.
expect(flattenSpy).toHaveBeenCalledWith(expect.any(String), 239);
});
it('passes the basename (not the full nested path) to classifyCodeArtifact and extractCodeArtifactText', async () => {
/* Codex review P2: with the path-preserving sanitizer, `safeName`
* can be a nested string like `reports.v1/Makefile`. The
* classifier reads `extensionOf` against the full string, which
* sees `.v1/Makefile` after the dotted-dir's first dot and
* misclassifies the file as `other` (so text extraction is
* skipped). Pass `path.basename(safeName)` instead. */
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
const mockSaveBuffer = jest.fn().mockResolvedValue('/uploads/saved.txt');
getStrategyFunctions.mockReturnValue({ saveBuffer: mockSaveBuffer });
await processCodeOutput({
...baseParams,
name: 'reports.v1/Makefile',
});
expect(mockClassifyCodeArtifact).toHaveBeenCalledWith('Makefile', expect.any(String));
expect(mockExtractCodeArtifactText).toHaveBeenCalledWith(
expect.any(Buffer),
'Makefile',
expect.any(String),
expect.any(String),
);
});
it('should detect MIME type from buffer', async () => {
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
determineFileType.mockResolvedValue({ mime: 'application/pdf' });
const { file: result } = await processCodeOutput({ ...baseParams, name: 'document.pdf' });
expect(determineFileType).toHaveBeenCalledWith(smallBuffer, true);
expect(result.type).toBe('application/pdf');
});
it('should fallback to application/octet-stream for unknown types', async () => {
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
determineFileType.mockResolvedValue(null);
const { file: result } = await processCodeOutput({ ...baseParams, name: 'unknown.xyz' });
expect(result.type).toBe('application/octet-stream');
});
});
describe('inline text extraction', () => {
it('should populate text on the file when extractor returns content', async () => {
const buffer = Buffer.from('hello world\n', 'utf-8');
mockAxios.mockResolvedValue({ data: buffer });
determineFileType.mockResolvedValue({ mime: 'text/plain' });
mockClassifyCodeArtifact.mockReturnValueOnce('utf8-text');
mockExtractCodeArtifactText.mockResolvedValueOnce('hello world\n');
const { file: result } = await processCodeOutput({ ...baseParams, name: 'note.txt' });
expect(mockClassifyCodeArtifact).toHaveBeenCalledWith('note.txt', 'text/plain');
expect(mockExtractCodeArtifactText).toHaveBeenCalledWith(
buffer,
'note.txt',
'text/plain',
'utf8-text',
);
expect(result.text).toBe('hello world\n');
expect(mockCommitCodeFile).toHaveBeenCalledWith(
expect.objectContaining({ text: 'hello world\n' }),
undefined,
);
});
it('should set text to null when extractor returns null so updates clear stale values', async () => {
const buffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: buffer });
determineFileType.mockResolvedValue({ mime: 'application/octet-stream' });
mockClassifyCodeArtifact.mockReturnValueOnce('other');
mockExtractCodeArtifactText.mockResolvedValueOnce(null);
const { file: result } = await processCodeOutput({ ...baseParams, name: 'archive.zip' });
expect(result.text).toBeNull();
const createCall = mockCommitCodeFile.mock.calls[0][0];
expect(createCall.text).toBeNull();
});
it('should overwrite a previously-stored text value when re-emitting a now-binary file', async () => {
// Same filename + conversationId already has a stored text value;
// claimCodeFile returns the existing record (isUpdate path).
mockClaimCodeFile.mockResolvedValueOnce({
file_id: 'existing-id',
filename: 'output.bin',
usage: 1,
createdAt: '2024-01-01T00:00:00.000Z',
});
const binaryBuffer = Buffer.from([0x00, 0xff, 0x00, 0xff]);
mockAxios.mockResolvedValue({ data: binaryBuffer });
determineFileType.mockResolvedValue({ mime: 'application/octet-stream' });
mockClassifyCodeArtifact.mockReturnValueOnce('other');
mockExtractCodeArtifactText.mockResolvedValueOnce(null);
await processCodeOutput({ ...baseParams, name: 'output.bin' });
// null (not omitted) so $set clears any prior `text` value.
const createCall = mockCommitCodeFile.mock.calls[0][0];
expect(createCall).toHaveProperty('text', null);
});
it('should not invoke text extraction for image files', async () => {
const imageBuffer = Buffer.alloc(500);
mockAxios.mockResolvedValue({ data: imageBuffer });
convertImage.mockResolvedValue({ filepath: '/uploads/x.webp', bytes: 400 });
await processCodeOutput({ ...baseParams, name: 'chart.png' });
expect(mockClassifyCodeArtifact).not.toHaveBeenCalled();
expect(mockExtractCodeArtifactText).not.toHaveBeenCalled();
});
it('clears deferred-preview lifecycle fields so a prior office record at this file_id stops looking pending', async () => {
/* Codex P2: same (filename, conversationId) was previously an
* office artifact, leaving status/previewError/previewRevision
* populated. The non-office update must reset them or the
* client renders the wrong state for the now non-office file. */
mockClaimCodeFile.mockResolvedValueOnce({
file_id: 'reused-id',
filename: 'output.txt',
usage: 1,
createdAt: '2024-01-01T00:00:00.000Z',
});
mockAxios.mockResolvedValue({ data: Buffer.from('hello') });
determineFileType.mockResolvedValue({ mime: 'text/plain' });
mockClassifyCodeArtifact.mockReturnValueOnce('text');
mockHasOfficeHtmlPath.mockReturnValueOnce(false);
mockExtractCodeArtifactText.mockResolvedValueOnce('hello');
await processCodeOutput({ ...baseParams, name: 'output.txt' });
const createCall = mockCommitCodeFile.mock.calls[0][0];
expect(createCall).toHaveProperty('status', null);
expect(createCall).toHaveProperty('previewError', null);
expect(createCall).toHaveProperty('previewRevision', null);
});
});
describe('file size limit enforcement', () => {
it('treats a zero configured limit as unlimited within the hard transport ceiling', async () => {
fileSizeLimitConfig.value = 0;
mockAxios.mockResolvedValue({ data: Buffer.alloc(100) });
await processCodeOutput(baseParams);
expect(mockAxios).toHaveBeenCalledWith(
expect.objectContaining({
maxContentLength: 64 * 1024 * 1024,
maxBodyLength: 64 * 1024 * 1024,
}),
);
expect(mockClaimCodeFile).toHaveBeenCalledTimes(1);
expect(mockCommitCodeFile).toHaveBeenCalledTimes(1);
});
it('should fallback to download URL when file exceeds size limit', async () => {
// Set a small file size limit for this test
fileSizeLimitConfig.value = 1000; // 1KB limit
const largeBuffer = Buffer.alloc(5000); // 5KB - exceeds 1KB limit
mockAxios.mockResolvedValue({ data: largeBuffer });
const { file: result } = await processCodeOutput(baseParams);
expect(mockAxios).toHaveBeenCalledWith(
expect.objectContaining({
maxContentLength: 1000,
maxBodyLength: 1000,
}),
);
expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('exceeds size limit'));
expect(result.filepath).toContain('/api/files/code/download/session-123/file-id-123');
expect(result.expiresAt).toBeDefined();
// Oversized files use the download fallback without committing metadata.
expect(mockCommitCodeFile).not.toHaveBeenCalled();
// Reset to default for other tests
fileSizeLimitConfig.value = 20 * 1024 * 1024;
});
it('uses the existing download fallback when Axios stops an oversized response', async () => {
fileSizeLimitConfig.value = 1000;
mockAxios.mockRejectedValue(new Error('maxContentLength size of 1000 exceeded'));
const { file: result } = await processCodeOutput(baseParams);
expect(result.filepath).toContain('/api/files/code/download/session-123/file-id-123');
expect(logger.warn).toHaveBeenCalledWith(
expect.stringContaining('Generated file exceeds size limit'),
);
expect(mockClaimCodeFile).not.toHaveBeenCalled();
expect(mockCommitCodeFile).not.toHaveBeenCalled();
fileSizeLimitConfig.value = 20 * 1024 * 1024;
});
});
describe('fallback behavior', () => {
it('preserves the stateful route in generated downloads and fallbacks', async () => {
mockAxios.mockRejectedValue(new Error('Network error'));
const executionRouteKey = `stateful:${'a'.repeat(32)}`;
const { file: result } = await processCodeOutput({
...baseParams,
codeApiBaseUrl: 'https://code-stateful.example.com',
executionProfile: 'stateful',
bridgeWorkerId: 'personal-worker-1',
executionRouteKey,
});
expect(mockAxios).toHaveBeenCalledWith(
expect.objectContaining({
url: expect.stringContaining('https://code-stateful.example.com/download/'),
headers: expect.objectContaining({
'X-CodeAPI-Expected-Profile': 'stateful',
'X-LibreChat-Code-Worker-ID': 'personal-worker-1',
}),
}),
);
expect(result.filepath).toContain('execution_profile=stateful');
expect(result.filepath).toContain(
`execution_route_key=${encodeURIComponent(executionRouteKey)}`,
);
});
it('should fallback to download URL when saveBuffer is not available', async () => {
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
getStrategyFunctions.mockReturnValue({ saveBuffer: null });
const { file: result } = await processCodeOutput(baseParams);
expect(logger.warn).toHaveBeenCalledWith(
expect.stringContaining('saveBuffer not available'),
);
expect(result.filepath).toContain('/api/files/code/download/');
expect(result.filename).toBe('test-file.txt');
});
it('should fallback to download URL on axios error', async () => {
mockAxios.mockRejectedValue(new Error('Network error'));
const { file: result } = await processCodeOutput(baseParams);
expect(logger.warn).toHaveBeenCalledWith(
expect.stringContaining('Falling back to Code API download URL for strategy local'),
);
expect(result.filepath).toContain('/api/files/code/download/session-123/file-id-123');
expect(result.conversationId).toBe('conv-123');
expect(result.messageId).toBe('msg-123');
expect(result.toolCallId).toBe('tool-call-123');
});
});
describe('usage counter increment', () => {
it('should set usage to 1 for new files', async () => {
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
const { file: result } = await processCodeOutput(baseParams);
expect(result.usage).toBe(1);
});
it('should increment usage for existing files', async () => {
mockClaimCodeFile.mockResolvedValue({
file_id: 'existing-id',
usage: 5,
createdAt: '2024-01-01',
});
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
const { file: result } = await processCodeOutput(baseParams);
expect(result.usage).toBe(6);
});
it('should handle existing file with undefined usage', async () => {
mockClaimCodeFile.mockResolvedValue({
file_id: 'existing-id',
createdAt: '2024-01-01',
});
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
const { file: result } = await processCodeOutput(baseParams);
expect(result.usage).toBe(1);
});
});
describe('metadata and file properties', () => {
it('should include codeEnvRef in metadata with kind: user', async () => {
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
const { file: result } = await processCodeOutput(baseParams);
expect(result.metadata).toEqual({
codeEnvRef: {
kind: 'user',
id: 'user-123',
storage_session_id: 'session-123',
file_id: 'file-id-123',
executionProfile: 'default',
},
codeEnvRefs: {
default: {
kind: 'user',
id: 'user-123',
storage_session_id: 'session-123',
file_id: 'file-id-123',
executionProfile: 'default',
},
},
sourceDispatchedAt: expect.any(Number),
});
});
it('persists the originating profile on a stateful artifact ref', async () => {
mockAxios.mockResolvedValue({ data: Buffer.alloc(100) });
const executionRouteKey = `stateful:${'a'.repeat(32)}`;
const { file: result } = await processCodeOutput({
...baseParams,
codeApiBaseUrl: 'https://code-stateful.example.com',
executionProfile: 'stateful',
executionRouteKey,
});
expect(result.metadata.codeEnvRef).toEqual(
expect.objectContaining({ executionProfile: 'stateful', executionRouteKey }),
);
expect(result.metadata.codeEnvRefs[executionRouteKey]).toEqual(result.metadata.codeEnvRef);
});
/* Phase C lock-in: outputs are ALWAYS user-scoped, never skill-scoped.
* Even when an execution turn invoked a skill (so input files were
* `kind: 'skill'` shared cross-user), the resulting output bucket
* tags `kind: 'user'` with the requesting user's id. This prevents
* cross-user leakage of artifacts a skill may have generated for
* one user — each user gets their own output sessionKey on codeapi.
*
* Drift hazard: someone reading the simple user-derivation may
* later think "we should respect input kind for outputs too" and
* widen output scope to match input scope. This test pins the
* intentional asymmetry so that change requires updating the test
* (and re-reading the rationale). */
it('outputs are user-scoped regardless of which skill the execution invoked', async () => {
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
const userA = { ...mockReq, user: { id: 'user-A' } };
const userB = { ...mockReq, user: { id: 'user-B' } };
const { file: outputA } = await processCodeOutput({ ...baseParams, req: userA });
const { file: outputB } = await processCodeOutput({ ...baseParams, req: userB });
// Each user's output ref is keyed by their own user id. The
// `id` field tracks the requesting user, never the skill.
expect(outputA.metadata.codeEnvRef).toEqual({
kind: 'user',
id: 'user-A',
storage_session_id: 'session-123',
file_id: 'file-id-123',
executionProfile: 'default',
});
expect(outputB.metadata.codeEnvRef).toEqual({
kind: 'user',
id: 'user-B',
storage_session_id: 'session-123',
file_id: 'file-id-123',
executionProfile: 'default',
});
// No skill identity leaks into the output ref under any property.
const refA = outputA.metadata.codeEnvRef;
const refB = outputB.metadata.codeEnvRef;
expect(refA.kind).not.toBe('skill');
expect(refB.kind).not.toBe('skill');
expect(refA).not.toHaveProperty('version');
expect(refB).not.toHaveProperty('version');
});
it('should set correct context for code-generated files', async () => {
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
const { file: result } = await processCodeOutput(baseParams);
expect(result.context).toBe(FileContext.execute_code);
});
it('should include toolCallId and messageId in result', async () => {
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
const { file: result } = await processCodeOutput(baseParams);
expect(result.toolCallId).toBe('tool-call-123');
expect(result.messageId).toBe('msg-123');
});
it('commits foreground output without a background dispatch constraint', async () => {
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
await processCodeOutput(baseParams);
expect(mockCommitCodeFile).toHaveBeenCalledWith(
expect.objectContaining({
file_id: 'mock-uuid-1234',
context: FileContext.execute_code,
}),
undefined,
);
});
});
describe('persistedMessageId (regression for cross-turn priming)', () => {
/**
* `getCodeGeneratedFiles` filters by `messageId IN <thread message ids>`
* to scope files to the current branch. If `processCodeOutput` overwrote
* the file's `messageId` with the current run's id on every update, a
* file re-touched by a later turn (e.g. a failed read attempt that
* re-shells the same filename) would lose its link to the assistant
* message that originally produced it. Subsequent turns then can't find
* it via `getCodeGeneratedFiles`, the priming chain has nothing to seed,
* and the model thinks its own prior-turn artifact disappeared.
*
* Contract:
* - On UPDATE (claimCodeFile returned an existing record): the persisted
* `messageId` is `claimed.messageId` (preserved). Falls back to the
* current run's `messageId` when the existing record predates the
* `messageId` field (legacy data).
* - On CREATE (new file): the persisted `messageId` is the current run's.
* - The runtime return value ALWAYS uses the current run's `messageId`
* via `Object.assign(file, { messageId, toolCallId })` so the artifact
* attaches to the correct tool_call in the live response.
*/
/**
* `processCodeOutput` mutates the file object after `commitCodeFile` returns
* (`Object.assign(file, { messageId, toolCallId })`) so the runtime
* caller sees the live messageId on the response. Reading
* `mockCommitCodeFile.mock.calls[0][0]` directly would therefore reflect the
* post-mutation state because JS captures by reference. To assert
* what was actually PERSISTED, snapshot the args at call time.
*/
function snapshotCommitCodeFileArgs() {
const snapshots = [];
mockCommitCodeFile.mockImplementation(async (file) => {
snapshots.push({ ...file });
return true;
});
return snapshots;
}
it('preserves the original messageId in the persisted record on UPDATE', async () => {
mockClaimCodeFile.mockResolvedValue({
file_id: 'existing-id',
filename: 'sentinel.txt',
usage: 1,
createdAt: '2024-01-01T00:00:00.000Z',
messageId: 'turn-1-original-msg',
});
const persisted = snapshotCommitCodeFileArgs();
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
await processCodeOutput({
...baseParams,
name: 'sentinel.txt',
messageId: 'turn-2-current-run-msg',
});
expect(persisted[0].messageId).toBe('turn-1-original-msg');
});
it('falls back to current run messageId on UPDATE when claimed.messageId is undefined (legacy record)', async () => {
// Legacy record predates the persistedMessageId tracking.
mockClaimCodeFile.mockResolvedValue({
file_id: 'legacy-id',
filename: 'legacy.txt',
usage: 1,
createdAt: '2024-01-01T00:00:00.000Z',
// messageId intentionally absent
});
const persisted = snapshotCommitCodeFileArgs();
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
await processCodeOutput({
...baseParams,
name: 'legacy.txt',
messageId: 'turn-N-current-run-msg',
});
expect(persisted[0].messageId).toBe('turn-N-current-run-msg');
});
it('uses the current run messageId on CREATE (no claimed record)', async () => {
mockClaimCodeFile.mockResolvedValue({
file_id: 'mock-uuid-1234',
user: 'user-123',
});
const persisted = snapshotCommitCodeFileArgs();
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
await processCodeOutput({
...baseParams,
messageId: 'turn-1-create-msg',
});
expect(persisted[0].messageId).toBe('turn-1-create-msg');
});
it('returns the CURRENT run messageId in the runtime response even on UPDATE (artifact attribution)', async () => {
// The persisted DB record keeps the original messageId, but the
// returned object surfaces the live messageId so the artifact lands
// on the correct tool_call in this run's response.
mockClaimCodeFile.mockResolvedValue({
file_id: 'existing-id',
filename: 'sentinel.txt',
usage: 1,
createdAt: '2024-01-01T00:00:00.000Z',
messageId: 'turn-1-original-msg',
});
const persisted = snapshotCommitCodeFileArgs();
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
const { file: result } = await processCodeOutput({
...baseParams,
name: 'sentinel.txt',
messageId: 'turn-2-current-run-msg',
});
// DB preserves original
expect(persisted[0].messageId).toBe('turn-1-original-msg');
// Runtime return surfaces the live (current) messageId
expect(result.messageId).toBe('turn-2-current-run-msg');
});
it('preserves the original messageId on UPDATE for image files too', async () => {
// Same contract as text files; the image branch builds its own file
// record and would silently regress if the ternary diverged there.
mockClaimCodeFile.mockResolvedValue({
file_id: 'existing-img',
filename: 'chart.png',
usage: 1,
createdAt: '2024-01-01T00:00:00.000Z',
messageId: 'turn-1-image-msg',
});
const persisted = snapshotCommitCodeFileArgs();
const imageBuffer = Buffer.alloc(500);
mockAxios.mockResolvedValue({ data: imageBuffer });
convertImage.mockResolvedValue({
filepath: '/uploads/chart.webp',
bytes: 400,
});
await processCodeOutput({
...baseParams,
name: 'chart.png',
messageId: 'turn-2-current-img-msg',
});
expect(persisted[0].messageId).toBe('turn-1-image-msg');
});
});
describe('socket pool isolation', () => {
it('should pass dedicated keepAlive:false agents to axios for processCodeOutput', async () => {
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
await processCodeOutput(baseParams);
const callConfig = mockAxios.mock.calls[0][0];
expect(callConfig.httpAgent).toBe(codeServerHttpAgent);
expect(callConfig.httpsAgent).toBe(codeServerHttpsAgent);
expect(callConfig.httpAgent).toBeInstanceOf(http.Agent);
expect(callConfig.httpsAgent).toBeInstanceOf(https.Agent);
expect(callConfig.httpAgent.keepAlive).toBe(false);
expect(callConfig.httpsAgent.keepAlive).toBe(false);
});
it('should pass dedicated keepAlive:false agents to axios for getSessionInfo', async () => {
mockAxios.mockResolvedValue({
data: [{ name: 'sess/fid', lastModified: new Date().toISOString() }],
});
await getSessionInfo({
kind: 'user',
id: 'user-1',
storage_session_id: 'sess',
file_id: 'fid',
});
const callConfig = mockAxios.mock.calls[0][0];
expect(callConfig.httpAgent).toBe(codeServerHttpAgent);
expect(callConfig.httpsAgent).toBe(codeServerHttpsAgent);
expect(callConfig.httpAgent.keepAlive).toBe(false);
expect(callConfig.httpsAgent.keepAlive).toBe(false);
});
it('forwards cancellation to the freshness request and preserves its error', async () => {
const controller = new AbortController();
const canceled = Object.assign(new Error('canceled'), {
name: 'CanceledError',
code: 'ERR_CANCELED',
});
mockAxios.mockImplementationOnce(async (config) => {
expect(config.signal).toBe(controller.signal);
controller.abort();
throw canceled;
});
await expect(
getSessionInfo(
{
kind: 'user',
id: 'user-1',
storage_session_id: 'sess',
file_id: 'fid',
},
mockReq,
{},
controller.signal,
),
).rejects.toBe(canceled);
});
it('forwards Code API auth headers when checking session object freshness', async () => {
getCodeApiAuthHeaders.mockResolvedValueOnce({ Authorization: 'Bearer freshness-token' });
mockAxios.mockResolvedValue({
data: { lastModified: '2024-01-01T00:00:00Z' },
});
await getSessionInfo(
{
kind: 'user',
id: 'user-123',
storage_session_id: 'session-123',
file_id: 'file-123',
},
mockReq,
);
expect(getCodeApiAuthHeaders).toHaveBeenCalledWith(mockReq, undefined);
expect(mockAxios).toHaveBeenCalledWith(
expect.objectContaining({
method: 'get',
headers: expect.objectContaining({
Authorization: 'Bearer freshness-token',
'User-Agent': 'LibreChat/1.0',
}),
}),
);
});
it('checks freshness against the trusted stateful endpoint and profile', async () => {
mockAxios.mockResolvedValue({
data: { lastModified: '2026-08-15T00:00:00Z' },
});
await getSessionInfo(
{
kind: 'user',
id: 'user-123',
storage_session_id: 'session-123',
file_id: 'file-123',
},
mockReq,
{
baseUrl: 'https://stateful-code.example.com',
executionProfile: 'stateful',
},
);
expect(mockAxios).toHaveBeenCalledWith(
expect.objectContaining({
url: expect.stringMatching(/^https:\/\/stateful-code\.example\.com\/sessions\//),
headers: expect.objectContaining({
'X-CodeAPI-Expected-Profile': 'stateful',
}),
}),
);
});
});
describe('deferred-preview flow (office-bucket files)', () => {
/* Office-bucket files (DOCX/XLSX/etc.) split into:
* the initial emit (await): persist `text: null, status: 'pending'`,
* return `{ file, finalize }` so the caller can ship the
* attachment to the client immediately;
* the deferred render (background): finalize() invokes the extractor and
* transitions the record to 'ready' (with text/textFormat) or
* 'failed' (with previewError). The agent's final response
* never blocks on the deferred render.
*
* The `hasOfficeHtmlPath` mock is the gate. Other tests keep it
* at `false` (legacy single-phase path); we flip it on here. */
const { updateFile } = require('~/models');
beforeEach(() => {
mockHasOfficeHtmlPath.mockReturnValue(true);
updateFile.mockResolvedValue({ file_id: 'mock-uuid-1234', status: 'ready' });
});
afterEach(() => {
mockHasOfficeHtmlPath.mockReturnValue(false);
});
it('persists the initial emit with status:pending and text:null, deferring extraction', async () => {
mockAxios.mockResolvedValue({ data: Buffer.alloc(100) });
determineFileType.mockResolvedValue({
mime: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
});
const result = await processCodeOutput({ ...baseParams, name: 'data.xlsx' });
expect(result.file).toMatchObject({
file_id: 'mock-uuid-1234',
filename: 'data.xlsx',
status: 'pending',
text: null,
textFormat: null,
});
expect(typeof result.finalize).toBe('function');
// Extractor MUST NOT have been called yet — that's deferred preview work.
expect(mockExtractCodeArtifactText).not.toHaveBeenCalled();
// Persisted record with the pending status.
expect(mockCommitCodeFile).toHaveBeenCalledWith(
expect.objectContaining({ status: 'pending', text: null, textFormat: null }),
undefined,
);
});
it('finalize() runs the extractor, transitions to ready with text+textFormat on success', async () => {
mockAxios.mockResolvedValue({ data: Buffer.alloc(100) });
determineFileType.mockResolvedValue({
mime: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
});
mockExtractCodeArtifactText.mockResolvedValueOnce('<table><tr><td>1</td></tr></table>');
mockGetExtractedTextFormat.mockReturnValueOnce('html');
const { finalize } = await processCodeOutput({ ...baseParams, name: 'data.xlsx' });
await finalize();
expect(mockExtractCodeArtifactText).toHaveBeenCalledTimes(1);
/* Update is conditional on `previewRevision` so an older render
* can't overwrite a newer turn's record on cross-turn filename
* reuse. The uuid mock returns the same value for every v4()
* call, so file_id and previewRevision happen to coincide here
* — what matters is the second arg carries the revision filter. */
expect(updateFile).toHaveBeenCalledWith(
{
file_id: 'mock-uuid-1234',
text: '<table><tr><td>1</td></tr></table>',
textFormat: 'html',
status: 'ready',
previewError: null,
},
{ previewRevision: 'mock-uuid-1234' },
);
});
it('finalize() transitions to failed with previewError when extractor returns null (HTML-or-null contract)', async () => {
mockAxios.mockResolvedValue({ data: Buffer.alloc(100) });
determineFileType.mockResolvedValue({
mime: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
});
mockExtractCodeArtifactText.mockResolvedValueOnce(null);
// Office bucket + null text → must be 'failed', NEVER raw text fallback
// (PR #12934 SEC fix: prevents <script> in cell text from rendering as HTML).
mockHasOfficeHtmlPath.mockReturnValue(true);
const { finalize } = await processCodeOutput({ ...baseParams, name: 'data.xlsx' });
await finalize();
expect(updateFile).toHaveBeenCalledWith(
expect.objectContaining({
file_id: 'mock-uuid-1234',
text: null,
status: 'failed',
previewError: 'parser-error',
}),
{ previewRevision: 'mock-uuid-1234' },
);
});
it('finalize() transitions to failed with previewError:timeout when the outer timeout rejects', async () => {
/* The passthrough `withTimeout` mock at the file scope returns
* its inner promise unchanged, so the only way the catch branch
* fires here is if the extractor itself throws. The real
* production path: `extractCodeArtifactText` swallows its own
* errors and returns null, so any throw reaching `finalizePreview`
* came from the outer `withTimeout` rejection. Simulate it by
* having the extractor throw with the same shape. */
mockAxios.mockResolvedValue({ data: Buffer.alloc(100) });
determineFileType.mockResolvedValue({
mime: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
});
mockExtractCodeArtifactText.mockImplementationOnce(async () => {
throw new Error('Preview extraction exceeded 60000ms');
});
const { finalize } = await processCodeOutput({ ...baseParams, name: 'data.xlsx' });
await finalize();
expect(updateFile).toHaveBeenCalledWith(
expect.objectContaining({
file_id: 'mock-uuid-1234',
status: 'failed',
previewError: 'timeout',
}),
{ previewRevision: 'mock-uuid-1234' },
);
});
it('survives a failing updateFile in finalize() without throwing', async () => {
mockAxios.mockResolvedValue({ data: Buffer.alloc(100) });
determineFileType.mockResolvedValue({
mime: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
});
mockExtractCodeArtifactText.mockResolvedValueOnce('<table></table>');
mockGetExtractedTextFormat.mockReturnValueOnce('html');
updateFile.mockRejectedValueOnce(new Error('mongo down'));
const { finalize } = await processCodeOutput({ ...baseParams, name: 'data.xlsx' });
await expect(finalize()).resolves.toBeNull();
expect(logger.error).toHaveBeenCalledWith(
expect.stringContaining('failed to persist preview result'),
);
});
});
describe('legacy single-phase flow (non-office files)', () => {
/* Lock in that non-office files (txt/json/pdf/binary) keep the
* inline extract+create flow with NO finalize key — the caller
* gets a fully-resolved record, no background work to run. */
it('returns no finalize key for plain text', async () => {
mockAxios.mockResolvedValue({ data: Buffer.alloc(100) });
const result = await processCodeOutput({ ...baseParams, name: 'note.txt' });
expect(result.finalize).toBeUndefined();
expect(result.file).toMatchObject({ filename: 'note.txt' });
});
it('returns no finalize key for the size-limit fallback', async () => {
mockAxios.mockResolvedValue({ data: Buffer.alloc(100 * 1024 * 1024) });
const result = await processCodeOutput(baseParams);
expect(result.finalize).toBeUndefined();
expect(result.file.filepath).toContain('/api/files/code/download/');
});
it('returns no finalize key for the saveBuffer-unavailable fallback', async () => {
getStrategyFunctions.mockReturnValueOnce({});
mockAxios.mockResolvedValue({ data: Buffer.alloc(100) });
const result = await processCodeOutput(baseParams);
expect(result.finalize).toBeUndefined();
expect(result.file.filepath).toContain('/api/files/code/download/');
});
it('returns no finalize key for the axios-error fallback', async () => {
mockAxios.mockRejectedValue(new Error('network'));
const result = await processCodeOutput(baseParams);
expect(result.finalize).toBeUndefined();
expect(result.file.filepath).toContain('/api/files/code/download/');
});
});
});
describe('runPreviewFinalize', () => {
/* The runtime pairing for `processCodeOutput`'s `finalize` thunk.
* `finalizePreview` is designed to never throw (translates errors
* to `status: 'failed'` internally). The helper's catch is the
* safety net for unexpected programming errors that would
* otherwise leave the DB record stuck at `status: 'pending'`
* forever — we attempt a best-effort `updateFile` to mark it
* `'failed'` with `previewError: 'unexpected'` so the UI stops
* polling and the next-turn LLM context surfaces the failure.
* (Codex audit on PR #12957 Finding 4.) */
const { runPreviewFinalize } = require('./process');
const { updateFile } = require('~/models');
beforeEach(() => {
updateFile.mockReset();
updateFile.mockResolvedValue({});
});
it('is a no-op when finalize is undefined (non-office files)', () => {
expect(() =>
runPreviewFinalize({ finalize: undefined, fileId: 'fid-1', onResolved: jest.fn() }),
).not.toThrow();
expect(updateFile).not.toHaveBeenCalled();
});
it('calls onResolved with the resolved record on success', async () => {
const onResolved = jest.fn();
const finalize = jest
.fn()
.mockResolvedValue({ file_id: 'fid-1', status: 'ready', text: '<x/>' });
runPreviewFinalize({ finalize, fileId: 'fid-1', onResolved });
await new Promise((resolve) => setImmediate(resolve));
expect(onResolved).toHaveBeenCalledWith(
expect.objectContaining({ file_id: 'fid-1', status: 'ready' }),
);
expect(updateFile).not.toHaveBeenCalled();
});
it('skips onResolved when finalize resolves to null (DB write failed inside finalizePreview)', async () => {
const onResolved = jest.fn();
const finalize = jest.fn().mockResolvedValue(null);
runPreviewFinalize({ finalize, fileId: 'fid-1', onResolved });
await new Promise((resolve) => setImmediate(resolve));
expect(onResolved).not.toHaveBeenCalled();
});
it('marks the record as failed (previewError: "unexpected") when finalize throws', async () => {
const onResolved = jest.fn();
const finalize = jest.fn().mockRejectedValue(new Error('unexpected ref error'));
runPreviewFinalize({
finalize,
fileId: 'fid-boom',
previewRevision: 'rev-A',
onResolved,
});
await new Promise((resolve) => setImmediate(resolve));
await new Promise((resolve) => setImmediate(resolve));
expect(onResolved).not.toHaveBeenCalled();
/* Defensive update is conditional on the same `previewRevision`
* the deferred render started with — a newer turn that has
* since rotated the revision is left untouched. */
expect(updateFile).toHaveBeenCalledWith(
{
file_id: 'fid-boom',
status: 'failed',
previewError: 'unexpected',
},
{ previewRevision: 'rev-A' },
);
expect(logger.error).toHaveBeenCalledWith(
'Error rendering deferred preview:',
expect.any(Error),
);
});
it('logs but does not throw when the defensive updateFile itself fails', async () => {
const onResolved = jest.fn();
const finalize = jest.fn().mockRejectedValue(new Error('original error'));
updateFile.mockRejectedValueOnce(new Error('mongo down'));
runPreviewFinalize({ finalize, fileId: 'fid-doublefail', onResolved });
await new Promise((resolve) => setImmediate(resolve));
await new Promise((resolve) => setImmediate(resolve));
expect(onResolved).not.toHaveBeenCalled();
// Two logger.error calls: one for the original throw, one for the failed mark.
expect(logger.error.mock.calls.some((c) => /also failed to mark/.test(c[0]))).toBe(true);
});
it('does not attempt the defensive updateFile when fileId is missing', async () => {
const finalize = jest.fn().mockRejectedValue(new Error('boom'));
runPreviewFinalize({ finalize, fileId: undefined });
await new Promise((resolve) => setImmediate(resolve));
expect(updateFile).not.toHaveBeenCalled();
});
it('skips onResolved gracefully when caller omits it (e.g., tools.js direct endpoint)', async () => {
const finalize = jest.fn().mockResolvedValue({ file_id: 'fid-1', status: 'ready' });
// No onResolved — non-streaming caller.
expect(() => runPreviewFinalize({ finalize, fileId: 'fid-1' })).not.toThrow();
await new Promise((resolve) => setImmediate(resolve));
expect(updateFile).not.toHaveBeenCalled();
});
it('does NOT downgrade the file to failed when finalize succeeds but onResolved throws', async () => {
/* Regression for the codex P2 finding: the original chain put the
* `.catch` after `.then(onResolved)`, so a throw inside
* `onResolved` (transport-side: SSE write race after stream
* close, an emitter listener throwing) propagated into the
* finalize catch and persisted `status: 'failed'` /
* `previewError: 'unexpected'` — even though extraction
* succeeded and the file was already on disk and marked ready.
* That surfaced "preview unavailable" in the UI for a perfectly
* valid file, and degraded next-turn LLM context. The fix wraps
* `onResolved` in its own try/catch so emit errors stay isolated
* from finalize errors. */
const onResolved = jest.fn(() => {
throw new Error('SSE write after stream closed');
});
const finalize = jest.fn().mockResolvedValue({
file_id: 'fid-emit-throw',
status: 'ready',
text: '<table>x</table>',
});
runPreviewFinalize({
finalize,
fileId: 'fid-emit-throw',
previewRevision: 'rev-A',
onResolved,
});
await new Promise((resolve) => setImmediate(resolve));
await new Promise((resolve) => setImmediate(resolve));
expect(onResolved).toHaveBeenCalledTimes(1);
/* The defensive "mark failed" path MUST NOT fire — the file is
* resolved and on disk; only the SSE emit failed. */
expect(updateFile).not.toHaveBeenCalled();
/* Emit error is logged so the failure is observable in the
* server log without affecting UX. */
expect(
logger.error.mock.calls.some((c) => /onResolved threw for fid-emit-throw/.test(c[0])),
).toBe(true);
});
});
describe('readWorkspaceFile', () => {
it('forwards the configured rate-limit budget to the workspace transport', async () => {
const req = {
...mockReq,
config: { ...mockReq.config, endpoints: { agents: { codeApiMaxRetryWaitMs: 0 } } },
};
mockExecuteWorkspaceTool.mockResolvedValueOnce({ operation: 'read_file' });
await readWorkspaceFile({
file_path: 'src/app.ts',
workspace_id: 'primary',
start_line: 1,
max_lines: 10,
codeApiBaseUrl: 'https://attached-code.example.com/v1',
executionProfile: 'stateful',
req,
});
expect(mockExecuteWorkspaceTool).toHaveBeenCalledWith(
expect.objectContaining({ codeApiMaxRetryWaitMs: 0 }),
);
});
it('forwards authenticated reads to the selected attached worker', async () => {
const controller = new AbortController();
const result = {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'src/app.ts',
content: 'const ready = true;',
startLine: 1,
endLine: 1,
truncated: false,
};
getCodeApiAuthHeaders.mockResolvedValueOnce({ Authorization: 'Bearer workspace-token' });
mockExecuteWorkspaceTool.mockResolvedValueOnce(result);
await expect(
readWorkspaceFile({
file_path: 'src/app.ts',
workspace_id: 'primary',
workspace_instance_id: 'a'.repeat(64),
start_line: 1,
max_lines: 200,
codeApiBaseUrl: 'https://attached-code.example.com/v1',
executionProfile: 'stateful',
bridgeWorkerId: 'worker-user-1',
req: mockReq,
signal: controller.signal,
maxQueueWaitMs: 0,
maxRequestTimeoutMs: 125_000,
maxRunTimeoutMs: 180_000,
admission: {
queueWaitMs: 60_000,
initialDelayMs: 1_000,
maxDelayMs: 30_000,
multiplier: 2,
jitterRatio: 0.2,
},
deadlineAtMs: 160_000,
}),
).resolves.toBe(result);
expect(getCodeApiAuthHeaders).not.toHaveBeenCalled();
const { authHeaders } = mockExecuteWorkspaceTool.mock.calls[0][0];
await expect(authHeaders()).resolves.toEqual({
Authorization: 'Bearer workspace-token',
'X-CodeAPI-Expected-Profile': 'stateful',
'X-LibreChat-Code-Worker-ID': 'worker-user-1',
});
getCodeApiAuthHeaders.mockResolvedValueOnce({ Authorization: 'Bearer refreshed-token' });
await expect(authHeaders()).resolves.toMatchObject({
Authorization: 'Bearer refreshed-token',
'X-LibreChat-Code-Worker-ID': 'worker-user-1',
});
expect(getCodeApiAuthHeaders).toHaveBeenNthCalledWith(2, mockReq, 'worker-user-1');
expect(mockExecuteWorkspaceTool).toHaveBeenCalledWith({
baseURL: 'https://attached-code.example.com/v1',
authHeaders: expect.any(Function),
maxQueueWaitMs: 0,
codeApiMaxRetryWaitMs: undefined,
maxRequestTimeoutMs: 125_000,
maxRunTimeoutMs: 180_000,
admission: {
queueWaitMs: 60_000,
initialDelayMs: 1_000,
maxDelayMs: 30_000,
multiplier: 2,
jitterRatio: 0.2,
},
deadlineAtMs: 160_000,
request: {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
workspaceInstanceId: 'a'.repeat(64),
path: 'src/app.ts',
startLine: 1,
maxLines: 200,
},
signal: controller.signal,
});
});
});
describe('searchWorkspace', () => {
it('forwards authenticated literal search to the selected attached worker', async () => {
const controller = new AbortController();
const result = {
protocolVersion: 1,
operation: 'search_text',
workspaceId: 'primary',
matches: [],
truncated: false,
};
getCodeApiAuthHeaders.mockResolvedValueOnce({ Authorization: 'Bearer workspace-token' });
mockExecuteWorkspaceTool.mockResolvedValueOnce(result);
await expect(
searchWorkspace({
query: 'needle',
workspace_id: 'primary',
path: 'src',
max_results: 20,
codeApiBaseUrl: 'https://attached-code.example.com/v1',
executionProfile: 'stateful',
bridgeWorkerId: 'worker-user-1',
req: mockReq,
signal: controller.signal,
maxQueueWaitMs: 0,
}),
).resolves.toBe(result);
expect(getCodeApiAuthHeaders).not.toHaveBeenCalled();
const { authHeaders } = mockExecuteWorkspaceTool.mock.calls[0][0];
await expect(authHeaders()).resolves.toEqual({
Authorization: 'Bearer workspace-token',
'X-CodeAPI-Expected-Profile': 'stateful',
'X-LibreChat-Code-Worker-ID': 'worker-user-1',
});
getCodeApiAuthHeaders.mockResolvedValueOnce({ Authorization: 'Bearer refreshed-token' });
await expect(authHeaders()).resolves.toMatchObject({
Authorization: 'Bearer refreshed-token',
'X-LibreChat-Code-Worker-ID': 'worker-user-1',
});
expect(getCodeApiAuthHeaders).toHaveBeenNthCalledWith(2, mockReq, 'worker-user-1');
expect(mockExecuteWorkspaceTool).toHaveBeenCalledWith({
baseURL: 'https://attached-code.example.com/v1',
authHeaders: expect.any(Function),
maxQueueWaitMs: 0,
codeApiMaxRetryWaitMs: undefined,
maxRequestTimeoutMs: undefined,
deadlineAtMs: undefined,
request: {
protocolVersion: 1,
operation: 'search_text',
workspaceId: 'primary',
query: 'needle',
path: 'src',
maxResults: 20,
},
signal: controller.signal,
});
});
});
describe('listWorkspaceFiles', () => {
it('forwards authenticated listing to the selected attached worker', async () => {
const controller = new AbortController();
const result = {
protocolVersion: 1,
operation: 'list_files',
workspaceId: 'primary',
paths: ['src/app.ts'],
truncated: false,
};
getCodeApiAuthHeaders.mockResolvedValueOnce({ Authorization: 'Bearer workspace-token' });
mockExecuteWorkspaceTool.mockResolvedValueOnce(result);
await expect(
listWorkspaceFiles({
workspace_id: 'primary',
linked_worktrees: true,
path: 'src',
after_path: 'src/app.ts',
max_results: 20,
codeApiBaseUrl: 'https://attached-code.example.com/v1',
executionProfile: 'stateful',
bridgeWorkerId: 'worker-user-1',
req: mockReq,
signal: controller.signal,
maxQueueWaitMs: 0,
}),
).resolves.toBe(result);
expect(getCodeApiAuthHeaders).not.toHaveBeenCalled();
const { authHeaders } = mockExecuteWorkspaceTool.mock.calls[0][0];
await expect(authHeaders()).resolves.toEqual({
Authorization: 'Bearer workspace-token',
'X-CodeAPI-Expected-Profile': 'stateful',
'X-LibreChat-Code-Worker-ID': 'worker-user-1',
});
getCodeApiAuthHeaders.mockResolvedValueOnce({ Authorization: 'Bearer refreshed-token' });
await expect(authHeaders()).resolves.toMatchObject({
Authorization: 'Bearer refreshed-token',
'X-LibreChat-Code-Worker-ID': 'worker-user-1',
});
expect(getCodeApiAuthHeaders).toHaveBeenNthCalledWith(2, mockReq, 'worker-user-1');
expect(mockExecuteWorkspaceTool).toHaveBeenCalledWith({
baseURL: 'https://attached-code.example.com/v1',
linkedWorktrees: true,
authHeaders: expect.any(Function),
maxQueueWaitMs: 0,
codeApiMaxRetryWaitMs: undefined,
maxRequestTimeoutMs: undefined,
deadlineAtMs: undefined,
request: {
protocolVersion: 1,
operation: 'list_files',
workspaceId: 'primary',
path: 'src',
afterPath: 'src/app.ts',
maxResults: 20,
},
signal: controller.signal,
});
});
});
describe('workspace mutations', () => {
it('forwards create-only writes to the selected attached worker', async () => {
const controller = new AbortController();
const result = {
protocolVersion: 1,
operation: 'write_file',
workspaceId: 'primary',
path: 'src/new.ts',
created: true,
bytesWritten: 5,
};
getCodeApiAuthHeaders.mockResolvedValueOnce({ Authorization: 'Bearer workspace-token' });
mockExecuteWorkspaceTool.mockResolvedValueOnce(result);
await expect(
writeWorkspaceFile({
file_path: 'src/new.ts',
content: 'ready',
overwrite: false,
workspace_id: 'primary',
workspace_instance_id: 'b'.repeat(64),
codeApiBaseUrl: 'https://attached-code.example.com/v1',
executionProfile: 'stateful',
bridgeWorkerId: 'worker-user-1',
req: mockReq,
signal: controller.signal,
maxQueueWaitMs: 0,
}),
).resolves.toBe(result);
expect(getCodeApiAuthHeaders).not.toHaveBeenCalled();
const { authHeaders } = mockExecuteWorkspaceTool.mock.calls[0][0];
await expect(authHeaders()).resolves.toEqual({
Authorization: 'Bearer workspace-token',
'X-CodeAPI-Expected-Profile': 'stateful',
'X-LibreChat-Code-Worker-ID': 'worker-user-1',
});
getCodeApiAuthHeaders.mockResolvedValueOnce({ Authorization: 'Bearer refreshed-token' });
await expect(authHeaders()).resolves.toMatchObject({
Authorization: 'Bearer refreshed-token',
'X-LibreChat-Code-Worker-ID': 'worker-user-1',
});
expect(getCodeApiAuthHeaders).toHaveBeenNthCalledWith(2, mockReq, 'worker-user-1');
expect(mockExecuteWorkspaceTool).toHaveBeenCalledWith({
baseURL: 'https://attached-code.example.com/v1',
authHeaders: expect.any(Function),
maxQueueWaitMs: 0,
codeApiMaxRetryWaitMs: undefined,
maxRequestTimeoutMs: undefined,
deadlineAtMs: undefined,
request: {
protocolVersion: 1,
operation: 'write_file',
workspaceId: 'primary',
workspaceInstanceId: 'b'.repeat(64),
path: 'src/new.ts',
content: 'ready',
overwrite: false,
},
signal: controller.signal,
});
});
it('forwards an edit batch as one attached-worker request', async () => {
const result = {
protocolVersion: 1,
operation: 'edit_file',
workspaceId: 'primary',
path: 'src/app.ts',
replacements: 2,
bytesWritten: 20,
};
getCodeApiAuthHeaders.mockResolvedValueOnce({ Authorization: 'Bearer workspace-token' });
mockExecuteWorkspaceTool.mockResolvedValueOnce(result);
await expect(
editWorkspaceFile({
file_path: 'src/app.ts',
edits: [
{ oldText: 'draft', newText: 'ready' },
{ oldText: 'false', newText: 'true' },
],
workspace_id: 'primary',
codeApiBaseUrl: 'https://attached-code.example.com/v1',
executionProfile: 'stateful',
bridgeWorkerId: 'worker-user-1',
req: mockReq,
expected_base_sha256: 'a'.repeat(64),
maxRequestTimeoutMs: 125_000,
deadlineAtMs: 160_000,
}),
).resolves.toBe(result);
expect(mockExecuteWorkspaceTool).toHaveBeenCalledWith(
expect.objectContaining({
maxRequestTimeoutMs: 125_000,
deadlineAtMs: 160_000,
request: {
protocolVersion: 1,
operation: 'edit_file',
workspaceId: 'primary',
path: 'src/app.ts',
edits: [
{ oldText: 'draft', newText: 'ready' },
{ oldText: 'false', newText: 'true' },
],
expectedBaseSha256: 'a'.repeat(64),
},
}),
);
});
it('forwards negotiated matching and replaceAll on edits and previews', async () => {
const edits = [{ oldText: 'false', newText: 'true', replaceAll: true }];
mockExecuteWorkspaceTool.mockResolvedValue({});
const shared = {
file_path: 'src/app.ts',
edits,
matching: 'tolerant',
workspace_id: 'primary',
codeApiBaseUrl: 'https://attached-code.example.com/v1',
executionProfile: 'stateful',
bridgeWorkerId: 'worker-user-1',
req: mockReq,
};
await editWorkspaceFile(shared);
await previewWorkspaceEdit(shared);
for (const operation of ['edit_file', 'preview_edit']) {
expect(mockExecuteWorkspaceTool).toHaveBeenCalledWith(
expect.objectContaining({
request: expect.objectContaining({ operation, edits, matching: 'tolerant' }),
}),
);
}
});
it('forwards a non-mutating attached-workspace edit preview', async () => {
const result = {
protocolVersion: 1,
operation: 'preview_edit',
workspaceId: 'primary',
path: 'src/app.ts',
content: 'prefix SECRET',
hasUtf8Bom: false,
baseSha256: 'b'.repeat(64),
replacements: 1,
bytesWritten: 13,
};
mockExecuteWorkspaceTool.mockResolvedValueOnce(result);
await expect(
previewWorkspaceEdit({
file_path: 'src/app.ts',
edits: [{ oldText: ' SEC', newText: ' SECRET' }],
workspace_id: 'primary',
codeApiBaseUrl: 'https://attached-code.example.com/v1',
executionProfile: 'stateful',
req: mockReq,
maxRequestTimeoutMs: 125_000,
deadlineAtMs: 160_000,
}),
).resolves.toBe(result);
expect(mockExecuteWorkspaceTool).toHaveBeenCalledWith(
expect.objectContaining({
maxRequestTimeoutMs: 125_000,
deadlineAtMs: 160_000,
request: {
protocolVersion: 1,
operation: 'preview_edit',
workspaceId: 'primary',
path: 'src/app.ts',
edits: [{ oldText: ' SEC', newText: ' SECRET' }],
},
}),
);
});
});
describe('readSandboxFile', () => {
/**
* `readSandboxFile` shells `cat <file_path>` through the sandbox
* `/exec` endpoint. The `file_path` argument is model-controlled, so
* the single-quote escaping is a security boundary — a regression
* here would let a malicious filename break out of the `cat`
* argument and inject arbitrary shell. Lock the contract in tests.
*/
/** Pull the bash code that the helper would send to /exec, given
* the file_path that the model supplied. */
function execCodeFor(file_path) {
mockAxios.mockResolvedValueOnce({ data: { stdout: '', stderr: '' } });
return readSandboxFile({ file_path }).then(() => {
const postData = mockAxios.mock.calls[0][0].data;
return postData.code;
});
}
describe('shell quoting (security boundary)', () => {
it('wraps a plain filename in single quotes', async () => {
const code = await execCodeFor('/mnt/data/sentinel.txt');
expect(code).toBe(`cat '/mnt/data/sentinel.txt'`);
});
it("escapes a literal single-quote in the filename via the standard '\\'' sequence", async () => {
// Adversarial filename: `quote'breakout.txt`. Naive
// single-quoting would terminate the quoted string and
// inject the trailing `breakout.txt'` as shell tokens.
const code = await execCodeFor(`/mnt/data/quote'breakout.txt`);
// Expected escape: end the string, escape a literal quote,
// start a new string. POSIX-portable.
expect(code).toBe(`cat '/mnt/data/quote'\\''breakout.txt'`);
});
it('does not interpret command substitution syntax inside the quoted argument', async () => {
// `$(rm -rf /)` would expand if the path were unquoted or
// double-quoted. Inside POSIX single-quotes it stays literal.
const code = await execCodeFor('/mnt/data/$(rm -rf /).txt');
expect(code).toBe(`cat '/mnt/data/$(rm -rf /).txt'`);
});
it('does not expand backtick command substitution inside the quoted argument', async () => {
const code = await execCodeFor('/mnt/data/`whoami`.txt');
expect(code).toBe(`cat '/mnt/data/\`whoami\`.txt'`);
});
it('keeps newlines literal inside the quoted argument', async () => {
const code = await execCodeFor('/mnt/data/line1\nline2.txt');
expect(code).toBe(`cat '/mnt/data/line1\nline2.txt'`);
});
it('keeps spaces and other shell metacharacters literal', async () => {
const code = await execCodeFor('/mnt/data/file ; ls -la /etc/passwd');
expect(code).toBe(`cat '/mnt/data/file ; ls -la /etc/passwd'`);
});
it('handles multiple consecutive single-quotes', async () => {
const code = await execCodeFor(`a''b`);
// Each `'` becomes the 4-char escape sequence.
expect(code).toBe(`cat 'a'\\'''\\''b'`);
});
});
describe('payload shape', () => {
it('POSTs to /exec on the configured codeapi base URL with bash language', async () => {
mockAxios.mockResolvedValueOnce({ data: { stdout: 'ok', stderr: '' } });
await readSandboxFile({ file_path: '/mnt/data/x.txt' });
const call = mockAxios.mock.calls[0][0];
expect(call.method).toBe('post');
expect(call.url).toBe('https://code-api.example.com/exec');
expect(call.data.lang).toBe('bash');
});
it('routes to the selected profile endpoint and asserts the expected profile', async () => {
mockAxios.mockResolvedValueOnce({ data: { stdout: 'ok', stderr: '' } });
await readSandboxFile({
file_path: '/mnt/data/x.txt',
codeApiBaseUrl: 'https://stateful-code.example.com',
executionProfile: 'stateful',
bridgeWorkerId: 'personal-worker-1',
runtime_session_hint: 'v1:user',
});
const call = mockAxios.mock.calls[0][0];
expect(call.url).toBe('https://stateful-code.example.com/exec');
expect(call.headers['X-CodeAPI-Expected-Profile']).toBe('stateful');
expect(call.headers['X-LibreChat-Code-Worker-ID']).toBe('personal-worker-1');
expect(call.data.runtime_session_hint).toBe('v1:user');
});
it('omits session_id and files when not provided', async () => {
mockAxios.mockResolvedValueOnce({ data: { stdout: '', stderr: '' } });
await readSandboxFile({ file_path: '/mnt/data/x.txt' });
const data = mockAxios.mock.calls[0][0].data;
expect(data).not.toHaveProperty('session_id');
expect(data).not.toHaveProperty('files');
});
it('forwards session_id when provided so the read lands in the seeded sandbox', async () => {
mockAxios.mockResolvedValueOnce({ data: { stdout: '', stderr: '' } });
await readSandboxFile({
file_path: '/mnt/data/x.txt',
session_id: 'sess-XYZ',
});
expect(mockAxios.mock.calls[0][0].data.session_id).toBe('sess-XYZ');
});
it('forwards files (non-empty array) so prior-turn artifacts are mounted', async () => {
mockAxios.mockResolvedValueOnce({ data: { stdout: '', stderr: '' } });
const files = [{ id: 'f1', name: 'sentinel.txt', session_id: 'sess-XYZ' }];
await readSandboxFile({
file_path: '/mnt/data/sentinel.txt',
session_id: 'sess-XYZ',
files,
});
expect(mockAxios.mock.calls[0][0].data.files).toEqual(files);
});
it('omits files when an empty array is provided (cleaner payload)', async () => {
mockAxios.mockResolvedValueOnce({ data: { stdout: '', stderr: '' } });
await readSandboxFile({
file_path: '/mnt/data/x.txt',
session_id: 'sess-XYZ',
files: [],
});
expect(mockAxios.mock.calls[0][0].data).not.toHaveProperty('files');
});
it('uses dedicated keepAlive:false agents (matches processCodeOutput pool isolation)', async () => {
mockAxios.mockResolvedValueOnce({ data: { stdout: '', stderr: '' } });
await readSandboxFile({ file_path: '/mnt/data/x.txt' });
const call = mockAxios.mock.calls[0][0];
expect(call.httpAgent).toBe(codeServerHttpAgent);
expect(call.httpsAgent).toBe(codeServerHttpsAgent);
});
it('forwards Code API auth headers when reading from the sandbox', async () => {
getCodeApiAuthHeaders.mockResolvedValueOnce({ Authorization: 'Bearer sandbox-token' });
mockAxios.mockResolvedValueOnce({ data: { stdout: 'x', stderr: '' } });
await readSandboxFile({ file_path: '/mnt/data/x.txt', req: mockReq });
expect(getCodeApiAuthHeaders).toHaveBeenCalledWith(mockReq, undefined);
expect(mockAxios).toHaveBeenCalledWith(
expect.objectContaining({
method: 'post',
headers: expect.objectContaining({
Authorization: 'Bearer sandbox-token',
'User-Agent': 'LibreChat/1.0',
}),
}),
);
});
});
describe('complete text for ranged reads', () => {
beforeEach(() => {
const actual = jest.requireActual('@librechat/api');
require('@librechat/api').readWindowedSandboxImage.mockImplementation(
actual.readWindowedSandboxImage,
);
mockParseSandboxImageChunk.mockImplementation(actual.parseSandboxImageChunk);
});
afterEach(() => {
require('@librechat/api').readWindowedSandboxImage.mockImplementation(({ readChunk }) =>
readChunk({ code: 'read-one-window' }),
);
mockParseSandboxImageChunk.mockImplementation((response) => response);
mockAxios.mockReset();
});
const fullText = Array.from(
{ length: 900 },
(_, i) => `${String(i + 1).padStart(4, '0')}: ${'x'.repeat(93)}`,
).join('\n');
function cappedExecResponse(code, content = fullText, cap = 65_536) {
let stdout;
if (code.startsWith('cat ')) stdout = content;
else {
const payload = /payload = ("[^"\n]+")/.exec(code);
if (!payload) throw new Error('Expected the production bounded reader script');
const { offset, chunk, limit } = JSON.parse(
Buffer.from(JSON.parse(payload[1]), 'base64').toString('utf8'),
);
const bytes = Buffer.from(content);
const window = bytes.subarray(offset, offset + chunk);
stdout =
JSON.stringify(
bytes.length > limit
? { too_large: true, bytes: bytes.length }
: { total: bytes.length, n: window.length, b64: window.toString('base64') },
) + '\n';
}
const overflow = stdout.length > cap;
return {
data: {
stdout: stdout.slice(0, cap),
stderr: overflow ? 'Output limit exceeded' : '',
status: overflow ? 'OL' : 'success',
},
};
}
it('retrieves the complete 900-line text before the handler selects line 850', async () => {
const actual = jest.requireActual('@librechat/api');
const { readWindowedSandboxImage } = require('@librechat/api');
readWindowedSandboxImage.mockImplementationOnce(actual.readWindowedSandboxImage);
mockParseSandboxImageChunk.mockImplementation(actual.parseSandboxImageChunk);
mockAxios.mockImplementation(async ({ data }) => cappedExecResponse(data.code));
const result = await readSandboxFile({
file_path: '/mnt/data/catalogue.txt',
maxBytes: 262_144,
});
expect(result.content).toBe(fullText);
expect(result.complete).toBe(true);
expect(mockAxios.mock.calls.length).toBeGreaterThan(1);
const handler = actual.createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [], configurable: { codeEnvAvailable: true } }),
readSandboxFile: async () => result,
});
const [page] = await new Promise((resolve, reject) =>
handler.handle('on_tool_execute', {
toolCalls: [
{
id: 'capped-range',
name: 'read_file',
args: { path: '/mnt/data/catalogue.txt', start_line: 850, max_lines: 1 },
},
],
resolve,
reject,
}),
);
expect(page.status).toBe('success');
expect(page.content).toContain('850 | 0850: ');
expect(page.content).toContain('start_line 851');
});
it('still filters protected text beyond the stdout prefix before serving a clean range', async () => {
const actual = jest.requireActual('@librechat/api');
const content = fullText + '\nPROTECTED-TAIL';
mockAxios.mockImplementation(async ({ data }) => cappedExecResponse(data.code, content));
const handler = actual.createToolExecuteHandler({
loadTools: async () => ({
loadedTools: [],
configurable: {
codeEnvAvailable: true,
req: {
config: {
filters: {
files: {
pii: {
fields: ['content'],
starterPatterns: [],
customPatterns: [
{ id: 'protected', label: 'protected', regex: 'PROTECTED-TAIL' },
],
},
},
},
},
},
},
}),
readSandboxFile,
});
const [page] = await new Promise((resolve, reject) =>
handler.handle('on_tool_execute', {
toolCalls: [
{
id: 'filtered-full-read',
name: 'read_file',
args: { path: '/mnt/data/catalogue.txt', max_lines: 1 },
},
],
resolve,
reject,
}),
);
expect(page.status).toBe('error');
expect(page.errorMessage).toContain('content_filter_block');
expect(page.content).toBe('');
});
it('narrows a smaller runner cap without accepting its incomplete stdout', async () => {
mockAxios.mockImplementation(async ({ data }) =>
cappedExecResponse(data.code, fullText, 16_384),
);
const result = await readSandboxFile({
file_path: '/mnt/data/catalogue.txt',
codeApiBaseUrl: 'https://small-text.example.com',
maxBytes: 262_144,
});
expect(result).toEqual({ content: fullText, complete: true });
expect(mockAxios.mock.calls.length).toBeGreaterThan(2);
});
it('refuses oversized files without transferring a prefix', async () => {
mockAxios.mockImplementation(async ({ data }) =>
cappedExecResponse(data.code, 'x'.repeat(262_145)),
);
const result = await readSandboxFile({
file_path: '/mnt/data/catalogue.txt',
maxBytes: 262_144,
});
expect(result).toEqual({ tooLarge: true, reason: 'size', bytes: 262_145 });
expect(mockAxios).toHaveBeenCalledTimes(1);
});
it('forwards the execution identity and cancellation signal on every chunk', async () => {
mockAxios.mockImplementation(async ({ data }) => cappedExecResponse(data.code));
const controller = new AbortController();
const files = [{ id: 'file-a', name: 'catalogue.txt', session_id: 'session-a' }];
const params = {
file_path: '/mnt/data/catalogue.txt',
maxBytes: 262_144,
session_id: 'session-a',
runtime_session_hint: 'runtime-a',
codeApiBaseUrl: 'https://stateful-code.example.com',
executionProfile: 'stateful',
bridgeWorkerId: 'worker-a',
files,
req: mockReq,
signal: controller.signal,
};
const result = await readSandboxFile(params);
expect(result.complete).toBe(true);
for (const [call] of mockAxios.mock.calls) {
expect(call).toMatchObject({
url: 'https://stateful-code.example.com/exec',
signal: controller.signal,
data: { session_id: 'session-a', runtime_session_hint: 'runtime-a', files },
headers: {
'X-CodeAPI-Expected-Profile': 'stateful',
'X-LibreChat-Code-Worker-ID': 'worker-a',
},
});
}
expect(getCodeApiAuthHeaders).toHaveBeenCalledWith(mockReq, 'worker-a');
});
});
describe('response handling', () => {
it('returns { content: stdout } on success', async () => {
mockAxios.mockResolvedValueOnce({
data: { stdout: 'sentinel-XYZ-1234\n', stderr: '' },
});
const result = await readSandboxFile({ file_path: '/mnt/data/sentinel.txt' });
expect(result).toEqual({ content: 'sentinel-XYZ-1234\n' });
});
it('returns null when getCodeBaseURL is not configured', async () => {
const { getCodeBaseURL } = require('@librechat/agents');
getCodeBaseURL.mockReturnValueOnce('');
const result = await readSandboxFile({ file_path: '/mnt/data/x.txt' });
expect(result).toBeNull();
expect(mockAxios).not.toHaveBeenCalled();
});
it('returns null when stdout is missing entirely (no content to surface)', async () => {
// stdout absent + no stderr = nothing to report; caller turns this
// into a model-visible "Failed to read" message.
mockAxios.mockResolvedValueOnce({ data: { stderr: '' } });
const result = await readSandboxFile({ file_path: '/mnt/data/x.txt' });
expect(result).toBeNull();
});
it('throws when the command writes to stderr with no stdout (exposes the error to the caller)', async () => {
mockAxios.mockResolvedValueOnce({
data: { stdout: '', stderr: 'cat: /mnt/data/missing.txt: No such file or directory\n' },
});
await expect(readSandboxFile({ file_path: '/mnt/data/missing.txt' })).rejects.toThrow(
'cat: /mnt/data/missing.txt: No such file or directory',
);
});
it('returns stdout even when stderr is also present (stdout wins on partial-success)', async () => {
// Some `cat` builds emit warnings on stderr while still producing
// stdout (e.g. unusual line endings). Surface the content.
mockAxios.mockResolvedValueOnce({
data: { stdout: 'partial', stderr: 'warning: ...' },
});
const result = await readSandboxFile({ file_path: '/mnt/data/x.txt' });
expect(result).toEqual({ content: 'partial' });
});
it('rethrows axios transport errors after logging via logAxiosError', async () => {
const { logAxiosError } = require('@librechat/api');
const transportError = Object.assign(new Error('connect ECONNREFUSED'), {
code: 'ECONNREFUSED',
});
mockAxios.mockRejectedValueOnce(transportError);
await expect(readSandboxFile({ file_path: '/mnt/data/x.txt' })).rejects.toBe(
transportError,
);
expect(logAxiosError).toHaveBeenCalledWith(
expect.objectContaining({
message: expect.stringContaining('/mnt/data/x.txt'),
error: transportError,
}),
);
});
/* `create_file` reads its target before writing so it can tell a create
* from an overwrite, so an absent path is the ordinary case. Reported at
* error level it made every file creation look like a lost file — and
* `logAxiosError` rendered the sandbox's own stderr as "An error occurred
* while setting up the request", which reads as a transport fault. */
it('logs an absent path at debug, not through the error-level axios logger', async () => {
const { logAxiosError } = require('@librechat/api');
mockAxios.mockResolvedValueOnce({
data: { stdout: '', stderr: 'cat: /mnt/data/SKILL.md: No such file or directory\n' },
});
await expect(readSandboxFile({ file_path: '/mnt/data/SKILL.md' })).rejects.toThrow(
'No such file or directory',
);
expect(logAxiosError).not.toHaveBeenCalled();
expect(logger.error).not.toHaveBeenCalled();
expect(logger.debug).toHaveBeenCalledWith(expect.stringContaining('/mnt/data/SKILL.md'));
});
it('still reports a non-missing sandbox read failure at error level', async () => {
const { logAxiosError } = require('@librechat/api');
mockAxios.mockResolvedValueOnce({
data: { stdout: '', stderr: 'cat: /mnt/data/x.txt: Permission denied\n' },
});
await expect(readSandboxFile({ file_path: '/mnt/data/x.txt' })).rejects.toThrow(
'Permission denied',
);
expect(logger.debug).not.toHaveBeenCalled();
expect(logger.error).toHaveBeenCalledWith(expect.stringContaining('Permission denied'));
/* The sandbox answered; nothing about the request failed, so the
* axios-shaped logger would misattribute this to the transport. */
expect(logAxiosError).not.toHaveBeenCalled();
});
});
describe('timeout', () => {
it('uses the same 15s timeout as processCodeOutput (consistent code-server SLA)', async () => {
mockAxios.mockResolvedValueOnce({ data: { stdout: '', stderr: '' } });
await readSandboxFile({ file_path: '/mnt/data/x.txt' });
expect(mockAxios.mock.calls[0][0].timeout).toBe(15000);
});
});
});
describe('writeSandboxFile', () => {
function extractWritePayload() {
const code = mockAxios.mock.calls[0][0].data.code;
const match = /payload = "([^"]+)"/.exec(code);
expect(match).not.toBeNull();
const payload = JSON.parse(Buffer.from(match[1], 'base64').toString('utf8'));
return {
file_path: payload.file_path,
content: Buffer.from(payload.content_b64, 'base64').toString('utf8'),
code,
};
}
it('POSTs a bash python writer to /exec and forwards session context', async () => {
mockAxios.mockResolvedValueOnce({
data: {
stdout: 'WROTE 11 bytes to /mnt/data/new.txt\n',
stderr: '',
session_id: 'sess-new',
files: [{ id: 'file-new', name: 'new.txt', storage_session_id: 'sess-new' }],
},
});
const files = [{ id: 'f1', name: 'input.csv', session_id: 'sess-prev' }];
const result = await writeSandboxFile({
file_path: '/mnt/data/new.txt',
content: 'hello world',
session_id: 'sess-prev',
files,
req: mockReq,
});
const call = mockAxios.mock.calls[0][0];
expect(call.method).toBe('post');
expect(call.url).toBe('https://code-api.example.com/exec');
expect(call.data.lang).toBe('bash');
expect(call.data.session_id).toBe('sess-prev');
expect(call.data.files).toEqual(files);
expect(call.timeout).toBe(15000);
expect(call.httpAgent).toBe(codeServerHttpAgent);
expect(call.httpsAgent).toBe(codeServerHttpsAgent);
expect(result).toMatchObject({
stdout: 'WROTE 11 bytes to /mnt/data/new.txt\n',
session_id: 'sess-new',
files: [{ id: 'file-new', name: 'new.txt' }],
});
});
it('forwards only a valid bounded artifact delivery failure', async () => {
mockAxios.mockResolvedValueOnce({
data: {
stdout: 'WROTE 1 bytes to /mnt/data/new.txt\n',
session_id: 'sess-new',
files: [],
artifact_delivery: {
code: 'artifact_delivery_failed',
status: 'failed',
attempted: 1,
delivered: 0,
failed: 1,
detail: 'private object storage failure',
},
},
});
const result = await writeSandboxFile({
file_path: '/mnt/data/new.txt',
content: 'x',
});
expect(result.artifact_delivery).toEqual({
code: 'artifact_delivery_failed',
status: 'failed',
attempted: 1,
delivered: 0,
failed: 1,
});
expect(JSON.stringify(result)).not.toContain('private object storage failure');
});
it('encodes path and content in a base64 JSON payload instead of shell-interpolating them', async () => {
mockAxios.mockResolvedValueOnce({ data: { stdout: 'ok', stderr: '', session_id: 'sess' } });
const trickyPath = `/mnt/data/quote'$(whoami).txt`;
const trickyContent = "hello ' $(rm -rf /)\nsecond line";
await writeSandboxFile({
file_path: trickyPath,
content: trickyContent,
});
const { file_path, content, code } = extractWritePayload();
expect(file_path).toBe(trickyPath);
expect(content).toBe(trickyContent);
expect(code).not.toContain(trickyPath);
expect(code).not.toContain(trickyContent);
});
it('returns null when getCodeBaseURL is not configured', async () => {
const { getCodeBaseURL } = require('@librechat/agents');
getCodeBaseURL.mockReturnValueOnce('');
const result = await writeSandboxFile({
file_path: '/mnt/data/x.txt',
content: 'x',
});
expect(result).toBeNull();
expect(mockAxios).not.toHaveBeenCalled();
});
it('throws when the writer reports stderr without stdout', async () => {
mockAxios.mockResolvedValueOnce({
data: { stdout: '', stderr: 'Permission denied\n' },
});
await expect(writeSandboxFile({ file_path: '/root/nope.txt', content: 'x' })).rejects.toThrow(
'Permission denied',
);
});
});
describe('primeFiles reupload pushes FRESH sandbox ids (Pass-N review P2)', () => {
/**
* Regression: when a primed code file is missing/expired in the
* sandbox (`getSessionInfo` returns null), `primeFiles` re-uploads
* the file via `handleFileUpload` and persists the new
* `fileIdentifier`. Before the fix, the in-memory `files[]` array
* (now consumed by `buildInitialToolSessions` to seed
* `Graph.sessions`) still received the STALE `(session_id, id)`
* parsed from the original `fileIdentifier` at the top of the
* loop. The DB record was correct but the seed referenced a
* sandbox object that no longer existed — the first tool call
* 404'd trying to mount it until the next turn re-read metadata.
*
* Fix: parse the FRESH `fileIdentifier` returned by upload and
* push those ids into both the dedupe Map and the seed list.
*/
const { getStrategyFunctions } = require('~/server/services/Files/strategies');
const { updateFile, getFiles } = require('~/models');
const { filterFilesByAgentAccess } = require('~/server/services/Files/permissions');
/**
* Mock the full strategy pair. `primeFiles` calls
* `getStrategyFunctions(file.source)` for the download stream and
* `getStrategyFunctions(FileSources.execute_code)` for the code-env
* upload — both go through the same factory in production.
*/
function setupReuploadMocks(newRef) {
const handleFileUpload = jest.fn().mockResolvedValue(newRef);
const getDownloadStream = jest.fn().mockResolvedValue('mock-stream');
getStrategyFunctions.mockImplementation((source) => {
if (source === 'execute_code') return { handleFileUpload };
return { getDownloadStream };
});
updateFile.mockResolvedValue({});
filterFilesByAgentAccess.mockImplementation(({ files }) => Promise.resolve(files));
// getSessionInfo is mocked at module level via mockAxios; return null
// to force the reupload path. Each `getSessionInfo` call hits axios.
mockAxios.mockResolvedValue({ data: null });
return { handleFileUpload, getDownloadStream };
}
function claimedFile() {
return {
file_id: 'claimed-file',
user: 'user-123',
tenantId: 'tenant-1',
filename: 'report.csv',
filepath: '/uploads/report.csv',
source: 'local',
metadata: {
codeEnvRef: {
kind: 'user',
id: 'user-123',
storage_session_id: 'OLD_SESSION',
file_id: 'OLD_ID',
},
},
};
}
function primeClaimedFile(file) {
return primeFiles({
req: { user: { id: 'user-123', role: 'USER' } },
tool_resources: { execute_code: { file_ids: [file.file_id] } },
agentId: 'agent-id',
});
}
it('does not open a stream or upload when the durable claim is denied', async () => {
const dbFile = claimedFile();
const { handleFileUpload, getDownloadStream } = setupReuploadMocks({
storage_session_id: 'NEW_SESSION',
file_id: 'NEW_ID',
});
getFiles.mockResolvedValue([dbFile]);
mockAcquireFileProvision.mockResolvedValueOnce(false);
await expect(primeClaimedFile(dbFile)).rejects.toThrow();
expect(mockAcquireFileProvision).toHaveBeenCalledTimes(1);
expect(getDownloadStream).not.toHaveBeenCalled();
expect(handleFileUpload).not.toHaveBeenCalled();
expect(updateFile).not.toHaveBeenCalled();
expect(mockReleaseFileProvision).not.toHaveBeenCalled();
});
it('holds the durable claim through stream upload and pointer persistence', async () => {
const dbFile = claimedFile();
const { handleFileUpload } = setupReuploadMocks({});
getFiles.mockResolvedValue([dbFile]);
let finishUpload;
let finishWrite;
const uploadGate = new Promise((resolve) => {
finishUpload = resolve;
});
const writeGate = new Promise((resolve) => {
finishWrite = resolve;
});
handleFileUpload.mockImplementation(async () => {
expect(mockAcquireFileProvision).toHaveBeenCalledTimes(1);
await uploadGate;
return { storage_session_id: 'NEW_SESSION', file_id: 'NEW_ID' };
});
updateFile.mockImplementation(async () => {
await writeGate;
return {};
});
const pending = primeClaimedFile(dbFile);
await new Promise((resolve) => setImmediate(resolve));
expect(handleFileUpload).toHaveBeenCalledTimes(1);
expect(updateFile).not.toHaveBeenCalled();
expect(mockReleaseFileProvision).not.toHaveBeenCalled();
finishUpload();
await new Promise((resolve) => setImmediate(resolve));
expect(updateFile).toHaveBeenCalledTimes(1);
expect(mockReleaseFileProvision).not.toHaveBeenCalled();
finishWrite();
const result = await pending;
expect(result.files).toEqual([expect.objectContaining({ id: 'NEW_ID' })]);
expect(mockReleaseFileProvision).toHaveBeenCalledTimes(1);
expect(mockAcquireFileProvision).toHaveBeenCalledWith(
expect.objectContaining({
file_id: dbFile.file_id,
userId: dbFile.user,
tenantId: dbFile.tenantId,
token: expect.any(String),
}),
);
expect(mockReleaseFileProvision.mock.calls[0]).toEqual(
mockAcquireFileProvision.mock.calls[0],
);
expect(mockCommitFileProvision).toHaveBeenCalledWith(
expect.objectContaining({
claim: mockAcquireFileProvision.mock.calls[0][0],
code: expect.objectContaining({
routeKey: 'default',
ref: expect.objectContaining({ file_id: 'NEW_ID' }),
}),
}),
);
});
it('does not seed a remote pointer when its conditional commit is rejected', async () => {
const dbFile = claimedFile();
setupReuploadMocks({ storage_session_id: 'NEW_SESSION', file_id: 'NEW_ID' });
getFiles.mockResolvedValue([dbFile]);
mockCommitFileProvision.mockResolvedValue(false);
await expect(primeClaimedFile(dbFile)).rejects.toThrow();
expect(mockCommitFileProvision).toHaveBeenCalledTimes(2);
expect(mockReleaseFileProvision).not.toHaveBeenCalled();
});
it('reuses the original claim and uploaded ref in the next primer invocation', async () => {
const dbFile = claimedFile();
const { handleFileUpload } = setupReuploadMocks({
storage_session_id: 'NEW_SESSION',
file_id: 'NEW_ID',
});
getFiles.mockResolvedValue([dbFile]);
mockCommitFileProvision.mockResolvedValueOnce(false).mockResolvedValueOnce(false);
await expect(primeClaimedFile(dbFile)).rejects.toThrow();
const originalClaim = mockAcquireFileProvision.mock.calls[0][0];
const result = await primeClaimedFile(dbFile);
expect(result.files).toEqual([expect.objectContaining({ id: 'NEW_ID' })]);
expect(handleFileUpload).toHaveBeenCalledTimes(1);
expect(mockAcquireFileProvision).toHaveBeenCalledTimes(1);
expect(mockCommitFileProvision).toHaveBeenLastCalledWith(
expect.objectContaining({ claim: originalClaim }),
);
expect(mockReleaseFileProvision).toHaveBeenCalledWith(originalClaim);
});
it.each(['primer', 'callback'])(
'recovers a %s upload through the other producer while provisioning an independent file',
async (first) => {
const { createProvisionFilesCallback } = jest.requireActual('@librechat/api');
const { getFileStorage } = require('~/server/services/Files/operations');
const dbFile = claimedFile();
const independent = {
...claimedFile(),
file_id: 'independent-file',
filename: 'independent.csv',
};
const { handleFileUpload } = setupReuploadMocks({
storage_session_id: 'NEW_SESSION',
file_id: 'NEW_ID',
filename: 'stored.csv',
});
handleFileUpload.mockImplementation(async ({ filename }) => ({
storage_session_id: 'NEW_SESSION',
file_id: filename === dbFile.filename ? 'NEW_ID' : 'INDEPENDENT_ID',
filename: filename === dbFile.filename ? 'stored.csv' : filename,
}));
const req = { user: { id: 'user-123', role: 'USER' } };
const provisionToCodeEnv = jest.fn(async ({ file, sandboxFilename }) => {
const ref = {
kind: 'user',
id: req.user.id,
storage_session_id: 'NEW_SESSION',
file_id: file === dbFile ? 'NEW_ID' : 'INDEPENDENT_ID',
sandboxFilename: file === dbFile ? 'stored.csv' : sandboxFilename,
};
return {
referenceSet: { codeEnvRefs: { default: ref } },
refUpdate: { file_id: file.file_id, routeKey: 'default', ref },
sandboxFilename: ref.sandboxFilename,
};
});
const callback = (files) => {
const provisionState = {
codeEnvFiles: files,
vectorDBFiles: [],
aliveFileIds: new Set(),
agentScopedFileIds: new Set(),
};
return createProvisionFilesCallback({
req,
fileStorage: getFileStorage(),
agentToolContexts: new Map([['agent-id', { provisionState }]]),
provisionToCodeEnv,
provisionToVectorDB: jest.fn(),
updateFile: jest.fn(),
updateCodeEnvRef: jest.fn(),
addEmbeddedEntity: jest.fn(),
})(['execute_code'], 'agent-id');
};
const primer = (files) => {
getFiles.mockResolvedValue(files);
return primeFiles({
req,
tool_resources: { execute_code: { file_ids: files.map((file) => file.file_id) } },
agentId: 'agent-id',
});
};
mockCommitFileProvision.mockResolvedValueOnce(false).mockResolvedValueOnce(false);
await expect(first === 'primer' ? primer([dbFile]) : callback([dbFile])).rejects.toThrow();
const claim = mockAcquireFileProvision.mock.calls[0][0];
const result =
first === 'primer'
? await callback([dbFile, independent])
: (await primer([dbFile, independent])).files;
expect(result).toEqual(
expect.arrayContaining([
expect.objectContaining({ id: 'NEW_ID', name: 'stored.csv' }),
expect.objectContaining({ id: 'INDEPENDENT_ID', name: 'independent.csv' }),
]),
);
expect(result).toHaveLength(2);
expect(handleFileUpload).toHaveBeenCalledTimes(1);
expect(provisionToCodeEnv).toHaveBeenCalledTimes(1);
expect(mockAcquireFileProvision).toHaveBeenCalledTimes(2);
expect(mockReleaseFileProvision).toHaveBeenCalledWith(claim);
expect(dbFile.metadata.codeEnvRefs.default).toMatchObject({
file_id: 'NEW_ID',
sandboxFilename: 'stored.csv',
});
},
);
it.each(['upload', 'persist'])(
'handles the durable claim after a %s failure',
async (failure) => {
const dbFile = claimedFile();
const { handleFileUpload } = setupReuploadMocks({
storage_session_id: 'NEW_SESSION',
file_id: 'NEW_ID',
});
getFiles.mockResolvedValue([dbFile]);
if (failure === 'upload')
handleFileUpload.mockRejectedValueOnce(new Error('upload unavailable'));
else updateFile.mockRejectedValue(new Error('database unavailable'));
await expect(primeClaimedFile(dbFile)).rejects.toThrow();
if (failure === 'upload') {
expect(mockReleaseFileProvision).toHaveBeenCalledTimes(1);
expect(mockReleaseFileProvision.mock.calls[0]).toEqual(
mockAcquireFileProvision.mock.calls[0],
);
} else {
expect(mockReleaseFileProvision).not.toHaveBeenCalled();
}
},
);
it('recovers a throttled stale-file reupload with a fresh stream', async () => {
const controller = new AbortController();
const dbFile = {
file_id: 'rate-limited-file',
filename: 'report.csv',
filepath: '/uploads/report.csv',
source: 'local',
context: 'execute_code',
metadata: {
codeEnvRef: {
kind: 'user',
id: 'user-123',
storage_session_id: 'OLD_SESSION',
file_id: 'OLD_ID',
},
},
};
const rateLimit = Object.assign(new Error('Request failed with status code 429'), {
isAxiosError: true,
response: { status: 429, headers: { 'retry-after': '0' } },
});
const handleFileUpload = jest
.fn()
.mockRejectedValueOnce(rateLimit)
.mockResolvedValueOnce({ storage_session_id: 'NEW_SESSION', file_id: 'NEW_ID' });
const getDownloadStream = jest
.fn()
.mockResolvedValueOnce('first-stream')
.mockResolvedValueOnce('second-stream');
getStrategyFunctions.mockImplementation((source) =>
source === 'execute_code' ? { handleFileUpload } : { getDownloadStream },
);
getFiles.mockResolvedValue([dbFile]);
filterFilesByAgentAccess.mockImplementation(({ files }) => Promise.resolve(files));
mockAxios.mockResolvedValue({ data: null });
updateFile.mockResolvedValue({});
const result = await primeFiles({
req: { user: { id: 'user-123', role: 'USER' } },
tool_resources: { execute_code: { file_ids: [dbFile.file_id], files: [] } },
agentId: 'agent-id',
signal: controller.signal,
});
const { withCodeApiUploadRecovery } = require('@librechat/api');
expect(withCodeApiUploadRecovery).toHaveBeenCalledWith(
expect.objectContaining({ signal: controller.signal }),
);
expect(handleFileUpload).toHaveBeenCalledTimes(2);
expect(handleFileUpload).toHaveBeenCalledWith(
expect.objectContaining({ signal: controller.signal }),
);
expect(getDownloadStream).toHaveBeenCalledTimes(2);
expect(getDownloadStream).toHaveBeenCalledWith(expect.anything(), '/uploads/report.csv', {
signal: controller.signal,
});
expect(handleFileUpload.mock.calls.map(([args]) => args.stream)).toEqual([
'first-stream',
'second-stream',
]);
expect(result.files).toEqual([
expect.objectContaining({ id: 'NEW_ID', storage_session_id: 'NEW_SESSION' }),
]);
});
it('propagates cancellation from a stale-file reupload', async () => {
const controller = new AbortController();
const dbFile = {
file_id: 'canceled-file',
filename: 'report.csv',
filepath: '/uploads/report.csv',
source: 'local',
context: 'execute_code',
metadata: {
codeEnvRef: {
kind: 'user',
id: 'user-123',
storage_session_id: 'OLD_SESSION',
file_id: 'OLD_ID',
},
},
};
const handleFileUpload = jest.fn(async () => {
controller.abort();
controller.signal.throwIfAborted();
});
getStrategyFunctions.mockImplementation((source) =>
source === 'execute_code'
? { handleFileUpload }
: { getDownloadStream: jest.fn().mockResolvedValue('stream') },
);
getFiles.mockResolvedValue([dbFile]);
filterFilesByAgentAccess.mockImplementation(({ files }) => Promise.resolve(files));
mockAxios.mockResolvedValue({ data: null });
await expect(
primeFiles({
req: { user: { id: 'user-123', role: 'USER' } },
tool_resources: { execute_code: { file_ids: [dbFile.file_id], files: [] } },
agentId: 'agent-id',
signal: controller.signal,
maxQueueWaitMs: 0,
}),
).rejects.toMatchObject({ name: 'AbortError' });
expect(handleFileUpload).toHaveBeenCalledTimes(1);
});
it('uses the permission resource type established by the calling route', async () => {
const files = [
{
file_id: 'owner-file',
filename: 'owner.txt',
user: 'agent-owner',
metadata: {},
},
];
getFiles.mockResolvedValue(files);
filterFilesByAgentAccess.mockImplementation(({ files: authorizedFiles }) =>
Promise.resolve(authorizedFiles),
);
await primeFiles({
req: { user: { id: 'remote-viewer', role: 'USER' } },
agentId: 'agent-123',
agentResourceType: ResourceType.REMOTE_AGENT,
tool_resources: { execute_code: { file_ids: ['owner-file'] } },
});
expect(filterFilesByAgentAccess).toHaveBeenCalledWith({
files,
userId: 'remote-viewer',
role: 'USER',
agentId: 'agent-123',
resourceType: ResourceType.REMOTE_AGENT,
});
expect(JSON.stringify(logger.debug.mock.calls)).not.toContain(files[0].filename);
});
it('does not read a runtime file record that has no authorized database record', async () => {
const getDownloadStream = jest.fn().mockResolvedValue('forged-stream');
const handleFileUpload = jest.fn();
getStrategyFunctions.mockImplementation((source) => {
if (source === 'execute_code') return { handleFileUpload };
return { getDownloadStream };
});
getFiles.mockResolvedValue([]);
mockAxios.mockResolvedValue({ data: null });
const result = await primeFiles({
req: { user: { id: 'user-123', role: 'USER' } },
tool_resources: {
execute_code: {
files: [
{
file_id: 'forged-file',
filename: 'secrets.txt',
filepath: '/etc/passwd',
source: 'local',
metadata: {
codeEnvRef: {
kind: 'user',
id: 'user-123',
storage_session_id: 'missing-session',
file_id: 'missing-file',
},
},
},
],
},
},
agentId: 'agent-id',
});
expect(result.files).toEqual([]);
expect(getDownloadStream).not.toHaveBeenCalled();
expect(handleFileUpload).not.toHaveBeenCalled();
});
it('rehydrates a runtime file by ID before using its storage metadata', async () => {
const trustedFile = {
file_id: 'runtime-file',
filename: 'trusted.txt',
filepath: '/uploads/trusted.txt',
source: 'local',
context: 'execute_code',
metadata: {
codeEnvRef: {
kind: 'user',
id: 'user-123',
storage_session_id: 'trusted-session',
file_id: 'trusted-file',
},
},
};
const getDownloadStream = jest.fn().mockResolvedValue('trusted-stream');
const handleFileUpload = jest
.fn()
.mockResolvedValue({ storage_session_id: 'new-session', file_id: 'new-file' });
getStrategyFunctions.mockImplementation((source) => {
if (source === 'execute_code') return { handleFileUpload };
return { getDownloadStream };
});
getFiles.mockResolvedValue([trustedFile]);
mockAxios.mockResolvedValue({ data: null });
await primeFiles({
req: { user: { id: 'user-123', role: 'USER' } },
tool_resources: {
execute_code: {
files: [
{
...trustedFile,
filepath: '/etc/passwd',
source: 'forged-source',
metadata: {
codeEnvRef: {
kind: 'user',
id: 'attacker',
storage_session_id: 'forged-session',
file_id: 'forged-file',
},
},
},
],
},
},
agentId: 'agent-id',
});
expect(getDownloadStream).toHaveBeenCalledTimes(1);
expect(getDownloadStream).toHaveBeenCalledWith(
{ user: { id: 'user-123', role: 'USER' } },
'/uploads/trusted.txt',
{ signal: undefined },
);
expect(handleFileUpload).toHaveBeenCalledTimes(1);
});
it('seed receives FRESH (storage_session_id, file_id) from the reupload response', async () => {
const dbFile = {
file_id: 'librechat-file-id',
filename: 'sentinel.txt',
filepath: '/uploads/sentinel.txt',
source: 'local',
context: 'execute_code',
metadata: {
/* Stale sandbox ref — this is what `getSessionInfo` will 404 on. */
codeEnvRef: {
kind: 'user',
id: 'user-123',
storage_session_id: 'OLD_SESSION',
file_id: 'OLD_ID',
},
},
};
getFiles.mockResolvedValue([dbFile]);
setupReuploadMocks({ storage_session_id: 'NEW_SESSION', file_id: 'NEW_ID' });
const result = await primeFiles({
req: { user: { id: 'user-123', role: 'USER' } },
tool_resources: {
execute_code: { file_ids: ['librechat-file-id'], files: [] },
},
agentId: 'agent-id',
});
// The seed list (consumed by buildInitialToolSessions) MUST carry
// the post-reupload ids — not the stale pre-reupload ones.
expect(result.files).toEqual([
{
id: 'NEW_ID',
/* `resource_id` carries the codeEnvRef.id (= original
* userId for kind: 'user'), threaded onto the in-memory
* file ref for codeapi's sessionKey re-derivation. */
resource_id: 'user-123',
storage_session_id: 'NEW_SESSION',
name: 'sentinel.txt',
kind: 'user',
},
]);
});
it('reuploads a recovered converted image under its advertised sandbox name', async () => {
getFiles.mockResolvedValue([
{
file_id: 'converted-image',
filename: 'photo.png',
filepath: '/uploads/photo.webp',
type: 'image/webp',
source: 'local',
context: 'execute_code',
metadata: {
codeEnvRef: {
kind: 'user',
id: 'user-123',
storage_session_id: 'OLD_SESSION',
file_id: 'OLD_ID',
},
},
},
]);
const { handleFileUpload } = setupReuploadMocks({
storage_session_id: 'NEW_SESSION',
file_id: 'NEW_ID',
});
const result = await primeFiles({
req: { user: { id: 'user-123', role: 'USER' } },
tool_resources: { execute_code: { file_ids: ['converted-image'], files: [] } },
agentId: 'agent-id',
});
expect(handleFileUpload).toHaveBeenCalledWith(
expect.objectContaining({ filename: 'photo.webp' }),
);
expect(result.files?.[0]?.name).toBe('photo.webp');
});
/* Phase C / option α (codeapi #1455): reupload preserves the
* resource identity from the existing ref so codeapi re-buckets
* under the same sessionKey shape. Without this, a skill-cache-miss
* reupload lands in the user bucket and is no longer cross-user
* shareable. */
it('reupload forwards kind/id (and version when skill) from the existing ref', async () => {
const dbFile = {
file_id: 'librechat-file-id',
filename: 'sentinel.txt',
filepath: '/uploads/sentinel.txt',
source: 'local',
context: 'execute_code',
metadata: {
codeEnvRef: {
kind: 'skill',
id: 'skill-99',
storage_session_id: 'OLD_SESSION',
file_id: 'OLD_ID',
version: 4,
},
},
};
getFiles.mockResolvedValue([dbFile]);
const { handleFileUpload } = setupReuploadMocks({
storage_session_id: 'NEW_SESSION',
file_id: 'NEW_ID',
});
await primeFiles({
req: { user: { id: 'user-123', role: 'USER' } },
tool_resources: {
execute_code: { file_ids: ['librechat-file-id'], files: [] },
},
agentId: 'agent-id',
});
expect(handleFileUpload).toHaveBeenCalledTimes(1);
const uploadArgs = handleFileUpload.mock.calls[0][0];
expect(uploadArgs.kind).toBe('skill');
expect(uploadArgs.id).toBe('skill-99');
expect(uploadArgs.version).toBe(4);
});
it('reuploads instead of reusing a ref from the other execution profile', async () => {
const dbFile = {
file_id: 'librechat-file-id',
filename: 'sentinel.txt',
filepath: '/uploads/sentinel.txt',
source: 'local',
context: 'execute_code',
metadata: {
codeEnvRef: {
kind: 'user',
id: 'user-123',
storage_session_id: 'DEFAULT_SESSION',
file_id: 'DEFAULT_ID',
executionProfile: 'default',
},
},
};
getFiles.mockResolvedValue([dbFile]);
const { handleFileUpload } = setupReuploadMocks({
storage_session_id: 'STATEFUL_SESSION',
file_id: 'STATEFUL_ID',
});
await primeFiles({
req: { user: { id: 'user-123', role: 'USER' } },
tool_resources: {
execute_code: { file_ids: ['librechat-file-id'], files: [] },
},
agentId: 'agent-id',
codeApiBaseUrl: 'https://stateful-code.example.com',
executionProfile: 'stateful',
bridgeWorkerId: 'personal-worker-1',
});
expect(mockAxios).not.toHaveBeenCalled();
expect(handleFileUpload).toHaveBeenCalledWith(
expect.objectContaining({
codeApiBaseUrl: 'https://stateful-code.example.com',
executionProfile: 'stateful',
bridgeWorkerId: 'personal-worker-1',
}),
);
expect(updateFile).toHaveBeenCalledWith(
expect.objectContaining({
'metadata.codeEnvRef': expect.objectContaining({ executionProfile: 'default' }),
'metadata.codeEnvRefs.stateful': expect.objectContaining({
executionProfile: 'stateful',
}),
}),
);
const persistedMetadata = {
...dbFile.metadata,
codeEnvRef: updateFile.mock.calls[0][0]['metadata.codeEnvRef'],
codeEnvRefs: {
default: dbFile.metadata.codeEnvRef,
stateful: updateFile.mock.calls[0][0]['metadata.codeEnvRefs.stateful'],
},
};
getFiles.mockResolvedValue([{ ...dbFile, metadata: persistedMetadata }]);
mockAxios.mockResolvedValue({ data: { lastModified: new Date().toISOString() } });
await primeFiles({
req: { user: { id: 'user-123', role: 'USER' } },
tool_resources: {
execute_code: { file_ids: ['librechat-file-id'], files: [] },
},
agentId: 'agent-id',
executionProfile: 'default',
});
expect(handleFileUpload).toHaveBeenCalledTimes(1);
expect(mockAxios).toHaveBeenCalledWith(
expect.objectContaining({
url: expect.stringContaining('/sessions/DEFAULT_SESSION/objects/DEFAULT_ID'),
}),
);
});
it('persists fresh codeEnvRef (kind/id preserved) on the DB record after reupload', async () => {
const dbFile = {
file_id: 'librechat-file-id',
filename: 'sentinel.txt',
filepath: '/uploads/sentinel.txt',
source: 'local',
context: 'execute_code',
metadata: {
codeEnvRef: {
kind: 'user',
id: 'user-123',
storage_session_id: 'OLD_SESSION',
file_id: 'OLD_ID',
},
},
};
getFiles.mockResolvedValue([dbFile]);
setupReuploadMocks({ storage_session_id: 'NEW_SESSION', file_id: 'NEW_ID' });
await primeFiles({
req: { user: { id: 'user-123', role: 'USER' } },
tool_resources: {
execute_code: { file_ids: ['librechat-file-id'], files: [] },
},
agentId: 'agent-id',
});
expect(updateFile).toHaveBeenCalledWith(
expect.objectContaining({
file_id: 'librechat-file-id',
'metadata.codeEnvRef': {
kind: 'user',
id: 'user-123',
storage_session_id: 'NEW_SESSION',
file_id: 'NEW_ID',
executionProfile: 'default',
sandboxFilename: 'sentinel.txt',
},
'metadata.codeEnvRefs.default': {
kind: 'user',
id: 'user-123',
storage_session_id: 'NEW_SESSION',
file_id: 'NEW_ID',
executionProfile: 'default',
sandboxFilename: 'sentinel.txt',
},
}),
);
});
it('reads codeEnvRef directly when present (skipping reupload)', async () => {
const dbFile = {
file_id: 'librechat-file-id',
filename: 'sentinel.txt',
filepath: '/uploads/sentinel.txt',
source: 'local',
context: 'execute_code',
metadata: {
codeEnvRef: {
kind: 'user',
id: 'user-123',
storage_session_id: 'STRUCT_SESSION',
file_id: 'STRUCT_ID',
},
},
};
getFiles.mockResolvedValue([dbFile]);
filterFilesByAgentAccess.mockImplementation(({ files }) => Promise.resolve(files));
// getSessionInfo returns a fresh timestamp so reupload is skipped.
mockAxios.mockResolvedValue({ data: { lastModified: new Date().toISOString() } });
const result = await primeFiles({
req: { user: { id: 'user-123', role: 'USER' } },
tool_resources: {
execute_code: { file_ids: ['librechat-file-id'], files: [] },
},
agentId: 'agent-id',
});
expect(updateFile).not.toHaveBeenCalled();
expect(result.files).toEqual([
{
id: 'STRUCT_ID',
/* `resource_id` from the persisted codeEnvRef.id — for
* `kind: 'user'` this is informational (codeapi derives
* sessionKey from auth context) but threaded for shape
* uniformity with shared kinds. */
resource_id: 'user-123',
storage_session_id: 'STRUCT_SESSION',
name: 'sentinel.txt',
kind: 'user',
},
]);
});
it.each([
['Axios/CloudFront 404', { response: { status: 404 } }, 'missing_backing_object'],
[
'AWS SDK NoSuchKey',
{ name: 'NoSuchKey', $metadata: { httpStatusCode: 404 } },
'missing_backing_object',
],
['Azure BlobNotFound', { code: 'BlobNotFound', statusCode: 404 }, 'missing_backing_object'],
['storage access denied', { code: 'AccessDenied', status: 403 }, 'resource_access_denied'],
['Code API throttling', { code: 'CODE_API_RATE_LIMITED', status: 429 }, 'rate_limited'],
])(
'fails with a typed recovery error for %s',
async (_errorShape, downloadError, expectedCategory) => {
const dbFile = {
file_id: 'librechat-file-id',
filename: 'cross-region-report.png',
filepath: 'https://storage.us-east.example.test/missing-object',
source: 'local',
context: 'execute_code',
metadata: {
codeEnvRef: {
kind: 'user',
id: 'user-123',
storage_session_id: 'US_EAST_SESSION',
file_id: 'MISSING_OBJECT',
},
},
};
const getDownloadStream = jest.fn().mockRejectedValue(downloadError);
getFiles.mockResolvedValue([dbFile]);
getStrategyFunctions.mockImplementation((source) =>
source === 'execute_code' ? { handleFileUpload: jest.fn() } : { getDownloadStream },
);
mockAxios.mockResolvedValue({ data: null });
await expect(
primeFiles({
req: {
id: 'request-123',
body: { messageId: 'run-123' },
user: { id: 'user-123', role: 'USER' },
},
tool_resources: {
execute_code: { file_ids: ['librechat-file-id'], files: [] },
},
agentId: 'agent-id',
}),
).rejects.toMatchObject({
code: ErrorTypes.RESOURCE_RECOVERY_REQUIRED,
status: 409,
statusCode: 409,
details: { required: 1, primed: 0, failed: 1 },
required: 1,
primed: 0,
failed: 1,
});
expect(logger.warn).toHaveBeenCalledWith(
expect.stringContaining(
`resource-recovery-required requestId=request-123 runId=run-123 required=1 primed=0 failed=1 category=${expectedCategory}`,
),
);
const failureLogs = logger.error.mock.calls.map(([message]) => message).join('\n');
expect(failureLogs).toContain(`category=${expectedCategory}`);
expect(failureLogs).not.toContain(dbFile.filename);
expect(failureLogs).not.toContain(dbFile.filepath);
},
);
});
describe('primeFiles toolContext for model-visible code files', () => {
/* User-visible code-env input files keep their `/mnt/data` context and
* preview lifecycle hints. Prior-turn generated artifacts are still
* primed into the sandbox, but no longer repeated in model-visible
* instructions every turn. */
const { getStrategyFunctions } = require('~/server/services/Files/strategies');
const { getFiles } = require('~/models');
const { filterFilesByAgentAccess } = require('~/server/services/Files/permissions');
function makeFile(overrides) {
return {
file_id: `fid-${overrides.status ?? 'ready'}`,
filename: `data-${overrides.status ?? 'ready'}.xlsx`,
filepath: `/uploads/${overrides.status ?? 'ready'}.xlsx`,
source: 'local',
context: FileContext.message_attachment,
metadata: {
codeEnvRef: {
kind: 'user',
id: 'user-123',
storage_session_id: 'CURRENT_SESSION',
file_id: 'CURRENT_ID',
},
},
...overrides,
};
}
function setupSessionInfoOk() {
/* `getSessionInfo` returns `lastModified`; `checkIfActive` parses
* that as a Date and decides whether the sandbox copy is still
* fresh (under 23 hours). Use `now` so we always go straight to
* `pushFile` and exercise the toolContext annotation logic. */
mockAxios.mockResolvedValue({ data: { lastModified: new Date().toISOString() } });
getStrategyFunctions.mockReturnValue({});
filterFilesByAgentAccess.mockImplementation(({ files }) => Promise.resolve(files));
}
it('does not include generated code files in model-visible toolContext', async () => {
setupSessionInfoOk();
getFiles.mockResolvedValue([
makeFile({
context: FileContext.execute_code,
filename: 'generated.html',
}),
]);
const result = await primeFiles({
req: { user: { id: 'user-123', role: 'USER' } },
tool_resources: { execute_code: { file_ids: ['fid-ready'], files: [] } },
agentId: 'agent-id',
});
expect(result.toolContext).toBe('');
expect(result.files).toEqual([
{
id: 'CURRENT_ID',
resource_id: 'user-123',
storage_session_id: 'CURRENT_SESSION',
name: 'generated.html',
kind: 'user',
},
]);
});
it('mounts a converted image under the name the sandbox actually holds', async () => {
/* Image uploads are converted to the configured output type while the record keeps
* the original filename. Provisioning uploaded the converted name, so rebuilding
* the mount path from the record advertises a file the sandbox does not have. */
setupSessionInfoOk();
getFiles.mockResolvedValue([
makeFile({
file_id: 'fid-ready',
filename: 'photo.png',
type: 'image/webp',
}),
]);
const result = await primeFiles({
req: { user: { id: 'user-123', role: 'USER' } },
tool_resources: { execute_code: { file_ids: ['fid-ready'], files: [] } },
agentId: 'agent-id',
});
expect(result.files?.[0]?.name).toBe('photo.webp');
});
it('tells the model an attached workspace cannot open primed files', async () => {
setupSessionInfoOk();
getFiles.mockResolvedValue([makeFile({ status: 'ready' })]);
const result = await primeFiles({
req: { user: { id: 'user-123', role: 'USER' } },
tool_resources: { execute_code: { file_ids: ['fid-ready'], files: [] } },
agentId: 'agent-id',
codeFileLocation: 'programmatic',
});
expect(result.toolContext).toContain('not in the attached workspace');
expect(result.toolContext).toContain('$LIBRECHAT_CODE_DATA_DIR/data-ready.xlsx');
expect(result.toolContext).not.toContain('/mnt/data');
expect(result.toolContext).not.toContain('tool environment:');
expect(result.files).toHaveLength(1);
expect(result.contextFiles).toEqual([
{
file: expect.objectContaining({ file_id: 'fid-ready' }),
destination: 'data-ready.xlsx',
agentScoped: true,
source: {
storage_session_id: result.files[0].storage_session_id,
file_id: result.files[0].id,
},
},
]);
});
it('returns no structured entries on a sandbox route', async () => {
setupSessionInfoOk();
getFiles.mockResolvedValue([makeFile({ status: 'ready' })]);
const result = await primeFiles({
req: { user: { id: 'user-123', role: 'USER' } },
tool_resources: { execute_code: { file_ids: ['fid-ready'], files: [] } },
agentId: 'agent-id',
});
expect(result.contextFiles).toBeUndefined();
});
it('annotates a pending file with "(preview not yet generated)"', async () => {
setupSessionInfoOk();
getFiles.mockResolvedValue([makeFile({ status: 'pending' })]);
const result = await primeFiles({
req: { user: { id: 'user-123', role: 'USER' } },
tool_resources: { execute_code: { file_ids: ['fid-pending'], files: [] } },
agentId: 'agent-id',
});
expect(result.toolContext).toContain('data-pending.xlsx');
expect(result.toolContext).toContain('(preview not yet generated)');
});
it('annotates a failed file with "(preview unavailable: <reason>)"', async () => {
setupSessionInfoOk();
getFiles.mockResolvedValue([makeFile({ status: 'failed', previewError: 'timeout' })]);
const result = await primeFiles({
req: { user: { id: 'user-123', role: 'USER' } },
tool_resources: { execute_code: { file_ids: ['fid-failed'], files: [] } },
agentId: 'agent-id',
});
expect(result.toolContext).toContain('data-failed.xlsx');
expect(result.toolContext).toContain('(preview unavailable: timeout)');
});
it('falls back to bare "(preview unavailable)" when previewError is absent', async () => {
setupSessionInfoOk();
getFiles.mockResolvedValue([makeFile({ status: 'failed' })]);
const result = await primeFiles({
req: { user: { id: 'user-123', role: 'USER' } },
tool_resources: { execute_code: { file_ids: ['fid-failed'], files: [] } },
agentId: 'agent-id',
});
expect(result.toolContext).toContain('(preview unavailable)');
expect(result.toolContext).not.toContain('(preview unavailable:');
});
it('does not annotate a ready file (no extra suffix)', async () => {
setupSessionInfoOk();
getFiles.mockResolvedValue([makeFile({ status: 'ready' })]);
const result = await primeFiles({
req: { user: { id: 'user-123', role: 'USER' } },
tool_resources: { execute_code: { file_ids: ['fid-ready'], files: [] } },
agentId: 'agent-id',
});
expect(result.toolContext).toContain('data-ready.xlsx');
expect(result.toolContext).not.toContain('preview');
});
it('does not annotate a legacy file (no status field, back-compat)', async () => {
/* Records pre-dating the deferred-preview flow have no `status`. They
* MUST render exactly as before — no suffix at all. */
setupSessionInfoOk();
getFiles.mockResolvedValue([makeFile({})]); // no status override
const result = await primeFiles({
req: { user: { id: 'user-123', role: 'USER' } },
tool_resources: { execute_code: { file_ids: ['fid-ready'], files: [] } },
agentId: 'agent-id',
});
expect(result.toolContext).toContain('data-ready.xlsx');
expect(result.toolContext).not.toContain('preview');
});
});
/**
* Windowing, window sizing, rate-limit waiting and byte assembly moved to
* `packages/api` (`files/code/image.ts`, `utils/code.ts`) and are tested
* there against the real implementations. What remains here is the piece
* this file still owns: the `/exec` transport — session forwarding, the
* profile header, and handing the response to the shared parser.
*/
describe('readSandboxImage transport', () => {
beforeEach(() => {
process.env.LIBRECHAT_CODE_BASEURL = 'http://code.test/v1';
mockAxios.mockReset();
mockParseSandboxImageChunk.mockReset();
mockParseSandboxImageChunk.mockImplementation((response) => response);
});
it('reuses the exact artifact preflight buffer without calling /exec', async () => {
const req = {
user: { id: 'artifact-user' },
config: mockReq.config,
};
const source = Buffer.from('cached-image-bytes');
mockAxios.mockResolvedValueOnce({ data: source });
determineFileType.mockResolvedValueOnce({ mime: 'image/png' });
await prepareCodeOutputForInspection({
...baseParams,
req,
id: 'artifact-file',
name: 'charts/result.png',
session_id: 'artifact-session',
});
expect(mockAxios).toHaveBeenCalledTimes(1);
expect(mockAxios.mock.calls[0][0].method).toBe('get');
mockAxios.mockClear();
const result = await readSandboxImage({
req,
file_path: '/mnt/data/charts/result.png',
session_id: 'runtime-session',
files: [
{
id: 'artifact-file',
name: 'charts/result.png',
storage_session_id: 'artifact-session',
},
],
});
expect(mockAxios).not.toHaveBeenCalled();
expect(result).toEqual({ base64: source.toString('base64'), bytes: source.length });
});
it('does not reuse a same-path buffer for a different artifact ref', async () => {
const req = {
user: { id: 'artifact-user' },
config: mockReq.config,
};
mockAxios.mockResolvedValueOnce({ data: Buffer.from('stale') });
determineFileType.mockResolvedValueOnce({ mime: 'image/png' });
await prepareCodeOutputForInspection({
...baseParams,
req,
id: 'stale-file',
name: 'chart.png',
session_id: 'artifact-session',
});
mockAxios.mockReset();
mockAxios.mockResolvedValueOnce({ data: { stdout: '{}' } });
await readSandboxImage({
req,
file_path: '/mnt/data/chart.png',
files: [
{
id: 'current-file',
name: 'chart.png',
storage_session_id: 'artifact-session',
},
],
});
expect(mockAxios).toHaveBeenCalledTimes(1);
expect(mockAxios.mock.calls[0][0].method).toBe('post');
});
it('does not reuse an exact artifact ref across requests', async () => {
const ownerReq = {
user: { id: 'artifact-user' },
config: mockReq.config,
};
const otherReq = {
user: { id: 'other-user' },
config: mockReq.config,
};
mockAxios.mockResolvedValueOnce({ data: Buffer.from('owner-bytes') });
determineFileType.mockResolvedValueOnce({ mime: 'image/png' });
await prepareCodeOutputForInspection({
...baseParams,
req: ownerReq,
id: 'artifact-file',
name: 'chart.png',
session_id: 'artifact-session',
});
mockAxios.mockReset();
mockAxios.mockResolvedValueOnce({ data: { stdout: '{}' } });
await readSandboxImage({
req: otherReq,
file_path: '/mnt/data/chart.png',
files: [
{
id: 'artifact-file',
name: 'chart.png',
storage_session_id: 'artifact-session',
},
],
});
expect(mockAxios).toHaveBeenCalledTimes(1);
expect(mockAxios.mock.calls[0][0].method).toBe('post');
});
it('does not reuse an artifact ref from a different Code API deployment', async () => {
const req = {
user: { id: 'artifact-user' },
config: mockReq.config,
};
mockAxios.mockResolvedValueOnce({ data: Buffer.from('deployment-a') });
determineFileType.mockResolvedValueOnce({ mime: 'image/png' });
await prepareCodeOutputForInspection({
...baseParams,
req,
id: 'artifact-file',
name: 'chart.png',
session_id: 'artifact-session',
codeApiBaseUrl: 'https://code-a.example.com',
executionProfile: 'stateful',
executionRouteKey: 'stateful:deployment-a',
});
mockAxios.mockReset();
mockAxios.mockResolvedValueOnce({ data: { stdout: '{}' } });
await readSandboxImage({
req,
file_path: '/mnt/data/chart.png',
codeApiBaseUrl: 'https://code-b.example.com',
executionProfile: 'stateful',
executionRouteKey: 'stateful:deployment-b',
files: [
{
id: 'artifact-file',
name: 'chart.png',
storage_session_id: 'artifact-session',
},
],
});
expect(mockAxios).toHaveBeenCalledTimes(1);
expect(mockAxios.mock.calls[0][0]).toMatchObject({
method: 'post',
url: 'https://code-b.example.com/exec',
});
});
it('does not reuse a cached artifact for a path containing parent traversal', async () => {
const req = {
user: { id: 'artifact-user' },
config: mockReq.config,
};
mockAxios.mockResolvedValueOnce({ data: Buffer.from('cached-chart') });
determineFileType.mockResolvedValueOnce({ mime: 'image/png' });
await prepareCodeOutputForInspection({
...baseParams,
req,
id: 'artifact-file',
name: 'chart.png',
session_id: 'artifact-session',
});
mockAxios.mockReset();
mockAxios.mockResolvedValueOnce({ data: { stdout: '{}' } });
await readSandboxImage({
req,
file_path: '/mnt/data/link/../chart.png',
files: [
{
id: 'artifact-file',
name: 'chart.png',
storage_session_id: 'artifact-session',
},
],
});
expect(mockAxios).toHaveBeenCalledTimes(1);
expect(mockAxios.mock.calls[0][0].method).toBe('post');
});
it('does not treat a literal backslash in a POSIX path as a separator', async () => {
const req = {
user: { id: 'artifact-user' },
config: mockReq.config,
};
mockAxios.mockResolvedValueOnce({ data: Buffer.from('cached-chart') });
determineFileType.mockResolvedValueOnce({ mime: 'image/png' });
await prepareCodeOutputForInspection({
...baseParams,
req,
id: 'artifact-file',
name: 'charts/result.png',
session_id: 'artifact-session',
});
mockAxios.mockReset();
mockAxios.mockResolvedValueOnce({ data: { stdout: '{}' } });
await readSandboxImage({
req,
file_path: '/mnt/data/charts\\result.png',
files: [
{
id: 'artifact-file',
name: 'charts/result.png',
storage_session_id: 'artifact-session',
},
],
});
expect(mockAxios).toHaveBeenCalledTimes(1);
expect(mockAxios.mock.calls[0][0].method).toBe('post');
});
it('evicts the oldest prepared buffers when the per-request cache reaches its limit', async () => {
const req = {
user: { id: 'artifact-user' },
config: mockReq.config,
};
mockAxios.mockResolvedValue({ data: Buffer.from('cached') });
for (let index = 0; index < 11; index++) {
await prepareCodeOutputForInspection({
...baseParams,
req,
id: `artifact-${index}`,
name: `chart-${index}.png`,
session_id: 'artifact-session',
inspectContent: false,
});
}
mockAxios.mockReset();
mockAxios.mockResolvedValueOnce({ data: { stdout: '{}' } });
await readSandboxImage({
req,
file_path: '/mnt/data/chart-0.png',
files: [
{
id: 'artifact-0',
name: 'chart-0.png',
storage_session_id: 'artifact-session',
},
],
});
expect(mockAxios).toHaveBeenCalledTimes(1);
expect(mockAxios.mock.calls[0][0].method).toBe('post');
mockAxios.mockClear();
const newest = await readSandboxImage({
req,
file_path: '/mnt/data/chart-10.png',
files: [
{
id: 'artifact-10',
name: 'chart-10.png',
storage_session_id: 'artifact-session',
},
],
});
expect(newest).toEqual({ base64: Buffer.from('cached').toString('base64'), bytes: 6 });
expect(mockAxios).not.toHaveBeenCalled();
});
it('applies the inline byte limit before returning a prepared artifact buffer', async () => {
const req = {
user: { id: 'artifact-user' },
config: mockReq.config,
};
const source = Buffer.alloc(128);
mockAxios.mockResolvedValueOnce({ data: source });
determineFileType.mockResolvedValueOnce({ mime: 'image/png' });
await prepareCodeOutputForInspection({
...baseParams,
req,
id: 'large-file',
name: 'large.png',
session_id: 'artifact-session',
});
mockAxios.mockClear();
const result = await readSandboxImage({
req,
file_path: '/mnt/data/large.png',
maxBytes: 64,
files: [
{
id: 'large-file',
name: 'large.png',
storage_session_id: 'artifact-session',
},
],
});
expect(result).toEqual({ tooLarge: true, reason: 'size', bytes: source.length });
expect(mockAxios).not.toHaveBeenCalled();
});
it('forwards the sandbox session, runtime hint and profile header', async () => {
const controller = new AbortController();
mockAxios.mockResolvedValue({ data: { stdout: '{}' } });
await readSandboxImage({
file_path: '/mnt/data/chart.png',
session_id: 'session-abc',
runtime_session_hint: 'hint-xyz',
files: [{ id: 'file-1', name: 'seed.csv' }],
codeApiBaseUrl: 'https://code-stateful.example.com',
executionProfile: 'stateful',
signal: controller.signal,
});
expect(mockAxios).toHaveBeenCalledTimes(1);
const call = mockAxios.mock.calls[0][0];
expect(call.url).toBe('https://code-stateful.example.com/exec');
expect(call.data).toMatchObject({
lang: 'bash',
session_id: 'session-abc',
runtime_session_hint: 'hint-xyz',
files: [{ id: 'file-1', name: 'seed.csv' }],
});
expect(call.headers['X-CodeAPI-Expected-Profile']).toBe('stateful');
expect(call.signal).toBe(controller.signal);
const { withCodeApiRateLimit } = require('@librechat/api');
expect(withCodeApiRateLimit).toHaveBeenCalledWith(
expect.objectContaining({ signal: controller.signal }),
);
});
it('omits the profile header and optional session fields when unset', async () => {
mockAxios.mockResolvedValue({ data: { stdout: '{}' } });
await readSandboxImage({ file_path: '/mnt/data/chart.png' });
const call = mockAxios.mock.calls[0][0];
expect(call.data.session_id).toBeUndefined();
expect(call.data.runtime_session_hint).toBeUndefined();
expect(call.data.files).toBeUndefined();
expect(call.headers['X-CodeAPI-Expected-Profile']).toBeUndefined();
});
it('hands the raw `/exec` response to the shared chunk parser', async () => {
const data = { stdout: '{"total":3,"n":3,"b64":"AAAA"}', status: null };
mockAxios.mockResolvedValue({ data });
mockParseSandboxImageChunk.mockReturnValue({ total: 3, n: 3, b64: 'AAAA' });
const result = await readSandboxImage({ file_path: '/mnt/data/x.png' });
expect(mockParseSandboxImageChunk).toHaveBeenCalledWith(data);
expect(result).toEqual({ total: 3, n: 3, b64: 'AAAA' });
});
it('returns null when no code base URL is configured', async () => {
const { getCodeBaseURL } = require('@librechat/agents');
getCodeBaseURL.mockReturnValueOnce('');
await expect(readSandboxImage({ file_path: '/mnt/data/x.png' })).resolves.toBeNull();
expect(mockAxios).not.toHaveBeenCalled();
});
it('logs and rethrows a transport failure', async () => {
const { logAxiosError } = require('@librechat/api');
mockAxios.mockRejectedValue(new Error('codeapi unreachable'));
await expect(readSandboxImage({ file_path: '/mnt/data/x.png' })).rejects.toThrow(
'codeapi unreachable',
);
expect(logAxiosError).toHaveBeenCalledWith(
expect.objectContaining({
message: 'Error reading sandbox image "/mnt/data/x.png"',
}),
);
});
});
describe('primeFiles keeps one file per sandbox destination (#15443 follow-up)', () => {
/**
* 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
* `context: message_attachment`, so a conversation can hold several
* records sharing a filename.
*/
const { getFiles } = require('~/models');
const { getStrategyFunctions } = require('~/server/services/Files/strategies');
const codeFile = ({
file_id,
filename,
storage_session_id,
createdAt,
context,
sourceDispatchedAt,
sandboxFilename,
}) => ({
file_id,
filename,
createdAt,
context: context ?? 'message_attachment',
source: 'local',
filepath: `/uploads/${file_id}`,
metadata: {
...(sourceDispatchedAt != null ? { sourceDispatchedAt } : {}),
codeEnvRef: {
kind: 'user',
...(sandboxFilename ? { sandboxFilename } : {}),
id: 'user-123',
storage_session_id,
file_id: `${file_id}-sandbox`,
},
},
});
/** Freshness probe answers "uploaded just now", so every file takes the
* cache-hit path and none of them re-upload. */
function setupActiveSessions() {
getStrategyFunctions.mockImplementation(() => ({
getDownloadStream: jest.fn(),
handleFileUpload: jest.fn(),
}));
mockAxios.mockResolvedValue({ data: { lastModified: new Date().toISOString() } });
}
const prime = (tool_resources) =>
primeFiles({
req: { user: { id: 'user-123', role: 'USER' } },
tool_resources: tool_resources ?? { execute_code: { file_ids: ['older', 'newer'] } },
agentId: 'agent-id',
});
const bySession = (result) =>
Object.fromEntries(result.files.map((f) => [f.storage_session_id, f.name]));
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({
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, toolContext } = await prime();
expect(bySession({ files })).toEqual({ 'sess-newer': 'image.png' });
expect(toolContext).toContain('/mnt/data/image.png');
expect(toolContext).not.toContain('uploaded as');
});
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 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',
filename: 'image.png',
storage_session_id: 'sess-older',
createdAt: new Date('2026-01-01T00:00:00Z'),
});
const newer = codeFile({
file_id: 'newer',
filename: 'image.png',
storage_session_id: 'sess-newer',
createdAt: new Date('2026-01-02T00:00:00Z'),
});
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' });
});
it('lets a code output supersede the upload whose name it reused', async () => {
setupActiveSessions();
getFiles.mockResolvedValue([
codeFile({
file_id: 'older',
filename: 'data.csv',
storage_session_id: 'sess-upload',
createdAt: new Date('2026-01-01T00:00:00Z'),
}),
codeFile({
file_id: 'newer',
filename: 'data.csv',
storage_session_id: 'sess-output',
createdAt: new Date('2026-01-02T00:00:00Z'),
context: 'execute_code',
}),
]);
const { files, toolContext } = await prime();
expect(bySession({ files })).toEqual({ 'sess-output': 'data.csv' });
/* The output keeps the path it wrote, so it stays out of the context
* exactly as any other generated file does. */
expect(toolContext).not.toContain('/mnt/data/data.csv');
});
it('lets a newer upload supersede the generated output at the same path', async () => {
setupActiveSessions();
getFiles.mockResolvedValue([
codeFile({
file_id: 'older',
filename: 'report.png',
storage_session_id: 'sess-output',
createdAt: new Date('2026-01-01T00:00:00Z'),
context: 'execute_code',
}),
codeFile({
file_id: 'newer',
filename: 'report.png',
storage_session_id: 'sess-upload',
createdAt: new Date('2026-01-02T00:00:00Z'),
}),
]);
const { files, toolContext } = await prime();
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 () => {
setupActiveSessions();
getFiles.mockResolvedValue([
codeFile({
file_id: 'older',
filename: 'data.csv',
storage_session_id: 'sess-output',
createdAt: new Date('2026-01-01T00:00:00Z'),
context: 'execute_code',
sourceDispatchedAt: Date.parse('2026-03-01T00:00:00Z'),
}),
codeFile({
file_id: 'newer',
filename: 'data.csv',
storage_session_id: 'sess-upload',
createdAt: new Date('2026-02-01T00:00:00Z'),
}),
]);
const { files } = await prime();
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 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([
codeFile({
file_id: 'shared',
filename: 'data.csv',
storage_session_id: 'sess-shared',
createdAt: new Date('2026-01-01T00:00:00Z'),
}),
codeFile({
file_id: 'agent-own',
filename: 'data.csv',
storage_session_id: 'sess-agent',
createdAt: new Date('2026-06-01T00:00:00Z'),
}),
]);
const { files } = await prime({
execute_code: {
file_ids: ['agent-own'],
files: [{ file_id: 'shared' }],
},
});
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 () => {
setupActiveSessions();
getFiles.mockResolvedValue([
codeFile({
file_id: 'older',
filename: 'report.pdf',
storage_session_id: 'sess-only',
createdAt: new Date('2026-01-01T00:00:00Z'),
}),
]);
const { files, toolContext } = await prime();
expect(files.map((f) => f.name)).toEqual(['report.pdf']);
expect(toolContext).toContain('/mnt/data/report.pdf');
expect(toolContext).not.toContain('uploaded as');
});
});
});