Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🚀 feat: Decouple File Attachment Persistence from Preview Rendering (#12957)

Danny Avila6c6c72def764
diff --git a/api/server/controllers/agents/__tests__/callbacks.spec.js b/api/server/controllers/agents/__tests__/callbacks.spec.js
index 8bd711f9c6..0ba20d409c 100644
--- a/api/server/controllers/agents/__tests__/callbacks.spec.js
+++ b/api/server/controllers/agents/__tests__/callbacks.spec.js
@@ -28,6 +28,28 @@ jest.mock('~/server/services/Files/Citations', () => ({
jest.mock('~/server/services/Files/Code/process', () => ({
processCodeOutput: jest.fn(),
+ /* `runPreviewFinalize` is the runtime pairing for `finalize` (defined
+ * alongside processCodeOutput in process.js). The callback wires
+ * the deferred render through it; reproduce the basic happy-path here so the
+ * SSE-emit assertions still work. The catch/defensive-updateFile
+ * branch is unit-tested directly against the real helper in
+ * process.spec.js — exercising it here would add test coupling
+ * without coverage benefit. */
+ runPreviewFinalize: ({ finalize, onResolved }) => {
+ if (typeof finalize !== 'function') {
+ return;
+ }
+ finalize()
+ .then((updated) => {
+ if (!updated || !onResolved) {
+ return;
+ }
+ onResolved(updated);
+ })
+ .catch(() => {
+ /* swallowed in the mock — see process.spec.js for catch coverage */
+ });
+ },
}));
jest.mock('~/server/services/Tools/credentials', () => ({
@@ -326,4 +348,266 @@ describe('createToolEndCallback', () => {
expect(res.write).not.toHaveBeenCalled();
});
});
+
+ describe('code execution deferred-preview emit', () => {
+ /* The deferred-preview code-execution flow emits the attachment twice over
+ * SSE: the initial emit with `status: 'pending'` and the current run's
+ * messageId, the deferred render with the resolved record. The preview update emit
+ * must use the CURRENT run's messageId (not the persisted DB one)
+ * because `processCodeOutput` intentionally preserves the original
+ * `messageId` on cross-turn filename reuse — `getCodeGeneratedFiles`
+ * needs that for prior-turn priming.
+ *
+ * Codex P1 review on PR #12957: shipping `updated.messageId`
+ * straight from the DB record routed preview-update patches to the wrong
+ * message slot, leaving the current turn's pending chip stuck. */
+
+ const { processCodeOutput } = require('~/server/services/Files/Code/process');
+
+ function makeCodeExecutionEvent({ runId, threadId, toolCallId, fileId, name }) {
+ return {
+ output: {
+ name: 'execute_code',
+ tool_call_id: toolCallId,
+ artifact: {
+ session_id: 'sess-1',
+ files: [{ id: fileId, name, session_id: 'sess-1' }],
+ },
+ },
+ metadata: { run_id: runId, thread_id: threadId },
+ };
+ }
+
+ /** Parse the SSE frame `res.write` produces back to a payload object. */
+ function parseSseAttachment(call) {
+ const frame = call[0];
+ const dataLine = frame.split('\n').find((l) => l.startsWith('data: '));
+ return JSON.parse(dataLine.slice('data: '.length));
+ }
+
+ it('the preview update emit uses the current run messageId, not the persisted DB messageId (cross-turn filename reuse)', async () => {
+ /* Simulate turn-2 reusing `output.csv` from turn-1. The DB record
+ * surfaced by `updateFile` carries the original `turn-1-msg`
+ * messageId; the runtime emit must rewrite to `turn-2-msg`. */
+ res.headersSent = true;
+ const finalize = jest.fn().mockResolvedValue({
+ file_id: 'fid-shared',
+ filename: 'output.csv',
+ filepath: '/uploads/output.csv',
+ type: 'text/csv',
+ conversationId: 'thread789',
+ messageId: 'turn-1-original-msg', // persisted DB id (older turn)
+ status: 'ready',
+ text: '<table></table>',
+ textFormat: 'html',
+ });
+ processCodeOutput.mockResolvedValue({
+ file: {
+ file_id: 'fid-shared',
+ filename: 'output.csv',
+ filepath: '/uploads/output.csv',
+ type: 'text/csv',
+ conversationId: 'thread789',
+ messageId: 'turn-2-current-run', // runtime overlay (current turn)
+ toolCallId: 'tool-2',
+ status: 'pending',
+ text: null,
+ textFormat: null,
+ },
+ finalize,
+ });
+
+ const toolEndCallback = createToolEndCallback({ req, res, artifactPromises });
+ const event = makeCodeExecutionEvent({
+ runId: 'turn-2-current-run',
+ threadId: 'thread789',
+ toolCallId: 'tool-2',
+ fileId: 'fid-shared',
+ name: 'output.csv',
+ });
+ await toolEndCallback({ output: event.output }, event.metadata);
+ await Promise.all(artifactPromises);
+ // Wait one more tick so the fire-and-forget finalize() chain settles.
+ await new Promise((resolve) => setImmediate(resolve));
+
+ // Two SSE writes: the initial emit (pending) and the deferred render (ready).
+ expect(res.write).toHaveBeenCalledTimes(2);
+ const phase1 = parseSseAttachment(res.write.mock.calls[0]);
+ const phase2 = parseSseAttachment(res.write.mock.calls[1]);
+
+ // Initial emit already used the runtime messageId (sourced from result.file).
+ expect(phase1.messageId).toBe('turn-2-current-run');
+ expect(phase1.status).toBe('pending');
+
+ /* The preview update MUST also route to the current run's messageId so the
+ * frontend's `useAttachmentHandler` upserts under the same
+ * messageAttachmentsMap slot as the initial emit. Routing to
+ * `turn-1-original-msg` would land the patch on a stale message
+ * and leave turn-2's pending chip stuck. */
+ expect(phase2.messageId).toBe('turn-2-current-run');
+ expect(phase2.file_id).toBe('fid-shared');
+ expect(phase2.status).toBe('ready');
+ expect(phase2.text).toBe('<table></table>');
+ expect(phase2.toolCallId).toBe('tool-2');
+ /* Wire-shape parity with the initial emit: preview update emits the full updated
+ * record so the client doesn't see one shape on the initial emit and a
+ * narrower projection on the deferred render. (Codex audit on PR #12957
+ * Finding 1.) */
+ expect(phase2.filename).toBe('output.csv');
+ expect(phase2.filepath).toBe('/uploads/output.csv');
+ expect(phase2.type).toBe('text/csv');
+ expect(phase2.conversationId).toBe('thread789');
+ expect(phase2.textFormat).toBe('html');
+ });
+
+ it('the preview update emit is skipped when finalize resolves to null (no DB update happened)', async () => {
+ res.headersSent = true;
+ processCodeOutput.mockResolvedValue({
+ file: {
+ file_id: 'fid-1',
+ filename: 'data.xlsx',
+ filepath: '/uploads/data.xlsx',
+ type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+ messageId: 'run-1',
+ toolCallId: 'tool-1',
+ status: 'pending',
+ },
+ finalize: jest.fn().mockResolvedValue(null),
+ });
+
+ const toolEndCallback = createToolEndCallback({ req, res, artifactPromises });
+ const event = makeCodeExecutionEvent({
+ runId: 'run-1',
+ threadId: 'thread-1',
+ toolCallId: 'tool-1',
+ fileId: 'fid-1',
+ name: 'data.xlsx',
+ });
+ await toolEndCallback({ output: event.output }, event.metadata);
+ await Promise.all(artifactPromises);
+ await new Promise((resolve) => setImmediate(resolve));
+
+ // Only the initial emit fired; preview update noop'd because finalize returned null.
+ expect(res.write).toHaveBeenCalledTimes(1);
+ });
+
+ it('the preview update emit is skipped when the response stream has already closed', async () => {
+ res.headersSent = true;
+ /* Hand-rolled deferred so we can hold finalize() open until
+ * AFTER setting `res.writableEnded = true`. Otherwise the mock
+ * resolves synchronously, the .then() runs in the same microtask
+ * queue as the artifactPromises await, and writableEnded is set
+ * too late. */
+ let resolveFinalize;
+ const finalizeDeferred = new Promise((resolve) => {
+ resolveFinalize = resolve;
+ });
+ processCodeOutput.mockResolvedValue({
+ file: {
+ file_id: 'fid-1',
+ filename: 'data.xlsx',
+ filepath: '/uploads/data.xlsx',
+ type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+ messageId: 'run-1',
+ toolCallId: 'tool-1',
+ status: 'pending',
+ },
+ finalize: jest.fn().mockReturnValue(finalizeDeferred),
+ });
+
+ const toolEndCallback = createToolEndCallback({ req, res, artifactPromises });
+ const event = makeCodeExecutionEvent({
+ runId: 'run-1',
+ threadId: 'thread-1',
+ toolCallId: 'tool-1',
+ fileId: 'fid-1',
+ name: 'data.xlsx',
+ });
+ await toolEndCallback({ output: event.output }, event.metadata);
+ await Promise.all(artifactPromises);
+ // Simulate the response closing AFTER the initial emit fires but BEFORE
+ // the deferred render lands. The frontend's polling path will catch the
+ // resolved record on its next tick.
+ res.writableEnded = true;
+ // Now resolve finalize and let the .then() chain run.
+ resolveFinalize({
+ file_id: 'fid-1',
+ filename: 'data.xlsx',
+ messageId: 'run-1',
+ status: 'ready',
+ text: '<x/>',
+ textFormat: 'html',
+ });
+ await new Promise((resolve) => setImmediate(resolve));
+
+ // Initial emit wrote; preview update noop'd because writableEnded.
+ expect(res.write).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not call finalize for a non-office file (no preview expected)', async () => {
+ res.headersSent = true;
+ processCodeOutput.mockResolvedValue({
+ file: {
+ file_id: 'fid-txt',
+ filename: 'note.txt',
+ filepath: '/uploads/note.txt',
+ type: 'text/plain',
+ messageId: 'run-1',
+ toolCallId: 'tool-1',
+ // No status — non-office files skip the deferred render entirely.
+ },
+ // No finalize key — caller should not call anything.
+ });
+
+ const toolEndCallback = createToolEndCallback({ req, res, artifactPromises });
+ const event = makeCodeExecutionEvent({
+ runId: 'run-1',
+ threadId: 'thread-1',
+ toolCallId: 'tool-1',
+ fileId: 'fid-txt',
+ name: 'note.txt',
+ });
+ await toolEndCallback({ output: event.output }, event.metadata);
+ await Promise.all(artifactPromises);
+ await new Promise((resolve) => setImmediate(resolve));
+
+ expect(res.write).toHaveBeenCalledTimes(1);
+ });
+ });
+});
+
+describe('isStreamWritable', () => {
+ /* Direct parametric coverage of the predicate that gates SSE writes
+ * in both the chat-completions and Open Responses callbacks. The
+ * existing deferred-preview tests cover this indirectly via the
+ * `writeAttachmentUpdate` writableEnded path; these tests pin down
+ * each individual branch so a future modification (e.g. adding a
+ * new condition) can't silently regress.
+ * (Comprehensive review NIT on PR #12957.) */
+ const { isStreamWritable } = require('../callbacks');
+
+ it('returns true when streamId is truthy regardless of res state', () => {
+ /* Resumable mode writes go to the job emitter; res state is
+ * irrelevant. Even a closed res with no headers should not block. */
+ expect(isStreamWritable(null, 'stream-1')).toBe(true);
+ expect(isStreamWritable({ headersSent: false, writableEnded: true }, 'stream-1')).toBe(true);
+ expect(isStreamWritable(undefined, 'stream-1')).toBe(true);
+ });
+
+ it('returns false when streamId is falsy and res is null/undefined', () => {
+ expect(isStreamWritable(null, null)).toBe(false);
+ expect(isStreamWritable(undefined, null)).toBe(false);
+ });
+
+ it('returns false when headers have not been sent yet', () => {
+ expect(isStreamWritable({ headersSent: false, writableEnded: false }, null)).toBe(false);
+ });
+
+ it('returns false when the stream has already ended', () => {
+ expect(isStreamWritable({ headersSent: true, writableEnded: true }, null)).toBe(false);
+ });
+
+ it('returns true on the happy path: headers sent, not ended, no streamId', () => {
+ expect(isStreamWritable({ headersSent: true, writableEnded: false }, null)).toBe(true);
+ });
});
diff --git a/api/server/controllers/agents/callbacks.js b/api/server/controllers/agents/callbacks.js
index dc8f6cc65a..c9612c6b62 100644
--- a/api/server/controllers/agents/callbacks.js
+++ b/api/server/controllers/agents/callbacks.js
@@ -15,7 +15,7 @@ const {
createToolExecuteHandler,
} = require('@librechat/api');
const { processFileCitations } = require('~/server/services/Files/Citations');
-const { processCodeOutput } = require('~/server/services/Files/Code/process');
+const { processCodeOutput, runPreviewFinalize } = require('~/server/services/Files/Code/process');
const { saveBase64Image } = require('~/server/services/Files/process');
class ModelEndHandler {
@@ -397,6 +397,55 @@ function writeAttachment(res, streamId, attachment) {
}
}
+/**
+ * Predicate: is it safe to push an SSE write to the caller right now?
+ *
+ * In `streamId` (resumable) mode, writes go to the job emitter and the
+ * `res` state is irrelevant — always writable.
+ *
+ * In standard mode, the caller's `res` must have headers sent (the
+ * stream has been opened) and not yet be `writableEnded` (the response
+ * hasn't closed). Writing to a closed stream raises
+ * `ERR_STREAM_WRITE_AFTER_END`.
+ *
+ * Used by deferred preview emits in both `createToolEndCallback`
+ * (chat-completions) and `createResponsesToolEndCallback` (Open
+ * Responses) so the gate logic stays in one place. (Comprehensive
+ * review #3 on PR #12957.)
+ */
+function isStreamWritable(res, streamId) {
+ if (streamId) {
+ return true;
+ }
+ return !!res && res.headersSent && !res.writableEnded;
+}
+
+/**
+ * Emit an update for an attachment that was previously sent with
+ * `status: 'pending'`. Fire-and-forget: if the response stream has
+ * already closed (the agent finished generating before the deferred
+ * preview resolved) the frontend's React Query polling on
+ * `/api/files/:file_id/preview` picks up the resolved record on its
+ * next tick. Skipping the write in that case avoids
+ * `ERR_STREAM_WRITE_AFTER_END`.
+ *
+ * Reuses the `attachment` SSE event name with a discriminated payload:
+ * the frontend's `useAttachmentHandler` upserts by `file_id`, so a
+ * second event with the same id and `status: 'ready' | 'failed'`
+ * overwrites the pending placeholder in place. No new event type, no
+ * new client listener.
+ *
+ * @param {ServerResponse} res
+ * @param {string | null} streamId
+ * @param {Object} attachment - Updated attachment payload (must carry `file_id`).
+ */
+function writeAttachmentUpdate(res, streamId, attachment) {
+ if (!isStreamWritable(res, streamId)) {
+ return;
+ }
+ writeAttachment(res, streamId, attachment);
+}
+
/**
*
* @param {Object} params
@@ -556,14 +605,15 @@ function createToolEndCallback({ req, res, artifactPromises, streamId = null })
continue;
}
const { id, name } = file;
+ const toolCallId = output.tool_call_id;
artifactPromises.push(
(async () => {
- const fileMetadata = await processCodeOutput({
+ const result = await processCodeOutput({
req,
id,
name,
messageId: metadata.run_id,
- toolCallId: output.tool_call_id,
+ toolCallId,
conversationId: metadata.thread_id,
/**
* Use the FILE's session_id (storage session), not the
@@ -583,15 +633,54 @@ function createToolEndCallback({ req, res, artifactPromises, streamId = null })
*/
session_id: file.session_id ?? output.artifact.session_id,
});
- if (!streamId && !res.headersSent) {
- return fileMetadata;
- }
-
+ const fileMetadata = result?.file ?? null;
+ const finalize = result?.finalize;
if (!fileMetadata) {
return null;
}
-
- writeAttachment(res, streamId, fileMetadata);
+ /* Initial emit: ship the attachment to the client immediately
+ * (carries `status: 'pending'` for office buckets so the UI
+ * shows "preparing preview…"). The agent's response stops
+ * blocking on extraction here.
+ *
+ * Use the shared `isStreamWritable` predicate rather than the
+ * narrower `streamId || res.headersSent` check that lived
+ * here before — a client disconnect mid-stream
+ * (`res.writableEnded`) would otherwise hit `res.write` and
+ * raise `ERR_STREAM_WRITE_AFTER_END` (caught by the outer
+ * IIFE catch but logged as noise). Same gate the Responses
+ * path uses below. */
+ if (isStreamWritable(res, streamId)) {
+ writeAttachment(res, streamId, fileMetadata);
+ }
+ /* Deferred preview rendering: extraction continues running
+ * even after the HTTP response closes. If the stream is still
+ * open when the preview resolves, push an `attachment`
+ * update event so the UI patches in place; otherwise React
+ * Query polling on `/api/files/:file_id/preview` picks it up.
+ *
+ * Spread the full updated record (mirroring the initial emit
+ * shape) and overlay `messageId`/`toolCallId` from the
+ * current run. The DB record preserves the original
+ * `messageId` across cross-turn filename reuse so
+ * `getCodeGeneratedFiles` can trace the file back to its
+ * original assistant message; routing the update SSE by the
+ * persisted id would land the patch on a stale message
+ * slot — turn-N's pending placeholder would stay stuck while
+ * turn-1's already-resolved attachment got re-merged.
+ * (Codex P1 review on PR #12957.) */
+ runPreviewFinalize({
+ finalize,
+ fileId: fileMetadata.file_id,
+ previewRevision: result?.previewRevision,
+ onResolved: (updated) => {
+ writeAttachmentUpdate(res, streamId, {
+ ...updated,
+ messageId: metadata.run_id,
+ toolCallId,
+ });
+ },
+ });
return fileMetadata;
})().catch((error) => {
logger.error('Error processing code output:', error);
@@ -782,14 +871,15 @@ function createResponsesToolEndCallback({ req, res, tracker, artifactPromises })
continue;
}
const { id, name } = file;
+ const toolCallId = output.tool_call_id;
artifactPromises.push(
(async () => {
- const fileMetadata = await processCodeOutput({
+ const result = await processCodeOutput({
req,
id,
name,
messageId: metadata.run_id,
- toolCallId: output.tool_call_id,
+ toolCallId,
conversationId: metadata.thread_id,
/**
* Use the FILE's session_id (storage session), not the
@@ -809,38 +899,45 @@ function createResponsesToolEndCallback({ req, res, tracker, artifactPromises })
*/
session_id: file.session_id ?? output.artifact.session_id,
});
-
+ const fileMetadata = result?.file ?? null;
+ const finalize = result?.finalize;
if (!fileMetadata) {
return null;
}
- // For Responses API, emit attachment during streaming
- if (res.headersSent && !res.writableEnded) {
- const attachment = {
- file_id: fileMetadata.file_id,
- filename: fileMetadata.filename,
- type: fileMetadata.type,
- url: fileMetadata.filepath,
- width: fileMetadata.width,
- height: fileMetadata.height,
- tool_call_id: output.tool_call_id,
- /* Inline text / sanitized HTML preview from
- * `extractCodeArtifactText` — drives the file artifact panel's
- * rich preview for DOCX/XLSX/CSV/PPTX. Pass null explicitly
- * (rather than undefined) so the wire format is stable for the
- * empty-text gate on the client. */
- text: fileMetadata.text ?? null,
- /* Trust signal so the client can route .docx/.csv/.xlsx/
- * .pptx attachments to the office HTML buckets only when
- * the backend produced sanitized full-document HTML.
- * RAG-uploaded plain text from mammoth.extractRawText
- * arrives without this flag and must NOT be injected as
- * HTML — Codex P1 review on PR #12934. */
- textFormat: fileMetadata.textFormat ?? null,
- };
- writeResponsesAttachment(res, tracker, attachment, metadata);
+ /* Initial emit (Open Responses extension format). The agent's
+ * response no longer blocks on extraction. */
+ if (isStreamWritable(res, null)) {
+ writeResponsesAttachment(
+ res,
+ tracker,
+ buildResponsesAttachment(fileMetadata, toolCallId),
+ metadata,
+ );
}
+ /* Deferred preview rendering: extract HTML in the background
+ * and emit a follow-up `librechat:attachment` with the same
+ * `file_id` so the client merges the resolved record over the
+ * pending placeholder. Fire-and-forget — survives response
+ * close; polling covers the post-close gap. */
+ runPreviewFinalize({
+ finalize,
+ fileId: fileMetadata.file_id,
+ previewRevision: result?.previewRevision,
+ onResolved: (updated) => {
+ if (!isStreamWritable(res, null)) {
+ return;
+ }
+ writeResponsesAttachment(
+ res,
+ tracker,
+ buildResponsesAttachment(updated, toolCallId),
+ metadata,
+ );
+ },
+ });
+
return fileMetadata;
})().catch((error) => {
logger.error('Error processing code output:', error);
@@ -851,6 +948,28 @@ function createResponsesToolEndCallback({ req, res, tracker, artifactPromises })
};
}
+/**
+ * Project a file metadata record into the Open Responses attachment
+ * shape. Mirrors the legacy inline projection but adds `status` and
+ * `previewError` so deferred preview updates carry the lifecycle
+ * signal the client uses to upsert by `file_id`.
+ */
+function buildResponsesAttachment(fileMetadata, toolCallId) {
+ return {
+ file_id: fileMetadata.file_id,
+ filename: fileMetadata.filename,
+ type: fileMetadata.type,
+ url: fileMetadata.filepath,
+ width: fileMetadata.width,
+ height: fileMetadata.height,
+ tool_call_id: toolCallId,
+ text: fileMetadata.text ?? null,
+ textFormat: fileMetadata.textFormat ?? null,
+ status: fileMetadata.status,
+ previewError: fileMetadata.previewError,
+ };
+}
+
const ALLOWED_LOG_LEVELS = new Set(['debug', 'info', 'warn', 'error']);
function agentLogHandler(_event, data) {
@@ -906,6 +1025,7 @@ module.exports = {
agentLogHandlerObj,
getDefaultHandlers,
createToolEndCallback,
+ isStreamWritable,
markSummarizationUsage,
buildSummarizationHandlers,
createResponsesToolEndCallback,
diff --git a/api/server/controllers/tools.js b/api/server/controllers/tools.js
index 8124894584..07be1210c1 100644
--- a/api/server/controllers/tools.js
+++ b/api/server/controllers/tools.js
@@ -10,7 +10,7 @@ const {
} = require('librechat-data-provider');
const { getRoleByName, createToolCall, getToolCallsByConvo, getMessage } = require('~/models');
const { processFileURL, uploadImageBuffer } = require('~/server/services/Files/process');
-const { processCodeOutput } = require('~/server/services/Files/Code/process');
+const { processCodeOutput, runPreviewFinalize } = require('~/server/services/Files/Code/process');
const { loadAuthValues } = require('~/server/services/Tools/credentials');
const { loadTools } = require('~/app/clients/tools/util');
@@ -192,7 +192,7 @@ const callTool = async (req, res) => {
const { id, name } = file;
artifactPromises.push(
(async () => {
- const fileMetadata = await processCodeOutput({
+ const result = await processCodeOutput({
req,
id,
name,
@@ -201,11 +201,22 @@ const callTool = async (req, res) => {
conversationId,
session_id: artifact.session_id,
});
-
+ const fileMetadata = result?.file ?? null;
+ const finalize = result?.finalize;
if (!fileMetadata) {
return null;
}
-
+ /* This endpoint is non-streaming and its contract is "give
+ * me the artifacts" — return the persisted record immediately
+ * (with `status: 'pending'` for office buckets) and run the
+ * preview render in the background. The client polls
+ * `/api/files/:file_id/preview` for the resolved record.
+ * No `onResolved` — there's no live stream to write to here. */
+ runPreviewFinalize({
+ finalize,
+ fileId: fileMetadata.file_id,
+ previewRevision: result?.previewRevision,
+ });
return fileMetadata;
})().catch((error) => {
logger.error('Error processing code output:', error);
diff --git a/api/server/experimental.js b/api/server/experimental.js
index cd594c1696..b12b9deffe 100644
--- a/api/server/experimental.js
+++ b/api/server/experimental.js
@@ -10,7 +10,7 @@ const express = require('express');
const passport = require('passport');
const compression = require('compression');
const cookieParser = require('cookie-parser');
-const { logger } = require('@librechat/data-schemas');
+const { logger, runAsSystem } = require('@librechat/data-schemas');
const mongoSanitize = require('express-mongo-sanitize');
const {
isEnabled,
@@ -26,7 +26,12 @@ const initializeOAuthReconnectManager = require('./services/initializeOAuthRecon
const createValidateImageRequest = require('./middleware/validateImageRequest');
const { jwtLogin, ldapLogin, passportLogin } = require('~/strategies');
const { updateInterfacePermissions: updateInterfacePerms } = require('@librechat/api');
-const { getRoleByName, updateAccessPermissions, seedDatabase } = require('~/models');
+const {
+ getRoleByName,
+ updateAccessPermissions,
+ seedDatabase,
+ sweepOrphanedPreviews,
+} = require('~/models');
const { checkMigrations } = require('./services/start/migration');
const initializeMCPs = require('./services/initializeMCPs');
const configureSocialLogins = require('./socialLogins');
@@ -220,6 +225,11 @@ if (cluster.isMaster) {
/** Seed database (idempotent) */
await seedDatabase();
+ /* Mirrors `server/index.js`; `runAsSystem` for tenant-isolated File. */
+ runAsSystem(sweepOrphanedPreviews).catch((err) => {
+ logger.error('[sweepOrphanedPreviews] Background sweep failed:', err);
+ });
+
/** Initialize app configuration */
const appConfig = await getAppConfig();
initializeFileStorage(appConfig);
diff --git a/api/server/index.js b/api/server/index.js
index d798f1a166..6bc4a131e6 100644
--- a/api/server/index.js
+++ b/api/server/index.js
@@ -25,7 +25,12 @@ const {
} = require('@librechat/api');
const { connectDb, indexSync } = require('~/db');
const initializeOAuthReconnectManager = require('./services/initializeOAuthReconnectManager');
-const { getRoleByName, updateAccessPermissions, seedDatabase } = require('~/models');
+const {
+ getRoleByName,
+ updateAccessPermissions,
+ seedDatabase,
+ sweepOrphanedPreviews,
+} = require('~/models');
const { capabilityContextMiddleware } = require('./middleware/roles/capabilities');
const createValidateImageRequest = require('./middleware/validateImageRequest');
const { jwtLogin, ldapLogin, passportLogin } = require('~/strategies');
@@ -69,6 +74,13 @@ const startServer = async () => {
}
await runAsSystem(seedDatabase);
+ /* Recover stuck `status: 'pending'` records from a crash mid-render.
+ * `runAsSystem` is required — `File` is tenant-isolated and strict
+ * mode rejects unscoped queries. Lazy sweep in the preview endpoint
+ * covers anything younger than the boot cutoff. */
+ runAsSystem(sweepOrphanedPreviews).catch((err) => {
+ logger.error('[sweepOrphanedPreviews] Background sweep failed:', err);
+ });
const appConfig = await getAppConfig({ baseOnly: true });
initializeFileStorage(appConfig);
await runAsSystem(async () => {
diff --git a/api/server/routes/files/files.js b/api/server/routes/files/files.js
index 5c26f65b81..285f783909 100644
--- a/api/server/routes/files/files.js
+++ b/api/server/routes/files/files.js
@@ -295,6 +295,86 @@ router.get('/code/download/:session_id/:fileId', async (req, res) => {
}
});
+/* Lazy-sweep cutoff: pending records older than this are marked failed
+ * on the next poll. 2min is well past the 60s render ceiling, so any
+ * `pending` past it is definitively orphaned. Tighter than the boot
+ * sweep (5min) since this runs per-request, not per-instance. */
+const PREVIEW_LAZY_SWEEP_CUTOFF_MS = 2 * 60 * 1000;
+
+/**
+ * Poll the lifecycle status of a code-execution file's inline preview.
+ *
+ * Deferred-preview flow: the immediate persist step writes the file
+ * record at `status: 'pending'`; the background render transitions
+ * it to `'ready'` (with `text` + `textFormat`) or `'failed'` (with
+ * `previewError`). The frontend's `useFilePreview` React Query hook
+ * polls this endpoint at ~2.5s intervals while `status === 'pending'`,
+ * then auto-stops on terminal status.
+ *
+ * Returns the smallest viable shape:
+ * - `status` always present (defaults to `'ready'` for legacy records
+ * that never had the field — clients treat absent as ready).
+ * - `text` and `textFormat` only when status is 'ready' AND text
+ * is non-null (preserves the security contract from PR #12934 —
+ * office bucket files MUST NOT receive plain-text fallbacks).
+ * - `previewError` only when status is 'failed'.
+ *
+ * Lazy-sweeps stale `pending` records on the spot — see
+ * `PREVIEW_LAZY_SWEEP_CUTOFF_MS` for the rationale.
+ *
+ * Reuses the `fileAccess` middleware so ACL is identical to download.
+ *
+ * @route GET /files/:file_id/preview
+ */
+router.get('/:file_id/preview', fileAccess, async (req, res) => {
+ try {
+ const { file_id } = req.params;
+ /* `fileAccess` already fetched the record (sans `text`, the default
+ * projection drops it). Reuse for the lifecycle check; only re-fetch
+ * with `text` on a terminal ready response — the typical lifecycle
+ * is N pending polls + 1 ready, so this avoids ~N redundant text
+ * reads per file. */
+ let file = req.fileAccess.file;
+ /* Lazy sweep: if stuck `pending` past the cutoff, mark `failed`
+ * conditional on the observed `updatedAt` (concurrent legitimate
+ * updates win). */
+ if (file.status === 'pending' && file.updatedAt instanceof Date) {
+ const ageMs = Date.now() - file.updatedAt.getTime();
+ if (ageMs > PREVIEW_LAZY_SWEEP_CUTOFF_MS) {
+ const swept = await db.updateFile(
+ { file_id, status: 'failed', previewError: 'orphaned' },
+ { status: 'pending', updatedAt: file.updatedAt },
+ );
+ if (swept) {
+ file = swept;
+ logger.info(
+ `[/files/:file_id/preview] Lazy-swept orphaned pending record ${file_id} (age ${Math.round(ageMs / 1000)}s)`,
+ );
+ }
+ }
+ }
+ /* Default to 'ready' for back-compat: legacy records pre-date the
+ * field, and non-office files never get a status set on persist. */
+ const status = file.status ?? 'ready';
+ const payload = { file_id, status };
+ if (status === 'ready') {
+ const withText = await db.findFileById(file_id);
+ if (withText?.text != null) {
+ payload.text = withText.text;
+ payload.textFormat = withText.textFormat ?? null;
+ }
+ } else if (status === 'failed' && file.previewError) {
+ payload.previewError = file.previewError;
+ }
+ return res.status(200).json(payload);
+ } catch (error) {
+ logger.error('[/files/:file_id/preview] Error fetching preview status:', error);
+ return res
+ .status(500)
+ .json({ error: 'Internal Server Error', message: 'Failed to fetch preview status' });
+ }
+});
+
router.get('/download/:userId/:file_id', fileAccess, async (req, res) => {
try {
const { userId, file_id } = req.params;
diff --git a/api/server/routes/files/preview.spec.js b/api/server/routes/files/preview.spec.js
new file mode 100644
index 0000000000..f86c128d4b
--- /dev/null
+++ b/api/server/routes/files/preview.spec.js
@@ -0,0 +1,372 @@
+/**
+ * Coverage for the new GET /files/:file_id/preview endpoint.
+ *
+ * Deferred-preview code-execution flow: the immediate persist step
+ * emits a file record at `status: 'pending'`; the background render
+ * transitions it to `'ready'` (with text) or `'failed'` (with
+ * previewError). The frontend polls this endpoint until status is
+ * terminal. This suite asserts the response shape across all four
+ * states (pending, ready, failed, legacy/back-compat) and the auth
+ * boundary (404 vs 403).
+ */
+
+jest.mock('@librechat/data-schemas', () => ({
+ logger: { warn: jest.fn(), debug: jest.fn(), error: jest.fn(), info: jest.fn() },
+ SystemCapabilities: {},
+}));
+
+jest.mock('@librechat/api', () => ({
+ refreshS3FileUrls: jest.fn(),
+ resolveUploadErrorMessage: jest.fn(),
+ verifyAgentUploadPermission: jest.fn(),
+}));
+
+const mockFindFileById = jest.fn();
+const mockGetFiles = jest.fn();
+const mockUpdateFile = jest.fn();
+jest.mock('~/models', () => ({
+ findFileById: (...args) => mockFindFileById(...args),
+ getFiles: (...args) => mockGetFiles(...args),
+ updateFile: (...args) => mockUpdateFile(...args),
+ getAgents: jest.fn().mockResolvedValue([]),
+ batchUpdateFiles: jest.fn(),
+}));
+
+jest.mock('~/server/services/Files/process', () => ({
+ filterFile: jest.fn(),
+ processFileUpload: jest.fn(),
+ processDeleteRequest: jest.fn(),
+ processAgentFileUpload: jest.fn(),
+}));
+
+jest.mock('~/server/services/Files/strategies', () => ({
+ getStrategyFunctions: jest.fn(() => ({})),
+}));
+
+jest.mock('~/server/controllers/assistants/helpers', () => ({
+ getOpenAIClient: jest.fn(),
+}));
+
+jest.mock('~/server/middleware/roles/capabilities', () => ({
+ hasCapability: jest.fn(() => (_req, _res, next) => next()),
+}));
+
+jest.mock('~/server/services/PermissionService', () => ({
+ checkPermission: jest.fn(() => (_req, _res, next) => next()),
+ getEffectivePermissions: jest.fn().mockResolvedValue(0),
+}));
+
+jest.mock('~/server/services/Files', () => ({
+ hasAccessToFilesViaAgent: jest.fn(),
+}));
+
+jest.mock('~/server/utils/files', () => ({
+ cleanFileName: (name) => name,
+}));
+
+jest.mock('~/cache', () => ({
+ getLogStores: jest.fn(() => ({ get: jest.fn(), set: jest.fn() })),
+}));
+
+const express = require('express');
+const request = require('supertest');
+const filesRouter = require('./files');
+
+/**
+ * Mount the router with a per-request user injector so we can simulate
+ * a logged-in user without spinning up the full auth stack.
+ */
+function buildApp({ user = { id: 'user-123', role: 'user' } } = {}) {
+ const app = express();
+ app.use(express.json());
+ app.use((req, _res, next) => {
+ req.user = user;
+ req.config = { fileStrategy: 'local' };
+ next();
+ });
+ app.use('/files', filesRouter);
+ return app;
+}
+
+const OWNER_USER_ID = 'user-123';
+
+describe('GET /files/:file_id/preview', () => {
+ beforeEach(() => {
+ mockFindFileById.mockReset();
+ mockGetFiles.mockReset();
+ mockUpdateFile.mockReset();
+ });
+
+ it('returns 404 when the file does not exist (auth check fails first via fileAccess)', async () => {
+ /* `fileAccess` middleware does its own getFiles lookup and returns
+ * 404 before our handler ever runs. This test asserts the boundary
+ * lives there, not that the handler duplicates the check. */
+ mockGetFiles.mockResolvedValueOnce([]);
+ const res = await request(buildApp()).get('/files/missing-id/preview');
+ expect(res.status).toBe(404);
+ expect(res.body).toMatchObject({ error: 'Not Found' });
+ expect(mockFindFileById).not.toHaveBeenCalled();
+ });
+
+ it('returns 403 when the requester does not own the file and has no agent-based access', async () => {
+ /* fileAccess returns 403 — the file exists but belongs to someone
+ * else and no agent grants access. The preview handler should
+ * never run. */
+ mockGetFiles.mockResolvedValueOnce([
+ { file_id: 'someone-elses', user: 'other-user', filename: 'x.xlsx' },
+ ]);
+ const res = await request(buildApp()).get('/files/someone-elses/preview');
+ expect(res.status).toBe(403);
+ expect(mockFindFileById).not.toHaveBeenCalled();
+ });
+
+ it('returns status:pending without text/textFormat while the deferred render is in flight', async () => {
+ mockGetFiles.mockResolvedValueOnce([
+ {
+ file_id: 'fid-pending',
+ user: OWNER_USER_ID,
+ filename: 'data.xlsx',
+ status: 'pending',
+ },
+ ]);
+ const res = await request(buildApp()).get('/files/fid-pending/preview');
+ expect(res.status).toBe(200);
+ expect(res.body).toEqual({ file_id: 'fid-pending', status: 'pending' });
+ /* Pending must NOT leak `text` and must NOT trigger the text re-fetch. */
+ expect(res.body).not.toHaveProperty('text');
+ expect(mockFindFileById).not.toHaveBeenCalled();
+ });
+
+ it('returns status:ready with text + textFormat when the deferred render succeeded', async () => {
+ mockGetFiles.mockResolvedValueOnce([
+ { file_id: 'fid-ready', user: OWNER_USER_ID, filename: 'data.xlsx', status: 'ready' },
+ ]);
+ /* Text is fetched only on the terminal ready response. */
+ mockFindFileById.mockResolvedValueOnce({
+ file_id: 'fid-ready',
+ text: '<table><tr><td>1</td></tr></table>',
+ textFormat: 'html',
+ });
+ const res = await request(buildApp()).get('/files/fid-ready/preview');
+ expect(res.status).toBe(200);
+ expect(res.body).toEqual({
+ file_id: 'fid-ready',
+ status: 'ready',
+ text: '<table><tr><td>1</td></tr></table>',
+ textFormat: 'html',
+ });
+ });
+
+ it('returns status:failed with previewError when the deferred render errored', async () => {
+ mockGetFiles.mockResolvedValueOnce([
+ {
+ file_id: 'fid-failed',
+ user: OWNER_USER_ID,
+ filename: 'data.xlsx',
+ status: 'failed',
+ previewError: 'parser-error',
+ },
+ ]);
+ const res = await request(buildApp()).get('/files/fid-failed/preview');
+ expect(res.status).toBe(200);
+ expect(res.body).toEqual({
+ file_id: 'fid-failed',
+ status: 'failed',
+ previewError: 'parser-error',
+ });
+ expect(mockFindFileById).not.toHaveBeenCalled();
+ });
+
+ it('defaults to status:ready for legacy records with no status field (back-compat)', async () => {
+ mockGetFiles.mockResolvedValueOnce([
+ {
+ file_id: 'fid-legacy',
+ user: OWNER_USER_ID,
+ filename: 'old.csv',
+ // status intentionally absent
+ },
+ ]);
+ mockFindFileById.mockResolvedValueOnce({
+ file_id: 'fid-legacy',
+ text: 'csv,header\n1,2',
+ textFormat: 'text',
+ });
+ const res = await request(buildApp()).get('/files/fid-legacy/preview');
+ expect(res.status).toBe(200);
+ expect(res.body).toEqual({
+ file_id: 'fid-legacy',
+ status: 'ready',
+ text: 'csv,header\n1,2',
+ textFormat: 'text',
+ });
+ });
+
+ it('returns status:ready with no text when the record is ready but text is null (binary/oversized)', async () => {
+ mockGetFiles.mockResolvedValueOnce([
+ { file_id: 'fid-binary', user: OWNER_USER_ID, filename: 'image.bin' },
+ ]);
+ mockFindFileById.mockResolvedValueOnce({
+ file_id: 'fid-binary',
+ text: null,
+ textFormat: null,
+ });
+ const res = await request(buildApp()).get('/files/fid-binary/preview');
+ expect(res.status).toBe(200);
+ expect(res.body).toEqual({ file_id: 'fid-binary', status: 'ready' });
+ });
+
+ it('returns ready with no text when ready record was deleted between fileAccess and text fetch', async () => {
+ /* `fileAccess` saw the record but the concurrent delete removed it
+ * before the text fetch. Surface ready-without-text rather than
+ * 500 — the client routes to download-only and stops polling. */
+ mockGetFiles.mockResolvedValueOnce([
+ { file_id: 'fid-race', user: OWNER_USER_ID, filename: 'data.xlsx', status: 'ready' },
+ ]);
+ mockFindFileById.mockResolvedValueOnce(null);
+ const res = await request(buildApp()).get('/files/fid-race/preview');
+ expect(res.status).toBe(200);
+ expect(res.body).toEqual({ file_id: 'fid-race', status: 'ready' });
+ });
+
+ it('returns 500 with a stable shape if the text fetch throws unexpectedly', async () => {
+ mockGetFiles.mockResolvedValueOnce([
+ { file_id: 'fid-boom', user: OWNER_USER_ID, filename: 'data.xlsx', status: 'ready' },
+ ]);
+ mockFindFileById.mockRejectedValueOnce(new Error('mongo down'));
+ const res = await request(buildApp()).get('/files/fid-boom/preview');
+ expect(res.status).toBe(500);
+ expect(res.body).toMatchObject({ error: 'Internal Server Error' });
+ });
+
+ describe('lazy sweep for stale pending records', () => {
+ /* The boot-time `sweepOrphanedPreviews` only runs once at startup
+ * with a 5-min cutoff. A backend crash + quick restart can leave
+ * `pending` records younger than 5 min that never get touched
+ * again. This endpoint sweeps them on the spot whenever a polling
+ * request lands on one — the user is exactly the consumer who
+ * cares, so on-demand sweep is the right shape. (Codex P2 review
+ * on PR #12957.) */
+ const STALE_MS = 6 * 60 * 1000;
+ const FRESH_MS = 30 * 1000;
+
+ it('marks a stale pending record as failed:orphaned and returns the swept state', async () => {
+ const updatedAt = new Date(Date.now() - STALE_MS);
+ mockGetFiles.mockResolvedValueOnce([
+ {
+ file_id: 'fid-stale',
+ user: OWNER_USER_ID,
+ filename: 'data.xlsx',
+ status: 'pending',
+ updatedAt,
+ },
+ ]);
+ mockUpdateFile.mockResolvedValueOnce({
+ file_id: 'fid-stale',
+ status: 'failed',
+ previewError: 'orphaned',
+ });
+
+ const res = await request(buildApp()).get('/files/fid-stale/preview');
+
+ expect(mockUpdateFile).toHaveBeenCalledWith(
+ { file_id: 'fid-stale', status: 'failed', previewError: 'orphaned' },
+ { status: 'pending', updatedAt },
+ );
+ expect(res.status).toBe(200);
+ expect(res.body).toEqual({
+ file_id: 'fid-stale',
+ status: 'failed',
+ previewError: 'orphaned',
+ });
+ });
+
+ it('does NOT sweep a fresh pending record (within the cutoff window)', async () => {
+ mockGetFiles.mockResolvedValueOnce([
+ {
+ file_id: 'fid-fresh',
+ user: OWNER_USER_ID,
+ filename: 'data.xlsx',
+ status: 'pending',
+ updatedAt: new Date(Date.now() - FRESH_MS),
+ },
+ ]);
+
+ const res = await request(buildApp()).get('/files/fid-fresh/preview');
+
+ expect(mockUpdateFile).not.toHaveBeenCalled();
+ expect(res.status).toBe(200);
+ expect(res.body).toEqual({ file_id: 'fid-fresh', status: 'pending' });
+ });
+
+ it('sweeps a record past the 2min cutoff but below the 5min boot-sweep threshold', async () => {
+ /* Pins the cutoff change from 5min to 2min — without this, a
+ * future revert wouldn't fail the suite. */
+ const updatedAt = new Date(Date.now() - 3 * 60 * 1000);
+ mockGetFiles.mockResolvedValueOnce([
+ {
+ file_id: 'fid-mid',
+ user: OWNER_USER_ID,
+ filename: 'data.xlsx',
+ status: 'pending',
+ updatedAt,
+ },
+ ]);
+ mockUpdateFile.mockResolvedValueOnce({
+ file_id: 'fid-mid',
+ status: 'failed',
+ previewError: 'orphaned',
+ });
+
+ const res = await request(buildApp()).get('/files/fid-mid/preview');
+
+ expect(mockUpdateFile).toHaveBeenCalled();
+ expect(res.body).toEqual({
+ file_id: 'fid-mid',
+ status: 'failed',
+ previewError: 'orphaned',
+ });
+ });
+
+ it('does NOT sweep a stale ready record (only pending qualifies)', async () => {
+ mockGetFiles.mockResolvedValueOnce([
+ {
+ file_id: 'fid-ready',
+ user: OWNER_USER_ID,
+ filename: 'data.xlsx',
+ status: 'ready',
+ updatedAt: new Date(Date.now() - STALE_MS),
+ },
+ ]);
+ mockFindFileById.mockResolvedValueOnce({
+ file_id: 'fid-ready',
+ text: 'final',
+ textFormat: 'html',
+ });
+
+ const res = await request(buildApp()).get('/files/fid-ready/preview');
+
+ expect(mockUpdateFile).not.toHaveBeenCalled();
+ expect(res.body).toMatchObject({ status: 'ready', text: 'final' });
+ });
+
+ it('falls through to the original pending payload if the conditional sweep loses the race', async () => {
+ const updatedAt = new Date(Date.now() - STALE_MS);
+ mockGetFiles.mockResolvedValueOnce([
+ {
+ file_id: 'fid-race',
+ user: OWNER_USER_ID,
+ filename: 'data.xlsx',
+ status: 'pending',
+ updatedAt,
+ },
+ ]);
+ mockUpdateFile.mockResolvedValueOnce(null);
+
+ const res = await request(buildApp()).get('/files/fid-race/preview');
+
+ expect(mockUpdateFile).toHaveBeenCalled();
+ expect(res.status).toBe(200);
+ expect(res.body).toEqual({ file_id: 'fid-race', status: 'pending' });
+ });
+ });
+});
diff --git a/api/server/services/Files/Code/__tests__/process-traversal.spec.js b/api/server/services/Files/Code/__tests__/process-traversal.spec.js
index 099794821d..b6fcc2636f 100644
--- a/api/server/services/Files/Code/__tests__/process-traversal.spec.js
+++ b/api/server/services/Files/Code/__tests__/process-traversal.spec.js
@@ -32,6 +32,13 @@ jest.mock('@librechat/api', () => {
* mock returns null in lockstep with the null `text` above so
* downstream consumers don't see a phantom format. */
getExtractedTextFormat: jest.fn(() => null),
+ /* Pass-through `withTimeout`: this suite asserts traversal sanitization,
+ * not deferred preview timing. */
+ withTimeout: async (promise) => promise,
+ /* These traversal cases all use non-office filenames — keep the
+ * inline (non-finalize) path so existing assertions on a single
+ * createFile call hold. */
+ hasOfficeHtmlPath: jest.fn(() => false),
codeServerHttpAgent: new http.Agent({ keepAlive: false }),
codeServerHttpsAgent: new https.Agent({ keepAlive: false }),
};
diff --git a/api/server/services/Files/Code/process.js b/api/server/services/Files/Code/process.js
index 4348d2766f..4efc938223 100644
--- a/api/server/services/Files/Code/process.js
+++ b/api/server/services/Files/Code/process.js
@@ -3,8 +3,10 @@ const { v4 } = require('uuid');
const { logger } = require('@librechat/data-schemas');
const { getCodeBaseURL } = require('@librechat/agents');
const {
+ withTimeout,
getBasePath,
logAxiosError,
+ hasOfficeHtmlPath,
sanitizeArtifactPath,
flattenArtifactPath,
createAxiosInstance,
@@ -69,8 +71,235 @@ const createDownloadFallback = ({
};
/**
- * Process code execution output files - downloads and saves both images and non-image files.
- * All files are saved to local storage with fileIdentifier metadata for code env re-upload.
+ * Hard ceiling on the deferred preview rendering (HTML extraction + DB
+ * update). The inner office-render path already has its own 12s timeout
+ * and a concurrency-limited queue; this is the outer guard that catches
+ * pathological cases where queue wait + render + DB write would
+ * otherwise hang the file in `status: 'pending'` indefinitely.
+ *
+ * If the timeout fires the record is updated to `status: 'failed'`
+ * with `previewError: 'timeout'` and the UI shows download-only.
+ */
+const PREVIEW_FINALIZE_TIMEOUT_MS = 60_000;
+
+/**
+ * Render the inline HTML preview for a code-execution file (or plain
+ * text for non-office buckets that still benefit from caching), then
+ * atomically transition the DB record to `status: 'ready'` (with
+ * `text`/`textFormat`) or `status: 'failed'` (with `previewError`).
+ *
+ * Decoupled from `processCodeOutput` so the agent's final response is
+ * not blocked on potentially slow office rendering. The caller fires
+ * this without awaiting; promises continue running after the HTTP
+ * response closes (Node doesn't kill them) and the frontend learns of
+ * completion via the `attachment` update SSE event (if the stream is
+ * still open) or via React Query polling otherwise. Process restart
+ * is the only thing that can lose progress — covered by the boot-time
+ * orphan sweep.
+ *
+ * @param {object} params
+ * @param {Buffer} params.buffer - The full downloaded file contents,
+ * bounded by the server's `fileSizeLimit` config (defaults far above
+ * the 1MB extractor cap). The buffer is captured by the closure
+ * returned in `{ finalize }`, so when many office files queue behind
+ * the inner concurrency limiter (cap 2), all queued buffers stay
+ * resident until each one's slot frees. For a tool result emitting
+ * N office files, peak heap usage from this path is up to
+ * `N * fileSizeLimit`. Acceptable for typical agent runs (a handful
+ * of files at a few hundred KB each); pathological cases are bounded
+ * by the inner per-file 12s timeout and the outer 60s render cap.
+ * @param {string} params.leafName - Basename for classification.
+ * @param {string} params.mimeType - Detected/inferred MIME.
+ * @param {string} params.category - Classifier output.
+ * @param {string} params.file_id - The DB record key for the update.
+ * @param {string} [params.previewRevision] - Generation marker stamped
+ * by the immediate persist step. The DB commit is conditional on
+ * this — if a newer emit (cross-turn filename reuse) has rotated
+ * the revision before this render finishes, `updateFile` returns
+ * null and the stale render is silently discarded rather than
+ * overwriting the newer record.
+ * @returns {Promise<MongoFile | null>} The post-update record on
+ * success; `null` if the DB update itself failed (extraction failure
+ * is reflected as `status: 'failed'`, not a thrown error) or if the
+ * `previewRevision` guard rejected the write.
+ */
+const finalizePreview = async ({
+ buffer,
+ leafName,
+ mimeType,
+ category,
+ file_id,
+ previewRevision,
+}) => {
+ let text = null;
+ let previewError;
+ try {
+ text = await withTimeout(
+ extractCodeArtifactText(buffer, leafName, mimeType, category),
+ PREVIEW_FINALIZE_TIMEOUT_MS,
+ `Preview extraction exceeded ${PREVIEW_FINALIZE_TIMEOUT_MS}ms`,
+ );
+ } catch (_error) {
+ /* `extractCodeArtifactText` swallows its own errors and returns null,
+ * so the only way to reach here is a `withTimeout` rejection — i.e.
+ * the queue + render combined exceeded the outer 60s ceiling. */
+ previewError = 'timeout';
+ logger.warn(
+ `[finalizePreview] ${file_id}: extraction timed out after ${PREVIEW_FINALIZE_TIMEOUT_MS}ms`,
+ );
+ }
+ /* HTML-or-null contract (PR #12934): null result on an office file
+ * must NOT fall back to plain text — surface as failed. Caller gates
+ * on `hasOfficeHtmlPath`, so reaching here always means office. */
+ const textFormat = getExtractedTextFormat(leafName, mimeType, text);
+ const failed = text == null;
+ const status = failed ? 'failed' : 'ready';
+ if (failed && !previewError) {
+ previewError = 'parser-error';
+ }
+ try {
+ /* Conditional update: commit only if `previewRevision` still
+ * matches what the immediate persist step stamped. If a newer
+ * emit has rotated the revision (cross-turn filename reuse),
+ * `updateFile` returns null and the stale render is silently
+ * discarded. (Codex P1 review on PR #12957.) */
+ const updated = await updateFile(
+ {
+ file_id,
+ text,
+ textFormat,
+ status,
+ previewError: failed ? previewError : null,
+ },
+ previewRevision ? { previewRevision } : undefined,
+ );
+ if (!updated && previewRevision) {
+ logger.debug(
+ `[finalizePreview] ${file_id}: stale render skipped — newer emit has superseded revision ${previewRevision}`,
+ );
+ }
+ return updated;
+ } catch (error) {
+ logger.error(
+ `[finalizePreview] ${file_id}: failed to persist preview result: ${error?.message ?? error}`,
+ );
+ return null;
+ }
+};
+
+/**
+ * Run the background `finalize` thunk returned by `processCodeOutput`
+ * and route the resolved record to the caller's emit logic. Shared
+ * between `callbacks.js` (chat-completions + Open Responses) and
+ * `tools.js` (direct tool endpoint) so the fire-and-forget pattern
+ * doesn't drift across callsites.
+ *
+ * `onResolved` receives the post-update DB record and is the only piece
+ * that varies — chat-completions writes the legacy `attachment` SSE
+ * event, Open Responses writes the spec-shaped `librechat:attachment`
+ * event with a sequence number, and the direct tool endpoint has no
+ * stream to write to (caller passes a no-op).
+ *
+ * The catch path is the safety net for unexpected programming errors
+ * inside `finalizePreview` ONLY. The function is designed to never
+ * throw (extraction and DB failures are translated to `status: 'failed'`
+ * inside it), but a ref error or future regression would otherwise
+ * leave the DB record stuck at `'pending'` until the boot-time orphan
+ * sweep — potentially hours away on a stable server. We attempt a
+ * best-effort `updateFile` to mark the record `'failed'` with
+ * `previewError: 'unexpected'` so the UI stops polling and the
+ * next-turn LLM context surfaces the failure.
+ *
+ * `onResolved` errors are deliberately isolated in their own try/catch.
+ * Without that isolation, a transient transport-side failure (SSE write
+ * race after the stream closed, an emitter listener throwing) would
+ * propagate into the finalize catch and downgrade an *already-resolved*
+ * record to `failed` with `previewError: 'unexpected'` — surfacing
+ * "preview unavailable" in the UI even though extraction succeeded
+ * and the file is on disk. The emit failure is logged but the DB
+ * record stays at whatever `finalizePreview` wrote (typically
+ * `'ready'`), so the polling layer / next page load still sees the
+ * resolved preview.
+ *
+ * @param {object} params
+ * @param {(() => Promise<object | null>) | undefined} params.finalize - The
+ * thunk returned by `processCodeOutput`. No-op when undefined.
+ * @param {string | undefined} params.fileId - DB key for the failure
+ * marker; if absent the catch only logs.
+ * @param {string | undefined} [params.previewRevision] - Generation
+ * marker stamped by the immediate persist step. The defensive
+ * `updateFile` in the catch is conditional on this — if a newer
+ * emit has rotated the revision, the stale failure marker is
+ * silently discarded so a programming error from an older render
+ * doesn't override a newer turn's record.
+ * @param {(updated: object) => void} [params.onResolved] - Called once
+ * on success with the post-update record.
+ */
+const runPreviewFinalize = ({ finalize, fileId, previewRevision, onResolved }) => {
+ if (typeof finalize !== 'function') {
+ return;
+ }
+ finalize()
+ .then((updated) => {
+ if (!updated || !onResolved) {
+ return;
+ }
+ /* Isolated try/catch — a throw inside `onResolved` (transport-side
+ * SSE write race, emitter listener error) MUST NOT propagate to
+ * the outer `.catch`, which would downgrade an already-resolved
+ * record to `failed` with `previewError: 'unexpected'`.
+ * Extraction succeeded at this point and `finalizePreview` has
+ * already persisted the terminal status; the polling layer / next
+ * page load will surface the resolved preview even if this turn's
+ * SSE emit didn't land. */
+ try {
+ onResolved(updated);
+ } catch (emitError) {
+ logger.error(
+ `[runPreviewFinalize] onResolved threw for ${fileId}; record stays at the finalized status:`,
+ emitError,
+ );
+ }
+ })
+ .catch((error) => {
+ logger.error('Error rendering deferred preview:', error);
+ if (!fileId) {
+ return;
+ }
+ updateFile(
+ {
+ file_id: fileId,
+ status: 'failed',
+ previewError: 'unexpected',
+ },
+ previewRevision ? { previewRevision } : undefined,
+ ).catch((updateErr) => {
+ logger.error(
+ `[runPreviewFinalize] also failed to mark ${fileId} as failed after error:`,
+ updateErr,
+ );
+ });
+ });
+};
+
+/**
+ * Process code execution output files — downloads and saves both images
+ * and non-image files. All files are saved to local storage with
+ * `fileIdentifier` metadata for code env re-upload.
+ *
+ * Returns a two-part shape so callers can ship the attachment to the
+ * client immediately and run preview extraction in the background:
+ * - `file`: persisted metadata (file is on disk, downloadable, and
+ * has `status: 'pending'` if a preview is still being rendered).
+ * - `finalize` (optional): a thunk returning the deferred preview
+ * result promise. Present only when an inline HTML preview is
+ * expected (office buckets — DOCX/XLSX/XLS/ODS/CSV/PPTX). Caller
+ * decides whether to await or fire-and-forget.
+ *
+ * Existing fallback paths (size limit, missing storage strategy, error
+ * catch) return `{ file }` with no `finalize` — there's nothing to
+ * extract.
+ *
* @param {ServerRequest} params.req - The Express request object.
* @param {string} params.id - The file ID from the code environment.
* @param {string} params.name - The filename.
@@ -78,7 +307,7 @@ const createDownloadFallback = ({
* @param {string} params.session_id - The code execution session ID.
* @param {string} params.conversationId - The current conversation ID.
* @param {string} params.messageId - The current message ID.
- * @returns {Promise<MongoFile & { messageId: string, toolCallId: string } | undefined>} The file metadata or undefined if an error occurs.
+ * @returns {Promise<{ file: MongoFile & { messageId: string, toolCallId: string }, finalize?: () => Promise<MongoFile | null> }>}
*/
const processCodeOutput = async ({
req,
@@ -123,15 +352,17 @@ const processCodeOutput = async ({
logger.warn(
`[processCodeOutput] File "${name}" (${(buffer.length / megabyte).toFixed(2)} MB) exceeds size limit of ${(fileSizeLimit / megabyte).toFixed(2)} MB, falling back to download URL`,
);
- return createDownloadFallback({
- id,
- name,
- messageId,
- toolCallId,
- session_id,
- conversationId,
- expiresAt: currentDate.getTime() + 86400000,
- });
+ return {
+ file: createDownloadFallback({
+ id,
+ name,
+ messageId,
+ toolCallId,
+ session_id,
+ conversationId,
+ expiresAt: currentDate.getTime() + 86400000,
+ }),
+ };
}
const fileIdentifier = `${session_id}/${id}`;
@@ -206,7 +437,7 @@ const processCodeOutput = async ({
metadata: { fileIdentifier },
};
await createFile(file, true);
- return Object.assign(file, { messageId, toolCallId });
+ return { file: Object.assign(file, { messageId, toolCallId }) };
}
const { saveBuffer } = getStrategyFunctions(appConfig.fileStrategy);
@@ -214,15 +445,17 @@ const processCodeOutput = async ({
logger.warn(
`[processCodeOutput] saveBuffer not available for strategy ${appConfig.fileStrategy}, falling back to download URL`,
);
- return createDownloadFallback({
- id,
- name,
- messageId,
- toolCallId,
- session_id,
- conversationId,
- expiresAt: currentDate.getTime() + 86400000,
- });
+ return {
+ file: createDownloadFallback({
+ id,
+ name,
+ messageId,
+ toolCallId,
+ session_id,
+ conversationId,
+ expiresAt: currentDate.getTime() + 86400000,
+ }),
+ };
}
const detectedType = await determineFileType(buffer, true);
@@ -271,18 +504,17 @@ const processCodeOutput = async ({
* what it would have gotten with the old flat-name flow. */
const leafName = path.basename(safeName);
const category = classifyCodeArtifact(leafName, mimeType);
- const text = await extractCodeArtifactText(buffer, leafName, mimeType, category);
- /* `textFormat` accompanies `text` so the client can gate
- * office-HTML-bucket routing on a trusted signal — clients MUST
- * NOT inject `text` into the iframe as HTML unless `textFormat ===
- * 'html'`. RAG-uploaded `.docx` etc. arrive with plain text from
- * mammoth.extractRawText and would otherwise be hijacked by the
- * extension-based office routing into the HTML-injection path
- * (Codex P1 review on PR #12934). null on extract failure — the
- * client treats absence as 'text' for safety. */
- const textFormat = getExtractedTextFormat(leafName, mimeType, text);
- const file = {
+ /* Office-bucket files (DOCX/XLSX/XLS/ODS/CSV/PPTX) route through
+ * `bufferToOfficeHtml` which is CPU-heavy. Persist the record now
+ * with `status: 'pending'` and `text: null` so the agent's response
+ * isn't blocked, then return a `finalize` thunk the caller can run
+ * in the background. Non-office files have cheap or no extraction
+ * — run it inline so the caller gets a fully-resolved record
+ * without juggling a finalize step. */
+ const expectsPreview = hasOfficeHtmlPath(leafName, mimeType);
+
+ const baseFile = {
file_id,
filepath,
messageId: persistedMessageId,
@@ -298,16 +530,70 @@ const processCodeOutput = async ({
context: FileContext.execute_code,
usage: isUpdate ? (claimed.usage ?? 0) + 1 : 1,
createdAt: isUpdate ? claimed.createdAt : formattedDate,
- // Always set `text` explicitly (string or null) so that an update which
- // produces a binary or oversized artifact clears any previously cached
- // text — `createFile` uses findOneAndUpdate with $set semantics, which
- // would otherwise leave a stale value behind.
+ };
+
+ if (expectsPreview) {
+ /* Persist with `status: 'pending'` and explicit
+ * `text: null` / `textFormat: null` so an update that previously
+ * had cached text gets cleared. The deferred finalize transitions
+ * to 'ready' (with text/textFormat) or 'failed' (with
+ * previewError).
+ *
+ * `previewRevision` is a fresh UUID stamped on every emit. The
+ * deferred finalize's `updateFile` is conditional on this — if
+ * a newer turn (cross-turn filename reuse) has rotated the
+ * revision before this render finishes, the stale render is
+ * silently discarded rather than overwriting the newer record.
+ * (Codex P1 review on PR #12957.) */
+ const previewRevision = v4();
+ const file = {
+ ...baseFile,
+ text: null,
+ textFormat: null,
+ status: 'pending',
+ previewError: null,
+ previewRevision,
+ };
+ await createFile(file, true);
+ return {
+ file: Object.assign(file, { messageId, toolCallId }),
+ finalize: () =>
+ finalizePreview({ buffer, leafName, mimeType, category, file_id, previewRevision }),
+ previewRevision,
+ };
+ }
+
+ /* Non-office path: extraction is cheap (utf8 decode, parseDocument
+ * for PDF/ODT, or null for binaries). Run inline and return a
+ * fully-resolved record — no `finalize` needed. */
+ const text = await extractCodeArtifactText(buffer, leafName, mimeType, category);
+ /* `textFormat` accompanies `text` so the client can gate
+ * office-HTML-bucket routing on a trusted signal — clients MUST
+ * NOT inject `text` into the iframe as HTML unless `textFormat ===
+ * 'html'`. RAG-uploaded `.docx` etc. arrive with plain text from
+ * mammoth.extractRawText and would otherwise be hijacked by the
+ * extension-based office routing into the HTML-injection path
+ * (Codex P1 review on PR #12934). null on extract failure — the
+ * client treats absence as 'text' for safety. */
+ const textFormat = getExtractedTextFormat(leafName, mimeType, text);
+ const file = {
+ ...baseFile,
+ // Always set explicitly so an update which produces a binary or
+ // oversized artifact clears any previously cached text — createFile
+ // uses findOneAndUpdate with $set semantics.
text: text ?? null,
textFormat: textFormat ?? null,
+ // Clear deferred-preview lifecycle fields in case the prior emit
+ // at this (filename, conversationId) was an office file —
+ // otherwise stale `pending`/`failed` would persist and the client
+ // would render the wrong state for the now non-office artifact.
+ status: null,
+ previewError: null,
+ previewRevision: null,
};
await createFile(file, true);
- return Object.assign(file, { messageId, toolCallId });
+ return { file: Object.assign(file, { messageId, toolCallId }) };
} catch (error) {
if (error?.message === 'Path traversal detected in filename') {
logger.warn(
@@ -320,15 +606,17 @@ const processCodeOutput = async ({
});
// Fallback for download errors - return download URL so user can still manually download
- return createDownloadFallback({
- id,
- name,
- messageId,
- toolCallId,
- session_id,
- conversationId,
- expiresAt: currentDate.getTime() + 86400000,
- });
+ return {
+ file: createDownloadFallback({
+ id,
+ name,
+ messageId,
+ toolCallId,
+ session_id,
+ conversationId,
+ expiresAt: currentDate.getTime() + 86400000,
+ }),
+ };
}
};
@@ -465,7 +753,23 @@ const primeFiles = async (options) => {
}
const entity_id = overrideEntityId ?? queryParams.entity_id;
- toolContext += `\n\t- /mnt/data/${file.filename}${fileSuffix}`;
+
+ /* Surface the preview lifecycle so the LLM knows when a
+ * prior-turn artifact's rich preview didn't materialize. The
+ * file blob is always available (`processCodeOutput` persists
+ * it before returning), so the model can still tell the user
+ * "you can download it" even when the preview never resolved.
+ * Absent status means legacy or non-office — render normally. */
+ let previewSuffix = '';
+ if (file.status === 'pending') {
+ previewSuffix = ' (preview not yet generated)';
+ } else if (file.status === 'failed') {
+ previewSuffix = file.previewError
+ ? ` (preview unavailable: ${file.previewError})`
+ : ' (preview unavailable)';
+ }
+
+ toolContext += `\n\t- /mnt/data/${file.filename}${fileSuffix}${previewSuffix}`;
files.push({
id: overrideId ?? id,
session_id: overrideSessionId ?? session_id,
@@ -624,4 +928,5 @@ module.exports = {
getSessionInfo,
processCodeOutput,
readSandboxFile,
+ runPreviewFinalize,
};
diff --git a/api/server/services/Files/Code/process.spec.js b/api/server/services/Files/Code/process.spec.js
index 8b12278c9a..98cbbf9fff 100644
--- a/api/server/services/Files/Code/process.spec.js
+++ b/api/server/services/Files/Code/process.spec.js
@@ -44,6 +44,15 @@ mockAxios.isAxiosError = jest.fn(() => false);
const mockClassifyCodeArtifact = jest.fn(() => 'other');
const mockExtractCodeArtifactText = jest.fn(async () => null);
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);
+/* 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', () => {
const http = require('http');
const https = require('https');
@@ -53,6 +62,8 @@ jest.mock('@librechat/api', () => {
sanitizeArtifactPath: jest.fn((name) => name),
flattenArtifactPath: jest.fn((name) => name.replace(/\//g, '__')),
createAxiosInstance: jest.fn(() => mockAxios),
+ withTimeout: (...args) => passthroughWithTimeout(...args),
+ hasOfficeHtmlPath: (...args) => mockHasOfficeHtmlPath(...args),
/**
* Arrow-function indirection (vs. a direct `jest.fn()` reference) so
* tests can per-case `mockReturnValueOnce` / `mockImplementationOnce`
@@ -178,7 +189,7 @@ describe('Code Process', () => {
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
- const result = await processCodeOutput(baseParams);
+ const { file: result } = await processCodeOutput(baseParams);
expect(mockClaimCodeFile).toHaveBeenCalledWith({
filename: 'test-file.txt',
@@ -201,7 +212,7 @@ describe('Code Process', () => {
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
- const result = await processCodeOutput(baseParams);
+ const { file: result } = await processCodeOutput(baseParams);
expect(result.file_id).toBe('mock-uuid-1234');
expect(result.usage).toBe(1);
@@ -221,7 +232,7 @@ describe('Code Process', () => {
};
convertImage.mockResolvedValue(convertedFile);
- const result = await processCodeOutput(imageParams);
+ const { file: result } = await processCodeOutput(imageParams);
expect(convertImage).toHaveBeenCalledWith(
mockReq,
@@ -246,7 +257,7 @@ describe('Code Process', () => {
mockAxios.mockResolvedValue({ data: imageBuffer });
convertImage.mockResolvedValue({ filepath: '/images/user-123/existing-img-id.webp' });
- const result = await processCodeOutput(imageParams);
+ const { file: result } = await processCodeOutput(imageParams);
expect(convertImage).toHaveBeenCalledWith(
mockReq,
@@ -272,7 +283,7 @@ describe('Code Process', () => {
getStrategyFunctions.mockReturnValue({ saveBuffer: mockSaveBuffer });
determineFileType.mockResolvedValue({ mime: 'text/plain' });
- const result = await processCodeOutput(baseParams);
+ const { file: result } = await processCodeOutput(baseParams);
expect(mockSaveBuffer).toHaveBeenCalledWith({
userId: 'user-123',
@@ -299,7 +310,7 @@ describe('Code Process', () => {
const mockSaveBuffer = jest.fn().mockResolvedValue('/uploads/saved.txt');
getStrategyFunctions.mockReturnValue({ saveBuffer: mockSaveBuffer });
- const result = await processCodeOutput({
+ const { file: result } = await processCodeOutput({
...baseParams,
name: 'test_folder/test_file.txt',
});
@@ -378,7 +389,7 @@ describe('Code Process', () => {
mockAxios.mockResolvedValue({ data: smallBuffer });
determineFileType.mockResolvedValue({ mime: 'application/pdf' });
- const result = await processCodeOutput({ ...baseParams, name: 'document.pdf' });
+ const { file: result } = await processCodeOutput({ ...baseParams, name: 'document.pdf' });
expect(determineFileType).toHaveBeenCalledWith(smallBuffer, true);
expect(result.type).toBe('application/pdf');
@@ -389,7 +400,7 @@ describe('Code Process', () => {
mockAxios.mockResolvedValue({ data: smallBuffer });
determineFileType.mockResolvedValue(null);
- const result = await processCodeOutput({ ...baseParams, name: 'unknown.xyz' });
+ const { file: result } = await processCodeOutput({ ...baseParams, name: 'unknown.xyz' });
expect(result.type).toBe('application/octet-stream');
});
@@ -403,7 +414,7 @@ describe('Code Process', () => {
mockClassifyCodeArtifact.mockReturnValueOnce('utf8-text');
mockExtractCodeArtifactText.mockResolvedValueOnce('hello world\n');
- const result = await processCodeOutput({ ...baseParams, name: 'note.txt' });
+ const { file: result } = await processCodeOutput({ ...baseParams, name: 'note.txt' });
expect(mockClassifyCodeArtifact).toHaveBeenCalledWith('note.txt', 'text/plain');
expect(mockExtractCodeArtifactText).toHaveBeenCalledWith(
@@ -426,7 +437,7 @@ describe('Code Process', () => {
mockClassifyCodeArtifact.mockReturnValueOnce('other');
mockExtractCodeArtifactText.mockResolvedValueOnce(null);
- const result = await processCodeOutput({ ...baseParams, name: 'archive.zip' });
+ const { file: result } = await processCodeOutput({ ...baseParams, name: 'archive.zip' });
expect(result.text).toBeNull();
const createCall = createFile.mock.calls[0][0];
@@ -465,6 +476,31 @@ describe('Code Process', () => {
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 = createFile.mock.calls[0][0];
+ expect(createCall).toHaveProperty('status', null);
+ expect(createCall).toHaveProperty('previewError', null);
+ expect(createCall).toHaveProperty('previewRevision', null);
+ });
});
describe('file size limit enforcement', () => {
@@ -475,7 +511,7 @@ describe('Code Process', () => {
const largeBuffer = Buffer.alloc(5000); // 5KB - exceeds 1KB limit
mockAxios.mockResolvedValue({ data: largeBuffer });
- const result = await processCodeOutput(baseParams);
+ const { file: result } = await processCodeOutput(baseParams);
expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('exceeds size limit'));
expect(result.filepath).toContain('/api/files/code/download/session-123/file-id-123');
@@ -494,7 +530,7 @@ describe('Code Process', () => {
mockAxios.mockResolvedValue({ data: smallBuffer });
getStrategyFunctions.mockReturnValue({ saveBuffer: null });
- const result = await processCodeOutput(baseParams);
+ const { file: result } = await processCodeOutput(baseParams);
expect(logger.warn).toHaveBeenCalledWith(
expect.stringContaining('saveBuffer not available'),
@@ -506,7 +542,7 @@ describe('Code Process', () => {
it('should fallback to download URL on axios error', async () => {
mockAxios.mockRejectedValue(new Error('Network error'));
- const result = await processCodeOutput(baseParams);
+ const { file: result } = await processCodeOutput(baseParams);
expect(result.filepath).toContain('/api/files/code/download/session-123/file-id-123');
expect(result.conversationId).toBe('conv-123');
@@ -520,7 +556,7 @@ describe('Code Process', () => {
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
- const result = await processCodeOutput(baseParams);
+ const { file: result } = await processCodeOutput(baseParams);
expect(result.usage).toBe(1);
});
@@ -534,7 +570,7 @@ describe('Code Process', () => {
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
- const result = await processCodeOutput(baseParams);
+ const { file: result } = await processCodeOutput(baseParams);
expect(result.usage).toBe(6);
});
@@ -547,7 +583,7 @@ describe('Code Process', () => {
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
- const result = await processCodeOutput(baseParams);
+ const { file: result } = await processCodeOutput(baseParams);
expect(result.usage).toBe(1);
});
@@ -558,7 +594,7 @@ describe('Code Process', () => {
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
- const result = await processCodeOutput(baseParams);
+ const { file: result } = await processCodeOutput(baseParams);
expect(result.metadata).toEqual({
fileIdentifier: 'session-123/file-id-123',
@@ -569,7 +605,7 @@ describe('Code Process', () => {
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
- const result = await processCodeOutput(baseParams);
+ const { file: result } = await processCodeOutput(baseParams);
expect(result.context).toBe(FileContext.execute_code);
});
@@ -578,7 +614,7 @@ describe('Code Process', () => {
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
- const result = await processCodeOutput(baseParams);
+ const { file: result } = await processCodeOutput(baseParams);
expect(result.toolCallId).toBe('tool-call-123');
expect(result.messageId).toBe('msg-123');
@@ -718,7 +754,7 @@ describe('Code Process', () => {
const smallBuffer = Buffer.alloc(100);
mockAxios.mockResolvedValue({ data: smallBuffer });
- const result = await processCodeOutput({
+ const { file: result } = await processCodeOutput({
...baseParams,
name: 'sentinel.txt',
messageId: 'turn-2-current-run-msg',
@@ -789,6 +825,329 @@ describe('Code Process', () => {
expect(callConfig.httpsAgent.keepAlive).toBe(false);
});
});
+
+ 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(createFile).toHaveBeenCalledWith(
+ expect.objectContaining({ status: 'pending', text: null, textFormat: null }),
+ true,
+ );
+ });
+
+ 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('readSandboxFile', () => {
@@ -1109,4 +1468,101 @@ describe('Code Process', () => {
);
});
});
+
+ describe('primeFiles toolContext surfaces preview status to the LLM', () => {
+ /* When a prior-turn code-execution file's HTML preview never resolved
+ * (still pending, or failed), the agent context for this turn must
+ * carry that signal so the model can tell the user "you can still
+ * download it, but the preview isn't available." Otherwise the model
+ * would refer to the file as if everything is fine and the user gets
+ * a confusing UI mismatch. */
+
+ 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: 'execute_code',
+ metadata: { fileIdentifier: 'CURRENT_SESSION/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('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');
+ });
+ });
});
diff --git a/client/src/components/Chat/Input/Files/FileContainer.tsx b/client/src/components/Chat/Input/Files/FileContainer.tsx
index a4b902fac4..551f477a84 100644
--- a/client/src/components/Chat/Input/Files/FileContainer.tsx
+++ b/client/src/components/Chat/Input/Files/FileContainer.tsx
@@ -1,3 +1,4 @@
+import type { ReactNode } from 'react';
import type { TFile } from 'librechat-data-provider';
import type { ExtendedFile } from '~/common';
import { getFileType, cn } from '~/utils';
@@ -8,6 +9,7 @@ const FileContainer = ({
file,
overrideType,
displayName,
+ subtitle,
buttonClassName,
containerClassName,
onDelete,
@@ -21,6 +23,15 @@ const FileContainer = ({
* persisted user files leave this undefined and render the raw filename.
*/
displayName?: string;
+ /**
+ * Optional override for the subtitle line (defaults to the file
+ * type's localized title — e.g. "PowerPoint Presentation"). Used by
+ * the deferred-preview flow to surface "Preparing preview…" /
+ * "Preview unavailable" inline within the chip rather than as a
+ * loose-feeling annotation below it. Pass a ReactNode so callers
+ * can include icons (spinner, alert) alongside the text.
+ */
+ subtitle?: ReactNode;
buttonClassName?: string;
containerClassName?: string;
onDelete?: () => void;
@@ -49,9 +60,13 @@ const FileContainer = ({
<div className="truncate font-medium" title={visibleName}>
{visibleName}
</div>
- <div className="truncate text-text-secondary" title={fileType.title}>
- {fileType.title}
- </div>
+ {subtitle != null ? (
+ subtitle
+ ) : (
+ <div className="truncate text-text-secondary" title={fileType.title}>
+ {fileType.title}
+ </div>
+ )}
</div>
</div>
</div>
diff --git a/client/src/components/Chat/Messages/Content/Parts/Attachment.tsx b/client/src/components/Chat/Messages/Content/Parts/Attachment.tsx
index 121f619847..65aa00ed1c 100644
--- a/client/src/components/Chat/Messages/Content/Parts/Attachment.tsx
+++ b/client/src/components/Chat/Messages/Content/Parts/Attachment.tsx
@@ -1,4 +1,5 @@
import { memo, useEffect, useId, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { Loader2, AlertCircle, Download } from 'lucide-react';
import { Tools } from 'librechat-data-provider';
import type { TAttachment, TFile, TAttachmentMetadata } from 'librechat-data-provider';
import type { ToolArtifactType } from '~/utils/artifacts';
@@ -12,17 +13,111 @@ import {
isTextAttachment,
renderAttachmentKey,
} from './attachmentTypes';
+import FilePreview from '~/components/Chat/Input/Files/FilePreview';
import FileContainer from '~/components/Chat/Input/Files/FileContainer';
import { fileToArtifact, TOOL_ARTIFACT_TYPES } from '~/utils/artifacts';
import Image from '~/components/Chat/Messages/Content/Image';
import ToolMermaidArtifact from './ToolMermaidArtifact';
import ToolArtifactCard from './ToolArtifactCard';
import { useAttachmentLink } from './LogLink';
-import { useLocalize } from '~/hooks';
-import { cn } from '~/utils';
+import { useLocalize, useAttachmentPreviewSync } from '~/hooks';
+import { cn, getFileType } from '~/utils';
const COLLAPSED_MAX_HEIGHT = 320;
+/**
+ * Card-shaped placeholder for a code-execution office file whose
+ * inline preview is still rendering (or failed). Visually mirrors
+ * `ToolArtifactCard`'s chrome — same rounded card, split body +
+ * download — so when the deferred render lands and the routing
+ * upgrades to the real `PanelArtifact` card the user sees a smooth
+ * transition between two card-shaped things, not a jarring jump from
+ * a small file chip to a big artifact card.
+ *
+ * The body is non-interactive while pending (there's no panel to
+ * open yet). On `'failed'` the body is also non-interactive — the
+ * download button is the only meaningful action since extraction
+ * never produced anything to render. Status reads via the spinner /
+ * alert subtitle inside the card, mirroring `ToolArtifactCard`'s
+ * "click to open" subtitle slot.
+ */
+const PreviewPlaceholderCard = memo(
+ ({
+ attachment,
+ status,
+ previewError,
+ }: {
+ attachment: Partial<TAttachment>;
+ status: 'pending' | 'failed';
+ previewError?: string;
+ }) => {
+ const localize = useLocalize();
+ const file = attachment as TFile & TAttachmentMetadata;
+ const { handleDownload } = useAttachmentLink({
+ href: attachment.filepath ?? '',
+ filename: attachment.filename ?? '',
+ file_id: file.file_id,
+ user: file.user,
+ source: file.source,
+ });
+ const fileType = getFileType('artifact');
+ const visibleFilename = displayFilename(attachment.filename);
+ const subtitleText =
+ status === 'pending'
+ ? localize('com_ui_preview_preparing')
+ : localize('com_ui_preview_failed');
+ return (
+ <div className="group relative my-2 inline-flex max-w-fit items-stretch gap-px overflow-hidden rounded-xl text-sm text-text-primary shadow-sm">
+ <div
+ aria-disabled="true"
+ aria-busy={status === 'pending'}
+ className="relative overflow-hidden rounded-l-xl border-border-light bg-surface-tertiary"
+ title={status === 'failed' ? (previewError ?? subtitleText) : undefined}
+ >
+ <div className="w-fit p-2">
+ <div className="flex flex-row items-center gap-2">
+ {/* Don't pass `file` here — it triggers `SourceIcon`'s
+ Terminal overlay for code-exec files (matches the
+ `metadata.fileIdentifier` marker), which is the
+ download-chip look. The artifact card doesn't show
+ that overlay; the placeholder shouldn't either, so
+ the pending→resolved transition is visually seamless. */}
+ <FilePreview fileType={fileType} className="relative" />
+ <div className="overflow-hidden text-left">
+ <div className="truncate font-medium" title={visibleFilename}>
+ {visibleFilename}
+ </div>
+ <div className="flex items-center gap-1.5 truncate text-xs text-text-secondary">
+ {status === 'pending' ? (
+ <Loader2 className="h-3 w-3 shrink-0 animate-spin" aria-hidden="true" />
+ ) : (
+ <AlertCircle className="h-3 w-3 shrink-0" aria-hidden="true" />
+ )}
+ <span className="truncate">{subtitleText}</span>
+ </div>
+ </div>
+ </div>
+ </div>
+ </div>
+ <button
+ type="button"
+ onClick={handleDownload}
+ aria-label={`${localize('com_ui_download')} ${visibleFilename}`}
+ title={localize('com_ui_download')}
+ className={cn(
+ 'flex shrink-0 items-center justify-center px-3 transition-colors duration-200',
+ 'rounded-r-xl bg-surface-tertiary text-text-secondary hover:bg-surface-hover hover:text-text-primary',
+ 'border-l border-border-light focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-border-heavy',
+ )}
+ >
+ <Download className="size-4" aria-hidden="true" />
+ </button>
+ </div>
+ );
+ },
+);
+PreviewPlaceholderCard.displayName = 'PreviewPlaceholderCard';
+
const FileAttachment = memo(({ attachment }: { attachment: Partial<TAttachment> }) => {
const [isVisible, setIsVisible] = useState(false);
const file = attachment as TFile & TAttachmentMetadata;
@@ -34,6 +129,13 @@ const FileAttachment = memo(({ attachment }: { attachment: Partial<TAttachment>
source: file.source,
});
const extension = attachment.filename?.split('.').pop();
+ /* Bridge the deferred-preview lifecycle: poll the backend for the
+ * resolved record while the file is still pending. The hook is a
+ * no-op for terminal states (legacy records, ready, failed
+ * already-known) so calling it unconditionally is cheap. */
+ const { status: previewStatus, previewError } = useAttachmentPreviewSync(
+ attachment as TAttachment,
+ );
useEffect(() => {
const timer = setTimeout(() => setIsVisible(true), 50);
@@ -43,6 +145,33 @@ const FileAttachment = memo(({ attachment }: { attachment: Partial<TAttachment>
if (!attachment.filepath) {
return null;
}
+ /* Pending or failed: render the card-shaped placeholder rather than
+ * the small file chip. Visual continuity with `ToolArtifactCard` so
+ * when the deferred render lands and the routing upgrades to
+ * `PanelArtifact`, the user sees a smooth card→card transition
+ * instead of a jump from "file download" to "artifact card". */
+ if (previewStatus === 'pending' || previewStatus === 'failed') {
+ return (
+ <div
+ className={cn(
+ 'file-attachment-container',
+ 'transition-all duration-300 ease-out',
+ isVisible ? 'translate-y-0 opacity-100' : 'translate-y-2 opacity-0',
+ )}
+ style={{
+ transformOrigin: 'center top',
+ willChange: 'opacity, transform',
+ WebkitFontSmoothing: 'subpixel-antialiased',
+ }}
+ >
+ <PreviewPlaceholderCard
+ attachment={attachment}
+ status={previewStatus}
+ previewError={previewError}
+ />
+ </div>
+ );
+ }
return (
<div
className={cn(
@@ -267,7 +396,11 @@ export function AttachmentGroup({ attachments }: { attachments?: TAttachment[] }
const fileAttachments: TAttachment[] = [];
const imageAttachments: TAttachment[] = [];
const textAttachments: TAttachment[] = [];
- const panelArtifacts: Array<{ attachment: TAttachment; type: ToolArtifactType }> = [];
+ /* Pending-preview chips share this row with their future selves —
+ * `type` is null while pending so the renderer falls back to
+ * FileAttachment (PreviewPlaceholderCard); on resolution it switches
+ * to PanelArtifact in place. */
+ const panelRow: Array<{ attachment: TAttachment; type: ToolArtifactType | null }> = [];
const mermaidArtifacts: TAttachment[] = [];
attachments.forEach((attachment) => {
@@ -281,13 +414,17 @@ export function AttachmentGroup({ attachments }: { attachments?: TAttachment[] }
imageAttachments.push(attachment);
return;
}
+ if ((attachment as Partial<TFile>).status === 'pending') {
+ panelRow.push({ attachment, type: null });
+ return;
+ }
const artType = artifactTypeForAttachment(attachment);
if (artType === TOOL_ARTIFACT_TYPES.MERMAID) {
mermaidArtifacts.push(attachment);
return;
}
if (artType != null) {
- panelArtifacts.push({ attachment, type: artType });
+ panelRow.push({ attachment, type: artType });
return;
}
if (isTextAttachment(attachment)) {
@@ -302,7 +439,13 @@ export function AttachmentGroup({ attachments }: { attachments?: TAttachment[] }
// engines (V8 ≥ 7.0) so equal-weight entries keep their input order.
fileAttachments.sort(bySalience);
textAttachments.sort(bySalience);
- panelArtifacts.sort(byEntrySalience);
+ /* Sort only the typed (resolved) entries; pending placeholders bubble
+ * to the end of the row so resolved siblings catch the eye first. */
+ const resolvedPanel = panelRow.filter(
+ (e): e is { attachment: TAttachment; type: ToolArtifactType } => e.type != null,
+ );
+ const pendingPanel = panelRow.filter((e) => e.type == null);
+ resolvedPanel.sort(byEntrySalience);
mermaidArtifacts.sort(bySalience);
imageAttachments.sort(bySalience);
@@ -320,15 +463,23 @@ export function AttachmentGroup({ attachments }: { attachments?: TAttachment[] }
)}
</div>
)}
- {panelArtifacts.length > 0 && (
+ {(resolvedPanel.length > 0 || pendingPanel.length > 0) && (
<div className="my-2 flex flex-wrap items-center gap-2">
- {panelArtifacts.map(({ attachment, type }, index) => (
+ {resolvedPanel.map(({ attachment, type }, index) => (
<PanelArtifact
attachment={attachment}
type={type}
key={renderAttachmentKey('artifact', attachment, index)}
/>
))}
+ {pendingPanel.map(({ attachment }, index) =>
+ attachment.filepath ? (
+ <FileAttachment
+ attachment={attachment}
+ key={renderAttachmentKey('pending', attachment, index)}
+ />
+ ) : null,
+ )}
</div>
)}
{mermaidArtifacts.length > 0 && (
diff --git a/client/src/components/Chat/Messages/Content/Parts/ToolArtifactCard.tsx b/client/src/components/Chat/Messages/Content/Parts/ToolArtifactCard.tsx
index 84125703cf..28349a7534 100644
--- a/client/src/components/Chat/Messages/Content/Parts/ToolArtifactCard.tsx
+++ b/client/src/components/Chat/Messages/Content/Parts/ToolArtifactCard.tsx
@@ -70,6 +70,8 @@ interface ToolArtifactCardProps {
const ToolArtifactCard = memo(({ attachment, artifact }: ToolArtifactCardProps) => {
const localize = useLocalize();
const claimKey = useId();
+ const file = attachment as TFile & TAttachmentMetadata;
+ const fileId = file.file_id;
const setVisible = useSetRecoilState(store.artifactsVisibility);
const setArtifacts = useSetRecoilState(store.artifactsState);
const setCurrentArtifactId = useSetRecoilState(store.currentArtifactId);
@@ -79,6 +81,22 @@ const ToolArtifactCard = memo(({ attachment, artifact }: ToolArtifactCardProps)
const [claim, setClaim] = useRecoilState(store.toolArtifactClaim(artifact.id));
const isSelected = artifact.id === currentArtifactId;
const isMyClaim = claim === claimKey;
+ /* Read+reset on mount only — `useRecoilCallback` avoids subscribing
+ * to the per-file_id flag (no re-renders when other files resolve).
+ * The deferred-preview hook flips this to `true` on the pending→ready
+ * edge; we consume it once and reset, so repeat mounts (panel close
+ * then reopen, history scroll) don't auto-open a second time. */
+ const consumeJustResolved = useRecoilCallback(
+ ({ snapshot, reset }) =>
+ (id: string) => {
+ const flagged = snapshot.getLoadable(store.previewJustResolved(id)).valueMaybe() ?? false;
+ if (flagged) {
+ reset(store.previewJustResolved(id));
+ }
+ return flagged;
+ },
+ [],
+ );
/**
* Captured at first render via a non-subscribing snapshot read so the
* downstream effect doesn't re-fire (and the component doesn't
@@ -136,11 +154,6 @@ const ToolArtifactCard = memo(({ attachment, artifact }: ToolArtifactCardProps)
}, [artifact, existingEntry, isMyClaim, setArtifacts]);
useEffect(() => {
- if (!mountedDuringStreamRef.current) {
- // Card mounted as part of conversation history — leave focus and
- // visibility alone so the side panel doesn't auto-open on navigation.
- return;
- }
if (isCodeOnlyArtifact(artifact.type)) {
// Source-code artifacts (`.py`, `.js`, `.cpp`, `Dockerfile`, …) are
// click-to-open only. They're typically supporting scripts the
@@ -151,16 +164,33 @@ const ToolArtifactCard = memo(({ attachment, artifact }: ToolArtifactCardProps)
// an HTML deliverable still surfaces immediately.
return;
}
- // Streaming arrival: focus the new artifact AND force the panel
- // visible. Without `setVisible(true)`, a session where the user had
- // previously closed the panel (visibility=false) would surface the
- // selection in the chip ("click to close") but never actually open
- // — `Presentation` gates rendering on visibility.
+ /* Two paths qualify the card for auto-open:
+ * 1. Streaming-time mount — ref captured `isSubmitting === true`
+ * at first render. The card is part of the live response, so
+ * the legacy "panel pops open as artifacts arrive" UX applies.
+ * 2. Just-resolved deferred preview — `useAttachmentPreviewSync`
+ * sets a one-shot flag on the pending→ready edge. The
+ * deferred render can complete *after* the SSE stream closes,
+ * so checking only `isSubmitting` would miss this case (the
+ * chip would render in place but never auto-open). Consuming
+ * the flag also resets it, so subsequent re-mounts (panel
+ * close/reopen, history scroll) do not re-steal focus.
+ * History mounts (file already resolved on page load) hit neither
+ * path, so the panel stays closed on navigation — no jarring
+ * auto-open just from scrolling past an old artifact. */
+ const justResolved = fileId ? consumeJustResolved(fileId) : false;
+ if (!mountedDuringStreamRef.current && !justResolved) {
+ return;
+ }
+ // Streaming arrival or just-resolved preview: focus the new artifact
+ // AND force the panel visible. Without `setVisible(true)`, a session
+ // where the user had previously closed the panel (visibility=false)
+ // would surface the selection in the chip ("click to close") but
+ // never actually open — `Presentation` gates rendering on visibility.
setCurrentArtifactId(artifact.id);
setVisible(true);
- }, [artifact.id, artifact.type, setCurrentArtifactId, setVisible]);
+ }, [artifact.id, artifact.type, fileId, consumeJustResolved, setCurrentArtifactId, setVisible]);
- const file = attachment as TFile & TAttachmentMetadata;
const { handleDownload } = useAttachmentLink({
href: attachment.filepath ?? '',
filename: attachment.filename ?? '',
diff --git a/client/src/components/Chat/Messages/Content/Parts/__tests__/ArtifactRouting.test.tsx b/client/src/components/Chat/Messages/Content/Parts/__tests__/ArtifactRouting.test.tsx
index 4b6c93ae92..ac9910bd0f 100644
--- a/client/src/components/Chat/Messages/Content/Parts/__tests__/ArtifactRouting.test.tsx
+++ b/client/src/components/Chat/Messages/Content/Parts/__tests__/ArtifactRouting.test.tsx
@@ -11,6 +11,11 @@ jest.mock('~/hooks', () => ({
() =>
(key: string): string =>
key,
+ /* `FileAttachment` calls this hook unconditionally to bridge the
+ * deferred-preview lifecycle into the attachment cache. The
+ * routing tests don't exercise the preview flow itself — stub it
+ * to a no-op so it doesn't blow up jsdom rendering. */
+ useAttachmentPreviewSync: () => ({ status: 'ready', previewError: undefined, isPolling: false }),
}));
jest.mock('../LogLink', () => ({
@@ -521,6 +526,106 @@ describe('ToolArtifactCard click behaviour', () => {
expect(snapshot.currentArtifactId).toBeNull();
});
+ it('auto-opens a non-streaming card when the deferred preview just resolved', () => {
+ /* Regression for the deferred-preview UX gap: when an office file's
+ * background HTML extraction lands AFTER the SSE stream has closed
+ * (`isSubmitting=false`), the freshly resolved chip would render in
+ * place but never auto-open the panel — the legacy auto-open path
+ * is gated only on streaming. `useAttachmentPreviewSync` flips the
+ * `previewJustResolved(file_id)` flag on the pending→ready edge to
+ * bridge that gap; `ToolArtifactCard` consumes it on mount and
+ * auto-opens regardless of submission state. The flag is one-shot:
+ * a subsequent re-mount (panel close/reopen, history scroll) must
+ * NOT fire again — covered by the next test. */
+ const xlsx = baseAttachment({
+ file_id: 'just-resolved-xlsx',
+ filename: 'data.xlsx',
+ type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+ text: '<table>resolved</table>',
+ textFormat: 'html',
+ } as Partial<TAttachment>);
+ const initializeState = (snap: MutableSnapshot) => {
+ snap.set(store.isSubmittingFamily(0), false);
+ snap.set(store.artifactsVisibility, false);
+ snap.set(store.previewJustResolved('just-resolved-xlsx'), true);
+ };
+ let snapshot: ArtifactsSnapshot = {
+ visibility: false,
+ currentArtifactId: null,
+ artifactIds: [],
+ };
+ render(
+ <RecoilRoot initializeState={initializeState}>
+ <StateProbe
+ onSnapshot={(snap) => {
+ snapshot = snap;
+ }}
+ />
+ <Attachment attachment={xlsx} />
+ </RecoilRoot>,
+ );
+ expect(snapshot.currentArtifactId).toBe('tool-artifact-just-resolved-xlsx');
+ expect(snapshot.visibility).toBe(true);
+ });
+
+ it('does NOT re-auto-open on a second mount after the just-resolved flag is consumed', () => {
+ /* The flag is one-shot — first card to mount consumes it. A second
+ * mount of the same file_id (panel close + reopen, history scroll
+ * onto the same card) must NOT re-steal focus, otherwise the user
+ * could never close the panel without it popping back open. */
+ const xlsx = baseAttachment({
+ file_id: 'one-shot-xlsx',
+ filename: 'data.xlsx',
+ type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+ text: '<table>resolved</table>',
+ textFormat: 'html',
+ } as Partial<TAttachment>);
+ const initializeState = (snap: MutableSnapshot) => {
+ snap.set(store.isSubmittingFamily(0), false);
+ snap.set(store.artifactsVisibility, false);
+ snap.set(store.previewJustResolved('one-shot-xlsx'), true);
+ };
+ let snapshot: ArtifactsSnapshot = {
+ visibility: false,
+ currentArtifactId: null,
+ artifactIds: [],
+ };
+ const { unmount } = render(
+ <RecoilRoot initializeState={initializeState}>
+ <StateProbe
+ onSnapshot={(snap) => {
+ snapshot = snap;
+ }}
+ />
+ <Attachment attachment={xlsx} />
+ </RecoilRoot>,
+ );
+ /* First mount auto-opened. Now simulate a fresh Recoil tree with the
+ * flag in the post-consume state (false) and assert the second
+ * mount stays closed. We use a fresh RecoilRoot to mirror what a
+ * real "panel was closed and the user then revealed the chip
+ * again" pathway would look like at the state level. */
+ unmount();
+ snapshot = { visibility: false, currentArtifactId: null, artifactIds: [] };
+ const secondInit = (snap: MutableSnapshot) => {
+ snap.set(store.isSubmittingFamily(0), false);
+ snap.set(store.artifactsVisibility, false);
+ // flag stays at default (false) — already consumed
+ };
+ render(
+ <RecoilRoot initializeState={secondInit}>
+ <StateProbe
+ onSnapshot={(snap) => {
+ snapshot = snap;
+ }}
+ />
+ <Attachment attachment={xlsx} />
+ </RecoilRoot>,
+ );
+ expect(snapshot.currentArtifactId).toBeNull();
+ expect(snapshot.visibility).toBe(false);
+ });
+
it('clicking a CODE artifact focuses it even though it skipped auto-open', () => {
// Counterpart to the streaming-CODE no-auto-open test: confirm the
// click path still surfaces a `.py` chip in the panel. Even on a
@@ -656,6 +761,40 @@ describe('AttachmentGroup routing', () => {
expect(chip?.textContent).toBe('.config.zip');
});
+ it('renders pending-preview chips in the panel-artifact row alongside resolved siblings', () => {
+ /* A pending preview is a future panel artifact — render it in the
+ * same row so when it resolves the chip stays put instead of
+ * jumping between rows. Plain files keep their own row. */
+ const attachments = [
+ baseAttachment({
+ file_id: 'resolved',
+ filename: 'index.html',
+ text: '<h1>hi</h1>',
+ } as Partial<TAttachment>),
+ baseAttachment({
+ file_id: 'pending-1',
+ filename: 'data.xlsx',
+ type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+ status: 'pending',
+ } as Partial<TAttachment>),
+ baseAttachment({
+ file_id: 'plain',
+ filename: 'archive.zip',
+ text: undefined as unknown as string,
+ } as Partial<TAttachment>),
+ ] as TAttachment[];
+
+ const { container } = renderWith(<AttachmentGroup attachments={attachments} />);
+
+ /* Two rows: file row (plain.zip) + panel row (resolved + pending). */
+ const rows = container.querySelectorAll('div.flex.flex-wrap');
+ expect(rows.length).toBe(2);
+ /* Resolved artifact card title visible. */
+ expect(screen.getByText('index.html')).toBeInTheDocument();
+ /* Pending placeholder is a FileContainer rendering. */
+ expect(screen.getAllByTestId('file-container').length).toBeGreaterThanOrEqual(1);
+ });
+
it('renders separate buckets for panel artifacts, mermaid, text, and plain files', () => {
const attachments = [
baseAttachment({
diff --git a/client/src/components/Chat/Messages/Content/Parts/__tests__/TextAttachment.test.tsx b/client/src/components/Chat/Messages/Content/Parts/__tests__/TextAttachment.test.tsx
index c5a8369796..f97c05d281 100644
--- a/client/src/components/Chat/Messages/Content/Parts/__tests__/TextAttachment.test.tsx
+++ b/client/src/components/Chat/Messages/Content/Parts/__tests__/TextAttachment.test.tsx
@@ -13,6 +13,10 @@ jest.mock('~/hooks', () => ({
};
return translations[key] ?? key;
},
+ /* `FileAttachment` calls this hook unconditionally to bridge the
+ * deferred-preview lifecycle. Stub to a no-op for tests that
+ * don't exercise the preview flow. */
+ useAttachmentPreviewSync: () => ({ status: 'ready', previewError: undefined, isPolling: false }),
}));
const mockHandleDownload = jest.fn();
diff --git a/client/src/data-provider/Files/__tests__/previewRefetchInterval.spec.ts b/client/src/data-provider/Files/__tests__/previewRefetchInterval.spec.ts
new file mode 100644
index 0000000000..b23d8f996d
--- /dev/null
+++ b/client/src/data-provider/Files/__tests__/previewRefetchInterval.spec.ts
@@ -0,0 +1,97 @@
+import type { TFilePreview } from 'librechat-data-provider';
+
+const mockGetFilePreview = jest.fn();
+jest.mock('librechat-data-provider', () => {
+ const actual = jest.requireActual('librechat-data-provider');
+ return {
+ ...actual,
+ dataService: {
+ ...actual.dataService,
+ getFilePreview: (...args: unknown[]) => mockGetFilePreview(...args),
+ },
+ };
+});
+
+import {
+ PREVIEW_MAX_CONSECUTIVE_ERRORS,
+ _resetPreviewErrorCounter,
+ fetchFilePreview,
+ previewRefetchInterval,
+} from '../queries';
+
+const q = (fileId: string) => ({ queryKey: ['filePreview' as const, fileId] });
+const FID = 'fid-test';
+
+beforeEach(() => {
+ _resetPreviewErrorCounter();
+ mockGetFilePreview.mockReset();
+});
+
+describe('previewRefetchInterval', () => {
+ it('polls every 2.5s when no data has arrived yet', () => {
+ expect(previewRefetchInterval(undefined, q(FID))).toBe(2500);
+ });
+
+ it('keeps polling while server reports pending', () => {
+ expect(previewRefetchInterval({ file_id: FID, status: 'pending' }, q(FID))).toBe(2500);
+ });
+
+ it('stops on terminal ready', () => {
+ const data: TFilePreview = {
+ file_id: FID,
+ status: 'ready',
+ text: 'x',
+ textFormat: 'html',
+ };
+ expect(previewRefetchInterval(data, q(FID))).toBe(false);
+ });
+
+ it('stops on terminal failed', () => {
+ const data: TFilePreview = { file_id: FID, status: 'failed', previewError: 'oops' };
+ expect(previewRefetchInterval(data, q(FID))).toBe(false);
+ });
+
+ it('keeps polling while consecutive errors are below the cap', async () => {
+ /* Regression for the bug where the counter relied on
+ * `query.state.fetchFailureCount`, which React Query v4 resets to
+ * 0 on every fetch dispatch — so the cap never fired and a broken
+ * endpoint polled forever. The counter now lives outside query
+ * state, incremented in the fetch wrapper. */
+ mockGetFilePreview.mockRejectedValue(new Error('500'));
+ for (let i = 0; i < PREVIEW_MAX_CONSECUTIVE_ERRORS - 1; i++) {
+ await expect(fetchFilePreview(FID)).rejects.toThrow();
+ expect(previewRefetchInterval(undefined, q(FID))).toBe(2500);
+ }
+ });
+
+ it('caps polling after MAX_CONSECUTIVE_ERRORS errors', async () => {
+ mockGetFilePreview.mockRejectedValue(new Error('500'));
+ for (let i = 0; i < PREVIEW_MAX_CONSECUTIVE_ERRORS; i++) {
+ await expect(fetchFilePreview(FID)).rejects.toThrow();
+ }
+ expect(previewRefetchInterval(undefined, q(FID))).toBe(false);
+ });
+
+ it('resets the error counter on a successful poll', async () => {
+ mockGetFilePreview.mockRejectedValueOnce(new Error('500'));
+ await expect(fetchFilePreview(FID)).rejects.toThrow();
+ mockGetFilePreview.mockResolvedValueOnce({ file_id: FID, status: 'pending' });
+ await fetchFilePreview(FID);
+ /* After a success, even an immediate cap-worth of new errors should
+ * be allowed before stopping again. */
+ mockGetFilePreview.mockRejectedValue(new Error('500'));
+ for (let i = 0; i < PREVIEW_MAX_CONSECUTIVE_ERRORS - 1; i++) {
+ await expect(fetchFilePreview(FID)).rejects.toThrow();
+ }
+ expect(previewRefetchInterval(undefined, q(FID))).toBe(2500);
+ });
+
+ it('tracks counters per file_id (one broken endpoint does not affect another)', async () => {
+ mockGetFilePreview.mockRejectedValue(new Error('500'));
+ for (let i = 0; i < PREVIEW_MAX_CONSECUTIVE_ERRORS; i++) {
+ await expect(fetchFilePreview('fid-broken')).rejects.toThrow();
+ }
+ expect(previewRefetchInterval(undefined, q('fid-broken'))).toBe(false);
+ expect(previewRefetchInterval(undefined, q('fid-healthy'))).toBe(2500);
+ });
+});
diff --git a/client/src/data-provider/Files/queries.ts b/client/src/data-provider/Files/queries.ts
index 9a213d5ad1..8502704676 100644
--- a/client/src/data-provider/Files/queries.ts
+++ b/client/src/data-provider/Files/queries.ts
@@ -105,3 +105,83 @@ export const useCodeOutputDownload = (url = ''): QueryObserverResult<string> =>
},
);
};
+
+/* Stop on terminal success or after 5 consecutive errors. The cap is
+ * tracked in a module-level Map keyed by file_id because React Query
+ * v4 resets `state.fetchFailureCount` to 0 on every fetch dispatch
+ * (the `'fetch'` action in the reducer), so it can't be used to count
+ * errors *across* polls. */
+export const PREVIEW_MAX_CONSECUTIVE_ERRORS = 5;
+const consecutivePreviewErrors = new Map<string, number>();
+
+export const fetchFilePreview = async (fileId: string): Promise<t.TFilePreview> => {
+ try {
+ const data = await dataService.getFilePreview(fileId);
+ consecutivePreviewErrors.delete(fileId);
+ return data;
+ } catch (err) {
+ consecutivePreviewErrors.set(fileId, (consecutivePreviewErrors.get(fileId) ?? 0) + 1);
+ throw err;
+ }
+};
+
+export const previewRefetchInterval = (
+ data: t.TFilePreview | undefined,
+ query: { queryKey: readonly unknown[] },
+): number | false => {
+ const fileId = String(query.queryKey[1] ?? '');
+ if (data?.status === 'ready' || data?.status === 'failed') {
+ consecutivePreviewErrors.delete(fileId);
+ return false;
+ }
+ if ((consecutivePreviewErrors.get(fileId) ?? 0) >= PREVIEW_MAX_CONSECUTIVE_ERRORS) {
+ consecutivePreviewErrors.delete(fileId);
+ return false;
+ }
+ return 2500;
+};
+
+/** Test-only: clear the consecutive-error counter. */
+export const _resetPreviewErrorCounter = (fileId?: string): void => {
+ if (fileId) consecutivePreviewErrors.delete(fileId);
+ else consecutivePreviewErrors.clear();
+};
+
+/**
+ * Poll the lifecycle of an inline file preview while background HTML
+ * extraction runs.
+ *
+ * Caller wires `enabled` to `attachment.status === 'pending'` so the
+ * query is dormant for terminal-status records. Once enabled, React
+ * Query's `refetchInterval` runs at 2.5s; see `previewRefetchInterval`
+ * for the auto-stop rules. Idle by default.
+ *
+ * Cache key: `[QueryKeys.filePreview, file_id]`. Sibling components
+ * watching the same `file_id` get a single shared poller.
+ */
+export const useFilePreview = (
+ file_id: string | undefined,
+ config?: UseQueryOptions<t.TFilePreview, unknown, t.TFilePreview>,
+): QueryObserverResult<t.TFilePreview, unknown> => {
+ return useQuery<t.TFilePreview, unknown, t.TFilePreview>(
+ [QueryKeys.filePreview, file_id],
+ () => fetchFilePreview(file_id ?? ''),
+ {
+ refetchOnWindowFocus: false,
+ refetchOnReconnect: false,
+ /* Note: `refetchOnMount` left at the React Query default (`true`)
+ * so a freshly-mounted observer with stale cached data refetches.
+ * Cross-turn filename reuse keeps the same `file_id`; the cache
+ * may hold a prior turn's `'ready'` payload. `useAttachmentHandler`
+ * removes the entry on every new attachment for safety, but this
+ * default is the second line of defense — without it, an observer
+ * that mounts before the handler runs would read the stale cache
+ * and `refetchInterval` would never start polling. (Codex P1
+ * round-3 review on PR #12957.) */
+ retry: false,
+ refetchInterval: previewRefetchInterval,
+ ...config,
+ enabled: !!file_id && (config?.enabled ?? true),
+ },
+ );
+};
diff --git a/client/src/hooks/Files/__tests__/useAttachmentPreviewSync.spec.tsx b/client/src/hooks/Files/__tests__/useAttachmentPreviewSync.spec.tsx
new file mode 100644
index 0000000000..096ec9fd83
--- /dev/null
+++ b/client/src/hooks/Files/__tests__/useAttachmentPreviewSync.spec.tsx
@@ -0,0 +1,442 @@
+/**
+ * Coverage for `useAttachmentPreviewSync` — the bridge between the
+ * deferred-preview code-execution lifecycle and the attachment cache.
+ *
+ * Behavior under test:
+ * 1. Polling enables only when `attachment.status === 'pending'` AND
+ * some conversation is submitting (per the user's explicit gate).
+ * 2. On a terminal poll response (ready/failed), the resolved record
+ * is upserted into `messageAttachmentsMap` by `file_id`.
+ * 3. The hook's returned `status` reflects the polled value once
+ * it arrives, not just the prop snapshot.
+ *
+ * The underlying `useFilePreview` hook is mocked here — its own
+ * polling cadence and refetchInterval semantics are React Query's
+ * concern, not this hook's.
+ */
+
+import { useEffect } from 'react';
+import { renderHook } from '@testing-library/react';
+import { RecoilRoot, useRecoilValue, useSetRecoilState } from 'recoil';
+import type { ReactNode } from 'react';
+import type { TAttachment, TFilePreview } from 'librechat-data-provider';
+import store from '~/store';
+
+const mockUseFilePreview = jest.fn();
+jest.mock('~/data-provider', () => ({
+ useFilePreview: (...args: unknown[]) => mockUseFilePreview(...args),
+}));
+
+import useAttachmentPreviewSync from '../useAttachmentPreviewSync';
+
+const wrapper = ({ children }: { children: ReactNode }) => <RecoilRoot>{children}</RecoilRoot>;
+
+const messageId = 'msg-1';
+const fileId = 'fid-1';
+
+function makeAttachment(overrides: Partial<TAttachment> = {}): TAttachment {
+ return {
+ file_id: fileId,
+ filename: 'data.xlsx',
+ filepath: '/uploads/data.xlsx',
+ type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+ messageId,
+ toolCallId: 'tc-1',
+ text: null,
+ textFormat: null,
+ status: 'pending',
+ ...overrides,
+ } as unknown as TAttachment;
+}
+
+/** Read messageAttachmentsMap and bridge it out via a mutable ref. */
+function setup({
+ attachment,
+ isSubmitting,
+ preview,
+ isFetching = false,
+ seedLiveMap = true,
+}: {
+ attachment: TAttachment;
+ isSubmitting: boolean;
+ preview?: TFilePreview;
+ isFetching?: boolean;
+ /* When false, simulates a loaded conversation: the message's
+ * attachments come from the DB but `messageAttachmentsMap[messageId]`
+ * is empty (no SSE handler ever fired for this messageId). The
+ * upsert must INSERT (not just update) the resolved record into the
+ * live map so the parent's `useAttachments` merge picks it up. */
+ seedLiveMap?: boolean;
+}) {
+ mockUseFilePreview.mockReset();
+ mockUseFilePreview.mockReturnValue({ data: preview, isFetching });
+ const ref: { current: Record<string, TAttachment[] | undefined> } = { current: {} };
+ let lastEnabled: boolean | undefined;
+ /* Spy on the second arg of useFilePreview to assert the gate. */
+ mockUseFilePreview.mockImplementation((_id: unknown, opts: { enabled?: boolean }) => {
+ lastEnabled = opts?.enabled;
+ return { data: preview, isFetching };
+ });
+
+ const Bridge = () => {
+ /* Seed the messageAttachmentsMap with the test attachment so the
+ * hook's upsert path has something to find. Also expose setters
+ * for tests that simulate `isAnySubmitting` toggling — the
+ * selector reads `conversationKeysAtom` × `isSubmittingFamily(key)`
+ * so we have to populate both for the selector to fire. */
+ const setMap = useSetRecoilState(store.messageAttachmentsMap);
+ const setKeys = useSetRecoilState(store.conversationKeysAtom);
+ const setSubmitting = useSetRecoilState(store.isSubmittingFamily(0));
+ useEffect(() => {
+ if (seedLiveMap) {
+ setMap({ [messageId]: [attachment] });
+ }
+ setKeys([0]);
+ setSubmitting(isSubmitting);
+ }, [setMap, setKeys, setSubmitting]);
+ const map = useRecoilValue(store.messageAttachmentsMap);
+ ref.current = map;
+ return null;
+ };
+
+ const { result } = renderHook(
+ () => {
+ return useAttachmentPreviewSync(attachment);
+ },
+ {
+ wrapper: ({ children }: { children: ReactNode }) =>
+ wrapper({
+ children: (
+ <>
+ <Bridge />
+ {children}
+ </>
+ ),
+ }),
+ },
+ );
+
+ return {
+ result,
+ get map() {
+ return ref.current;
+ },
+ get enabled() {
+ return lastEnabled;
+ },
+ };
+}
+
+/**
+ * Render the hook with controllable preview output (so a test can
+ * trigger the pending→ready edge by re-rendering with a new value)
+ * AND expose a snapshot read of the per-file_id `previewJustResolved`
+ * flag so the test can assert the hook flipped it on the edge.
+ *
+ * `isSubmittingAtMount` seeds `isSubmittingFamily(0)` *before* the hook
+ * runs (via `initializeState`) so the hook's mount-time snapshot read
+ * captures the intended value. Setting it after mount via a child
+ * effect would race with the hook's first render and the gate would
+ * see the default (`false`), defeating the whole point of the test.
+ */
+function setupWithTransitions(
+ initialPreview?: TFilePreview,
+ { isSubmittingAtMount = true }: { isSubmittingAtMount?: boolean } = {},
+) {
+ let currentPreview = initialPreview;
+ mockUseFilePreview.mockReset();
+ mockUseFilePreview.mockImplementation(() => ({
+ data: currentPreview,
+ isFetching: false,
+ }));
+
+ const flagRef: { current: boolean | undefined } = { current: undefined };
+ const FlagProbe = ({ id }: { id: string }) => {
+ /* Subscribing read — re-renders the probe whenever the flag flips,
+ * so `flagRef.current` is updated after the consumer hook commits
+ * the transition. (A non-subscribing snapshot read inside an
+ * effect would capture the value as of the previous commit, which
+ * misses the flag set fired in *this* render's effect tick.) */
+ const flag = useRecoilValue(store.previewJustResolved(id));
+ useEffect(() => {
+ flagRef.current = flag;
+ }, [flag]);
+ return null;
+ };
+
+ const { rerender } = renderHook(
+ ({ attachment }: { attachment: TAttachment }) => useAttachmentPreviewSync(attachment),
+ {
+ initialProps: { attachment: makeAttachment({ status: 'pending' }) },
+ wrapper: ({ children }: { children: ReactNode }) => (
+ <RecoilRoot
+ initializeState={(snap) => {
+ snap.set(store.isSubmittingFamily(0), isSubmittingAtMount);
+ }}
+ >
+ <FlagProbe id={fileId} />
+ {children}
+ </RecoilRoot>
+ ),
+ },
+ );
+
+ return {
+ setPreview: (preview: TFilePreview | undefined) => {
+ currentPreview = preview;
+ rerender({ attachment: makeAttachment({ status: 'pending' }) });
+ },
+ get justResolved() {
+ return flagRef.current;
+ },
+ };
+}
+
+describe('useAttachmentPreviewSync', () => {
+ it('enables polling whenever status=pending (no longer gated on isSubmitting)', () => {
+ const ctx = setup({
+ attachment: makeAttachment({ status: 'pending' }),
+ isSubmitting: true,
+ });
+ expect(ctx.enabled).toBe(true);
+ });
+
+ it('does NOT enable polling when status is already ready', () => {
+ const ctx = setup({
+ attachment: makeAttachment({ status: 'ready' }),
+ isSubmitting: true,
+ });
+ expect(ctx.enabled).toBe(false);
+ });
+
+ it('does NOT enable polling when status is already failed', () => {
+ const ctx = setup({
+ attachment: makeAttachment({ status: 'failed', previewError: 'timeout' }),
+ isSubmitting: true,
+ });
+ expect(ctx.enabled).toBe(false);
+ });
+
+ it('STILL enables polling for pending records even after the LLM has finished generating', () => {
+ /* Regression for the stuck-spinner bug: the deferred render can
+ * complete a few seconds AFTER the SSE stream closes. With the
+ * earlier `isAnySubmitting` gate, polling stopped the moment the
+ * model finished and the resolved-but-not-yet-emitted state would
+ * never reach the UI. Polling now runs on `status === 'pending'`
+ * alone; `useFilePreview`'s `refetchInterval` auto-stops on the
+ * first terminal response, and the server-side render ceiling +
+ * lazy sweep cap the worst case. */
+ const ctx = setup({
+ attachment: makeAttachment({ status: 'pending' }),
+ isSubmitting: false,
+ });
+ expect(ctx.enabled).toBe(true);
+ });
+
+ it('does NOT enable polling when the attachment has no file_id', () => {
+ const noId = { ...makeAttachment({ status: 'pending' }) } as Partial<TAttachment>;
+ delete (noId as { file_id?: string }).file_id;
+ const ctx = setup({
+ attachment: noId as TAttachment,
+ isSubmitting: true,
+ });
+ expect(ctx.enabled).toBe(false);
+ });
+
+ it('returns ready when no preview and no status (legacy back-compat)', () => {
+ const legacy = makeAttachment();
+ delete (legacy as Partial<TAttachment & { status?: string }>).status;
+ const ctx = setup({ attachment: legacy as TAttachment, isSubmitting: false });
+ expect(ctx.result.current.status).toBe('ready');
+ });
+
+ it('upserts the resolved preview into messageAttachmentsMap when preview reports ready', () => {
+ const ctx = setup({
+ attachment: makeAttachment({ status: 'pending' }),
+ isSubmitting: true,
+ preview: {
+ file_id: fileId,
+ status: 'ready',
+ text: '<table>final</table>',
+ textFormat: 'html',
+ },
+ });
+ const updated = ctx.map[messageId]?.[0] as TAttachment & { text?: string };
+ expect(updated.status).toBe('ready');
+ expect(updated.text).toBe('<table>final</table>');
+ expect(ctx.result.current.status).toBe('ready');
+ });
+
+ it('upserts the resolved preview when preview reports failed (with previewError)', () => {
+ const ctx = setup({
+ attachment: makeAttachment({ status: 'pending' }),
+ isSubmitting: true,
+ preview: {
+ file_id: fileId,
+ status: 'failed',
+ previewError: 'parser-error',
+ },
+ });
+ const updated = ctx.map[messageId]?.[0] as TAttachment & { previewError?: string };
+ expect(updated.status).toBe('failed');
+ expect(updated.previewError).toBe('parser-error');
+ expect(ctx.result.current.status).toBe('failed');
+ expect(ctx.result.current.previewError).toBe('parser-error');
+ });
+
+ it('does NOT upsert while the polled status is still pending', () => {
+ const ctx = setup({
+ attachment: makeAttachment({ status: 'pending' }),
+ isSubmitting: true,
+ preview: { file_id: fileId, status: 'pending' },
+ });
+ /* Map should be unchanged from the initial seed — no patch. */
+ const list = ctx.map[messageId] ?? [];
+ expect(list).toHaveLength(1);
+ expect((list[0] as TAttachment & { status?: string }).status).toBe('pending');
+ });
+
+ it('reports isPolling true when the query is fetching and the gate is open', () => {
+ const ctx = setup({
+ attachment: makeAttachment({ status: 'pending' }),
+ isSubmitting: true,
+ isFetching: true,
+ });
+ expect(ctx.result.current.isPolling).toBe(true);
+ });
+
+ it('reports isPolling false when the query is not fetching', () => {
+ const ctx = setup({
+ attachment: makeAttachment({ status: 'pending' }),
+ isSubmitting: true,
+ isFetching: false,
+ });
+ expect(ctx.result.current.isPolling).toBe(false);
+ });
+
+ it('INSERTS a new live entry when messageAttachmentsMap has no record for this file_id (loaded-conversation path)', () => {
+ /* Regression for the "DB-frozen pending" bug: on a reloaded
+ * conversation, messages come back from the DB with the
+ * immediate-persist snapshot (`status: 'pending'`) and there is no
+ * SSE handler running for the historical messageId — so
+ * `messageAttachmentsMap[messageId]` is empty. The polling layer
+ * must INSERT a new entry (not just update an existing one) so the
+ * parent's `useAttachments` merge can overlay the resolved
+ * lifecycle fields onto the DB attachment by file_id. */
+ const ctx = setup({
+ attachment: makeAttachment({ status: 'pending' }),
+ isSubmitting: false,
+ seedLiveMap: false,
+ preview: {
+ file_id: fileId,
+ status: 'ready',
+ text: '<table>resolved-on-reload</table>',
+ textFormat: 'html',
+ },
+ });
+ const list = ctx.map[messageId] ?? [];
+ expect(list).toHaveLength(1);
+ const inserted = list[0] as TAttachment & { text?: string; textFormat?: string };
+ expect(inserted.file_id).toBe(fileId);
+ expect(inserted.status).toBe('ready');
+ expect(inserted.text).toBe('<table>resolved-on-reload</table>');
+ expect(inserted.textFormat).toBe('html');
+ /* The inserted entry must carry forward the original attachment's
+ * non-lifecycle fields (filename, type, messageId, toolCallId) so
+ * the renderer can still classify it correctly. */
+ expect(inserted.filename).toBe('data.xlsx');
+ expect(inserted.messageId).toBe(messageId);
+ });
+
+ it('INSERTS a failed entry on a loaded conversation when polling reports failed', () => {
+ const ctx = setup({
+ attachment: makeAttachment({ status: 'pending' }),
+ isSubmitting: false,
+ seedLiveMap: false,
+ preview: {
+ file_id: fileId,
+ status: 'failed',
+ previewError: 'render-timeout',
+ },
+ });
+ const list = ctx.map[messageId] ?? [];
+ expect(list).toHaveLength(1);
+ const inserted = list[0] as TAttachment & { previewError?: string };
+ expect(inserted.status).toBe('failed');
+ expect(inserted.previewError).toBe('render-timeout');
+ });
+
+ describe('previewJustResolved signal (auto-open trigger)', () => {
+ /* The signal is the bridge to ToolArtifactCard's auto-open path:
+ * the card mounts after the routing re-runs (post-transition), so
+ * it can't observe the transition itself. Setting a one-shot flag
+ * keyed by file_id lets the card consume the signal on its very
+ * first effect tick. We assert on the flag directly here; the
+ * consume+open behavior lives in `ToolArtifactCard`'s coverage. */
+ it('flips the per-file_id flag on the pending→ready transition', () => {
+ const ctx = setupWithTransitions({ file_id: fileId, status: 'pending' });
+ expect(ctx.justResolved).toBe(false);
+ ctx.setPreview({
+ file_id: fileId,
+ status: 'ready',
+ text: '<table>x</table>',
+ textFormat: 'html',
+ });
+ expect(ctx.justResolved).toBe(true);
+ });
+
+ it('does NOT flip the flag when the polled status is "failed"', () => {
+ /* Failed previews stay as a download-only chip — nothing to
+ * auto-open. The signal must stay false so the eventual
+ * routing decision (PreviewPlaceholderCard with the alert
+ * subtitle) doesn't get hijacked into opening an empty panel. */
+ const ctx = setupWithTransitions({ file_id: fileId, status: 'pending' });
+ ctx.setPreview({
+ file_id: fileId,
+ status: 'failed',
+ previewError: 'render-timeout',
+ });
+ expect(ctx.justResolved).toBe(false);
+ });
+
+ it('does NOT flip the flag when the first observed status is already "ready" (history load)', () => {
+ /* A page-load mount where the file resolved long ago must not
+ * trigger auto-open — the user is scrolling through history,
+ * not awaiting a result. Without this guard, every loaded
+ * conversation would yank the panel open on first paint. */
+ const ctx = setupWithTransitions({
+ file_id: fileId,
+ status: 'ready',
+ text: '<table>x</table>',
+ textFormat: 'html',
+ });
+ expect(ctx.justResolved).toBe(false);
+ });
+
+ it('does NOT flip the flag on a navigation-time pending→ready (hook mounted with isSubmitting=false)', () => {
+ /* Regression for the "panel auto-opens on every revisit" bug:
+ * the immediate-persist snapshot saves the message's attachment
+ * at `status: 'pending'`, which never gets rewritten when the
+ * file record itself transitions to `'ready'`. When the user
+ * navigates back, the hook mounts with `isSubmitting=false`,
+ * polls once, and sees a pending→ready transition — but this
+ * is NOT a fresh resolution from the user's perspective, just
+ * polling catching up to long-resolved data. The
+ * `mountedDuringStreamRef` gate must drop this transition on
+ * the floor so the panel stays closed. The pre-PR commit
+ * history explicitly removed history-load auto-open; this
+ * preserves that contract. */
+ const ctx = setupWithTransitions(
+ { file_id: fileId, status: 'pending' },
+ { isSubmittingAtMount: false },
+ );
+ ctx.setPreview({
+ file_id: fileId,
+ status: 'ready',
+ text: '<table>resolved-on-revisit</table>',
+ textFormat: 'html',
+ });
+ expect(ctx.justResolved).toBe(false);
+ });
+ });
+});
diff --git a/client/src/hooks/Files/index.ts b/client/src/hooks/Files/index.ts
index 499572f0e0..7fa4df5a17 100644
--- a/client/src/hooks/Files/index.ts
+++ b/client/src/hooks/Files/index.ts
@@ -1,3 +1,4 @@
+export { default as useAttachmentPreviewSync } from './useAttachmentPreviewSync';
export { default as useDeleteFilesFromTable } from './useDeleteFilesFromTable';
export { default as useSetFilesToDelete } from './useSetFilesToDelete';
export { default as useFileHandling, useFileHandlingNoChatContext } from './useFileHandling';
diff --git a/client/src/hooks/Files/useAttachmentPreviewSync.ts b/client/src/hooks/Files/useAttachmentPreviewSync.ts
new file mode 100644
index 0000000000..d339118c20
--- /dev/null
+++ b/client/src/hooks/Files/useAttachmentPreviewSync.ts
@@ -0,0 +1,197 @@
+import { useEffect, useRef } from 'react';
+import { useRecoilCallback, useSetRecoilState } from 'recoil';
+import type { TAttachment, TFile, TFilePreview } from 'librechat-data-provider';
+import { useFilePreview } from '~/data-provider';
+import store from '~/store';
+
+interface UseAttachmentPreviewSyncResult {
+ /**
+ * Effective lifecycle status: `'pending'` while background HTML
+ * extraction is in flight, `'ready'` once it completes successfully
+ * (or for legacy / non-office files that never had a status), and
+ * `'failed'` when extraction errored or hit the 60s ceiling. Drives
+ * UI state (spinner, badge, etc.) without callers needing to read
+ * the attachment shape directly.
+ */
+ status: 'pending' | 'ready' | 'failed';
+ /** Short machine-readable failure reason from the backend. */
+ previewError?: string;
+ /** True while React Query is actively polling the preview endpoint. */
+ isPolling: boolean;
+}
+
+/**
+ * Bridge the deferred-preview code-execution lifecycle to the
+ * attachment cache.
+ *
+ * The immediate persist step (in callbacks.js + processCodeOutput)
+ * emits the attachment record at `status: 'pending'` so the agent's
+ * response stops blocking on extraction. The background render runs
+ * separately; if the SSE stream is still open when it lands, an
+ * `attachment` update event arrives and the SSE handler upserts by
+ * `file_id`. If the stream has already closed (the model finished
+ * generating before the render resolved), this hook covers the gap by
+ * polling `GET /api/files/:file_id/preview` and writing the resolved
+ * record back into `messageAttachmentsMap` — which triggers
+ * re-classification through `artifactTypeForAttachment`, so the file
+ * chip transitions from a plain download to the rich preview card
+ * (or to a download-with-error state) without remounting.
+ *
+ * Polling is gated on:
+ * - `attachment.file_id` present (no id → nothing to poll for)
+ * - Effective status is `'pending'` (terminal states need no work).
+ * `useFilePreview`'s `refetchInterval` returns `false` the moment
+ * the server reports `ready`/`failed`, so polling auto-terminates
+ * within one tick of resolution. Bounded ceiling: the server-side
+ * render timeout is 60s, so a stuck pending record gets ~24 polls
+ * max before the lazy sweep in the preview endpoint forces it to
+ * `'failed'`.
+ *
+ * NOTE: an earlier version of this hook also gated on `isAnySubmitting`
+ * (the LLM still generating). That gate was removed because the
+ * deferred render can complete *after* the SSE stream closes — when it
+ * does, the SSE update is silently dropped, and polling is the only
+ * recovery path. With the gate in place, the chip would stay stuck on
+ * "Preparing preview…" forever (until manual refresh) for any render
+ * that landed even seconds after submission ended. The polling itself
+ * doesn't block UX; the user can keep messaging regardless.
+ */
+export default function useAttachmentPreviewSync(
+ attachment: TAttachment | undefined,
+): UseAttachmentPreviewSyncResult {
+ const setAttachmentsMap = useSetRecoilState(store.messageAttachmentsMap);
+ /* `useRecoilCallback` reads/writes without subscribing this hook to
+ * the per-file_id flag — we only ever set it on the pending→ready
+ * edge, so subscribing would cause needless re-renders. */
+ const flagJustResolved = useRecoilCallback(
+ ({ set }) =>
+ (id: string) => {
+ set(store.previewJustResolved(id), true);
+ },
+ [],
+ );
+ /* Capture `isAnySubmitting` at first render via a non-subscribing
+ * snapshot read. Mirrors `ToolArtifactCard`'s `mountedDuringStreamRef`
+ * pattern so this hook applies the same "is the user actively in a
+ * turn?" classification as the card itself. The ref is the gate that
+ * distinguishes a *fresh* deferred-preview resolution (auto-open
+ * eligible) from a *stale* DB-pending record resolving on a history
+ * load (auto-open must NOT fire — the user is scrolling old data,
+ * not awaiting a result). Without this gate, navigating back to a
+ * conversation whose immediate-persist snapshot left the message's
+ * attachments at `status: 'pending'` would re-trigger auto-open
+ * every time the polling layer caught up — which is exactly the
+ * pre-PR "panel pops open on every visit" UX the team explicitly
+ * removed. */
+ const readInitialIsSubmitting = useRecoilCallback(
+ ({ snapshot }) =>
+ () =>
+ snapshot.getLoadable(store.isSubmittingFamily(0)).valueMaybe() ?? false,
+ [],
+ );
+ const mountedDuringStreamRef = useRef<boolean | null>(null);
+ if (mountedDuringStreamRef.current === null) {
+ mountedDuringStreamRef.current = readInitialIsSubmitting();
+ }
+
+ const file = (attachment ?? undefined) as Partial<TFile> | undefined;
+ const fileId = file?.file_id;
+ const baseStatus: 'pending' | 'ready' | 'failed' = file?.status ?? 'ready';
+ const messageId = (attachment as Partial<TAttachment> | undefined)?.messageId;
+
+ const enabled = !!fileId && baseStatus === 'pending';
+
+ const previewQuery = useFilePreview(fileId, { enabled });
+
+ /* Effective status: prefer the polled record once it arrives, since
+ * the SSE handler may have already moved the cache forward and the
+ * `attachment` prop will catch up on the next render anyway. */
+ const polled = previewQuery.data as TFilePreview | undefined;
+ const effectiveStatus: 'pending' | 'ready' | 'failed' = polled?.status ?? baseStatus;
+ const previewError = polled?.previewError ?? file?.previewError;
+
+ /* Track the previous effective status so we can fire the
+ * pending→ready edge exactly once per session. Two gates have to
+ * pass for the auto-open flag to flip:
+ * 1. We actually observed the transition (prev → curr).
+ * 2. The hook mounted during an active stream — i.e. the file is
+ * part of the user's current turn, not a history load. A
+ * page-navigation mount (or refresh) of a stale-pending DB
+ * record will see the same transition when polling catches
+ * up, but we must NOT auto-open in that case — the user is
+ * revisiting old work, not waiting on a fresh result.
+ * Refs are read inline so the effect doesn't have to list them as
+ * deps (mutating a ref doesn't subscribe). */
+ const prevStatusRef = useRef<'pending' | 'ready' | 'failed' | null>(null);
+ useEffect(() => {
+ const prev = prevStatusRef.current;
+ prevStatusRef.current = effectiveStatus;
+ if (
+ prev === 'pending' &&
+ effectiveStatus === 'ready' &&
+ fileId &&
+ mountedDuringStreamRef.current === true
+ ) {
+ flagJustResolved(fileId);
+ }
+ }, [effectiveStatus, fileId, flagJustResolved]);
+
+ /* On a terminal poll response (ready or failed), upsert into the
+ * shared attachments map. Mirrors the SSE handler's by-file_id
+ * upsert (`useAttachmentHandler`) — the attachment object is
+ * patched in place so siblings sharing the same atom re-render
+ * with the resolved data and `artifactTypeForAttachment` re-runs
+ * its empty-text gate, transitioning the file chip into a panel
+ * artifact card.
+ *
+ * Two paths:
+ * 1. Live SSE flow (active turn): the SSE handler already wrote
+ * the attachment into messageAttachmentsMap. `existingIndex`
+ * finds it; we patch in place.
+ * 2. Loaded conversation (no SSE): the message's `attachments`
+ * come from the DB (frozen at the immediate-persist state of
+ * `status: 'pending'`); messageAttachmentsMap is empty for
+ * this messageId. `existingIndex` is `-1`. We INSERT a new
+ * entry that overlays the polled fields onto the original
+ * `attachment` prop. `useAttachments` (the hook the renderer
+ * reads through) merges live entries onto DB entries by
+ * `file_id`, so the inserted entry takes precedence and the
+ * parent re-routes to the proper PanelArtifact card. */
+ useEffect(() => {
+ if (!polled || polled.status === 'pending' || !messageId || !fileId || !attachment) {
+ return;
+ }
+ setAttachmentsMap((prevMap) => {
+ const messageAttachments =
+ (prevMap as Record<string, TAttachment[] | undefined>)[messageId] || [];
+ const existingIndex = messageAttachments.findIndex(
+ (a) => (a as Partial<TFile>).file_id === fileId,
+ );
+ const resolvedFields = {
+ status: polled.status,
+ text: polled.text ?? null,
+ textFormat: polled.textFormat ?? null,
+ previewError: polled.previewError,
+ };
+ if (existingIndex >= 0) {
+ const existing = messageAttachments[existingIndex] as Partial<TFile> & TAttachment;
+ const merged = [...messageAttachments];
+ merged[existingIndex] = {
+ ...existing,
+ ...resolvedFields,
+ text: polled.text ?? existing.text ?? null,
+ textFormat: polled.textFormat ?? existing.textFormat ?? null,
+ } as TAttachment;
+ return { ...prevMap, [messageId]: merged };
+ }
+ const inserted = { ...attachment, ...resolvedFields } as TAttachment;
+ return { ...prevMap, [messageId]: [...messageAttachments, inserted] };
+ });
+ }, [polled, fileId, messageId, attachment, setAttachmentsMap]);
+
+ return {
+ status: effectiveStatus,
+ previewError,
+ isPolling: enabled && previewQuery.isFetching,
+ };
+}
diff --git a/client/src/hooks/Messages/__tests__/useAttachments.spec.tsx b/client/src/hooks/Messages/__tests__/useAttachments.spec.tsx
new file mode 100644
index 0000000000..61ce071728
--- /dev/null
+++ b/client/src/hooks/Messages/__tests__/useAttachments.spec.tsx
@@ -0,0 +1,129 @@
+/**
+ * Coverage for `useAttachments` — the merge layer that overlays live
+ * (SSE / poll-driven) attachment lifecycle fields onto DB-loaded
+ * attachments by `file_id`.
+ *
+ * The merge is the only thing that lets the deferred-preview flow
+ * recover on a reloaded conversation: messages persist with the
+ * immediate-snapshot `status: 'pending'`, but the file record itself
+ * resolves to `'ready'` later. Without the by-file_id overlay, the
+ * renderer would route through the plain file chip forever.
+ */
+
+import { useEffect } from 'react';
+import { renderHook } from '@testing-library/react';
+import { RecoilRoot, useSetRecoilState } from 'recoil';
+import type { ReactNode } from 'react';
+import type { TAttachment } from 'librechat-data-provider';
+import store from '~/store';
+
+jest.mock('~/hooks/useLocalize', () => () => (key: string) => key);
+
+import useAttachments from '../useAttachments';
+
+const messageId = 'msg-1';
+
+function makeAttachment(overrides: Partial<TAttachment> = {}): TAttachment {
+ return {
+ file_id: 'fid-1',
+ filename: 'data.xlsx',
+ filepath: '/uploads/data.xlsx',
+ type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+ messageId,
+ toolCallId: 'tc-1',
+ text: null,
+ textFormat: null,
+ status: 'pending',
+ ...overrides,
+ } as unknown as TAttachment;
+}
+
+function setup({
+ attachments,
+ liveMap,
+}: {
+ attachments?: TAttachment[];
+ liveMap?: Record<string, TAttachment[]>;
+}) {
+ const Seed = () => {
+ const setMap = useSetRecoilState(store.messageAttachmentsMap);
+ useEffect(() => {
+ if (liveMap) {
+ setMap(liveMap);
+ }
+ }, [setMap]);
+ return null;
+ };
+
+ return renderHook(() => useAttachments({ messageId, attachments }), {
+ wrapper: ({ children }: { children: ReactNode }) => (
+ <RecoilRoot>
+ <Seed />
+ {children}
+ </RecoilRoot>
+ ),
+ });
+}
+
+describe('useAttachments', () => {
+ it('returns DB attachments when no live entries exist', () => {
+ const db = makeAttachment({ status: 'pending' });
+ const { result } = setup({ attachments: [db] });
+ expect(result.current.attachments).toHaveLength(1);
+ expect(result.current.attachments[0]).toBe(db);
+ });
+
+ it('returns live entries when no DB attachments exist (active SSE turn)', () => {
+ const live = makeAttachment({ status: 'ready', text: '<table>x</table>' });
+ const { result } = setup({
+ attachments: undefined,
+ liveMap: { [messageId]: [live] },
+ });
+ expect(result.current.attachments).toHaveLength(1);
+ expect((result.current.attachments[0] as TAttachment & { text?: string }).text).toBe(
+ '<table>x</table>',
+ );
+ });
+
+ it('overlays live lifecycle fields onto matching DB attachment by file_id', () => {
+ /* This is the regression test for the stuck-pending bug on a
+ * reloaded conversation: the DB record was frozen at the
+ * immediate-persist snapshot; the polling layer fetched the
+ * resolved record and inserted it into messageAttachmentsMap; the
+ * merge here must surface the resolved fields to the renderer. */
+ const db = makeAttachment({ status: 'pending', text: null, textFormat: null });
+ const live = makeAttachment({
+ status: 'ready',
+ text: '<table>resolved</table>',
+ textFormat: 'html',
+ });
+ const { result } = setup({
+ attachments: [db],
+ liveMap: { [messageId]: [live] },
+ });
+ expect(result.current.attachments).toHaveLength(1);
+ const merged = result.current.attachments[0] as TAttachment & {
+ text?: string;
+ textFormat?: string;
+ };
+ expect(merged.status).toBe('ready');
+ expect(merged.text).toBe('<table>resolved</table>');
+ expect(merged.textFormat).toBe('html');
+ /* Non-lifecycle DB fields stay intact. */
+ expect(merged.filename).toBe('data.xlsx');
+ });
+
+ it('leaves DB attachments untouched when no live entry shares the file_id', () => {
+ const db = makeAttachment({ file_id: 'fid-A', status: 'pending' });
+ const live = makeAttachment({ file_id: 'fid-B', status: 'ready' });
+ const { result } = setup({
+ attachments: [db],
+ liveMap: { [messageId]: [live] },
+ });
+ /* DB attachments are the authoritative list for THIS message — a
+ * live entry without a matching file_id must NOT bleed in. */
+ expect(result.current.attachments).toHaveLength(1);
+ expect((result.current.attachments[0] as TAttachment).file_id).toBe('fid-A');
+ expect((result.current.attachments[0] as TAttachment).status).toBe('pending');
+ });
+});
diff --git a/client/src/hooks/Messages/useAttachments.ts b/client/src/hooks/Messages/useAttachments.ts
index de7910175f..09826d0205 100644
--- a/client/src/hooks/Messages/useAttachments.ts
+++ b/client/src/hooks/Messages/useAttachments.ts
@@ -1,6 +1,6 @@
import { useMemo } from 'react';
import { useRecoilValue } from 'recoil';
-import type { TAttachment } from 'librechat-data-provider';
+import type { TAttachment, TFile } from 'librechat-data-provider';
import { useSearchResultsByTurn } from './useSearchResultsByTurn';
import store from '~/store';
@@ -12,10 +12,43 @@ export default function useAttachments({
attachments?: TAttachment[];
}) {
const messageAttachmentsMap = useRecoilValue(store.messageAttachmentsMap);
- const messageAttachments = useMemo(
- () => attachments ?? messageAttachmentsMap[messageId ?? ''] ?? [],
- [attachments, messageAttachmentsMap, messageId],
- );
+ const messageAttachments = useMemo<TAttachment[]>(() => {
+ const live = messageAttachmentsMap[messageId ?? ''];
+ if (!attachments || attachments.length === 0) {
+ return live ?? [];
+ }
+ if (!live || live.length === 0) {
+ return attachments;
+ }
+ /* DB-loaded attachments are the source of truth for which
+ * attachments belong to this message, but live entries (from the
+ * SSE handler / `useAttachmentPreviewSync` polling) carry fresher
+ * lifecycle fields — `status`, `text`, `textFormat`,
+ * `previewError`. Without this merge, the deferred-preview flow
+ * would render "stuck pending" forever on a loaded conversation:
+ * the message saved to DB at end-of-run has the immediate-persist
+ * snapshot (`status: 'pending'`, `text: null`); the file record
+ * itself updates to `'ready'` later, but the message's
+ * `attachments` array doesn't get rewritten. Polling fetches the
+ * resolved record into `messageAttachmentsMap`; merging here lets
+ * `artifactTypeForAttachment` see the resolved text/textFormat
+ * and route through the proper PanelArtifact card. */
+ const liveByFileId = new Map<string, TAttachment>();
+ for (const a of live) {
+ const id = (a as Partial<TFile>).file_id;
+ if (id) {
+ liveByFileId.set(id, a);
+ }
+ }
+ return attachments.map((db) => {
+ const id = (db as Partial<TFile>).file_id;
+ if (!id) {
+ return db;
+ }
+ const liveEntry = liveByFileId.get(id);
+ return liveEntry ? ({ ...db, ...liveEntry } as TAttachment) : db;
+ });
+ }, [attachments, messageAttachmentsMap, messageId]);
const searchResults = useSearchResultsByTurn(messageAttachments);
diff --git a/client/src/hooks/SSE/__tests__/useAttachmentHandler.spec.tsx b/client/src/hooks/SSE/__tests__/useAttachmentHandler.spec.tsx
new file mode 100644
index 0000000000..5a4b68e79e
--- /dev/null
+++ b/client/src/hooks/SSE/__tests__/useAttachmentHandler.spec.tsx
@@ -0,0 +1,279 @@
+/**
+ * Coverage for the upsert-by-file_id behavior in `useAttachmentHandler`.
+ *
+ * Deferred-preview code-execution flow: the immediate persist step
+ * emits an attachment with `status: 'pending'`; the deferred render
+ * emits the same `file_id` again with `status: 'ready'` (and
+ * resolved `text`/`textFormat`) or `'failed'` (with `previewError`).
+ * The handler MUST merge over the pending placeholder in place —
+ * appending would render the artifact twice in the UI (once stuck
+ * pending, once resolved).
+ *
+ * Lightweight attachments without a `file_id` (web_search citations,
+ * file_search results) keep the legacy append-only behavior so two
+ * unrelated citations both show up.
+ */
+
+import { renderHook, act } from '@testing-library/react';
+import { RecoilRoot, useRecoilValue } from 'recoil';
+import { QueryClient } from '@tanstack/react-query';
+import { Tools } from 'librechat-data-provider';
+import type { ReactNode } from 'react';
+import type { TAttachment, EventSubmission } from 'librechat-data-provider';
+import useAttachmentHandler from '../useAttachmentHandler';
+import store from '~/store';
+
+const wrapper = ({ children }: { children: ReactNode }) => <RecoilRoot>{children}</RecoilRoot>;
+
+const submission = {} as EventSubmission;
+const messageId = 'msg-1';
+
+function makeAttachment(overrides: Partial<TAttachment>): TAttachment {
+ return {
+ file_id: 'fid-1',
+ filename: 'data.xlsx',
+ filepath: '/uploads/data.xlsx',
+ type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+ messageId,
+ toolCallId: 'tc-1',
+ text: null,
+ textFormat: null,
+ status: 'pending',
+ ...overrides,
+ } as unknown as TAttachment;
+}
+
+/* Co-mount the handler and a reader of the messageAttachmentsMap atom in
+ * the same RecoilRoot so each act() shows the post-write state. The
+ * `attachmentsMap` ref is mutated by the reader on every render, so
+ * callers read it after their `act()` to assert.
+ *
+ * Also exposes the underlying `queryClient` so tests can spy on
+ * `removeQueries` for the deferred-preview cache-staleness fix
+ * (Codex P1 review on PR #12957; round 3 swapped invalidate→remove). */
+function setup() {
+ const queryClient = new QueryClient();
+ const removeSpy = jest.spyOn(queryClient, 'removeQueries');
+ const ref: { current: Record<string, TAttachment[] | undefined> } = { current: {} };
+ const { result } = renderHook(
+ () => {
+ const handler = useAttachmentHandler(queryClient);
+ const map = useRecoilValue(store.messageAttachmentsMap);
+ ref.current = map;
+ return handler;
+ },
+ { wrapper },
+ );
+ return {
+ handle: (data: TAttachment) => act(() => result.current({ data, submission })),
+ get list(): TAttachment[] {
+ return ref.current[messageId] ?? [];
+ },
+ removeSpy,
+ };
+}
+
+describe('useAttachmentHandler upsert-by-file_id', () => {
+ it('appends a new attachment when no record with the same file_id exists', () => {
+ const ctx = setup();
+ ctx.handle(makeAttachment({ status: 'pending' }));
+ expect(ctx.list).toHaveLength(1);
+ expect(ctx.list[0]).toMatchObject({ file_id: 'fid-1', status: 'pending' });
+ });
+
+ it('upserts in place when a second event arrives for the same file_id (initial pending → deferred ready)', () => {
+ const ctx = setup();
+ ctx.handle(makeAttachment({ status: 'pending' }));
+ ctx.handle(makeAttachment({ status: 'ready', text: '<table></table>', textFormat: 'html' }));
+ /* Critical: still ONE attachment, not two. The deferred update
+ * patches the pending record in place. */
+ expect(ctx.list).toHaveLength(1);
+ expect(ctx.list[0]).toMatchObject({
+ file_id: 'fid-1',
+ status: 'ready',
+ text: '<table></table>',
+ textFormat: 'html',
+ });
+ });
+
+ it('upserts a failed deferred update over the pending placeholder', () => {
+ const ctx = setup();
+ ctx.handle(makeAttachment({ status: 'pending' }));
+ ctx.handle(makeAttachment({ status: 'failed', previewError: 'timeout' }));
+ expect(ctx.list).toHaveLength(1);
+ expect(ctx.list[0]).toMatchObject({ status: 'failed', previewError: 'timeout' });
+ });
+
+ it('keeps multiple distinct file_ids as separate entries', () => {
+ const ctx = setup();
+ ctx.handle(makeAttachment({ file_id: 'fid-A' }));
+ ctx.handle(makeAttachment({ file_id: 'fid-B' }));
+ expect(ctx.list).toHaveLength(2);
+ expect(ctx.list.map((a) => (a as { file_id: string }).file_id).sort()).toEqual([
+ 'fid-A',
+ 'fid-B',
+ ]);
+ });
+
+ it('appends (does NOT merge) attachments with no file_id', () => {
+ /* Lightweight attachments like file_search citations and web_search
+ * results don't carry file_id. The handler must keep its legacy
+ * append behavior for them — merging would lose distinct citations
+ * and is unnecessary because they're never the target of a
+ * deferred preview update. */
+ const ctx = setup();
+ const noFileId = {
+ messageId,
+ toolCallId: 'tc-1',
+ type: Tools.web_search,
+ } as unknown as TAttachment;
+ ctx.handle(noFileId);
+ ctx.handle(noFileId);
+ expect(ctx.list).toHaveLength(2);
+ });
+
+ it('preserves fields from the first event when the second omits them', () => {
+ /* The deferred preview update only carries the deltas (text, status,
+ * textFormat). Fields set in the initial emit (filename, type, etc.)
+ * must survive the merge — the second event uses spread-over-
+ * existing semantics. */
+ const ctx = setup();
+ ctx.handle(makeAttachment({ status: 'pending', filename: 'phase1-name.xlsx' }));
+ ctx.handle({
+ file_id: 'fid-1',
+ messageId,
+ status: 'ready',
+ text: 'final',
+ textFormat: 'html',
+ } as unknown as TAttachment);
+ expect(ctx.list).toHaveLength(1);
+ expect(ctx.list[0]).toMatchObject({
+ filename: 'phase1-name.xlsx',
+ status: 'ready',
+ text: 'final',
+ });
+ });
+
+ it('does NOT regress a resolved record when finalHandler replays the phase-1 snapshot', () => {
+ /* `useEventHandlers.finalHandler` iterates `responseMessage.attachments`
+ * at stream end — which is the immediate-persist snapshot
+ * (status:pending, text:null). If a deferred update has already
+ * moved this file_id to ready/failed, that replay must NOT
+ * downgrade it. Otherwise the chip flickers back to "pending" and
+ * polling restarts until the lazy sweep catches up. (Codex P1.) */
+ const ctx = setup();
+ ctx.handle(makeAttachment({ status: 'pending', text: null }));
+ ctx.handle({
+ file_id: 'fid-1',
+ messageId,
+ status: 'ready',
+ text: '<table>resolved</table>',
+ textFormat: 'html',
+ } as unknown as TAttachment);
+ /* Phase-1 replay arrives last (finalHandler at stream end). */
+ ctx.handle(makeAttachment({ status: 'pending', text: null }));
+ expect(ctx.list).toHaveLength(1);
+ expect(ctx.list[0]).toMatchObject({
+ status: 'ready',
+ text: '<table>resolved</table>',
+ textFormat: 'html',
+ });
+ });
+
+ it('does NOT regress a failed record when finalHandler replays the phase-1 snapshot', () => {
+ const ctx = setup();
+ ctx.handle(makeAttachment({ status: 'pending' }));
+ ctx.handle({
+ file_id: 'fid-1',
+ messageId,
+ status: 'failed',
+ previewError: 'parser-error',
+ } as unknown as TAttachment);
+ ctx.handle(makeAttachment({ status: 'pending' }));
+ expect(ctx.list[0]).toMatchObject({
+ status: 'failed',
+ previewError: 'parser-error',
+ });
+ });
+
+ describe('filePreview cache eviction (cross-turn filename reuse)', () => {
+ /* Cross-turn filename reuse keeps the same `file_id`. If a prior
+ * turn left `[QueryKeys.filePreview, file_id]` cached at
+ * `status: 'ready'`, a new pending attachment would mount against
+ * stale cache and `useFilePreview`'s polling (gated on `pending`)
+ * would never start.
+ *
+ * The handler uses `removeQueries` (not `invalidateQueries`) for
+ * this — invalidate alone only marks data stale, and the hook's
+ * default `refetchOnMount` semantics combined with the
+ * polling-gate-on-pending shape meant the new observer would still
+ * read the stale 'ready' cache and never trigger a fetch. Removing
+ * the entry forces a fresh server hit on next mount. (Codex P1
+ * round-3 review on PR #12957.) */
+
+ it('removes [QueryKeys.filePreview, file_id] when an attachment with a file_id arrives', () => {
+ const ctx = setup();
+ ctx.handle(makeAttachment({ status: 'pending' }));
+ expect(ctx.removeSpy).toHaveBeenCalledWith(['filePreview', 'fid-1']);
+ });
+
+ it('removes the same query key for the deferred preview update event too', () => {
+ /* Both the initial emit and the preview update should evict —
+ * the second event is itself the authoritative new state, but
+ * the upsert below races with the React Query cache and we want
+ * the next mount to start clean. */
+ const ctx = setup();
+ ctx.handle(makeAttachment({ status: 'pending' }));
+ ctx.handle(makeAttachment({ status: 'ready', text: '<table></table>', textFormat: 'html' }));
+ const previewEvictions = ctx.removeSpy.mock.calls.filter(
+ (c) => Array.isArray(c[0]) && c[0][0] === 'filePreview' && c[0][1] === 'fid-1',
+ );
+ expect(previewEvictions.length).toBe(2);
+ });
+
+ it('does not evict when the attachment carries no file_id', () => {
+ const ctx = setup();
+ const noFileId = {
+ messageId,
+ toolCallId: 'tc-1',
+ type: Tools.web_search,
+ } as unknown as TAttachment;
+ ctx.handle(noFileId);
+ const previewEvictions = ctx.removeSpy.mock.calls.filter(
+ (c) => Array.isArray(c[0]) && c[0][0] === 'filePreview',
+ );
+ expect(previewEvictions).toHaveLength(0);
+ });
+
+ it('does NOT use invalidateQueries (would leave stale cache readable per round-3 review)', () => {
+ /* Lock in the choice of `removeQueries` over `invalidateQueries`.
+ * Invalidate marks data stale but does not remove it; an
+ * observer reading a stale cache still gets the value back and
+ * the polling `refetchInterval` evaluates against stale 'ready'
+ * → returns false → polling never starts. removeQueries forces
+ * a refetch on next mount. */
+ const queryClient = new QueryClient();
+ const invalidateSpy = jest.spyOn(queryClient, 'invalidateQueries');
+ const removeSpy = jest.spyOn(queryClient, 'removeQueries');
+ const ref: { current: Record<string, TAttachment[] | undefined> } = { current: {} };
+ const { result } = renderHook(
+ () => {
+ const handler = useAttachmentHandler(queryClient);
+ const map = useRecoilValue(store.messageAttachmentsMap);
+ ref.current = map;
+ return handler;
+ },
+ { wrapper },
+ );
+ act(() => result.current({ data: makeAttachment({ status: 'pending' }), submission }));
+ const usedRemove = removeSpy.mock.calls.some(
+ (c) => Array.isArray(c[0]) && c[0][0] === 'filePreview',
+ );
+ const usedInvalidate = invalidateSpy.mock.calls.some(
+ (c) => Array.isArray(c[0]) && c[0][0] === 'filePreview',
+ );
+ expect(usedRemove).toBe(true);
+ expect(usedInvalidate).toBe(false);
+ });
+ });
+});
diff --git a/client/src/hooks/SSE/useAttachmentHandler.ts b/client/src/hooks/SSE/useAttachmentHandler.ts
index 06261f4af6..e24c9df068 100644
--- a/client/src/hooks/SSE/useAttachmentHandler.ts
+++ b/client/src/hooks/SSE/useAttachmentHandler.ts
@@ -15,6 +15,7 @@ export default function useAttachmentHandler(queryClient?: QueryClient) {
return ({ data }: { data: TAttachment; submission: EventSubmission }) => {
const { messageId } = data;
+ const fileId = (data as Partial<TFile>).file_id;
const fileData = data as TFile;
if (
@@ -49,9 +50,62 @@ export default function useAttachmentHandler(queryClient?: QueryClient) {
});
}
+ /* Cross-turn filename reuse keeps the same `file_id` across runs.
+ * If a prior turn left `[QueryKeys.filePreview, file_id]` cached at
+ * `status: 'ready'`, a new pending attachment would mount against
+ * that stale cache and `useFilePreview`'s `refetchInterval` (which
+ * only polls on `pending`) would never start. Drop the cache entry
+ * entirely so a fresh mount has nothing to read and must fetch.
+ *
+ * `removeQueries` (vs the earlier `invalidateQueries`) is the
+ * stronger fix: invalidate only marks data stale, but
+ * `refetchOnMount: false` was masking that — the new observer
+ * read the stale 'ready' value and `refetchInterval` shut polling
+ * off before it ever started. (Codex P1 round-3 review on
+ * PR #12957.) */
+ if (queryClient && fileId) {
+ queryClient.removeQueries([QueryKeys.filePreview, fileId]);
+ }
+
setAttachmentsMap((prevMap) => {
const messageAttachments =
(prevMap as Record<string, TAttachment[] | undefined>)[messageId] || [];
+ /* Upsert by `file_id` rather than always appending. The
+ * deferred-preview flow emits the same attachment twice: first
+ * with `status: 'pending'` and `text: null`, then again with
+ * `status: 'ready'` (and text/textFormat) or `'failed'` (with
+ * previewError). The second event must merge over the first in
+ * place — appending would render the artifact card twice, once
+ * stuck pending and once resolved. Attachments without a
+ * `file_id` (lightweight types like web_search / file_search
+ * citations) keep the legacy append behavior. */
+ if (fileId) {
+ const existingIndex = messageAttachments.findIndex(
+ (a) => (a as Partial<TFile>).file_id === fileId,
+ );
+ if (existingIndex > -1) {
+ const existing = messageAttachments[existingIndex] as Partial<TFile>;
+ const incoming = data as Partial<TFile>;
+ const next = { ...existing, ...data } as TAttachment;
+ /* Don't let a phase-1 replay (finalHandler iterates
+ * `responseMessage.attachments`, which is the immediate-persist
+ * snapshot at status:pending) regress a record a deferred
+ * update has already moved to ready/failed. Pin the terminal
+ * lifecycle fields when the merge would downgrade. */
+ if (
+ (existing.status === 'ready' || existing.status === 'failed') &&
+ incoming.status === 'pending'
+ ) {
+ (next as Partial<TFile>).status = existing.status;
+ (next as Partial<TFile>).text = existing.text;
+ (next as Partial<TFile>).textFormat = existing.textFormat;
+ (next as Partial<TFile>).previewError = existing.previewError;
+ }
+ const merged = [...messageAttachments];
+ merged[existingIndex] = next;
+ return { ...prevMap, [messageId]: merged };
+ }
+ }
return {
...prevMap,
[messageId]: [...messageAttachments, data],
diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.json
index 1299774c3a..81f513560c 100644
--- a/client/src/locales/en/translation.json
+++ b/client/src/locales/en/translation.json
@@ -1305,6 +1305,8 @@
"com_ui_prev": "Prev",
"com_ui_prev_result": "Previous result",
"com_ui_preview": "Preview",
+ "com_ui_preview_failed": "Preview unavailable",
+ "com_ui_preview_preparing": "Preparing preview…",
"com_ui_preview_unavailable": "Preview not available for this file type",
"com_ui_privacy_policy": "Privacy policy",
"com_ui_privacy_policy_url": "Privacy Policy URL",
diff --git a/client/src/store/artifacts.ts b/client/src/store/artifacts.ts
index 2222b3a1c0..a92844293a 100644
--- a/client/src/store/artifacts.ts
+++ b/client/src/store/artifacts.ts
@@ -88,6 +88,32 @@ export const artifactByIdSelector = selectorFamily<Artifact | undefined, string>
},
});
+/**
+ * One-shot signal that an attachment's deferred preview just transitioned
+ * from `pending` to `ready` during the current session — keyed by
+ * `file_id` (raw, NOT the `tool-artifact-${file_id}` form).
+ *
+ * The preview-sync hook flips this to `true` on the pending→ready edge.
+ * `ToolArtifactCard` reads it on mount; if set, it auto-opens the panel
+ * (even when no submission is in flight) and then resets the flag, so
+ * subsequent re-mounts (panel close/reopen, re-render of the same card
+ * from history) do not steal focus a second time.
+ *
+ * Why a separate signal rather than reusing `mountedDuringStreamRef`:
+ * the deferred render can complete *after* the SSE stream has closed,
+ * so the card mounts with `isSubmitting === false` and the existing
+ * focus/open path skips. Without this signal, a freshly resolved
+ * artifact would render in place but not auto-open — which is exactly
+ * the bug the deferred-preview flow was designed to mask in the first
+ * place. Auto-open ONLY on the pending→ready edge means a user
+ * scrolling through history doesn't get the panel popping open every
+ * time a previously resolved chip enters the viewport.
+ */
+export const previewJustResolved = atomFamily<boolean, string>({
+ key: 'previewJustResolved',
+ default: false,
+});
+
export const visibleArtifacts = atom<Record<string, Artifact | undefined> | null>({
key: 'visibleArtifacts',
default: null,
diff --git a/packages/api/src/files/code/extract.ts b/packages/api/src/files/code/extract.ts
index 85f9321d71..e49ad61ad6 100644
--- a/packages/api/src/files/code/extract.ts
+++ b/packages/api/src/files/code/extract.ts
@@ -39,8 +39,13 @@ const officeHtmlLimit = createConcurrencyLimiter(OFFICE_HTML_CONCURRENCY);
* (e.g. a tool emitting `data` with `text/csv`, which would otherwise
* classify as `utf8-text`, skip the office gate, and ship raw CSV text
* to the client's SPREADSHEET bucket that expects full HTML).
+ *
+ * Exported so `processCodeOutput`'s deferred-preview flow can decide
+ * whether to mark a freshly-persisted file record as `status:
+ * 'pending'` (preview expected later) or skip the status field
+ * entirely (no preview ever expected).
*/
-const hasOfficeHtmlPath = (name: string, mimeType: string): boolean =>
+export const hasOfficeHtmlPath = (name: string, mimeType: string): boolean =>
officeHtmlBucket(name, mimeType) !== null;
/**
diff --git a/packages/data-provider/src/api-endpoints.ts b/packages/data-provider/src/api-endpoints.ts
index 992d4a78a6..0a50f678d4 100644
--- a/packages/data-provider/src/api-endpoints.ts
+++ b/packages/data-provider/src/api-endpoints.ts
@@ -284,6 +284,11 @@ export const fileUpload = () => `${BASE_URL}/api/files`;
export const fileDelete = () => `${BASE_URL}/api/files`;
export const fileDownload = (userId: string, fileId: string) =>
`${BASE_URL}/api/files/download/${userId}/${fileId}`;
+/* Deferred-preview lifecycle endpoint. Returns
+ * `{ status, text?, textFormat?, previewError? }` so the frontend can
+ * poll while background HTML extraction is in flight. See PR #12957. */
+export const filePreview = (fileId: string) =>
+ `${BASE_URL}/api/files/${encodeURIComponent(fileId)}/preview`;
export const fileConfig = () => `${BASE_URL}/api/files/config`;
export const agentFiles = (agentId: string) => `${BASE_URL}/api/files/agent/${agentId}`;
diff --git a/packages/data-provider/src/data-service.ts b/packages/data-provider/src/data-service.ts
index 1e118c6f07..5c4dc8dfde 100644
--- a/packages/data-provider/src/data-service.ts
+++ b/packages/data-provider/src/data-service.ts
@@ -402,6 +402,22 @@ export const getFiles = (): Promise<f.TFile[]> => {
return request.get(endpoints.files());
};
+/**
+ * Poll the lifecycle of an inline file preview. Returns the smallest
+ * shape needed to drive the UI:
+ * - `status` always present (defaults to `'ready'` server-side for
+ * legacy records that pre-date the field).
+ * - `text` and `textFormat` only when `status === 'ready'` and text
+ * was extracted (preserves the HTML-or-null security contract).
+ * - `previewError` only when `status === 'failed'`.
+ *
+ * Called from `useFilePreview`; React Query's `refetchInterval`
+ * polls while `status === 'pending'` and stops on terminal status.
+ */
+export const getFilePreview = (fileId: string): Promise<f.TFilePreview> => {
+ return request.get(endpoints.filePreview(fileId));
+};
+
export const getAgentFiles = (agentId: string): Promise<f.TFile[]> => {
return request.get(endpoints.agentFiles(agentId));
};
diff --git a/packages/data-provider/src/keys.ts b/packages/data-provider/src/keys.ts
index 2200558cf1..36f4286617 100644
--- a/packages/data-provider/src/keys.ts
+++ b/packages/data-provider/src/keys.ts
@@ -34,6 +34,7 @@ export enum QueryKeys {
assistantDocs = 'assistantDocs',
agentDocs = 'agentDocs',
fileDownload = 'fileDownload',
+ filePreview = 'filePreview',
voices = 'voices',
customConfigSpeech = 'customConfigSpeech',
prompts = 'prompts',
diff --git a/packages/data-provider/src/types/files.ts b/packages/data-provider/src/types/files.ts
index 8168136685..c8f9621cc9 100644
--- a/packages/data-provider/src/types/files.ts
+++ b/packages/data-provider/src/types/files.ts
@@ -127,6 +127,20 @@ export type TFile = {
* See Codex P1 review on PR #12934.
*/
textFormat?: 'html' | 'text' | null;
+ /**
+ * Lifecycle of the inline preview rendered from `text`. `'pending'`
+ * while background HTML extraction is in flight (deferred-preview
+ * code-execution flow), `'ready'` once `text`/`textFormat` are set,
+ * `'failed'` if extraction errored or hit the 60s ceiling. `undefined`
+ * for legacy records and for files that never expect a preview —
+ * clients MUST treat that as `'ready'`.
+ */
+ status?: 'pending' | 'ready' | 'failed';
+ /**
+ * Short machine-readable failure reason when `status === 'failed'`.
+ * Suitable for tooltip text but not user-facing prose.
+ */
+ previewError?: string;
metadata?: { fileIdentifier?: string };
createdAt?: string | Date;
updatedAt?: string | Date;
@@ -136,6 +150,28 @@ export type TFileUpload = TFile & {
temp_file_id: string;
};
+/**
+ * Shape returned by `GET /api/files/:file_id/preview`. The deferred-
+ * preview code-execution flow polls this until status is terminal:
+ * - `pending`: HTML extraction is still running. No `text`.
+ * - `ready`: extraction succeeded; `text` + `textFormat` populated
+ * iff the file produced inline preview content (binary/oversized
+ * files reach `ready` with no text — render download-only).
+ * - `failed`: extraction errored or hit the 60s ceiling;
+ * `previewError` carries the short reason (`timeout`,
+ * `parser-error`, `orphaned`, etc.).
+ *
+ * Legacy records pre-dating the field are surfaced as `'ready'` server-
+ * side so existing attachments keep rendering normally.
+ */
+export type TFilePreview = {
+ file_id: string;
+ status: 'pending' | 'ready' | 'failed';
+ text?: string;
+ textFormat?: 'html' | 'text' | null;
+ previewError?: string;
+};
+
export type AvatarUploadResponse = {
url: string;
};
diff --git a/packages/data-schemas/src/methods/file.spec.ts b/packages/data-schemas/src/methods/file.spec.ts
index 390b6a8f5c..e8012feb5f 100644
--- a/packages/data-schemas/src/methods/file.spec.ts
+++ b/packages/data-schemas/src/methods/file.spec.ts
@@ -4,6 +4,8 @@ import { MongoMemoryServer } from 'mongodb-memory-server';
import { EToolResources, FileContext } from 'librechat-data-provider';
import { createFileMethods } from './file';
import { createModels } from '~/models';
+import { runAsSystem } from '~/config/tenantContext';
+import { _resetStrictCache } from '~/models/plugins/tenantIsolation';
let File: mongoose.Model<unknown>;
let fileMethods: ReturnType<typeof createFileMethods>;
@@ -256,6 +258,89 @@ describe('File Methods', () => {
expect(updated?.bytes).toBe(200);
expect(updated?.expiresAt).toBeUndefined();
});
+
+ /* The optional `extraFilter` enables conditional updates — used by
+ * the deferred-preview render's `finalizePreview` to guard against
+ * an older render of the same `file_id` overwriting a newer turn's
+ * record on cross-turn filename reuse. (Codex P1 review on PR
+ * #12957.) */
+ describe('extraFilter (conditional update)', () => {
+ it('commits when the extra filter matches the current document', async () => {
+ const fileId = uuidv4();
+ const userId = new mongoose.Types.ObjectId();
+ await fileMethods.createFile({
+ file_id: fileId,
+ user: userId,
+ filename: 'data.xlsx',
+ filepath: '/uploads/data.xlsx',
+ type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+ bytes: 100,
+ status: 'pending',
+ previewRevision: 'rev-A',
+ });
+
+ const updated = await fileMethods.updateFile(
+ { file_id: fileId, status: 'ready', text: '<table></table>' },
+ { previewRevision: 'rev-A' },
+ );
+
+ expect(updated).not.toBeNull();
+ expect(updated?.status).toBe('ready');
+ expect(updated?.text).toBe('<table></table>');
+ });
+
+ it('returns null and skips the write when the extra filter does NOT match', async () => {
+ const fileId = uuidv4();
+ const userId = new mongoose.Types.ObjectId();
+ await fileMethods.createFile({
+ file_id: fileId,
+ user: userId,
+ filename: 'data.xlsx',
+ filepath: '/uploads/data.xlsx',
+ type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+ bytes: 100,
+ status: 'pending',
+ previewRevision: 'rev-B', // newer turn has rotated the revision
+ });
+
+ /* An older render that started while revision was 'rev-A' tries
+ * to commit. The newer turn has since rotated to 'rev-B'. The
+ * conditional update silently no-ops. */
+ const updated = await fileMethods.updateFile(
+ { file_id: fileId, status: 'ready', text: '<stale/>' },
+ { previewRevision: 'rev-A' },
+ );
+
+ expect(updated).toBeNull();
+
+ /* Critical: the newer record's text MUST be untouched. */
+ const fresh = await fileMethods.findFileById(fileId);
+ expect(fresh?.previewRevision).toBe('rev-B');
+ expect(fresh?.status).toBe('pending');
+ expect(fresh?.text).toBeUndefined();
+ });
+
+ it('falls back to single-key update when extraFilter is omitted (back-compat)', async () => {
+ const fileId = uuidv4();
+ const userId = new mongoose.Types.ObjectId();
+ await fileMethods.createFile({
+ file_id: fileId,
+ user: userId,
+ filename: 'plain.txt',
+ filepath: '/uploads/plain.txt',
+ type: 'text/plain',
+ bytes: 50,
+ });
+
+ const updated = await fileMethods.updateFile({
+ file_id: fileId,
+ bytes: 99,
+ });
+
+ expect(updated).not.toBeNull();
+ expect(updated?.bytes).toBe(99);
+ });
+ });
});
describe('updateFileUsage', () => {
@@ -529,4 +614,133 @@ describe('File Methods', () => {
await expect(fileMethods.batchUpdateFiles([])).resolves.toBeUndefined();
});
});
+
+ describe('sweepOrphanedPreviews', () => {
+ /* The deferred-preview flow runs the deferred render in-process. If the
+ * backend restarts mid-extraction, records stay at `status: 'pending'`
+ * forever. The boot-time sweep transitions stale ones to 'failed'
+ * with `previewError: 'orphaned'` so the frontend stops polling. */
+ const userId = new mongoose.Types.ObjectId();
+
+ /**
+ * Stamp a precise `updatedAt` on a file record. Mongoose timestamps
+ * insist on the current time during create, so we backdate via a
+ * direct collection write afterwards.
+ */
+ async function makeFile(opts: {
+ ageMs: number;
+ status?: 'pending' | 'ready' | 'failed';
+ }): Promise<string> {
+ const fileId = uuidv4();
+ await fileMethods.createFile({
+ file_id: fileId,
+ user: userId,
+ filename: `${fileId}.xlsx`,
+ filepath: `/uploads/${fileId}.xlsx`,
+ type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+ bytes: 1024,
+ ...(opts.status ? { status: opts.status } : {}),
+ });
+ const backdated = new Date(Date.now() - opts.ageMs);
+ await File.collection.updateOne({ file_id: fileId }, { $set: { updatedAt: backdated } });
+ return fileId;
+ }
+
+ it('marks stale pending records as failed with previewError:orphaned', async () => {
+ const stale = await makeFile({ ageMs: 10 * 60 * 1000, status: 'pending' });
+ const fresh = await makeFile({ ageMs: 30 * 1000, status: 'pending' });
+
+ const count = await fileMethods.sweepOrphanedPreviews();
+ expect(count).toBe(1);
+
+ const staleAfter = (await fileMethods.findFileById(stale)) as {
+ status?: string;
+ previewError?: string;
+ } | null;
+ expect(staleAfter?.status).toBe('failed');
+ expect(staleAfter?.previewError).toBe('orphaned');
+
+ const freshAfter = (await fileMethods.findFileById(fresh)) as {
+ status?: string;
+ } | null;
+ expect(freshAfter?.status).toBe('pending');
+ });
+
+ it('does not touch records that are already ready or failed (idempotent)', async () => {
+ const ready = await makeFile({ ageMs: 60 * 60 * 1000, status: 'ready' });
+ const failed = await makeFile({ ageMs: 60 * 60 * 1000, status: 'failed' });
+
+ const count = await fileMethods.sweepOrphanedPreviews();
+ expect(count).toBe(0);
+
+ const readyAfter = (await fileMethods.findFileById(ready)) as { status?: string } | null;
+ const failedAfter = (await fileMethods.findFileById(failed)) as { status?: string } | null;
+ expect(readyAfter?.status).toBe('ready');
+ expect(failedAfter?.status).toBe('failed');
+ });
+
+ it('does not touch legacy records with no status field (back-compat)', async () => {
+ const legacy = await makeFile({ ageMs: 60 * 60 * 1000 }); // no status set
+ const count = await fileMethods.sweepOrphanedPreviews();
+ expect(count).toBe(0);
+ const after = (await fileMethods.findFileById(legacy)) as { status?: string } | null;
+ expect(after?.status).toBeUndefined();
+ });
+
+ it('respects a custom maxAgeMs cutoff', async () => {
+ const old10s = await makeFile({ ageMs: 10 * 1000, status: 'pending' });
+ const old1m = await makeFile({ ageMs: 60 * 1000, status: 'pending' });
+
+ // Cutoff = 30s — only the 60s-old record should be swept.
+ const count = await fileMethods.sweepOrphanedPreviews(30 * 1000);
+ expect(count).toBe(1);
+
+ const tenSecAfter = (await fileMethods.findFileById(old10s)) as { status?: string } | null;
+ const oneMinAfter = (await fileMethods.findFileById(old1m)) as {
+ status?: string;
+ previewError?: string;
+ } | null;
+ expect(tenSecAfter?.status).toBe('pending');
+ expect(oneMinAfter?.status).toBe('failed');
+ expect(oneMinAfter?.previewError).toBe('orphaned');
+ });
+
+ it('returns 0 when there are no stale pending records', async () => {
+ await makeFile({ ageMs: 30 * 1000, status: 'pending' });
+ const count = await fileMethods.sweepOrphanedPreviews();
+ expect(count).toBe(0);
+ });
+
+ describe('strict tenant isolation (boot-time recovery)', () => {
+ afterEach(() => {
+ delete process.env.TENANT_ISOLATION_STRICT;
+ _resetStrictCache();
+ });
+
+ it('throws under strict mode without runAsSystem', async () => {
+ await runAsSystem(() => makeFile({ ageMs: 10 * 60 * 1000, status: 'pending' }));
+ process.env.TENANT_ISOLATION_STRICT = 'true';
+ _resetStrictCache();
+ await expect(fileMethods.sweepOrphanedPreviews()).rejects.toThrow(
+ /Query attempted without tenant context in strict mode/,
+ );
+ });
+
+ it('succeeds under strict mode when wrapped in runAsSystem', async () => {
+ const stale = await runAsSystem(() =>
+ makeFile({ ageMs: 10 * 60 * 1000, status: 'pending' }),
+ );
+ process.env.TENANT_ISOLATION_STRICT = 'true';
+ _resetStrictCache();
+ const count = await runAsSystem(() => fileMethods.sweepOrphanedPreviews());
+ expect(count).toBe(1);
+ const after = (await runAsSystem(() => fileMethods.findFileById(stale))) as {
+ status?: string;
+ previewError?: string;
+ } | null;
+ expect(after?.status).toBe('failed');
+ expect(after?.previewError).toBe('orphaned');
+ });
+ });
+ });
});
diff --git a/packages/data-schemas/src/methods/file.ts b/packages/data-schemas/src/methods/file.ts
index 4c0969afb3..7393f4d78d 100644
--- a/packages/data-schemas/src/methods/file.ts
+++ b/packages/data-schemas/src/methods/file.ts
@@ -229,11 +229,24 @@ export function createFileMethods(mongoose: typeof import('mongoose')) {
/**
* Updates a file identified by file_id with new data and removes the TTL.
+ *
+ * `extraFilter` extends the by-id query with additional conditions
+ * (e.g. `{ previewRevision: '<expected uuid>' }`). When provided, the
+ * update is conditional — it commits only if the document still
+ * matches the extra filter, returning `null` otherwise. Used by the
+ * deferred-preview render to guard against an older render of the
+ * same `file_id` overwriting a newer turn's record on cross-turn
+ * filename reuse.
+ *
* @param data - The data to update, must contain file_id
- * @returns A promise that resolves to the updated file document
+ * @param extraFilter - Optional extra equality filter merged into the query.
+ * @returns A promise that resolves to the updated file document, or
+ * null if the conditional filter excluded it (or the file was
+ * deleted).
*/
async function updateFile(
data: Partial<IMongoFile> & { file_id: string },
+ extraFilter?: FilterQuery<IMongoFile>,
): Promise<IMongoFile | null> {
const File = mongoose.models.File as Model<IMongoFile>;
const { file_id, ...update } = data;
@@ -241,7 +254,8 @@ export function createFileMethods(mongoose: typeof import('mongoose')) {
$set: update,
$unset: { expiresAt: '' },
};
- return File.findOneAndUpdate({ file_id }, updateOperation, {
+ const query: FilterQuery<IMongoFile> = extraFilter ? { file_id, ...extraFilter } : { file_id };
+ return File.findOneAndUpdate(query, updateOperation, {
new: true,
}).lean();
}
@@ -368,6 +382,38 @@ export function createFileMethods(mongoose: typeof import('mongoose')) {
return results.filter((result): result is IMongoFile => result != null);
}
+ /**
+ * Mark stale `status: 'pending'` file records as `'failed'` with
+ * `previewError: 'orphaned'`. Recovers from the one case the
+ * in-process deferred-preview render can't handle on its own: a
+ * backend restart mid-render loses the in-memory promise, leaving
+ * the record stuck pending forever.
+ *
+ * Cheap to run on boot — the `status` field is indexed and the typical
+ * cutoff (5 min) bounds the candidate set to whatever was in flight at
+ * the prior shutdown. The 60s render timeout means anything older
+ * than a few minutes that's still pending is definitively orphaned.
+ *
+ * @param maxAgeMs - Cutoff in milliseconds; records whose `updatedAt`
+ * is older than `now - maxAgeMs` are marked failed. Defaults to 5
+ * minutes (well above the 60s render ceiling).
+ * @returns Number of records updated.
+ */
+ async function sweepOrphanedPreviews(maxAgeMs: number = 5 * 60 * 1000): Promise<number> {
+ const File = mongoose.models.File as Model<IMongoFile>;
+ const cutoff = new Date(Date.now() - maxAgeMs);
+ const result = await File.updateMany(
+ { status: 'pending', updatedAt: { $lt: cutoff } },
+ { $set: { status: 'failed', previewError: 'orphaned' } },
+ );
+ if (result.modifiedCount > 0) {
+ logger.info(
+ `[sweepOrphanedPreviews] Marked ${result.modifiedCount} stale 'pending' files as 'failed' (cutoff: ${cutoff.toISOString()})`,
+ );
+ }
+ return result.modifiedCount ?? 0;
+ }
+
return {
findFileById,
getFiles,
@@ -383,6 +429,7 @@ export function createFileMethods(mongoose: typeof import('mongoose')) {
deleteFileByFilter,
batchUpdateFiles,
updateFilesUsage,
+ sweepOrphanedPreviews,
};
}
diff --git a/packages/data-schemas/src/schema/file.ts b/packages/data-schemas/src/schema/file.ts
index 4098c83eb9..e9127dfd5f 100644
--- a/packages/data-schemas/src/schema/file.ts
+++ b/packages/data-schemas/src/schema/file.ts
@@ -64,6 +64,36 @@ const file: Schema<IMongoFile> = new Schema(
type: String,
enum: ['html', 'text'],
},
+ status: {
+ /* Deferred-preview code-execution flow: the immediate persist
+ * step writes the record with 'pending'; the background render
+ * (HTML extraction) updates to 'ready' or 'failed'. Absent on
+ * legacy records and on file kinds that never expect a preview. */
+ type: String,
+ enum: ['pending', 'ready', 'failed'],
+ index: true,
+ },
+ previewError: {
+ type: String,
+ /* Bounded to short machine-readable reasons (`'timeout'`,
+ * `'parser-error'`, `'orphaned'`, `'unexpected'`). Cap prevents a
+ * future codepath from accidentally persisting a stack trace or
+ * full error message — would bloat documents and ship a wall of
+ * text into the UI tooltip. */
+ maxlength: 200,
+ },
+ previewRevision: {
+ /* Generation marker for the deferred-preview lifecycle. Stamped
+ * by the immediate persist step on every emit (each new emit
+ * gets a fresh UUID); the deferred preview render's `updateFile`
+ * only commits when the marker still matches what it was when
+ * extraction started. Without this, two turns reusing the same
+ * `(filename, conversationId)` share a `file_id`, and an older
+ * render finishing after a newer one would silently overwrite
+ * the newer record with stale `text`/`status`. (Codex P1 review
+ * on PR #12957.) */
+ type: String,
+ },
context: {
type: String,
},
diff --git a/packages/data-schemas/src/types/file.ts b/packages/data-schemas/src/types/file.ts
index 9541d5abec..163980ca84 100644
--- a/packages/data-schemas/src/types/file.ts
+++ b/packages/data-schemas/src/types/file.ts
@@ -19,6 +19,35 @@ export interface IMongoFile extends Omit<Document, 'model'> {
* become executable markup. See Codex P1 review on PR #12934.
*/
textFormat?: 'html' | 'text';
+ /**
+ * Lifecycle of the inline preview rendered from `text`. Tracks the
+ * deferred-preview code-execution flow (PR #12951 follow-up): the
+ * immediate persist step saves the file blob and emits the attachment
+ * record with `status: 'pending'`; a background render runs HTML
+ * extraction and updates the record to `'ready'` (with `text` +
+ * `textFormat`) or `'failed'` (with `previewError`). Decouples the
+ * agent's final response from CPU-heavy office-format rendering.
+ *
+ * Absent for legacy records and for files that never expect a preview
+ * (RAG uploads, images, plain-text artifacts). Clients MUST treat
+ * `undefined` as `'ready'` so prior-version records render normally.
+ */
+ status?: 'pending' | 'ready' | 'failed';
+ /**
+ * Short machine-readable reason when `status === 'failed'` —
+ * `'timeout'`, `'parser-error'`, `'oversized'`, `'orphaned'`. UI hint
+ * for tooltip text; not user-facing prose. Absent otherwise.
+ */
+ previewError?: string;
+ /**
+ * Generation marker for the deferred-preview lifecycle. The
+ * immediate persist step stamps a fresh UUID on every emit; the
+ * deferred render's update only commits when the marker still
+ * matches. Guards against an older render overwriting a newer
+ * record on cross-turn filename reuse. Absent for legacy records
+ * and for files that never expect a preview.
+ */
+ previewRevision?: string;
filename: string;
filepath: string;
object: 'file';