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: Route Attachments and Provision Tools Lazily (#15763)

Danny Avilaec15075dc871
diff --git a/api/app/clients/BaseClient.js b/api/app/clients/BaseClient.js
index 72b716a9b4..05d1b7e714 100644
--- a/api/app/clients/BaseClient.js
+++ b/api/app/clients/BaseClient.js
@@ -38,6 +38,9 @@ const {
HITL_MESSAGE_FILTER_FIELDS,
getEndpointFileConfig,
stripReasoningLabelMetadata,
+ resolveUploadLLMDeliveryPath,
+ isSpeechProviderConfigured,
+ resolveUseResponsesApi,
} = require('librechat-data-provider');
const { getStrategyFunctions } = require('~/server/services/Files/strategies');
const { logViolation } = require('~/cache');
@@ -1720,6 +1723,16 @@ class BaseClient {
return await this.sendCompletion(payload, opts);
}
+ /** Whether this turn talks to the Responses API, which is what lets Azure carry a
+ * document natively. A saved agent holds it in its parameters and a plain conversation
+ * in its model options, and both readers of it have been wrong by consulting one. */
+ usesResponsesApi() {
+ return resolveUseResponsesApi(
+ this.options.agent?.model_parameters?.useResponsesApi,
+ this.modelOptions?.useResponsesApi,
+ );
+ }
+
async addDocuments(message, attachments) {
const documentResult = await encodeAndFormatDocuments(
this.options.req,
@@ -1727,7 +1740,7 @@ class BaseClient {
{
provider: this.options.agent?.provider ?? this.options.endpoint,
endpoint: this.options.agent?.endpoint ?? this.options.endpoint,
- useResponsesApi: this.options.agent?.model_parameters?.useResponsesApi,
+ useResponsesApi: this.usesResponsesApi(),
model: this.modelOptions?.model ?? this.model,
},
getStrategyFunctions,
@@ -1777,8 +1790,9 @@ class BaseClient {
* @returns {Promise<void>}
*/
async addFileContextToMessage(message, attachments) {
+ const textAttachments = this.getTextContextAttachments(attachments);
const fileContext = await extractFileContext({
- attachments,
+ attachments: textAttachments,
req: this.options?.req,
tokenCountFn: (text) => countTokens(text),
});
@@ -1788,6 +1802,44 @@ class BaseClient {
}
}
+ getTextContextAttachments(attachments) {
+ return attachments.filter((file) => {
+ const deliveryPath = this.getAttachmentDeliveryPath(file);
+ /* Records predating delivery paths keep legacy extraction. Current routing is
+ * authoritative for inferred uploads, so native provider bytes are not also
+ * injected as extracted text after a provider handoff. */
+ return deliveryPath == null || deliveryPath === 'text';
+ });
+ }
+
+ /** Re-resolves an inferred upload route against the provider handling this turn. */
+ getAttachmentDeliveryPath(file) {
+ if (!this._mergedFileConfig) {
+ this._mergedFileConfig = mergeFileConfig(this.options.req?.config?.fileConfig);
+ /* Agent file policy is configured under the endpoint it names, not the client
+ * family initialization may rewrite it to. */
+ const agentEndpoint = this.options.agent?.endpoint ?? this.options.agent?.provider;
+ this._deliveryEndpoint = agentEndpoint ?? this.options.endpoint;
+ this._endpointFileConfig = getEndpointFileConfig({
+ fileConfig: this._mergedFileConfig,
+ endpoint: this._deliveryEndpoint,
+ endpointType: agentEndpoint != null ? undefined : this.options.endpointType,
+ });
+ }
+
+ return file.llmDeliveryPath == null || file.metadata?.destinationChosen === true
+ ? file.llmDeliveryPath
+ : resolveUploadLLMDeliveryPath({
+ /* Conversion changes the stored type, so use the type routing originally saw. */
+ mimeType: file.metadata?.routingMimeType ?? file.type,
+ endpointConfig: this._endpointFileConfig,
+ fileConfig: this._mergedFileConfig,
+ endpoint: this._deliveryEndpoint,
+ useResponsesApi: this.usesResponsesApi(),
+ sttConfigured: isSpeechProviderConfigured(this.options.req?.config?.speech?.stt),
+ });
+ }
+
async processAttachments(message, attachments) {
const categorizedAttachments = {
images: [],
@@ -1797,20 +1849,14 @@ class BaseClient {
};
const allFiles = [];
-
const provider = this.options.agent?.provider ?? this.options.endpoint;
const isBedrock = provider === EModelEndpoint.bedrock;
- if (!this._mergedFileConfig) {
- this._mergedFileConfig = mergeFileConfig(this.options.req?.config?.fileConfig);
- const endpoint = this.options.agent?.endpoint ?? this.options.endpoint;
- this._endpointFileConfig = getEndpointFileConfig({
- fileConfig: this._mergedFileConfig,
- endpoint,
- endpointType: this.options.endpointType,
- });
- }
-
+ /* The stored path records what upload time inferred from the endpoint it saw, and this
+ * turn may be running somewhere else: audio stored as `provider` under Google reaches
+ * an encoder that emits nothing for OpenAI, delivering neither media nor text. An
+ * explicit chooser decision is the user's and survives, and a record predating the
+ * field keeps its legacy handling. */
for (const file of attachments) {
/** @type {FileSources} */
const source = file.source ?? FileSources.local;
@@ -1818,11 +1864,20 @@ class BaseClient {
allFiles.push(file);
continue;
}
+ const deliveryPath = this.getAttachmentDeliveryPath(file);
+ if (deliveryPath === 'text' || deliveryPath === 'none') {
+ allFiles.push(file);
+ continue;
+ }
+ /* An explicit `provider` path is authoritative: lazy provisioning stamps
+ * `embedded`/`codeEnvRef` on files that are still meant for the model, so the
+ * legacy tool-provisioning exclusion only applies to records without one. */
if (
- file.embedded === true ||
- file.metadata?.codeEnvRef != null ||
- file.metadata?.codeEnvRefs != null ||
- file.metadata?.fileIdentifier != null
+ deliveryPath !== 'provider' &&
+ (file.embedded === true ||
+ file.metadata?.codeEnvRef != null ||
+ file.metadata?.codeEnvRefs != null ||
+ file.metadata?.fileIdentifier != null)
) {
allFiles.push(file);
continue;
diff --git a/api/app/clients/specs/BaseClient.test.js b/api/app/clients/specs/BaseClient.test.js
index 9caa0a06b0..8f2bbbafee 100644
--- a/api/app/clients/specs/BaseClient.test.js
+++ b/api/app/clients/specs/BaseClient.test.js
@@ -1,4 +1,4 @@
-const { Constants, ContentTypes } = require('librechat-data-provider');
+const { Constants, ContentTypes, EModelEndpoint } = require('librechat-data-provider');
const BaseClientClass = require('../BaseClient');
const { ContentFilterError } = require('@librechat/api');
const { FakeClient, initializeFakeClient } = require('./FakeClient');
@@ -3106,6 +3106,400 @@ describe('BaseClient', () => {
]);
});
});
+
+ describe('processAttachments llmDeliveryPath handling', () => {
+ beforeEach(() => {
+ TestClient.options = {
+ endpoint: EModelEndpoint.openAI,
+ };
+ TestClient._mergedFileConfig = undefined;
+ TestClient._endpointFileConfig = undefined;
+ TestClient.addImageURLs = jest.fn(async (message, files) => {
+ message.image_urls = ['encoded-image'];
+ return files;
+ });
+ TestClient.addDocuments = jest.fn(async (message, files) => {
+ message.documents = [{ type: 'file' }];
+ return files;
+ });
+ TestClient.addVideos = jest.fn(async (_message, files) => files);
+ TestClient.modelOptions = undefined;
+ TestClient.addAudios = jest.fn(async (_message, files) => files);
+ });
+
+ /* The stored path is an upload-time inference, so delivery re-resolves it for the
+ * endpoint running the turn. A test asserting a route has to configure that route
+ * rather than rely on the stored value alone. */
+ const routeTo = (path, ...mimeTypes) => {
+ TestClient.options.req = {
+ config: {
+ fileConfig: {
+ endpoints: {
+ [EModelEndpoint.openAI]: {
+ defaultLLMDeliveryPath: {
+ overrides: Object.fromEntries(mimeTypes.map((mime) => [mime, path])),
+ },
+ },
+ },
+ },
+ },
+ };
+ TestClient._mergedFileConfig = undefined;
+ TestClient._endpointFileConfig = undefined;
+ };
+
+ test('keeps a none image in returned files without adding image URLs', async () => {
+ routeTo('none', 'image/*');
+ const message = {};
+ const file = {
+ user: 'user1',
+ file_id: 'none-image',
+ filename: 'image.png',
+ filepath: '/uploads/image.png',
+ type: 'image/png',
+ bytes: 100,
+ source: 'local',
+ llmDeliveryPath: 'none',
+ };
+
+ const result = await TestClient.processAttachments(message, [file]);
+
+ expect(result).toEqual([file]);
+ expect(message.image_urls).toBeUndefined();
+ expect(TestClient.addImageURLs).not.toHaveBeenCalled();
+ });
+
+ test('does not inject extracted text after the current provider resolves none', () => {
+ routeTo('none', 'application/pdf');
+ const file = {
+ file_id: 'none-pdf',
+ filename: 'report.pdf',
+ type: 'application/pdf',
+ llmDeliveryPath: 'text',
+ metadata: { destinationChosen: false },
+ };
+
+ expect(TestClient.getTextContextAttachments([file])).toEqual([]);
+ });
+
+ test('does not inject extracted text when the current provider resolves native delivery', () => {
+ routeTo('provider', 'application/pdf');
+ const file = {
+ file_id: 'provider-pdf',
+ filename: 'report.pdf',
+ type: 'application/pdf',
+ llmDeliveryPath: 'text',
+ metadata: { destinationChosen: false },
+ };
+
+ expect(TestClient.getTextContextAttachments([file])).toEqual([]);
+ });
+
+ test('re-resolves a path stored under a different provider', async () => {
+ /* Audio uploaded under Google stores `provider`, and the OpenAI encoder emits no
+ * audio payload for it, so the inference is not this endpoint's to honor.
+ *
+ * What this does not do is produce a transcript: the record holds raw media and no
+ * extracted text, and extraction at delivery is Phase 2 work. So the model receives
+ * nothing here either way, which the assertions state rather than imply, and the
+ * change is limited to not downloading and encoding a file to no purpose. */
+ routeTo('text', 'audio/*');
+ const message = {};
+ const file = {
+ user: 'user1',
+ file_id: 'foreign-audio',
+ filename: 'note.mp3',
+ filepath: '/uploads/note.mp3',
+ type: 'audio/mpeg',
+ bytes: 100,
+ source: 'local',
+ llmDeliveryPath: 'provider',
+ };
+
+ const result = await TestClient.processAttachments(message, [file]);
+
+ expect(result).toEqual([file]);
+ expect(TestClient.addAudios).not.toHaveBeenCalled();
+ expect(message.audios).toBeUndefined();
+ expect(file.text).toBeUndefined();
+ });
+
+ test('re-resolves a converted image against the type it was routed on', async () => {
+ /* Conversion rewrote the stored type, so resolving against that asks about a format
+ * the administrator never configured a route for and delivers what they excluded. */
+ routeTo('none', 'image/png');
+ const message = {};
+ const file = {
+ user: 'user1',
+ file_id: 'converted-image',
+ filename: 'photo.png',
+ filepath: '/uploads/photo.webp',
+ type: 'image/webp',
+ bytes: 100,
+ source: 'local',
+ llmDeliveryPath: 'none',
+ metadata: { routingMimeType: 'image/png' },
+ };
+
+ const result = await TestClient.processAttachments(message, [file]);
+
+ expect(result).toEqual([file]);
+ expect(TestClient.addImageURLs).not.toHaveBeenCalled();
+ });
+
+ test('reads the Responses setting from a plain conversation too', async () => {
+ /* A non-agent Azure chat carries it in model options, and reading only the agent
+ * parameters re-resolves a natively supported PDF to text, which the record has
+ * none of, so the model receives nothing. */
+ TestClient.options = {
+ endpoint: EModelEndpoint.azureOpenAI,
+ req: { config: { fileConfig: undefined } },
+ };
+ TestClient.modelOptions = { useResponsesApi: true };
+ TestClient._mergedFileConfig = undefined;
+ TestClient._endpointFileConfig = undefined;
+ const message = {};
+ const file = {
+ user: 'user1',
+ file_id: 'azure-pdf',
+ filename: 'doc.pdf',
+ filepath: '/uploads/doc.pdf',
+ type: 'application/pdf',
+ bytes: 100,
+ source: 'local',
+ llmDeliveryPath: 'provider',
+ };
+
+ await TestClient.processAttachments(message, [file]);
+
+ expect(TestClient.addDocuments).toHaveBeenCalled();
+ TestClient.modelOptions = undefined;
+ });
+
+ test('resolves a custom endpoint policy by the name the admin configured', async () => {
+ /* `initializeAgent` rewrites `agent.provider` to the client family a custom endpoint
+ * runs on, so resolving by it looks up `openAI` and silently loses every override
+ * written against the endpoint's own name. Upload routed under that name, and
+ * delivery has to agree or the file is stored and never sent. */
+ TestClient.options = {
+ endpoint: EModelEndpoint.agents,
+ endpointType: EModelEndpoint.agents,
+ agent: { provider: EModelEndpoint.openAI, endpoint: 'Mock Provider B' },
+ req: {
+ config: {
+ fileConfig: {
+ endpoints: {
+ 'Mock Provider B': {
+ defaultLLMDeliveryPath: { overrides: { 'image/*': 'none' } },
+ },
+ },
+ },
+ },
+ },
+ };
+ TestClient._mergedFileConfig = undefined;
+ TestClient._endpointFileConfig = undefined;
+ const message = {};
+ const file = {
+ user: 'user1',
+ file_id: 'custom-image',
+ filename: 'photo.png',
+ filepath: '/uploads/photo.png',
+ type: 'image/png',
+ bytes: 100,
+ source: 'local',
+ llmDeliveryPath: 'provider',
+ };
+
+ const result = await TestClient.processAttachments(message, [file]);
+
+ expect(result).toEqual([file]);
+ expect(TestClient.addImageURLs).not.toHaveBeenCalled();
+ });
+
+ test('resolves an agent policy by its own endpoint, not the agents container', async () => {
+ /* getEndpointFileConfig prefers endpointType, and an agents chat carries `agents`,
+ * so supplying it answers with the generic entry rather than the agent's.
+ * `initializeAgent` sets `agent.endpoint` from the agent's provider, so it names a
+ * configurable entry and never the container. */
+ TestClient.options = {
+ endpoint: EModelEndpoint.agents,
+ endpointType: EModelEndpoint.agents,
+ agent: { provider: EModelEndpoint.openAI, endpoint: EModelEndpoint.openAI },
+ req: {
+ config: {
+ fileConfig: {
+ endpoints: {
+ [EModelEndpoint.openAI]: {
+ defaultLLMDeliveryPath: { overrides: { 'image/*': 'none' } },
+ },
+ },
+ },
+ },
+ },
+ };
+ TestClient._mergedFileConfig = undefined;
+ TestClient._endpointFileConfig = undefined;
+ const message = {};
+ const file = {
+ user: 'user1',
+ file_id: 'agent-image',
+ filename: 'photo.png',
+ filepath: '/uploads/photo.png',
+ type: 'image/png',
+ bytes: 100,
+ source: 'local',
+ llmDeliveryPath: 'provider',
+ };
+
+ const result = await TestClient.processAttachments(message, [file]);
+
+ expect(result).toEqual([file]);
+ expect(TestClient.addImageURLs).not.toHaveBeenCalled();
+ });
+
+ test('keeps an explicitly named destination even under a different provider', async () => {
+ /* The user named this one, through the chooser or by requesting a tool resource,
+ * and that decision is not this endpoint's to re-derive. */
+ routeTo('text', 'audio/*');
+ const message = {};
+ const file = {
+ user: 'user1',
+ file_id: 'chosen-audio',
+ filename: 'note.mp3',
+ filepath: '/uploads/note.mp3',
+ type: 'audio/mpeg',
+ bytes: 100,
+ source: 'local',
+ llmDeliveryPath: 'provider',
+ metadata: { destinationChosen: true },
+ };
+
+ await TestClient.processAttachments(message, [file]);
+
+ expect(TestClient.addAudios).toHaveBeenCalled();
+ });
+
+ test('keeps a none PDF in returned files without adding documents', async () => {
+ routeTo('none', 'application/pdf');
+ const message = {};
+ const file = {
+ user: 'user1',
+ file_id: 'none-pdf',
+ filename: 'document.pdf',
+ filepath: '/uploads/document.pdf',
+ type: 'application/pdf',
+ bytes: 100,
+ source: 'local',
+ llmDeliveryPath: 'none',
+ };
+
+ const result = await TestClient.processAttachments(message, [file]);
+
+ expect(result).toEqual([file]);
+ expect(message.documents).toBeUndefined();
+ expect(TestClient.addDocuments).not.toHaveBeenCalled();
+ });
+
+ test('keeps a text-delivery markdown file in returned files without adding documents', async () => {
+ const message = {};
+ const file = {
+ user: 'user1',
+ file_id: 'text-markdown',
+ filename: 'notes.md',
+ filepath: '/uploads/notes.md',
+ type: 'text/markdown',
+ bytes: 100,
+ source: 'local',
+ text: 'extracted markdown',
+ llmDeliveryPath: 'text',
+ };
+
+ const result = await TestClient.processAttachments(message, [file]);
+
+ expect(result).toEqual([file]);
+ expect(message.documents).toBeUndefined();
+ expect(TestClient.addDocuments).not.toHaveBeenCalled();
+ });
+
+ test('still delivers a provider PDF that lazy provisioning marked embedded', async () => {
+ const message = {};
+ const file = {
+ user: 'user1',
+ file_id: 'provisioned-pdf',
+ filename: 'report.pdf',
+ filepath: '/uploads/report.pdf',
+ type: 'application/pdf',
+ bytes: 100,
+ source: 'local',
+ embedded: true,
+ llmDeliveryPath: 'provider',
+ };
+
+ await TestClient.processAttachments(message, [file]);
+
+ expect(TestClient.addDocuments).toHaveBeenCalled();
+ expect(message.documents).toEqual([{ type: 'file' }]);
+ });
+
+ test('still delivers a provider image that carries a codeEnvRef', async () => {
+ const message = {};
+ const file = {
+ user: 'user1',
+ file_id: 'provisioned-image',
+ filename: 'chart.png',
+ filepath: '/uploads/chart.png',
+ type: 'image/png',
+ bytes: 100,
+ source: 'local',
+ llmDeliveryPath: 'provider',
+ metadata: { codeEnvRef: { kind: 'user', id: 'u1' } },
+ };
+
+ await TestClient.processAttachments(message, [file]);
+
+ expect(TestClient.addImageURLs).toHaveBeenCalled();
+ expect(message.image_urls).toEqual(['encoded-image']);
+ });
+
+ test('keeps excluding embedded legacy files that have no delivery path', async () => {
+ const message = {};
+ const file = {
+ user: 'user1',
+ file_id: 'legacy-embedded',
+ filename: 'legacy.pdf',
+ filepath: '/uploads/legacy.pdf',
+ type: 'application/pdf',
+ bytes: 100,
+ source: 'local',
+ embedded: true,
+ };
+
+ const result = await TestClient.processAttachments(message, [file]);
+
+ expect(result).toEqual([file]);
+ expect(TestClient.addDocuments).not.toHaveBeenCalled();
+ });
+
+ test('routes legacy files without llmDeliveryPath normally', async () => {
+ const message = {};
+ const file = {
+ user: 'user1',
+ file_id: 'legacy-pdf',
+ filename: 'document.pdf',
+ filepath: '/uploads/document.pdf',
+ type: 'application/pdf',
+ bytes: 100,
+ source: 'local',
+ };
+
+ const result = await TestClient.processAttachments(message, [file]);
+
+ expect(result).toEqual([file]);
+ expect(message.documents).toEqual([{ type: 'file' }]);
+ expect(TestClient.addDocuments).toHaveBeenCalledWith(message, [file]);
+ });
+ });
});
describe('BaseClient compaction turns', () => {
diff --git a/api/server/controllers/agents/__tests__/openai.spec.js b/api/server/controllers/agents/__tests__/openai.spec.js
index 42be10e7f4..9986276e20 100644
--- a/api/server/controllers/agents/__tests__/openai.spec.js
+++ b/api/server/controllers/agents/__tests__/openai.spec.js
@@ -173,6 +173,8 @@ jest.mock('@librechat/agents', () => ({
}));
jest.mock('@librechat/api', () => ({
+ /* Provisioning moved into this package; the controllers build the callback from it. */
+ createProvisionFilesCallback: () => async () => {},
createAgentExecutionContext: (context) => context,
/** Grants both by default; the capability set is what these specs vary. */
resolveToolRoleGrants: jest.fn(async () => ({ runCode: true, fileSearch: true })),
diff --git a/api/server/controllers/agents/__tests__/responses.unit.spec.js b/api/server/controllers/agents/__tests__/responses.unit.spec.js
index 42c56f763e..a088e484bd 100644
--- a/api/server/controllers/agents/__tests__/responses.unit.spec.js
+++ b/api/server/controllers/agents/__tests__/responses.unit.spec.js
@@ -196,6 +196,8 @@ jest.mock('@librechat/agents', () => ({
}));
jest.mock('@librechat/api', () => ({
+ /* Provisioning moved into this package; the controllers build the callback from it. */
+ createProvisionFilesCallback: () => async () => {},
createAgentExecutionContext: (context) => context,
/** Grants both by default; the capability set is what these specs vary. */
resolveToolRoleGrants: jest.fn(async () => ({ runCode: true, fileSearch: true })),
diff --git a/api/server/controllers/agents/openai.js b/api/server/controllers/agents/openai.js
index 2a6c920fca..3fb6a213da 100644
--- a/api/server/controllers/agents/openai.js
+++ b/api/server/controllers/agents/openai.js
@@ -92,6 +92,8 @@ const {
resolveMemoryAvailability,
enrichLoadedToolsWithAgentContext,
} = require('~/server/services/Endpoints/agents/skillDeps');
+const { createProvisionFilesCallback } = require('~/server/services/Files/provisionCallback');
+const { checkSessionsAlive, loadCodeApiKey } = require('~/server/services/Files/provision');
const { getModelsConfig } = require('~/server/controllers/ModelController');
const { filterFilesByAgentAccess } = require('~/server/services/Files/permissions');
const { resolveConfigServers } = require('~/server/services/MCP');
@@ -482,6 +484,9 @@ const executeOpenAIChatCompletion = async (envelope, { req, res }) => {
updateFilesUsage: db.updateFilesUsage,
getUserKeyValues: db.getUserKeyValues,
getUserCodeFiles: db.getUserCodeFiles,
+ getDeferredProvisionFiles: db.getDeferredProvisionFiles,
+ checkSessionsAlive,
+ loadCodeApiKey,
getToolFilesByIds: db.getToolFilesByIds,
getCodeGeneratedFiles: db.getCodeGeneratedFiles,
listSkillsByAccess: skillDbMethods.listSkillsByAccess,
@@ -793,6 +798,11 @@ const executeOpenAIChatCompletion = async (envelope, { req, res }) => {
agent never gains sandbox access even if the admin enabled the
capability globally. */
const toolExecuteOptions = {
+ provisionFiles: createProvisionFilesCallback({
+ req,
+ agentToolContexts,
+ resolvePrimaryAgentId: () => primaryConfig.id,
+ }),
loadTools: async (toolNames, agentId, _configurable, callerCapabilityProjection) => {
const ctx =
agentToolContexts.get(agentId) ?? agentToolContexts.get(primaryConfig.id) ?? {};
diff --git a/api/server/controllers/agents/responses.js b/api/server/controllers/agents/responses.js
index 7b8ff642f6..fdcd93a372 100644
--- a/api/server/controllers/agents/responses.js
+++ b/api/server/controllers/agents/responses.js
@@ -107,6 +107,8 @@ const {
resolveMemoryAvailability,
enrichLoadedToolsWithAgentContext,
} = require('~/server/services/Endpoints/agents/skillDeps');
+const { createProvisionFilesCallback } = require('~/server/services/Files/provisionCallback');
+const { checkSessionsAlive, loadCodeApiKey } = require('~/server/services/Files/provision');
const { getModelsConfig } = require('~/server/controllers/ModelController');
const { filterFilesByAgentAccess } = require('~/server/services/Files/permissions');
const { resolveConfigServers, getAccessibleMcpServerNames } = require('~/server/services/MCP');
@@ -730,6 +732,9 @@ const executeResponse = async (envelope, { req, res }) => {
updateFilesUsage: db.updateFilesUsage,
getUserKeyValues: db.getUserKeyValues,
getUserCodeFiles: db.getUserCodeFiles,
+ getDeferredProvisionFiles: db.getDeferredProvisionFiles,
+ checkSessionsAlive,
+ loadCodeApiKey,
getToolFilesByIds: db.getToolFilesByIds,
getCodeGeneratedFiles: db.getCodeGeneratedFiles,
listSkillsByAccess: skillDbMethods.listSkillsByAccess,
@@ -1134,6 +1139,11 @@ const executeResponse = async (envelope, { req, res }) => {
// Create tool execute options for event-driven tool execution
const toolExecuteOptions = {
+ provisionFiles: createProvisionFilesCallback({
+ req,
+ agentToolContexts,
+ resolvePrimaryAgentId: () => primaryConfig.id,
+ }),
loadTools: async (toolNames, agentId, _configurable, callerCapabilityProjection) => {
const ctx =
agentToolContexts.get(agentId) ?? agentToolContexts.get(primaryConfig.id) ?? {};
@@ -1349,6 +1359,11 @@ const executeResponse = async (envelope, { req, res }) => {
});
const toolExecuteOptions = {
+ provisionFiles: createProvisionFilesCallback({
+ req,
+ agentToolContexts,
+ resolvePrimaryAgentId: () => primaryConfig.id,
+ }),
loadTools: async (toolNames, agentId, _configurable, callerCapabilityProjection) => {
const ctx =
agentToolContexts.get(agentId) ?? agentToolContexts.get(primaryConfig.id) ?? {};
diff --git a/api/server/index.js b/api/server/index.js
index 046004252d..a6be1e68ae 100644
--- a/api/server/index.js
+++ b/api/server/index.js
@@ -57,6 +57,7 @@ const {
createScheduleWriteGate,
startCodeEnvironmentLifecycleReconciler,
waitForKeyvRedisClient,
+ warnOnUnreachableDeliveryPaths,
} = require('@librechat/api');
const { connectDb, indexSync } = require('~/db');
const {
@@ -228,6 +229,7 @@ const startServer = async () => {
});
const appConfig = await getAppConfig({ baseOnly: true });
configureAgentEventRuntime(appConfig?.endpoints?.agents?.eventDriven);
+ warnOnUnreachableDeliveryPaths(appConfig);
initializeFileStorage(appConfig);
const projectRoot = path.resolve(__dirname, '../..');
// Plugin hooks execute only when the operator opts in via DEPLOYMENT_PLUGIN_HOOKS;
diff --git a/api/server/routes/files/files.agents.test.js b/api/server/routes/files/files.agents.test.js
index 86ff18025f..4323a28e81 100644
--- a/api/server/routes/files/files.agents.test.js
+++ b/api/server/routes/files/files.agents.test.js
@@ -428,6 +428,13 @@ describe('File Routes - Agent Files Endpoint', () => {
};
it('inspects the canonical sanitized filename used by upload processing', async () => {
+ await createAgent({
+ id: agentCustomId,
+ name: 'Test Agent',
+ provider: 'openai',
+ model: 'gpt-4',
+ author: authorId,
+ });
const testApp = createAppWithUser(
authorId,
SystemRoles.USER,
@@ -463,6 +470,49 @@ describe('File Routes - Agent Files Endpoint', () => {
expect(processAgentFileUpload).not.toHaveBeenCalled();
});
+ it('denies an unauthorized caller before validating against the agent', async () => {
+ /* Size and content validation run under the target agent's provider policy, so
+ * reaching them first answers an unauthorized caller with that agent's
+ * configuration instead of a 403. */
+ await createAgent({
+ id: agentCustomId,
+ name: 'Test Agent',
+ provider: 'openai',
+ model: 'gpt-4',
+ author: authorId,
+ });
+
+ const readFile = jest.spyOn(fs, 'readFile');
+ const testApp = createAppWithUser(
+ otherUserId,
+ SystemRoles.USER,
+ {
+ filters: {
+ files: {
+ pii: {
+ fields: ['content'],
+ uninspectable: 'block',
+ },
+ },
+ },
+ },
+ { mimetype: 'application/octet-stream', size: 15 * 1024 * 1024 + 1 },
+ );
+
+ const response = await request(testApp).post('/files').send({
+ endpoint: 'agents',
+ agent_id: agentCustomId,
+ tool_resource: 'context',
+ file_id: uuidv4(),
+ });
+
+ expect(response.status).toBe(403);
+ expect(response.body.error).toBe('Forbidden');
+ expect(readFile).not.toHaveBeenCalled();
+ expect(processAgentFileUpload).not.toHaveBeenCalled();
+ readFile.mockRestore();
+ });
+
it('should deny file upload to agent when user has no permission', async () => {
// Create an agent owned by authorId
await createAgent({
@@ -512,6 +562,13 @@ describe('File Routes - Agent Files Endpoint', () => {
});
it('inspects mislabeled text content before upload processing', async () => {
+ await createAgent({
+ id: agentCustomId,
+ name: 'Test Agent',
+ provider: 'openai',
+ model: 'gpt-4',
+ author: authorId,
+ });
const readFile = jest
.spyOn(fs, 'readFile')
.mockResolvedValueOnce(Buffer.from('Contains PRIVATE-1234'));
@@ -554,6 +611,13 @@ describe('File Routes - Agent Files Endpoint', () => {
});
it('blocks opaque file content before upload processing when configured fail-closed', async () => {
+ await createAgent({
+ id: agentCustomId,
+ name: 'Test Agent',
+ provider: 'openai',
+ model: 'gpt-4',
+ author: authorId,
+ });
const readFile = jest
.spyOn(fs, 'readFile')
.mockResolvedValueOnce(Buffer.from([0, 255, 0, 137, 80, 78, 71]));
@@ -709,6 +773,13 @@ describe('File Routes - Agent Files Endpoint', () => {
});
it('does not defer raw content fail-close when extracted text is also selected', async () => {
+ await createAgent({
+ id: agentCustomId,
+ name: 'Test Agent',
+ provider: 'openai',
+ model: 'gpt-4',
+ author: authorId,
+ });
const readFile = jest
.spyOn(fs, 'readFile')
.mockResolvedValueOnce(Buffer.from([0, 255, 0, 80, 68, 70]));
@@ -747,6 +818,13 @@ describe('File Routes - Agent Files Endpoint', () => {
});
it('does not defer extracted-text fail-close for non-context agent resources', async () => {
+ await createAgent({
+ id: agentCustomId,
+ name: 'Test Agent',
+ provider: 'openai',
+ model: 'gpt-4',
+ author: authorId,
+ });
const readFile = jest
.spyOn(fs, 'readFile')
.mockResolvedValueOnce(Buffer.from([0, 255, 0, 80, 68, 70]));
@@ -788,6 +866,13 @@ describe('File Routes - Agent Files Endpoint', () => {
['an unsupported binary', 'archive.bin', 'application/octet-stream'],
['audio handled as a transcript', 'recording.mp3', 'audio/mpeg'],
])('does not defer extracted-text fail-close for %s', async (_, originalname, mimetype) => {
+ await createAgent({
+ id: agentCustomId,
+ name: 'Test Agent',
+ provider: 'openai',
+ model: 'gpt-4',
+ author: authorId,
+ });
const readFile = jest
.spyOn(fs, 'readFile')
.mockResolvedValueOnce(Buffer.from([0, 255, 0, 80, 68, 70]));
@@ -860,6 +945,13 @@ describe('File Routes - Agent Files Endpoint', () => {
});
it('detects opaque content after a long printable file prefix', async () => {
+ await createAgent({
+ id: agentCustomId,
+ name: 'Test Agent',
+ provider: 'openai',
+ model: 'gpt-4',
+ author: authorId,
+ });
const readFile = jest
.spyOn(fs, 'readFile')
.mockResolvedValueOnce(Buffer.concat([Buffer.alloc(8192, 'a'), Buffer.from([0, 255])]));
@@ -1241,7 +1333,7 @@ describe('File Routes - Agent Files Endpoint', () => {
expect(JSON.stringify(response.body)).not.toContain(rawProviderDetail);
});
- it('should allow file upload with agent_id but no tool_resource (message attachment)', async () => {
+ it('should deny a permanent agent upload with no tool_resource from a user without permission', async () => {
// Create an agent owned by authorId
await createAgent({
id: agentCustomId,
@@ -1253,15 +1345,17 @@ describe('File Routes - Agent Files Endpoint', () => {
const testApp = createAppWithUser(otherUserId);
+ /* Unified mode accepts an upload with no tool_resource and promotes it to a
+ * context resource, so the permission check has to apply here: otherwise any
+ * user could attach persistent context to an agent they cannot edit. */
const response = await request(testApp).post('/files').send({
endpoint: 'agents',
agent_id: agentCustomId,
file_id: uuidv4(),
- // No tool_resource - permission check should not apply
});
- expect(response.status).toBe(200);
- expect(processAgentFileUpload).toHaveBeenCalled();
+ expect(response.status).toBe(403);
+ expect(processAgentFileUpload).not.toHaveBeenCalled();
});
it('should allow message_file attachment to agent even without EDIT permission', async () => {
diff --git a/api/server/routes/files/files.js b/api/server/routes/files/files.js
index f0859b0fb1..de84c67c95 100644
--- a/api/server/routes/files/files.js
+++ b/api/server/routes/files/files.js
@@ -42,6 +42,11 @@ const {
processDeleteRequest,
processAgentFileUpload,
} = require('~/server/services/Files/process');
+const {
+ resolveEffectiveToolResource,
+ resolveUploadEndpoint,
+ resolveUploadAgent,
+} = require('~/server/services/Files/routing');
const { fileAccess } = require('~/server/middleware/accessResources/fileAccess');
const { getStrategyFunctions } = require('~/server/services/Files/strategies');
const { getOpenAIClient } = require('~/server/controllers/assistants/helpers');
@@ -781,7 +786,48 @@ const handleFileUpload = async (req, res) => {
try {
req.file.originalname = sanitizeFilename(req.file.originalname);
- filterFile({ req });
+ const isAssistants = isAssistantsEndpoint(metadata.endpoint);
+
+ /* Authorization runs before anything reads the target agent. Validating against a
+ * record the caller cannot access answers with that agent's provider limits and
+ * content policy, so the rejection itself reports its configuration. */
+ if (!isAssistants) {
+ const denied = await verifyAgentUploadPermission({
+ req,
+ res,
+ metadata,
+ getAgent: ({ id }) => resolveUploadAgent(req, id),
+ checkPermission,
+ hasUploadBypass: () => hasCapability(req.user, SystemCapabilities.MANAGE_AGENTS),
+ });
+ if (denied) {
+ return;
+ }
+ }
+
+ /* Same configuration for validation and routing: an agent upload arrives as
+ * `agents` but is processed under the agent's own provider. */
+ const effectiveEndpoint = await resolveUploadEndpoint({
+ endpoint: metadata.endpoint,
+ agent_id: metadata.agent_id,
+ req,
+ });
+ /* Carried so processing routes under the same configuration validation used, and so
+ * it can tell whether any enabled tool could consume a file kept off the model path,
+ * both from the one agent read this request already made. */
+ metadata.effectiveEndpoint = effectiveEndpoint;
+ /* Left undefined when no agent record backs this upload, as for an ephemeral agent
+ * that exists only for the request. Processing then cannot judge what tools could
+ * consume the file and does not try. */
+ const uploadAgent = await resolveUploadAgent(req, metadata.agent_id);
+ metadata.agentTools = uploadAgent?.tools;
+ metadata.useResponsesApi ??= uploadAgent?.model_parameters?.useResponsesApi;
+ filterFile({ req, endpoint: effectiveEndpoint });
+
+ /* Same destination the processing path will use: a unified upload routed to text
+ * becomes a context resource, and the preflight must account for that extraction
+ * before fail-closing on an uninspectable derived field. */
+ const effectiveToolResource = await resolveEffectiveToolResource({ req, metadata });
/** Check the role permission before any content inspection: a forbidden upload
* must be rejected without reading or embedding the file. */
@@ -803,7 +849,7 @@ const handleFileUpload = async (req, res) => {
filters: req.config?.filters,
file: req.file,
endpoint: metadata.endpoint,
- toolResource: metadata.tool_resource,
+ toolResource: effectiveToolResource,
fileConfig: mergeFileConfig(req.config?.fileConfig),
ocrConfigured: req.config?.ocr != null,
ragConfigured: !!process.env.RAG_API_URL,
@@ -813,7 +859,7 @@ const handleFileUpload = async (req, res) => {
metadata.temp_file_id = metadata.file_id;
metadata.file_id = req.file_id;
- if (isAssistantsEndpoint(metadata.endpoint)) {
+ if (isAssistants) {
openSseStreamIfRequested();
return await processFileUpload({
req,
@@ -824,26 +870,6 @@ const handleFileUpload = async (req, res) => {
});
}
- let skipUploadAuth = false;
- try {
- skipUploadAuth = await hasCapability(req.user, SystemCapabilities.MANAGE_AGENTS);
- } catch (err) {
- logger.warn('[/files] capability check failed, denying bypass:', getSafeErrorMetadata(err));
- }
-
- if (!skipUploadAuth) {
- const denied = await verifyAgentUploadPermission({
- req,
- res,
- metadata,
- getAgent: db.getAgent,
- checkPermission,
- });
- if (denied) {
- return;
- }
- }
-
openSseStreamIfRequested();
return await processAgentFileUpload({ req, res, metadata, sseStream });
} catch (error) {
diff --git a/api/server/routes/files/images.agents.test.js b/api/server/routes/files/images.agents.test.js
index 4bd5ffee22..e49215506d 100644
--- a/api/server/routes/files/images.agents.test.js
+++ b/api/server/routes/files/images.agents.test.js
@@ -22,6 +22,18 @@ jest.mock('~/server/services/Files/process', () => ({
filterFile: jest.fn(),
}));
+jest.mock('~/server/services/Files/routing', () => {
+ const actual = jest.requireActual('~/server/services/Files/routing');
+ return {
+ ...actual,
+ /* Real by default so the dispatch is exercised end to end; individual tests override
+ * it for a single call to stand in for a routing configuration. */
+ resolveEffectiveToolResource: jest.fn((...args) =>
+ actual.resolveEffectiveToolResource(...args),
+ ),
+ };
+});
+
jest.mock('fs', () => {
const actualFs = jest.requireActual('fs');
return {
@@ -35,6 +47,8 @@ jest.mock('fs', () => {
const fs = require('fs');
const { processAgentFileUpload, processImageFile } = require('~/server/services/Files/process');
+const { resolveEffectiveToolResource } = require('~/server/services/Files/routing');
+const { filterFile } = require('~/server/services/Files/process');
const { UninspectableFileError } = require('@librechat/api');
const router = require('~/server/routes/files/images');
@@ -134,6 +148,13 @@ describe('POST /images - Agent Upload Permission Check (Integration)', () => {
};
it('inspects the canonical sanitized image filename used by upload processing', async () => {
+ await createAgent({
+ id: agentCustomId,
+ name: 'Test Agent',
+ provider: 'openai',
+ model: 'gpt-4',
+ author: authorId,
+ });
const app = createAppWithUser(
authorId,
SystemRoles.USER,
@@ -193,6 +214,41 @@ describe('POST /images - Agent Upload Permission Check (Integration)', () => {
expect(fs.promises.unlink).toHaveBeenCalledWith('/tmp/t.png');
});
+ it('denies an unauthorized caller before validating against the agent', async () => {
+ /* Image validation applies the target agent's provider policy, so reaching it first
+ * answers an unauthorized caller with that agent's configuration instead of a 403. */
+ await createAgent({
+ id: agentCustomId,
+ name: 'Test Agent',
+ provider: 'openai',
+ model: 'gpt-4',
+ author: authorId,
+ });
+
+ const app = createAppWithUser(otherUserId, SystemRoles.USER, {
+ filters: {
+ files: {
+ pii: {
+ fields: ['content'],
+ starterPatterns: [],
+ customPatterns: [],
+ uninspectable: 'block',
+ },
+ },
+ },
+ });
+ const response = await request(app).post('/images').send({
+ endpoint: 'agents',
+ agent_id: agentCustomId,
+ tool_resource: 'context',
+ file_id: uuidv4(),
+ });
+
+ expect(response.status).toBe(403);
+ expect(response.body.error).toBe('Forbidden');
+ expect(processAgentFileUpload).not.toHaveBeenCalled();
+ });
+
it('should allow upload for agent owner', async () => {
await createAgent({
id: agentCustomId,
@@ -214,9 +270,36 @@ describe('POST /images - Agent Upload Permission Check (Integration)', () => {
expect(processAgentFileUpload).toHaveBeenCalled();
});
+ it('rejects a none-routed image for a standard chat', async () => {
+ const app = createAppWithUser(authorId, SystemRoles.USER, {
+ fileConfig: {
+ endpoints: {
+ openAI: { defaultLLMDeliveryPath: { overrides: { 'image/*': 'none' } } },
+ },
+ },
+ });
+
+ const response = await request(app).post('/images').send({
+ endpoint: 'openAI',
+ message_file: 'true',
+ file_id: uuidv4(),
+ });
+
+ expect(response.status).toBe(500);
+ expect(processImageFile).not.toHaveBeenCalled();
+ expect(processAgentFileUpload).not.toHaveBeenCalled();
+ });
+
it.each(['content', 'extracted_text'])(
- 'blocks opaque image %s before permission or processing side effects',
+ 'blocks opaque image %s before processing side effects',
async (field) => {
+ await createAgent({
+ id: agentCustomId,
+ name: 'Test Agent',
+ provider: 'openai',
+ model: 'gpt-4',
+ author: authorId,
+ });
const app = createAppWithUser(authorId, SystemRoles.USER, {
filters: {
files: {
@@ -284,6 +367,45 @@ describe('POST /images - Agent Upload Permission Check (Integration)', () => {
expect(processAgentFileUpload).toHaveBeenCalledTimes(1);
});
+ it('defers extracted-text fail-close for a unified upload the config routes to text', async () => {
+ /* Same policy and file as the explicit-context case above, but with no tool_resource.
+ * Routing promotes it to a context resource, so the preflight has to see the same
+ * downstream extraction rather than fail-closing on an uninspectable derived field. */
+ await createAgent({
+ id: agentCustomId,
+ name: 'Test Agent',
+ provider: 'openai',
+ model: 'gpt-4',
+ author: authorId,
+ });
+ resolveEffectiveToolResource.mockResolvedValueOnce('context');
+
+ const app = createAppWithUser(authorId, SystemRoles.USER, {
+ filters: {
+ files: {
+ pii: {
+ fields: ['extracted_text'],
+ starterPatterns: [],
+ customPatterns: [],
+ uninspectable: 'block',
+ },
+ },
+ },
+ fileConfig: {
+ ocr: { supportedMimeTypes: ['image/png'] },
+ },
+ ocr: {},
+ });
+ const response = await request(app).post('/images').send({
+ endpoint: 'agents',
+ agent_id: agentCustomId,
+ file_id: uuidv4(),
+ });
+
+ expect(response.status).toBe(200);
+ expect(processAgentFileUpload).toHaveBeenCalledTimes(1);
+ });
+
it('preserves a deferred extracted-text policy error from image processing', async () => {
await createAgent({
id: agentCustomId,
@@ -329,6 +451,13 @@ describe('POST /images - Agent Upload Permission Check (Integration)', () => {
});
it('blocks extracted-text fail-close when configured OCR does not support the image MIME type', async () => {
+ await createAgent({
+ id: agentCustomId,
+ name: 'Test Agent',
+ provider: 'openai',
+ model: 'gpt-4',
+ author: authorId,
+ });
const app = createAppWithUser(authorId, SystemRoles.USER, {
filters: {
files: {
@@ -361,6 +490,13 @@ describe('POST /images - Agent Upload Permission Check (Integration)', () => {
});
it('preserves raw-content fail-close even when configured OCR supports the image', async () => {
+ await createAgent({
+ id: agentCustomId,
+ name: 'Test Agent',
+ provider: 'openai',
+ model: 'gpt-4',
+ author: authorId,
+ });
const app = createAppWithUser(authorId, SystemRoles.USER, {
filters: {
files: {
@@ -487,6 +623,67 @@ describe('POST /images - Agent Upload Permission Check (Integration)', () => {
expect(response.status).toBe(200);
});
+ it('validates an agent upload against the provider that will process it', async () => {
+ /* The request carries endpoint `agents`, but the agent's own provider governs
+ * routing, so it has to govern acceptance too or the two disagree. */
+ await createAgent({
+ id: agentCustomId,
+ name: 'Test Agent',
+ provider: 'openai',
+ model: 'gpt-4',
+ author: authorId,
+ });
+ const app = createAppWithUser(authorId);
+
+ await request(app).post('/images').send({
+ endpoint: 'agents',
+ agent_id: agentCustomId,
+ tool_resource: 'context',
+ file_id: uuidv4(),
+ });
+
+ expect(filterFile).toHaveBeenCalledWith(
+ expect.objectContaining({ endpoint: 'openai', image: true }),
+ );
+ });
+
+ it('sends a permanent agent image through the agent upload path', async () => {
+ /* The image pipeline always stores a message attachment and never files anything
+ * against the agent, so a permanent upload sent there would report success while
+ * leaving an orphan. */
+ await createAgent({
+ id: agentCustomId,
+ name: 'Test Agent',
+ provider: 'openai',
+ model: 'gpt-4',
+ author: authorId,
+ });
+ const app = createAppWithUser(authorId);
+
+ await request(app).post('/images').send({
+ endpoint: 'agents',
+ agent_id: agentCustomId,
+ file_id: uuidv4(),
+ });
+
+ expect(processAgentFileUpload).toHaveBeenCalled();
+ expect(processImageFile).not.toHaveBeenCalled();
+ });
+
+ it('sends an image the config routes to text through the agent upload path', async () => {
+ resolveEffectiveToolResource.mockResolvedValueOnce('context');
+ const app = createAppWithUser(otherUserId);
+
+ const response = await request(app).post('/images').send({
+ endpoint: 'agents',
+ file_id: uuidv4(),
+ });
+
+ expect(response.status).toBe(200);
+ expect(processAgentFileUpload).toHaveBeenCalled();
+ expect(processImageFile).not.toHaveBeenCalled();
+ });
+
it('uses a normalized image error when file protection is active', async () => {
const rawProviderDetail = 'PRIVATE-IMAGE echoed in provider failure';
const providerError = Object.assign(new Error(rawProviderDetail), {
diff --git a/api/server/routes/files/images.js b/api/server/routes/files/images.js
index 1228bddad1..7e5512f0cd 100644
--- a/api/server/routes/files/images.js
+++ b/api/server/routes/files/images.js
@@ -1,7 +1,7 @@
const path = require('path');
const fs = require('fs').promises;
const express = require('express');
-const { logger } = require('@librechat/data-schemas');
+const { logger, SystemCapabilities } = require('@librechat/data-schemas');
const {
getSafeErrorMetadata,
shouldUseUploadSse,
@@ -18,13 +18,24 @@ const {
isAssistantsEndpoint,
hasActivePiiPatterns,
mergeFileConfig,
+ isMessageFileUpload,
+ getEndpointFileConfig,
+ resolveUploadLLMDeliveryPath,
+ isResponsesApiUpload,
+ isSpeechProviderConfigured,
} = require('librechat-data-provider');
const {
processAgentFileUpload,
processImageFile,
filterFile,
} = require('~/server/services/Files/process');
+const {
+ resolveEffectiveToolResource,
+ resolveUploadEndpoint,
+ resolveUploadAgent,
+} = require('~/server/services/Files/routing');
const { checkPermission } = require('~/server/services/PermissionService');
+const { hasCapability } = require('~/server/middleware/roles/capabilities');
const db = require('~/models');
const router = express.Router();
@@ -44,7 +55,70 @@ router.post('/', async (req, res) => {
try {
req.file.originalname = sanitizeFilename(req.file.originalname);
- filterFile({ req, image: true });
+ const isAssistants = isAssistantsEndpoint(metadata.endpoint);
+
+ /* Authorization runs before anything reads the target agent, matching the file
+ * route. Validating against a record the caller cannot access answers with that
+ * agent's provider limits and content policy, so the rejection reports its
+ * configuration. Message attachments and requests naming no agent pass straight
+ * through without a read. */
+ if (!isAssistants) {
+ const denied = await verifyAgentUploadPermission({
+ req,
+ res,
+ metadata,
+ getAgent: ({ id }) => resolveUploadAgent(req, id),
+ checkPermission,
+ hasUploadBypass: () => hasCapability(req.user, SystemCapabilities.MANAGE_AGENTS),
+ });
+ if (denied) {
+ return;
+ }
+ }
+
+ /* Agent uploads arrive as `agents` but route by the agent's own provider, so the
+ * provider's configuration has to govern acceptance too. Resolved once here and
+ * reused by routing, authorization and processing below. */
+ const effectiveEndpoint = await resolveUploadEndpoint({
+ endpoint: metadata.endpoint,
+ agent_id: metadata.agent_id,
+ req,
+ });
+ /* Carried so processing routes under the same configuration validation used, and so
+ * it can tell whether any enabled tool could consume a file kept off the model path,
+ * both from the one agent read this request already made. */
+ metadata.effectiveEndpoint = effectiveEndpoint;
+ /* Left undefined when no agent record backs this upload, as for an ephemeral agent
+ * that exists only for the request. Processing then cannot judge what tools could
+ * consume the file and does not try. */
+ const uploadAgent = await resolveUploadAgent(req, metadata.agent_id);
+ metadata.agentTools = uploadAgent?.tools;
+ metadata.useResponsesApi ??= uploadAgent?.model_parameters?.useResponsesApi;
+ filterFile({ req, image: true, endpoint: effectiveEndpoint });
+
+ /* A unified upload the config routes to text is processed as a context resource, so
+ * the preflight has to judge that destination. Told only the request's empty tool
+ * resource, it cannot see the extraction step and fail-closes on a derived field it
+ * would in fact be able to inspect. */
+ const effectiveToolResource = await resolveEffectiveToolResource({ req, metadata });
+ const fileConfig = mergeFileConfig(req.config?.fileConfig);
+ const deliveryPath = resolveUploadLLMDeliveryPath({
+ mimeType: req.file.mimetype,
+ endpointConfig: getEndpointFileConfig({ fileConfig, endpoint: effectiveEndpoint }),
+ fileConfig,
+ endpoint: effectiveEndpoint,
+ useResponsesApi: isResponsesApiUpload(metadata.useResponsesApi),
+ sttConfigured: isSpeechProviderConfigured(req.config?.speech?.stt),
+ });
+ if (
+ deliveryPath === 'none' &&
+ effectiveToolResource == null &&
+ metadata.endpoint !== 'agents'
+ ) {
+ throw new Error(
+ `Files of type ${req.file.mimetype} are not sent to the model here, and this conversation has no agent whose tools could read them.`,
+ );
+ }
/** The Code Files UI routes image uploads here instead of `/files`, so the
* same role gate has to run before any content inspection — otherwise an
@@ -62,8 +136,8 @@ router.post('/', async (req, res) => {
filters: req.config?.filters,
file: req.file,
endpoint: metadata.endpoint,
- toolResource: metadata.tool_resource,
- fileConfig: mergeFileConfig(req.config?.fileConfig),
+ toolResource: effectiveToolResource,
+ fileConfig,
ocrConfigured: req.config?.ocr != null,
ragConfigured: !!process.env.RAG_API_URL,
rawFileMode: 'opaque',
@@ -72,17 +146,20 @@ router.post('/', async (req, res) => {
metadata.temp_file_id = metadata.file_id;
metadata.file_id = req.file_id;
- if (!isAssistantsEndpoint(metadata.endpoint) && metadata.tool_resource != null) {
- const denied = await verifyAgentUploadPermission({
- req,
- res,
- metadata,
- getAgent: db.getAgent,
- checkPermission,
- });
- if (denied) {
- return;
- }
+ /* An image the config routes to text delivery has to go through the agent upload
+ * path, which extracts and stores the text. The image pipeline would persist the
+ * routing without any text, leaving the file out of provider delivery and out of
+ * the text context both.
+ *
+ * A permanent upload against an agent takes that path regardless of what the routing
+ * inferred, because the image pipeline always stores a message attachment and never
+ * files anything against the agent. Sent here it would report success while leaving
+ * an orphan, so it goes where that is decided rather than assumed. */
+ const isPermanentAgentUpload =
+ metadata.agent_id != null && !isMessageFileUpload(metadata.message_file);
+ const takesAgentUploadPath = effectiveToolResource != null || isPermanentAgentUpload;
+
+ if (!isAssistants && takesAgentUploadPath) {
openSseStreamIfRequested();
return await processAgentFileUpload({ req, res, metadata, sseStream });
}
diff --git a/api/server/routes/files/multer.js b/api/server/routes/files/multer.js
index 023619c579..5f375f39cd 100644
--- a/api/server/routes/files/multer.js
+++ b/api/server/routes/files/multer.js
@@ -7,6 +7,7 @@ const { logger } = require('@librechat/data-schemas');
const {
mergeFileConfig,
inferMimeType,
+ isAgentsEndpoint,
getEndpointFileConfig,
fileConfig: defaultFileConfig,
} = require('librechat-data-provider');
@@ -58,6 +59,18 @@ const importFileFilter = (req, file, cb) => {
}
};
+/** Every type some configured endpoint accepts, for a request whose real endpoint is only
+ * known after an agent read this filter cannot make. */
+const collectSupportedMimeTypes = (customFileConfig, endpointFileConfig) => {
+ const merged = [...(endpointFileConfig.supportedMimeTypes ?? [])];
+ for (const config of Object.values(customFileConfig?.endpoints ?? {})) {
+ for (const mimeType of config?.supportedMimeTypes ?? []) {
+ merged.push(mimeType);
+ }
+ }
+ return merged;
+};
+
const normalizeUploadMimeType = (file) => {
const mimeType = inferMimeType(file.originalname || '', file.mimetype || '');
if (mimeType && file.mimetype !== mimeType) {
@@ -96,7 +109,16 @@ const createFileFilter = (customFileConfig, resolveEndpoint) => {
endpointType,
});
- if (!defaultFileConfig.checkType(mimeType, endpointFileConfig.supportedMimeTypes)) {
+ /* An agent upload is validated again under the agent's own provider once the route
+ * has resolved and authorized it. That provider's allowlist can be wider than the
+ * `agents` entry, and this filter is synchronous so it cannot resolve it, so here the
+ * question is only whether any configured endpoint accepts the type. Narrowing to
+ * `agents` would make the later provider check able to reject but never to permit. */
+ const supportedMimeTypes = isAgentsEndpoint(endpoint)
+ ? collectSupportedMimeTypes(customFileConfig, endpointFileConfig)
+ : endpointFileConfig.supportedMimeTypes;
+
+ if (!defaultFileConfig.checkType(mimeType, supportedMimeTypes)) {
return cb(
createCustomError(415, 'Unsupported file type: ' + (file.mimetype || mimeType)),
false,
diff --git a/api/server/routes/files/multer.spec.js b/api/server/routes/files/multer.spec.js
index 1c186dc745..351ed34a02 100644
--- a/api/server/routes/files/multer.spec.js
+++ b/api/server/routes/files/multer.spec.js
@@ -739,4 +739,64 @@ describe('Multer Configuration', () => {
expect(getAppConfig).toHaveBeenCalled();
});
});
+
+ describe('agent uploads and provider allowlists', () => {
+ const configWithWiderProvider = () => {
+ const { mergeFileConfig } = require('librechat-data-provider');
+ return mergeFileConfig({
+ endpoints: {
+ agents: { supportedMimeTypes: ['^application/pdf$'] },
+ 'Custom Provider': { supportedMimeTypes: ['^application/pdf$', '^video/mp4$'] },
+ },
+ });
+ };
+
+ it('accepts a type only the agent provider allows', (done) => {
+ /* This filter is synchronous and runs before the agent read, so narrowing to the
+ * agents entry would make the later provider check able to reject but never
+ * permit. The route validates again under the resolved provider. */
+ const fileFilter = createFileFilter(configWithWiderProvider());
+ mockReq.body = { endpoint: 'agents' };
+
+ fileFilter(
+ mockReq,
+ { ...mockFile, originalname: 'clip.mp4', mimetype: 'video/mp4' },
+ (err, accepted) => {
+ expect(err).toBeNull();
+ expect(accepted).toBe(true);
+ done();
+ },
+ );
+ });
+
+ it('still refuses a type no configured endpoint allows', (done) => {
+ const fileFilter = createFileFilter(configWithWiderProvider());
+ mockReq.body = { endpoint: 'agents' };
+
+ fileFilter(
+ mockReq,
+ { ...mockFile, originalname: 'installer.exe', mimetype: 'application/x-msdownload' },
+ (err, accepted) => {
+ expect(err).toBeTruthy();
+ expect(accepted).toBe(false);
+ done();
+ },
+ );
+ });
+
+ it('keeps a non-agent endpoint judged by its own allowlist alone', (done) => {
+ const fileFilter = createFileFilter(configWithWiderProvider());
+ mockReq.body = { endpoint: 'agents-lookalike' };
+
+ fileFilter(
+ mockReq,
+ { ...mockFile, originalname: 'clip.mp4', mimetype: 'video/mp4' },
+ (err, accepted) => {
+ expect(err).toBeTruthy();
+ expect(accepted).toBe(false);
+ done();
+ },
+ );
+ });
+ });
});
diff --git a/api/server/services/Endpoints/agents/initialize.js b/api/server/services/Endpoints/agents/initialize.js
index 9d73e6d711..053f809e4a 100644
--- a/api/server/services/Endpoints/agents/initialize.js
+++ b/api/server/services/Endpoints/agents/initialize.js
@@ -64,6 +64,13 @@ const {
resolveMemoryAvailability,
enrichLoadedToolsWithAgentContext,
} = require('./skillDeps');
+const {
+ loadCodeApiKey,
+ provisionToCodeEnv,
+ provisionToVectorDB,
+ checkSessionsAlive,
+} = require('~/server/services/Files/provision');
+const { createProvisionFilesCallback } = require('~/server/services/Files/provisionCallback');
const { getModelsConfig } = require('~/server/controllers/ModelController');
const { checkPermission, findAccessibleResources } = require('~/server/services/PermissionService');
const AgentClient = require('~/server/controllers/agents/client');
@@ -476,6 +483,11 @@ const initializeClient = async ({
}
},
...getSkillToolDeps(),
+ provisionFiles: createProvisionFilesCallback({
+ req,
+ agentToolContexts,
+ resolvePrimaryAgentId: () => primaryConfig?.id,
+ }),
};
const summarizationOptions =
@@ -647,12 +659,18 @@ const initializeClient = async ({
updateFilesUsage: db.updateFilesUsage,
getUserKeyValues: db.getUserKeyValues,
getUserCodeFiles: db.getUserCodeFiles,
+ getDeferredProvisionFiles: db.getDeferredProvisionFiles,
getToolFilesByIds: db.getToolFilesByIds,
getCodeGeneratedFiles: db.getCodeGeneratedFiles,
filterFilesByAgentAccess,
listSkillsByAccess: skillDbMethods.listSkillsByAccess,
listAlwaysApplySkills: skillDbMethods.listAlwaysApplySkills,
getSkillByName: skillDbMethods.getSkillByName,
+ provisionToCodeEnv,
+ provisionToVectorDB,
+ checkSessionsAlive,
+ loadCodeApiKey,
+ updateFile: db.updateFile,
},
);
@@ -731,12 +749,18 @@ const initializeClient = async ({
updateFilesUsage: db.updateFilesUsage,
getUserKeyValues: db.getUserKeyValues,
getUserCodeFiles: db.getUserCodeFiles,
+ getDeferredProvisionFiles: db.getDeferredProvisionFiles,
getToolFilesByIds: db.getToolFilesByIds,
getCodeGeneratedFiles: db.getCodeGeneratedFiles,
filterFilesByAgentAccess,
listSkillsByAccess: skillDbMethods.listSkillsByAccess,
listAlwaysApplySkills: skillDbMethods.listAlwaysApplySkills,
getSkillByName: skillDbMethods.getSkillByName,
+ provisionToCodeEnv,
+ provisionToVectorDB,
+ checkSessionsAlive,
+ loadCodeApiKey,
+ updateFile: db.updateFile,
},
// The callback fires during BFS, before the helper prunes agents
// whose edges end up filtered. Don't populate `agentConfigs` here —
@@ -1177,12 +1201,18 @@ const initializeClient = async ({
updateFilesUsage: db.updateFilesUsage,
getUserKeyValues: db.getUserKeyValues,
getUserCodeFiles: db.getUserCodeFiles,
+ getDeferredProvisionFiles: db.getDeferredProvisionFiles,
getToolFilesByIds: db.getToolFilesByIds,
getCodeGeneratedFiles: db.getCodeGeneratedFiles,
filterFilesByAgentAccess,
listSkillsByAccess: skillDbMethods.listSkillsByAccess,
listAlwaysApplySkills: skillDbMethods.listAlwaysApplySkills,
getSkillByName: skillDbMethods.getSkillByName,
+ provisionToCodeEnv,
+ provisionToVectorDB,
+ checkSessionsAlive,
+ loadCodeApiKey,
+ updateFile: db.updateFile,
},
),
context.signal,
diff --git a/api/server/services/Endpoints/agents/skillDeps.js b/api/server/services/Endpoints/agents/skillDeps.js
index 8fe49aedc3..2558ba021c 100644
--- a/api/server/services/Endpoints/agents/skillDeps.js
+++ b/api/server/services/Endpoints/agents/skillDeps.js
@@ -311,6 +311,7 @@ function buildAgentToolContext({ agent, config }) {
fileAuthoringToolNames: config.fileAuthoringToolNames,
skillPrimedIdsByName:
buildSkillPrimedIdsByName(config.manualSkillPrimes, config.alwaysApplySkillPrimes) ?? {},
+ provisionState: config.provisionState,
};
}
diff --git a/api/server/services/Files/Audio/STTService.js b/api/server/services/Files/Audio/STTService.js
index 0f52a277e2..1b0f6f5942 100644
--- a/api/server/services/Files/Audio/STTService.js
+++ b/api/server/services/Files/Audio/STTService.js
@@ -16,7 +16,11 @@ const {
contentFilterUninspectableResponse,
getBlockedUninspectableFileField,
} = require('@librechat/api');
-const { extractEnvVariable, STTProviders } = require('librechat-data-provider');
+const {
+ STTProviders,
+ extractEnvVariable,
+ listConfiguredSpeechProviders,
+} = require('librechat-data-provider');
const { getAppConfig } = require('~/server/services/Config');
/**
@@ -163,9 +167,7 @@ class STTService {
);
}
- const providers = Object.entries(sttSchema).filter(
- ([key, value]) => key !== 'allowedAddresses' && Object.keys(value).length > 0,
- );
+ const providers = listConfiguredSpeechProviders(sttSchema);
if (providers.length !== 1) {
throw new Error(
diff --git a/api/server/services/Files/Audio/STTService.spec.js b/api/server/services/Files/Audio/STTService.spec.js
index d8bcf364bc..d1a37c4327 100644
--- a/api/server/services/Files/Audio/STTService.spec.js
+++ b/api/server/services/Files/Audio/STTService.spec.js
@@ -52,6 +52,9 @@ jest.mock('@librechat/api', () => ({
}));
jest.mock('librechat-data-provider', () => ({
extractEnvVariable: jest.fn(),
+ /* Real selection logic: these tests are about which provider a schema resolves to. */
+ listConfiguredSpeechProviders:
+ jest.requireActual('librechat-data-provider').listConfiguredSpeechProviders,
STTProviders: {},
}));
jest.mock('~/server/services/Config', () => ({ getAppConfig: jest.fn() }));
diff --git a/api/server/services/Files/Audio/TTSService.js b/api/server/services/Files/Audio/TTSService.js
index bace395504..99b3cdb428 100644
--- a/api/server/services/Files/Audio/TTSService.js
+++ b/api/server/services/Files/Audio/TTSService.js
@@ -7,7 +7,11 @@ const {
resolveConfigSecret,
applySSRFSafeAgentIfDirect,
} = require('@librechat/api');
-const { extractEnvVariable, TTSProviders } = require('librechat-data-provider');
+const {
+ TTSProviders,
+ extractEnvVariable,
+ listConfiguredSpeechProviders,
+} = require('librechat-data-provider');
const { getRandomVoiceId, createChunkProcessor, splitTextIntoChunks } = require('./streamAudio');
const { getAppConfig } = require('~/server/services/Config');
@@ -52,9 +56,7 @@ class TTSService {
'No TTS schema is set. Did you configure TTS in the custom config (librechat.yaml)?',
);
}
- const providers = Object.entries(ttsSchema).filter(
- ([key, value]) => key !== 'allowedAddresses' && Object.keys(value).length > 0,
- );
+ const providers = listConfiguredSpeechProviders(ttsSchema);
if (providers.length !== 1) {
throw new Error(
diff --git a/api/server/services/Files/Audio/TTSService.spec.js b/api/server/services/Files/Audio/TTSService.spec.js
index 1f9fb79dc0..8273d8b4e5 100644
--- a/api/server/services/Files/Audio/TTSService.spec.js
+++ b/api/server/services/Files/Audio/TTSService.spec.js
@@ -8,6 +8,9 @@ jest.mock('@librechat/api', () => ({
}));
jest.mock('librechat-data-provider', () => ({
extractEnvVariable: jest.fn((value) => value),
+ /* Real selection logic: these tests are about which provider a schema resolves to. */
+ listConfiguredSpeechProviders:
+ jest.requireActual('librechat-data-provider').listConfiguredSpeechProviders,
TTSProviders: {
OPENAI: 'openai',
AZURE_OPENAI: 'azureOpenAI',
diff --git a/api/server/services/Files/Azure/crud.js b/api/server/services/Files/Azure/crud.js
index 59ffed9891..5944f40ab7 100644
--- a/api/server/services/Files/Azure/crud.js
+++ b/api/server/services/Files/Azure/crud.js
@@ -1,7 +1,6 @@
const fs = require('fs');
const path = require('path');
const mime = require('mime');
-const axios = require('axios');
const fetch = require('node-fetch');
const { logger } = require('@librechat/data-schemas');
const {
@@ -250,14 +249,43 @@ async function uploadFileToAzure({
* @param {string} fileURL - The URL of the blob.
* @returns {Promise<ReadableStream>} A readable stream of the blob.
*/
-async function getAzureFileStream(_req, fileURL) {
+async function getAzureFileStream(_req, fileURL, { signal } = {}) {
try {
- const response = await axios({
- method: 'get',
- url: fileURL,
- responseType: 'stream',
+ const url = new URL(fileURL);
+ const configuredClient = await getAzureContainerClient();
+ const configuredURL = configuredClient.url ? new URL(configuredClient.url) : undefined;
+ const configuredPrefix = configuredURL?.pathname.replace(/\/$/, '');
+ let containerClient = configuredClient;
+ let blobPath;
+
+ if (
+ configuredURL &&
+ configuredPrefix &&
+ url.origin === configuredURL.origin &&
+ url.pathname.startsWith(`${configuredPrefix}/`)
+ ) {
+ /* Azurite puts the account name before the container in the path. The configured
+ * container URL already includes both, so resolve the blob relative to it. */
+ blobPath = url.pathname.slice(configuredPrefix.length + 1);
+ } else {
+ const pathSegments = url.pathname.split('/').filter(Boolean);
+ const containerName = pathSegments.shift();
+ blobPath = pathSegments.join('/');
+ if (containerName) {
+ containerClient = await getAzureContainerClient(decodeURIComponent(containerName));
+ }
+ }
+ blobPath = blobPath?.split('/').map(decodeURIComponent).join('/');
+ if (!blobPath) {
+ throw new Error('Invalid Azure Blob URL');
+ }
+ const response = await containerClient.getBlockBlobClient(blobPath).download(0, undefined, {
+ abortSignal: signal,
});
- return response.data;
+ if (!response.readableStreamBody) {
+ throw new Error('Azure Blob download returned no readable stream');
+ }
+ return response.readableStreamBody;
} catch (error) {
logger.error('[getAzureFileStream] Error getting blob stream:', error);
throw error;
diff --git a/api/server/services/Files/Azure/crud.spec.js b/api/server/services/Files/Azure/crud.spec.js
new file mode 100644
index 0000000000..c7e87b1d9b
--- /dev/null
+++ b/api/server/services/Files/Azure/crud.spec.js
@@ -0,0 +1,57 @@
+const mockDownload = jest.fn();
+const mockGetBlockBlobClient = jest.fn(() => ({ download: mockDownload }));
+const mockGetAzureContainerClient = jest.fn(async () => ({
+ url: 'https://account.blob.core.windows.net/files',
+ getBlockBlobClient: mockGetBlockBlobClient,
+}));
+
+jest.mock('@librechat/data-schemas', () => ({
+ logger: { error: jest.fn() },
+}));
+
+jest.mock('@librechat/api', () => ({
+ deleteRagFile: jest.fn(),
+ assertRemoteFileURL: jest.fn((url) => url),
+ getAzureContainerClient: (...args) => mockGetAzureContainerClient(...args),
+ getRemoteFileFetchMaxBytes: jest.fn(() => 1024),
+ getRemoteFileFetchTimeoutMs: jest.fn(() => 1000),
+ assertRemoteFileContentLength: jest.fn(),
+}));
+
+const { getAzureFileStream } = require('./crud');
+
+describe('getAzureFileStream', () => {
+ it('downloads private blobs through the authenticated Azure client', async () => {
+ const stream = { pipe: jest.fn() };
+ mockDownload.mockResolvedValue({ readableStreamBody: stream });
+
+ await expect(
+ getAzureFileStream(
+ {},
+ 'https://account.blob.core.windows.net/private-files/uploads/user/report%20one.pdf',
+ ),
+ ).resolves.toBe(stream);
+
+ expect(mockGetAzureContainerClient).toHaveBeenCalledWith('private-files');
+ expect(mockGetBlockBlobClient).toHaveBeenCalledWith('uploads/user/report one.pdf');
+ });
+
+ it('resolves Azurite blobs relative to the configured account and container path', async () => {
+ const stream = { pipe: jest.fn() };
+ mockDownload.mockResolvedValue({ readableStreamBody: stream });
+ mockGetAzureContainerClient.mockResolvedValueOnce({
+ url: 'http://127.0.0.1:10000/devstoreaccount1/files',
+ getBlockBlobClient: mockGetBlockBlobClient,
+ });
+
+ await expect(
+ getAzureFileStream(
+ {},
+ 'http://127.0.0.1:10000/devstoreaccount1/files/uploads/user/report%20one.pdf',
+ ),
+ ).resolves.toBe(stream);
+
+ expect(mockGetAzureContainerClient).toHaveBeenCalledWith();
+ expect(mockGetBlockBlobClient).toHaveBeenCalledWith('uploads/user/report one.pdf');
+ });
+});
diff --git a/api/server/services/Files/Code/crud.js b/api/server/services/Files/Code/crud.js
index aaa53a82d8..3732e4f6b7 100644
--- a/api/server/services/Files/Code/crud.js
+++ b/api/server/services/Files/Code/crud.js
@@ -197,6 +197,7 @@ async function uploadCodeEnvFile({
codeApiBaseUrl,
executionProfile,
bridgeWorkerId,
+ signal,
}) {
try {
const form = new FormData();
@@ -220,6 +221,7 @@ async function uploadCodeEnvFile({
timeout: 120000,
maxContentLength: MAX_FILE_SIZE,
maxBodyLength: MAX_FILE_SIZE,
+ ...(signal ? { signal } : {}),
};
const response = await axios.post(`${baseURL}/upload`, form, options);
diff --git a/api/server/services/Files/Code/process.js b/api/server/services/Files/Code/process.js
index ab76eaf3aa..001a43423e 100644
--- a/api/server/services/Files/Code/process.js
+++ b/api/server/services/Files/Code/process.js
@@ -53,6 +53,7 @@ const {
mergeCodeEnvRef,
getCodeEnvRefForProfile,
getEndpointFileConfig,
+ resolveSandboxFilename,
} = require('librechat-data-provider');
const { filterFilesByAgentAccess } = require('~/server/services/Files/permissions');
const { createFile, getFiles, updateFile, claimCodeFile } = require('~/models');
@@ -1395,11 +1396,20 @@ const primeFiles = async (options) => {
* codeapi can resolve sessionKey per-file (kind switch +
* tenant prefix from auth context).
*/
+ const sandboxName = resolveSandboxFilename(file.filename, file.type);
+ let claimedDestination;
+ const getDestination = () => {
+ claimedDestination ??= claimCodeDestination(destinations, sandboxName, file.file_id);
+ return claimedDestination;
+ };
+
const pushFile = (overrideSessionId, overrideId) => {
/* Claimed here rather than up front so files that never reach the
* sandbox — no code-env ref, or a failed re-upload — do not reserve a
* name and push a file that does reach it onto a counter. */
- const destination = claimCodeDestination(destinations, file.filename, file.file_id);
+ /* The sandbox holds the converted name, not the record's, so the mount path has
+ * to follow the same rule provisioning uploaded under. */
+ const destination = getDestination();
if (destination !== file.filename) {
logger.debug(
`[primeCodeFiles] file=${file.file_id} destination=${destination} ` +
@@ -1441,7 +1451,7 @@ const primeFiles = async (options) => {
const uploaded = await uploadCodeEnvFile({
req: options.req,
stream,
- filename: file.filename,
+ filename: getDestination(),
kind: sourceRef.kind,
id: sourceRef.id,
...(sourceRef.kind === 'skill' ? { version: sourceRef.version } : {}),
diff --git a/api/server/services/Files/Code/process.spec.js b/api/server/services/Files/Code/process.spec.js
index 91473eb74f..f678feefab 100644
--- a/api/server/services/Files/Code/process.spec.js
+++ b/api/server/services/Files/Code/process.spec.js
@@ -2760,6 +2760,42 @@ describe('Code Process', () => {
]);
});
+ it('reuploads a recovered converted image under its advertised sandbox name', async () => {
+ getFiles.mockResolvedValue([
+ {
+ file_id: 'converted-image',
+ filename: 'photo.png',
+ filepath: '/uploads/photo.webp',
+ type: 'image/webp',
+ source: 'local',
+ context: 'execute_code',
+ metadata: {
+ codeEnvRef: {
+ kind: 'user',
+ id: 'user-123',
+ storage_session_id: 'OLD_SESSION',
+ file_id: 'OLD_ID',
+ },
+ },
+ },
+ ]);
+ const { handleFileUpload } = setupReuploadMocks({
+ storage_session_id: 'NEW_SESSION',
+ file_id: 'NEW_ID',
+ });
+
+ const result = await primeFiles({
+ req: { user: { id: 'user-123', role: 'USER' } },
+ tool_resources: { execute_code: { file_ids: ['converted-image'], files: [] } },
+ agentId: 'agent-id',
+ });
+
+ expect(handleFileUpload).toHaveBeenCalledWith(
+ expect.objectContaining({ filename: 'photo.webp' }),
+ );
+ expect(result.files?.[0]?.name).toBe('photo.webp');
+ });
+
/* Phase C / option α (codeapi #1455): reupload preserves the
* resource identity from the existing ref so codeapi re-buckets
* under the same sessionKey shape. Without this, a skill-cache-miss
@@ -3112,6 +3148,28 @@ describe('Code Process', () => {
]);
});
+ it('mounts a converted image under the name the sandbox actually holds', async () => {
+ /* Image uploads are converted to the configured output type while the record keeps
+ * the original filename. Provisioning uploaded the converted name, so rebuilding
+ * the mount path from the record advertises a file the sandbox does not have. */
+ setupSessionInfoOk();
+ getFiles.mockResolvedValue([
+ makeFile({
+ file_id: 'fid-ready',
+ filename: 'photo.png',
+ type: 'image/webp',
+ }),
+ ]);
+
+ const result = await primeFiles({
+ req: { user: { id: 'user-123', role: 'USER' } },
+ tool_resources: { execute_code: { file_ids: ['fid-ready'], files: [] } },
+ agentId: 'agent-id',
+ });
+
+ expect(result.files?.[0]?.name).toBe('photo.webp');
+ });
+
it('annotates a pending file with "(preview not yet generated)"', async () => {
setupSessionInfoOk();
getFiles.mockResolvedValue([makeFile({ status: 'pending' })]);
diff --git a/api/server/services/Files/Firebase/crud.js b/api/server/services/Files/Firebase/crud.js
index 9fbdb91dbe..cf6d4c74e3 100644
--- a/api/server/services/Files/Firebase/crud.js
+++ b/api/server/services/Files/Firebase/crud.js
@@ -249,7 +249,7 @@ async function uploadFileToFirebase({ req, file, file_id }) {
* @param {string} filepath - The filepath.
* @returns {Promise<ReadableStream>} A readable stream of the file.
*/
-async function getFirebaseFileStream(_req, filepath) {
+async function getFirebaseFileStream(_req, filepath, { signal } = {}) {
try {
const storage = getFirebaseStorage();
if (!storage) {
@@ -260,6 +260,7 @@ async function getFirebaseFileStream(_req, filepath) {
method: 'get',
url: filepath,
responseType: 'stream',
+ signal,
});
return response.data;
diff --git a/api/server/services/Files/VectorDB/crud.js b/api/server/services/Files/VectorDB/crud.js
index 4eea1169c1..9f43f0e4ae 100644
--- a/api/server/services/Files/VectorDB/crud.js
+++ b/api/server/services/Files/VectorDB/crud.js
@@ -64,7 +64,7 @@ const deleteVectors = async (req, file) => {
* - filepath: The path where the file is saved.
* - bytes: The size of the file in bytes.
*/
-async function uploadVectors({ req, file, file_id, entity_id, storageMetadata }) {
+async function uploadVectors({ req, file, file_id, entity_id, storageMetadata, signal }) {
if (!process.env.RAG_API_URL) {
throw new Error('RAG_API_URL not defined');
}
@@ -86,6 +86,7 @@ async function uploadVectors({ req, file, file_id, entity_id, storageMetadata })
const formHeaders = formData.getHeaders();
const response = await axios.post(`${process.env.RAG_API_URL}/embed`, formData, {
+ ...(signal ? { signal } : {}),
headers: {
Authorization: `Bearer ${jwtToken}`,
accept: 'application/json',
diff --git a/api/server/services/Files/process.js b/api/server/services/Files/process.js
index 517d90c466..c888746bea 100644
--- a/api/server/services/Files/process.js
+++ b/api/server/services/Files/process.js
@@ -17,6 +17,14 @@ const {
removeNullishValues,
isAssistantsEndpoint,
getEndpointFileConfig,
+ resolveUploadLLMDeliveryPath,
+ isNativelyReadableText,
+ resolveUploadDestination,
+ resolveSandboxFilename,
+ canToolResourceConsume,
+ isMessageFileUpload,
+ isResponsesApiUpload,
+ isSpeechProviderConfigured,
} = require('librechat-data-provider');
const { logger, runAsSystem } = require('@librechat/data-schemas');
const {
@@ -460,7 +468,7 @@ const processFileURL = async ({
* @param {ServerRequest} params.req - The Express request object.
* @param {Express.Response} [params.res] - The Express response object.
* @param {ImageMetadata} params.metadata - Additional metadata for the file.
- * @param {boolean} params.returnFile - Whether to return the file metadata or return response as normal.
+ * @param {boolean} params.returnFile - Return the converted file's metadata without persisting it, for a caller that creates its own record.
* @param {import('@librechat/api').UploadSseStream | null} [params.sseStream] - Active upload SSE stream, if enabled.
* @returns {Promise<void>}
*/
@@ -471,6 +479,19 @@ const processImageFile = async ({ req, res, metadata, returnFile = false, sseStr
const source = getFileStrategy(appConfig, { isImage: true });
const { handleImageUpload } = getStrategyFunctions(source);
const { file_id, temp_file_id, endpoint } = metadata;
+ const fileConfig = mergeFileConfig(appConfig?.fileConfig);
+ /* The route resolved the agent's provider before validating, so the same endpoint
+ * governs delivery routing here. */
+ const configEndpoint = metadata.effectiveEndpoint ?? endpoint;
+ const endpointConfig = getEndpointFileConfig({ fileConfig, endpoint: configEndpoint });
+ const llmDeliveryPath = resolveUploadLLMDeliveryPath({
+ mimeType: file.mimetype,
+ endpointConfig,
+ fileConfig,
+ endpoint: configEndpoint,
+ useResponsesApi: isResponsesApiUpload(metadata.useResponsesApi ?? req.body?.useResponsesApi),
+ sttConfigured: isSpeechProviderConfigured(appConfig?.speech?.stt),
+ });
const { filepath, bytes, width, height, storageKey, storageRegion } = await handleImageUpload({
req,
@@ -480,29 +501,41 @@ const processImageFile = async ({ req, res, metadata, returnFile = false, sseStr
});
const storageMetadata = getStorageMetadata({ filepath, source, storageKey, storageRegion });
- const result = await db.createFile(
- {
- user: req.user.id,
- file_id,
- temp_file_id,
- bytes,
- filepath,
- ...storageMetadata,
- filename: file.originalname,
- context: FileContext.message_attachment,
- source,
- type: `image/${appConfig.imageOutputType}`,
- ...(await retentionExpiryPromise),
- width,
- height,
- tenantId: req.user.tenantId,
+ const fileInfo = {
+ user: req.user.id,
+ file_id,
+ temp_file_id,
+ bytes,
+ filepath,
+ ...storageMetadata,
+ filename: file.originalname,
+ context: FileContext.message_attachment,
+ source,
+ type: `image/${appConfig.imageOutputType}`,
+ ...(await retentionExpiryPromise),
+ width,
+ height,
+ tenantId: req.user.tenantId,
+ llmDeliveryPath,
+ /* The image route persists through here directly, so the choice has to be recorded
+ * on this path too. Absent, a later turn substitutes its own endpoint's mode. */
+ metadata: {
+ destinationChosen:
+ endpointConfig?.legacyFileUploadUX === true || metadata.tool_resource != null,
+ ...(`image/${appConfig.imageOutputType}` !== file.mimetype
+ ? { routingMimeType: file.mimetype }
+ : {}),
},
- true,
- );
+ };
+ /* Callers asking for the file are converting an image for a record of their own, under
+ * a different id. Persisting here would leave that row referenced by nothing while the
+ * converted object it points at is the one they go on to use. */
if (returnFile) {
- return result;
+ return fileInfo;
}
+
+ const result = await db.createFile(fileInfo, true);
sendUploadSuccess(res, sseStream, 'File uploaded and processed successfully', result);
};
@@ -690,19 +723,150 @@ const processFileUpload = async ({ req, res, metadata, sseStream, openai: provid
* @param {import('@librechat/api').UploadSseStream | null} [params.sseStream] - Active upload SSE stream, if enabled.
* @returns {Promise<void>}
*/
+/** Reader-facing names for the destinations an upload can be rejected against. */
+const TOOL_RESOURCE_LABELS = {
+ [EToolResources.execute_code]: 'the code interpreter',
+ [EToolResources.code_interpreter]: 'the code interpreter',
+ [EToolResources.file_search]: 'file search',
+ [EToolResources.context]: 'text context',
+ [EToolResources.image_edit]: 'image editing',
+ [EToolResources.ocr]: 'OCR',
+};
+
+/** Capability gate for each tool that can consume a file kept off the model path. */
+const CONSUMER_CAPABILITIES = [
+ [EToolResources.execute_code, AgentCapabilities.execute_code],
+ [EToolResources.file_search, AgentCapabilities.file_search],
+];
+
+/**
+ * Narrows an agent's tools to those this deployment will actually honor. Filing a file
+ * under a disabled capability fails the upload on a rule the agent's tool order picked.
+ */
+const filterEnabledConsumers = async (req, agentTools, roleGrants) => {
+ if (!agentTools?.length) {
+ return agentTools;
+ }
+ const candidates = CONSUMER_CAPABILITIES.filter(([resource]) => agentTools.includes(resource));
+ if (candidates.length === 0) {
+ return agentTools;
+ }
+ const enabled = await Promise.all(
+ candidates.map(([, capability]) => checkCapability(req, capability)),
+ );
+ const disabled = new Set(
+ candidates
+ .filter(([resource], index) => {
+ if (!enabled[index]) {
+ return true;
+ }
+ if (resource === EToolResources.execute_code) {
+ return roleGrants?.runCode === false;
+ }
+ return resource === EToolResources.file_search && roleGrants?.fileSearch === false;
+ })
+ .map(([resource]) => resource),
+ );
+ return disabled.size > 0 ? agentTools.filter((tool) => !disabled.has(tool)) : agentTools;
+};
+
const processAgentFileUpload = async ({ req, res, metadata, sseStream }) => {
const { file } = req;
const appConfig = req.config;
const { agent_id, tool_resource, file_id, temp_file_id = null } = metadata;
- let messageAttachment = !!metadata.message_file;
+ let messageAttachment = isMessageFileUpload(metadata.message_file);
+
+ let effectiveToolResource;
+
+ const fileConfig = mergeFileConfig(appConfig?.fileConfig);
+ const endpoint = metadata.effectiveEndpoint ?? req.body?.endpoint;
+ const endpointConfig = getEndpointFileConfig({ fileConfig, endpoint });
+
+ /* Recorded on the file below, both ways: the endpoint setting can differ on a later
+ * turn, but the user's decision about this file does not change with it. An absent
+ * marker means a record written before this was tracked, not an inferred destination.
+ *
+ * A destination is the user's whenever they named one, which the chooser always does
+ * and a request naming a tool resource does too. Recording the endpoint mode instead
+ * would treat an explicitly sandbox-only upload in unified mode as inferred. */
+ const legacyUploadUX = endpointConfig?.legacyFileUploadUX === true;
+ const uploadChoiceMetadata = { destinationChosen: legacyUploadUX || tool_resource != null };
if (agent_id && !tool_resource && !messageAttachment) {
- throw new Error('No tool resource provided for agent file upload');
+ if (legacyUploadUX) {
+ throw new Error('No tool resource provided for agent file upload');
+ }
+ }
+
+ const llmDeliveryPath = resolveUploadLLMDeliveryPath({
+ toolResource: tool_resource,
+ mimeType: file.mimetype,
+ endpointConfig,
+ fileConfig,
+ endpoint,
+ useResponsesApi: isResponsesApiUpload(metadata.useResponsesApi ?? req.body?.useResponsesApi),
+ sttConfigured: isSpeechProviderConfigured(appConfig?.speech?.stt),
+ });
+
+ /* Destination and acceptability are one decision, made by shared policy rather than
+ * rebuilt here. `agentTools` is undefined when no agent record backs the upload. */
+ /* Only a permanent agent upload can land on a context resource, so the capability is
+ * looked up only there and the common attachment path pays nothing for it. */
+ const contextEnabled =
+ messageAttachment || agent_id == null
+ ? undefined
+ : await checkCapability(req, AgentCapabilities.context);
+ const hasRoleGatedConsumer =
+ tool_resource === EToolResources.execute_code ||
+ tool_resource === EToolResources.file_search ||
+ metadata.agentTools?.some(
+ (tool) => tool === EToolResources.execute_code || tool === EToolResources.file_search,
+ );
+ const toolRoleGrants = hasRoleGatedConsumer
+ ? await resolveToolRoleGrants({
+ req,
+ getRoleByName: db.getRoleByName,
+ context: 'fileUpload',
+ })
+ : undefined;
+ const destination = resolveUploadDestination({
+ toolResource: tool_resource,
+ deliveryPath: llmDeliveryPath,
+ mimeType: file.mimetype,
+ agentTools: await filterEnabledConsumers(req, metadata.agentTools, toolRoleGrants),
+ hasAgent: agent_id != null,
+ isMessageAttachment: messageAttachment,
+ /* A message attachment can acquire a file-tool consumer later in the same draft or
+ * on a later turn. This deliberately includes saved agents whose persisted tools are
+ * empty: skills and per-turn tool selection are not represented by agent.tools.
+ * Audio has no deferred file-tool contract and still requires STT. Permanent agent
+ * uploads must be filed under a durable resource before returning. */
+ allowUnknownMessageConsumer: messageAttachment && !file.mimetype.startsWith('audio/'),
+ contextEnabled,
+ });
+
+ if (destination.rejection === 'no-consumer') {
+ throw new Error(
+ `Files of type ${file.mimetype} are not sent to the model here, and this conversation has no agent whose tools could read them. Attach it to an agent with the code interpreter or file search enabled, or upload a supported file type.`,
+ );
+ }
+ if (destination.rejection === 'context-disabled') {
+ throw new Error(
+ `Files of type ${file.mimetype} are saved to an agent as extracted text, and the context capability is disabled. Enable it for Agents, or attach the file to a message instead.`,
+ );
+ }
+ if (destination.rejection === 'no-agent-resource') {
+ throw new Error(
+ `Files of type ${file.mimetype} cannot be saved to an agent on their own. Attach the file to a message, or enable the code interpreter or file search so the agent has somewhere to keep it.`,
+ );
}
+ effectiveToolResource = destination.toolResource;
- if (tool_resource === EToolResources.file_search && file.mimetype.startsWith('image')) {
- throw new Error('Image uploads are not supported for file search tool resources');
+ if (effectiveToolResource && !canToolResourceConsume(effectiveToolResource, file.mimetype)) {
+ throw new Error(
+ `Files of type ${file.mimetype} cannot be read by ${TOOL_RESOURCE_LABELS[effectiveToolResource] ?? effectiveToolResource}.`,
+ );
}
if (!messageAttachment && !agent_id) {
@@ -712,70 +876,40 @@ const processAgentFileUpload = async ({ req, res, metadata, sseStream }) => {
const retentionExpiryPromise = getAgentFileRetentionExpiry({
req,
messageAttachment,
- tool_resource,
+ tool_resource: effectiveToolResource,
});
const isImage = file.mimetype.startsWith('image');
let fileInfoMetadata;
const entity_id = messageAttachment === true ? undefined : agent_id;
const basePath = mime.getType(file.originalname)?.startsWith('image') ? 'images' : 'uploads';
- if (tool_resource === EToolResources.execute_code) {
+ let shouldUploadToCodeEnv = effectiveToolResource === EToolResources.execute_code;
+ if (effectiveToolResource === EToolResources.execute_code) {
const isCodeEnabled =
(await checkCapability(req, AgentCapabilities.execute_code)) &&
- (await resolveToolRoleGrants({ req, getRoleByName: db.getRoleByName, context: 'fileUpload' }))
- .runCode;
+ toolRoleGrants?.runCode === true;
if (!isCodeEnabled) {
throw new Error('Code execution is not enabled for Agents');
}
- const { handleFileUpload: uploadCodeEnvFile } = getStrategyFunctions(FileSources.execute_code);
- const stream = fs.createReadStream(file.path);
- /* Resource identity for codeapi's sessionKey:
- * - chat attachments (messageAttachment=true): `kind: 'user'`, codeapi
- * buckets under `<tenant>:user:<authContext.userId>` regardless of `id`.
- * - agent setup files (messageAttachment=false): `kind: 'agent'`, shared
- * per agent identity. `id` carries the agent id. */
- const codeKind = messageAttachment === true ? 'user' : 'agent';
- const codeId = messageAttachment === true ? req.user.id : agent_id;
- /* Upload under the same sanitized filename LC stores in its DB
- * (`fileInfo.filename` below uses `sanitizeFilename(originalname)`).
- * Codeapi/file_server use this as the on-disk name in the sandbox
- * — `/mnt/data/<filename>` — and `primeFiles`'s `toolContext` text
- * + `_injected_files.name` both reference `file.filename`. Sending
- * the unsanitized `file.originalname` here makes the sandbox path
- * (with spaces / special chars) drift from what LC tells the model
- * is available, causing FileNotFoundError on the first reference. */
- const sandboxFilename = sanitizeFilename(file.originalname);
- const uploaded = await uploadCodeEnvFile({
- req,
- stream,
- filename: sandboxFilename,
- kind: codeKind,
- id: codeId,
- });
- /* Persist under the structured `codeEnvRef` shape — the only key the
- * post-cutover schema (`metadata.codeEnvRef`) and downstream readers
- * (`primeFiles`, `getCodeFilesByIds`, `categorizeFileForToolResources`,
- * controller filtering) accept. Storing under the legacy
- * `fileIdentifier` key would be silently dropped by mongoose strict
- * mode and the file would lose its sandbox reference on subsequent
- * priming turns. */
- fileInfoMetadata = mergeCodeEnvRef(undefined, {
- kind: codeKind,
- id: codeId,
- storage_session_id: uploaded.storage_session_id,
- file_id: uploaded.file_id,
- executionProfile: 'default',
- });
- } else if (tool_resource === EToolResources.file_search) {
+ /* Only an explicit choice uploads here. A promoted destination has no user decision
+ * behind it and the agent's code deployment is resolved per turn, so uploading now
+ * would name the default route and be uploaded again at execution, or fail outright
+ * where only a stateful deployment exists. Deferred provisioning does it with the
+ * route the turn actually runs on. */
+ if (tool_resource == null) {
+ shouldUploadToCodeEnv = false;
+ }
+ }
+
+ if (effectiveToolResource === EToolResources.file_search) {
const isFileSearchEnabled =
(await checkCapability(req, AgentCapabilities.file_search)) &&
- (await resolveToolRoleGrants({ req, getRoleByName: db.getRoleByName, context: 'fileUpload' }))
- .fileSearch;
+ toolRoleGrants?.fileSearch === true;
if (!isFileSearchEnabled) {
throw new Error('File search is not enabled for Agents');
}
// Note: File search processing continues to dual storage logic below
- } else if (tool_resource === EToolResources.context) {
+ } else if (effectiveToolResource === EToolResources.context) {
const { file_id, temp_file_id = null } = metadata;
const getExtractionLogDetails = (error) =>
getFileExtractionLogDetails({
@@ -789,19 +923,10 @@ const processAgentFileUpload = async ({ req, res, metadata, sseStream }) => {
/**
* @param {object} params
* @param {string} params.text
- * @param {number} params.bytes
- * @param {string} params.filepath
- * @param {string} params.type
* @param {boolean} params.isTranscript
* @return {Promise<void>}
*/
- const createTextFile = async ({
- text,
- bytes,
- filepath,
- type = 'text/plain',
- isTranscript = false,
- }) => {
+ const createTextFile = async ({ text, isTranscript = false }) => {
if (!isTranscript) {
assertExtractedTextInspectable({
filters: appConfig?.filters,
@@ -839,6 +964,19 @@ const processAgentFileUpload = async ({ req, res, metadata, sseStream }) => {
return;
}
}
+ const isImageFile = file.mimetype.startsWith('image');
+ const source = getFileStrategy(appConfig, { isImage: isImageFile });
+ const { handleFileUpload } = getStrategyFunctions(source);
+ const sanitizedUploadFn = createSanitizedUploadWrapper(handleFileUpload);
+ const storageResult = await sanitizedUploadFn({
+ req,
+ file,
+ file_id,
+ basePath,
+ entity_id,
+ });
+ const { bytes, filename, filepath, embedded, height, width } = storageResult;
+
const retentionExpiry = await retentionExpiryPromise;
const fileInfo = {
...removeNullishValues({
@@ -847,22 +985,27 @@ const processAgentFileUpload = async ({ req, res, metadata, sseStream }) => {
file_id,
temp_file_id,
user: req.user.id,
- type,
- filepath: filepath ?? file.path,
- source: FileSources.text,
- filename: file.originalname,
+ type: file.mimetype,
+ filepath,
+ source,
+ filename: filename ?? sanitizeFilename(file.originalname),
model: messageAttachment ? undefined : req.body.model,
context: messageAttachment ? FileContext.message_attachment : FileContext.agents,
tenantId: req.user.tenantId,
+ embedded,
+ height,
+ width,
+ llmDeliveryPath: 'text',
}),
+ metadata: uploadChoiceMetadata,
...retentionExpiry,
};
- if (!messageAttachment && tool_resource) {
+ if (!messageAttachment && effectiveToolResource) {
await db.addAgentResourceFile({
file_id,
agent_id,
- tool_resource,
+ tool_resource: effectiveToolResource,
updatingUserId: req?.user?.id,
});
}
@@ -873,7 +1016,7 @@ const processAgentFileUpload = async ({ req, res, metadata, sseStream }) => {
const fileConfig = mergeFileConfig(appConfig.fileConfig);
const extractedTextPlan = getUploadExtractedTextPlan({
endpoint: metadata.endpoint,
- toolResource: tool_resource,
+ toolResource: effectiveToolResource,
mimeType: file.mimetype,
fileConfig,
ocrConfigured: appConfig?.ocr != null,
@@ -923,8 +1066,8 @@ const processAgentFileUpload = async ({ req, res, metadata, sseStream }) => {
extract: resolveDocumentText,
});
if (ocrResult) {
- const { text, bytes, filepath: ocrFileURL } = ocrResult;
- return await createTextFile({ text, bytes, filepath: ocrFileURL });
+ const { text } = ocrResult;
+ return await createTextFile({ text });
}
throw new Error(
`Unable to extract text from "${file.originalname}". The document may be image-based and requires an OCR service to process.`,
@@ -938,8 +1081,8 @@ const processAgentFileUpload = async ({ req, res, metadata, sseStream }) => {
if (shouldUseSTT) {
const sttService = await STTService.getInstance();
- const { text, bytes } = await processAudioFile({ req, file, sttService });
- return await createTextFile({ text, bytes, type: file.mimetype, isTranscript: true });
+ const { text } = await processAudioFile({ req, file, sttService });
+ return await createTextFile({ text, isTranscript: true });
}
const shouldUseText = fileConfig.checkType(
@@ -977,29 +1120,40 @@ const processAgentFileUpload = async ({ req, res, metadata, sseStream }) => {
`Unable to extract text from "${file.originalname}". RAG text extraction was unavailable and the built-in parser produced no result.`,
);
}
- const { text, bytes, filepath: docFileURL } = documentText;
- return await createTextFile({ text, bytes, filepath: docFileURL });
+ const { text } = documentText;
+ return await createTextFile({ text });
}
- return await createTextFile({
- text: configuredText.text,
- bytes: configuredText.bytes,
- type: file.mimetype,
- });
+ return await createTextFile({ text: configuredText.text });
}
- const { text, bytes } = await extractInspectableFileText({
+ /* The native reader decodes whatever bytes it is given as UTF-8, which is meaningful
+ * only for types that are already text. For anything else, a raster image on a
+ * deployment without OCR being the case in point, it would store mojibake as the
+ * file's text, so a real extractor is required and its absence surfaces as an error
+ * rather than as nonsense content. */
+ const { text } = await extractInspectableFileText({
filters: appConfig?.filters,
- extract: () => parseText({ req, file, file_id }),
+ extract: () =>
+ parseText({
+ req,
+ file,
+ file_id,
+ allowNativeFallback: isNativelyReadableText(file.mimetype),
+ }),
});
- return await createTextFile({ text, bytes, type: file.mimetype });
+ return await createTextFile({ text });
}
// Dual storage pattern for RAG files: Storage + Vector DB
let storageResult, embeddingResult;
+ let storedType = file.mimetype;
const isImageFile = file.mimetype.startsWith('image');
const source = getFileStrategy(appConfig, { isImage: isImageFile });
- if (tool_resource === EToolResources.file_search) {
+ if (
+ effectiveToolResource === EToolResources.file_search &&
+ tool_resource === EToolResources.file_search
+ ) {
// FIRST: Upload to Storage for permanent backup (S3/local/etc.)
const { handleFileUpload } = getStrategyFunctions(source);
const sanitizedUploadFn = createSanitizedUploadWrapper(handleFileUpload);
@@ -1021,8 +1175,30 @@ const processAgentFileUpload = async ({ req, res, metadata, sseStream }) => {
entity_id,
});
- // Vector status will be stored at root level, no need for metadata
- fileInfoMetadata = {};
+ /* Vectors live under the entity that embedded them, and priming asks which namespaces
+ * hold them rather than reading the root flag. Omitting it here re-embeds the file on
+ * the first search, and aborts that search if RAG is briefly unavailable. */
+ fileInfoMetadata = entity_id != null ? { embeddedEntities: [entity_id] } : {};
+ } else if (isImage) {
+ /* The conversion is this file's storage step. Uploading the original first left a
+ * second object nothing references, and the record's size and dimensions describing
+ * bytes that were replaced. Only the storage fields are kept: the record below is
+ * built here, and its filename goes through the sanitizer. */
+ const converted = await processImageFile({
+ req,
+ file,
+ metadata: { file_id },
+ returnFile: true,
+ });
+ storedType = converted.type ?? storedType;
+ storageResult = {
+ bytes: converted.bytes,
+ filepath: converted.filepath,
+ storageKey: converted.storageKey,
+ storageRegion: converted.storageRegion,
+ height: converted.height,
+ width: converted.width,
+ };
} else {
// Standard single storage for non-RAG files
const { handleFileUpload } = getStrategyFunctions(source);
@@ -1036,6 +1212,57 @@ const processAgentFileUpload = async ({ req, res, metadata, sseStream }) => {
});
}
+ if (shouldUploadToCodeEnv) {
+ const { handleFileUpload: uploadCodeEnvFile } = getStrategyFunctions(FileSources.execute_code);
+ const { getDownloadStream } = getStrategyFunctions(source);
+ if (!getDownloadStream && source !== FileSources.local) {
+ throw new Error(`No download stream available for ${source} storage`);
+ }
+ /* Upload from the persisted representation. Images have already been converted here,
+ * so both the bytes and extension advertised to the sandbox describe the same file. */
+ const downloadPath = storageResult.storageKey ?? storageResult.filepath;
+ const stream = getDownloadStream
+ ? await getDownloadStream(req, downloadPath)
+ : fs.createReadStream(file.path);
+ const codeKind = messageAttachment === true ? 'user' : 'agent';
+ const codeId = messageAttachment === true ? req.user.id : agent_id;
+ const sandboxFilename = resolveSandboxFilename(sanitizeFilename(file.originalname), storedType);
+ let uploaded;
+ try {
+ uploaded = await uploadCodeEnvFile({
+ req,
+ stream,
+ filename: sandboxFilename,
+ kind: codeKind,
+ id: codeId,
+ });
+ } catch (error) {
+ const { deleteFile } = getStrategyFunctions(source);
+ if (deleteFile) {
+ try {
+ await deleteFile(req, {
+ file_id,
+ filepath: storageResult.filepath,
+ storageKey: storageResult.storageKey,
+ storageRegion: storageResult.storageRegion,
+ source,
+ });
+ } catch (cleanupError) {
+ logger.error('[processAgentFileUpload] Failed to clean up stored file', cleanupError);
+ }
+ }
+ throw error;
+ }
+ fileInfoMetadata = mergeCodeEnvRef(undefined, {
+ kind: codeKind,
+ id: codeId,
+ storage_session_id: uploaded.storage_session_id,
+ file_id: uploaded.file_id,
+ executionProfile: 'default',
+ provisionedAt: Date.now(),
+ });
+ }
+
let {
bytes,
filename,
@@ -1047,7 +1274,10 @@ const processAgentFileUpload = async ({ req, res, metadata, sseStream }) => {
} = storageResult;
// For RAG files, use embedding result; for others, use storage result
let embedded = storageResult.embedded;
- if (tool_resource === EToolResources.file_search) {
+ if (
+ effectiveToolResource === EToolResources.file_search &&
+ tool_resource === EToolResources.file_search
+ ) {
embedded = embeddingResult?.embedded;
filename = embeddingResult?.filename || filename;
}
@@ -1060,31 +1290,15 @@ const processAgentFileUpload = async ({ req, res, metadata, sseStream }) => {
storageRegion: _storageRegion,
});
- if (!messageAttachment && tool_resource) {
+ if (!messageAttachment && effectiveToolResource) {
await db.addAgentResourceFile({
file_id,
agent_id,
- tool_resource,
+ tool_resource: effectiveToolResource,
updatingUserId: req?.user?.id,
});
}
- if (isImage) {
- const result = await processImageFile({
- req,
- file,
- metadata: { file_id: v4() },
- returnFile: true,
- });
- filepath = result.filepath;
- storageMetadata = getStorageMetadata({
- filepath,
- source: result.source,
- storageKey: result.storageKey,
- storageRegion: result.storageRegion,
- });
- }
-
const retentionExpiry = await retentionExpiryPromise;
const fileInfo = {
...removeNullishValues({
@@ -1097,13 +1311,21 @@ const processAgentFileUpload = async ({ req, res, metadata, sseStream }) => {
filename: filename ?? sanitizeFilename(file.originalname),
context: messageAttachment ? FileContext.message_attachment : FileContext.agents,
model: messageAttachment ? undefined : req.body.model,
- metadata: fileInfoMetadata,
- type: file.mimetype,
+ metadata: {
+ ...(fileInfoMetadata ?? {}),
+ ...uploadChoiceMetadata,
+ /* The route was resolved against the upload's own type, and delivery re-resolves
+ * it later. Conversion changes `type`, so without this the second answer is drawn
+ * from a format the administrator never configured a route for. */
+ ...(storedType !== file.mimetype ? { routingMimeType: file.mimetype } : {}),
+ },
+ type: storedType,
embedded,
source,
height,
width,
tenantId: req.user.tenantId,
+ llmDeliveryPath,
}),
...retentionExpiry,
};
@@ -1403,9 +1625,30 @@ async function saveBase64Image(
*
* @throws {Error} If a file exception is caught (invalid file size or type, lack of metadata).
*/
-function filterFile({ req, image, isAvatar }) {
+/**
+ * @param {object} params
+ * @param {ServerRequest} params.req
+ * @param {boolean} [params.image]
+ * @param {boolean} [params.isAvatar]
+ * @param {string} [params.endpoint] Effective endpoint for this upload. Agent uploads
+ * arrive as `agents` but route by the agent's own provider, so validation has to be
+ * told which configuration governs, or it admits files the provider rejects and
+ * rejects files the provider allows.
+ */
+function filterFile({ req, image, isAvatar, endpoint: endpointOverride }) {
const { file } = req;
- const { endpoint, endpointType, file_id, width, height } = req.body;
+ const {
+ endpoint: requestEndpoint,
+ endpointType: requestEndpointType,
+ file_id,
+ width,
+ height,
+ } = req.body;
+ const endpoint = endpointOverride ?? requestEndpoint;
+ /* getEndpointFileConfig consults endpointType ahead of endpoint, so a composer upload
+ * carrying `agents` would keep the Agents policy and shadow the provider the override
+ * names. The override replaces both or neither. */
+ const endpointType = endpointOverride != null ? undefined : requestEndpointType;
if (!file_id && !isAvatar) {
throw new Error('No file_id provided');
@@ -1432,6 +1675,9 @@ function filterFile({ req, image, isAvatar }) {
fileConfig,
endpointType,
});
+ if (isAvatar !== true && endpointFileConfig?.disabled === true) {
+ throw new Error(`File uploads are disabled for ${endpoint} endpoint`);
+ }
const fileSizeLimit =
isAvatar === true ? fileConfig.avatarSizeLimit : endpointFileConfig.fileSizeLimit;
diff --git a/api/server/services/Files/process.spec.js b/api/server/services/Files/process.spec.js
index 9a54b3a3d3..76c0e2044e 100644
--- a/api/server/services/Files/process.spec.js
+++ b/api/server/services/Files/process.spec.js
@@ -174,6 +174,7 @@ jest.mock('~/models', () => ({
findFileById: jest.fn(),
getConvo: jest.fn(),
getExpiredFiles: jest.fn(),
+ getAgent: jest.fn().mockResolvedValue(null),
incrementFileDeletionAttempts: jest.fn(),
deferExpiredFile: jest.fn(),
addAgentResourceFile: jest.fn().mockResolvedValue({}),
@@ -215,6 +216,10 @@ jest.mock('~/server/services/Files/Audio/STTService', () => ({
STTService: { getInstance: jest.fn() },
}));
+jest.mock('./VectorDB/crud', () => ({
+ uploadVectors: jest.fn().mockResolvedValue({ embedded: true, filename: 'embedded-upload.bin' }),
+}));
+
const {
getRetentionExpiry,
getAgentFileRetentionExpiry,
@@ -222,6 +227,7 @@ const {
startExpiredFileSweep: startExpiredFileSweepWithDeps,
} = require('@librechat/api');
const {
+ EModelEndpoint,
EToolResources,
FileSources,
FileContext,
@@ -230,19 +236,21 @@ const {
} = require('librechat-data-provider');
const { mergeFileConfig } = require('librechat-data-provider');
const { checkCapability } = require('~/server/services/Config');
+const { loadAuthValues } = require('~/server/services/Tools/credentials');
const { getStrategyFunctions } = require('~/server/services/Files/strategies');
const { uploadVectors } = require('./VectorDB/crud');
const { logger } = require('@librechat/data-schemas');
const db = require('~/models');
const {
processAgentFileUpload,
+ processImageFile,
processDeleteRequest,
processFileUpload,
processFileURL,
- processImageFile,
retrieveAndProcessFile,
sweepExpiredFiles,
startExpiredFileSweep,
+ filterFile,
} = require('./process');
const {
inspectContent,
@@ -279,6 +287,7 @@ const makeReq = ({
ocrConfig = null,
interfaceConfig,
filters,
+ speech,
body,
} = {}) => ({
user: { id: 'user-123', tenantId: 'tenant-a' },
@@ -292,7 +301,9 @@ const makeReq = ({
config: {
fileConfig: {},
fileStrategy: 'local',
+ imageOutputType: 'webp',
ocr: ocrConfig,
+ ...(speech ? { speech } : {}),
...(filters ? { filters } : {}),
...(interfaceConfig ? { interfaceConfig } : {}),
},
@@ -422,6 +433,8 @@ describe('processAgentFileUpload', () => {
mockRes.status.mockReturnThis();
mockRes.json.mockReturnValue({});
checkCapability.mockResolvedValue(true);
+ loadAuthValues.mockResolvedValue({ CODE_API_KEY: 'code-key' });
+ uploadVectors.mockResolvedValue({ embedded: true, filename: 'embedded-upload.bin' });
getStrategyFunctions.mockReturnValue({
handleFileUpload: jest
.fn()
@@ -527,7 +540,7 @@ describe('processAgentFileUpload', () => {
expect(db.createFile).toHaveBeenCalledWith(
expect.objectContaining({
type: 'audio/webm',
- source: FileSources.text,
+ llmDeliveryPath: 'text',
text: 'submitted transcript',
}),
true,
@@ -640,7 +653,11 @@ describe('processAgentFileUpload', () => {
test('throws when configured OCR capability is not enabled for the agent', async () => {
mergeFileConfig.mockReturnValue(makeFileConfig({ ocrSupportedMimeTypes: [PDF_MIME] }));
- checkCapability.mockResolvedValue(false);
+ /* Only OCR is under test here; disabling every capability would trip the
+ * separate context guard first. */
+ checkCapability.mockImplementation(
+ async (_req, capability) => capability !== AgentCapabilities.ocr,
+ );
const req = makeReq({
mimetype: PDF_MIME,
ocrConfig: { strategy: FileSources.mistral_ocr },
@@ -652,7 +669,11 @@ describe('processAgentFileUpload', () => {
});
test('uses document_parser (no capability check) when OCR capability returns false but no OCR config', async () => {
- checkCapability.mockResolvedValue(false);
+ /* Only OCR is under test here; disabling every capability would trip the
+ * separate context guard first. */
+ checkCapability.mockImplementation(
+ async (_req, capability) => capability !== AgentCapabilities.ocr,
+ );
const req = makeReq({ mimetype: PDF_MIME, ocrConfig: null });
await processAgentFileUpload({ req, res: mockRes, metadata: makeMetadata() });
@@ -1271,11 +1292,165 @@ describe('processAgentFileUpload', () => {
getStrategyFunctions.mockImplementation((src) =>
src === FileSources.execute_code
? { handleFileUpload: codeEnvUpload }
- : { handleFileUpload: localUpload, saveBuffer: jest.fn() },
+ : {
+ handleFileUpload: localUpload,
+ getDownloadStream: jest.fn(async () => Readable.from(Buffer.from('stored'))),
+ saveBuffer: jest.fn(),
+ },
);
return codeEnvUpload;
};
+ const agentsZipReq = () => {
+ const req = makeReq({ mimetype: 'application/zip', ocrConfig: null });
+ req.body.endpoint = EModelEndpoint.agents;
+ return req;
+ };
+
+ it('leaves a promoted code destination for deferred provisioning', async () => {
+ /* No explicit choice stands behind a promotion, and the agent's code deployment is
+ * resolved per turn, so uploading now names the default route and has to be
+ * uploaded again where the turn actually runs. */
+ const codeEnvUpload = setupCodeEnvUpload({ storage_session_id: 'sess-x', file_id: 'fid-x' });
+
+ await processAgentFileUpload({
+ req: agentsZipReq(),
+ res: mockRes,
+ metadata: {
+ agent_id: 'agent-abc',
+ file_id: 'file-promoted',
+ agentTools: [EToolResources.execute_code],
+ },
+ }).catch(() => {});
+
+ expect(codeEnvUpload).not.toHaveBeenCalled();
+ expect(db.createFile).toHaveBeenCalledWith(
+ expect.objectContaining({
+ metadata: expect.not.objectContaining({ codeEnvRef: expect.anything() }),
+ }),
+ true,
+ );
+ });
+
+ it('still uploads eagerly when the user chose the code destination', async () => {
+ const codeEnvUpload = setupCodeEnvUpload({ storage_session_id: 'sess-y', file_id: 'fid-y' });
+
+ await processAgentFileUpload({
+ req: agentsZipReq(),
+ res: mockRes,
+ metadata: {
+ agent_id: 'agent-abc',
+ tool_resource: EToolResources.execute_code,
+ file_id: 'file-chosen',
+ },
+ }).catch(() => {});
+
+ expect(codeEnvUpload).toHaveBeenCalled();
+ });
+
+ it('defers an inferred file-search destination until tool execution', async () => {
+ const { uploadVectors } = require('~/server/services/Files/VectorDB/crud');
+ setupStoredFileUpload();
+ const req = makeReq({
+ mimetype: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+ ocrConfig: null,
+ });
+ req.body.endpoint = EModelEndpoint.agents;
+
+ await processAgentFileUpload({
+ req,
+ res: mockRes,
+ metadata: {
+ agent_id: 'agent-abc',
+ file_id: 'file-inferred-search',
+ agentTools: [EToolResources.file_search],
+ },
+ });
+
+ expect(uploadVectors).not.toHaveBeenCalled();
+ expect(db.createFile).toHaveBeenCalledWith(
+ expect.objectContaining({
+ llmDeliveryPath: 'none',
+ metadata: expect.not.objectContaining({ embeddedEntities: expect.anything() }),
+ }),
+ true,
+ );
+ });
+
+ it('uploads converted image bytes under the converted extension', async () => {
+ const codeEnvUpload = jest
+ .fn()
+ .mockResolvedValue({ storage_session_id: 'sess-image', file_id: 'fid-image' });
+ const convertedStream = Readable.from(Buffer.from('webp'));
+ getStrategyFunctions.mockImplementation((src) =>
+ src === FileSources.execute_code
+ ? { handleFileUpload: codeEnvUpload }
+ : {
+ handleImageUpload: jest.fn().mockResolvedValue({
+ filepath: '/images/photo.webp',
+ bytes: 4,
+ width: 10,
+ height: 10,
+ }),
+ getDownloadStream: jest.fn().mockResolvedValue(convertedStream),
+ },
+ );
+ const req = makeReq({ mimetype: 'image/jpeg', ocrConfig: null });
+ req.file.originalname = 'photo.jpg';
+ req.body.endpoint = EModelEndpoint.agents;
+
+ await processAgentFileUpload({
+ req,
+ res: mockRes,
+ metadata: {
+ agent_id: 'agent-abc',
+ tool_resource: EToolResources.execute_code,
+ file_id: 'file-image',
+ },
+ });
+
+ expect(codeEnvUpload).toHaveBeenCalledWith(
+ expect.objectContaining({ filename: 'photo.webp', stream: convertedStream }),
+ );
+ });
+
+ it('removes durable storage when an eager code upload fails', async () => {
+ const deleteFile = jest.fn().mockResolvedValue(undefined);
+ getStrategyFunctions.mockImplementation((src) =>
+ src === FileSources.execute_code
+ ? { handleFileUpload: jest.fn().mockRejectedValue(new Error('code unavailable')) }
+ : {
+ handleFileUpload: jest.fn().mockResolvedValue({
+ filepath: '/uploads/user-123/stored.bin',
+ bytes: 4,
+ }),
+ getDownloadStream: jest.fn(async () => Readable.from(Buffer.from('stored'))),
+ deleteFile,
+ },
+ );
+
+ await expect(
+ processAgentFileUpload({
+ req: agentsZipReq(),
+ res: mockRes,
+ metadata: {
+ agent_id: 'agent-abc',
+ tool_resource: EToolResources.execute_code,
+ file_id: 'file-cleanup',
+ },
+ }),
+ ).rejects.toThrow('code unavailable');
+
+ expect(deleteFile).toHaveBeenCalledWith(
+ expect.anything(),
+ expect.objectContaining({
+ file_id: 'file-cleanup',
+ filepath: '/uploads/user-123/stored.bin',
+ }),
+ );
+ expect(db.createFile).not.toHaveBeenCalled();
+ });
+
it('persists kind:user codeEnvRef for chat attachments (messageAttachment=true)', async () => {
setupCodeEnvUpload({ storage_session_id: 'sess-1', file_id: 'fid-1' });
const req = makeReq();
@@ -1292,13 +1467,14 @@ describe('processAgentFileUpload', () => {
expect(db.createFile).toHaveBeenCalledWith(
expect.objectContaining({
- metadata: {
+ metadata: expect.objectContaining({
codeEnvRef: {
kind: 'user',
id: 'user-123',
storage_session_id: 'sess-1',
file_id: 'fid-1',
executionProfile: 'default',
+ provisionedAt: expect.any(Number),
},
codeEnvRefs: {
default: {
@@ -1307,9 +1483,10 @@ describe('processAgentFileUpload', () => {
storage_session_id: 'sess-1',
file_id: 'fid-1',
executionProfile: 'default',
+ provisionedAt: expect.any(Number),
},
},
- },
+ }),
}),
true,
);
@@ -1330,13 +1507,14 @@ describe('processAgentFileUpload', () => {
expect(db.createFile).toHaveBeenCalledWith(
expect.objectContaining({
- metadata: {
+ metadata: expect.objectContaining({
codeEnvRef: {
kind: 'agent',
id: 'agent-abc',
storage_session_id: 'sess-2',
file_id: 'fid-2',
executionProfile: 'default',
+ provisionedAt: expect.any(Number),
},
codeEnvRefs: {
default: {
@@ -1345,9 +1523,10 @@ describe('processAgentFileUpload', () => {
storage_session_id: 'sess-2',
file_id: 'fid-2',
executionProfile: 'default',
+ provisionedAt: expect.any(Number),
},
},
- },
+ }),
}),
true,
);
@@ -1400,13 +1579,14 @@ describe('processAgentFileUpload', () => {
expect.objectContaining({
expiredAt,
context: FileContext.agents,
- metadata: {
+ metadata: expect.objectContaining({
codeEnvRef: {
kind: 'agent',
id: 'agent-abc',
storage_session_id: 'sess-5',
file_id: 'fid-5',
executionProfile: 'default',
+ provisionedAt: expect.any(Number),
},
codeEnvRefs: {
default: {
@@ -1415,9 +1595,10 @@ describe('processAgentFileUpload', () => {
storage_session_id: 'sess-5',
file_id: 'fid-5',
executionProfile: 'default',
+ provisionedAt: expect.any(Number),
},
},
- },
+ }),
}),
true,
);
@@ -1447,6 +1628,555 @@ describe('processAgentFileUpload', () => {
expect(persisted.metadata).not.toHaveProperty('fileIdentifier');
});
});
+
+ describe('text delivery storage', () => {
+ test('stores the original file durably for plain text delivery records', async () => {
+ const { parseText } = require('@librechat/api');
+ const { createFile } = require('~/models');
+ const storageUpload = jest.fn().mockResolvedValue({
+ filepath: '/uploads/user-123/file-uuid-123__upload.bin',
+ bytes: 128,
+ filename: 'upload.bin',
+ embedded: false,
+ });
+ mergeFileConfig.mockReturnValue(makeFileConfig({ textSupportedMimeTypes: ['text/plain'] }));
+ parseText.mockResolvedValueOnce({ text: 'plain extracted text', bytes: 20 });
+ getStrategyFunctions.mockReturnValue({ handleFileUpload: storageUpload });
+ const req = makeReq({ mimetype: 'text/plain', ocrConfig: null });
+
+ await processAgentFileUpload({ req, res: mockRes, metadata: makeMetadata() });
+
+ expect(storageUpload).toHaveBeenCalledWith(
+ expect.objectContaining({
+ file_id: 'file-uuid-123',
+ file: expect.objectContaining({ originalname: 'upload.bin' }),
+ }),
+ );
+ expect(createFile).toHaveBeenCalledWith(
+ expect.objectContaining({
+ text: 'plain extracted text',
+ bytes: 128,
+ filepath: '/uploads/user-123/file-uuid-123__upload.bin',
+ source: FileSources.local,
+ filename: 'upload.bin',
+ type: 'text/plain',
+ llmDeliveryPath: 'text',
+ }),
+ true,
+ );
+ });
+
+ test('stores the original file durably for OCR delivery records', async () => {
+ const { createFile } = require('~/models');
+ const documentUpload = jest.fn().mockResolvedValue({
+ text: 'ocr extracted text',
+ bytes: 42,
+ filepath: 'document_parser',
+ });
+ const storageUpload = jest.fn().mockResolvedValue({
+ filepath: '/uploads/user-123/file-uuid-123__upload.bin',
+ bytes: 4096,
+ filename: 'upload.bin',
+ embedded: false,
+ });
+ getStrategyFunctions.mockImplementation((source) => {
+ if (source === FileSources.document_parser) {
+ return { handleFileUpload: documentUpload };
+ }
+ return { handleFileUpload: storageUpload };
+ });
+ const req = makeReq({ mimetype: PDF_MIME, ocrConfig: null });
+
+ await processAgentFileUpload({ req, res: mockRes, metadata: makeMetadata() });
+
+ expect(documentUpload).toHaveBeenCalled();
+ expect(storageUpload).toHaveBeenCalled();
+ expect(createFile).toHaveBeenCalledWith(
+ expect.objectContaining({
+ text: 'ocr extracted text',
+ bytes: 4096,
+ filepath: '/uploads/user-123/file-uuid-123__upload.bin',
+ source: FileSources.local,
+ filename: 'upload.bin',
+ type: PDF_MIME,
+ llmDeliveryPath: 'text',
+ }),
+ true,
+ );
+ });
+ });
+
+ describe('explicit legacy tool delivery path', () => {
+ test('persists llmDeliveryPath none for explicit file_search uploads', async () => {
+ const { createFile } = require('~/models');
+ const storageUpload = jest.fn().mockResolvedValue({
+ filepath: '/uploads/user-123/file-uuid-123__upload.bin',
+ bytes: 128,
+ filename: 'upload.bin',
+ embedded: false,
+ });
+ getStrategyFunctions.mockReturnValue({ handleFileUpload: storageUpload });
+ mergeFileConfig.mockReturnValue({
+ ...makeFileConfig(),
+ defaultLLMDeliveryPath: {
+ fallback: 'text',
+ },
+ });
+ const req = makeReq({ mimetype: 'text/markdown', ocrConfig: null });
+
+ await processAgentFileUpload({
+ req,
+ res: mockRes,
+ metadata: {
+ ...makeMetadata(),
+ tool_resource: EToolResources.file_search,
+ },
+ });
+
+ expect(checkCapability).toHaveBeenCalledWith(
+ expect.anything(),
+ AgentCapabilities.file_search,
+ );
+ expect(createFile).toHaveBeenCalledWith(
+ expect.objectContaining({
+ filepath: '/uploads/user-123/file-uuid-123__upload.bin',
+ source: FileSources.local,
+ type: 'text/markdown',
+ embedded: true,
+ llmDeliveryPath: 'none',
+ }),
+ true,
+ );
+ });
+
+ test('persists llmDeliveryPath provider for legacy provider uploads without tool_resource', async () => {
+ const { createFile } = require('~/models');
+ const storageUpload = jest.fn().mockResolvedValue({
+ filepath: '/uploads/user-123/file-uuid-123__upload.bin',
+ bytes: 128,
+ filename: 'upload.bin',
+ embedded: false,
+ });
+ getStrategyFunctions.mockReturnValue({ handleFileUpload: storageUpload });
+ mergeFileConfig.mockReturnValue({
+ ...makeFileConfig(),
+ endpoints: {
+ [EModelEndpoint.agents]: { legacyFileUploadUX: true },
+ },
+ defaultLLMDeliveryPath: {
+ fallback: 'none',
+ },
+ });
+ const req = makeReq({ mimetype: 'text/markdown', ocrConfig: null });
+ req.body.endpoint = EModelEndpoint.agents;
+
+ await processAgentFileUpload({
+ req,
+ res: mockRes,
+ metadata: {
+ agent_id: 'agent-abc',
+ message_file: 'true',
+ file_id: 'file-uuid-123',
+ },
+ });
+
+ expect(createFile).toHaveBeenCalledWith(
+ expect.objectContaining({
+ filepath: '/uploads/user-123/file-uuid-123__upload.bin',
+ source: FileSources.local,
+ type: 'text/markdown',
+ llmDeliveryPath: 'provider',
+ }),
+ true,
+ );
+ });
+
+ test('rejects ordinary chat audio when no speech provider can consume it', async () => {
+ /* Transcription needs exactly one non-empty provider block. A schema holding only
+ * allowedAddresses reports STT present while the service refuses it, so routing
+ * audio to text there sends the upload to a transcription that cannot run. */
+ const { createFile } = require('~/models');
+ const storageUpload = jest.fn().mockResolvedValue({
+ filepath: '/uploads/user-123/file-uuid-123__upload.bin',
+ bytes: 128,
+ filename: 'upload.bin',
+ embedded: false,
+ });
+ getStrategyFunctions.mockReturnValue({ handleFileUpload: storageUpload });
+ mergeFileConfig.mockReturnValue(makeFileConfig());
+ const req = makeReq({
+ mimetype: 'audio/mpeg',
+ ocrConfig: null,
+ speech: { stt: { allowedAddresses: ['127.0.0.1'] } },
+ });
+ req.body.endpoint = EModelEndpoint.openAI;
+
+ const error = await processAgentFileUpload({
+ req,
+ res: mockRes,
+ metadata: { agent_id: 'agent-abc', message_file: 'true', file_id: 'file-uuid-123' },
+ }).catch((thrown) => thrown);
+
+ expect(error).toEqual(
+ expect.objectContaining({ message: expect.stringMatching(/no agent/i) }),
+ );
+ expect(createFile).not.toHaveBeenCalled();
+ });
+
+ test('retains an auto-routed context upload as an agent resource', async () => {
+ const { getAgentFileRetentionExpiry } = require('@librechat/api');
+ mergeFileConfig.mockReturnValue(makeFileConfig());
+ const req = makeReq({ mimetype: DOCX_MIME, ocrConfig: null });
+
+ await processAgentFileUpload({
+ req,
+ res: mockRes,
+ metadata: { agent_id: 'agent-abc', file_id: 'file-uuid-123' },
+ }).catch(() => {});
+
+ expect(getAgentFileRetentionExpiry).toHaveBeenCalledWith(
+ expect.objectContaining({ toolResource: EToolResources.context }),
+ expect.any(Object),
+ );
+ });
+
+ test('plans extraction with the promoted context resource for auto-routed text uploads', async () => {
+ const { getUploadExtractedTextPlan } = require('@librechat/api');
+ mergeFileConfig.mockReturnValue(makeFileConfig());
+ const req = makeReq({ mimetype: DOCX_MIME, ocrConfig: null });
+
+ /** The planner runs before extraction; downstream extraction is covered by the
+ * OCR strategy tests, so failures past this point must not mask the argument. */
+ await processAgentFileUpload({
+ req,
+ res: mockRes,
+ metadata: { agent_id: 'agent-abc', file_id: 'file-uuid-123' },
+ }).catch(() => {});
+
+ expect(getUploadExtractedTextPlan).toHaveBeenCalledWith(
+ expect.objectContaining({ toolResource: EToolResources.context }),
+ );
+ });
+
+ test('routes under the provider endpoint the caller resolved', async () => {
+ /* The route resolves the agent's provider once, before validation, and hands it
+ * down so acceptance and routing use one configuration. */
+ const { createFile } = require('~/models');
+ const storageUpload = jest.fn().mockResolvedValue({
+ filepath: '/uploads/user-123/file-uuid-123__upload.bin',
+ bytes: 128,
+ filename: 'upload.bin',
+ embedded: false,
+ });
+ getStrategyFunctions.mockReturnValue({ handleFileUpload: storageUpload });
+ mergeFileConfig.mockReturnValue({
+ ...makeFileConfig(),
+ endpoints: {
+ 'Custom Provider': { defaultLLMDeliveryPath: { fallback: 'none' } },
+ },
+ });
+ const req = makeReq({ mimetype: 'text/markdown', ocrConfig: null });
+ req.body.endpoint = EModelEndpoint.agents;
+
+ await processAgentFileUpload({
+ req,
+ res: mockRes,
+ metadata: {
+ agent_id: 'agent-abc',
+ message_file: 'true',
+ file_id: 'file-uuid-123',
+ effectiveEndpoint: 'Custom Provider',
+ },
+ });
+
+ expect(createFile).toHaveBeenCalledWith(
+ expect.objectContaining({ llmDeliveryPath: 'none' }),
+ true,
+ );
+ });
+
+ test('persists llmDeliveryPath none for explicit execute_code uploads', async () => {
+ const { createFile } = require('~/models');
+ const codeUpload = jest
+ .fn()
+ .mockResolvedValue({ storage_session_id: 'sess-csv', file_id: 'fid-csv' });
+ const storageUpload = jest.fn().mockResolvedValue({
+ filepath: '/uploads/user-123/file-uuid-123__upload.bin',
+ bytes: 128,
+ filename: 'upload.bin',
+ embedded: false,
+ });
+ getStrategyFunctions.mockImplementation((source) => {
+ if (source === FileSources.execute_code) {
+ return { handleFileUpload: codeUpload };
+ }
+ return { handleFileUpload: storageUpload };
+ });
+ mergeFileConfig.mockReturnValue({
+ ...makeFileConfig(),
+ defaultLLMDeliveryPath: {
+ fallback: 'text',
+ },
+ });
+ const req = makeReq({ mimetype: 'text/csv', ocrConfig: null });
+ req.file.path = __filename;
+
+ await processAgentFileUpload({
+ req,
+ res: mockRes,
+ metadata: {
+ ...makeMetadata(),
+ tool_resource: EToolResources.execute_code,
+ },
+ });
+
+ expect(checkCapability).toHaveBeenCalledWith(
+ expect.anything(),
+ AgentCapabilities.execute_code,
+ );
+ expect(createFile).toHaveBeenCalledWith(
+ expect.objectContaining({
+ filepath: '/uploads/user-123/file-uuid-123__upload.bin',
+ source: FileSources.local,
+ type: 'text/csv',
+ metadata: expect.objectContaining({
+ codeEnvRef: {
+ kind: 'agent',
+ id: 'agent-abc',
+ storage_session_id: 'sess-csv',
+ file_id: 'fid-csv',
+ executionProfile: 'default',
+ provisionedAt: expect.any(Number),
+ },
+ codeEnvRefs: {
+ default: {
+ kind: 'agent',
+ id: 'agent-abc',
+ storage_session_id: 'sess-csv',
+ file_id: 'fid-csv',
+ executionProfile: 'default',
+ provisionedAt: expect.any(Number),
+ },
+ },
+ }),
+ llmDeliveryPath: 'none',
+ }),
+ true,
+ );
+ });
+
+ test('persists llmDeliveryPath text for explicit context uploads', async () => {
+ const { parseText } = require('@librechat/api');
+ const { createFile } = require('~/models');
+ const storageUpload = jest.fn().mockResolvedValue({
+ filepath: '/uploads/user-123/file-uuid-123__upload.bin',
+ bytes: 128,
+ filename: 'upload.bin',
+ embedded: false,
+ });
+ getStrategyFunctions.mockReturnValue({ handleFileUpload: storageUpload });
+ mergeFileConfig.mockReturnValue(
+ makeFileConfig({ textSupportedMimeTypes: ['text/markdown'] }),
+ );
+ parseText.mockResolvedValueOnce({ text: 'markdown text', bytes: 13 });
+ const req = makeReq({ mimetype: 'text/markdown', ocrConfig: null });
+
+ await processAgentFileUpload({
+ req,
+ res: mockRes,
+ metadata: {
+ ...makeMetadata(),
+ tool_resource: EToolResources.context,
+ },
+ });
+
+ expect(createFile).toHaveBeenCalledWith(
+ expect.objectContaining({
+ text: 'markdown text',
+ filepath: '/uploads/user-123/file-uuid-123__upload.bin',
+ source: FileSources.local,
+ type: 'text/markdown',
+ llmDeliveryPath: 'text',
+ }),
+ true,
+ );
+ });
+
+ test('normalizes explicit ocr uploads to context text delivery', async () => {
+ const { parseText } = require('@librechat/api');
+ const { createFile, addAgentResourceFile } = require('~/models');
+ const storageUpload = jest.fn().mockResolvedValue({
+ filepath: '/uploads/user-123/file-uuid-123__upload.bin',
+ bytes: 128,
+ filename: 'upload.bin',
+ embedded: false,
+ });
+ getStrategyFunctions.mockReturnValue({ handleFileUpload: storageUpload });
+ mergeFileConfig.mockReturnValue(
+ makeFileConfig({ textSupportedMimeTypes: ['text/markdown'] }),
+ );
+ parseText.mockResolvedValueOnce({ text: 'markdown text', bytes: 13 });
+ const req = makeReq({ mimetype: 'text/markdown', ocrConfig: null });
+
+ await processAgentFileUpload({
+ req,
+ res: mockRes,
+ metadata: {
+ ...makeMetadata(),
+ tool_resource: EToolResources.ocr,
+ },
+ });
+
+ expect(addAgentResourceFile).toHaveBeenCalledWith(
+ expect.objectContaining({
+ file_id: 'file-uuid-123',
+ agent_id: 'agent-abc',
+ tool_resource: EToolResources.context,
+ }),
+ );
+ expect(createFile).toHaveBeenCalledWith(
+ expect.objectContaining({
+ text: 'markdown text',
+ source: FileSources.local,
+ type: 'text/markdown',
+ llmDeliveryPath: 'text',
+ }),
+ true,
+ );
+ });
+ });
+});
+
+describe('processImageFile', () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ mockRes.status.mockReturnThis();
+ mockRes.json.mockReturnValue({});
+ mergeFileConfig.mockReturnValue(makeFileConfig());
+ });
+
+ test('persists resolved llmDeliveryPath for image uploads', async () => {
+ const { createFile } = require('~/models');
+ const handleImageUpload = jest.fn().mockResolvedValue({
+ filepath: '/images/user-123/image.webp',
+ bytes: 256,
+ width: 100,
+ height: 80,
+ });
+ mergeFileConfig.mockReturnValue({
+ ...makeFileConfig(),
+ defaultLLMDeliveryPath: {
+ overrides: { 'image/*': 'none' },
+ },
+ });
+ getStrategyFunctions.mockReturnValue({ handleImageUpload });
+ const req = makeReq({ mimetype: 'image/png', ocrConfig: null });
+
+ await processImageFile({
+ req,
+ res: mockRes,
+ metadata: {
+ file_id: 'image-file-id',
+ temp_file_id: 'temp-image-file-id',
+ endpoint: EModelEndpoint.agents,
+ },
+ });
+
+ expect(createFile).toHaveBeenCalledWith(
+ expect.objectContaining({
+ file_id: 'image-file-id',
+ temp_file_id: 'temp-image-file-id',
+ filepath: '/images/user-123/image.webp',
+ source: FileSources.local,
+ type: 'image/webp',
+ llmDeliveryPath: 'none',
+ }),
+ true,
+ );
+ });
+
+ test('persists provider llmDeliveryPath for legacy image provider uploads', async () => {
+ const { createFile } = require('~/models');
+ const handleImageUpload = jest.fn().mockResolvedValue({
+ filepath: '/images/user-123/image.webp',
+ bytes: 256,
+ width: 100,
+ height: 80,
+ });
+ mergeFileConfig.mockReturnValue({
+ ...makeFileConfig(),
+ endpoints: {
+ [EModelEndpoint.agents]: { legacyFileUploadUX: true },
+ },
+ defaultLLMDeliveryPath: {
+ overrides: { 'image/*': 'none' },
+ },
+ });
+ getStrategyFunctions.mockReturnValue({ handleImageUpload });
+ const req = makeReq({ mimetype: 'image/png', ocrConfig: null });
+ req.body.endpoint = EModelEndpoint.agents;
+
+ await processImageFile({
+ req,
+ res: mockRes,
+ metadata: {
+ file_id: 'image-file-id',
+ temp_file_id: 'temp-image-file-id',
+ endpoint: EModelEndpoint.agents,
+ },
+ });
+
+ expect(createFile).toHaveBeenCalledWith(
+ expect.objectContaining({
+ file_id: 'image-file-id',
+ temp_file_id: 'temp-image-file-id',
+ filepath: '/images/user-123/image.webp',
+ source: FileSources.local,
+ type: 'image/webp',
+ llmDeliveryPath: 'provider',
+ }),
+ true,
+ );
+ });
+
+ test('routes an agent image under the provider endpoint the caller resolved', async () => {
+ const { createFile } = require('~/models');
+ const handleImageUpload = jest.fn().mockResolvedValue({
+ filepath: '/images/user-123/image.webp',
+ bytes: 256,
+ width: 100,
+ height: 80,
+ });
+ mergeFileConfig.mockReturnValue({
+ ...makeFileConfig(),
+ endpoints: {
+ 'Custom Provider': { defaultLLMDeliveryPath: { overrides: { 'image/*': 'none' } } },
+ },
+ });
+ getStrategyFunctions.mockReturnValue({ handleImageUpload });
+ const req = makeReq({ mimetype: 'image/png', ocrConfig: null });
+
+ await processImageFile({
+ req,
+ res: mockRes,
+ metadata: {
+ file_id: 'image-file-id',
+ agent_id: 'agent-abc',
+ endpoint: EModelEndpoint.agents,
+ effectiveEndpoint: 'Custom Provider',
+ },
+ });
+
+ /* Storage still keys off the request endpoint; only delivery routing follows the
+ * resolved provider. */
+ expect(handleImageUpload).toHaveBeenCalledWith(
+ expect.objectContaining({ endpoint: EModelEndpoint.agents }),
+ );
+ expect(createFile).toHaveBeenCalledWith(
+ expect.objectContaining({ llmDeliveryPath: 'none' }),
+ true,
+ );
+ });
});
describe('processFileURL', () => {
@@ -1977,3 +2707,431 @@ describe('startExpiredFileSweep', () => {
expect(interval).toBe('sweep-interval');
});
});
+
+describe('uploads with no consumer on the agent record', () => {
+ test('accepts a type the record shows no tool for', async () => {
+ /* Skills contribute file search and code execution for a turn without being written
+ * to agent.tools, so an empty list is not evidence that nothing will read the file.
+ * Reaching storage, which this suite leaves unwired, proves it was not refused. */
+ const req = makeReq({ mimetype: 'application/zip', ocrConfig: null });
+ req.body.endpoint = EModelEndpoint.agents;
+ getStrategyFunctions.mockClear();
+
+ await processAgentFileUpload({
+ req,
+ res: mockRes,
+ metadata: {
+ agent_id: 'agent-abc',
+ message_file: 'true',
+ file_id: 'file-uuid-zip',
+ agentTools: [],
+ },
+ }).catch(() => {});
+
+ expect(getStrategyFunctions).toHaveBeenCalled();
+ });
+
+ test('accepts a standard-chat attachment for a tool enabled later', async () => {
+ const req = makeReq({ mimetype: 'application/zip', ocrConfig: null });
+ req.body.endpoint = 'Custom Provider';
+ getStrategyFunctions.mockClear();
+
+ await processAgentFileUpload({
+ req,
+ res: mockRes,
+ metadata: {
+ endpoint: 'Custom Provider',
+ message_file: 'true',
+ file_id: 'file-uuid-zip',
+ },
+ }).catch(() => {});
+
+ expect(getStrategyFunctions).toHaveBeenCalled();
+ });
+});
+
+describe('native text fallback', () => {
+ /* The text matcher has to admit the type, or processing refuses before reaching the
+ * reader at all. This mirrors a deployment whose text config accepts these types. */
+ beforeEach(() => {
+ mergeFileConfig.mockReturnValue(
+ makeFileConfig({ textSupportedMimeTypes: [/^image\/png$/, /^text\/plain$/] }),
+ );
+ setupStoredFileUpload();
+ });
+
+ test('does not read a raster image as text when no extractor handles it', async () => {
+ /* An administrator can route images to text; without OCR nothing parses them, and
+ * reading the bytes directly would store mojibake as the file's text. */
+ const { parseText } = require('@librechat/api');
+ const req = makeReq({ mimetype: 'image/png', ocrConfig: null });
+ req.body.endpoint = EModelEndpoint.agents;
+
+ await processAgentFileUpload({
+ req,
+ res: mockRes,
+ metadata: {
+ agent_id: 'agent-abc',
+ message_file: 'true',
+ file_id: 'f-png',
+ tool_resource: 'context',
+ },
+ }).catch(() => {});
+
+ const call = parseText.mock.calls.at(-1)?.[0];
+ expect(call?.allowNativeFallback).toBe(false);
+ });
+
+ test('still reads a text file directly', async () => {
+ const { parseText } = require('@librechat/api');
+ const req = makeReq({ mimetype: 'text/plain', ocrConfig: null });
+ req.body.endpoint = EModelEndpoint.agents;
+
+ await processAgentFileUpload({
+ req,
+ res: mockRes,
+ metadata: {
+ agent_id: 'agent-abc',
+ message_file: 'true',
+ file_id: 'f-txt',
+ tool_resource: 'context',
+ },
+ }).catch(() => {});
+
+ const call = parseText.mock.calls.at(-1)?.[0];
+ expect(call?.allowNativeFallback).toBe(true);
+ });
+});
+
+describe('permanent unified uploads and unknown tool sets', () => {
+ const zipReq = () => {
+ const req = makeReq({ mimetype: 'application/zip', ocrConfig: null });
+ req.body.endpoint = EModelEndpoint.agents;
+ return req;
+ };
+
+ test('does not refuse when the agent tools are unknown', async () => {
+ /* An ephemeral agent has no record to read, so the route reports no tool set and
+ * processing must not conclude that nothing can consume the file. */
+ const error = await processAgentFileUpload({
+ req: zipReq(),
+ res: mockRes,
+ metadata: { agent_id: 'agent-abc', message_file: 'true', file_id: 'f-eph' },
+ }).catch((thrown) => thrown);
+
+ expect(String(error?.message ?? '')).not.toMatch(/code interpreter or file search/i);
+ });
+
+ test('files a permanent upload under the tool that will consume it', async () => {
+ const { addAgentResourceFile } = require('~/models');
+ setupStoredFileUpload();
+ /* The code-env branch streams the upload from disk after this assertion resolves, and
+ * an unhandled stream error would take down the worker. Left in place rather than
+ * cleaned up, since the read happens later than the test body. */
+ jest.requireActual('fs').writeFileSync('/tmp/upload.bin', 'zip');
+
+ await processAgentFileUpload({
+ req: zipReq(),
+ res: mockRes,
+ metadata: {
+ agent_id: 'agent-abc',
+ file_id: 'f-perm',
+ agentTools: [EToolResources.execute_code],
+ },
+ }).catch(() => {});
+
+ expect(addAgentResourceFile).toHaveBeenCalledWith(
+ expect.objectContaining({ tool_resource: EToolResources.execute_code }),
+ );
+ });
+
+ test('records the converted image format rather than the upload type', async () => {
+ /* The stored bytes are the converted image. Keeping the upload's type leaves a later
+ * reprovision handing the sandbox webp bytes under a .jpg name, which the rename
+ * cannot catch because the extension already matches the stale type. */
+ const handleImageUpload = jest.fn().mockResolvedValue({
+ filepath: '/uploads/photo.webp',
+ bytes: 64,
+ width: 10,
+ height: 10,
+ });
+ const storedFileUpload = jest.fn().mockResolvedValue({
+ bytes: 4096,
+ filename: 'photo.jpg',
+ filepath: '/uploads/photo.jpg',
+ });
+ getStrategyFunctions.mockReturnValue({
+ handleImageUpload,
+ handleFileUpload: storedFileUpload,
+ });
+ const req = makeReq({ mimetype: 'image/jpeg', ocrConfig: null });
+ req.body.endpoint = EModelEndpoint.agents;
+
+ await processAgentFileUpload({
+ req,
+ res: mockRes,
+ metadata: { agent_id: 'agent-abc', message_file: 'true', file_id: 'f-image' },
+ }).catch(() => {});
+
+ expect(db.createFile).toHaveBeenLastCalledWith(
+ expect.objectContaining({ file_id: 'f-image', type: 'image/webp' }),
+ true,
+ );
+ /* The conversion runs under an id of its own, so persisting it too would leave a
+ * message-attachment row referenced by nothing beside the record above. */
+ expect(db.createFile).toHaveBeenCalledTimes(1);
+ /* And the conversion is the only storage write: uploading the original first left a
+ * second object nothing references. */
+ expect(handleImageUpload).toHaveBeenCalledTimes(1);
+ expect(storedFileUpload).not.toHaveBeenCalled();
+ /* Size and dimensions describe the bytes actually stored, which the persistent-file
+ * screening later charges against the agent's allowance. */
+ expect(db.createFile).toHaveBeenLastCalledWith(
+ expect.objectContaining({ bytes: 64, width: 10, height: 10 }),
+ true,
+ );
+ });
+
+ test('treats an explicit message_file of "false" as a permanent upload', async () => {
+ /* Multipart form values arrive as strings, so the truthy reading made "false" mean
+ * message attachment while the route had already classified it as permanent. The
+ * upload reported success and filed nothing against the agent. */
+ const { addAgentResourceFile } = require('~/models');
+ setupStoredFileUpload();
+
+ await processAgentFileUpload({
+ req: zipReq(),
+ res: mockRes,
+ metadata: {
+ agent_id: 'agent-abc',
+ message_file: 'false',
+ file_id: 'f-explicit-false',
+ agentTools: [EToolResources.execute_code],
+ },
+ }).catch(() => {});
+
+ expect(addAgentResourceFile).toHaveBeenCalledWith(
+ expect.objectContaining({ tool_resource: EToolResources.execute_code }),
+ );
+ });
+
+ test('skips a consumer whose capability is disabled', async () => {
+ /* Otherwise the choice depends on the persisted tool order: code execution listed
+ * first would be selected and then rejected, while file search could have kept it. */
+ const { addAgentResourceFile } = require('~/models');
+ setupStoredFileUpload();
+ checkCapability.mockImplementation(
+ async (_req, capability) => capability !== AgentCapabilities.execute_code,
+ );
+
+ /* A searchable type routed off the model path, since a consumer is only chosen for a
+ * file kept off it, and only one that can read the file. */
+ mergeFileConfig.mockReturnValue({
+ ...makeFileConfig(),
+ defaultLLMDeliveryPath: { overrides: { [PDF_MIME]: 'none' } },
+ });
+ const req = makeReq({ mimetype: PDF_MIME, ocrConfig: null });
+ req.body.endpoint = EModelEndpoint.agents;
+
+ await processAgentFileUpload({
+ req,
+ res: mockRes,
+ metadata: {
+ agent_id: 'agent-abc',
+ file_id: 'f-disabled',
+ agentTools: [EToolResources.execute_code, EToolResources.file_search],
+ },
+ }).catch(() => {});
+
+ expect(addAgentResourceFile).toHaveBeenCalledWith(
+ expect.objectContaining({ tool_resource: EToolResources.file_search }),
+ );
+ checkCapability.mockResolvedValue(true);
+ });
+
+ test('chooses an authorized consumer before routing an inferred destination', async () => {
+ const { addAgentResourceFile } = require('~/models');
+ const { resolveToolRoleGrants } = require('@librechat/api');
+ setupStoredFileUpload();
+ resolveToolRoleGrants.mockResolvedValueOnce({ runCode: false, fileSearch: true });
+ mergeFileConfig.mockReturnValue({
+ ...makeFileConfig(),
+ defaultLLMDeliveryPath: { overrides: { [PDF_MIME]: 'none' } },
+ });
+ const req = makeReq({ mimetype: PDF_MIME, ocrConfig: null });
+ req.body.endpoint = EModelEndpoint.agents;
+
+ await processAgentFileUpload({
+ req,
+ res: mockRes,
+ metadata: {
+ agent_id: 'agent-abc',
+ file_id: 'f-role-filtered',
+ agentTools: [EToolResources.execute_code, EToolResources.file_search],
+ },
+ });
+
+ expect(addAgentResourceFile).toHaveBeenCalledWith(
+ expect.objectContaining({ tool_resource: EToolResources.file_search }),
+ );
+ expect(resolveToolRoleGrants).toHaveBeenCalledTimes(1);
+ });
+
+ test('records a named destination as chosen in unified mode', async () => {
+ /* The marker asks whether the user named a destination, not which endpoint mode was
+ * on. Recording the mode treats an explicitly sandbox-only upload as inferred, and
+ * delivery then re-resolves it onto the model path. */
+ setupStoredFileUpload();
+ const req = makeReq({ mimetype: PDF_MIME, ocrConfig: null });
+ req.body.endpoint = EModelEndpoint.agents;
+
+ await processAgentFileUpload({
+ req,
+ res: mockRes,
+ metadata: {
+ agent_id: 'agent-abc',
+ tool_resource: EToolResources.file_search,
+ file_id: 'f-named',
+ },
+ }).catch(() => {});
+
+ expect(db.createFile).toHaveBeenCalledWith(
+ expect.objectContaining({
+ metadata: expect.objectContaining({ destinationChosen: true }),
+ }),
+ true,
+ );
+ });
+
+ test('records the agent namespace on an eagerly embedded file', async () => {
+ /* Vectors go in under entity_id, and priming asks which namespaces hold them rather
+ * than reading the root flag, so omitting this re-embeds on the first search and
+ * aborts that search when RAG is briefly unavailable. */
+ setupStoredFileUpload();
+ const req = makeReq({ mimetype: PDF_MIME, ocrConfig: null });
+ req.body.endpoint = EModelEndpoint.agents;
+
+ await processAgentFileUpload({
+ req,
+ res: mockRes,
+ metadata: {
+ agent_id: 'agent-abc',
+ tool_resource: EToolResources.file_search,
+ file_id: 'f-embedded',
+ },
+ }).catch(() => {});
+
+ expect(db.createFile).toHaveBeenCalledWith(
+ expect.objectContaining({
+ metadata: expect.objectContaining({ embeddedEntities: ['agent-abc'] }),
+ }),
+ true,
+ );
+ });
+
+ test('names the destination that refused the file, not file search', async () => {
+ /* The message is the only thing telling the reader which tool rejected the upload,
+ * and reporting an image sent to file search for an audio file sent to the code
+ * interpreter describes neither the file nor the destination. */
+ const req = makeReq({ mimetype: 'audio/mpeg', ocrConfig: null });
+ req.body.endpoint = EModelEndpoint.agents;
+
+ await expect(
+ processAgentFileUpload({
+ req,
+ res: mockRes,
+ metadata: {
+ agent_id: 'agent-abc',
+ tool_resource: EToolResources.execute_code,
+ file_id: 'f-audio',
+ },
+ }),
+ ).rejects.toThrow(/audio\/mpeg.*code interpreter/i);
+ });
+
+ test('refuses a permanent upload that would land on no agent resource', async () => {
+ /* Delivered straight to the model, with no agent resource to hold it, storing it
+ * would report success while leaving the agent without a reference. */
+ const req = makeReq({ mimetype: 'image/png', ocrConfig: null });
+ req.body.endpoint = EModelEndpoint.agents;
+
+ await expect(
+ processAgentFileUpload({
+ req,
+ res: mockRes,
+ metadata: { agent_id: 'agent-abc', file_id: 'f-orphan', agentTools: [] },
+ }),
+ ).rejects.toThrow(/cannot be saved to an agent on their own/i);
+ });
+});
+
+describe('filterFile endpoint resolution', () => {
+ /* getEndpointFileConfig consults endpointType ahead of endpoint, so a composer upload
+ * carrying `agents` would keep the Agents policy and shadow the provider the caller
+ * resolved. */
+ /* mergeFileConfig is mocked here, so these are raw byte values rather than the
+ * megabytes an admin would write. The agents policy refuses the file on size and the
+ * provider policy accepts it, which makes the assertions read as which one governed. */
+ const policyConfig = {
+ ...makeFileConfig(),
+ endpoints: {
+ default: {
+ disabled: false,
+ fileLimit: 10,
+ fileSizeLimit: 1_000_000,
+ totalSizeLimit: 1_000_000,
+ supportedMimeTypes: [/^image\/png$/],
+ },
+ agents: { fileSizeLimit: 1 },
+ 'Custom Provider': { fileSizeLimit: 1_000_000 },
+ },
+ };
+
+ const makeFilterReq = (endpointType) => ({
+ body: {
+ endpoint: EModelEndpoint.agents,
+ ...(endpointType ? { endpointType } : {}),
+ file_id: '00000000-0000-4000-8000-000000000000',
+ width: 1,
+ height: 1,
+ },
+ file: { size: 10, mimetype: 'image/png', originalname: 'a.png' },
+ config: {},
+ });
+
+ beforeEach(() => {
+ mergeFileConfig.mockReturnValue(policyConfig);
+ });
+
+ test('applies the resolved provider policy even when the request names an endpoint type', () => {
+ expect(() =>
+ filterFile({ req: makeFilterReq('agents'), image: true, endpoint: 'Custom Provider' }),
+ ).not.toThrow();
+ });
+
+ test('keeps the request endpoint type when no override is given', () => {
+ expect(() => filterFile({ req: makeFilterReq('agents'), image: true })).toThrow(/size limit/i);
+ });
+
+ test('rejects endpoint uploads when the resolved provider disables files', () => {
+ policyConfig.endpoints['Disabled Provider'] = {
+ ...policyConfig.endpoints.default,
+ disabled: true,
+ };
+
+ expect(() =>
+ filterFile({ req: makeFilterReq('agents'), image: true, endpoint: 'Disabled Provider' }),
+ ).toThrow(/uploads are disabled/i);
+ });
+
+ test('does not apply an endpoint disabled flag to avatars', () => {
+ policyConfig.endpoints['Disabled Provider'] = {
+ ...policyConfig.endpoints.default,
+ disabled: true,
+ };
+ const req = makeFilterReq();
+ req.body.endpoint = 'Disabled Provider';
+
+ expect(() => filterFile({ req, image: true, isAvatar: true })).not.toThrow();
+ });
+});
diff --git a/api/server/services/Files/provision.js b/api/server/services/Files/provision.js
new file mode 100644
index 0000000000..32311cc500
--- /dev/null
+++ b/api/server/services/Files/provision.js
@@ -0,0 +1,23 @@
+const { createProvisionService } = require('@librechat/api');
+const { loadAuthValues } = require('~/server/services/Tools/credentials');
+const { uploadVectors } = require('./VectorDB/crud');
+const { getStrategyFunctions } = require('./strategies');
+
+/* Wiring only: the provisioning logic lives in packages/api, where it is type checked.
+ * Storage strategies, vector upload, and credential lookup are api-workspace concerns,
+ * so they are bound here and injected.
+ *
+ * Built on first use rather than at module load: this module is reachable from the
+ * OpenAI-compatible controllers, whose suites partially mock @librechat/api, and a
+ * load-time call would throw before any provisioning is requested. */
+let service;
+const getService = () =>
+ (service ??= createProvisionService({ getStrategyFunctions, uploadVectors, loadAuthValues }));
+
+module.exports = {
+ loadCodeApiKey: (...args) => getService().loadCodeApiKey(...args),
+ provisionToCodeEnv: (...args) => getService().provisionToCodeEnv(...args),
+ provisionToVectorDB: (...args) => getService().provisionToVectorDB(...args),
+ checkCodeEnvFileAlive: (...args) => getService().checkCodeEnvFileAlive(...args),
+ checkSessionsAlive: (...args) => getService().checkSessionsAlive(...args),
+};
diff --git a/api/server/services/Files/provisionCallback.js b/api/server/services/Files/provisionCallback.js
new file mode 100644
index 0000000000..328cca2d9b
--- /dev/null
+++ b/api/server/services/Files/provisionCallback.js
@@ -0,0 +1,20 @@
+const { createProvisionFilesCallback: createCallback } = require('@librechat/api');
+const { provisionToCodeEnv, provisionToVectorDB } = require('~/server/services/Files/provision');
+const db = require('~/models');
+
+/* Wiring only: binds this workspace's provisioning service and file model to the
+ * ON_TOOL_EXECUTE callback implemented in packages/api. */
+function createProvisionFilesCallback({ req, agentToolContexts, resolvePrimaryAgentId }) {
+ return createCallback({
+ req,
+ agentToolContexts,
+ resolvePrimaryAgentId,
+ provisionToCodeEnv,
+ provisionToVectorDB,
+ updateFile: db.updateFile,
+ updateCodeEnvRef: db.updateFileCodeEnvRef,
+ addEmbeddedEntity: db.addFileEmbeddedEntity,
+ });
+}
+
+module.exports = { createProvisionFilesCallback };
diff --git a/api/server/services/Files/routing.js b/api/server/services/Files/routing.js
new file mode 100644
index 0000000000..0a22fa880f
--- /dev/null
+++ b/api/server/services/Files/routing.js
@@ -0,0 +1,24 @@
+const {
+ resolveUploadAgent: resolveAgent,
+ resolveEffectiveToolResource: resolveToolResource,
+ resolveUploadEndpoint: resolveEndpoint,
+ resolveUploadLLMDeliveryPath,
+} = require('@librechat/api');
+const db = require('~/models');
+
+/* Wiring only: binds this workspace's agent model to the upload routing implemented in
+ * packages/api. */
+const resolveUploadAgent = (req, agent_id) => resolveAgent(req, agent_id, db.getAgent);
+
+const resolveUploadEndpoint = ({ endpoint, agent_id, req }) =>
+ resolveEndpoint({ req, metadata: { endpoint, agent_id }, getAgent: db.getAgent });
+
+const resolveEffectiveToolResource = ({ req, metadata }) =>
+ resolveToolResource({ req, metadata, getAgent: db.getAgent });
+
+module.exports = {
+ resolveUploadAgent,
+ resolveUploadEndpoint,
+ resolveUploadLLMDeliveryPath,
+ resolveEffectiveToolResource,
+};
diff --git a/api/server/services/__tests__/toolCapabilityGates.spec.js b/api/server/services/__tests__/toolCapabilityGates.spec.js
index d50f1ba1e7..56820fec4b 100644
--- a/api/server/services/__tests__/toolCapabilityGates.spec.js
+++ b/api/server/services/__tests__/toolCapabilityGates.spec.js
@@ -37,8 +37,10 @@ const CLASSIFIED = {
'api/server/controllers/agents/responses.js': 2,
/** `codeEnvAvailable` for the memory-agent initializer. */
'api/server/controllers/agents/client.js': 1,
- /** Upload processing: the code-environment and file-search branches. */
- 'api/server/services/Files/process.js': 2,
+ /** Upload processing: two consumer-map entries, the role-gated consumer checks,
+ * and the code-environment/file-search branches. All consumer selection shares
+ * the role grant resolved before routing. */
+ 'api/server/services/Files/process.js': 5,
/** Agent-management upload purposes. */
'api/server/routes/agents/management.js': 2,
/** Two gates, each paired when the embedder wires `getRoleByName`; one in a
diff --git a/client/src/Providers/DragDropContext.tsx b/client/src/Providers/DragDropContext.tsx
index eae5f0165f..c7c5fc076f 100644
--- a/client/src/Providers/DragDropContext.tsx
+++ b/client/src/Providers/DragDropContext.tsx
@@ -1,8 +1,6 @@
import React, { createContext, useContext, useMemo } from 'react';
-import { isAgentsEndpoint, resolveEndpointType } from 'librechat-data-provider';
import type { EModelEndpoint } from 'librechat-data-provider';
-import { useGetEndpointsQuery, useGetAgentByIdQuery } from '~/data-provider';
-import { useAgentsMapContext } from './AgentsMapContext';
+import useAgentUploadTarget from '~/hooks/Agents/useAgentUploadTarget';
import { useChatContext } from './ChatContext';
interface DragDropContextValue {
@@ -17,51 +15,7 @@ const DragDropContext = createContext<DragDropContextValue | undefined>(undefine
export function DragDropProvider({ children }: { children: React.ReactNode }) {
const { conversation } = useChatContext();
- const { data: endpointsConfig } = useGetEndpointsQuery();
- const agentsMap = useAgentsMapContext();
-
- const needsAgentFetch = useMemo(() => {
- const isAgents = isAgentsEndpoint(conversation?.endpoint);
- if (!isAgents || !conversation?.agent_id) {
- return false;
- }
- const agent = agentsMap?.[conversation.agent_id];
- return !agent?.model_parameters;
- }, [conversation?.endpoint, conversation?.agent_id, agentsMap]);
-
- const { data: agentData } = useGetAgentByIdQuery(conversation?.agent_id, {
- enabled: needsAgentFetch,
- });
-
- const agentProvider = useMemo(() => {
- const isAgents = isAgentsEndpoint(conversation?.endpoint);
- if (!isAgents || !conversation?.agent_id) {
- return undefined;
- }
- return agentData?.provider ?? agentsMap?.[conversation.agent_id]?.provider;
- }, [conversation?.endpoint, conversation?.agent_id, agentData, agentsMap]);
-
- const endpointType = useMemo(
- () => resolveEndpointType(endpointsConfig, conversation?.endpoint, agentProvider),
- [endpointsConfig, conversation?.endpoint, agentProvider],
- );
-
- const useResponsesApi = useMemo(() => {
- const isAgents = isAgentsEndpoint(conversation?.endpoint);
- if (!isAgents || !conversation?.agent_id || conversation?.useResponsesApi !== undefined) {
- return conversation?.useResponsesApi;
- }
- return (
- agentData?.model_parameters?.useResponsesApi ??
- agentsMap?.[conversation.agent_id]?.model_parameters?.useResponsesApi
- );
- }, [
- conversation?.endpoint,
- conversation?.agent_id,
- conversation?.useResponsesApi,
- agentData,
- agentsMap,
- ]);
+ const { endpointType, useResponsesApi } = useAgentUploadTarget(conversation);
/** Context value only created when conversation fields change */
const contextValue = useMemo<DragDropContextValue>(
diff --git a/client/src/Providers/__tests__/DragDropContext.spec.tsx b/client/src/Providers/__tests__/DragDropContext.spec.tsx
index 12a5edbb0a..946ced7de2 100644
--- a/client/src/Providers/__tests__/DragDropContext.spec.tsx
+++ b/client/src/Providers/__tests__/DragDropContext.spec.tsx
@@ -136,7 +136,9 @@ describe('DragDropContext endpointType resolution', () => {
expect(result.current.useResponsesApi).toBe(true);
});
- it('preserves an explicit conversation useResponsesApi false override', () => {
+ it('lets the saved agent decide over the conversation', () => {
+ /* Execution reads the agent's own model parameters, so predicting the conversation
+ * here routes an upload the turn then resolves the other way. */
mockConversation = {
endpoint: EModelEndpoint.agents,
agent_id: 'agent-1',
@@ -147,7 +149,21 @@ describe('DragDropContext endpointType resolution', () => {
model_parameters: { useResponsesApi: true },
} as Partial<Agent>;
const { result } = renderHook(() => useDragDropContext(), { wrapper });
- expect(result.current.useResponsesApi).toBe(false);
+ expect(result.current.useResponsesApi).toBe(true);
+ });
+
+ it('keeps the conversation setting when the agent states none', () => {
+ mockConversation = {
+ endpoint: EModelEndpoint.agents,
+ agent_id: 'agent-1',
+ useResponsesApi: true,
+ };
+ mockAgentQueryData = {
+ provider: EModelEndpoint.azureOpenAI,
+ model_parameters: {},
+ } as Partial<Agent>;
+ const { result } = renderHook(() => useDragDropContext(), { wrapper });
+ expect(result.current.useResponsesApi).toBe(true);
});
});
diff --git a/client/src/components/Chat/Input/Files/AttachFileChat.tsx b/client/src/components/Chat/Input/Files/AttachFileChat.tsx
index 89bd49f0ae..5395b8351b 100644
--- a/client/src/components/Chat/Input/Files/AttachFileChat.tsx
+++ b/client/src/components/Chat/Input/Files/AttachFileChat.tsx
@@ -4,14 +4,15 @@ import {
supportsFiles,
mergeFileConfig,
isAgentsEndpoint,
- resolveEndpointType,
+ isEphemeralAgentId,
isAssistantsEndpoint,
getEndpointFileConfig,
} from 'librechat-data-provider';
import type { TConversation } from 'librechat-data-provider';
import type { ExtendedFile, FileSetter } from '~/common';
-import { useGetFileConfig, useGetEndpointsQuery, useGetAgentByIdQuery } from '~/data-provider';
-import { useAgentsMapContext } from '~/Providers';
+import useAgentUploadTarget from '~/hooks/Agents/useAgentUploadTarget';
+import { useGetFileConfig } from '~/data-provider';
+import { isUnifiedUploadMode } from '~/utils';
import AttachFileMenu from './AttachFileMenu';
import AttachFile from './AttachFile';
@@ -33,48 +34,14 @@ function AttachFileChat({
const isAgents = useMemo(() => isAgentsEndpoint(endpoint), [endpoint]);
const isAssistants = useMemo(() => isAssistantsEndpoint(endpoint), [endpoint]);
- const agentsMap = useAgentsMapContext();
+ const { agentProvider, endpointType, useResponsesApi } = useAgentUploadTarget(conversation);
- const needsAgentFetch = useMemo(() => {
- if (!isAgents || !conversation?.agent_id) {
- return false;
- }
- const agent = agentsMap?.[conversation.agent_id];
- return !agent?.model_parameters;
- }, [isAgents, conversation?.agent_id, agentsMap]);
-
- const { data: agentData } = useGetAgentByIdQuery(conversation?.agent_id, {
- enabled: needsAgentFetch,
- });
-
- const useResponsesApi = useMemo(() => {
- if (!isAgents || !conversation?.agent_id || conversation?.useResponsesApi !== undefined) {
- return conversation?.useResponsesApi;
- }
- return (
- agentData?.model_parameters?.useResponsesApi ??
- agentsMap?.[conversation.agent_id]?.model_parameters?.useResponsesApi
- );
- }, [isAgents, conversation?.agent_id, conversation?.useResponsesApi, agentData, agentsMap]);
-
- const { data: fileConfig = null } = useGetFileConfig({
+ /* Success, not merely settled: a failed or paused fetch leaves the built-in defaults in
+ * place, where the absent opt-out reads as unified. */
+ const { data: fileConfig = null, isSuccess: isFileConfigLoaded } = useGetFileConfig({
select: (data) => mergeFileConfig(data),
});
- const { data: endpointsConfig } = useGetEndpointsQuery();
-
- const agentProvider = useMemo(() => {
- if (!isAgents || !conversation?.agent_id) {
- return undefined;
- }
- return agentData?.provider ?? agentsMap?.[conversation.agent_id]?.provider;
- }, [isAgents, conversation?.agent_id, agentData, agentsMap]);
-
- const endpointType = useMemo(
- () => resolveEndpointType(endpointsConfig, endpoint, agentProvider),
- [endpointsConfig, endpoint, agentProvider],
- );
-
const fileConfigEndpoint = useMemo(
() => (isAgents && agentProvider ? agentProvider : endpoint),
[isAgents, agentProvider, endpoint],
@@ -96,6 +63,19 @@ function AttachFileChat({
() => (disableInputs || endpointFileConfig?.disabled) ?? false,
[disableInputs, endpointFileConfig?.disabled],
);
+ /* A saved agent's policy lives under its provider, so nothing is resolved for it until
+ * that provider is known; until then endpointFileConfig is the generic agents entry.
+ * An ephemeral agent has no record to fetch, so waiting on one never ends. */
+ const isSavedAgent =
+ isAgents && conversation?.agent_id != null && !isEphemeralAgentId(conversation.agent_id);
+ const isPolicyResolved = isFileConfigLoaded && (!isSavedAgent || agentProvider != null);
+
+ /* Resolved here rather than in the menu: an unresolved config reads as unified, which
+ * would show the wrong uploader on a legacy deployment. */
+ const isUnifiedMode = useMemo(
+ () => isUnifiedUploadMode(endpointFileConfig, isPolicyResolved),
+ [endpointFileConfig, isPolicyResolved],
+ );
if (isAssistants && endpointSupportsFiles && !isUploadDisabled) {
return (
@@ -111,11 +91,15 @@ function AttachFileChat({
return (
<AttachFileMenu
endpoint={endpoint}
- disabled={disableInputs}
+ /* Inert until the config resolves: the menu is an action, not just a display, and
+ * offering the chooser here submits an explicit destination a unified deployment
+ * would have inferred. The drag and paste paths hold for the same reason. */
+ disabled={disableInputs || !isPolicyResolved}
endpointType={endpointType}
conversationId={conversationId}
agentId={conversation?.agent_id}
endpointFileConfig={endpointFileConfig}
+ isUnifiedMode={isUnifiedMode}
useResponsesApi={useResponsesApi}
files={files}
setFiles={setFiles}
diff --git a/client/src/components/Chat/Input/Files/AttachFileMenu.tsx b/client/src/components/Chat/Input/Files/AttachFileMenu.tsx
index 8c35af1747..71f89b03ee 100644
--- a/client/src/components/Chat/Input/Files/AttachFileMenu.tsx
+++ b/client/src/components/Chat/Input/Files/AttachFileMenu.tsx
@@ -9,6 +9,7 @@ import {
TerminalSquareIcon,
} from 'lucide-react';
import {
+ IconButton,
FileUpload,
TooltipAnchor,
DropdownPopup,
@@ -76,6 +77,8 @@ interface AttachFileMenuProps {
conversationId: string;
endpointType?: EModelEndpoint | string;
endpointFileConfig?: EndpointFileConfig;
+ /** Resolved by the parent, which knows whether the file config has landed. */
+ isUnifiedMode: boolean;
useResponsesApi?: boolean;
files: Map<string, ExtendedFile>;
setFiles: FileSetter;
@@ -90,6 +93,7 @@ const AttachFileMenu = ({
endpointType,
conversationId,
endpointFileConfig,
+ isUnifiedMode,
useResponsesApi,
files,
setFiles,
@@ -164,11 +168,38 @@ const AttachFileMenu = ({
inputRef.current.accept = '';
}
inputRef.current.click();
- inputRef.current.accept = '';
},
[endpointFileConfig?.supportedMimeTypes],
);
+ /** Unified mode: single click triggers file upload with no tool_resource */
+ const handleUnifiedUpload = useCallback(() => {
+ toolResourceRef.current = undefined;
+ handleUploadClick();
+ }, [handleUploadClick]);
+
+ /** Unified mode removed the destination chooser, not the source chooser. SharePoint has
+ * no trigger of its own, so without this the picker becomes unreachable whenever the
+ * composer is in unified mode. Destination stays implicit on both sources. */
+ const unifiedSourceItems = useMemo<MenuItemProps[]>(
+ () => [
+ {
+ label: localize('com_files_upload_local_machine'),
+ onClick: handleUnifiedUpload,
+ icon: <FileImageIcon className="icon-md" />,
+ },
+ {
+ label: localize('com_files_upload_sharepoint'),
+ onClick: () => {
+ toolResourceRef.current = undefined;
+ setIsSharePointDialogOpen(true);
+ },
+ icon: <SharePointIcon className="icon-md" />,
+ },
+ ],
+ [localize, handleUnifiedUpload, setIsSharePointDialogOpen],
+ );
+
const dropdownItems = useMemo(() => {
const setToolResource = (value: EToolResources | undefined) => {
toolResourceRef.current = value;
@@ -330,6 +361,63 @@ const AttachFileMenu = ({
}
};
+ if (isUnifiedMode) {
+ return (
+ <>
+ <FileUpload
+ ref={inputRef}
+ handleFileChange={(e) => {
+ handleFileChange(e, toolResourceRef.current);
+ }}
+ >
+ {sharePointEnabled === true ? (
+ <DropdownPopup
+ menuId="attach-file-menu"
+ className="overflow-visible"
+ isOpen={isPopoverActive}
+ setIsOpen={setIsPopoverActive}
+ modal={false}
+ portal={true}
+ unmountOnHide={true}
+ trigger={menuTrigger}
+ items={unifiedSourceItems}
+ iconClassName="mr-0"
+ />
+ ) : (
+ <TooltipAnchor
+ render={
+ <IconButton
+ type="button"
+ size="theme"
+ shape="theme"
+ disabled={isUploadDisabled}
+ id="attach-file-button"
+ label={localize('com_sidepanel_attach_files')}
+ onClick={handleUnifiedUpload}
+ aria-keyshortcuts={uploadFileAriaKey}
+ className="p-1 hover:bg-surface-composer-hover"
+ >
+ <AttachmentIcon />
+ </IconButton>
+ }
+ id="attach-file-button"
+ description={uploadFileTooltip}
+ disabled={isUploadDisabled}
+ />
+ )}
+ </FileUpload>
+ <SharePointPickerDialog
+ isOpen={isSharePointDialogOpen}
+ onOpenChange={setIsSharePointDialogOpen}
+ onFilesSelected={handleSharePointFilesSelected}
+ isDownloading={isProcessing}
+ downloadProgress={downloadProgress}
+ maxSelectionCount={endpointFileConfig?.fileLimit}
+ />
+ </>
+ );
+ }
+
return (
<>
<FileUpload
diff --git a/client/src/components/Chat/Input/Files/__tests__/AttachFileChat.spec.tsx b/client/src/components/Chat/Input/Files/__tests__/AttachFileChat.spec.tsx
index 3ac3d33be9..eef31f49db 100644
--- a/client/src/components/Chat/Input/Files/__tests__/AttachFileChat.spec.tsx
+++ b/client/src/components/Chat/Input/Files/__tests__/AttachFileChat.spec.tsx
@@ -25,11 +25,13 @@ let mockFileConfig = defaultFileConfig;
let mockAgentsMap: Record<string, Partial<Agent>> = {};
let mockAgentQueryData: Partial<Agent> | undefined;
+let mockFileConfigLoaded = true;
jest.mock('~/data-provider', () => ({
useGetEndpointsQuery: () => ({ data: mockEndpointsConfig }),
useGetFileConfig: ({ select }: { select?: (data: unknown) => unknown }) => ({
data: select != null ? select(mockFileConfig) : mockFileConfig,
+ isSuccess: mockFileConfigLoaded,
}),
useGetAgentByIdQuery: () => ({ data: mockAgentQueryData }),
}));
@@ -38,6 +40,12 @@ jest.mock('~/Providers', () => ({
useAgentsMapContext: () => mockAgentsMap,
}));
+/* The shared upload-target hook reads the module directly rather than the barrel, so
+ * the barrel mock alone leaves it with no agents map. */
+jest.mock('~/Providers/AgentsMapContext', () => ({
+ useAgentsMapContext: () => mockAgentsMap,
+}));
+
/** Capture the props passed to AttachFileMenu */
let mockAttachFileMenuProps: Record<string, unknown> = {};
jest.mock('../AttachFileMenu', () => {
@@ -77,6 +85,7 @@ describe('AttachFileChat', () => {
mockAgentsMap = {};
mockAgentQueryData = undefined;
mockAttachFileMenuProps = {};
+ mockFileConfigLoaded = true;
});
describe('rendering decisions', () => {
@@ -161,7 +170,9 @@ describe('AttachFileChat', () => {
expect(mockAttachFileMenuProps.useResponsesApi).toBe(true);
});
- it('preserves an explicit conversation useResponsesApi false override', () => {
+ it('lets the saved agent decide over the conversation', () => {
+ /* Execution reads the agent's own model parameters, so the attach menu must offer
+ * what the turn will actually do rather than what the conversation says. */
mockAgentQueryData = {
provider: EModelEndpoint.azureOpenAI,
model_parameters: { useResponsesApi: true },
@@ -171,7 +182,20 @@ describe('AttachFileChat', () => {
agent_id: 'agent-1',
useResponsesApi: false,
});
- expect(mockAttachFileMenuProps.useResponsesApi).toBe(false);
+ expect(mockAttachFileMenuProps.useResponsesApi).toBe(true);
+ });
+
+ it('keeps the conversation setting when the agent states none', () => {
+ mockAgentQueryData = {
+ provider: EModelEndpoint.azureOpenAI,
+ model_parameters: {},
+ } as Partial<Agent>;
+ renderComponent({
+ endpoint: EModelEndpoint.agents,
+ agent_id: 'agent-1',
+ useResponsesApi: true,
+ });
+ expect(mockAttachFileMenuProps.useResponsesApi).toBe(true);
});
});
@@ -282,3 +306,64 @@ describe('AttachFileChat', () => {
});
});
});
+
+describe('AttachFileChat upload config gating', () => {
+ beforeEach(() => {
+ mockFileConfig = defaultFileConfig;
+ mockAgentsMap = {};
+ mockAgentQueryData = undefined;
+ mockAttachFileMenuProps = {};
+ });
+
+ it('leaves the attach menu inert until the file config resolves', () => {
+ /* The menu is an action, not just a display: offering the chooser here submits an
+ * explicit destination a unified deployment would have inferred, and after a failed
+ * fetch it would keep offering it. */
+ mockFileConfigLoaded = false;
+
+ renderComponent({ endpoint: EModelEndpoint.agents });
+
+ expect(mockAttachFileMenuProps.disabled).toBe(true);
+ });
+
+ it('enables it once the config lands', () => {
+ mockFileConfigLoaded = true;
+
+ renderComponent({ endpoint: EModelEndpoint.agents });
+
+ expect(mockAttachFileMenuProps.disabled).toBe(false);
+ });
+
+ it('keeps it inert while a saved agent provider is still being fetched', () => {
+ /* The config can succeed before the agent does, and until then endpointFileConfig is
+ * the generic agents entry rather than the provider's. */
+ mockFileConfigLoaded = true;
+ mockAgentsMap = {};
+ mockAgentQueryData = undefined;
+
+ renderComponent({ endpoint: EModelEndpoint.agents, agent_id: 'agent_saved01' });
+
+ expect(mockAttachFileMenuProps.disabled).toBe(true);
+ });
+
+ it('does not wait on a provider an ephemeral agent will never have', () => {
+ /* There is no record to fetch for one, so gating on its provider never lifts and the
+ * attach control stays disabled for the whole conversation. */
+ mockFileConfigLoaded = true;
+ mockAgentsMap = {};
+ mockAgentQueryData = undefined;
+
+ renderComponent({ endpoint: EModelEndpoint.agents, agent_id: 'ephemeral-convo-1' });
+
+ expect(mockAttachFileMenuProps.disabled).toBe(false);
+ });
+
+ it('enables it once that provider resolves', () => {
+ mockFileConfigLoaded = true;
+ mockAgentQueryData = { provider: 'openAI' } as Partial<Agent>;
+
+ renderComponent({ endpoint: EModelEndpoint.agents, agent_id: 'agent_saved01' });
+
+ expect(mockAttachFileMenuProps.disabled).toBe(false);
+ });
+});
diff --git a/client/src/components/Chat/Input/Files/__tests__/AttachFileMenu.spec.tsx b/client/src/components/Chat/Input/Files/__tests__/AttachFileMenu.spec.tsx
index 4393f81918..13d60564e4 100644
--- a/client/src/components/Chat/Input/Files/__tests__/AttachFileMenu.spec.tsx
+++ b/client/src/components/Chat/Input/Files/__tests__/AttachFileMenu.spec.tsx
@@ -46,6 +46,12 @@ jest.mock('@librechat/client', () => {
),
),
TooltipAnchor: (props) => props.render,
+ /* Mirrors the real primitive closely enough for these assertions: it applies
+ * `label` as the accessible name, which is how the trigger is queried. */
+ IconButton: R.forwardRef((props, ref) => {
+ const { label, size: _size, shape: _shape, variant: _variant, children, ...rest } = props;
+ return R.createElement('button', { ref, 'aria-label': label, ...rest }, children);
+ }),
DropdownPopup: (props) =>
R.createElement(
'div',
@@ -99,6 +105,7 @@ const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false
function setupMocks(overrides: { provider?: string } = {}) {
const translations: Record<string, string> = {
+ com_files_upload_local_machine: 'From Local Computer',
com_files_upload_sharepoint: 'Upload from SharePoint',
com_sidepanel_attach_files: 'Attach Files',
com_ui_upload_code_environment: 'Upload to Code Environment',
@@ -141,6 +148,7 @@ function renderMenu(props: Record<string, unknown> = {}) {
setFiles={() => {}}
setFilesLoading={() => {}}
conversation={null}
+ isUnifiedMode={false}
{...props}
/>
</RecoilRoot>
@@ -155,6 +163,51 @@ function openMenu() {
describe('AttachFileMenu', () => {
beforeEach(jest.clearAllMocks);
+ describe('unified mode upload sources', () => {
+ it('uses a single upload button when SharePoint is disabled', () => {
+ setupMocks();
+ renderMenu({ isUnifiedMode: true });
+
+ expect(screen.getByRole('button', { name: /attach files/i })).toBeInTheDocument();
+ expect(
+ screen.queryByRole('button', { name: /attach file options/i }),
+ ).not.toBeInTheDocument();
+ });
+
+ it('offers SharePoint alongside local upload when SharePoint is enabled', () => {
+ setupMocks();
+ mockUseGetStartupConfig.mockReturnValue({ data: { sharePointFilePickerEnabled: true } });
+ renderMenu({ isUnifiedMode: true });
+
+ openMenu();
+
+ expect(screen.getByText('From Local Computer')).toBeInTheDocument();
+ expect(screen.getByText('Upload from SharePoint')).toBeInTheDocument();
+ });
+
+ it('does not offer a destination choice on either source', () => {
+ setupMocks();
+ mockUseAgentCapabilities.mockReturnValue({
+ contextEnabled: true,
+ fileSearchEnabled: true,
+ codeEnabled: true,
+ });
+ mockUseAgentToolPermissions.mockReturnValue({
+ fileSearchAllowedByAgent: true,
+ codeAllowedByAgent: true,
+ provider: undefined,
+ });
+ mockUseGetStartupConfig.mockReturnValue({ data: { sharePointFilePickerEnabled: true } });
+ renderMenu({ isUnifiedMode: true });
+
+ openMenu();
+
+ expect(screen.queryByText('Upload to Code Environment')).not.toBeInTheDocument();
+ expect(screen.queryByText('Upload for File Search')).not.toBeInTheDocument();
+ expect(screen.queryByText('Upload as Text')).not.toBeInTheDocument();
+ });
+ });
+
describe('Upload to Provider vs Upload Image', () => {
it('shows "Upload to Provider" when endpointType is custom (resolved from agent provider)', () => {
setupMocks({ provider: 'Moonshot' });
@@ -273,6 +326,15 @@ describe('AttachFileMenu', () => {
expect(screen.getByTestId('dropdown-popup')).toHaveAttribute('data-modal', 'false');
expect(screen.getByTestId('dropdown-popup')).toHaveAttribute('data-portal', 'true');
});
+
+ it('renders the unified upload button when legacyFileUploadUX is not true', () => {
+ setupMocks();
+ renderMenu({ isUnifiedMode: true });
+ expect(screen.getByRole('button', { name: /attach files/i })).toBeInTheDocument();
+ expect(
+ screen.queryByRole('button', { name: /attach file options/i }),
+ ).not.toBeInTheDocument();
+ });
});
describe('Agent Capabilities', () => {
diff --git a/client/src/components/Chat/Input/ToolsDropdown.tsx b/client/src/components/Chat/Input/ToolsDropdown.tsx
index 66d5684ddc..64fc779bba 100644
--- a/client/src/components/Chat/Input/ToolsDropdown.tsx
+++ b/client/src/components/Chat/Input/ToolsDropdown.tsx
@@ -167,7 +167,7 @@ const ToolsDropdown = ({ disabled }: ToolsDropdownProps) => {
onClick: handleFileSearchToggle,
hideOnClick: false,
render: (props) => (
- <div {...props}>
+ <div {...props} data-testid="tools-menu-file-search">
<div className="flex items-center gap-2">
<VectorIcon className="icon-md" />
<span>{localize('com_assistants_file_search')}</span>
@@ -317,7 +317,7 @@ const ToolsDropdown = ({ disabled }: ToolsDropdownProps) => {
onClick: handleCodeInterpreterToggle,
hideOnClick: false,
render: (props) => (
- <div {...props}>
+ <div {...props} data-testid="tools-menu-run-code">
<div className="flex items-center gap-2">
<TerminalSquareIcon className="icon-md" aria-hidden="true" />
<span>{localize('com_ui_run_code')}</span>
diff --git a/client/src/components/Chat/Input/__tests__/ChatForm.attachments.spec.tsx b/client/src/components/Chat/Input/__tests__/ChatForm.attachments.spec.tsx
index 23b2168ec7..201e7d6e23 100644
--- a/client/src/components/Chat/Input/__tests__/ChatForm.attachments.spec.tsx
+++ b/client/src/components/Chat/Input/__tests__/ChatForm.attachments.spec.tsx
@@ -124,7 +124,12 @@ function renderComposer({
const queryClient = new QueryClient({
defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
});
- queryClient.setQueryData([QueryKeys.fileConfig], {});
+ /* These interaction tests exercise the destination menu. Unified-mode control
+ * behavior has its own focused coverage, so opt this harness into the legacy menu
+ * instead of depending on the product default. */
+ queryClient.setQueryData([QueryKeys.fileConfig], {
+ endpoints: { default: { legacyFileUploadUX: true } },
+ });
queryClient.setQueryData<TFile[]>([QueryKeys.files], []);
queryClient.setQueryData([QueryKeys.endpoints], { [EModelEndpoint.openAI]: { order: 0 } });
diff --git a/client/src/components/Chat/Input/__tests__/ChatForm.pasteUpload.spec.tsx b/client/src/components/Chat/Input/__tests__/ChatForm.pasteUpload.spec.tsx
index dbb077b925..650099a521 100644
--- a/client/src/components/Chat/Input/__tests__/ChatForm.pasteUpload.spec.tsx
+++ b/client/src/components/Chat/Input/__tests__/ChatForm.pasteUpload.spec.tsx
@@ -115,11 +115,14 @@ function Harness() {
);
}
-function renderComposer() {
+function renderComposer({ legacyUploadUX = false }: { legacyUploadUX?: boolean } = {}) {
const queryClient = new QueryClient({
defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
});
- queryClient.setQueryData([QueryKeys.fileConfig], {});
+ queryClient.setQueryData(
+ [QueryKeys.fileConfig],
+ legacyUploadUX ? { legacyFileUploadUX: true } : {},
+ );
queryClient.setQueryData<TFile[]>([QueryKeys.files], []);
queryClient.setQueryData([QueryKeys.endpoints], { [EModelEndpoint.openAI]: { order: 0 } });
@@ -157,6 +160,10 @@ const pasteImage = (textarea: HTMLElement) => {
* trigger to return focus to when it closes and used to leave focus on
* `document.body` — which reads to the user as "the send button is enabled but
* Enter does nothing", since Enter-to-send is a textarea key handler.
+ *
+ * The dialog only exists on a `legacyFileUploadUX` endpoint. Unified upload routes
+ * a pasted file straight to its destination, so these render in legacy mode and the
+ * unified path is covered separately below.
*/
describe('composer focus after a pasted upload', () => {
beforeEach(() => {
@@ -172,7 +179,7 @@ describe('composer focus after a pasted upload', () => {
});
test('returns focus to the composer when the upload dialog closes', async () => {
- renderComposer();
+ renderComposer({ legacyUploadUX: true });
const textarea = await screen.findByTestId('text-input');
await userEvent.click(textarea);
@@ -189,7 +196,7 @@ describe('composer focus after a pasted upload', () => {
}, 20000);
test('Enter still sends after a pasted upload, with no further typing', async () => {
- renderComposer();
+ renderComposer({ legacyUploadUX: true });
const textarea = await screen.findByTestId('text-input');
await userEvent.click(textarea);
@@ -210,3 +217,56 @@ describe('composer focus after a pasted upload', () => {
expect(mockAsk.mock.calls[0][0]).toEqual(expect.objectContaining({ text: 'hi' }));
}, 20000);
});
+
+/**
+ * Unified upload routes a pasted file to its destination without raising the chooser,
+ * so the dialog that used to steal focus never opens. The user-facing contract is the
+ * same either way: the composer keeps focus and Enter still sends.
+ */
+describe('composer focus after a pasted upload in unified mode', () => {
+ beforeEach(() => {
+ localStorage.clear();
+ global.URL.createObjectURL = jest.fn(() => 'blob:preview');
+ global.URL.revokeObjectURL = jest.fn();
+ (global as unknown as { Image: unknown }).Image = StubImage;
+ mockUpload.mockReset();
+ mockAsk.mockReset();
+ mockUpload.mockImplementation((body: FormData) =>
+ Promise.resolve({ ...uploadResponse, temp_file_id: body.get('file_id') as string }),
+ );
+ });
+
+ test('uploads without a destination dialog and leaves focus in the composer', async () => {
+ renderComposer();
+
+ const textarea = await screen.findByTestId('text-input');
+ await userEvent.click(textarea);
+ await userEvent.type(textarea, 'hi');
+ expect(textarea).toHaveFocus();
+
+ pasteImage(textarea);
+
+ await waitFor(() => expect(mockUpload).toHaveBeenCalled());
+ expect(screen.queryAllByRole('button', { name: /upload/i })).toHaveLength(0);
+ expect(textarea).toHaveFocus();
+ }, 20000);
+
+ test('Enter still sends after a pasted upload, with no further typing', async () => {
+ renderComposer();
+
+ const textarea = await screen.findByTestId('text-input');
+ await userEvent.click(textarea);
+ await userEvent.type(textarea, 'hi');
+
+ pasteImage(textarea);
+ await waitFor(() => expect(mockUpload).toHaveBeenCalled());
+ await waitFor(() => expect(screen.getByTestId('send-button')).toBeEnabled());
+
+ /** Straight to the keyboard, as above: any click or keystroke first would restore
+ * focus on its own and hide a regression. */
+ fireEvent.keyDown(document.activeElement as Element, { key: 'Enter', code: 'Enter' });
+
+ await waitFor(() => expect(mockAsk).toHaveBeenCalled());
+ expect(mockAsk.mock.calls[0][0]).toEqual(expect.objectContaining({ text: 'hi' }));
+ }, 20000);
+});
diff --git a/client/src/hooks/Agents/index.ts b/client/src/hooks/Agents/index.ts
index 0d32e8bfd3..639ac2ade3 100644
--- a/client/src/hooks/Agents/index.ts
+++ b/client/src/hooks/Agents/index.ts
@@ -6,6 +6,8 @@ export { default as useAgentCapabilities } from './useAgentCapabilities';
export { default as useGetAgentsConfig } from './useGetAgentsConfig';
export { default as useAgentDefaultPermissionLevel } from './useAgentDefaultPermissionLevel';
export { default as useAgentFileConfig } from './useAgentFileConfig';
+export { default as useAgentUploadTarget } from './useAgentUploadTarget';
+export type { AgentUploadTarget } from './useAgentUploadTarget';
export { default as useAgentToolPermissions } from './useAgentToolPermissions';
export { default as useCodeApprovalMode } from './useCodeApprovalMode';
export { default as useMCPToolOptions } from './useMCPToolOptions';
diff --git a/client/src/hooks/Agents/useAgentUploadTarget.ts b/client/src/hooks/Agents/useAgentUploadTarget.ts
new file mode 100644
index 0000000000..f57d74ddb9
--- /dev/null
+++ b/client/src/hooks/Agents/useAgentUploadTarget.ts
@@ -0,0 +1,69 @@
+import { useMemo } from 'react';
+import {
+ isAgentsEndpoint,
+ resolveEndpointType,
+ resolveUseResponsesApi,
+} from 'librechat-data-provider';
+import type { EModelEndpoint, TConversation } from 'librechat-data-provider';
+import { useGetEndpointsQuery, useGetAgentByIdQuery } from '~/data-provider';
+import { useAgentsMapContext } from '~/Providers/AgentsMapContext';
+
+export interface AgentUploadTarget {
+ /** The saved agent's provider, which is the endpoint uploads are validated under. */
+ agentProvider: string | undefined;
+ endpointType: EModelEndpoint | string | undefined;
+ useResponsesApi: boolean | undefined;
+}
+
+/**
+ * One answer to what a conversation's agent uploads under, for every entry point that
+ * needs it: the attach menu, drag and drop, and the upload handler itself.
+ *
+ * The agents map can be missing a saved agent on a direct-link or cache-miss load, so the
+ * record is fetched when the map has no parameters for it. Reading the map alone leaves
+ * those loads preflighting against the generic `agents` limits with no Responses flag.
+ */
+export default function useAgentUploadTarget(
+ conversation: TConversation | null | undefined,
+): AgentUploadTarget {
+ const agentsMap = useAgentsMapContext();
+ const { data: endpointsConfig } = useGetEndpointsQuery();
+
+ const endpoint = conversation?.endpoint;
+ const agentId = conversation?.agent_id;
+ const isAgents = useMemo(() => isAgentsEndpoint(endpoint), [endpoint]);
+
+ const needsAgentFetch = useMemo(() => {
+ if (!isAgents || agentId == null || agentId === '') {
+ return false;
+ }
+ return !agentsMap?.[agentId]?.model_parameters;
+ }, [isAgents, agentId, agentsMap]);
+
+ const { data: agentData } = useGetAgentByIdQuery(agentId, { enabled: needsAgentFetch });
+
+ const agentProvider = useMemo(() => {
+ if (!isAgents || agentId == null || agentId === '') {
+ return undefined;
+ }
+ return agentData?.provider ?? agentsMap?.[agentId]?.provider;
+ }, [isAgents, agentId, agentData, agentsMap]);
+
+ const endpointType = useMemo(
+ () => resolveEndpointType(endpointsConfig, endpoint, agentProvider),
+ [endpointsConfig, endpoint, agentProvider],
+ );
+
+ const useResponsesApi = useMemo(() => {
+ if (!isAgents || agentId == null || agentId === '') {
+ return conversation?.useResponsesApi;
+ }
+ return resolveUseResponsesApi(
+ agentData?.model_parameters?.useResponsesApi ??
+ agentsMap?.[agentId]?.model_parameters?.useResponsesApi,
+ conversation?.useResponsesApi,
+ );
+ }, [isAgents, agentId, conversation?.useResponsesApi, agentData, agentsMap]);
+
+ return { agentProvider, endpointType, useResponsesApi };
+}
diff --git a/client/src/hooks/Files/__tests__/useFileHandling.test.ts b/client/src/hooks/Files/__tests__/useFileHandling.test.ts
index 251947cf1f..bcbc2e1b56 100644
--- a/client/src/hooks/Files/__tests__/useFileHandling.test.ts
+++ b/client/src/hooks/Files/__tests__/useFileHandling.test.ts
@@ -62,12 +62,19 @@ const makeSizedFile = (name: string, type: string, size: number): File => {
return file;
};
-let mockConversation: Record<string, string | null | undefined> = {};
+let mockConversation: Record<string, string | boolean | null | undefined> = {};
let mockFileConfig: ReturnType<typeof mergeFileConfig> | null = null;
let mockIsConfigPending = false;
let mockIsTemporary = false;
let mockUploadOptions: MockUploadMutationOptions = {};
+let mockAgentsMap: Record<string, unknown> = {};
+let mockEndpointsConfig: Record<string, unknown> | undefined = undefined;
+let mockAgentQueryData: Record<string, unknown> | undefined = undefined;
+jest.mock('~/Providers/AgentsMapContext', () => ({
+ useAgentsMapContext: () => mockAgentsMap,
+}));
+
jest.mock('~/Providers/ChatContext', () => ({
useChatContext: jest.fn(() => ({
files: new Map(),
@@ -104,6 +111,8 @@ jest.mock('@tanstack/react-query', () => ({
jest.mock('~/data-provider', () => ({
useGetFileConfig: jest.fn(() => ({ data: mockFileConfig })),
+ useGetEndpointsQuery: jest.fn(() => ({ data: mockEndpointsConfig })),
+ useGetAgentByIdQuery: jest.fn(() => ({ data: mockAgentQueryData })),
useUploadFileMutation: jest.fn((opts: MockUploadMutationOptions) => {
mockUploadOptions = opts;
return { mutate: mockMutate };
@@ -189,6 +198,9 @@ describe('useFileHandling', () => {
mockResizeImageIfNeeded.mockImplementation(async (file: File) => ({ file, resized: false }));
mockWaitForConfig.mockResolvedValue(undefined);
mockConversation = {};
+ mockAgentsMap = {};
+ mockEndpointsConfig = undefined;
+ mockAgentQueryData = undefined;
mockFileConfig = null;
mockIsConfigPending = false;
mockIsTemporary = false;
@@ -1067,6 +1079,127 @@ describe('useFileHandling', () => {
expect(formData.get('conversationId')).toBeNull();
});
+ it('validates against the agent provider policy, not the agents entry', async () => {
+ /* The server validates a saved agent's upload under its provider, so preflighting the
+ * `agents` entry rejects provider-supported files that the request would have accepted. */
+ mockConversation = { conversationId: 'convo-1', endpoint: 'agents', agent_id: 'agent_a1' };
+ mockAgentsMap = { agent_a1: { provider: 'Custom Provider' } };
+ mockFileConfig = mergeFileConfig({
+ endpoints: {
+ agents: { fileSizeLimit: 5 },
+ 'Custom Provider': { fileSizeLimit: 20 },
+ },
+ });
+
+ const useFileHandling = await loadHook();
+ const { result } = renderHook(() => useFileHandling());
+
+ await act(async () => {
+ await result.current.handleFiles([makeSizedFile('notes.txt', 'text/plain', megabyte)]);
+ });
+
+ expect(mockValidateFiles).toHaveBeenCalledWith(
+ expect.objectContaining({
+ endpointFileConfig: expect.objectContaining({
+ fileSizeLimit: mockFileConfig.endpoints['Custom Provider']?.fileSizeLimit,
+ }),
+ }),
+ );
+ expect(mockFileConfig.endpoints['Custom Provider']?.fileSizeLimit).not.toEqual(
+ mockFileConfig.endpoints.agents?.fileSizeLimit,
+ );
+ });
+
+ it('sends the Responses flag a saved agent holds on its own record', async () => {
+ /* A saved Azure agent keeps the setting in model_parameters, and without it the
+ * server routes a natively supported PDF to extracted text. */
+ mockConversation = { conversationId: 'convo-1', endpoint: 'agents', agent_id: 'agent_a1' };
+ mockAgentsMap = { agent_a1: { model_parameters: { useResponsesApi: true } } };
+
+ const useFileHandling = await loadHook();
+ const { result } = renderHook(() => useFileHandling());
+
+ await act(async () => {
+ await result.current.handleFiles([new File(['hi'], 'a.txt', { type: 'text/plain' })]);
+ });
+
+ const formData: FormData = mockMutate.mock.calls[0][0];
+ expect(formData.get('useResponsesApi')).toBe('true');
+ });
+
+ it('resolves the provider and Responses flag from a fetched agent on a cache miss', async () => {
+ /* A direct-link load has no entry for the agent in the map. The record is fetched
+ * for the controls, so preflight has to read the same one or the upload is measured
+ * against the generic agents limits and loses the Responses flag. */
+ mockConversation = { conversationId: 'convo-1', endpoint: 'agents', agent_id: 'agent_a1' };
+ mockAgentsMap = {};
+ mockAgentQueryData = {
+ provider: 'Custom Provider',
+ model_parameters: { useResponsesApi: true },
+ };
+ mockFileConfig = mergeFileConfig({
+ endpoints: {
+ agents: { fileSizeLimit: 5 },
+ 'Custom Provider': { fileSizeLimit: 20 },
+ },
+ });
+
+ const useFileHandling = await loadHook();
+ const { result } = renderHook(() => useFileHandling());
+
+ await act(async () => {
+ await result.current.handleFiles([makeSizedFile('notes.txt', 'text/plain', megabyte)]);
+ });
+
+ expect(mockValidateFiles).toHaveBeenCalledWith(
+ expect.objectContaining({
+ endpointFileConfig: expect.objectContaining({
+ fileSizeLimit: mockFileConfig.endpoints['Custom Provider']?.fileSizeLimit,
+ }),
+ }),
+ );
+ const formData: FormData = mockMutate.mock.calls[0][0];
+ expect(formData.get('useResponsesApi')).toBe('true');
+ });
+
+ it('lets a saved agent override the conversation Responses flag', async () => {
+ /* Execution runs on the agent's own model parameters, so an upload that trusted
+ * the conversation would store a raw provider document the turn then re-resolves
+ * to text it has no extraction for. */
+ mockConversation = {
+ conversationId: 'convo-1',
+ endpoint: 'agents',
+ agent_id: 'agent_a1',
+ useResponsesApi: true,
+ };
+ mockAgentsMap = { agent_a1: { model_parameters: { useResponsesApi: false } } };
+
+ const useFileHandling = await loadHook();
+ const { result } = renderHook(() => useFileHandling());
+
+ await act(async () => {
+ await result.current.handleFiles([new File(['hi'], 'a.txt', { type: 'text/plain' })]);
+ });
+
+ const formData: FormData = mockMutate.mock.calls[0][0];
+ expect(formData.get('useResponsesApi')).toBeNull();
+ });
+
+ it('omits the flag when neither the conversation nor the agent sets it', async () => {
+ mockConversation = { conversationId: 'convo-1', endpoint: 'agents', agent_id: 'agent_a1' };
+ mockAgentsMap = { agent_a1: { model_parameters: {} } };
+
+ const useFileHandling = await loadHook();
+ const { result } = renderHook(() => useFileHandling());
+
+ await act(async () => {
+ await result.current.handleFiles([new File(['hi'], 'a.txt', { type: 'text/plain' })]);
+ });
+
+ const formData: FormData = mockMutate.mock.calls[0][0];
+ expect(formData.get('useResponsesApi')).toBeNull();
+ });
+
it('does not enter assistants upload path when override is agents', async () => {
mockConversation = {
conversationId: 'convo-1',
diff --git a/client/src/hooks/Files/__tests__/useUploadOptions.spec.tsx b/client/src/hooks/Files/__tests__/useUploadOptions.spec.tsx
new file mode 100644
index 0000000000..4392ffc444
--- /dev/null
+++ b/client/src/hooks/Files/__tests__/useUploadOptions.spec.tsx
@@ -0,0 +1,86 @@
+import { RecoilRoot } from 'recoil';
+import { renderHook } from '@testing-library/react';
+import useUploadOptions from '../useUploadOptions';
+
+const mockDragDropContext = {
+ conversationId: 'convo-1',
+ get agentId() {
+ return mockAgentId;
+ },
+ endpoint: 'agents',
+ endpointType: 'custom',
+ useResponsesApi: undefined,
+};
+let mockProvider: string | undefined = 'Custom Provider';
+/* Saved agent ids carry the `agent_` prefix; anything else reads as ephemeral. */
+let mockAgentId: string | undefined = 'agent_saved01';
+
+jest.mock('~/Providers', () => ({
+ useDragDropContext: () => mockDragDropContext,
+}));
+jest.mock('~/hooks/Agents/useGetAgentsConfig', () => ({
+ __esModule: true,
+ default: () => ({ agentsConfig: {} }),
+}));
+jest.mock('~/hooks/Agents/useAgentCapabilities', () => ({
+ __esModule: true,
+ default: () => ({ fileSearchEnabled: false, codeEnabled: false, contextEnabled: false }),
+}));
+jest.mock('~/hooks/Agents/useAgentToolPermissions', () => ({
+ __esModule: true,
+ default: () => ({ provider: mockProvider, tools: [] }),
+}));
+jest.mock('~/data-provider', () => ({
+ useGetFileConfig: () => ({
+ data: jest
+ .requireActual('librechat-data-provider')
+ .mergeFileConfig({ endpoints: { 'Custom Provider': { legacyFileUploadUX: true } } }),
+ isError: false,
+ isPaused: false,
+ isSuccess: true,
+ }),
+}));
+
+const render = () => renderHook(() => useUploadOptions(), { wrapper: RecoilRoot });
+
+describe('useUploadOptions endpoint resolution', () => {
+ it('applies the agent provider policy rather than the agents entry', () => {
+ /* An agent conversation carries endpoint `agents`, but a named custom provider
+ * configures its own entry. Reading the conversation endpoint missed it, so a
+ * provider that opted into the chooser was treated as unified. */
+ mockProvider = 'Custom Provider';
+
+ const { result } = render();
+
+ expect(result.current.isUnifiedMode).toBe(false);
+ });
+
+ it('falls back to the conversation endpoint when no provider is resolved', () => {
+ mockProvider = undefined;
+ mockAgentId = undefined;
+
+ const { result } = render();
+
+ expect(result.current.isUnifiedMode).toBe(true);
+ });
+
+ it('withholds resolution until the saved agent provider lands', () => {
+ /* Falling back to the agents entry meanwhile reports a settled answer drawn from the
+ * wrong record, so an upload routes on a policy the server will not apply. */
+ mockProvider = undefined;
+ mockAgentId = 'agent_saved01';
+
+ const { result } = render();
+
+ expect(result.current.isConfigResolved).toBe(false);
+ });
+
+ it('does not wait on a provider an ephemeral agent will never have', () => {
+ mockProvider = undefined;
+ mockAgentId = 'ephemeral-convo-1';
+
+ const { result } = render();
+
+ expect(result.current.isConfigResolved).toBe(true);
+ });
+});
diff --git a/client/src/hooks/Files/useDragHelpers.ts b/client/src/hooks/Files/useDragHelpers.ts
index 1409aeb01d..c212d2eb97 100644
--- a/client/src/hooks/Files/useDragHelpers.ts
+++ b/client/src/hooks/Files/useDragHelpers.ts
@@ -2,16 +2,8 @@ import { useRef, useMemo, useCallback } from 'react';
import { useDrop } from 'react-dnd';
import { useToastContext } from '@librechat/client';
import { NativeTypes } from 'react-dnd-html5-backend';
-import { useQueryClient } from '@tanstack/react-query';
-import {
- QueryKeys,
- mergeFileConfig,
- resolveEndpointType,
- isAssistantsEndpoint,
- getEndpointFileConfig,
-} from 'librechat-data-provider';
+import { isAssistantsEndpoint } from 'librechat-data-provider';
import type { DropTargetMonitor } from 'react-dnd';
-import type * as t from 'librechat-data-provider';
import { useChatContext } from '~/Providers/ChatContext';
import useFileUploadRouter from './useFileUploadRouter';
import { useUploadModalContext } from '~/Providers';
@@ -19,7 +11,6 @@ import useUploadOptions from './useUploadOptions';
import useLocalize from '../useLocalize';
export default function useDragHelpers() {
- const queryClient = useQueryClient();
const { showToast } = useToastContext();
const localize = useLocalize();
const { conversation } = useChatContext();
@@ -29,48 +20,44 @@ export default function useDragHelpers() {
[conversation?.endpoint],
);
- const { getOptions } = useUploadOptions();
+ const { getOptions, isConfigResolved, isUnifiedMode, uploadsDisabled } = useUploadOptions();
const routeFiles = useFileUploadRouter();
const { openModal } = useUploadModalContext();
/** Use refs to avoid re-creating the drop handler */
const conversationRef = useRef(conversation);
const getOptionsRef = useRef(getOptions);
+ const isConfigResolvedRef = useRef(isConfigResolved);
+ const isUnifiedModeRef = useRef(isUnifiedMode);
+ const uploadsDisabledRef = useRef(uploadsDisabled);
const routeFilesRef = useRef(routeFiles);
const openModalRef = useRef(openModal);
const isAssistantsRef = useRef(isAssistants);
conversationRef.current = conversation;
getOptionsRef.current = getOptions;
+ isConfigResolvedRef.current = isConfigResolved;
+ isUnifiedModeRef.current = isUnifiedMode;
+ uploadsDisabledRef.current = uploadsDisabled;
routeFilesRef.current = routeFiles;
openModalRef.current = openModal;
isAssistantsRef.current = isAssistants;
const handleDrop = useCallback(
(item: { files: File[] }) => {
- /** Early block: leverage endpoint file config to prevent drag/drop on disabled endpoints */
- const currentEndpoint = conversationRef.current?.endpoint ?? 'default';
- const endpointsConfig = queryClient.getQueryData<t.TEndpointsConfig>([QueryKeys.endpoints]);
- const agentId = conversationRef.current?.agent_id;
- const agent = agentId
- ? queryClient.getQueryData<t.Agent>([QueryKeys.agent, agentId])
- : undefined;
- const currentEndpointType = resolveEndpointType(
- endpointsConfig,
- currentEndpoint,
- agent?.provider,
- );
- const cfg = queryClient.getQueryData<t.TFileConfig>([QueryKeys.fileConfig]);
- if (cfg) {
- const endpointCfg = getEndpointFileConfig({
- fileConfig: mergeFileConfig(cfg),
- endpoint: currentEndpoint,
- endpointType: currentEndpointType,
- });
- if (endpointCfg?.disabled === true) {
- showToast({ message: localize('com_ui_attach_error_disabled'), status: 'error' });
- return;
- }
+ /* Both answers come from the hook the attach menu and the paste path already use.
+ * Resolving the endpoint config here as well missed an agent's provider entry, so a
+ * named custom provider's rules applied to one flow and not the others. */
+ if (uploadsDisabledRef.current) {
+ showToast({ message: localize('com_ui_attach_error_disabled'), status: 'error' });
+ return;
+ }
+ /* Neither answer is safe before the config lands: offering the chooser sends an
+ * explicit destination on a unified deployment, and skipping it sends none on a
+ * legacy one, which the server refuses. Say so instead of guessing. */
+ if (!isConfigResolvedRef.current) {
+ showToast({ message: localize('com_ui_attach_error_pending'), status: 'warning' });
+ return;
}
/** Assistants do not use the upload-option flow */
@@ -79,6 +66,14 @@ export default function useDragHelpers() {
return;
}
+ /* Unified mode decides the destination from the file itself, so a drop must not
+ * present the chooser the attach button no longer shows. Offering it here would let
+ * the same file be delivered differently depending on how it was added. */
+ if (isUnifiedModeRef.current) {
+ routeFilesRef.current(item.files);
+ return;
+ }
+
const options = getOptionsRef.current(item.files);
if (options.length === 0) {
showToast({ message: localize('com_error_files_unsupported'), status: 'error' });
@@ -90,7 +85,7 @@ export default function useDragHelpers() {
}
openModalRef.current(item.files);
},
- [queryClient, showToast, localize],
+ [showToast, localize],
);
const [{ canDrop, isOver }, drop] = useDrop(
diff --git a/client/src/hooks/Files/useFileHandling.ts b/client/src/hooks/Files/useFileHandling.ts
index 650cef6fc1..51e8608c6e 100644
--- a/client/src/hooks/Files/useFileHandling.ts
+++ b/client/src/hooks/Files/useFileHandling.ts
@@ -35,6 +35,7 @@ import {
validateFileDuplicates,
} from '~/utils';
import { useGetFileConfig, useUploadFileMutation } from '~/data-provider';
+import useAgentUploadTarget from '~/hooks/Agents/useAgentUploadTarget';
import useLocalize, { TranslationKeys } from '~/hooks/useLocalize';
import { useDelayedUploadToast } from './useDelayedUploadToast';
import { useChatContext } from '~/Providers/ChatContext';
@@ -214,6 +215,12 @@ const useFileHandlingCore = (params: UseFileHandling | undefined, fileState: Fil
() => endpointOverride ?? conversation?.endpoint ?? 'default',
[endpointOverride, conversation?.endpoint],
);
+ const uploadTarget = useAgentUploadTarget(conversation);
+ /** An agent's file policy lives under its provider, which is the entry the server
+ * validates against. An explicit override names its own endpoint and keeps it. */
+ const agentProvider = endpointOverride != null ? undefined : uploadTarget.agentProvider;
+ const agentEndpointType = endpointOverride != null ? undefined : uploadTarget.endpointType;
+ const usesResponsesApi = uploadTarget.useResponsesApi;
const { data: fileConfig = null } = useGetFileConfig({
select: (data) => mergeFileConfig(data),
@@ -360,6 +367,13 @@ const useFileHandlingCore = (params: UseFileHandling | undefined, fileState: Fil
const formData = new FormData();
formData.append('endpoint', endpoint);
formData.append('endpointType', endpointType ?? '');
+ /* Azure carries native documents only through the Responses API, so routing needs to
+ * know which one this conversation uses. A saved agent holds the setting on its own
+ * record when the conversation does not carry one, which is the same fallback the
+ * attach menu and the drop handler resolve. */
+ if (usesResponsesApi === true) {
+ formData.append('useResponsesApi', 'true');
+ }
formData.append('file', extendedFile.file as File, encodeURIComponent(filename));
formData.append('file_id', extendedFile.file_id);
if (
@@ -489,9 +503,9 @@ const useFileHandlingCore = (params: UseFileHandling | undefined, fileState: Fil
: filesRef.current;
const currentFileConfig = fileConfigRef.current;
const endpointFileConfig = getEndpointFileConfig({
- endpoint,
+ endpoint: agentProvider ?? endpoint,
fileConfig: currentFileConfig,
- endpointType,
+ endpointType: agentProvider != null ? agentEndpointType : endpointType,
});
/** The source remains visible until success, so exclude only its matching entry from this
* upload's validation tallies. All other callers validate against the complete file map. */
diff --git a/client/src/hooks/Files/useUploadOptions.ts b/client/src/hooks/Files/useUploadOptions.ts
index 7481e3ad99..c2f401bb50 100644
--- a/client/src/hooks/Files/useUploadOptions.ts
+++ b/client/src/hooks/Files/useUploadOptions.ts
@@ -4,16 +4,17 @@ import {
Tools,
Constants,
mergeFileConfig,
+ isAgentsEndpoint,
getEndpointFileConfig,
defaultAgentCapabilities,
} from 'librechat-data-provider';
import type { EToolResources } from 'librechat-data-provider';
import useAgentToolPermissions from '~/hooks/Agents/useAgentToolPermissions';
import useAgentCapabilities from '~/hooks/Agents/useAgentCapabilities';
+import { getViableUploadOptions, isUnifiedUploadMode } from '~/utils';
import useGetAgentsConfig from '~/hooks/Agents/useGetAgentsConfig';
import { useGetFileConfig } from '~/data-provider';
import { ephemeralAgentByConvoId } from '~/store';
-import { getViableUploadOptions } from '~/utils';
import { useDragDropContext } from '~/Providers';
import { isEphemeralAgent } from '~/common';
@@ -49,8 +50,23 @@ export default function useUploadOptions() {
const fileSearchAllowedByAgent = !isSavedAgent || (tools?.includes(Tools.file_search) ?? false);
const codeAllowedByAgent = !isSavedAgent || (tools?.includes(Tools.execute_code) ?? false);
- const endpointFileConfig = getEndpointFileConfig({ fileConfig, endpoint, endpointType });
+ /* An agent conversation carries endpoint `agents`, but its file policy belongs to the
+ * provider it runs on, which is the entry a named custom endpoint configures. Resolved
+ * the same way the attach menu resolves it, so the two cannot offer different rules. */
+ const fileConfigEndpoint = isAgentsEndpoint(endpoint) && provider ? provider : endpoint;
+ /* A saved agent's policy lives under its provider, so the config is not resolved for it
+ * until that provider is known. Falling back to the `agents` entry meanwhile reports a
+ * settled answer drawn from the wrong record. Ephemeral agents have no provider to
+ * wait for. */
+ const awaitingAgentProvider = isAgentsEndpoint(endpoint) && isSavedAgent && provider == null;
+ const endpointFileConfig = getEndpointFileConfig({
+ fileConfig,
+ endpoint: fileConfigEndpoint,
+ endpointType,
+ });
const uploadsDisabled = endpointFileConfig.disabled === true;
+ const isConfigResolved = isFileConfigLoaded && !awaitingAgentProvider;
+ const isUnifiedMode = isUnifiedUploadMode(endpointFileConfig, isConfigResolved);
const endpointSupportedMimeTypes = endpointFileConfig.supportedMimeTypes;
const getOptions = useCallback(
@@ -83,5 +99,11 @@ export default function useUploadOptions() {
],
);
- return { getOptions, uploadsDisabled, isConfigPending };
+ return {
+ getOptions,
+ uploadsDisabled,
+ isConfigPending,
+ isConfigResolved,
+ isUnifiedMode,
+ };
}
diff --git a/client/src/hooks/Input/useTextarea.spec.tsx b/client/src/hooks/Input/useTextarea.spec.tsx
index 37204fee6e..cf557f899a 100644
--- a/client/src/hooks/Input/useTextarea.spec.tsx
+++ b/client/src/hooks/Input/useTextarea.spec.tsx
@@ -29,6 +29,7 @@ let useTextarea: typeof import('./useTextarea').default;
let mockIndex = 0;
let mockIsSubmitting = false;
let mockIsUploadConfigPending = false;
+let mockIsUnifiedMode = false;
let mockConversation: { endpoint: string; conversationId?: string } = {
endpoint: 'openAI',
conversationId: 'convo-1',
@@ -102,6 +103,8 @@ jest.mock('~/hooks/Files/useUploadOptions', () => ({
getOptions: mockGetUploadOptions,
uploadsDisabled: false,
isConfigPending: mockIsUploadConfigPending,
+ isConfigResolved: !mockIsUploadConfigPending,
+ isUnifiedMode: mockIsUnifiedMode,
})),
}));
@@ -178,6 +181,7 @@ describe('useTextarea long-paste fallback', () => {
mockIndex = 0;
mockIsSubmitting = false;
mockIsUploadConfigPending = false;
+ mockIsUnifiedMode = false;
mockConversation = { endpoint: 'openAI', conversationId: 'convo-1' };
mockGetUploadOptions.mockReturnValue([EToolResources.context]);
mockSetValue.mockReset();
@@ -1053,3 +1057,68 @@ describe('useTextarea composer handoff', () => {
expect(mockSetPendingComposerText).not.toHaveBeenCalled();
});
});
+
+describe('useTextarea clipboard routing in unified mode', () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ localStorage.clear();
+ mockIndex = 0;
+ mockIsSubmitting = false;
+ mockIsUploadConfigPending = false;
+ mockIsUnifiedMode = true;
+ mockConversation = { endpoint: 'openAI', conversationId: 'convo-1' };
+ mockGetUploadOptions.mockReturnValue([EToolResources.context, EToolResources.execute_code]);
+ });
+
+ it('routes a pasted file without offering the destination chooser', async () => {
+ /* The attach button no longer shows the chooser in unified mode, so raising it here
+ * would deliver the same file differently depending on how it was added. */
+ mockRouteFiles.mockResolvedValueOnce(true);
+ const { result } = renderTextareaHook();
+ const pastedFile = new File(['%PDF-'], 'report.pdf', { type: 'application/pdf' });
+ const event = createPasteEvent([pastedFile]);
+
+ act(() =>
+ result.current.handlePaste(event as unknown as React.ClipboardEvent<HTMLTextAreaElement>),
+ );
+
+ await waitFor(() => expect(mockRouteFiles).toHaveBeenCalledTimes(1));
+ expect(mockRouteFiles.mock.calls[0][1]).toBeUndefined();
+ expect(mockOpenModal).not.toHaveBeenCalled();
+ });
+
+ it('holds a paste rather than offering the chooser before the config lands', async () => {
+ /* Neither answer is safe while pending: the chooser sends an explicit destination a
+ * unified deployment no longer uses, and skipping it sends none, which a legacy one
+ * refuses. */
+ mockIsUnifiedMode = false;
+ mockIsUploadConfigPending = true;
+ const { result } = renderTextareaHook();
+ const pastedFile = new File(['%PDF-'], 'report.pdf', { type: 'application/pdf' });
+ const event = createPasteEvent([pastedFile]);
+
+ act(() =>
+ result.current.handlePaste(event as unknown as React.ClipboardEvent<HTMLTextAreaElement>),
+ );
+
+ await waitFor(() => expect(mockShowToast).toHaveBeenCalled());
+ expect(mockOpenModal).not.toHaveBeenCalled();
+ expect(mockRouteFiles).not.toHaveBeenCalled();
+ });
+
+ it('still honors a destination the caller already resolved', async () => {
+ /* The long-text paste knows the file belongs in the text context, and unified routing
+ * does not override a caller that already decided. */
+ mockRouteFiles.mockResolvedValueOnce(true);
+ const { result } = renderTextareaHook();
+ const event = createPasteEvent();
+
+ act(() =>
+ result.current.handlePaste(event as unknown as React.ClipboardEvent<HTMLTextAreaElement>),
+ );
+
+ await waitFor(() => expect(mockRouteFiles).toHaveBeenCalledTimes(1));
+ expect(mockRouteFiles.mock.calls[0][1]).toBe(EToolResources.context);
+ expect(mockOpenModal).not.toHaveBeenCalled();
+ });
+});
diff --git a/client/src/hooks/Input/useTextarea.ts b/client/src/hooks/Input/useTextarea.ts
index ae16a34216..52218585e5 100644
--- a/client/src/hooks/Input/useTextarea.ts
+++ b/client/src/hooks/Input/useTextarea.ts
@@ -75,6 +75,8 @@ export default function useTextarea({
getOptions: getUploadOptions,
uploadsDisabled,
isConfigPending: isUploadConfigPending,
+ isConfigResolved: isUploadConfigResolved,
+ isUnifiedMode,
} = useUploadOptions();
const routeFiles = useFileUploadRouter();
const { openModal } = useUploadModalContext();
@@ -334,6 +336,21 @@ export default function useTextarea({
return await upload();
}
+ /* Unified mode decides the destination from the file itself, matching the drop
+ * handler. A caller that already knows where the file belongs, as the long-text
+ * paste does, still passes that through. */
+ if (isUnifiedMode && preferred == null) {
+ return await upload();
+ }
+
+ /* Before the config lands neither answer is safe, so the paste says so rather than
+ * falling through to the chooser a unified deployment no longer shows. */
+ if (preferred == null && !isUploadConfigResolved) {
+ showToast({ message: localize('com_ui_attach_error_pending'), status: 'warning' });
+ setFilesLoading(false);
+ return false;
+ }
+
/** Resolving options reads the file config, so until that lands the list is empty for
* reasons that have nothing to do with this file. A caller that already knows where the
* file belongs hands it to the upload instead, which waits for the same config and
@@ -372,6 +389,8 @@ export default function useTextarea({
setFilesLoading,
getUploadOptions,
isUploadConfigPending,
+ isUploadConfigResolved,
+ isUnifiedMode,
],
);
diff --git a/client/src/hooks/useKeyboardShortcuts.ts b/client/src/hooks/useKeyboardShortcuts.ts
index 94a0d06b2d..d63aeda894 100644
--- a/client/src/hooks/useKeyboardShortcuts.ts
+++ b/client/src/hooks/useKeyboardShortcuts.ts
@@ -712,6 +712,7 @@ export function useShortcutActions(): ShortcutAction[] {
const handleUploadFile = useCallback(() => {
const btn =
document.querySelector<HTMLButtonElement>('#attach-file-menu-button') ??
+ document.querySelector<HTMLButtonElement>('#attach-file-button') ??
document.querySelector<HTMLButtonElement>('#attach-file');
return clickTarget(btn);
}, []);
diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.json
index 19e1a57193..ba47c2b815 100644
--- a/client/src/locales/en/translation.json
+++ b/client/src/locales/en/translation.json
@@ -964,6 +964,7 @@
"com_ui_at_least_one_owner_required": "At least one owner is required",
"com_ui_attach_error": "Cannot attach file. Create or select a conversation, or try refreshing the page.",
"com_ui_attach_error_disabled": "File uploads are disabled for this endpoint",
+ "com_ui_attach_error_pending": "Still loading upload settings. Try attaching the file again in a moment.",
"com_ui_attach_error_limit": "File limit reached:",
"com_ui_attach_error_openai": "Cannot attach Assistant files to other endpoints",
"com_ui_attach_error_size": "File size limit exceeded for endpoint:",
diff --git a/client/src/utils/__tests__/unifiedUploadMode.spec.ts b/client/src/utils/__tests__/unifiedUploadMode.spec.ts
new file mode 100644
index 0000000000..1a817cd4e0
--- /dev/null
+++ b/client/src/utils/__tests__/unifiedUploadMode.spec.ts
@@ -0,0 +1,25 @@
+import { isUnifiedUploadMode } from '../files';
+
+describe('isUnifiedUploadMode', () => {
+ it('withholds unified mode until the config actually resolves', () => {
+ /* An unresolved config falls back to the built-in defaults, where the absent
+ * legacyFileUploadUX reads as unified. Trusting it shows the unified uploader on a
+ * legacy deployment, and an upload made in that window carries no tool resource
+ * while the server still applies legacy rules. A failed or paused fetch is as
+ * unresolved as an in-flight one, which is why the flag is "resolved" and not
+ * "settled". */
+ expect(isUnifiedUploadMode(undefined, false)).toBe(false);
+ expect(isUnifiedUploadMode({}, false)).toBe(false);
+ expect(isUnifiedUploadMode({ legacyFileUploadUX: false }, false)).toBe(false);
+ });
+
+ it('is unified once the config lands and does not opt out', () => {
+ expect(isUnifiedUploadMode({}, true)).toBe(true);
+ expect(isUnifiedUploadMode({ legacyFileUploadUX: false }, true)).toBe(true);
+ expect(isUnifiedUploadMode(undefined, true)).toBe(true);
+ });
+
+ it('honors an explicit legacy opt-out', () => {
+ expect(isUnifiedUploadMode({ legacyFileUploadUX: true }, true)).toBe(false);
+ });
+});
diff --git a/client/src/utils/__tests__/validateFiles.spec.ts b/client/src/utils/__tests__/validateFiles.spec.ts
index ffced653af..68fac8f991 100644
--- a/client/src/utils/__tests__/validateFiles.spec.ts
+++ b/client/src/utils/__tests__/validateFiles.spec.ts
@@ -57,6 +57,42 @@ describe('validateFiles', () => {
expect(setError).not.toHaveBeenCalled();
});
+ it('rejects a type outside a restricted endpoint allowlist in unified mode', () => {
+ endpointFileConfig = makeEndpointConfig({
+ supportedMimeTypes: [/^image\/(jpeg|png)$/],
+ });
+ const fileList = [makeFile('notes.txt', 'text/plain', 1024)];
+
+ const result = validateFiles({
+ files,
+ fileList,
+ setError,
+ endpointFileConfig,
+ fileConfig: defaultFileConfig,
+ });
+
+ expect(result).toBe(false);
+ expect(setError).toHaveBeenCalledWith('Unsupported file type: text/plain');
+ });
+
+ it('accepts a type the restricted endpoint allowlist permits in unified mode', () => {
+ endpointFileConfig = makeEndpointConfig({
+ supportedMimeTypes: [/^image\/(jpeg|png)$/],
+ });
+ const fileList = [makeFile('shot.png', 'image/png', 1024)];
+
+ const result = validateFiles({
+ files,
+ fileList,
+ setError,
+ endpointFileConfig,
+ fileConfig: defaultFileConfig,
+ });
+
+ expect(result).toBe(true);
+ expect(setError).not.toHaveBeenCalled();
+ });
+
it('rejects when endpoint is disabled', () => {
endpointFileConfig = makeEndpointConfig({ disabled: true });
const fileList = [makeFile('doc.pdf', 'application/pdf', 1024)];
diff --git a/client/src/utils/files.ts b/client/src/utils/files.ts
index 99827472ab..62e77dacaf 100644
--- a/client/src/utils/files.ts
+++ b/client/src/utils/files.ts
@@ -460,6 +460,10 @@ export const validateFiles = ({
fileList[i] = newFile;
}
+ /* Unified mode routes by MIME type but does not widen what may be uploaded: the
+ * endpoint allowlist is the same ceiling the server enforces in `filterFile`, so
+ * accepting extraction-capable types beyond it only turns a preflight message into
+ * a failed request. */
let mimeTypesToCheck = supportedMimeTypes;
if (toolResource === EToolResources.context) {
mimeTypesToCheck = [
@@ -556,6 +560,19 @@ const isContextType = (type: string, fileConfig: FileConfig | null): boolean =>
* Each option requires every file to be valid for it, so the caller can decide between
* auto-routing (one option), prompting (multiple), or rejecting (none).
*/
+/**
+ * Whether uploads route from the file itself rather than through the destination chooser.
+ * Answering it needs a config the server actually returned: without one the built-in
+ * defaults apply, and their absent `legacyFileUploadUX` reads as unified, which is the
+ * wrong uploader on a legacy deployment. A failed or paused query is as unresolved as a
+ * pending one, so the caller passes whether the fetch succeeded rather than whether it
+ * has stopped.
+ */
+export const isUnifiedUploadMode = (
+ endpointFileConfig: EndpointFileConfig | undefined,
+ isConfigResolved: boolean,
+): boolean => isConfigResolved && endpointFileConfig?.legacyFileUploadUX !== true;
+
export const getViableUploadOptions = (
fileList: File[],
ctx: UploadOptionContext,
diff --git a/e2e/config/librechat.e2e.yaml b/e2e/config/librechat.e2e.yaml
index 5052c0104b..8d3dbda7f2 100644
--- a/e2e/config/librechat.e2e.yaml
+++ b/e2e/config/librechat.e2e.yaml
@@ -72,6 +72,25 @@ mcpServers:
client_id: e2e-oauth-client
# __E2E_DYNAMIC_MCP_NETWORK_SERVERS__
+# Per-endpoint file upload config so both upload UXs get e2e coverage:
+# - Mock Provider A keeps the legacy 3-way dropdown (chat.spec.ts exercises
+# "Upload to Provider"); legacyFileUploadUX also forces llmDeliveryPath
+# 'provider', so that test's CSV still reaches the model.
+# - Mock Provider B uses the unified single button with spreadsheet/csv routed
+# to llmDeliveryPath 'none' (unified-upload.spec.ts).
+fileConfig:
+ endpoints:
+ 'Mock Provider A':
+ legacyFileUploadUX: true
+ 'Mock Provider B':
+ defaultLLMDeliveryPath:
+ overrides:
+ 'text/csv': 'none'
+ 'text/plain': 'none'
+ 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': 'none'
+ # Routed to the provider: still delivered to the model AND shown in chat.
+ 'text/markdown': 'provider'
+
endpoints:
# Default capabilities plus run_in_background (off by default upstream) so the
# background tool-call e2e can opt an MCP tool into detached dispatch.
diff --git a/e2e/playwright.config.mock.ts b/e2e/playwright.config.mock.ts
index 66470b87ba..a3bbe50b2a 100644
--- a/e2e/playwright.config.mock.ts
+++ b/e2e/playwright.config.mock.ts
@@ -28,6 +28,12 @@ const labelServerPath = path.resolve(rootPath, 'e2e/setup/fake-label-server.js')
/** The template's custom-endpoint `baseURL`s hard-code 8889;
* `writeRuntimeMockConfig` substitutes any override into the generated copy. */
const LABEL_PORT = process.env.E2E_LABEL_PORT || '8889';
+const codeServerPath = path.resolve(rootPath, 'e2e/setup/fake-code-server.js');
+const ragServerPath = path.resolve(rootPath, 'e2e/setup/fake-rag-server.js');
+/** Ports the backend reaches via LIBRECHAT_CODE_BASEURL / RAG_API_URL below.
+ * Kept clear of the MCP (8765/8766) and label (8889) fixtures. */
+const CODE_API_PORT = process.env.E2E_CODE_API_PORT || '8790';
+const RAG_API_PORT = process.env.E2E_RAG_API_PORT || '8791';
const fakeModelHookPath = path.resolve(rootPath, 'e2e/setup/fake-model.js');
/** Model-fixture record mode: the run hook taps the REAL provider stream into a
* replayable fixture instead of overriding the model (e2e/setup/model-replay.js). */
@@ -142,6 +148,10 @@ const baseEnv = {
...(process.env.E2E_CODE_BRIDGE_ADMIN_TOKEN
? { E2E_CODE_BRIDGE_ADMIN_TOKEN: process.env.E2E_CODE_BRIDGE_ADMIN_TOKEN }
: {}),
+ /** Point code-env + RAG provisioning at the local fakes started below. */
+ LIBRECHAT_CODE_BASEURL: `http://127.0.0.1:${CODE_API_PORT}/v1`,
+ LIBRECHAT_CODE_API_KEY: 'e2e-code-key',
+ RAG_API_URL: `http://127.0.0.1:${RAG_API_PORT}`,
...vanillaOverrides,
};
@@ -402,6 +412,26 @@ export default defineConfig({
timeout: 60_000,
reuseExistingServer: false,
},
+ {
+ // Fake code-execution API for file-provisioning specs (LIBRECHAT_CODE_BASEURL).
+ command: `node ${codeServerPath}`,
+ cwd: rootPath,
+ env: { ...process.env, E2E_CODE_API_PORT: CODE_API_PORT },
+ url: `http://127.0.0.1:${CODE_API_PORT}/health`,
+ stdout: 'pipe',
+ timeout: 60_000,
+ reuseExistingServer: false,
+ },
+ {
+ // Fake RAG (vector DB) API for file-provisioning specs (RAG_API_URL).
+ command: `node ${ragServerPath}`,
+ cwd: rootPath,
+ env: { ...process.env, E2E_RAG_API_PORT: RAG_API_PORT },
+ url: `http://127.0.0.1:${RAG_API_PORT}/health`,
+ stdout: 'pipe',
+ timeout: 60_000,
+ reuseExistingServer: false,
+ },
{
// Start one LibreChat process, or a two-process topology behind a test-only proxy, after the
// network fixtures so inspection and persistent connections agree.
diff --git a/e2e/setup/fake-code-server.js b/e2e/setup/fake-code-server.js
new file mode 100644
index 0000000000..354f66c5d7
--- /dev/null
+++ b/e2e/setup/fake-code-server.js
@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+
+/**
+ * Fake code-execution API for mock e2e file-provisioning tests.
+ *
+ * Stands in for the LibreChat code sandbox that `@librechat/agents` reaches at
+ * `LIBRECHAT_CODE_BASEURL`. It implements just enough of the real contract to
+ * exercise the unified-upload provisioning paths end to end (real backend + DB)
+ * without a live sandbox:
+ *
+ * - `POST /v1/upload` — single-file provisioning (`uploadCodeEnvFile`).
+ * - `POST /v1/upload/batch` — batch provisioning (`batchUploadCodeEnvFiles`).
+ * - `GET /v1/files/:sid` — session liveness (`checkSessionsAlive`).
+ * - `POST /v1/exec` — code execution (`execute_code` tool run).
+ *
+ * Uploads are grouped into a deterministic `storage_session_id` per `kind:id`,
+ * mirroring codeapi's sessionKey bucketing so liveness checks resolve. Every
+ * request is recorded and surfaced at `GET /__debug/uploads` so specs can assert
+ * a file's bytes actually reached the code env, independent of the DB write.
+ */
+
+const http = require('http');
+const busboy = require('busboy');
+const { randomUUID } = require('crypto');
+
+const PORT = parseInt(process.env.E2E_CODE_API_PORT || '8790', 10);
+const HOST = '127.0.0.1';
+
+/** @type {Map<string, Array<{ fileId: string; filename: string }>>} */
+const sessions = new Map();
+/** @type {Array<{ filename: string; kind: string; id: string; storage_session_id: string; fileId: string; apiKey: string; userId: string; bytes: number }>} */
+const uploads = [];
+/** @type {Array<{ lang: string; codeLength: number; fileCount: number }>} */
+const execs = [];
+
+function sessionIdFor(kind, id) {
+ return `sess-${kind || 'user'}-${id || 'anon'}`;
+}
+
+function recordUpload({ kind, id, filename, bytes, apiKey, userId }) {
+ const storage_session_id = sessionIdFor(kind, id);
+ const fileId = `fid-${randomUUID()}`;
+ if (!sessions.has(storage_session_id)) {
+ sessions.set(storage_session_id, []);
+ }
+ sessions.get(storage_session_id).push({ fileId, filename });
+ uploads.push({ filename, kind, id, storage_session_id, fileId, apiKey, userId, bytes });
+ return { storage_session_id, fileId };
+}
+
+function sendJson(res, status, body) {
+ res.writeHead(status, { 'Content-Type': 'application/json' });
+ res.end(JSON.stringify(body));
+}
+
+function parseMultipart(req) {
+ return new Promise((resolve, reject) => {
+ const bb = busboy({ headers: req.headers });
+ /** @type {Record<string, string>} */
+ const fields = {};
+ /** @type {Array<{ field: string; filename: string; bytes: number }>} */
+ const files = [];
+ bb.on('field', (name, value) => {
+ fields[name] = value;
+ });
+ bb.on('file', (name, stream, info) => {
+ let bytes = 0;
+ stream.on('data', (chunk) => {
+ bytes += chunk.length;
+ });
+ stream.on('end', () => {
+ files.push({ field: name, filename: info.filename, bytes });
+ });
+ stream.on('error', reject);
+ });
+ bb.on('close', () => resolve({ fields, files }));
+ bb.on('error', reject);
+ req.pipe(bb);
+ });
+}
+
+function readJson(req) {
+ return new Promise((resolve, reject) => {
+ let raw = '';
+ req.on('data', (chunk) => {
+ raw += chunk;
+ });
+ req.on('end', () => {
+ try {
+ resolve(raw ? JSON.parse(raw) : {});
+ } catch (error) {
+ reject(error);
+ }
+ });
+ req.on('error', reject);
+ });
+}
+
+async function handleUpload(req, res) {
+ const { fields, files } = await parseMultipart(req);
+ if (files.length === 0) {
+ sendJson(res, 400, { message: 'error', error: 'no file provided' });
+ return;
+ }
+ const apiKey = req.headers['x-api-key'] || '';
+ const userId = req.headers['user-id'] || '';
+ const { storage_session_id, fileId } = recordUpload({
+ kind: fields.kind,
+ id: fields.id,
+ filename: files[0].filename,
+ bytes: files[0].bytes,
+ apiKey,
+ userId,
+ });
+ sendJson(res, 200, {
+ message: 'success',
+ storage_session_id,
+ files: [{ fileId, filename: files[0].filename }],
+ });
+}
+
+async function handleUploadBatch(req, res) {
+ const { fields, files } = await parseMultipart(req);
+ if (files.length === 0) {
+ sendJson(res, 400, { message: 'error', error: 'no files provided' });
+ return;
+ }
+ const apiKey = req.headers['x-api-key'] || '';
+ const userId = req.headers['user-id'] || '';
+ const storage_session_id = sessionIdFor(fields.kind, fields.id);
+ const responseFiles = files.map((file) => {
+ const fileId = `fid-${randomUUID()}`;
+ if (!sessions.has(storage_session_id)) {
+ sessions.set(storage_session_id, []);
+ }
+ sessions.get(storage_session_id).push({ fileId, filename: file.filename });
+ uploads.push({
+ filename: file.filename,
+ kind: fields.kind,
+ id: fields.id,
+ storage_session_id,
+ fileId,
+ apiKey,
+ userId,
+ bytes: file.bytes,
+ });
+ return { status: 'success', fileId, filename: file.filename };
+ });
+ sendJson(res, 200, {
+ message: 'success',
+ storage_session_id,
+ files: responseFiles,
+ succeeded: responseFiles.length,
+ failed: 0,
+ });
+}
+
+async function handleExec(req, res) {
+ const body = await readJson(req);
+ execs.push({
+ lang: body.lang || '',
+ codeLength: typeof body.code === 'string' ? body.code.length : 0,
+ fileCount: Array.isArray(body.files) ? body.files.length : 0,
+ });
+ sendJson(res, 200, { stdout: 'E2E code exec ok\n', stderr: '', files: [] });
+}
+
+const server = http.createServer((req, res) => {
+ const url = new URL(req.url, `http://${req.headers.host}`);
+ const { pathname } = url;
+
+ const handle = async () => {
+ if (pathname === '/health' && req.method === 'GET') {
+ res.writeHead(200, { 'Content-Type': 'text/plain' });
+ res.end('ok');
+ return;
+ }
+
+ if (pathname === '/__debug/uploads' && req.method === 'GET') {
+ sendJson(res, 200, { uploads, execs });
+ return;
+ }
+
+ if (pathname === '/__debug/reset' && req.method === 'POST') {
+ sessions.clear();
+ uploads.length = 0;
+ execs.length = 0;
+ sendJson(res, 200, { ok: true });
+ return;
+ }
+
+ if (pathname === '/v1/upload' && req.method === 'POST') {
+ await handleUpload(req, res);
+ return;
+ }
+
+ if (pathname === '/v1/upload/batch' && req.method === 'POST') {
+ await handleUploadBatch(req, res);
+ return;
+ }
+
+ if (pathname === '/v1/exec' && req.method === 'POST') {
+ await handleExec(req, res);
+ return;
+ }
+
+ const filesMatch = pathname.match(/^\/v1\/files\/([^/]+)$/);
+ if (filesMatch && req.method === 'GET') {
+ sendJson(res, 200, sessions.get(decodeURIComponent(filesMatch[1])) ?? []);
+ return;
+ }
+
+ res.writeHead(404, { 'Content-Type': 'application/json' });
+ res.end(JSON.stringify({ message: 'not found' }));
+ };
+
+ handle().catch((error) => {
+ console.error('[e2e] fake code server error:', error);
+ sendJson(res, 500, { message: 'error', error: String(error?.message ?? error) });
+ });
+});
+
+server.listen(PORT, HOST, () => {
+ console.log(`[e2e] fake code API listening on http://${HOST}:${PORT}/v1`);
+});
diff --git a/e2e/setup/fake-model.js b/e2e/setup/fake-model.js
index 84c89658f3..c80ef33942 100644
--- a/e2e/setup/fake-model.js
+++ b/e2e/setup/fake-model.js
@@ -103,6 +103,20 @@ const APPROVAL_TOOL_NAME = 'approval_probe_mcp_e2e-memory';
const APPROVAL_TOOL_CALL_PREFIX = 'call_e2e_approval_';
const BACKGROUND_DISPATCH_TOOL_CALL_ID = 'call_e2e_background_dispatch';
const BACKGROUND_COLLECT_TOOL_CALL_ID = 'call_e2e_background_collect';
+const EXECUTE_CODE_MARKER = 'E2E_EXECUTE_CODE:';
+const FILE_SEARCH_MARKER = 'E2E_FILE_SEARCH:';
+/** Code Interpreter advertises bash_tool/read_file at runtime (execute_code is legacy);
+ * emit whichever the agent actually exposes so the tool batch — and provisioning — fires. */
+const CODE_EXEC_TOOLS = [
+ { name: 'bash_tool', args: { command: 'echo e2e' } },
+ { name: 'read_file', args: { path: '/mnt/data' } },
+ { name: 'execute_code', args: { lang: 'py', code: 'print("e2e")' } },
+];
+const FILE_SEARCH_TOOL_NAME = 'file_search';
+const EXECUTE_CODE_FINAL_TEXT = 'E2E execute_code complete';
+const FILE_SEARCH_FINAL_TEXT = 'E2E file_search complete';
+const EXECUTE_CODE_TOOL_CALL_ID = 'call_e2e_execute_code';
+const FILE_SEARCH_TOOL_CALL_ID = 'call_e2e_file_search';
const MODEL_SPEC_ACCESSIBLE_SKILL = 'e2e-model-spec-allowed';
const DEPLOYMENT_SKILL_NAME = 'e2e-deployment-skill';
const ALWAYS_APPLY_BODY_MARKER = 'E2E_ALWAYS_APPLY_BODY_MARKER';
@@ -2282,6 +2296,62 @@ function buildHandoffResponses(graph, parsed) {
};
}
+/**
+ * Emit an `execute_code` / `file_search` tool call so the run reaches
+ * ON_TOOL_EXECUTE, where `provisionFiles` lazily uploads message attachments to
+ * the code env / vector DB. The tool's own result is irrelevant to the
+ * provisioning assertion (which inspects the fake servers) — we just need the
+ * batch to fire. Guards assert the resource tool was actually advertised.
+ */
+function provisioningToolResponses({ text, toolNames }) {
+ const codeLabel = getMarkerValue(text, EXECUTE_CODE_MARKER);
+ if (codeLabel) {
+ const codeTool = CODE_EXEC_TOOLS.find((tool) => toolNames.has(tool.name));
+ if (!codeTool) {
+ return {
+ responses: [
+ `E2E execute_code unavailable: no code-execution tool advertised (saw ${
+ JSON.stringify([...toolNames]) || 'none'
+ }).`,
+ ],
+ };
+ }
+ return {
+ responses: ['', `${EXECUTE_CODE_FINAL_TEXT}: ${codeLabel}`],
+ toolCalls: [
+ {
+ id: EXECUTE_CODE_TOOL_CALL_ID,
+ name: codeTool.name,
+ args: codeTool.args,
+ type: 'tool_call',
+ },
+ ],
+ };
+ }
+
+ const searchLabel = getMarkerValue(text, FILE_SEARCH_MARKER);
+ if (searchLabel) {
+ if (!toolNames.has(FILE_SEARCH_TOOL_NAME)) {
+ return {
+ responses: [`E2E file_search unavailable: ${FILE_SEARCH_TOOL_NAME} was not advertised.`],
+ };
+ }
+ return {
+ responses: ['', `${FILE_SEARCH_FINAL_TEXT}: ${searchLabel}`],
+ toolCalls: [
+ {
+ id: FILE_SEARCH_TOOL_CALL_ID,
+ name: FILE_SEARCH_TOOL_NAME,
+ args: { query: `e2e ${searchLabel}` },
+ type: 'tool_call',
+ },
+ ],
+ };
+ }
+
+ return null;
+}
+
function resolveResponses({ graph, messages, text, toolNames }) {
const backgroundCompletion = backgroundCompletionResponses(text);
if (backgroundCompletion) {
@@ -2333,6 +2403,11 @@ function resolveResponses({ graph, messages, text, toolNames }) {
return steerToolReplyResponses(steerToolLabel, toolNames);
}
+ const provisioningTool = provisioningToolResponses({ text, toolNames });
+ if (provisioningTool) {
+ return provisioningTool;
+ }
+
const steerSplitLabel = getMarkerValue(text, STEER_SPLIT_REPLY_MARKER);
if (steerSplitLabel) {
return steerSplitReplyResponses(steerSplitLabel, toolNames);
diff --git a/e2e/setup/fake-rag-server.js b/e2e/setup/fake-rag-server.js
new file mode 100644
index 0000000000..61af20f93c
--- /dev/null
+++ b/e2e/setup/fake-rag-server.js
@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+
+/**
+ * Fake RAG (vector DB) API for mock e2e file-provisioning tests.
+ *
+ * Stands in for the external RAG service LibreChat reaches at `RAG_API_URL`. It
+ * implements just enough of the contract to exercise the vector-DB provisioning
+ * path end to end (real backend + DB) without a live embedding service:
+ *
+ * - `POST /embed` — embed an uploaded file (`uploadVectors`); returns
+ * `known_type: true` so the file is marked `embedded`.
+ * - `POST /query` — semantic query from the `file_search` tool; returns an
+ * empty result set (valid, handled gracefully).
+ * - `DELETE /documents` — delete embeddings (`deleteVectors`).
+ *
+ * Every embed is recorded and surfaced at `GET /__debug/embedded` so specs can
+ * assert a file's bytes actually reached the RAG env, independent of the DB write.
+ */
+
+const http = require('http');
+const busboy = require('busboy');
+
+const PORT = parseInt(process.env.E2E_RAG_API_PORT || '8791', 10);
+const HOST = '127.0.0.1';
+
+/** @type {Array<{ file_id: string; filename: string; entity_id: string; bytes: number; auth: string }>} */
+const embedded = [];
+/** @type {Array<{ file_id: string; query: string }>} */
+const queries = [];
+/** @type {string[]} */
+const deleted = [];
+
+function sendJson(res, status, body) {
+ res.writeHead(status, { 'Content-Type': 'application/json' });
+ res.end(JSON.stringify(body));
+}
+
+function parseMultipart(req) {
+ return new Promise((resolve, reject) => {
+ const bb = busboy({ headers: req.headers });
+ /** @type {Record<string, string>} */
+ const fields = {};
+ /** @type {Array<{ field: string; filename: string; bytes: number }>} */
+ const files = [];
+ bb.on('field', (name, value) => {
+ fields[name] = value;
+ });
+ bb.on('file', (name, stream, info) => {
+ let bytes = 0;
+ stream.on('data', (chunk) => {
+ bytes += chunk.length;
+ });
+ stream.on('end', () => {
+ files.push({ field: name, filename: info.filename, bytes });
+ });
+ stream.on('error', reject);
+ });
+ bb.on('close', () => resolve({ fields, files }));
+ bb.on('error', reject);
+ req.pipe(bb);
+ });
+}
+
+function readJson(req) {
+ return new Promise((resolve, reject) => {
+ let raw = '';
+ req.on('data', (chunk) => {
+ raw += chunk;
+ });
+ req.on('end', () => {
+ try {
+ resolve(raw ? JSON.parse(raw) : {});
+ } catch (error) {
+ reject(error);
+ }
+ });
+ req.on('error', reject);
+ });
+}
+
+async function handleEmbed(req, res) {
+ const { fields, files } = await parseMultipart(req);
+ embedded.push({
+ file_id: fields.file_id || '',
+ filename: files[0]?.filename || '',
+ entity_id: fields.entity_id || '',
+ bytes: files[0]?.bytes ?? 0,
+ auth: req.headers['authorization'] || '',
+ });
+ sendJson(res, 200, { status: true, known_type: true });
+}
+
+async function handleQuery(req, res) {
+ const body = await readJson(req);
+ queries.push({ file_id: body.file_id || '', query: body.query || '' });
+ sendJson(res, 200, { data: [] });
+}
+
+async function handleDeleteDocuments(req, res) {
+ const body = await readJson(req);
+ if (Array.isArray(body)) {
+ deleted.push(...body.map(String));
+ }
+ sendJson(res, 200, { status: true });
+}
+
+const server = http.createServer((req, res) => {
+ const url = new URL(req.url, `http://${req.headers.host}`);
+ const { pathname } = url;
+
+ const handle = async () => {
+ if ((pathname === '/health' || pathname === '/') && req.method === 'GET') {
+ res.writeHead(200, { 'Content-Type': 'text/plain' });
+ res.end('ok');
+ return;
+ }
+
+ if (pathname === '/__debug/embedded' && req.method === 'GET') {
+ sendJson(res, 200, { embedded, queries, deleted });
+ return;
+ }
+
+ if (pathname === '/__debug/reset' && req.method === 'POST') {
+ embedded.length = 0;
+ queries.length = 0;
+ deleted.length = 0;
+ sendJson(res, 200, { ok: true });
+ return;
+ }
+
+ if (pathname === '/embed' && req.method === 'POST') {
+ await handleEmbed(req, res);
+ return;
+ }
+
+ if (pathname === '/query' && req.method === 'POST') {
+ await handleQuery(req, res);
+ return;
+ }
+
+ if (pathname === '/documents' && req.method === 'DELETE') {
+ await handleDeleteDocuments(req, res);
+ return;
+ }
+
+ res.writeHead(404, { 'Content-Type': 'application/json' });
+ res.end(JSON.stringify({ message: 'not found' }));
+ };
+
+ handle().catch((error) => {
+ console.error('[e2e] fake RAG server error:', error);
+ sendJson(res, 500, { status: false, error: String(error?.message ?? error) });
+ });
+});
+
+server.listen(PORT, HOST, () => {
+ console.log(`[e2e] fake RAG API listening on http://${HOST}:${PORT}`);
+});
diff --git a/e2e/specs/mock/file-provisioning.spec.ts b/e2e/specs/mock/file-provisioning.spec.ts
new file mode 100644
index 0000000000..e5dcef61ba
--- /dev/null
+++ b/e2e/specs/mock/file-provisioning.spec.ts
@@ -0,0 +1,154 @@
+import { expect, test } from '@playwright/test';
+import type { UploadedFile } from './helpers';
+import {
+ MOCK_ENDPOINTS,
+ NEW_CHAT_PATH,
+ uniqueName,
+ sendMessage,
+ getRagEmbedded,
+ enableFileSearch,
+ selectMockEndpoint,
+ resetProvisioning,
+ enableCodeInterpreter,
+ uploadViaLegacyOption,
+ uploadViaUnifiedButton,
+ getCodeProvisionedUploads,
+} from './helpers';
+
+/**
+ * File provisioning to the code env + vector DB (PR #12626), exercised against the
+ * local fake code/RAG servers wired in e2e/playwright.config.mock.ts.
+ *
+ * Two trigger points are covered end to end (real backend + DB + provisioning HTTP):
+ *
+ * - Immediate (legacy dropdown, Mock Provider A): choosing "Upload to Code
+ * Environment" / "Upload for File Search" provisions at upload time
+ * (`uploadCodeEnvFile` / `uploadVectors`).
+ * - Lazy (unified button, Mock Provider B): a plain attachment routes to `none` and
+ * is NOT provisioned at upload; it is uploaded to the code env / embedded only
+ * when a tool that needs it runs (`provisionFiles` at ON_TOOL_EXECUTE). This is the
+ * headline behavior — "all uploaded files available to the tool at execute time".
+ *
+ * The fake servers record every request, so each test asserts the file's bytes
+ * actually reached the target env, independent of the deferred DB write.
+ */
+
+test.describe('file provisioning — immediate (legacy dropdown)', () => {
+ test('"Upload to Code Environment" provisions the file to the code env', async ({ page }) => {
+ test.setTimeout(120000);
+ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
+ await selectMockEndpoint(page, MOCK_ENDPOINTS[0]);
+ await resetProvisioning(page);
+ // The legacy "Upload to Code Environment" option only appears once the
+ // ephemeral execute_code capability is enabled.
+ await enableCodeInterpreter(page);
+
+ const fileName = `${uniqueName('code')}.csv`;
+ const response = await uploadViaLegacyOption(page, 'Upload to Code Environment', {
+ name: fileName,
+ mimeType: 'text/csv',
+ content: 'x,y\n1,2\n',
+ });
+ expect(response.ok()).toBeTruthy();
+
+ // The upload reached the code env (fake server received it at upload time).
+ await expect
+ .poll(async () => (await getCodeProvisionedUploads(page)).map((u) => u.filename), {
+ timeout: 15000,
+ })
+ .toContain(fileName);
+ });
+
+ test('"Upload for File Search" embeds the file into the vector DB', async ({ page }) => {
+ test.setTimeout(120000);
+ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
+ await selectMockEndpoint(page, MOCK_ENDPOINTS[0]);
+ await resetProvisioning(page);
+ // The legacy "Upload for File Search" option only appears once the ephemeral
+ // file_search capability is enabled.
+ await enableFileSearch(page);
+
+ const fileName = `${uniqueName('search')}.csv`;
+ const response = await uploadViaLegacyOption(page, 'Upload for File Search', {
+ name: fileName,
+ mimeType: 'text/csv',
+ content: 'a,b\n3,4\n',
+ });
+ expect(response.ok()).toBeTruthy();
+
+ await expect
+ .poll(async () => (await getRagEmbedded(page)).map((e) => e.filename), { timeout: 15000 })
+ .toContain(fileName);
+ });
+});
+
+test.describe('file provisioning — lazy (unified upload, at tool-execute)', () => {
+ test('a unified attachment is provisioned to the code env when execute_code runs', async ({
+ page,
+ }) => {
+ test.setTimeout(120000);
+ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
+ await selectMockEndpoint(page, MOCK_ENDPOINTS[1]);
+ await resetProvisioning(page);
+ await enableCodeInterpreter(page);
+
+ // Unified upload routes to `none`: stored, but NOT yet in the code env.
+ const fileName = `${uniqueName('lazycode')}.csv`;
+ const response = await uploadViaUnifiedButton(page, {
+ name: fileName,
+ mimeType: 'text/csv',
+ content: 'name,score\nzoe,9\n',
+ });
+ expect(response.ok()).toBeTruthy();
+ expect(
+ (await getCodeProvisionedUploads(page)).map((u) => u.filename),
+ 'unified upload must not provision to the code env until a tool runs',
+ ).not.toContain(fileName);
+ await expect(page.getByRole('button', { name: fileName })).toBeVisible({ timeout: 15000 });
+
+ // A tool run triggers lazy provisioning: the fake model emits an execute_code call.
+ // Provisioning fires at ON_TOOL_EXECUTE, before the execute_code tool itself runs,
+ // so assert it reached the code env independent of the tool's own result.
+ await sendMessage(page, `E2E_EXECUTE_CODE:${uniqueName('run')}`);
+
+ await expect
+ .poll(async () => (await getCodeProvisionedUploads(page)).map((u) => u.filename), {
+ timeout: 30000,
+ })
+ .toContain(fileName);
+ });
+
+ test('a unified attachment is embedded into the vector DB when file_search runs', async ({
+ page,
+ }) => {
+ test.setTimeout(120000);
+ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
+ await selectMockEndpoint(page, MOCK_ENDPOINTS[1]);
+ await resetProvisioning(page);
+ await enableFileSearch(page);
+
+ const fileName = `${uniqueName('lazysearch')}.csv`;
+ const response = await uploadViaUnifiedButton(page, {
+ name: fileName,
+ mimeType: 'text/csv',
+ content: 'k,v\nfoo,bar\n',
+ });
+ expect(response.ok()).toBeTruthy();
+ // uploadVectors streams from a temp path, so the fake RAG records the file_id,
+ // not the original filename — correlate on the id from the upload response.
+ const fileId = ((await response.json()) as UploadedFile).file_id;
+ expect(fileId, 'upload response should include a file_id').toBeTruthy();
+ expect(
+ (await getRagEmbedded(page)).map((e) => e.file_id),
+ 'unified upload must not embed until file_search runs',
+ ).not.toContain(fileId);
+ await expect(page.getByRole('button', { name: fileName })).toBeVisible({ timeout: 15000 });
+
+ // Embedding fires at ON_TOOL_EXECUTE, independent of the file_search tool result.
+ await sendMessage(page, `E2E_FILE_SEARCH:${uniqueName('q')}`);
+
+ await expect
+ .poll(async () => (await getRagEmbedded(page)).map((e) => e.file_id), { timeout: 30000 })
+ .toContain(fileId);
+ });
+});
diff --git a/e2e/specs/mock/helpers.ts b/e2e/specs/mock/helpers.ts
index fa08d43bc3..d5cf26f9ad 100644
--- a/e2e/specs/mock/helpers.ts
+++ b/e2e/specs/mock/helpers.ts
@@ -90,6 +90,22 @@ export async function enableMemory(page: Page) {
await expect(page.getByRole('checkbox', { name: 'Memory' })).toBeVisible();
}
+/** Enable the ephemeral Code Interpreter (execute_code) capability from the tool menu. */
+export async function enableCodeInterpreter(page: Page) {
+ await page.getByRole('button', { name: 'Tools Options' }).click();
+ await page.getByTestId('tools-menu-run-code').click();
+ await page.keyboard.press('Escape');
+ await expect(page.getByRole('checkbox', { name: 'Run Code' })).toBeVisible();
+}
+
+/** Enable the ephemeral File Search capability from the composer tool menu. */
+export async function enableFileSearch(page: Page) {
+ await page.getByRole('button', { name: 'Tools Options' }).click();
+ await page.getByTestId('tools-menu-file-search').click();
+ await page.keyboard.press('Escape');
+ await expect(page.getByRole('checkbox', { name: 'File Search' })).toBeVisible();
+}
+
/** The conversation messages container. */
export const messagesView = (page: Page) => page.getByTestId('messages-view');
@@ -369,3 +385,100 @@ export async function requestJson<T>(
export async function fetchJson<T>(page: Page, path: string, token: string): Promise<T> {
return requestJson<T>(page, { path, token });
}
+
+/** Base URLs of the fake code-exec + RAG servers started by playwright.config.mock.ts. */
+/** Defaults must match `playwright.config.mock.ts`, which keeps these clear of
+ * the MCP (8765/8766) and label (8889) fixtures. */
+export const CODE_API_BASE = `http://127.0.0.1:${process.env.E2E_CODE_API_PORT || '8790'}`;
+export const RAG_API_BASE = `http://127.0.0.1:${process.env.E2E_RAG_API_PORT || '8791'}`;
+
+export type CodeProvisionRecord = {
+ filename: string;
+ kind: string;
+ id: string;
+ storage_session_id: string;
+ fileId: string;
+};
+
+export type RagEmbedRecord = { file_id: string; filename: string; entity_id: string };
+
+/** Files the fake code server received via /upload (proof they reached the code env). */
+export async function getCodeProvisionedUploads(page: Page): Promise<CodeProvisionRecord[]> {
+ const response = await page.request.get(`${CODE_API_BASE}/__debug/uploads`);
+ expect(response.ok(), 'fake code server /__debug/uploads should respond').toBeTruthy();
+ const body = (await response.json()) as { uploads: CodeProvisionRecord[] };
+ return body.uploads;
+}
+
+/** Files the fake RAG server embedded via /embed (proof they reached the vector DB). */
+export async function getRagEmbedded(page: Page): Promise<RagEmbedRecord[]> {
+ const response = await page.request.get(`${RAG_API_BASE}/__debug/embedded`);
+ expect(response.ok(), 'fake RAG server /__debug/embedded should respond').toBeTruthy();
+ const body = (await response.json()) as { embedded: RagEmbedRecord[] };
+ return body.embedded;
+}
+
+/** Clear both fake servers' recorded provisioning (call at test start for isolation). */
+export async function resetProvisioning(page: Page): Promise<void> {
+ await Promise.all([
+ page.request.post(`${CODE_API_BASE}/__debug/reset`),
+ page.request.post(`${RAG_API_BASE}/__debug/reset`),
+ ]);
+}
+
+/** Shape of a file record as returned by POST /api/files and GET /api/files. */
+export type UploadedFile = {
+ file_id?: string;
+ filename?: string;
+ type?: string;
+ llmDeliveryPath?: string;
+ embedded?: boolean;
+ metadata?: { codeEnvRef?: { storage_session_id?: string; file_id?: string } };
+};
+
+export type AttachFile = { name: string; mimeType: string; content: string };
+
+/** Unique, filesystem-safe name so tests never collide on accumulated fake-server state. */
+export const uniqueName = (prefix: string) =>
+ `${prefix}-${Date.now()}-${Math.floor(Math.random() * 1e4)}`;
+
+const isFilesUpload = (url: string, method: string) =>
+ method === 'POST' && /\/api\/files(?:\?|$)/.test(new URL(url).pathname);
+
+/** Wait for the next POST /api/files upload response. */
+export function waitForUpload(page: Page) {
+ return page.waitForResponse((r) => isFilesUpload(r.url(), r.request().method()), {
+ timeout: 30000,
+ });
+}
+
+/** Attach a file via the unified single button (no tool resource). */
+export async function uploadViaUnifiedButton(page: Page, file: AttachFile) {
+ const uploadResponse = waitForUpload(page);
+ const [fileChooser] = await Promise.all([
+ page.waitForEvent('filechooser'),
+ page.locator('#attach-file-button').click(),
+ ]);
+ await fileChooser.setFiles({
+ name: file.name,
+ mimeType: file.mimeType,
+ buffer: Buffer.from(file.content, 'utf8'),
+ });
+ return uploadResponse;
+}
+
+/** Attach a file via a named option in the legacy 3-way dropdown. */
+export async function uploadViaLegacyOption(page: Page, optionName: string, file: AttachFile) {
+ const uploadResponse = waitForUpload(page);
+ await page.locator('#attach-file-menu-button').click();
+ const [fileChooser] = await Promise.all([
+ page.waitForEvent('filechooser'),
+ page.getByRole('menuitem', { name: optionName }).click(),
+ ]);
+ await fileChooser.setFiles({
+ name: file.name,
+ mimeType: file.mimeType,
+ buffer: Buffer.from(file.content, 'utf8'),
+ });
+ return uploadResponse;
+}
diff --git a/e2e/specs/mock/unified-upload.spec.ts b/e2e/specs/mock/unified-upload.spec.ts
new file mode 100644
index 0000000000..b064001338
--- /dev/null
+++ b/e2e/specs/mock/unified-upload.spec.ts
@@ -0,0 +1,162 @@
+import { expect, test } from '@playwright/test';
+import type { UploadedFile } from './helpers';
+import {
+ MOCK_ENDPOINTS,
+ NEW_CHAT_PATH,
+ uniqueName,
+ fetchJson,
+ isAgentsStream,
+ getAccessToken,
+ selectMockEndpoint,
+ uploadViaUnifiedButton,
+} from './helpers';
+
+/**
+ * Unified file upload — per-mime-type delivery routing (PR #12626).
+ *
+ * Runs against Mock Provider B, configured for unified mode in
+ * e2e/config/librechat.e2e.yaml (Mock Provider A stays on the legacy dropdown
+ * for chat.spec.ts's upload-to-provider test).
+ *
+ * What this proves end-to-end (real backend + DB), and what it deliberately can't:
+ * - The composer renders ONE attach button (unified mode), not the legacy 3-way
+ * dropdown.
+ * - A `none`-routed upload (csv) persists `llmDeliveryPath: 'none'` and is kept
+ * out of LLM delivery — reachable only by tools.
+ * - A `provider`-routed upload (markdown) is STILL delivered to the model AND
+ * shown as an attachment chip — unified mode doesn't lose upload-to-provider.
+ * - A `text`-routed upload (json) is extracted and persisted as `text`.
+ *
+ * The "available to the code interpreter / file_search at tool-execute time" half
+ * lives in file-provisioning.spec.ts, which drives the fake code + RAG servers.
+ *
+ * `.xlsx` follows the identical `none` code path; csv/markdown/json are used so the
+ * uploaded bytes match the declared mime type without synthesizing binaries.
+ */
+
+test.describe('unified file upload', () => {
+ test('single attach button routes a csv to llmDeliveryPath "none"', async ({ page }) => {
+ test.setTimeout(120000);
+ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
+
+ // Default model needs a real key; Mock Provider B is the unified-mode endpoint.
+ await selectMockEndpoint(page, MOCK_ENDPOINTS[1]);
+
+ // Unified mode: one attach button, and the legacy multi-option dropdown trigger
+ // is not rendered at all.
+ await expect(page.locator('#attach-file-button')).toBeVisible({ timeout: 15000 });
+ await expect(page.locator('#attach-file-menu-button')).toHaveCount(0);
+
+ // Upload-time routing: the configured override (csv -> none) must persist, so
+ // the file is kept out of LLM delivery and left for tools (code interpreter).
+ const fileName = `${uniqueName('data')}.csv`;
+ const response = await uploadViaUnifiedButton(page, {
+ name: fileName,
+ mimeType: 'text/csv',
+ content: 'name,score\nalice,1\nbob,2\n',
+ });
+ expect(response.ok()).toBeTruthy();
+
+ const uploaded = (await response.json()) as UploadedFile;
+ expect(uploaded.filename).toBe(fileName);
+ expect(uploaded.llmDeliveryPath).toBe('none');
+
+ // Persistence: the file is queryable from the backend with the same routing.
+ const token = await getAccessToken(page);
+ const files = await fetchJson<UploadedFile[]>(page, '/api/files', token);
+ const persisted = files.find((f) => f.filename === fileName);
+ expect(persisted, `uploaded file "${fileName}" should persist`).toBeTruthy();
+ expect(persisted?.llmDeliveryPath).toBe('none');
+ });
+
+ test('single attach button still delivers a provider-routed upload and shows it in chat', async ({
+ page,
+ }) => {
+ test.setTimeout(120000);
+ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
+ await selectMockEndpoint(page, MOCK_ENDPOINTS[1]);
+
+ // Same single unified button — no legacy dropdown.
+ await expect(page.locator('#attach-file-button')).toBeVisible({ timeout: 15000 });
+ await expect(page.locator('#attach-file-menu-button')).toHaveCount(0);
+
+ // markdown is overridden to `provider` for Mock Provider B: it should be
+ // delivered to the model (unlike `none`) while still attaching to the chat.
+ const fileName = `${uniqueName('doc')}.md`;
+ const response = await uploadViaUnifiedButton(page, {
+ name: fileName,
+ mimeType: 'text/markdown',
+ content: '# E2E provider doc\n\nrouted to the provider via unified upload\n',
+ });
+ expect(response.ok()).toBeTruthy();
+ expect(((await response.json()) as UploadedFile).llmDeliveryPath).toBe('provider');
+
+ // (a) shows as an attachment chip in the composer before sending.
+ await expect(page.getByRole('button', { name: fileName })).toBeVisible({ timeout: 15000 });
+
+ // (b) reaches the model input: the mock LLM echoes a pass marker only when the
+ // provider file is present in the request content (see e2e/setup/fake-model.js).
+ const input = page.getByRole('textbox', { name: 'Message input' });
+ await input.click();
+ await input.fill(`E2E_ASSERT_PROVIDER_FILE:${fileName}`);
+ const [stream] = await Promise.all([
+ page.waitForResponse(isAgentsStream, { timeout: 30000 }),
+ page.getByTestId('send-button').click(),
+ ]);
+ expect(stream.ok()).toBeTruthy();
+
+ await expect(
+ page
+ .getByTestId('messages-view')
+ .getByText(`E2E provider file assertion passed: ${fileName}`),
+ ).toBeVisible({ timeout: 20000 });
+
+ // chip persists on the sent message.
+ await expect(
+ page.getByTestId('messages-view').getByRole('button', { name: fileName }),
+ ).toBeVisible();
+ });
+
+ test('single attach button routes a json upload to llmDeliveryPath "text"', async ({ page }) => {
+ test.setTimeout(120000);
+ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
+ await selectMockEndpoint(page, MOCK_ENDPOINTS[1]);
+
+ await expect(page.locator('#attach-file-button')).toBeVisible({ timeout: 15000 });
+
+ // application/json is neither overridden nor image/pdf, so it falls through to the
+ // system fallback ('text'): extracted and delivered as text context, not a provider file.
+ const fileName = `${uniqueName('notes')}.json`;
+ const response = await uploadViaUnifiedButton(page, {
+ name: fileName,
+ mimeType: 'application/json',
+ content: '{"e2e":"unified text routing","rows":[1,2,3]}\n',
+ });
+ expect(response.ok()).toBeTruthy();
+
+ const token = await getAccessToken(page);
+ const files = await fetchJson<UploadedFile[]>(page, '/api/files', token);
+ const persisted = files.find((f) => f.filename === fileName);
+ expect(persisted, `uploaded file "${fileName}" should persist`).toBeTruthy();
+ expect(persisted?.llmDeliveryPath).toBe('text');
+ });
+
+ test('legacy endpoint renders the 3-way upload dropdown, not the single button', async ({
+ page,
+ }) => {
+ test.setTimeout(120000);
+ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
+ // Mock Provider A opts into legacyFileUploadUX.
+ await selectMockEndpoint(page, MOCK_ENDPOINTS[0]);
+
+ // Legacy: the menu-button trigger is present; the unified single button is not.
+ await expect(page.locator('#attach-file-menu-button')).toBeVisible({ timeout: 15000 });
+ await expect(page.locator('#attach-file-button')).toHaveCount(0);
+
+ // Opening it reveals the classic multi-option menu (its always-present entry is
+ // the provider upload; the code/file_search options are gated on those ephemeral
+ // capabilities being enabled first).
+ await page.locator('#attach-file-menu-button').click();
+ await expect(page.getByText('Upload to Provider')).toBeVisible();
+ });
+});
diff --git a/packages/api/src/agents/__tests__/initialize.test.ts b/packages/api/src/agents/__tests__/initialize.test.ts
index 2fdb5d0183..6c528e004d 100644
--- a/packages/api/src/agents/__tests__/initialize.test.ts
+++ b/packages/api/src/agents/__tests__/initialize.test.ts
@@ -97,6 +97,7 @@ jest.mock('~/endpoints', () => ({
jest.mock('~/files', () => ({
filterFilesByEndpointConfig: jest.fn(() => []),
filterFilesByEndpointRuntimeConfig: jest.fn(() => []),
+ isLegacyFileUploadUX: jest.fn(() => false),
}));
jest.mock('~/prompts', () => ({
@@ -110,6 +111,20 @@ jest.mock('../resources', () => ({
}),
}));
+jest.mock('../../middleware/modelBoundContent', () => {
+ const actual = jest.requireActual('../../middleware/modelBoundContent');
+ /* Real by default; a single test overrides it to stand in for a policy that started
+ * refusing a file after it was attached. */
+ return {
+ ...actual,
+ assertModelBoundContent: jest.fn((...args: unknown[]) =>
+ (actual as { assertModelBoundContent: (...a: unknown[]) => void }).assertModelBoundContent(
+ ...args,
+ ),
+ ),
+ };
+});
+
import { initializeAgent } from '../initialize';
import { isFatalAgentInitializationError } from '../errors';
@@ -2930,6 +2945,52 @@ describe('initializeAgent — code-generated file thread filter (regression)', (
return { agent, req, res, loadTools, db };
}
+ it('provisions code files for a skill tool that never names execute_code', async () => {
+ /**
+ * `bash_tool` reads the code environment but is not an `EToolResources` key, so an
+ * agent that gets it only through a skill built no provisioning state and invoked
+ * the tool against an empty sandbox. Execution-time eligibility already counted it.
+ */
+ const { agent, req, res, loadTools, db } = setupExecuteCodeAgent();
+ agent.tools = ['web_search'];
+ const { Types } = await import('mongoose');
+ const skillId = new Types.ObjectId();
+ const getSkillByName = jest.fn().mockResolvedValue({
+ _id: skillId,
+ name: 'sandbox-skill',
+ body: 'body of sandbox-skill',
+ author: { toString: () => req.user!.id } as unknown as import('mongoose').Types.ObjectId,
+ allowedTools: ['bash_tool'],
+ });
+ mockGetThreadData.mockReturnValue({ messageIds: ['msgN'], fileIds: ['file-1'] });
+ const getCodeGeneratedFiles = jest.fn().mockResolvedValue([]);
+
+ await initializeAgent(
+ {
+ req,
+ res,
+ agent,
+ loadTools,
+ endpointOption: { endpoint: EModelEndpoint.agents },
+ conversationId: 'conv-1',
+ parentMessageId: 'msgN',
+ allowedProviders: new Set([Providers.OPENAI]),
+ isInitialAgent: true,
+ codeEnvAvailable: true,
+ accessibleSkillIds: [skillId],
+ manualSkills: ['sandbox-skill'],
+ },
+ {
+ ...db,
+ getCodeGeneratedFiles,
+ getSkillByName,
+ listSkillsByAccess: async () => ({ skills: [], has_more: false, after: null }),
+ },
+ );
+
+ expect(getCodeGeneratedFiles).toHaveBeenCalledTimes(1);
+ });
+
it('passes threadFileIds (not threadMessageIds) to getCodeGeneratedFiles', async () => {
const { agent, req, res, loadTools, db } = setupExecuteCodeAgent();
@@ -3079,6 +3140,243 @@ describe('initializeAgent — code-generated file thread filter (regression)', (
expect(getUserCodeFiles).not.toHaveBeenCalled();
});
+ it('charges a file appearing in both sets against the allowance once', async () => {
+ /* An embedded attachment still missing the active code route is hydrated for delivery
+ * and returned as a provisioning candidate. Charging its bytes twice would spend an
+ * allowance the request never uses and drop a different candidate that fits. */
+ const { filterFilesByEndpointRuntimeConfig } = jest.requireMock('~/files') as {
+ filterFilesByEndpointRuntimeConfig: jest.Mock;
+ };
+ const shared = { file_id: 'shared', filename: 'a.csv', bytes: 400 };
+ const deferredOnly = { file_id: 'deferred', filename: 'b.csv', bytes: 100 };
+ const { agent, req, res, loadTools, db } = setupExecuteCodeAgent();
+
+ /* Delivery keeps the shared file; the deferred pass keeps both. */
+ filterFilesByEndpointRuntimeConfig
+ .mockReturnValueOnce([shared])
+ .mockReturnValueOnce([shared, deferredOnly]);
+ const getDeferredProvisionFiles = jest.fn().mockResolvedValue([shared, deferredOnly]);
+ const getConvoFiles = jest.fn().mockResolvedValue(['shared', 'deferred']);
+ const getToolFilesByIds = jest.fn().mockResolvedValue([shared]);
+
+ await initializeAgent(
+ {
+ req,
+ res,
+ agent,
+ loadTools,
+ endpointOption: { endpoint: EModelEndpoint.agents },
+ conversationId: 'conv-1',
+ allowedProviders: new Set([Providers.OPENAI]),
+ isInitialAgent: true,
+ codeEnvAvailable: true,
+ },
+ {
+ ...db,
+ getDeferredProvisionFiles,
+ getConvoFiles,
+ getToolFilesByIds,
+ getFiles: jest.fn().mockResolvedValue([shared, deferredOnly]),
+ },
+ );
+
+ const chargedToDeferred = filterFilesByEndpointRuntimeConfig.mock.calls
+ .map(([, params]) => (params as { consumedBytes?: number }).consumedBytes)
+ .find((bytes) => bytes !== undefined);
+ /* The only delivered file is also the shared one, and the deferred pass charges its
+ * own list as it walks it, so nothing is carried in. */
+ expect(chargedToDeferred).toBe(0);
+
+ /* The persistent screening runs inside the callback, and must see the two unique
+ * files rather than three. */
+ const { primeResources } = jest.requireMock('../resources') as { primeResources: jest.Mock };
+ const lastCall = primeResources.mock.calls[primeResources.mock.calls.length - 1];
+ const screen = lastCall?.[0].screenPersistentFiles as (files: unknown[]) => unknown[];
+ filterFilesByEndpointRuntimeConfig.mockClear();
+ filterFilesByEndpointRuntimeConfig.mockReturnValueOnce([]);
+ screen([]);
+ expect(filterFilesByEndpointRuntimeConfig).toHaveBeenCalledWith(
+ expect.anything(),
+ expect.objectContaining({ consumedBytes: 500 }),
+ );
+ });
+
+ it('screens persistent agent files under the remaining size allowance and content policy', async () => {
+ /* These are read inside primeResources, so the caller never sees them. Both checks it
+ * applied to this turn's other files have to reach them through the callback. */
+ const { filterFilesByEndpointRuntimeConfig } = jest.requireMock('~/files') as {
+ filterFilesByEndpointRuntimeConfig: jest.Mock;
+ };
+ const { primeResources } = jest.requireMock('../resources') as { primeResources: jest.Mock };
+ const { agent, req, res, loadTools, db } = setupExecuteCodeAgent();
+
+ await initializeAgent(
+ {
+ req,
+ res,
+ agent,
+ loadTools,
+ endpointOption: { endpoint: EModelEndpoint.agents },
+ allowedProviders: new Set([Providers.OPENAI]),
+ isInitialAgent: true,
+ codeEnvAvailable: true,
+ },
+ db,
+ );
+
+ const screen = primeResources.mock.calls[0][0].screenPersistentFiles as (
+ files: unknown[],
+ ) => unknown[];
+ expect(typeof screen).toBe('function');
+
+ filterFilesByEndpointRuntimeConfig.mockClear();
+ const persistent = [{ file_id: 'persistent-1', filename: 'notes.csv', bytes: 10 }];
+ filterFilesByEndpointRuntimeConfig.mockReturnValueOnce(persistent);
+
+ expect(screen(persistent)).toEqual(persistent);
+ expect(filterFilesByEndpointRuntimeConfig).toHaveBeenCalledWith(
+ expect.anything(),
+ expect.objectContaining({ consumedBytes: expect.any(Number) }),
+ );
+ });
+
+ it('drops a persistent agent file the content policy now refuses', async () => {
+ const { filterFilesByEndpointRuntimeConfig } = jest.requireMock('~/files') as {
+ filterFilesByEndpointRuntimeConfig: jest.Mock;
+ };
+ const { primeResources } = jest.requireMock('../resources') as { primeResources: jest.Mock };
+ const { assertModelBoundContent } = jest.requireMock('../../middleware/modelBoundContent') as {
+ assertModelBoundContent: jest.Mock;
+ };
+ const { agent, req, res, loadTools, db } = setupExecuteCodeAgent();
+
+ await initializeAgent(
+ {
+ req,
+ res,
+ agent,
+ loadTools,
+ endpointOption: { endpoint: EModelEndpoint.agents },
+ allowedProviders: new Set([Providers.OPENAI]),
+ isInitialAgent: true,
+ codeEnvAvailable: true,
+ },
+ db,
+ );
+
+ const screen = primeResources.mock.calls[0][0].screenPersistentFiles as (
+ files: unknown[],
+ ) => unknown[];
+ const persistent = [
+ {
+ file_id: 'blocked-1',
+ filename: 'secrets.bin',
+ bytes: 10,
+ type: 'application/octet-stream',
+ },
+ ];
+ filterFilesByEndpointRuntimeConfig.mockReturnValueOnce(persistent);
+ assertModelBoundContent.mockImplementationOnce(() => {
+ throw new Error('content policy');
+ });
+
+ expect(screen(persistent)).toEqual([]);
+ });
+
+ it('finds deferred files from the conversation when no anchor is supplied', async () => {
+ /* The Responses API always continues via `previous_response_id` and passes a null
+ * parentMessageId, and chat completions may omit it. Without an anchor there is no
+ * thread walk, so the conversation's own file refs are the only available scope. */
+ const { agent, req, res, loadTools, db } = setupExecuteCodeAgent();
+
+ const getMessages = jest.fn().mockResolvedValue([]);
+ const getConvoFiles = jest.fn().mockResolvedValue(['convo-file-1']);
+ const getDeferredProvisionFiles = jest.fn().mockResolvedValue([]);
+
+ await initializeAgent(
+ {
+ req,
+ res,
+ agent,
+ loadTools,
+ endpointOption: { endpoint: EModelEndpoint.agents },
+ conversationId: 'conv-1',
+ parentMessageId: null,
+ allowedProviders: new Set([Providers.OPENAI]),
+ isInitialAgent: true,
+ codeEnvAvailable: true,
+ },
+ { ...db, getMessages, getConvoFiles, getDeferredProvisionFiles },
+ );
+
+ expect(getMessages).not.toHaveBeenCalled();
+ expect(getDeferredProvisionFiles).toHaveBeenCalledWith(
+ ['convo-file-1'],
+ expect.anything(),
+ expect.objectContaining({ code: true }),
+ );
+ });
+
+ it('keeps an anchored branch scoped to itself when it references no files', async () => {
+ /* Widening an empty branch to the conversation would provision a sibling branch's
+ * attachments, sending files this branch never mentioned to the Code API or RAG. */
+ const { agent, req, res, loadTools, db } = setupExecuteCodeAgent();
+
+ const getMessages = jest.fn().mockResolvedValue([{ messageId: 'm1' }]);
+ const getConvoFiles = jest.fn().mockResolvedValue(['sibling-branch-file']);
+ const getDeferredProvisionFiles = jest.fn().mockResolvedValue([]);
+ mockGetThreadData.mockReturnValueOnce({ fileIds: [] });
+
+ await initializeAgent(
+ {
+ req,
+ res,
+ agent,
+ loadTools,
+ endpointOption: { endpoint: EModelEndpoint.agents },
+ conversationId: 'conv-1',
+ parentMessageId: 'parent-1',
+ allowedProviders: new Set([Providers.OPENAI]),
+ isInitialAgent: true,
+ codeEnvAvailable: true,
+ },
+ { ...db, getMessages, getConvoFiles, getDeferredProvisionFiles },
+ );
+
+ expect(getDeferredProvisionFiles).not.toHaveBeenCalled();
+ });
+
+ it('prefers the thread scope for deferred files when an anchor is supplied', async () => {
+ const { agent, req, res, loadTools, db } = setupExecuteCodeAgent();
+
+ const getMessages = jest.fn().mockResolvedValue([{ messageId: 'm1' }]);
+ const getConvoFiles = jest.fn().mockResolvedValue(['convo-file-1']);
+ const getDeferredProvisionFiles = jest.fn().mockResolvedValue([]);
+ mockGetThreadData.mockReturnValueOnce({ fileIds: ['thread-file-1'] });
+
+ await initializeAgent(
+ {
+ req,
+ res,
+ agent,
+ loadTools,
+ endpointOption: { endpoint: EModelEndpoint.agents },
+ conversationId: 'conv-1',
+ parentMessageId: 'parent-1',
+ allowedProviders: new Set([Providers.OPENAI]),
+ isInitialAgent: true,
+ codeEnvAvailable: true,
+ },
+ { ...db, getMessages, getConvoFiles, getDeferredProvisionFiles },
+ );
+
+ expect(getDeferredProvisionFiles).toHaveBeenCalledWith(
+ ['thread-file-1'],
+ expect.anything(),
+ expect.objectContaining({ code: true }),
+ );
+ });
+
it('skips the thread walk when parentMessageId is an empty string', async () => {
/* An empty anchor can never match a parent chain, so walking the
* conversation only buys an unbounded read whose result is discarded.
diff --git a/packages/api/src/agents/attachments.test.ts b/packages/api/src/agents/attachments.test.ts
index a7d6d64836..66745db153 100644
--- a/packages/api/src/agents/attachments.test.ts
+++ b/packages/api/src/agents/attachments.test.ts
@@ -48,6 +48,14 @@ describe('agent attachment helpers', () => {
text: 'injected context',
} as IMongoFile),
).toBe(true);
+ expect(
+ isModelBoundAttachmentFile({
+ file_id: 'text-with-code-ref',
+ llmDeliveryPath: 'text',
+ text: 'context survives provisioning',
+ metadata: { codeEnvRef: { file_id: 'code-file', storage_session_id: 'session' } },
+ } as IMongoFile),
+ ).toBe(true);
expect(
isModelBoundAttachmentFile({
file_id: 'empty-text',
@@ -55,6 +63,20 @@ describe('agent attachment helpers', () => {
text: '',
} as IMongoFile),
).toBe(false);
+ expect(
+ isModelBoundAttachmentFile({
+ file_id: 'lazy-code-file',
+ llmDeliveryPath: 'none',
+ bytes: 200 * 1024 * 1024,
+ } as IMongoFile),
+ ).toBe(false);
+ expect(
+ isModelBoundAttachmentFile({
+ file_id: 'provider-with-code-ref',
+ llmDeliveryPath: 'provider',
+ metadata: { codeEnvRef: { file_id: 'code-file', storage_session_id: 'session' } },
+ } as IMongoFile),
+ ).toBe(true);
});
it('summarizes unique attachment bytes and extracted text', () => {
diff --git a/packages/api/src/agents/attachments.ts b/packages/api/src/agents/attachments.ts
index 438e58fd78..2606905ff0 100644
--- a/packages/api/src/agents/attachments.ts
+++ b/packages/api/src/agents/attachments.ts
@@ -22,6 +22,7 @@ type AttachmentTelemetryFile = FileWithId & {
source?: string | null;
type?: string | null;
text?: string | null;
+ llmDeliveryPath?: string | null;
metadata?: (IMongoFile['metadata'] & { pageCount?: number | null }) | null;
};
@@ -36,6 +37,15 @@ export function isModelBoundAttachmentFile(
if (source === FileSources.text) {
return typeof file.text === 'string' && file.text.length > 0;
}
+ if (file.llmDeliveryPath === 'text') {
+ return typeof file.text === 'string' && file.text.length > 0;
+ }
+ if (file.llmDeliveryPath === 'none') {
+ return false;
+ }
+ if (file.llmDeliveryPath === 'provider') {
+ return true;
+ }
const metadata = file.metadata as
| (IMongoFile['metadata'] & { fileIdentifier?: unknown })
| null
diff --git a/packages/api/src/agents/codeFilesSession.spec.ts b/packages/api/src/agents/codeFilesSession.spec.ts
index 4a600f07aa..32c2a1f2b7 100644
--- a/packages/api/src/agents/codeFilesSession.spec.ts
+++ b/packages/api/src/agents/codeFilesSession.spec.ts
@@ -2,6 +2,7 @@ import { Constants } from '@librechat/agents';
import type { CodeEnvFile, CodeSessionContext, ToolSessionMap } from '@librechat/agents';
import {
buildAgentInitialToolSessions,
+ mergeCodeFilesIntoContext,
buildInitialToolSessions,
collectCodeExecutionProfileRoutes,
seedCodeFilesIntoSessions,
@@ -23,6 +24,62 @@ const file = (id: string, storage_session_id: string, name: string): CodeEnvFile
kind: 'user',
});
+describe('mergeCodeFilesIntoContext', () => {
+ it('adds a freshly provisioned file to an existing session context', () => {
+ const prior: CodeSessionContext = {
+ session_id: 'exec-1',
+ files: [file('a', 'store-1', 'a.csv')],
+ lastUpdated: 1,
+ };
+
+ const merged = mergeCodeFilesIntoContext(prior, [file('b', 'store-1', 'b.csv')]);
+
+ expect(merged?.session_id).toBe('exec-1');
+ expect(merged?.files.map((f) => f.id)).toEqual(['a', 'b']);
+ });
+
+ it('builds a context when the batch had none', () => {
+ const merged = mergeCodeFilesIntoContext(undefined, [file('b', 'store-2', 'b.csv')]);
+
+ expect(merged?.session_id).toBe('store-2');
+ expect(merged?.files.map((f) => f.id)).toEqual(['b']);
+ });
+
+ it('does not duplicate a file the context already carries', () => {
+ const prior: CodeSessionContext = {
+ session_id: 'exec-1',
+ files: [file('a', 'store-1', 'a.csv')],
+ lastUpdated: 1,
+ };
+
+ const merged = mergeCodeFilesIntoContext(prior, [file('a', 'store-1', 'a.csv')]);
+
+ expect(merged?.files.map((f) => f.id)).toEqual(['a']);
+ });
+
+ it('drops a provisioned file whose destination the context already claimed', () => {
+ /**
+ * The destination constraint has to hold on this path too. Lazy provisioning
+ * folds its uploads into a context the graph seeded at run start, so a name
+ * the seed already claimed reaches codeapi as a duplicate destination and
+ * takes the whole `/exec` call down, exactly as in the seeding path.
+ */
+ const prior: CodeSessionContext = {
+ session_id: 'exec-1',
+ files: [file('id-A', 'sess-A', 'data.csv')],
+ lastUpdated: 1,
+ };
+
+ const merged = mergeCodeFilesIntoContext(prior, [file('id-B', 'sess-B', 'data.csv')]);
+
+ expect(merged?.files.map((f) => f.id)).toEqual(['id-A']);
+ });
+
+ it('reports nothing to record when there are no files', () => {
+ expect(mergeCodeFilesIntoContext({ session_id: 'exec-1' }, [])).toBeUndefined();
+ });
+});
+
describe('seedCodeFilesIntoSessions', () => {
it('returns existing map untouched when files is undefined', () => {
const existing: ToolSessionMap = new Map();
diff --git a/packages/api/src/agents/codeFilesSession.ts b/packages/api/src/agents/codeFilesSession.ts
index c1ce5ae3ce..7a59af3a69 100644
--- a/packages/api/src/agents/codeFilesSession.ts
+++ b/packages/api/src/agents/codeFilesSession.ts
@@ -160,6 +160,45 @@ export function seedCodeFilesIntoSessions(
const sessions: ToolSessionMap = existing ?? new Map();
const prior = sessions.get(sessionKey) as CodeSessionContext | undefined;
+ const merged = mergeCodeFilesIntoContext(prior, files, sessionKey);
+ if (!merged) {
+ return existing;
+ }
+
+ sessions.set(sessionKey, {
+ session_id: merged.session_id,
+ files: merged.files as FileRefs,
+ lastUpdated: Date.now(),
+ } satisfies CodeSessionContext);
+
+ return sessions;
+}
+
+/**
+ * Adds primed or freshly provisioned file refs to one code-session context, keeping
+ * the ordering and identity rules the graph seed uses so both entry points agree on
+ * what the sandbox receives.
+ *
+ * Composes `(storage_session_id, id)` as the identity. `name` alone isn't sufficient:
+ * two distinct uploads can share a filename across different storage sessions and
+ * file_ids. First seen wins, so pre-existing refs keep their position.
+ *
+ * The representative top-level `session_id` is preserved when one already exists,
+ * otherwise it stands in from the first incoming file's `storage_session_id`, since
+ * no execution session exists until the first call returns one. ToolNode reads the
+ * per-file `storage_session_id` for actual injection, so the representative is
+ * informational. Mirrors the convention in `primeInvokedSkills`.
+ *
+ * Returns undefined when there is nothing usable to record.
+ */
+export function mergeCodeFilesIntoContext(
+ prior: { session_id?: string; files?: CodeEnvFile[] | FileRefs } | undefined,
+ files: CodeEnvFile[] | undefined,
+ sessionKey?: string,
+): { session_id: string; files: CodeEnvFile[] } | undefined {
+ if (!files || files.length === 0) {
+ return undefined;
+ }
/**
* Identity is `(storage_session_id, id)`, not `name` — two distinct primed
@@ -171,44 +210,31 @@ export function seedCodeFilesIntoSessions(
*/
const seenKeys = new Set<string>();
const destinations = createCodeDestinationSet();
- const mergedFiles: FileRefs = [];
+ const mergedFiles: CodeEnvFile[] = [];
const pushIfFresh = (f: { id?: string; storage_session_id?: string; name?: string }): void => {
const key = `${f.storage_session_id ?? ''}\0${f.id ?? ''}`;
if (seenKeys.has(key)) return;
if (f.name != null && !reserveCodeDestination(destinations, f.name)) {
logger.debug(
- `[seedCodeFilesIntoSessions] dropped id=${f.id} name=${f.name} ` +
- `reason=destination-taken sessionKey=${sessionKey}`,
+ `[mergeCodeFilesIntoContext] dropped id=${f.id} name=${f.name} ` +
+ `reason=destination-taken${sessionKey != null ? ` sessionKey=${sessionKey}` : ''}`,
);
return;
}
seenKeys.add(key);
- mergedFiles.push(f as FileRefs[number]);
+ mergedFiles.push(f as CodeEnvFile);
};
if (prior?.files) {
for (const f of prior.files) pushIfFresh(f);
}
for (const f of files) pushIfFresh(f);
- /* Representative top-level `session_id` for the seed CodeSessionContext.
- * No execution session exists yet at seed time, so the first incoming
- * file's `storage_session_id` stands in until the first `/exec` call
- * returns a real execution session id. ToolNode reads per-file
- * `storage_session_id` for actual injection — the representative is
- * informational rather than load-bearing. Mirrors the same convention
- * used in `primeInvokedSkills`. */
const representativeSessionId = prior?.session_id ?? files[0].storage_session_id;
if (!representativeSessionId) {
- return existing;
+ return undefined;
}
- sessions.set(sessionKey, {
- session_id: representativeSessionId,
- files: mergedFiles,
- lastUpdated: Date.now(),
- } satisfies CodeSessionContext);
-
- return sessions;
+ return { session_id: representativeSessionId, files: mergedFiles };
}
/** Builds an isolated child-graph seed from the run's exact trusted partition
diff --git a/packages/api/src/agents/handlers.ts b/packages/api/src/agents/handlers.ts
index 8886306f41..67ac39725d 100644
--- a/packages/api/src/agents/handlers.ts
+++ b/packages/api/src/agents/handlers.ts
@@ -20,6 +20,7 @@ import type {
import type { BackgroundToolResultClaim, ValidationIssue } from '@librechat/data-schemas';
import type { StructuredToolInterface } from '@librechat/agents/langchain/tools';
import type { CodeEnvRef, PtcToolCallEvent } from 'librechat-data-provider';
+import type { CodeEnvFile, CodeSessionContext } from '@librechat/agents';
import type {
WorkspaceEditResult,
WorkspacePreviewEditResult,
@@ -106,6 +107,7 @@ import {
} from './intent';
import { buildSkillPrimeMessage, isSkillFilePath, SKILL_FILE_PREFIX } from './skills';
import { resolveCallerCapabilityProjectionSnapshot } from './callerCapabilities';
+import { mergeCodeFilesIntoContext } from './codeFilesSession';
import { createSkillContentDigest } from './compatibility';
import { isMissingSandboxPathError } from '~/files/code';
import { resolveDownloadPath } from '~/storage/path';
@@ -238,6 +240,14 @@ export interface ToolExecuteOptions {
toolEndCallback?: ToolEndCallback;
/** Durable internal-completion adapter, present only for an Event Actor invocation. */
eventActorDetachedAction?: EventActorDetachedActionLifecycle;
+ /** Called once per batch before tool execution to lazily provision files to tool
+ * environments. Resolves to the code-env refs it uploaded, which the caller folds
+ * into this batch's code-session context. */
+ provisionFiles?: (
+ toolNames: string[],
+ agentId?: string,
+ signal?: AbortSignal,
+ ) => Promise<CodeEnvFile[] | void>;
/**
* Persists a backgrounded code-execution result onto the dispatch turn once
* the detached call settles: downloads/persists generated files, patches the
@@ -5150,6 +5160,7 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHand
emitAttachment,
emitPtcProgress,
subagentTasks,
+ provisionFiles,
} = options;
return {
@@ -5216,6 +5227,11 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHand
return;
}
const toolNames = [...new Set(allowedToolCalls.map((tc) => tc.name))];
+
+ const provisionedCodeFiles = provisionFiles
+ ? await provisionFiles(toolNames, agentId, runSignal)
+ : undefined;
+
const { loadedTools, configurable: toolConfigurable } = await loadTools(
toolNames,
agentId,
@@ -5228,6 +5244,26 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHand
sourceConfigurable,
loadedConfigurable,
);
+ /* The graph populated each call's code-session context from the sessions that
+ * existed at run start, before this batch provisioned anything, and nothing
+ * downstream refreshes it. buildToolCallConfig reads `_injected_files` from
+ * that context alone, so without this fold a successful upload still reaches
+ * a sandbox that cannot see the file. */
+ if (provisionedCodeFiles && provisionedCodeFiles.length > 0) {
+ for (const tc of allowedToolCalls) {
+ if (!isCodeSessionAwareToolCall(tc.name, mergedConfigurable)) {
+ continue;
+ }
+ const merged = mergeCodeFilesIntoContext(
+ tc.codeSessionContext as CodeSessionContext | undefined,
+ provisionedCodeFiles,
+ );
+ if (merged) {
+ tc.codeSessionContext = merged;
+ }
+ }
+ }
+
const codeExecutionContext = getCodeExecutionContext(mergedConfigurable);
const runtimeSessionHint = codeExecutionContext?.runtimeSessionHint;
const executionRouteKey =
diff --git a/packages/api/src/agents/initialize.files.spec.ts b/packages/api/src/agents/initialize.files.spec.ts
index 25f98bd1d4..c2875779dc 100644
--- a/packages/api/src/agents/initialize.files.spec.ts
+++ b/packages/api/src/agents/initialize.files.spec.ts
@@ -1,6 +1,10 @@
import { Tools, EToolResources } from 'librechat-data-provider';
import type { IConversation } from '@librechat/data-schemas';
-import { readResolvedConversationFiles, resolveResendToolResources } from './initialize';
+import {
+ partitionCommittedFiles,
+ readResolvedConversationFiles,
+ resolveResendToolResources,
+} from './initialize';
import { PARTIAL_RESOLVED_CONVERSATION } from './guard';
describe('readResolvedConversationFiles', () => {
@@ -58,6 +62,36 @@ describe('readResolvedConversationFiles', () => {
});
});
+describe('partitionCommittedFiles', () => {
+ it('separates files this request already screened from the rest', () => {
+ const shared = { file_id: 'shared', bytes: 2 };
+ const persistent = { file_id: 'persistent', bytes: 7 };
+
+ const { committed, pending } = partitionCommittedFiles(
+ [shared, persistent],
+ [{ file_id: 'shared' }, { file_id: 'attachment' }],
+ );
+
+ expect(committed).toEqual([shared]);
+ expect(pending).toEqual([persistent]);
+ });
+
+ it('treats a file with no id as still to screen', () => {
+ const anonymous: { file_id?: string; bytes: number } = { bytes: 1 };
+
+ expect(partitionCommittedFiles([anonymous], [{ file_id: 'shared' }])).toEqual({
+ committed: [],
+ pending: [anonymous],
+ });
+ });
+
+ it('keeps every file when nothing was committed', () => {
+ const files = [{ file_id: 'a' }, { file_id: 'b' }];
+
+ expect(partitionCommittedFiles(files, [])).toEqual({ committed: [], pending: files });
+ });
+});
+
describe('resolveResendToolResources', () => {
const resolve = (tools: string[], flags: { code: boolean; fileSearch?: boolean }) =>
resolveResendToolResources({
@@ -81,6 +115,13 @@ describe('resolveResendToolResources', () => {
]).toEqual([EToolResources.execute_code]);
});
+ it('maps sandbox file tools to execute_code and applies the same code grant', () => {
+ expect([...resolve([Tools.bash_tool, Tools.read_file], { code: true })]).toEqual([
+ EToolResources.execute_code,
+ ]);
+ expect([...resolve([Tools.bash_tool, Tools.read_file], { code: false })]).toEqual([]);
+ });
+
it('primes neither when the role carries neither grant', () => {
expect([
...resolve([Tools.execute_code, Tools.file_search], { code: false, fileSearch: false }),
diff --git a/packages/api/src/agents/initialize.ts b/packages/api/src/agents/initialize.ts
index 863179d7f8..582d723848 100644
--- a/packages/api/src/agents/initialize.ts
+++ b/packages/api/src/agents/initialize.ts
@@ -29,6 +29,15 @@ import type {
import type { GenericTool, LCToolRegistry, ToolMap, LCTool } from '@librechat/agents';
import type { IMongoFile, FileOwnerScope } from '@librechat/data-schemas';
import type { Response as ServerResponse } from 'express';
+import type {
+ TFileUpdate,
+ ProvisionState,
+ TFilterFilesByAgentAccess,
+ TProvisionToCodeEnv,
+ TProvisionToVectorDB,
+ TCheckSessionsAlive,
+ TLoadCodeApiKey,
+} from './resources';
import type {
ResolvedManualSkill,
ResolvedAlwaysApplySkill,
@@ -47,7 +56,6 @@ import type { LCAvailableTools, RequestScopedMCPConnectionStore } from '../mcp/t
import type { ContentTraversalLimitError } from '../protection/adapters/nested';
import type { SkillContentInput } from '../protection/adapters/submissions';
import type { TextContentFragment } from '../protection/types';
-import type { TFilterFilesByAgentAccess } from './resources';
import type { MCPToolAlias } from '~/tools/classification';
import type { AgentExecutionContext } from './runtime';
import {
@@ -64,28 +72,30 @@ import {
isContentTraversalProtected,
isContentTraversalLimitError,
} from '../protection/adapters/nested';
-import {
- normalizeServerName,
- requiresEphemeralUserConnection,
- splitMCPToolKey,
- normalizeAgentToolKeys,
-} from '~/mcp/utils';
-import {
- normalizeStatefulCodeEnvironment,
- resolveCodeExecutionContext,
- type CodeExecutionContext,
-} from './execution';
import {
optionalChainWithEmptyCheck,
extractLibreChatParams,
+ getSafeErrorMetadata,
getModelMaxTokens,
getThreadData,
} from '~/utils';
import {
+ isCodeFileToolName,
registerCodeExecutionTools,
registerFileAuthoringTools,
isFileAuthoringToolDefinition,
} from './tools';
+import {
+ normalizeServerName,
+ requiresEphemeralUserConnection,
+ splitMCPToolKey,
+ normalizeAgentToolKeys,
+} from '~/mcp/utils';
+import {
+ normalizeStatefulCodeEnvironment,
+ resolveCodeExecutionContext,
+ type CodeExecutionContext,
+} from './execution';
import {
createStatefulCodeEnvironmentPolicyError,
isFatalAgentInitializationError,
@@ -111,6 +121,54 @@ import { primeResources } from './resources';
* manages overflow. `createRun` can further override this via `SummarizationConfig.reserveRatio`.
*/
const DEFAULT_RESERVE_RATIO = 0.05;
+
+/**
+ * Bytes these files spend against the endpoint's total-size allowance, counting a file
+ * that appears in more than one set once. The sets overlap, an embedded attachment still
+ * missing the active code route being the case in point, and they are merged with the
+ * same deduplication downstream, so charging it twice spends an allowance the request
+ * never uses and drops another file that fits.
+ */
+/**
+ * Splits persistent files into those this request already screened and charged, and those
+ * still to screen. A setup file can also be the turn's attachment, and the sets are merged
+ * by id downstream, so charging it again against the remaining size allowance spends it
+ * twice and drops another file that would have fit.
+ */
+export function partitionCommittedFiles<T extends { file_id?: string }>(
+ files: T[],
+ committed: Array<{ file_id?: string }>,
+): { committed: T[]; pending: T[] } {
+ const ids = new Set(
+ committed.map((file) => file.file_id).filter((id): id is string => id != null),
+ );
+ const alreadyCommitted: T[] = [];
+ const pending: T[] = [];
+ for (const file of files) {
+ if (file.file_id != null && ids.has(file.file_id)) {
+ alreadyCommitted.push(file);
+ continue;
+ }
+ pending.push(file);
+ }
+ return { committed: alreadyCommitted, pending };
+}
+
+function sumUniqueBytes(files: Array<{ file_id?: string; bytes?: number }>): number {
+ const seen = new Set<string>();
+ let total = 0;
+ for (const file of files) {
+ if (file.file_id != null) {
+ if (seen.has(file.file_id)) {
+ continue;
+ }
+ seen.add(file.file_id);
+ }
+ total += file.bytes ?? 0;
+ }
+ return total;
+}
+
const temporalSpecialVarRegex = /{{\s*(current_date|current_datetime|iso_datetime)\s*}}/i;
const geminiModelVersionRegex = /^gemini-(\d+)(?:\.(\d+))?(?:-|$)/;
const googleToolCombinationTextModels = [
@@ -254,12 +312,15 @@ export function resolveResendToolResources({
}: ResolveResendToolResourcesParams): Set<EToolResources> {
const toolResourceSet = new Set<EToolResources>();
for (const tool of tools ?? []) {
- if (tool === Tools.execute_code && !codeEnvAvailable) {
+ if (isCodeFileToolName(tool) && !codeEnvAvailable) {
continue;
}
if (tool === Tools.file_search && fileSearchAvailable === false) {
continue;
}
+ if (isCodeFileToolName(tool)) {
+ toolResourceSet.add(EToolResources.execute_code);
+ }
if (EToolResources[tool as keyof typeof EToolResources]) {
toolResourceSet.add(EToolResources[tool as keyof typeof EToolResources]);
}
@@ -560,6 +621,10 @@ export type InitializedAgent = Agent & {
* context limits with the same numbers the UI shows — not default rates.
*/
endpointTokenConfig?: EndpointTokenConfig;
+ /** Warnings from lazy file provisioning (e.g., failed uploads) */
+ provisionWarnings?: string[];
+ /** State for deferred file provisioning — actual uploads happen at tool invocation time */
+ provisionState?: ProvisionState;
};
export const DEFAULT_MAX_CONTEXT_TOKENS = 32000;
@@ -724,6 +789,17 @@ export interface InitializeAgentDbMethods extends EndpointDbMethods {
) => Promise<unknown[]>;
/** Get user-uploaded execute_code files by file IDs (from message.files in thread) */
getUserCodeFiles?: (fileIds: string[], ownerScope: FileOwnerScope) => Promise<unknown[]>;
+ getDeferredProvisionFiles?: (
+ fileIds: string[],
+ ownerScope: FileOwnerScope,
+ resources?: {
+ code?: boolean;
+ search?: boolean;
+ codeRouteKey?: string;
+ searchNamespaces?: string[];
+ hydrateProvisioned?: boolean;
+ },
+ ) => Promise<unknown[]>;
/** Get messages for a conversation (supports select for field projection) */
getMessages?: (
filter: { conversationId: string },
@@ -761,6 +837,16 @@ export interface InitializeAgentDbMethods extends EndpointDbMethods {
has_more?: boolean;
after?: string | null;
}>;
+ /** Optional: provision a file to the code execution environment */
+ provisionToCodeEnv?: TProvisionToCodeEnv;
+ /** Optional: provision a file to the vector DB for file_search */
+ provisionToVectorDB?: TProvisionToVectorDB;
+ /** Optional: batch-check code env file liveness */
+ checkSessionsAlive?: TCheckSessionsAlive;
+ /** Optional: load CODE_API_KEY once per request */
+ loadCodeApiKey?: TLoadCodeApiKey;
+ /** Optional: persist file metadata updates after provisioning */
+ updateFile?: (data: TFileUpdate) => Promise<unknown>;
}
/**
@@ -1056,6 +1142,27 @@ export async function initializeAgent(
),
];
const toolFileIds: string[] = [];
+ /** Earlier-turn attachments still awaiting provisioning; provisioning input only. */
+ let deferredProvisionFiles: IMongoFile[] = [];
+ let deferredProvisionFileIds: string[] = [];
+
+ /** Build the role-gated resource set from the agent and its effective skills. */
+ const resourceToolNames = [...(agent.tools ?? [])];
+ /* A skill's allowed-tools can contribute file_search or execute_code that the agent
+ * itself does not list. Eligibility has to reflect the effective tool set, or invoking
+ * the skill's tool searches or runs code with nothing provisioned. The primes are
+ * resolved above, so this needs no reordering, and the MCP name heal applied to the
+ * union later never rewrites these plain resource names. */
+ for (const prime of [...(manualSkillPrimes ?? []), ...(alwaysApplySkillPrimes ?? [])]) {
+ for (const tool of prime.allowedTools ?? []) {
+ resourceToolNames.push(tool);
+ }
+ }
+ const toolResourceSet = resolveResendToolResources({
+ tools: resourceToolNames,
+ codeEnvAvailable: params.codeEnvAvailable === true,
+ fileSearchAvailable: params.fileSearchAvailable,
+ });
/**
* Load conversation files for ALL agents, not just the initial agent.
@@ -1063,24 +1170,22 @@ export async function initializeAgent(
* in the conversation. Without this, file_search and execute_code tools
* on handoff agents would fail to find previously attached files.
*/
- if (conversationId != null && resendFiles) {
- /** Both flags already carry their role grant, so a denied role skips the
- * thread walk and the hydration below rather than paying for resources the
- * tool loader is about to drop. */
- const toolResourceSet = resolveResendToolResources({
- tools: agent.tools,
- codeEnvAvailable: effectiveCodeEnvAvailable,
- fileSearchAvailable: params.fileSearchAvailable,
- });
-
+ /* `resendFiles` governs whether earlier attachments are sent to the model again, so
+ * it gates the delivery queries below. Deferred provisioning candidates are already
+ * excluded from delivery, and a sandbox or search call still needs its inputs, so
+ * that lookup runs whichever way the setting is configured. */
+ const wantsCodeFiles = toolResourceSet.has(EToolResources.execute_code);
+ const wantsSearchFiles = toolResourceSet.has(EToolResources.file_search);
+ const wantsProvisioning = wantsCodeFiles || wantsSearchFiles;
+
+ if (conversationId != null && (resendFiles || wantsProvisioning)) {
const getThreadMessages = db.getMessages;
/** Falsy anchors cannot match a parent chain, so they get no walk. */
const threadAnchor =
parentMessageId && parentMessageId !== Constants.NO_PARENT ? parentMessageId : null;
- const needsThreadWalk =
- toolResourceSet.has(EToolResources.execute_code) &&
- threadAnchor != null &&
- getThreadMessages != null;
+ /* Either provisioning resource needs the anchor: deferred attachments for
+ * file_search are found by thread file ids just as code files are. */
+ const needsThreadWalk = wantsProvisioning && threadAnchor != null && getThreadMessages != null;
/**
* The conversation's file refs and the thread walk share no inputs, so they resolve
@@ -1111,6 +1216,17 @@ export async function initializeAgent(
? getThreadData(threadMessages, threadAnchor).fileIds
: undefined;
+ /* Linear continuation APIs supply no anchor: the Responses API always continues via
+ * `previous_response_id`, and chat completions may send `conversation_id` alone. There
+ * is no branch to walk in either case, so the conversation's own file refs are both the
+ * correct scope and the only one available. Without this the deferred lookup never runs
+ * there, and a later code or search call executes without the attachment.
+ *
+ * An anchored walk keeps its own result even when empty. Widening a branch that
+ * references no files to the whole conversation would provision a sibling branch's
+ * attachments, sending files this branch never mentioned to the Code API or RAG. */
+ const provisionFileIds = threadAnchor == null ? fileIds : (threadFileIds ?? []);
+
/**
* Retrieve execute_code files filtered to the current thread.
* This includes both code-generated files and user-uploaded execute_code files.
@@ -1121,20 +1237,24 @@ export async function initializeAgent(
* both on `threadFileIds` reaches files regardless of which sibling first generated
* them — see `getCodeGeneratedFiles` for the branched-conversation rationale.
*/
- const wantsCodeFiles = toolResourceSet.has(EToolResources.execute_code);
- const [toolFiles, codeGeneratedFiles, userCodeFiles] = await Promise.all([
- requestFileOwnerScope
+ /* Attachments accepted on an earlier turn whose tool never ran are absent from the
+ * three queries below, since those match only files that already carry the result
+ * of provisioning. Fetched alongside them, not after: it is independent of all
+ * three, and this runs on the agent initialization path. */
+ const [toolFiles, codeGeneratedFiles, userCodeFiles, deferredFiles] = await Promise.all([
+ resendFiles && requestFileOwnerScope
? (db.getToolFilesByIds(fileIds, toolResourceSet, requestFileOwnerScope) as Promise<
IMongoFile[]
>)
: ([] as IMongoFile[]),
- wantsCodeFiles && db.getCodeGeneratedFiles && requestFileOwnerScope
+ resendFiles && wantsCodeFiles && db.getCodeGeneratedFiles && requestFileOwnerScope
? (db.getCodeGeneratedFiles(
conversationId,
threadFileIds,
requestFileOwnerScope,
) as Promise<IMongoFile[]>)
: ([] as IMongoFile[]),
+ resendFiles &&
wantsCodeFiles &&
db.getUserCodeFiles &&
requestFileOwnerScope &&
@@ -1142,8 +1262,35 @@ export async function initializeAgent(
threadFileIds.length > 0
? (db.getUserCodeFiles(threadFileIds, requestFileOwnerScope) as Promise<IMongoFile[]>)
: ([] as IMongoFile[]),
+ wantsProvisioning &&
+ db.getDeferredProvisionFiles &&
+ requestFileOwnerScope &&
+ provisionFileIds.length > 0
+ ? (db.getDeferredProvisionFiles(provisionFileIds, requestFileOwnerScope, {
+ code: wantsCodeFiles,
+ search: wantsSearchFiles,
+ codeRouteKey:
+ codeExecutionContext.executionRouteKey ?? codeExecutionContext.executionProfile,
+ /* Both namespaces an attachment can be embedded under this turn: this agent's,
+ * for its own resource files, and the user's for everything else. */
+ searchNamespaces: [agent.id, requestFileOwnerId].filter(
+ (id): id is string => typeof id === 'string',
+ ),
+ /* With resendFiles on, getToolFilesByIds already loads provisioned files and
+ * both priming and the staleness probe see them. Off, this query is the only
+ * one that runs, for search as well as for code. */
+ hydrateProvisioned: !resendFiles,
+ }) as Promise<IMongoFile[]>)
+ : ([] as IMongoFile[]),
]);
+ /* Ids only: these are hydrated with the request's own files below so the same
+ * content policy applies before their bytes can reach the Code API or RAG. They
+ * are kept out of the delivery set, not out of inspection. */
+ deferredProvisionFileIds = deferredFiles
+ .map((file) => file.file_id)
+ .filter((fileId): fileId is string => typeof fileId === 'string');
+
const allToolFiles = toolFiles.concat(codeGeneratedFiles, userCodeFiles);
const snapshotFileIds = new Set(requestFileIds);
for (const file of allToolFiles) {
@@ -1163,7 +1310,7 @@ export async function initializeAgent(
* keep this exact snapshot authoritative for inspection, priming, and the
* later usage update to avoid a post-inspection re-read.
*/
- const snapshotFileIds = [...requestFileIds, ...toolFileIds];
+ const snapshotFileIds = [...requestFileIds, ...toolFileIds, ...deferredProvisionFileIds];
let requestUsageFiles: IMongoFile[] = [];
let toolUsageFiles: IMongoFile[] = [];
if (requestFileOwnerScope && snapshotFileIds.length > 0) {
@@ -1190,16 +1337,20 @@ export async function initializeAgent(
toolUsageFiles = toolFileIds
.map((fileId) => hydratedFilesById.get(fileId))
.filter((file): file is IMongoFile => file != null);
+ deferredProvisionFiles = deferredProvisionFileIds
+ .map((fileId) => hydratedFilesById.get(fileId))
+ .filter((file): file is IMongoFile => file != null);
}
if (requestFiles.length > 0 || toolFileIds.length > 0) {
currentFiles = requestUsageFiles.concat(toolUsageFiles);
}
- if (currentFiles && currentFiles.length) {
- let endpointType: EModelEndpoint | undefined;
- if (!paramEndpoints.has(agent.endpoint ?? '')) {
- endpointType = EModelEndpoint.custom;
- }
+ let endpointFileType: EModelEndpoint | undefined;
+ if (!paramEndpoints.has(agent.endpoint ?? '')) {
+ endpointFileType = EModelEndpoint.custom;
+ }
+ if ((currentFiles && currentFiles.length) || deferredProvisionFiles.length > 0) {
+ const endpointType = endpointFileType;
currentFiles = filterFilesByEndpointRuntimeConfig(appConfig, {
files: currentFiles,
@@ -1217,6 +1368,38 @@ export async function initializeAgent(
endpoint: agent.endpoint ?? '',
endpointType,
});
+
+ /* The same endpoint configuration governs both paths. A file this endpoint refuses
+ * by size, MIME type, or a files-disabled setting must not reach the Code API or
+ * RAG through provisioning just because it left the delivery set. */
+ if (deferredProvisionFiles.length > 0) {
+ /* One request, one total-size allowance. Filtering each set from zero would let a
+ * delivery attachment and a provisioning candidate that each fit alone exceed the
+ * limit together once withDeferredCandidates merges them.
+ *
+ * A file can appear in both sets, an embedded attachment still missing the active
+ * code route being the case in point, and the merge deduplicates afterwards. Charging
+ * it twice would spend an allowance the request never uses and drop a different
+ * candidate that fits, so the shared ones are counted once. */
+ const deferredFileIds = new Set(
+ deferredProvisionFiles
+ .map((file) => file.file_id)
+ .filter((fileId): fileId is string => fileId != null),
+ );
+ deferredProvisionFiles = filterFilesByEndpointRuntimeConfig(appConfig, {
+ files: deferredProvisionFiles,
+ endpoint: agent.endpoint ?? '',
+ endpointType,
+ /* The deferred pass charges its own list as it walks it, so a file in both sets
+ * is counted there. Only what delivery spends on files the deferred pass will
+ * not see is carried in. */
+ consumedBytes: sumUniqueBytes(
+ (currentFiles ?? []).filter(
+ (file) => file.file_id == null || !deferredFileIds.has(file.file_id),
+ ),
+ ),
+ }) as IMongoFile[];
+ }
}
assertModelBoundContent({
@@ -1224,6 +1407,26 @@ export async function initializeAgent(
files: currentFiles,
});
+ /* Provisioning candidates are inspected under the same policy before their bytes can
+ * be sent to the Code API or RAG. A violator is dropped rather than failing the turn:
+ * these were not attached by this request, and before deferred hydration existed they
+ * were simply absent, so refusing the conversation over a historical record would be
+ * a harsher outcome than the one this change replaced. */
+ if (deferredProvisionFiles.length > 0) {
+ deferredProvisionFiles = deferredProvisionFiles.filter((file) => {
+ try {
+ assertModelBoundContent({ filters: appConfig?.filters, files: [file] });
+ return true;
+ } catch (error) {
+ logger.warn(
+ `[initializeAgent] Skipping provisioning for "${file.filename}" (${file.file_id}): content policy`,
+ getSafeErrorMetadata(error),
+ );
+ return false;
+ }
+ });
+ }
+
/**
* Usage accounting is the first file mutation. It runs only after every
* hydrated file in the exact snapshot above has passed endpoint filtering
@@ -1248,7 +1451,10 @@ export async function initializeAgent(
requestAttachments: primedRequestAttachments,
agentContextAttachments: primedAgentContextAttachments,
tool_resources,
+ provisionState,
+ warnings: provisionWarnings,
} = await primeResources({
+ req: params.req,
principal: user,
getFiles: db.getFiles as never,
filterFiles: db.filterFilesByAgentAccess,
@@ -1259,6 +1465,46 @@ export async function initializeAgent(
: undefined,
tool_resources: agent.tool_resources,
requestFileSet: new Set(requestFiles?.map((file) => file.file_id)),
+ enabledToolResources: toolResourceSet,
+ checkSessionsAlive: db.checkSessionsAlive,
+ loadCodeApiKey: db.loadCodeApiKey,
+ provisionCandidates: deferredProvisionFiles as unknown as TFile[],
+ codeRouteKey: codeExecutionContext.executionRouteKey ?? codeExecutionContext.executionProfile,
+ codeBaseUrl: codeExecutionContext.baseUrl,
+ screenPersistentFiles: (files) => {
+ /* Persistent agent files are read inside primeResources, so they miss both checks
+ * the caller already applied to this turn's other files. They face the same
+ * endpoint policy under the remainder of the one total-size allowance the current
+ * and deferred sets have already drawn on, and the same content policy, which can
+ * have changed since the file was attached. */
+ const committedFiles = [...(currentFiles ?? []), ...deferredProvisionFiles];
+ const { committed, pending } = partitionCommittedFiles(files, committedFiles);
+ const withinPolicy = filterFilesByEndpointRuntimeConfig(appConfig, {
+ files: pending as unknown as IMongoFile[],
+ endpoint: agent.endpoint ?? '',
+ endpointType: endpointFileType,
+ consumedBytes: sumUniqueBytes(committedFiles),
+ }) as unknown as TFile[];
+
+ /* Dropped rather than fatal, matching the deferred candidates: these were not
+ * attached by this request, so refusing the conversation over a historical record
+ * would be harsher than leaving it out. */
+ return committed.concat(withinPolicy).filter((file) => {
+ try {
+ assertModelBoundContent({
+ filters: appConfig?.filters,
+ files: [file] as unknown as IMongoFile[],
+ });
+ return true;
+ } catch (error) {
+ logger.warn(
+ `[initializeAgent] Skipping persistent agent file "${file.filename}" (${file.file_id}): content policy`,
+ error,
+ );
+ return false;
+ }
+ });
+ },
});
/**
@@ -1895,6 +2141,9 @@ export async function initializeAgent(
useLegacyContent: !!options.useLegacyContent,
tools: (tools ?? []) as GenericTool[] & string[],
maxToolResultChars: maxToolResultCharsResolved,
+ provisionState,
+ provisionWarnings:
+ provisionWarnings != null && provisionWarnings.length > 0 ? provisionWarnings : undefined,
maxContextTokens:
maxContextTokens != null && maxContextTokens > 0
? maxContextTokens
diff --git a/packages/api/src/agents/resources.test.ts b/packages/api/src/agents/resources.test.ts
index 4a200f935f..fff479b146 100644
--- a/packages/api/src/agents/resources.test.ts
+++ b/packages/api/src/agents/resources.test.ts
@@ -1,9 +1,10 @@
import { logger } from '@librechat/data-schemas';
import {
+ FileSources,
+ FileContext,
EModelEndpoint,
EToolResources,
AgentCapabilities,
- FileSources,
} from 'librechat-data-provider';
import type { TAgentsEndpoint, TFile } from 'librechat-data-provider';
import type { IUser, AppConfig } from '@librechat/data-schemas';
@@ -15,6 +16,7 @@ import { primeResources } from './resources';
jest.mock('@librechat/data-schemas', () => ({
logger: {
error: jest.fn(),
+ info: jest.fn(),
},
}));
@@ -95,6 +97,131 @@ describe('primeResources', () => {
});
});
+ describe('embedding state across agents that share a file record', () => {
+ const sharedContextFile = (embeddedEntities?: string[]): TFile =>
+ ({
+ user: 'user1',
+ file_id: 'shared-context-file',
+ filename: 'notes.pdf',
+ filepath: '/uploads/notes.pdf',
+ object: 'file' as const,
+ type: 'application/pdf',
+ bytes: 1024,
+ usage: 0,
+ embedded: true,
+ source: FileSources.local,
+ context: FileContext.agents,
+ ...(embeddedEntities ? { metadata: { embeddedEntities } } : {}),
+ }) as TFile;
+
+ const primeFor = (agentId: string, file: TFile) => {
+ mockGetFiles.mockResolvedValue([file]);
+ return primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ requestFileSet,
+ attachments: undefined,
+ tool_resources: { [EToolResources.context]: { file_ids: ['shared-context-file'] } },
+ agentId,
+ enabledToolResources: new Set([EToolResources.file_search]),
+ });
+ };
+
+ it('re-embeds for an agent whose namespace was never provisioned', async () => {
+ /* A duplicated agent inherits the file id but searches its own namespace, so the
+ * record-wide embedded flag cannot answer for it. */
+ const result = await primeFor('agent-b', sharedContextFile(['agent-a']));
+
+ expect(result.provisionState?.vectorDBFiles.map((f) => f.file_id)).toEqual([
+ 'shared-context-file',
+ ]);
+ });
+
+ it('does not re-embed for the agent that already provisioned it', async () => {
+ const result = await primeFor('agent-a', sharedContextFile(['agent-a']));
+
+ expect(result.provisionState).toBeUndefined();
+ });
+ });
+
+ describe('when policy screening rejects a persistent context file', () => {
+ it('keeps it out of provisioning and out of attachments', async () => {
+ /* These files are read inside primeResources, so the caller never sees them to
+ * filter. A provider or policy change since they were attached must still stop
+ * their bytes reaching the Code API or RAG. */
+ const rejected: TFile[] = [
+ {
+ user: 'user1',
+ file_id: 'stale-context-file',
+ filename: 'legacy.csv',
+ filepath: '/uploads/legacy.csv',
+ object: 'file' as const,
+ type: 'text/csv',
+ bytes: 1024,
+ embedded: false,
+ usage: 0,
+ source: FileSources.local,
+ metadata: { destinationChosen: false },
+ },
+ ];
+ mockGetFiles.mockResolvedValue(rejected);
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ requestFileSet,
+ attachments: undefined,
+ tool_resources: { [EToolResources.context]: { file_ids: ['stale-context-file'] } },
+ agentId: 'agent_test',
+ enabledToolResources: new Set([EToolResources.execute_code, EToolResources.file_search]),
+ screenPersistentFiles: () => [],
+ });
+
+ expect(result.provisionState).toBeUndefined();
+ expect(result.attachments).toBeUndefined();
+ });
+
+ it('still provisions a persistent context file the policy allows', async () => {
+ const allowed: TFile[] = [
+ {
+ user: 'user1',
+ file_id: 'live-context-file',
+ filename: 'data.csv',
+ filepath: '/uploads/data.csv',
+ object: 'file' as const,
+ type: 'text/csv',
+ bytes: 1024,
+ embedded: false,
+ usage: 0,
+ source: FileSources.local,
+ metadata: { destinationChosen: false },
+ },
+ ];
+ mockGetFiles.mockResolvedValue(allowed);
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ requestFileSet,
+ attachments: undefined,
+ tool_resources: { [EToolResources.context]: { file_ids: ['live-context-file'] } },
+ agentId: 'agent_test',
+ enabledToolResources: new Set([EToolResources.execute_code, EToolResources.file_search]),
+ screenPersistentFiles: (files) => files,
+ });
+
+ expect(result.provisionState?.codeEnvFiles.map((f) => f.file_id)).toEqual([
+ 'live-context-file',
+ ]);
+ });
+ });
+
describe('when `context` capability is disabled', () => {
it('should not fetch context files even if tool_resources has context file_ids', async () => {
(mockAppConfig.endpoints![EModelEndpoint.agents] as TAgentsEndpoint).capabilities = [];
@@ -1110,7 +1237,7 @@ describe('primeResources', () => {
expect(logger.error).toHaveBeenCalledWith('Error priming resources', error);
expect(result.attachments).toEqual(mockFiles);
- expect(result.tool_resources).toEqual(tool_resources);
+ expect(result.tool_resources).toEqual({});
});
it('should handle promise rejection in attachments', async () => {
@@ -1581,7 +1708,7 @@ describe('primeResources', () => {
});
expect(logger.error).toHaveBeenCalledWith('Error priming resources', expect.any(Error));
- expect(result.tool_resources).toEqual(tool_resources);
+ expect(result.tool_resources).toEqual({});
});
it('should skip filtering when agentId is missing', async () => {
@@ -1691,4 +1818,1336 @@ describe('primeResources', () => {
expect(result.tool_resources?.[EToolResources.image_edit]).toBeUndefined();
});
});
+
+ describe('llmDeliveryPath handling', () => {
+ it('should keep files with llmDeliveryPath "none" in attachments', async () => {
+ const providerFile: TFile = {
+ user: 'user1',
+ file_id: 'provider-file',
+ filename: 'image.png',
+ filepath: '/path/image.png',
+ type: 'image/png',
+ bytes: 1000,
+ object: 'file' as const,
+ usage: 0,
+ embedded: false,
+ source: FileSources.local,
+ llmDeliveryPath: 'provider',
+ width: 100,
+ height: 100,
+ };
+ const noneFile: TFile = {
+ user: 'user1',
+ file_id: 'none-file',
+ filename: 'audio.mp3',
+ filepath: '/path/audio.mp3',
+ type: 'audio/mpeg',
+ bytes: 5000,
+ object: 'file' as const,
+ usage: 0,
+ embedded: false,
+ source: FileSources.local,
+ llmDeliveryPath: 'none',
+ metadata: { destinationChosen: false },
+ };
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([providerFile, noneFile]),
+ requestFileSet,
+ agentId: 'agent1',
+ });
+
+ const attachmentIds = result.attachments?.map((f) => f?.file_id);
+ expect(attachmentIds).toContain('provider-file');
+ expect(attachmentIds).toContain('none-file');
+ });
+
+ it('should include llmDeliveryPath "none" files in lazy provisioning state', async () => {
+ const noneFile: TFile = {
+ user: 'user1',
+ file_id: 'none-file',
+ filename: 'data.csv',
+ filepath: '/path/data.csv',
+ type: 'text/csv',
+ bytes: 5000,
+ object: 'file' as const,
+ usage: 0,
+ embedded: false,
+ source: FileSources.local,
+ llmDeliveryPath: 'none',
+ metadata: { destinationChosen: false },
+ };
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([noneFile]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code, EToolResources.file_search]),
+ loadCodeApiKey: jest.fn().mockResolvedValue('code-key'),
+ });
+
+ expect(result.attachments?.map((f) => f?.file_id)).toContain('none-file');
+ expect(result.provisionState?.codeEnvFiles.map((f) => f.file_id)).toContain('none-file');
+ expect(result.provisionState?.vectorDBFiles.map((f) => f.file_id)).toContain('none-file');
+ });
+
+ it('provisions nothing when the legacy destination chooser is active', async () => {
+ /* In legacy mode the destination is the user's explicit choice and the upload path
+ * already acted on it, so a missing reference records a decline, not pending work.
+ * Queueing on it would send the file to a service the user did not select. */
+ const providerFile: TFile = {
+ user: 'user1',
+ file_id: 'provider-file',
+ filename: 'data.csv',
+ filepath: '/path/data.csv',
+ type: 'text/csv',
+ bytes: 5000,
+ object: 'file' as const,
+ usage: 0,
+ embedded: false,
+ source: FileSources.local,
+ };
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([providerFile]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code, EToolResources.file_search]),
+ loadCodeApiKey: jest.fn().mockResolvedValue('code-key'),
+ });
+
+ expect(result.attachments?.map((f) => f?.file_id)).toContain('provider-file');
+ expect(result.provisionState).toBeUndefined();
+ });
+
+ it('should include files with undefined llmDeliveryPath in attachments (legacy files)', async () => {
+ const legacyFile: TFile = {
+ user: 'user1',
+ file_id: 'legacy-file',
+ filename: 'doc.pdf',
+ filepath: '/path/doc.pdf',
+ type: 'application/pdf',
+ bytes: 2000,
+ object: 'file' as const,
+ usage: 0,
+ embedded: false,
+ source: FileSources.local,
+ };
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([legacyFile]),
+ requestFileSet,
+ agentId: 'agent1',
+ });
+
+ const attachmentIds = result.attachments?.map((f) => f?.file_id);
+ expect(attachmentIds).toContain('legacy-file');
+ });
+ });
+
+ describe('code auth gating for lazy provisioning', () => {
+ const priorAuthProvider = process.env.CODEAPI_AUTH_PROVIDER;
+ const priorJwtEnabled = process.env.CODEAPI_JWT_ENABLED;
+
+ afterEach(() => {
+ if (priorAuthProvider === undefined) {
+ delete process.env.CODEAPI_AUTH_PROVIDER;
+ } else {
+ process.env.CODEAPI_AUTH_PROVIDER = priorAuthProvider;
+ }
+ if (priorJwtEnabled === undefined) {
+ delete process.env.CODEAPI_JWT_ENABLED;
+ } else {
+ process.env.CODEAPI_JWT_ENABLED = priorJwtEnabled;
+ }
+ });
+
+ const makeCodeFile = (overrides: Partial<TFile> = {}): TFile => ({
+ user: 'user1',
+ file_id: 'code-file',
+ filename: 'data.csv',
+ filepath: '/path/data.csv',
+ type: 'text/csv',
+ bytes: 5000,
+ object: 'file' as const,
+ usage: 0,
+ embedded: false,
+ source: FileSources.local,
+ llmDeliveryPath: 'none',
+ metadata: { destinationChosen: false },
+ ...overrides,
+ });
+
+ it('populates codeEnvFiles under JWT code auth without a legacy key', async () => {
+ process.env.CODEAPI_AUTH_PROVIDER = 'librechat-jwt';
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([makeCodeFile()]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code]),
+ });
+
+ expect(result.provisionState?.codeEnvFiles.map((f) => f.file_id)).toContain('code-file');
+ });
+
+ it('still queues provisioning for an unauthenticated Code API deployment', async () => {
+ delete process.env.CODEAPI_AUTH_PROVIDER;
+ delete process.env.CODEAPI_JWT_ENABLED;
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([makeCodeFile()]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code]),
+ loadCodeApiKey: jest.fn().mockResolvedValue(undefined),
+ });
+
+ expect(result.provisionState?.codeEnvFiles.map((f) => f.file_id)).toContain('code-file');
+ });
+
+ it('passes req through to checkSessionsAlive so JWT auth can mint tokens', async () => {
+ process.env.CODEAPI_AUTH_PROVIDER = 'librechat-jwt';
+ const checkSessionsAlive = jest.fn().mockResolvedValue(new Set(['ref-file']));
+ const refFile = makeCodeFile({
+ file_id: 'ref-file',
+ metadata: {
+ codeEnvRef: { kind: 'user', id: 'user1', storage_session_id: 'sess', file_id: 'remote' },
+ },
+ });
+
+ await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([refFile]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code]),
+ checkSessionsAlive,
+ });
+
+ expect(checkSessionsAlive).toHaveBeenCalledWith(
+ expect.objectContaining({ req: mockReq, apiKey: undefined }),
+ );
+ });
+
+ it('queues re-provisioning and clears refs for a pre-categorized stale code file', async () => {
+ process.env.CODEAPI_AUTH_PROVIDER = 'librechat-jwt';
+ const checkSessionsAlive = jest.fn().mockResolvedValue(new Set<string>());
+ const staleFile = makeCodeFile({
+ file_id: 'stale-file',
+ metadata: {
+ codeEnvRef: {
+ kind: 'user',
+ id: 'user1',
+ storage_session_id: 'sess',
+ file_id: 'remote',
+ executionProfile: 'default',
+ },
+ codeEnvRefs: {
+ default: {
+ kind: 'user',
+ id: 'user1',
+ storage_session_id: 'sess',
+ file_id: 'remote',
+ executionProfile: 'default',
+ },
+ 'stateful:env1': {
+ kind: 'user',
+ id: 'user1',
+ storage_session_id: 'sess-2',
+ file_id: 'remote-2',
+ executionProfile: 'stateful',
+ },
+ },
+ },
+ });
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([staleFile]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code]),
+ checkSessionsAlive,
+ });
+
+ expect(result.provisionState?.codeEnvFiles.map((f) => f.file_id)).toContain('stale-file');
+ expect(staleFile.metadata?.codeEnvRef).toBeUndefined();
+ expect(staleFile.metadata?.codeEnvRefs?.default).toBeUndefined();
+ expect(staleFile.metadata?.codeEnvRefs?.['stateful:env1']).toBeDefined();
+ });
+
+ it('probes a stateful route against its own Code API and clears its stale ref', async () => {
+ /* A configured deployment issues its own refs, so leaving it out of the probe left
+ * a dead session usable forever: nothing queued a replacement and the same file id
+ * was injected on every later turn. */
+ process.env.CODEAPI_AUTH_PROVIDER = 'librechat-jwt';
+ const checkSessionsAlive = jest.fn().mockResolvedValue(new Set<string>());
+ const statefulFile = makeCodeFile({
+ file_id: 'stateful-stale',
+ metadata: {
+ codeEnvRefs: {
+ default: {
+ kind: 'user',
+ id: 'user1',
+ storage_session_id: 'sess-default',
+ file_id: 'remote-default',
+ executionProfile: 'default',
+ },
+ 'stateful:env1': {
+ kind: 'user',
+ id: 'user1',
+ storage_session_id: 'sess-2',
+ file_id: 'remote-2',
+ executionProfile: 'stateful',
+ executionRouteKey: 'stateful:env1',
+ },
+ },
+ },
+ });
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([statefulFile]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code]),
+ checkSessionsAlive,
+ codeRouteKey: 'stateful:env1',
+ codeBaseUrl: 'https://stateful.example.com',
+ });
+
+ expect(checkSessionsAlive).toHaveBeenCalledWith(
+ expect.objectContaining({
+ baseURL: 'https://stateful.example.com',
+ routeKey: 'stateful:env1',
+ }),
+ );
+ expect(result.provisionState?.codeEnvFiles.map((f) => f.file_id)).toContain('stateful-stale');
+ expect(statefulFile.metadata?.codeEnvRefs?.['stateful:env1']).toBeUndefined();
+ /* Another deployment's ref is untouched: this probe never asked about it. */
+ expect(statefulFile.metadata?.codeEnvRefs?.default).toBeDefined();
+ });
+
+ it('keeps alive pre-categorized files out of the provisioning queue', async () => {
+ process.env.CODEAPI_AUTH_PROVIDER = 'librechat-jwt';
+ const checkSessionsAlive = jest.fn().mockResolvedValue(new Set(['alive-file']));
+ const aliveFile = makeCodeFile({
+ file_id: 'alive-file',
+ metadata: {
+ codeEnvRef: { kind: 'user', id: 'user1', storage_session_id: 'sess', file_id: 'remote' },
+ },
+ });
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([aliveFile]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code]),
+ checkSessionsAlive,
+ });
+
+ expect(result.provisionState).toBeUndefined();
+ const codeFiles = result.tool_resources?.[EToolResources.execute_code]?.files;
+ expect(codeFiles?.map((f) => f.file_id)).toContain('alive-file');
+ });
+
+ it('does not treat refs as stale when no liveness check ran', async () => {
+ process.env.CODEAPI_AUTH_PROVIDER = 'librechat-jwt';
+ const refFile = makeCodeFile({
+ file_id: 'unchecked-file',
+ metadata: {
+ codeEnvRef: { kind: 'user', id: 'user1', storage_session_id: 'sess', file_id: 'remote' },
+ },
+ });
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([refFile]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code]),
+ });
+
+ expect(result.provisionState).toBeUndefined();
+ expect(refFile.metadata?.codeEnvRef).toBeDefined();
+ });
+
+ it('skips the liveness check when JWT auth has no req to mint from', async () => {
+ process.env.CODEAPI_AUTH_PROVIDER = 'librechat-jwt';
+ const checkSessionsAlive = jest.fn();
+ const refFile = makeCodeFile({
+ file_id: 'principal-file',
+ metadata: {
+ codeEnvRef: { kind: 'user', id: 'user1', storage_session_id: 'sess', file_id: 'remote' },
+ },
+ });
+
+ const result = await primeResources({
+ principal: { id: 'user1', role: 'USER' },
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([refFile]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code]),
+ checkSessionsAlive,
+ });
+
+ expect(checkSessionsAlive).not.toHaveBeenCalled();
+ expect(result.provisionState).toBeUndefined();
+ expect(refFile.metadata?.codeEnvRef).toBeDefined();
+ });
+
+ it('never clears a non-default route ref probed against the default Code API', async () => {
+ process.env.CODEAPI_AUTH_PROVIDER = 'librechat-jwt';
+ const checkSessionsAlive = jest.fn().mockResolvedValue(new Set<string>());
+ const statefulRef = {
+ kind: 'user' as const,
+ id: 'user1',
+ storage_session_id: 'sess-stateful',
+ file_id: 'remote-stateful',
+ executionProfile: 'stateful' as const,
+ executionRouteKey: 'stateful:abc',
+ };
+ const statefulFile = makeCodeFile({
+ file_id: 'stateful-file',
+ metadata: { codeEnvRef: statefulRef, codeEnvRefs: { 'stateful:abc': statefulRef } },
+ });
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([statefulFile]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code]),
+ checkSessionsAlive,
+ /* The agent runs on the same route the ref names, so the file is already usable
+ * and the probe has nothing to clear. */
+ codeRouteKey: 'stateful:abc',
+ });
+
+ expect(checkSessionsAlive).not.toHaveBeenCalled();
+ expect(result.provisionState).toBeUndefined();
+ expect(statefulFile.metadata?.codeEnvRef).toEqual(statefulRef);
+ expect(statefulFile.metadata?.codeEnvRefs?.['stateful:abc']).toEqual(statefulRef);
+ });
+
+ it('keeps a usable stateful reference when the default session behind it died', async () => {
+ /* Liveness is probed on the default route only, so a dead default session says
+ * nothing about the stateful deployment this turn runs on. Re-uploading there is
+ * redundant, and a failure would abort a tool call the existing file could serve. */
+ const defaultRef = {
+ kind: 'user' as const,
+ id: 'user1',
+ storage_session_id: 'sess-default',
+ file_id: 'remote-default',
+ };
+ const statefulRef = {
+ kind: 'user' as const,
+ id: 'user1',
+ storage_session_id: 'sess-stateful',
+ file_id: 'remote-stateful',
+ executionProfile: 'stateful' as const,
+ executionRouteKey: 'stateful:abc',
+ };
+ const bothRoutesFile = makeCodeFile({
+ file_id: 'both-routes-file',
+ metadata: {
+ codeEnvRef: defaultRef,
+ codeEnvRefs: { default: defaultRef, 'stateful:abc': statefulRef },
+ },
+ });
+ const checkSessionsAlive = jest.fn().mockResolvedValue(new Set<string>());
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([bothRoutesFile]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code]),
+ checkSessionsAlive,
+ codeRouteKey: 'stateful:abc',
+ });
+
+ expect(checkSessionsAlive).not.toHaveBeenCalled();
+ expect(result.provisionState?.codeEnvFiles ?? []).toEqual([]);
+ expect(bothRoutesFile.metadata?.codeEnvRefs?.['stateful:abc']).toEqual(statefulRef);
+ });
+
+ it('reprovisions a sandbox reference owned by another agent', async () => {
+ /* Code API derives its session key from the reference kind and id, so an agent-owned
+ * reference points at a session this caller cannot read. Reusing it adds the file to
+ * the second agent's code resources while the bytes live in the first agent's. */
+ const foreignRef = {
+ kind: 'agent' as const,
+ id: 'other-agent',
+ storage_session_id: 'sess-other',
+ file_id: 'remote-other',
+ };
+ const foreignScopedFile = makeCodeFile({
+ file_id: 'foreign-code-file',
+ metadata: { codeEnvRef: foreignRef, codeEnvRefs: { default: foreignRef } },
+ });
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([foreignScopedFile]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code]),
+ });
+
+ expect(result.provisionState?.codeEnvFiles.map((f) => f.file_id)).toEqual([
+ 'foreign-code-file',
+ ]);
+ });
+
+ it('keeps a sandbox reference already owned by the requesting user', async () => {
+ /* The converse: a message attachment is provisioned under the user, so a matching
+ * user reference is reusable and must not be uploaded again every turn. */
+ const ownRef = {
+ kind: 'user' as const,
+ id: 'user1',
+ storage_session_id: 'sess-own',
+ file_id: 'remote-own',
+ };
+ const ownScopedFile = makeCodeFile({
+ file_id: 'own-code-file',
+ metadata: { codeEnvRef: ownRef, codeEnvRefs: { default: ownRef } },
+ });
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([ownScopedFile]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code]),
+ });
+
+ expect(result.provisionState?.codeEnvFiles ?? []).toEqual([]);
+ });
+
+ it('queues a file whose only reference names another code route', async () => {
+ /* Priming resolves the active route alone, so a reference to a different deployment
+ * would leave the sandbox call without the attachment. */
+ const otherRouteRef = {
+ kind: 'user' as const,
+ id: 'user1',
+ storage_session_id: 'sess-a',
+ file_id: 'remote-a',
+ executionProfile: 'stateful' as const,
+ executionRouteKey: 'stateful:a',
+ };
+ const otherRouteFile = makeCodeFile({
+ file_id: 'other-route-file',
+ metadata: { codeEnvRef: otherRouteRef, codeEnvRefs: { 'stateful:a': otherRouteRef } },
+ });
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([otherRouteFile]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code]),
+ codeRouteKey: 'stateful:b',
+ });
+
+ expect(result.provisionState?.codeEnvFiles.map((f) => f.file_id)).toEqual([
+ 'other-route-file',
+ ]);
+ });
+
+ it('queues persistent context files on a turn with no request attachments', async () => {
+ process.env.CODEAPI_AUTH_PROVIDER = 'librechat-jwt';
+ const contextFile: TFile = {
+ user: 'user1',
+ file_id: 'context-file',
+ filename: 'handbook.pdf',
+ filepath: '/uploads/handbook.pdf',
+ object: 'file',
+ type: 'application/pdf',
+ bytes: 2048,
+ embedded: false,
+ usage: 0,
+ metadata: { destinationChosen: false },
+ };
+ mockGetFiles.mockResolvedValue([contextFile]);
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: { [EToolResources.context]: { file_ids: ['context-file'] } },
+ attachments: undefined,
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code, EToolResources.file_search]),
+ });
+
+ expect(result.provisionState?.codeEnvFiles.map((f) => f.file_id)).toContain('context-file');
+ expect(result.provisionState?.vectorDBFiles.map((f) => f.file_id)).toContain('context-file');
+ });
+
+ it('rebuilds an embedded agent context file as an agent-scoped file_id', async () => {
+ const embeddedContextFile: TFile = {
+ user: 'user1',
+ file_id: 'embedded-context',
+ filename: 'handbook.pdf',
+ filepath: '/uploads/handbook.pdf',
+ object: 'file',
+ type: 'application/pdf',
+ bytes: 2048,
+ embedded: true,
+ usage: 0,
+ context: FileContext.agents,
+ metadata: { embeddedEntities: ['agent1'] },
+ } as TFile;
+ mockGetFiles.mockResolvedValue([embeddedContextFile]);
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: { [EToolResources.context]: { file_ids: ['embedded-context'] } },
+ attachments: undefined,
+ requestFileSet,
+ agentId: 'agent1',
+ });
+
+ const searchResource = result.tool_resources?.[EToolResources.file_search];
+ expect(searchResource?.file_ids).toContain('embedded-context');
+ expect(searchResource?.files?.map((f) => f.file_id) ?? []).not.toContain('embedded-context');
+ });
+
+ it('re-embeds a foreign agent setup file attached as an ordinary message file', async () => {
+ /* Its vectors live under the other agent's entity, and the record-wide flag cannot
+ * say otherwise. Registering it for the user namespace on the strength of that flag
+ * leaves file_search querying a namespace holding none of its vectors, which returns
+ * nothing rather than failing. */
+ const foreignSetupFile = {
+ user: 'user1',
+ file_id: 'foreign-setup',
+ filename: 'handbook.pdf',
+ filepath: '/uploads/handbook.pdf',
+ object: 'file',
+ type: 'application/pdf',
+ bytes: 2048,
+ embedded: true,
+ usage: 0,
+ context: FileContext.agents,
+ metadata: { embeddedEntities: ['other-agent'] },
+ } as TFile;
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([foreignSetupFile]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.file_search]),
+ });
+
+ const searchResource = result.tool_resources?.[EToolResources.file_search];
+ expect(searchResource?.files?.map((f) => f.file_id) ?? []).not.toContain('foreign-setup');
+ expect(result.provisionState?.vectorDBFiles.map((f) => f.file_id)).toEqual(['foreign-setup']);
+ });
+
+ it('registers a file already embedded in the user namespace without re-queueing it', async () => {
+ /* The converse: once an unscoped upload records the user namespace, the file is
+ * reachable through .files and must not be embedded again every turn. */
+ const userNamespaceFile = {
+ user: 'user1',
+ file_id: 'user-embedded',
+ filename: 'handbook.pdf',
+ filepath: '/uploads/handbook.pdf',
+ object: 'file',
+ type: 'application/pdf',
+ bytes: 2048,
+ embedded: true,
+ usage: 0,
+ context: FileContext.agents,
+ metadata: { embeddedEntities: ['other-agent', 'user1'] },
+ } as TFile;
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([userNamespaceFile]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.file_search]),
+ });
+
+ const searchResource = result.tool_resources?.[EToolResources.file_search];
+ expect(searchResource?.files?.map((f) => f.file_id) ?? []).toContain('user-embedded');
+ expect(result.provisionState?.vectorDBFiles ?? []).toEqual([]);
+ });
+
+ it('re-embeds an agent context file recorded before namespaces were tracked', async () => {
+ /* Records predating per-namespace tracking cannot say which agent holds their
+ * vectors, so they are provisioned once for the agent that next uses them and carry
+ * the namespace afterwards. */
+ const legacyContextFile = {
+ user: 'user1',
+ file_id: 'legacy-context',
+ filename: 'handbook.pdf',
+ filepath: '/uploads/handbook.pdf',
+ object: 'file',
+ type: 'application/pdf',
+ bytes: 2048,
+ embedded: true,
+ usage: 0,
+ context: FileContext.agents,
+ } as TFile;
+ mockGetFiles.mockResolvedValue([legacyContextFile]);
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: { [EToolResources.context]: { file_ids: ['legacy-context'] } },
+ attachments: undefined,
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.file_search]),
+ });
+
+ expect(result.provisionState?.vectorDBFiles.map((f) => f.file_id)).toEqual([
+ 'legacy-context',
+ ]);
+ });
+
+ it('leaves a file alone whose destination came from the legacy chooser', async () => {
+ /* The endpoint deciding this turn need not be the one the file was uploaded under,
+ * so the request-level legacy check cannot answer for it. Its missing references
+ * are declines, not work to do. */
+ const chosenFile = {
+ user: 'user1',
+ file_id: 'legacy-chosen',
+ filename: 'notes.csv',
+ filepath: '/uploads/notes.csv',
+ object: 'file',
+ type: 'text/csv',
+ bytes: 512,
+ embedded: false,
+ usage: 0,
+ metadata: { destinationChosen: true },
+ } as TFile;
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([chosenFile]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code, EToolResources.file_search]),
+ });
+
+ expect(result.provisionState).toBeUndefined();
+ });
+
+ it('queues a unified file even when this turn runs under the legacy setting', async () => {
+ /* The marker says the upload was not a legacy choice, so its missing references are
+ * work to do. Deferring to the request's setting would let the tool run without it
+ * after an administrator flips the endpoint or a handoff crosses providers. */
+ const unifiedFile = {
+ user: 'user1',
+ file_id: 'unified-under-legacy',
+ filename: 'notes.csv',
+ filepath: '/uploads/notes.csv',
+ object: 'file',
+ type: 'text/csv',
+ bytes: 512,
+ embedded: false,
+ usage: 0,
+ metadata: { destinationChosen: false },
+ } as TFile;
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([unifiedFile]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.file_search]),
+ });
+
+ expect(result.provisionState?.vectorDBFiles.map((f) => f.file_id)).toEqual([
+ 'unified-under-legacy',
+ ]);
+ });
+
+ it('preserves chooser semantics for a record predating the marker', async () => {
+ /* Every markerless record predates unified routing. Missing destination evidence
+ * therefore means the chooser declined this consumer, regardless of today's mode. */
+ const legacyEraFile = {
+ user: 'user1',
+ file_id: 'pre-marker',
+ filename: 'notes.csv',
+ filepath: '/uploads/notes.csv',
+ object: 'file',
+ type: 'text/csv',
+ bytes: 512,
+ embedded: false,
+ usage: 0,
+ } as TFile;
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([legacyEraFile]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.file_search]),
+ });
+
+ expect(result.provisionState).toBeUndefined();
+ });
+
+ it('uses persisted membership as the destination for a pre-marker chooser file', async () => {
+ const legacySearchFile = {
+ user: 'user1',
+ file_id: 'pre-marker-search',
+ filename: 'notes.pdf',
+ filepath: '/uploads/notes.pdf',
+ object: 'file',
+ type: 'application/pdf',
+ bytes: 512,
+ embedded: false,
+ usage: 0,
+ source: FileSources.local,
+ } as TFile;
+ mockGetFiles.mockResolvedValue([legacySearchFile]);
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {
+ [EToolResources.file_search]: { file_ids: ['pre-marker-search'] },
+ },
+ attachments: undefined,
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code, EToolResources.file_search]),
+ });
+
+ expect(result.provisionState?.vectorDBFiles.map((file) => file.file_id)).toEqual([
+ 'pre-marker-search',
+ ]);
+ expect(result.provisionState?.codeEnvFiles).toEqual([]);
+ });
+
+ it('removes a screened-out file id from the runtime tool resources', async () => {
+ /* The tool primers read these ids directly and re-check only access, so a record
+ * the screen rejected still reaches the Code API unless its id goes with it. */
+ const rejected = {
+ user: 'user1',
+ file_id: 'rejected-code',
+ filename: 'bundle.zip',
+ filepath: '/uploads/bundle.zip',
+ object: 'file',
+ type: 'application/zip',
+ bytes: 2048,
+ embedded: false,
+ usage: 0,
+ context: FileContext.agents,
+ } as TFile;
+ mockGetFiles.mockResolvedValue([rejected]);
+ const tool_resources = {
+ [EToolResources.execute_code]: { file_ids: ['rejected-code'] },
+ };
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources,
+ attachments: undefined,
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code]),
+ screenPersistentFiles: () => [],
+ });
+
+ expect(result.tool_resources?.[EToolResources.execute_code]?.file_ids ?? []).not.toContain(
+ 'rejected-code',
+ );
+ });
+
+ it('keeps screened resources pruned when a later liveness probe fails', async () => {
+ const rejected = {
+ user: 'user1',
+ file_id: 'rejected-code',
+ filename: 'rejected.zip',
+ filepath: '/uploads/rejected.zip',
+ object: 'file',
+ type: 'application/zip',
+ bytes: 2048,
+ embedded: false,
+ usage: 0,
+ context: FileContext.agents,
+ } as TFile;
+ const allowed = {
+ ...rejected,
+ file_id: 'allowed-code',
+ filename: 'allowed.zip',
+ metadata: {
+ destinationChosen: false,
+ codeEnvRef: {
+ kind: 'agent',
+ id: 'agent1',
+ storage_session_id: 'session',
+ file_id: 'remote',
+ },
+ },
+ } as TFile;
+ mockGetFiles.mockResolvedValue([rejected, allowed]);
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {
+ [EToolResources.execute_code]: {
+ file_ids: ['rejected-code', 'allowed-code'],
+ },
+ },
+ attachments: undefined,
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code]),
+ screenPersistentFiles: (files) => files.filter((file) => file.file_id === 'allowed-code'),
+ checkSessionsAlive: jest.fn().mockRejectedValue(new Error('code api unavailable')),
+ });
+
+ expect(result.tool_resources?.[EToolResources.execute_code]?.file_ids).toEqual([
+ 'allowed-code',
+ ]);
+ });
+
+ it('queues a permanent code resource on a turn that attaches nothing', async () => {
+ /* A promoted code upload waits for the route the turn resolves, so it carries no
+ * sandbox reference. Without loading the agent's own code resources here, its first
+ * code call runs without the file it was uploaded for. */
+ const codeResourceFile = {
+ user: 'user1',
+ file_id: 'permanent-code',
+ filename: 'bundle.zip',
+ filepath: '/uploads/bundle.zip',
+ object: 'file',
+ type: 'application/zip',
+ bytes: 2048,
+ embedded: false,
+ usage: 0,
+ context: FileContext.agents,
+ metadata: { destinationChosen: false },
+ } as TFile;
+ mockGetFiles.mockResolvedValue([codeResourceFile]);
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {
+ [EToolResources.execute_code]: { file_ids: ['permanent-code'] },
+ },
+ attachments: undefined,
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code]),
+ });
+
+ expect(result.provisionState?.codeEnvFiles.map((f) => f.file_id)).toEqual(['permanent-code']);
+ });
+
+ it('reprovisions a chooser message attachment onto the route this turn uses', async () => {
+ /* A message attachment is never in the agent's resources, so membership cannot show
+ * which destination the chooser picked. The reference it already carries can: only
+ * a code upload creates one. */
+ const defaultRef = {
+ kind: 'user' as const,
+ id: 'user1',
+ storage_session_id: 'sess-default',
+ file_id: 'remote-default',
+ };
+ const chosenAttachment = makeCodeFile({
+ file_id: 'chooser-attachment',
+ metadata: {
+ destinationChosen: true,
+ codeEnvRef: defaultRef,
+ codeEnvRefs: { default: defaultRef },
+ },
+ });
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([chosenAttachment]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code, EToolResources.file_search]),
+ codeRouteKey: 'stateful:abc',
+ });
+
+ expect(result.provisionState?.codeEnvFiles.map((f) => f.file_id)).toEqual([
+ 'chooser-attachment',
+ ]);
+ /* And still only that destination: search was declined at upload. */
+ expect(result.provisionState?.vectorDBFiles ?? []).toEqual([]);
+ });
+
+ it('reprovisions the destination a chooser upload was actually filed under', async () => {
+ /* A duplicated agent inherits the file id but not its vectors, and the marker says
+ * the upload was a chooser one without saying which destination it chose. Blanket
+ * suppression leaves search querying a namespace holding nothing. */
+ const inherited = {
+ user: 'user1',
+ file_id: 'inherited-search',
+ filename: 'handbook.pdf',
+ filepath: '/uploads/handbook.pdf',
+ object: 'file',
+ type: 'application/pdf',
+ bytes: 2048,
+ embedded: true,
+ usage: 0,
+ context: FileContext.agents,
+ metadata: { destinationChosen: true, embeddedEntities: ['original-agent'] },
+ } as TFile;
+ mockGetFiles.mockResolvedValue([inherited]);
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {
+ [EToolResources.file_search]: { file_ids: ['inherited-search'] },
+ },
+ attachments: undefined,
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.file_search, EToolResources.execute_code]),
+ });
+
+ expect(result.provisionState?.vectorDBFiles.map((f) => f.file_id)).toEqual([
+ 'inherited-search',
+ ]);
+ /* And only that destination: code was declined at upload. */
+ expect(result.provisionState?.codeEnvFiles ?? []).toEqual([]);
+ });
+
+ it('keeps a type the sandbox cannot take out of the code queue', async () => {
+ /* Uploading it aborts the whole tool batch over a file that was only ever meant for
+ * provider delivery. */
+ const clip = {
+ user: 'user1',
+ file_id: 'clip-file',
+ filename: 'clip.mp4',
+ filepath: '/uploads/clip.mp4',
+ object: 'file',
+ type: 'video/mp4',
+ bytes: 4096,
+ embedded: false,
+ usage: 0,
+ } as TFile;
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([clip]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code]),
+ });
+
+ expect(result.provisionState?.codeEnvFiles ?? []).toEqual([]);
+ });
+
+ it('keeps a type the vector store cannot read out of the search queue', async () => {
+ /* Queueing it sends it to RAG on the next search call, and extraction refusing it
+ * aborts the tool over a file that was never a search candidate. */
+ const archive = {
+ user: 'user1',
+ file_id: 'archive-file',
+ filename: 'bundle.zip',
+ filepath: '/uploads/bundle.zip',
+ object: 'file',
+ type: 'application/zip',
+ bytes: 2048,
+ embedded: false,
+ usage: 0,
+ } as TFile;
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([archive]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.file_search]),
+ });
+
+ expect(result.provisionState?.vectorDBFiles ?? []).toEqual([]);
+ });
+
+ it('queues a deferred candidate for provisioning without delivering it again', async () => {
+ process.env.CODEAPI_AUTH_PROVIDER = 'librechat-jwt';
+ const deferred = makeCodeFile({ file_id: 'deferred-file' });
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code, EToolResources.file_search]),
+ provisionCandidates: [deferred],
+ });
+
+ expect(result.provisionState?.codeEnvFiles.map((f) => f.file_id)).toContain('deferred-file');
+ expect(result.provisionState?.vectorDBFiles.map((f) => f.file_id)).toContain('deferred-file');
+ /* The point of the separation: it must not become an attachment again. */
+ expect(result.attachments?.map((f) => f?.file_id) ?? []).not.toContain('deferred-file');
+ });
+
+ it('does not double-queue a candidate that is already an attachment', async () => {
+ process.env.CODEAPI_AUTH_PROVIDER = 'librechat-jwt';
+ const file = makeCodeFile({ file_id: 'shared-file' });
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([file]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code]),
+ provisionCandidates: [{ ...file }],
+ });
+
+ const queued = result.provisionState?.codeEnvFiles.filter((f) => f.file_id === 'shared-file');
+ expect(queued).toHaveLength(1);
+ });
+
+ it('never queues a text-source record, which has no streamable backing', async () => {
+ process.env.CODEAPI_AUTH_PROVIDER = 'librechat-jwt';
+ const textFile = makeCodeFile({ file_id: 'text-record', source: FileSources.text });
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: {},
+ attachments: Promise.resolve([textFile]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code, EToolResources.file_search]),
+ });
+
+ expect(result.provisionState).toBeUndefined();
+ expect(result.attachments?.map((f) => f?.file_id)).toContain('text-record');
+ });
+
+ it('grants agent scope only to the active agent own resource files', async () => {
+ /* A user who owns another agent's setup file can attach it here. Scoping it to this
+ * agent would provision it under an identity this agent's other users share, so the
+ * record's context is not enough: membership in this agent's resources decides. */
+ const foreignSetupFile = makeCodeFile({
+ file_id: 'foreign-agent-file',
+ context: FileContext.agents,
+ });
+ const ownSetupFile = makeCodeFile({ file_id: 'own-agent-file', context: FileContext.agents });
+ mockGetFiles.mockResolvedValue([ownSetupFile]);
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: { [EToolResources.context]: { file_ids: ['own-agent-file'] } },
+ attachments: Promise.resolve([foreignSetupFile]),
+ requestFileSet,
+ agentId: 'agent1',
+ enabledToolResources: new Set([EToolResources.execute_code]),
+ });
+
+ const scoped = result.provisionState?.agentScopedFileIds;
+ expect(scoped?.has('own-agent-file')).toBe(true);
+ expect(scoped?.has('foreign-agent-file')).toBe(false);
+ });
+
+ it('rebuilds an embedded code output under files, not agent file_ids', async () => {
+ const codeOutput: TFile = {
+ user: 'user1',
+ file_id: 'code-output',
+ filename: 'plot.csv',
+ filepath: '/uploads/plot.csv',
+ object: 'file',
+ type: 'text/csv',
+ bytes: 512,
+ embedded: true,
+ usage: 0,
+ context: FileContext.execute_code,
+ };
+ mockGetFiles.mockResolvedValue([codeOutput]);
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: { [EToolResources.context]: { file_ids: ['code-output'] } },
+ attachments: undefined,
+ requestFileSet,
+ agentId: 'agent1',
+ });
+
+ const searchResource = result.tool_resources?.[EToolResources.file_search];
+ expect(searchResource?.files?.map((f) => f.file_id)).toContain('code-output');
+ expect(searchResource?.file_ids ?? []).not.toContain('code-output');
+ });
+
+ it('rebuilds an embedded user attachment under files, not agent file_ids', async () => {
+ const embeddedAttachment: TFile = {
+ user: 'user1',
+ file_id: 'embedded-attachment',
+ filename: 'notes.pdf',
+ filepath: '/uploads/notes.pdf',
+ object: 'file',
+ type: 'application/pdf',
+ bytes: 1024,
+ embedded: true,
+ usage: 0,
+ context: FileContext.message_attachment,
+ };
+ mockGetFiles.mockResolvedValue([embeddedAttachment]);
+
+ const result = await primeResources({
+ req: mockReq,
+ appConfig: mockAppConfig,
+ getFiles: mockGetFiles,
+ filterFiles: mockFilterFiles,
+ tool_resources: { [EToolResources.context]: { file_ids: ['embedded-attachment'] } },
+ attachments: undefined,
+ requestFileSet,
+ agentId: 'agent1',
+ });
+
+ const searchResource = result.tool_resources?.[EToolResources.file_search];
+ expect(searchResource?.files?.map((f) => f.file_id)).toContain('embedded-attachment');
+ expect(searchResource?.file_ids ?? []).not.toContain('embedded-attachment');
+ });
+ });
});
diff --git a/packages/api/src/agents/resources.ts b/packages/api/src/agents/resources.ts
index e1260276c6..f23eeb1bb6 100644
--- a/packages/api/src/agents/resources.ts
+++ b/packages/api/src/agents/resources.ts
@@ -1,9 +1,23 @@
import { logger } from '@librechat/data-schemas';
-import { EModelEndpoint, EToolResources, AgentCapabilities } from 'librechat-data-provider';
-import type { AgentToolResources, TFile, AgentBaseResource } from 'librechat-data-provider';
+import {
+ EModelEndpoint,
+ EToolResources,
+ AgentCapabilities,
+ FileContext,
+ FileSources,
+ getCodeEnvRefs,
+ canToolResourceConsume,
+} from 'librechat-data-provider';
+import type {
+ AgentToolResources,
+ CodeEnvReferenceSet,
+ AgentBaseResource,
+ CodeEnvRef,
+ TFile,
+} from 'librechat-data-provider';
import type { IMongoFile, AppConfig, IUser } from '@librechat/data-schemas';
import type { FilterQuery, QueryOptions, ProjectionType } from 'mongoose';
-import type { Request as ServerRequest } from 'express';
+import type { ServerRequest } from '~/types';
import { TOOL_RESOURCE_KEYS } from './orphans';
@@ -24,6 +38,66 @@ const sanitizePersistedToolResources = (
return sanitized;
};
+/** Deferred DB update from provisioning (batched after all files are provisioned) */
+export type TFileUpdate = {
+ file_id: string;
+ metadata?: Record<string, unknown>;
+ embedded?: boolean;
+};
+
+/**
+ * Function type for provisioning a file to the code execution environment.
+ * @returns The codeEnvRef and a deferred DB update object
+ */
+export type TProvisionToCodeEnv = (params: {
+ req: ServerRequest;
+ file: TFile;
+ entity_id?: string;
+}) => Promise<{ referenceSet: CodeEnvReferenceSet; fileUpdate: TFileUpdate }>;
+
+/**
+ * Function type for provisioning a file to the vector DB for file_search.
+ * @returns Object with embedded status and a deferred DB update object
+ */
+export type TProvisionToVectorDB = (params: {
+ req: ServerRequest;
+ file: TFile;
+ entity_id?: string;
+ existingStream?: unknown;
+}) => Promise<{ embedded: boolean; fileUpdate: TFileUpdate | null }>;
+
+/**
+ * Function type for batch-checking code env file liveness.
+ * Groups files by session, makes one API call per session.
+ * @returns Set of file_ids that are confirmed alive
+ */
+export type TCheckSessionsAlive = (params: {
+ files: TFile[];
+ req?: ServerRequest;
+ apiKey?: string;
+ staleSafeWindowMs?: number;
+ baseURL?: string;
+ routeKey?: string;
+}) => Promise<Set<string>>;
+
+/** Loads CODE_API_KEY for a user. Call once per request. */
+export type TLoadCodeApiKey = (userId: string) => Promise<string>;
+
+/** State computed during primeResources for lazy provisioning at tool invocation time */
+export type ProvisionState = {
+ /** Files that need uploading to the code execution environment */
+ codeEnvFiles: TFile[];
+ /** Files that need embedding into the vector DB for file_search */
+ vectorDBFiles: TFile[];
+ /** Set of file_ids confirmed alive in code env (from staleness check) */
+ aliveFileIds: Set<string>;
+ /** The active agent's own resource files, which are the only ones provisioned under its
+ * shared identity. A record carrying an agent context is not enough: a user may attach
+ * another agent's setup file to this conversation, and provisioning it here would put
+ * it in a namespace this agent's other users can read. */
+ agentScopedFileIds: Set<string>;
+};
+
/**
* Function type for retrieving files from the database
* @param filter - MongoDB filter query for files
@@ -58,7 +132,7 @@ export type TFilterFilesByAgentAccess = (params: {
* @param params.tool_resources - The agent's tool resources object to update
* @param params.processedResourceFiles - Set tracking processed files per resource type
*/
-const addFileToResource = ({
+export const addFileToResource = ({
file,
resourceType,
tool_resources,
@@ -96,6 +170,90 @@ const addFileToResource = ({
}
};
+/** Contexts that positively identify an agent's own setup files. Everything else,
+ * including generated images, code outputs, and unknown contexts, belongs to the
+ * requesting user: provisioning those under a shared agent would copy one user's
+ * private file into a sandbox every other user of that agent can read. An allowlist
+ * fails safe, since an unrecognized context provisions per user rather than leaking. */
+
+/** Whether a file's existing vectors live under the agent's identity rather than the
+ * user's. This reads where content already is, which the record's context records.
+ * Where new provisioning may write is a separate question, answered by membership in
+ * the active agent's resources. */
+const AGENT_SCOPED_FILE_CONTEXTS = new Set<string>([FileContext.agents]);
+
+export const isAgentScopedFile = (file: Pick<TFile, 'context'>): boolean =>
+ AGENT_SCOPED_FILE_CONTEXTS.has(file.context as string);
+
+/**
+ * Whether this file's vectors exist in the namespace about to be queried, named by the
+ * agent whose namespace it is or by the user for the unscoped one.
+ *
+ * The record-wide `embedded` flag only says the file was embedded somewhere. An agent's
+ * setup file attached to a second agent is embedded under the first agent's entity, so
+ * trusting the flag registers it for a namespace that holds none of its vectors and the
+ * search returns nothing. Records embedded before namespaces were tracked carry no entity
+ * list and are re-embedded once per namespace, which repairs the record as it goes.
+ */
+const isEmbeddedForNamespace = (file: TFile, namespaceId?: string): boolean => {
+ if (!isAgentScopedFile(file)) {
+ return file.embedded === true;
+ }
+ return namespaceId != null && file.metadata?.embeddedEntities?.includes(namespaceId) === true;
+};
+
+/** The scope a code upload would be filed under this turn, mirroring what
+ * provisionToCodeEnv records: an agent's own resource file belongs to the agent, and
+ * everything else to the requesting user. */
+interface CodeEnvScope {
+ kind: 'agent' | 'user';
+ id?: string;
+}
+
+/**
+ * Whether this file already has a sandbox reference for the route the agent will execute
+ * on, under the identity this turn would use. A reference for another deployment does not
+ * make the file reachable here, and neither does one owned by another agent or user:
+ * `kind` and `id` are what Code API derives its session key from, so reusing a foreign
+ * reference points the tool at a session this caller cannot read. References this
+ * pipeline does not write, skill files being the case in point, are left to their owner.
+ */
+const hasCodeRefForRoute = (file: TFile, routeKey: string, scope: CodeEnvScope): boolean =>
+ getCodeEnvRefs(file.metadata).some(
+ ([key, ref]) =>
+ key === routeKey &&
+ (ref.kind !== 'agent' && ref.kind !== 'user'
+ ? true
+ : ref.kind === scope.kind && ref.id === scope.id),
+ );
+
+/** Mirrors the lazy provisioning writer: agent-scoped search files live in
+ * `file_ids`, which is the only shape fileSearch treats as agent-owned. */
+const addAgentScopedSearchFile = ({
+ file,
+ tool_resources,
+ processedResourceFiles,
+}: {
+ file: TFile;
+ tool_resources: AgentToolResources;
+ processedResourceFiles: Set<string>;
+}): void => {
+ if (!file.file_id) {
+ return;
+ }
+ const resourceKey = `${EToolResources.file_search}:${file.file_id}`;
+ if (processedResourceFiles.has(resourceKey)) {
+ return;
+ }
+ const resource = tool_resources[EToolResources.file_search] ?? {};
+ const fileIds = resource.file_ids ? [...resource.file_ids] : [];
+ if (!fileIds.includes(file.file_id)) {
+ fileIds.push(file.file_id);
+ }
+ tool_resources[EToolResources.file_search] = { ...resource, file_ids: fileIds };
+ processedResourceFiles.add(resourceKey);
+};
+
/**
* Categorizes a file into the appropriate tool resource based on its properties
* Files are categorized as:
@@ -113,11 +271,20 @@ const categorizeFileForToolResources = ({
tool_resources,
requestFileSet,
processedResourceFiles,
+ agentScoped = false,
+ agentId,
+ userId,
}: {
file: TFile;
tool_resources: AgentToolResources;
requestFileSet: Set<string>;
processedResourceFiles: Set<string>;
+ /** Whether this file's vectors were embedded under the agent's entity_id. */
+ agentScoped?: boolean;
+ /** The agent whose vector namespace this turn will search, when one is scoped. */
+ agentId?: string;
+ /** Owner of the unscoped namespace, which is where anything not agent-scoped lands. */
+ userId?: string;
}): void => {
if (file.metadata?.codeEnvRef || file.metadata?.codeEnvRefs) {
addFileToResource({
@@ -126,17 +293,25 @@ const categorizeFileForToolResources = ({
tool_resources,
processedResourceFiles,
});
- return;
}
- if (file.embedded === true) {
- addFileToResource({
- file,
- resourceType: EToolResources.file_search,
- tool_resources,
- processedResourceFiles,
- });
- return;
+ /* Judged per namespace, not by the record-wide flag: registering a file this agent's
+ * namespace never received would make search query for vectors that are not there. */
+ if (isEmbeddedForNamespace(file, agentScoped ? agentId : userId)) {
+ /** Agent-scoped files are embedded under `entity_id: agentId`, so they must be
+ * reconstructed as `file_ids`: fileSearch's primeFiles only marks those
+ * `fromAgent` and only `fromAgent` queries carry the entity_id that can find
+ * their vectors. Rebuilding them under `.files` makes them unsearchable. */
+ if (agentScoped) {
+ addAgentScopedSearchFile({ file, tool_resources, processedResourceFiles });
+ } else {
+ addFileToResource({
+ file,
+ resourceType: EToolResources.file_search,
+ tool_resources,
+ processedResourceFiles,
+ });
+ }
}
if (
@@ -173,6 +348,275 @@ const categorizeFileForToolResources = ({
* @param params.agentId - Agent ID used for access control filtering
* @returns Promise resolving to processed attachments and updated tool resources
*/
+/** Code env pointers are deployment-local, so a ref is probed against the Code API that
+ * issued it. The probe therefore runs on the route this turn executes on, and only refs
+ * belonging to that route take part or may be cleared as stale. */
+const codeEnvRouteKey = (ref: CodeEnvRef): string =>
+ ref.executionRouteKey ?? ref.executionProfile ?? 'default';
+
+/** The reference a given route issued, across both the per-route map and the legacy
+ * single pointer. */
+const codeEnvRefForRoute = (file: TFile, routeKey: string): CodeEnvRef | undefined =>
+ getCodeEnvRefs(file.metadata).find(([key]) => key === routeKey)?.[1];
+
+/** Attachments plus any deferred candidates not already present, deduped by file_id.
+ * Only the provisioning computation sees this: the delivery list stays untouched. */
+const withDeferredCandidates = (
+ attachments: Array<TFile>,
+ candidates?: Array<TFile>,
+): Array<TFile> => {
+ if (!candidates || candidates.length === 0) {
+ return attachments;
+ }
+ const seen = new Set(attachments.map((file) => file.file_id));
+ const merged = [...attachments];
+ for (const candidate of candidates) {
+ if (candidate?.file_id && !seen.has(candidate.file_id)) {
+ seen.add(candidate.file_id);
+ merged.push(candidate);
+ }
+ }
+ return merged;
+};
+
+/**
+ * Lazy provisioning: instead of provisioning files now, compute which files need
+ * provisioning. Actual provisioning happens at tool invocation time via the
+ * ON_TOOL_EXECUTE handler. Runs for persistent agent context files too, so a turn
+ * that carries no new attachment still queues them.
+ */
+const computeProvisionState = async ({
+ req,
+ attachments,
+ resourcePrincipal,
+ enabledToolResources,
+ tool_resources,
+ processedResourceFiles,
+ checkSessionsAlive,
+ loadCodeApiKey,
+ agentId,
+ codeRouteKey,
+ codeBaseUrl,
+ agentScopedFileIds,
+ persistedResourceMembership,
+ staleSafeWindowMs,
+}: {
+ req?: ServerRequest;
+ attachments: Array<TFile>;
+ agentId?: string;
+ codeRouteKey?: string;
+ /** Base URL of the deployment this turn runs on, used to probe its own refs. */
+ codeBaseUrl?: string;
+ agentScopedFileIds?: ReadonlySet<string>;
+ resourcePrincipal?: Pick<IUser, 'id' | 'role'>;
+ enabledToolResources?: Set<EToolResources>;
+ tool_resources: AgentToolResources;
+ processedResourceFiles: Set<string>;
+ checkSessionsAlive?: TCheckSessionsAlive;
+ loadCodeApiKey?: TLoadCodeApiKey;
+ /** Which resource each persisted file is filed under, before categorization mutates it. */
+ persistedResourceMembership?: ReadonlyMap<EToolResources, ReadonlySet<string>>;
+ staleSafeWindowMs?: number;
+}): Promise<ProvisionState | undefined> => {
+ if (!enabledToolResources || enabledToolResources.size === 0 || attachments.length === 0) {
+ return undefined;
+ }
+
+ /* The legacy chooser makes the destination an explicit user decision, so a file it
+ * uploaded carries no reference for the destinations the user declined, and queueing on
+ * a missing reference would read those declines as work to do. The decision belongs to
+ * the file, not to this request: the endpoint deciding this turn need not be the one it
+ * was uploaded under. Records predating the marker were written by the chooser flow,
+ * so their existing resource membership/reference is the only durable destination evidence. */
+ const cameFromChooser = (file: TFile): boolean => {
+ const choice = file.metadata?.destinationChosen;
+ return choice == null ? true : choice;
+ };
+
+ /** A chooser upload may still be provisioned for the destination it was filed under,
+ * which is how an inherited search file gets vectors in a duplicated agent's namespace.
+ * The destinations it carries no reference for were declined, not deferred. */
+ /** What the record itself shows about where it was sent. A message attachment is never
+ * in the agent's resources, so a reference or an embedding is the only evidence that
+ * the chooser picked that destination, and it is proof: nothing else creates one. */
+ const carriesEvidenceFor = (file: TFile, resourceType: EToolResources): boolean => {
+ if (resourceType === EToolResources.execute_code) {
+ return getCodeEnvRefs(file.metadata).length > 0;
+ }
+ return file.embedded === true || (file.metadata?.embeddedEntities?.length ?? 0) > 0;
+ };
+
+ const allowsResource = (file: TFile, resourceType: EToolResources): boolean => {
+ if (!cameFromChooser(file)) {
+ return true;
+ }
+ const isPersistedResource =
+ file.file_id != null &&
+ persistedResourceMembership?.get(resourceType)?.has(file.file_id) === true;
+ return isPersistedResource || carriesEvidenceFor(file, resourceType);
+ };
+ const provisionable = attachments.filter(
+ (file) =>
+ file != null &&
+ (allowsResource(file, EToolResources.execute_code) ||
+ allowsResource(file, EToolResources.file_search)),
+ );
+ if (provisionable.length === 0) {
+ return undefined;
+ }
+
+ const needsCodeEnv = enabledToolResources.has(EToolResources.execute_code);
+ const needsVectorDB = enabledToolResources.has(EToolResources.file_search);
+ if (!needsCodeEnv && !needsVectorDB) {
+ return undefined;
+ }
+
+ const activeCodeRouteKey = codeRouteKey ?? 'default';
+
+ /** Batch staleness check: identify which code env files are still alive. Only files
+ * that already carry a ref for this turn's route can be probed, so that set is
+ * computed first: a turn whose attachments are all freshly uploaded has nothing to
+ * probe and must not pay for a credential lookup that cannot change the outcome. */
+ /* A non-default route can only be probed when its own base URL is known; the default
+ * Code API is resolved by the probe itself when none is passed. */
+ const canProbeRoute = activeCodeRouteKey === 'default' || codeBaseUrl != null;
+ const filesWithIdentifiers =
+ needsCodeEnv && checkSessionsAlive && canProbeRoute
+ ? provisionable.filter((f) => f?.file_id && codeEnvRefForRoute(f, activeCodeRouteKey))
+ : [];
+
+ /** Code API auth is optional: deployments may use a legacy key, JWT bearer minting,
+ * or no auth at all, and the upload path handles each. Credentials therefore gate
+ * only the liveness probe, never whether files are queued for provisioning. */
+ let codeApiKey: string | undefined;
+ if (filesWithIdentifiers.length > 0 && loadCodeApiKey && resourcePrincipal?.id) {
+ try {
+ codeApiKey = await loadCodeApiKey(resourcePrincipal.id);
+ } catch (error) {
+ logger.error('[primeResources] Failed to load CODE_API_KEY', error);
+ }
+ }
+
+ /** Requires credentials the callback can actually send: a legacy key, or a req to
+ * mint JWT bearer auth from. Without either, skip the check so an unauthorized 401
+ * cannot mark live sandbox files as expired. */
+ let aliveFileIds: Set<string> | undefined;
+ if (filesWithIdentifiers.length > 0 && checkSessionsAlive && (codeApiKey != null || req)) {
+ aliveFileIds = await checkSessionsAlive({
+ files: filesWithIdentifiers as TFile[],
+ req,
+ apiKey: codeApiKey,
+ baseURL: codeBaseUrl,
+ routeKey: activeCodeRouteKey,
+ staleSafeWindowMs,
+ });
+ }
+
+ const scopedIds = agentScopedFileIds ?? new Set<string>();
+ const codeEnvFiles: TFile[] = [];
+ const vectorDBFiles: TFile[] = [];
+
+ for (const file of provisionable) {
+ if (!file?.file_id) {
+ continue;
+ }
+
+ /* Mirrors entityIdForFile in the provisioning callback: membership in the agent's own
+ * resources decides both the vector namespace and the sandbox identity, so the queue
+ * asks about the scope the upload will actually write under. */
+ const isAgentScoped = scopedIds.has(file.file_id);
+ const namespaceId = isAgentScoped ? agentId : resourcePrincipal?.id;
+ const codeScope: CodeEnvScope = isAgentScoped
+ ? { kind: 'agent', id: agentId }
+ : { kind: 'user', id: resourcePrincipal?.id };
+
+ /** Text-source records keep their content in the database with no backing object
+ * to stream, so provisioning them would fail and, for code, abort the turn.
+ * Provisioning them from their stored text is tracked as follow-up work. */
+ if (file.source === FileSources.text) {
+ continue;
+ }
+
+ /* Same question the search branch asks, and the same consequence: uploading a type
+ * the sandbox refuses aborts the tool batch over a file meant for the model. */
+ if (
+ needsCodeEnv &&
+ allowsResource(file, EToolResources.execute_code) &&
+ canToolResourceConsume(EToolResources.execute_code, file.type ?? '')
+ ) {
+ const legacyRef = file.metadata?.codeEnvRef;
+ /* Liveness answers only for the route it was probed on, so a ref belonging to
+ * another deployment is never cleared on the strength of this turn's answer. */
+ const isStale =
+ codeEnvRefForRoute(file, activeCodeRouteKey) != null &&
+ aliveFileIds != null &&
+ !aliveFileIds.has(file.file_id);
+
+ /** Staleness must be repaired even for files that pre-categorization already
+ * added to execute_code resources, so the check runs before the processed
+ * guard. Clear both the legacy ref and its route entry, else getCodeEnvRefs
+ * keeps resolving the dead session over the re-provisioned one. */
+ if (isStale) {
+ logger.info(
+ `[primeResources] Code env file expired for "${file.filename}" (${file.file_id}), will re-provision on tool use`,
+ );
+ const remainingRefs = Object.fromEntries(
+ Object.entries(file.metadata?.codeEnvRefs ?? {}).filter(
+ ([routeKey]) => routeKey !== activeCodeRouteKey,
+ ),
+ );
+ /* The legacy pointer only answers for the route it names, so a ref for another
+ * deployment survives a stale answer this turn could not have been about. */
+ const legacyBelongsToRoute =
+ legacyRef != null && codeEnvRouteKey(legacyRef) === activeCodeRouteKey;
+ file.metadata = {
+ ...file.metadata,
+ codeEnvRef: legacyBelongsToRoute ? undefined : legacyRef,
+ codeEnvRefs: Object.keys(remainingRefs).length > 0 ? remainingRefs : undefined,
+ };
+ codeEnvFiles.push(file);
+ } else if (!hasCodeRefForRoute(file, activeCodeRouteKey, codeScope)) {
+ /* Judged by the active route rather than by any reference at all: a file
+ * provisioned to another deployment is not reachable from this one, and priming
+ * resolves only this route, so it would be omitted from the sandbox call. The
+ * pre-categorization pass marks such a file processed on the strength of the
+ * reference it does have, so the processed flag cannot gate this. */
+ codeEnvFiles.push(file);
+ } else if (!processedResourceFiles.has(`${EToolResources.execute_code}:${file.file_id}`)) {
+ addFileToResource({
+ file,
+ resourceType: EToolResources.execute_code,
+ tool_resources,
+ processedResourceFiles,
+ });
+ }
+ }
+
+ /* The same predicate the upload path files a consumer with. Queueing a type the
+ * vector store cannot read sends it to RAG on the next search call and aborts the
+ * tool when extraction refuses it. */
+ if (
+ needsVectorDB &&
+ allowsResource(file, EToolResources.file_search) &&
+ canToolResourceConsume(EToolResources.file_search, file.type ?? '') &&
+ !isEmbeddedForNamespace(file, namespaceId) &&
+ !processedResourceFiles.has(`${EToolResources.file_search}:${file.file_id}`)
+ ) {
+ vectorDBFiles.push(file);
+ }
+ }
+
+ if (codeEnvFiles.length === 0 && vectorDBFiles.length === 0) {
+ return undefined;
+ }
+ return {
+ codeEnvFiles,
+ vectorDBFiles,
+ aliveFileIds: aliveFileIds ?? new Set(),
+ agentScopedFileIds: new Set(scopedIds),
+ };
+};
+
export const primeResources = async ({
req,
principal,
@@ -183,8 +627,15 @@ export const primeResources = async ({
attachments: _attachments,
tool_resources: _tool_resources,
agentId,
+ enabledToolResources,
+ checkSessionsAlive,
+ loadCodeApiKey,
+ provisionCandidates,
+ screenPersistentFiles,
+ codeRouteKey,
+ codeBaseUrl,
}: {
- req?: ServerRequest & { user?: IUser };
+ req?: ServerRequest;
principal?: Pick<IUser, 'id' | 'role'>;
appConfig?: AppConfig;
requestFileSet: Set<string>;
@@ -193,22 +644,48 @@ export const primeResources = async ({
getFiles: TGetFiles;
filterFiles?: TFilterFilesByAgentAccess;
agentId?: string;
+ /** Set of tool resource types the agent has enabled (e.g., execute_code, file_search) */
+ enabledToolResources?: Set<EToolResources>;
+ /** Optional callback to batch-check code env file liveness by session */
+ checkSessionsAlive?: TCheckSessionsAlive;
+ /** Optional callback to load CODE_API_KEY once per request */
+ loadCodeApiKey?: TLoadCodeApiKey;
+ /** Attachments from earlier turns that were never provisioned. Considered for
+ * provisioning only and never returned as attachments: re-delivering an earlier
+ * upload to the model on every later turn is not the intent. */
+ provisionCandidates?: Array<TFile>;
+ /** True when this endpoint still shows the explicit upload-destination chooser. */
+ /** Applies the caller's endpoint and content policies. Persistent agent files are read
+ * here rather than by the caller, so the caller has no chance to screen them itself
+ * and a configuration or policy change since they were attached would otherwise let
+ * their bytes reach the model, the Code API or RAG. */
+ screenPersistentFiles?: (files: Array<TFile>) => Array<TFile>;
+ /** The code deployment this turn will execute on, which decides whether an existing
+ * sandbox reference is usable here. */
+ codeRouteKey?: string;
+ /** Base URL of that deployment. Refs are deployment-local, so the liveness probe runs
+ * against the Code API that issued them rather than the default one. */
+ codeBaseUrl?: string;
}): Promise<{
attachments: Array<TFile | undefined> | undefined;
requestAttachments: Array<TFile | undefined> | undefined;
agentContextAttachments: Array<TFile | undefined> | undefined;
tool_resources: AgentToolResources | undefined;
+ provisionState?: ProvisionState;
+ warnings: string[];
}> => {
const resourcePrincipal = principal ?? req?.user;
const requestAttachments: Array<TFile> = [];
const agentContextAttachments: Array<TFile> = [];
const persistedToolResources = sanitizePersistedToolResources(_tool_resources);
+ let safeToolResources = persistedToolResources;
try {
/**
* Array to collect all unique files that will be returned as attachments
* Files are added from OCR results and attachment promises, with duplicates prevented
*/
const attachments: Array<TFile> = [];
+ const warnings: string[] = [];
/**
* Set of file IDs already added to the attachments array
* Used to prevent duplicate files from being added multiple times
@@ -226,6 +703,7 @@ export const primeResources = async ({
* Create a shallow copy first to avoid mutating the original
*/
const tool_resources: AgentToolResources = { ...persistedToolResources };
+ safeToolResources = tool_resources;
// Deep copy each resource to avoid mutating nested objects/arrays
for (const [resourceType, resource] of Object.entries(tool_resources)) {
@@ -276,6 +754,38 @@ export const primeResources = async ({
persistedResourceFileIds.add(fileId);
}
+ /** The agent's own tool resource files are provisioning candidates in their own right.
+ * A promoted code upload waits for the route the turn resolves, and an inherited
+ * search file may hold no vectors in this agent's namespace, so both have to be
+ * loaded even on a turn that attaches nothing. They are candidates only: delivery
+ * still follows the context ids below. */
+ const toolResourceFileIds = new Set<string>();
+ /** Which resource each persisted file is filed under, read before categorization
+ * mutates tool_resources. A legacy upload's selected destination is the only one it
+ * may be provisioned for; the rest were declined. */
+ const persistedResourceMembership = new Map<EToolResources, Set<string>>();
+ const provisionableResources = [
+ {
+ type: EToolResources.execute_code,
+ ids: tool_resources[EToolResources.execute_code]?.file_ids,
+ },
+ {
+ type: EToolResources.file_search,
+ ids: tool_resources[EToolResources.file_search]?.file_ids,
+ },
+ ];
+ for (const { type, ids } of provisionableResources) {
+ persistedResourceMembership.set(type, new Set(ids ?? []));
+ if (enabledToolResources?.has(type) !== true) {
+ continue;
+ }
+ for (const fileId of ids ?? []) {
+ toolResourceFileIds.add(fileId);
+ persistedResourceFileIds.add(fileId);
+ }
+ }
+ const resourceProvisionCandidates: Array<TFile> = [];
+
if (shouldLoadContext) {
delete tool_resources[EToolResources.context];
}
@@ -298,6 +808,35 @@ export const primeResources = async ({
agentId,
});
}
+
+ if (screenPersistentFiles) {
+ const admitted = screenPersistentFiles(persistedResourceFiles);
+ /* The tool primers read tool_resources ids directly and re-check only access, so
+ * a record dropped here still reaches the Code API or RAG unless its id goes with
+ * it. Screening the hydrated list alone screens nothing. */
+ if (admitted.length !== persistedResourceFiles.length) {
+ const admittedIds = new Set(
+ admitted.map((file) => file.file_id).filter((id): id is string => id != null),
+ );
+ const rejectedIds = persistedResourceFiles
+ .map((file) => file.file_id)
+ .filter((id): id is string => id != null && !admittedIds.has(id));
+ const runtimeResources = [
+ tool_resources[EToolResources.execute_code],
+ tool_resources[EToolResources.file_search],
+ ];
+ for (const resource of runtimeResources) {
+ if (resource?.file_ids == null) {
+ continue;
+ }
+ resource.file_ids = resource.file_ids.filter((id: string) => !rejectedIds.includes(id));
+ }
+ for (const id of rejectedIds) {
+ toolResourceFileIds.delete(id);
+ }
+ }
+ persistedResourceFiles = admitted;
+ }
}
for (const file of persistedResourceFiles) {
@@ -306,21 +845,25 @@ export const primeResources = async ({
}
if (contextFileIds.has(file.file_id)) {
- // Clear from attachmentFileIds if it was pre-added
attachmentFileIds.delete(file.file_id);
- // Add to attachments
- attachments.push(file);
- agentContextAttachments.push(file);
- attachmentFileIds.add(file.file_id);
-
- // Categorize for tool resources
categorizeFileForToolResources({
file,
tool_resources,
requestFileSet,
processedResourceFiles,
+ agentScoped: agentId != null && isAgentScopedFile(file),
+ agentId,
+ userId: resourcePrincipal?.id,
});
+
+ attachments.push(file);
+ agentContextAttachments.push(file);
+ attachmentFileIds.add(file.file_id);
+ }
+
+ if (toolResourceFileIds.has(file.file_id)) {
+ resourceProvisionCandidates.push(file);
}
if (imageEditFileIdSet.has(file.file_id)) {
@@ -335,12 +878,35 @@ export const primeResources = async ({
}
if (!_attachments) {
+ /** Persistent agent context files are already collected above; queue them for
+ * provisioning here too, so a turn with no new attachment still primes them. */
+ const contextProvisionState = await computeProvisionState({
+ req,
+ attachments: withDeferredCandidates(attachments, [
+ ...(provisionCandidates ?? []),
+ ...resourceProvisionCandidates,
+ ]),
+ resourcePrincipal,
+ enabledToolResources,
+ tool_resources,
+ processedResourceFiles,
+ checkSessionsAlive,
+ loadCodeApiKey,
+ agentId,
+ codeRouteKey,
+ codeBaseUrl,
+ agentScopedFileIds: persistedResourceFileIds,
+ persistedResourceMembership,
+ staleSafeWindowMs: appConfig?.fileConfig?.codeEnvLivenessSafeWindowMs,
+ });
return {
attachments: attachments.length > 0 ? attachments : undefined,
requestAttachments: undefined,
agentContextAttachments:
agentContextAttachments.length > 0 ? agentContextAttachments : undefined,
tool_resources,
+ provisionState: contextProvisionState,
+ warnings,
};
}
@@ -357,6 +923,7 @@ export const primeResources = async ({
tool_resources,
requestFileSet,
processedResourceFiles,
+ userId: resourcePrincipal?.id,
});
if (file.file_id && attachmentFileIds.has(file.file_id)) {
@@ -377,12 +944,34 @@ export const primeResources = async ({
}
}
+ const provisionState = await computeProvisionState({
+ req,
+ attachments: withDeferredCandidates(attachments, [
+ ...(provisionCandidates ?? []),
+ ...resourceProvisionCandidates,
+ ]),
+ resourcePrincipal,
+ enabledToolResources,
+ tool_resources,
+ processedResourceFiles,
+ checkSessionsAlive,
+ loadCodeApiKey,
+ agentId,
+ codeRouteKey,
+ codeBaseUrl,
+ agentScopedFileIds: persistedResourceFileIds,
+ persistedResourceMembership,
+ staleSafeWindowMs: appConfig?.fileConfig?.codeEnvLivenessSafeWindowMs,
+ });
+
return {
attachments: attachments.length > 0 ? attachments : [],
requestAttachments,
agentContextAttachments:
agentContextAttachments.length > 0 ? agentContextAttachments : undefined,
tool_resources,
+ provisionState,
+ warnings,
};
} catch (error) {
logger.error('Error priming resources', error);
@@ -405,7 +994,9 @@ export const primeResources = async ({
requestAttachments: safeAttachments,
agentContextAttachments:
agentContextAttachments.length > 0 ? agentContextAttachments : undefined,
- tool_resources: persistedToolResources,
+ tool_resources: safeToolResources,
+ provisionState: undefined,
+ warnings: [],
};
}
};
diff --git a/packages/api/src/agents/tools.spec.ts b/packages/api/src/agents/tools.spec.ts
index 0ebdabfc17..4ba738e040 100644
--- a/packages/api/src/agents/tools.spec.ts
+++ b/packages/api/src/agents/tools.spec.ts
@@ -6,6 +6,7 @@
*/
jest.mock('@librechat/agents', () => ({
CODE_EXECUTION_TOOLS: new Set(['execute_code', 'bash_tool']),
+ Constants: { READ_FILE: 'read_file', WRITE_FILE: 'write_file' },
ReadFileToolDefinition: {
name: 'read_file',
description: 'read skill files using {skillName}/{filePath} and SKILL.md',
diff --git a/packages/api/src/agents/tools.ts b/packages/api/src/agents/tools.ts
index ec3392fe32..e02879e83c 100644
--- a/packages/api/src/agents/tools.ts
+++ b/packages/api/src/agents/tools.ts
@@ -5,6 +5,7 @@ import {
splitMCPToolKey,
} from 'librechat-data-provider';
import {
+ Constants as AgentConstants,
CODE_EXECUTION_TOOLS,
BashExecutionToolDefinition,
ReadFileToolDefinition,
@@ -31,6 +32,23 @@ export const FILE_AUTHORING_TOOL_NAMES: ReadonlySet<string> = new Set([
EDIT_FILE_TOOL_NAME,
]);
+/**
+ * Every tool that reads or writes the code environment. Eligibility and provisioning both
+ * consult this: a turn starting with any of them needs its files in the sandbox already,
+ * and an agent that has any of them wants code-file provisioning built even when it never
+ * names the `execute_code` marker itself.
+ */
+export const CODE_FILE_TOOL_NAMES: ReadonlySet<string> = new Set([
+ ...CODE_EXECUTION_TOOLS,
+ ...FILE_AUTHORING_TOOL_NAMES,
+ AgentConstants.READ_FILE,
+ AgentConstants.WRITE_FILE,
+]);
+
+export function isCodeFileToolName(name: string): boolean {
+ return CODE_FILE_TOOL_NAMES.has(name);
+}
+
export function isCodeSessionToolName(
name: string,
hostFileAuthoringToolNames?: ReadonlySet<string>,
diff --git a/packages/api/src/files/agents/auth.spec.ts b/packages/api/src/files/agents/auth.spec.ts
new file mode 100644
index 0000000000..df5e06c90b
--- /dev/null
+++ b/packages/api/src/files/agents/auth.spec.ts
@@ -0,0 +1,221 @@
+import { SystemRoles, PermissionBits } from 'librechat-data-provider';
+import { checkAgentUploadAuth, verifyAgentUploadPermission } from './auth';
+
+jest.mock('@librechat/data-schemas', () => ({
+ logger: { warn: jest.fn(), error: jest.fn() },
+}));
+
+describe('checkAgentUploadAuth', () => {
+ const agent = { _id: 'agent-object-id', author: { toString: () => 'owner-id' } };
+ const getAgent = jest.fn().mockResolvedValue(agent);
+ const checkPermission = jest.fn().mockResolvedValue(false);
+
+ beforeEach(() => {
+ jest.clearAllMocks();
+ getAgent.mockResolvedValue(agent);
+ checkPermission.mockResolvedValue(false);
+ });
+
+ it('denies a permanent upload with no tool resource from a user without edit permission', async () => {
+ const result = await checkAgentUploadAuth(
+ { userId: 'attacker-id', userRole: SystemRoles.USER, agentId: 'agent_victim01' },
+ { getAgent, checkPermission },
+ );
+
+ expect(result.allowed).toBe(false);
+ expect(checkPermission).toHaveBeenCalled();
+ });
+
+ it('allows a permanent upload with no tool resource when the user may edit the agent', async () => {
+ checkPermission.mockResolvedValue(true);
+
+ const result = await checkAgentUploadAuth(
+ { userId: 'editor-id', userRole: SystemRoles.USER, agentId: 'agent_shared01' },
+ { getAgent, checkPermission },
+ );
+
+ expect(result.allowed).toBe(true);
+ });
+
+ it('reports a missing agent to an admin rather than proceeding', async () => {
+ getAgent.mockResolvedValue(null);
+
+ const result = await checkAgentUploadAuth(
+ { userId: 'admin-id', userRole: SystemRoles.ADMIN, agentId: 'missing-agent' },
+ { getAgent, checkPermission },
+ );
+
+ expect(result).toMatchObject({ allowed: false, status: 404 });
+ });
+
+ it('allows the agent author without consulting permissions', async () => {
+ const result = await checkAgentUploadAuth(
+ { userId: 'owner-id', userRole: SystemRoles.USER, agentId: 'agent_own0001' },
+ { getAgent, checkPermission },
+ );
+
+ expect(result.allowed).toBe(true);
+ expect(checkPermission).not.toHaveBeenCalled();
+ });
+
+ it('asks only for view access on a message attachment', async () => {
+ /* The attachment belongs to the conversation rather than the agent, so edit access is
+ * too much. Skipping the check entirely was too little: the upload is validated under
+ * the named agent's provider, so its rejections describe a record the caller may not
+ * be allowed to see. */
+ checkPermission.mockResolvedValue(true);
+
+ const result = await checkAgentUploadAuth(
+ {
+ userId: 'viewer-id',
+ userRole: SystemRoles.USER,
+ agentId: 'agent_shared01',
+ messageFile: 'true',
+ },
+ { getAgent, checkPermission },
+ );
+
+ expect(result.allowed).toBe(true);
+ expect(checkPermission).toHaveBeenCalledWith(
+ expect.objectContaining({ requiredPermission: PermissionBits.VIEW }),
+ );
+ });
+
+ it('denies a message attachment naming an agent the caller cannot view', async () => {
+ const result = await checkAgentUploadAuth(
+ {
+ userId: 'attacker-id',
+ userRole: SystemRoles.USER,
+ agentId: 'agent_victim01',
+ messageFile: 'true',
+ },
+ { getAgent, checkPermission },
+ );
+
+ expect(result.allowed).toBe(false);
+ });
+
+ it('allows a message attachment in an ephemeral conversation', async () => {
+ /* An ephemeral id names no stored agent, so there is nothing to authorize against and
+ * nothing for the provider resolution to read. Requiring view access refuses every
+ * attachment in those conversations. */
+ const result = await checkAgentUploadAuth(
+ {
+ userId: 'any-user',
+ userRole: SystemRoles.USER,
+ agentId: 'ephemeral-convo-1',
+ messageFile: 'true',
+ },
+ { getAgent, checkPermission },
+ );
+
+ expect(result.allowed).toBe(true);
+ expect(getAgent).not.toHaveBeenCalled();
+ });
+
+ it('leaves an upload naming no agent alone', async () => {
+ const result = await checkAgentUploadAuth(
+ { userId: 'any-user', userRole: SystemRoles.USER, messageFile: 'true' },
+ { getAgent, checkPermission },
+ );
+
+ expect(result.allowed).toBe(true);
+ expect(getAgent).not.toHaveBeenCalled();
+ });
+
+ it('still denies when a tool resource is supplied without permission', async () => {
+ const result = await checkAgentUploadAuth(
+ {
+ userId: 'attacker-id',
+ userRole: SystemRoles.USER,
+ agentId: 'agent_victim01',
+ toolResource: 'context',
+ },
+ { getAgent, checkPermission },
+ );
+
+ expect(result.allowed).toBe(false);
+ });
+});
+
+describe('verifyAgentUploadPermission', () => {
+ const agent = { _id: 'agent-object-id', author: { toString: () => 'owner-id' } };
+ const getAgent = jest.fn();
+ const checkPermission = jest.fn();
+ const makeRes = () => {
+ const status = jest.fn();
+ const res = { status, json: jest.fn() };
+ status.mockReturnValue(res);
+ return res as unknown as Parameters<typeof verifyAgentUploadPermission>[0]['res'];
+ };
+ const req = { user: { id: 'manager-id', role: SystemRoles.USER } } as unknown as Parameters<
+ typeof verifyAgentUploadPermission
+ >[0]['req'];
+
+ beforeEach(() => {
+ jest.clearAllMocks();
+ getAgent.mockResolvedValue(agent);
+ checkPermission.mockResolvedValue(false);
+ });
+
+ it('allows an upload the global capability permits after establishing the agent exists', async () => {
+ /* The bypass lives here rather than at each route, because the two upload routes
+ * answered it differently and an image upload was refused where a file one passed. */
+ const denied = await verifyAgentUploadPermission({
+ req,
+ res: makeRes(),
+ metadata: { agent_id: 'agent_victim01' },
+ getAgent,
+ checkPermission,
+ hasUploadBypass: async () => true,
+ });
+
+ expect(denied).toBe(false);
+ expect(getAgent).toHaveBeenCalled();
+ });
+
+ it('reports a missing agent rather than letting the capability waive it', async () => {
+ getAgent.mockResolvedValue(null);
+ const res = makeRes();
+
+ const denied = await verifyAgentUploadPermission({
+ req,
+ res,
+ metadata: { agent_id: 'missing-agent' },
+ getAgent,
+ checkPermission,
+ hasUploadBypass: async () => true,
+ });
+
+ expect(denied).toBe(true);
+ expect(res.status).toHaveBeenCalledWith(404);
+ });
+
+ it('denies the same upload when the capability is absent', async () => {
+ const denied = await verifyAgentUploadPermission({
+ req,
+ res: makeRes(),
+ metadata: { agent_id: 'agent_victim01' },
+ getAgent,
+ checkPermission,
+ hasUploadBypass: async () => false,
+ });
+
+ expect(denied).toBe(true);
+ });
+
+ it('denies rather than allowing when the capability lookup throws', async () => {
+ const denied = await verifyAgentUploadPermission({
+ req,
+ res: makeRes(),
+ metadata: { agent_id: 'agent_victim01' },
+ getAgent,
+ checkPermission,
+ hasUploadBypass: async () => {
+ throw new Error('capability service unavailable');
+ },
+ });
+
+ expect(denied).toBe(true);
+ });
+});
diff --git a/packages/api/src/files/agents/auth.ts b/packages/api/src/files/agents/auth.ts
index d9fb2b7423..689a6ca4fb 100644
--- a/packages/api/src/files/agents/auth.ts
+++ b/packages/api/src/files/agents/auth.ts
@@ -1,8 +1,14 @@
+import { logger } from '@librechat/data-schemas';
+import {
+ SystemRoles,
+ ResourceType,
+ PermissionBits,
+ isMessageFileUpload,
+ isEphemeralAgentId,
+} from 'librechat-data-provider';
import type { IUser } from '@librechat/data-schemas';
import type { Response } from 'express';
import type { Types } from 'mongoose';
-import { logger } from '@librechat/data-schemas';
-import { SystemRoles, ResourceType, PermissionBits } from 'librechat-data-provider';
import type { ServerRequest } from '~/types';
export type AgentUploadAuthResult =
@@ -35,36 +41,48 @@ export async function checkAgentUploadAuth(
params: AgentUploadAuthParams,
deps: AgentUploadAuthDeps,
): Promise<AgentUploadAuthResult> {
- const { userId, userRole, agentId, toolResource, messageFile } = params;
+ const { userId, userRole, agentId, messageFile } = params;
const { getAgent, checkPermission } = deps;
- const isMessageAttachment = messageFile === true || messageFile === 'true';
- if (!agentId || toolResource == null || isMessageAttachment) {
- return { allowed: true };
- }
-
- if (userRole === SystemRoles.ADMIN) {
+ const isMessageAttachment = isMessageFileUpload(messageFile);
+ /* Any permanent upload against an agent can mutate that agent's resources, so it needs
+ * edit permission whether or not the request names a tool resource: unified uploads
+ * omit it and are promoted to a context resource during processing. A message
+ * attachment belongs to the conversation rather than the agent, so it needs only the
+ * access a conversation already implies, but it cannot skip the check outright: the
+ * upload is validated under the named agent's provider, and those responses describe a
+ * record the caller may not be allowed to see. */
+ /* An ephemeral id names no stored agent, so there is no record to authorize against and
+ * none for the provider resolution to read either. Requiring view access there refuses
+ * every attachment in an ephemeral conversation. Saved ids keep the check. */
+ if (!agentId || (isMessageAttachment && isEphemeralAgentId(agentId))) {
return { allowed: true };
}
+ const requiredPermission = isMessageAttachment ? PermissionBits.VIEW : PermissionBits.EDIT;
+ /* Privilege can waive an ACL check, but it cannot make a missing agent valid. */
const agent = await getAgent({ id: agentId });
if (!agent) {
return { allowed: false, status: 404, error: 'Not Found', message: 'Agent not found' };
}
+ if (userRole === SystemRoles.ADMIN) {
+ return { allowed: true };
+ }
+
if (agent.author?.toString() === userId) {
return { allowed: true };
}
- const hasEditPermission = await checkPermission({
+ const hasPermission = await checkPermission({
userId,
role: userRole,
resourceType: ResourceType.AGENT,
resourceId: agent._id,
- requiredPermission: PermissionBits.EDIT,
+ requiredPermission,
});
- if (hasEditPermission) {
+ if (hasPermission) {
return { allowed: true };
}
@@ -86,12 +104,16 @@ export async function verifyAgentUploadPermission({
metadata,
getAgent,
checkPermission,
+ hasUploadBypass,
}: {
req: ServerRequest;
res: Response;
metadata: { agent_id?: string; tool_resource?: string | null; message_file?: boolean | string };
getAgent: AgentUploadAuthDeps['getAgent'];
checkPermission: AgentUploadAuthDeps['checkPermission'];
+ /** Global capability that permits agent writes regardless of the per-agent grant. Held
+ * here rather than at each route so the two upload routes cannot answer differently. */
+ hasUploadBypass?: () => Promise<boolean>;
}): Promise<boolean> {
const user = req.user as IUser;
const result = await checkAgentUploadAuth(
@@ -106,6 +128,16 @@ export async function verifyAgentUploadPermission({
);
if (!result.allowed) {
+ /* The capability waives the per-agent grant, not the agent's existence. */
+ if (result.status !== 404 && hasUploadBypass) {
+ try {
+ if (await hasUploadBypass()) {
+ return false;
+ }
+ } catch (error) {
+ logger.warn('[agentUploadAuth] capability check failed, denying bypass:', error);
+ }
+ }
res.status(result.status).json({ error: result.error, message: result.message });
return true;
}
diff --git a/packages/api/src/files/code/identity.ts b/packages/api/src/files/code/identity.ts
index 731aba492e..4373c311f1 100644
--- a/packages/api/src/files/code/identity.ts
+++ b/packages/api/src/files/code/identity.ts
@@ -68,6 +68,20 @@ export function appendCodeEnvFileIdentity(form: FormData, identity: CodeEnvIdent
*
* Returns a string with leading `?`; concatenate onto a path.
*/
+/**
+ * The same `kind`/`id`/`version?` identity as an axios `params` object, for callers that
+ * build their query that way rather than concatenating a string. Both forms exist so the
+ * identity codeapi's `sessionAuth` needs is stated once.
+ */
+export function buildCodeEnvIdentityParams(identity: CodeEnvIdentity): Record<string, string> {
+ validateIdentity(identity, 'buildCodeEnvIdentityParams');
+ return {
+ kind: identity.kind,
+ id: identity.id,
+ ...(identity.version != null ? { version: String(identity.version) } : {}),
+ };
+}
+
export function buildCodeEnvDownloadQuery(identity: CodeEnvIdentity): string {
validateIdentity(identity, 'buildCodeEnvDownloadQuery');
const params = new URLSearchParams({ kind: identity.kind, id: identity.id });
diff --git a/packages/api/src/files/context.test.ts b/packages/api/src/files/context.test.ts
new file mode 100644
index 0000000000..efc399f47e
--- /dev/null
+++ b/packages/api/src/files/context.test.ts
@@ -0,0 +1,64 @@
+import { FileSources } from 'librechat-data-provider';
+
+import type { IMongoFile } from '@librechat/data-schemas';
+import type { ServerRequest } from '~/types';
+
+import { extractFileContext } from './context';
+
+const makeReq = () =>
+ ({
+ body: { fileTokenLimit: 1000 },
+ config: { fileConfig: {} },
+ }) as ServerRequest;
+
+const countTokens = (text: string) => text.length;
+
+describe('extractFileContext', () => {
+ it('should skip files with llmDeliveryPath "none"', async () => {
+ const file = {
+ filename: 'hidden.txt',
+ source: FileSources.text,
+ text: 'do not include this',
+ llmDeliveryPath: 'none',
+ } as IMongoFile;
+
+ await expect(
+ extractFileContext({ attachments: [file], req: makeReq(), tokenCountFn: countTokens }),
+ ).resolves.toBeUndefined();
+ });
+
+ it('should include legacy text-source files with undefined llmDeliveryPath', async () => {
+ const file = {
+ filename: 'legacy.txt',
+ source: FileSources.text,
+ text: 'legacy text',
+ } as IMongoFile;
+
+ const result = await extractFileContext({
+ attachments: [file],
+ req: makeReq(),
+ tokenCountFn: countTokens,
+ });
+
+ expect(result).toContain('# "legacy.txt"');
+ expect(result).toContain('legacy text');
+ });
+
+ it('should include standard-storage files with text and llmDeliveryPath "text"', async () => {
+ const file = {
+ filename: 'stored.txt',
+ source: FileSources.local,
+ text: 'stored extracted text',
+ llmDeliveryPath: 'text',
+ } as IMongoFile;
+
+ const result = await extractFileContext({
+ attachments: [file],
+ req: makeReq(),
+ tokenCountFn: countTokens,
+ });
+
+ expect(result).toContain('# "stored.txt"');
+ expect(result).toContain('stored extracted text');
+ });
+});
diff --git a/packages/api/src/files/context.ts b/packages/api/src/files/context.ts
index b16b498b35..735bb63ab1 100644
--- a/packages/api/src/files/context.ts
+++ b/packages/api/src/files/context.ts
@@ -64,7 +64,12 @@ export async function extractFileContext({
for (const file of attachments) {
const source = file.source ?? FileSources.local;
- if (source === FileSources.text && file.text) {
+ if (file.llmDeliveryPath === 'none') {
+ continue;
+ }
+
+ const hasTextDelivery = file.llmDeliveryPath === 'text' || source === FileSources.text;
+ if (hasTextDelivery && file.text) {
const { text: limitedText, wasTruncated } = await processTextWithTokenLimit({
text: file.text,
tokenLimit: fileTokenLimit,
diff --git a/packages/api/src/files/encode/processAttachments.spec.ts b/packages/api/src/files/encode/processAttachments.spec.ts
index f9af6fd1e7..01855dbf67 100644
--- a/packages/api/src/files/encode/processAttachments.spec.ts
+++ b/packages/api/src/files/encode/processAttachments.spec.ts
@@ -17,6 +17,7 @@ function categorizeFile(
source?: string;
embedded?: boolean;
metadata?: { fileIdentifier?: string; codeEnvRef?: unknown };
+ llmDeliveryPath?: 'provider' | 'text' | 'none';
},
isBedrock: boolean,
mergedFileConfig: FileConfig | undefined,
@@ -26,6 +27,9 @@ function categorizeFile(
if (source === FileSources.text) {
return 'skipped';
}
+ if (file.llmDeliveryPath === 'text' || file.llmDeliveryPath === 'none') {
+ return 'skipped';
+ }
if (
file.embedded === true ||
file.metadata?.codeEnvRef != null ||
@@ -154,6 +158,28 @@ describe('processAttachments — supportedMimeTypes routing logic', () => {
expect(result).toBe('skipped');
});
+ it('should skip text-delivery markdown files regardless of config', () => {
+ const { merged, epConfig } = resolveConfig(['.*']);
+ const result = categorizeFile(
+ { type: 'text/markdown', llmDeliveryPath: 'text' },
+ false,
+ merged,
+ epConfig,
+ );
+ expect(result).toBe('skipped');
+ });
+
+ it('should skip none-delivery markdown files regardless of config', () => {
+ const { merged, epConfig } = resolveConfig(['.*']);
+ const result = categorizeFile(
+ { type: 'text/markdown', llmDeliveryPath: 'none' },
+ false,
+ merged,
+ epConfig,
+ );
+ expect(result).toBe('skipped');
+ });
+
it('should skip embedded files regardless of config', () => {
const { merged, epConfig } = resolveConfig(['.*']);
const result = categorizeFile({ type: 'text/csv', embedded: true }, false, merged, epConfig);
diff --git a/packages/api/src/files/filter.spec.ts b/packages/api/src/files/filter.spec.ts
index e74933de24..f64a601719 100644
--- a/packages/api/src/files/filter.spec.ts
+++ b/packages/api/src/files/filter.spec.ts
@@ -2,8 +2,93 @@ import { Types } from 'mongoose';
import { Providers } from '@librechat/agents';
import { EModelEndpoint, FileSources } from 'librechat-data-provider';
import type { IMongoFile } from '@librechat/data-schemas';
+import type { AppConfig } from '@librechat/data-schemas';
import type { ServerRequest } from '~/types';
-import { filterFilesByEndpointConfig } from './filter';
+import { filterFilesByEndpointConfig, filterFilesByEndpointRuntimeConfig } from './filter';
+
+describe('filterFilesByEndpointRuntimeConfig', () => {
+ const sizedFile = (filename: string, bytes: number): IMongoFile =>
+ ({
+ _id: new Types.ObjectId(),
+ user: new Types.ObjectId(),
+ file_id: new Types.ObjectId().toString(),
+ filename,
+ type: 'application/pdf',
+ bytes,
+ object: 'file',
+ usage: 0,
+ source: 'test',
+ filepath: `/test/${filename}`,
+ }) as unknown as IMongoFile;
+
+ /** Endpoint limits are configured in megabytes; 1 MB is 1_048_576 bytes. */
+ const appConfig = {
+ fileConfig: {
+ endpoints: {
+ default: { disabled: false, fileLimit: 10, fileSizeLimit: 1, totalSizeLimit: 1 },
+ },
+ },
+ } as unknown as AppConfig;
+
+ it('spends one total-size allowance across two filtered sets', () => {
+ const delivery = filterFilesByEndpointRuntimeConfig(appConfig, {
+ files: [sizedFile('delivered.pdf', 900_000)],
+ endpoint: 'default',
+ });
+ const deliveredBytes = delivery.reduce((sum, file) => sum + file.bytes, 0);
+
+ const deferred = filterFilesByEndpointRuntimeConfig(appConfig, {
+ files: [sizedFile('deferred.pdf', 900_000)],
+ endpoint: 'default',
+ consumedBytes: deliveredBytes,
+ });
+
+ expect(delivery).toHaveLength(1);
+ expect(deferred).toHaveLength(0);
+ });
+
+ it('still admits a second set that fits in the remaining allowance', () => {
+ const deferred = filterFilesByEndpointRuntimeConfig(appConfig, {
+ files: [sizedFile('deferred.pdf', 100_000)],
+ endpoint: 'default',
+ consumedBytes: 900_000,
+ });
+
+ expect(deferred).toHaveLength(1);
+ });
+
+ it('screens a converted image by the type it was accepted as', () => {
+ /* The allowlist admitted a png, conversion rewrote the stored type, and screening it
+ * by that drops a file the same allowlist accepted minutes earlier. */
+ const narrowConfig = {
+ fileConfig: {
+ endpoints: { default: { disabled: false, supportedMimeTypes: ['^image/png$'] } },
+ },
+ } as unknown as AppConfig;
+ const converted = {
+ ...sizedFile('photo.png', 1000),
+ type: 'image/webp',
+ metadata: { routingMimeType: 'image/png' },
+ } as unknown as IMongoFile;
+
+ expect(
+ filterFilesByEndpointRuntimeConfig(narrowConfig, { files: [converted], endpoint: 'default' }),
+ ).toHaveLength(1);
+ });
+
+ it('still screens an unconverted file by its own type', () => {
+ const narrowConfig = {
+ fileConfig: {
+ endpoints: { default: { disabled: false, supportedMimeTypes: ['^image/png$'] } },
+ },
+ } as unknown as AppConfig;
+ const webp = { ...sizedFile('photo.webp', 1000), type: 'image/webp' } as unknown as IMongoFile;
+
+ expect(
+ filterFilesByEndpointRuntimeConfig(narrowConfig, { files: [webp], endpoint: 'default' }),
+ ).toHaveLength(0);
+ });
+});
describe('filterFilesByEndpointConfig', () => {
/** Helper to create a mock file */
diff --git a/packages/api/src/files/filter.ts b/packages/api/src/files/filter.ts
index 1d2e58cd53..02dc91a3ec 100644
--- a/packages/api/src/files/filter.ts
+++ b/packages/api/src/files/filter.ts
@@ -48,12 +48,32 @@ export function filterFilesByEndpointConfig(
}
/** Request-free endpoint file-policy adapter used by Agent execution hosts. */
+/**
+ * Whether this endpoint still presents the explicit upload-destination chooser. In that
+ * mode the destination is the user's choice and the upload path acts on it immediately,
+ * so nothing may be provisioned to a service they did not select.
+ */
+export function isLegacyFileUploadUX(
+ appConfig: AppConfig | undefined,
+ params: { endpoint?: string | null; endpointType?: string | null },
+): boolean {
+ const endpointFileConfig = getEndpointFileConfig({
+ fileConfig: mergeFileConfig(appConfig?.fileConfig),
+ endpoint: params.endpoint,
+ endpointType: params.endpointType,
+ });
+ return endpointFileConfig?.legacyFileUploadUX === true;
+}
+
export function filterFilesByEndpointRuntimeConfig(
appConfig: AppConfig | undefined,
params: {
files: IMongoFile[] | undefined;
endpoint?: string | null;
endpointType?: string | null;
+ /** Bytes already committed by an earlier call, so a request split across several
+ * sets spends one shared `totalSizeLimit` instead of restarting it per set. */
+ consumedBytes?: number;
skipTotalSizeLimit?: boolean;
preserveTextSources?: boolean;
},
@@ -62,6 +82,7 @@ export function filterFilesByEndpointRuntimeConfig(
files,
endpoint,
endpointType,
+ consumedBytes = 0,
skipTotalSizeLimit = false,
preserveTextSources = false,
} = params;
@@ -97,19 +118,21 @@ export function filterFilesByEndpointRuntimeConfig(
});
}
- /** Filter by MIME type */
+ /** Filter by MIME type, against the type the upload was accepted as. Conversion rewrites
+ * `type`, so screening a converted image by its stored format drops a file the same
+ * allowlist admitted minutes earlier. */
if (supportedMimeTypes && supportedMimeTypes.length > 0) {
filteredFiles = filteredFiles.filter((file) => {
return (
(preserveTextSources && (file.source ?? FileSources.local) === FileSources.text) ||
- isMimeTypeSupported(file.type, supportedMimeTypes)
+ isMimeTypeSupported(file.metadata?.routingMimeType ?? file.type, supportedMimeTypes)
);
});
}
/** Filter by total size limit - keep files until total exceeds limit */
if (!skipTotalSizeLimit && totalSizeLimit !== undefined && totalSizeLimit > 0) {
- let totalSize = 0;
+ let totalSize = consumedBytes;
const withinTotalLimit: IMongoFile[] = [];
for (let i = 0; i < filteredFiles.length; i++) {
diff --git a/packages/api/src/files/index.ts b/packages/api/src/files/index.ts
index 97b7c716ce..87df6f4105 100644
--- a/packages/api/src/files/index.ts
+++ b/packages/api/src/files/index.ts
@@ -13,6 +13,9 @@ export * from './mistral/crud';
export * from './ocr';
export * from './parse';
export * from './preflight';
+export * from './provision';
+export * from './upload/routing';
+export * from './upload/diagnostics';
export * from './rag';
export * from './regexEngine';
export * from './retention';
diff --git a/packages/api/src/files/provision/callback.spec.ts b/packages/api/src/files/provision/callback.spec.ts
new file mode 100644
index 0000000000..cac57da4ab
--- /dev/null
+++ b/packages/api/src/files/provision/callback.spec.ts
@@ -0,0 +1,509 @@
+import { Constants } from '@librechat/agents';
+import { EToolResources, FileContext } from 'librechat-data-provider';
+import type { TFile } from 'librechat-data-provider';
+import type { ProvisionState } from '~/agents/resources';
+import type { ProvisionToolContext } from './callback';
+import type { ServerRequest } from '~/types';
+import { createProvisionFilesCallback } from './callback';
+
+jest.mock('@librechat/data-schemas', () => ({
+ logger: { error: jest.fn(), warn: jest.fn(), debug: jest.fn(), info: jest.fn() },
+}));
+
+const req = { user: { id: 'user-1' } } as ServerRequest;
+
+function makeFile(overrides: Partial<TFile> = {}): TFile {
+ return {
+ file_id: 'file-1',
+ filename: 'data.csv',
+ filepath: '/uploads/data.csv',
+ type: 'text/csv',
+ user: 'user-1',
+ object: 'file',
+ bytes: 10,
+ embedded: false,
+ usage: 0,
+ context: FileContext.message_attachment,
+ ...overrides,
+ } as TFile;
+}
+
+function state(
+ codeEnvFiles: TFile[],
+ vectorDBFiles: TFile[],
+ agentScopedFileIds: string[] = [],
+): ProvisionState {
+ return {
+ codeEnvFiles,
+ vectorDBFiles,
+ aliveFileIds: new Set<string>(),
+ agentScopedFileIds: new Set(agentScopedFileIds),
+ };
+}
+
+function buildHarness({
+ contexts,
+ codeImpl,
+ vectorImpl,
+}: {
+ contexts: Array<[string, ProvisionToolContext]>;
+ codeImpl?: jest.Mock;
+ vectorImpl?: jest.Mock;
+}) {
+ const provisionToCodeEnv =
+ codeImpl ??
+ jest.fn(async ({ file, sandboxFilename }: { file: TFile; sandboxFilename: string }) => ({
+ referenceSet: {
+ codeEnvRefs: {
+ default: {
+ kind: 'user',
+ id: 'u1',
+ storage_session_id: 'sess-1',
+ file_id: 'remote-1',
+ },
+ },
+ },
+ refUpdate: {
+ file_id: file.file_id,
+ routeKey: 'default',
+ ref: { kind: 'user', id: 'u1', storage_session_id: 'sess-1', file_id: 'remote-1' },
+ },
+ /* Mirrors the service: the sandbox stores a converted image under a corrected
+ * extension, so the name the model is told is not always the record's. */
+ sandboxFilename,
+ }));
+ const provisionToVectorDB =
+ vectorImpl ??
+ jest.fn(async ({ file }: { file: TFile }) => ({
+ embedded: true,
+ fileUpdate: { file_id: file.file_id, embedded: true },
+ }));
+ const updateFile = jest.fn(async () => ({}));
+ const updateCodeEnvRef = jest.fn(async () => ({}));
+ const addEmbeddedEntity = jest.fn(async () => ({}));
+ const agentToolContexts = new Map<string, ProvisionToolContext>(contexts);
+
+ return {
+ provisionToCodeEnv,
+ provisionToVectorDB,
+ updateFile,
+ updateCodeEnvRef,
+ addEmbeddedEntity,
+ agentToolContexts,
+ provisionFiles: createProvisionFilesCallback({
+ req,
+ agentToolContexts,
+ provisionToCodeEnv: provisionToCodeEnv as never,
+ provisionToVectorDB: provisionToVectorDB as never,
+ updateFile,
+ updateCodeEnvRef,
+ addEmbeddedEntity,
+ }),
+ };
+}
+
+describe('createProvisionFilesCallback', () => {
+ it('scopes only the agent own resource files to its identity', async () => {
+ /* A user can attach another agent's setup file to this conversation. Uploading it under
+ * this agent would place it in a namespace this agent's other users share, so the
+ * upload identity comes from membership in this agent's resources. */
+ const own = makeFile({ file_id: 'own-file', context: FileContext.agents });
+ const foreign = makeFile({ file_id: 'foreign-file', context: FileContext.agents });
+ const { provisionFiles, provisionToCodeEnv } = buildHarness({
+ contexts: [['agent-a', { provisionState: state([own, foreign], [], ['own-file']) }]],
+ });
+
+ await provisionFiles([Constants.EXECUTE_CODE], 'agent-a');
+
+ const byFile = new Map(
+ provisionToCodeEnv.mock.calls.map(([args]) => [
+ (args as { file: TFile }).file.file_id,
+ (args as { entity_id?: string }).entity_id,
+ ]),
+ );
+ expect(byFile.get('own-file')).toBe('agent-a');
+ expect(byFile.get('foreign-file')).toBeUndefined();
+ });
+
+ it('provisions once for the request when two agents queue the same file', async () => {
+ const shared = makeFile();
+ const contexts: Array<[string, ProvisionToolContext]> = [
+ ['agent-a', { provisionState: state([{ ...shared }], []) }],
+ ['agent-b', { provisionState: state([{ ...shared }], []) }],
+ ];
+ const { provisionFiles, provisionToCodeEnv, agentToolContexts } = buildHarness({ contexts });
+
+ await provisionFiles([Constants.EXECUTE_CODE], 'agent-a');
+ await provisionFiles([Constants.EXECUTE_CODE], 'agent-b');
+
+ expect(provisionToCodeEnv).toHaveBeenCalledTimes(1);
+ for (const agentId of ['agent-a', 'agent-b']) {
+ const ctx = agentToolContexts.get(agentId);
+ const files = (ctx?.tool_resources as Record<string, { files?: TFile[] }>)[
+ EToolResources.execute_code
+ ]?.files;
+ expect(files?.[0]?.metadata).toMatchObject({
+ codeEnvRefs: { default: { file_id: 'remote-1' } },
+ });
+ expect(ctx?.provisionState?.codeEnvFiles).toHaveLength(0);
+ }
+ });
+
+ it('returns the provisioned refs so the batch can inject them', async () => {
+ const { provisionFiles } = buildHarness({
+ contexts: [['agent-a', { provisionState: state([makeFile()], []) }]],
+ });
+
+ const provisioned = await provisionFiles([Constants.EXECUTE_CODE], 'agent-a');
+
+ expect(provisioned).toEqual([
+ {
+ id: 'remote-1',
+ resource_id: 'u1',
+ storage_session_id: 'sess-1',
+ name: 'data.csv',
+ kind: 'user',
+ },
+ ]);
+ });
+
+ it('reports the name the sandbox stored, not the record name', async () => {
+ /* A converted image is uploaded under a corrected extension, so telling the model the
+ * record's name points it at a path the sandbox does not have. */
+ const converted = makeFile({ file_id: 'converted', filename: 'photo.png', type: 'image/webp' });
+ const { provisionFiles } = buildHarness({
+ contexts: [['agent-a', { provisionState: state([converted], []) }]],
+ codeImpl: jest.fn(async ({ file }: { file: TFile }) => ({
+ referenceSet: {
+ codeEnvRef: { kind: 'user', id: 'u1', storage_session_id: 'sess-1', file_id: 'remote-1' },
+ codeEnvRefs: {
+ default: {
+ kind: 'user',
+ id: 'u1',
+ storage_session_id: 'sess-1',
+ file_id: 'remote-1',
+ },
+ },
+ },
+ refUpdate: {
+ file_id: file.file_id,
+ routeKey: 'default',
+ ref: { kind: 'user', id: 'u1', storage_session_id: 'sess-1', file_id: 'remote-1' },
+ },
+ sandboxFilename: 'photo.webp',
+ })),
+ });
+
+ const provisioned = await provisionFiles([Constants.EXECUTE_CODE], 'agent-a');
+
+ expect(provisioned.map((entry) => entry.name)).toEqual(['photo.webp']);
+ });
+
+ it('assigns deterministic unique names before lazy uploads', async () => {
+ const first = makeFile({ file_id: 'first', filename: 'data.csv' });
+ const second = makeFile({ file_id: 'second', filename: 'data.csv', bytes: 20 });
+ const { provisionFiles, provisionToCodeEnv } = buildHarness({
+ contexts: [['agent-a', { provisionState: state([first, second], []) }]],
+ });
+
+ const provisioned = await provisionFiles([Constants.EXECUTE_CODE], 'agent-a');
+ const uploadedNames = provisionToCodeEnv.mock.calls.map(
+ ([args]) => (args as { sandboxFilename: string }).sandboxFilename,
+ );
+
+ expect(new Set(uploadedNames).size).toBe(2);
+ expect(new Set(provisioned.map((file) => file.name))).toEqual(new Set(uploadedNames));
+ });
+
+ it('reserves names already present in the code session', async () => {
+ const existing = makeFile({ file_id: 'existing', filename: 'data.csv' });
+ const queued = makeFile({ file_id: 'queued', filename: 'data.csv' });
+ const { provisionFiles, provisionToCodeEnv } = buildHarness({
+ contexts: [
+ [
+ 'agent-a',
+ {
+ provisionState: state([queued], []),
+ tool_resources: { execute_code: { files: [existing] } },
+ },
+ ],
+ ],
+ });
+
+ await provisionFiles([Constants.EXECUTE_CODE], 'agent-a');
+
+ expect(provisionToCodeEnv).toHaveBeenCalledWith(
+ expect.objectContaining({ sandboxFilename: expect.not.stringMatching(/^data\.csv$/) }),
+ );
+ });
+
+ it('returns the refs to every agent sharing one upload', async () => {
+ const shared = makeFile();
+ const { provisionFiles } = buildHarness({
+ contexts: [
+ ['agent-a', { provisionState: state([{ ...shared }], []) }],
+ ['agent-b', { provisionState: state([{ ...shared }], []) }],
+ ],
+ });
+
+ const first = await provisionFiles([Constants.EXECUTE_CODE], 'agent-a');
+ const second = await provisionFiles([Constants.EXECUTE_CODE], 'agent-b');
+
+ expect(first).toHaveLength(1);
+ expect(second).toEqual(first);
+ });
+
+ it('persists the shared provisioning result once', async () => {
+ const shared = makeFile();
+ const { provisionFiles, updateCodeEnvRef } = buildHarness({
+ contexts: [
+ ['agent-a', { provisionState: state([{ ...shared }], []) }],
+ ['agent-b', { provisionState: state([{ ...shared }], []) }],
+ ],
+ });
+
+ await provisionFiles([Constants.EXECUTE_CODE], 'agent-a');
+ await provisionFiles([Constants.EXECUTE_CODE], 'agent-b');
+
+ expect(updateCodeEnvRef).toHaveBeenCalledTimes(1);
+ });
+
+ it('holds every waiter until the shared reference is persisted', async () => {
+ let releaseWrite: () => void = () => undefined;
+ const writeGate = new Promise<void>((resolve) => {
+ releaseWrite = resolve;
+ });
+ const shared = makeFile();
+ const harness = buildHarness({
+ contexts: [
+ ['agent-a', { provisionState: state([{ ...shared }], []) }],
+ ['agent-b', { provisionState: state([{ ...shared }], []) }],
+ ],
+ });
+ const events: string[] = [];
+ harness.updateCodeEnvRef.mockImplementation(async () => {
+ await writeGate;
+ events.push('write');
+ return {};
+ });
+
+ const waiterA = harness
+ .provisionFiles([Constants.EXECUTE_CODE], 'agent-a')
+ .then(() => events.push('a'));
+ const waiterB = harness
+ .provisionFiles([Constants.EXECUTE_CODE], 'agent-b')
+ .then(() => events.push('b'));
+
+ /* Drains every pending microtask, so anything that could return without the write
+ * already has by the time this resolves. */
+ await new Promise((resolve) => setImmediate(resolve));
+ expect(events).toEqual([]);
+
+ releaseWrite();
+ await Promise.all([waiterA, waiterB]);
+
+ expect(events[0]).toBe('write');
+ expect(events).toHaveLength(3);
+ expect(harness.updateCodeEnvRef).toHaveBeenCalledTimes(1);
+ });
+
+ it('aborts the turn when the reference cannot be persisted', async () => {
+ const harness = buildHarness({
+ contexts: [['agent-a', { provisionState: state([makeFile()], []) }]],
+ });
+ harness.updateCodeEnvRef.mockRejectedValue(new Error('mongo down'));
+
+ await expect(harness.provisionFiles([Constants.EXECUTE_CODE], 'agent-a')).rejects.toThrow(
+ /aborting tool execution rather than running without them/,
+ );
+ expect(harness.updateCodeEnvRef).toHaveBeenCalledTimes(2);
+ });
+
+ it('uploads separately when the agents resolve different code deployments', async () => {
+ const shared = makeFile();
+ const { provisionFiles, provisionToCodeEnv } = buildHarness({
+ contexts: [
+ ['agent-a', { provisionState: state([{ ...shared }], []) }],
+ [
+ 'agent-b',
+ {
+ provisionState: state([{ ...shared }], []),
+ codeExecutionContext: { executionProfile: 'stateful', executionRouteKey: 'stateful:x' },
+ },
+ ],
+ ],
+ });
+
+ await provisionFiles([Constants.EXECUTE_CODE], 'agent-a');
+ await provisionFiles([Constants.EXECUTE_CODE], 'agent-b');
+
+ expect(provisionToCodeEnv).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not start provisioning after the run is cancelled', async () => {
+ const controller = new AbortController();
+ controller.abort();
+ const { provisionFiles, provisionToCodeEnv } = buildHarness({
+ contexts: [['agent-a', { provisionState: state([makeFile()], []) }]],
+ });
+
+ await expect(
+ provisionFiles([Constants.EXECUTE_CODE], 'agent-a', controller.signal),
+ ).rejects.toMatchObject({ name: 'AbortError' });
+ expect(provisionToCodeEnv).not.toHaveBeenCalled();
+ });
+
+ it('shares embedding work across agents queueing the same search file', async () => {
+ const shared = makeFile();
+ const { provisionFiles, provisionToVectorDB, addEmbeddedEntity } = buildHarness({
+ contexts: [
+ ['agent-a', { provisionState: state([], [{ ...shared }]) }],
+ ['agent-b', { provisionState: state([], [{ ...shared }]) }],
+ ],
+ });
+
+ await Promise.all([
+ provisionFiles(['file_search'], 'agent-a'),
+ provisionFiles(['file_search'], 'agent-b'),
+ ]);
+
+ expect(provisionToVectorDB).toHaveBeenCalledTimes(1);
+ /* Unscoped vectors land in the requesting user's namespace, so that is what gets
+ * recorded. Without it the file reads as unembedded and re-embeds every turn. */
+ expect(addEmbeddedEntity).toHaveBeenCalledTimes(1);
+ expect(addEmbeddedEntity).toHaveBeenCalledWith({
+ file_id: shared.file_id,
+ entityId: 'user-1',
+ });
+ });
+
+ it('retries a failed upload on a later tool call instead of replaying the rejection', async () => {
+ let attempts = 0;
+ const codeImpl = jest.fn(async ({ file }: { file: TFile }) => {
+ attempts += 1;
+ if (attempts === 1) {
+ throw new Error('code api unreachable');
+ }
+ return {
+ referenceSet: {
+ codeEnvRefs: {
+ default: {
+ kind: 'user',
+ id: 'u1',
+ storage_session_id: 'sess-1',
+ file_id: 'remote-1',
+ },
+ },
+ },
+ refUpdate: {
+ file_id: file.file_id,
+ routeKey: 'default',
+ ref: { kind: 'user', id: 'u1', storage_session_id: 'sess-1', file_id: 'remote-1' },
+ },
+ };
+ });
+ const { provisionFiles, agentToolContexts } = buildHarness({
+ contexts: [['agent-a', { provisionState: state([makeFile()], []) }]],
+ codeImpl,
+ });
+
+ await expect(provisionFiles([Constants.EXECUTE_CODE], 'agent-a')).rejects.toThrow(
+ /Failed to provision/,
+ );
+ expect(agentToolContexts.get('agent-a')?.provisionState?.codeEnvFiles).toHaveLength(1);
+
+ await expect(provisionFiles([Constants.EXECUTE_CODE], 'agent-a')).resolves.toHaveLength(1);
+ expect(codeImpl).toHaveBeenCalledTimes(2);
+ });
+
+ it('returns earlier successes when the rest of a batch succeeds on retry', async () => {
+ const first = makeFile({ file_id: 'first', filename: 'first.csv' });
+ const second = makeFile({ file_id: 'second', filename: 'second.csv' });
+ let secondAttempts = 0;
+ const codeImpl = jest.fn(
+ async ({ file, sandboxFilename }: { file: TFile; sandboxFilename: string }) => {
+ if (file.file_id === 'second' && secondAttempts++ === 0) {
+ throw new Error('temporary failure');
+ }
+ const remoteId = `remote-${file.file_id}`;
+ return {
+ referenceSet: {
+ codeEnvRefs: {
+ default: {
+ kind: 'user',
+ id: 'u1',
+ storage_session_id: 'sess-1',
+ file_id: remoteId,
+ },
+ },
+ },
+ refUpdate: {
+ file_id: file.file_id,
+ routeKey: 'default',
+ ref: {
+ kind: 'user',
+ id: 'u1',
+ storage_session_id: 'sess-1',
+ file_id: remoteId,
+ },
+ },
+ sandboxFilename,
+ };
+ },
+ );
+ const { provisionFiles } = buildHarness({
+ contexts: [['agent-a', { provisionState: state([first, second], []) }]],
+ codeImpl,
+ });
+
+ await expect(provisionFiles([Constants.EXECUTE_CODE], 'agent-a')).rejects.toThrow(
+ /Failed to provision/,
+ );
+ const retried = await provisionFiles([Constants.EXECUTE_CODE], 'agent-a');
+
+ expect(retried.map((file) => file.id).sort()).toEqual(['remote-first', 'remote-second']);
+ expect(codeImpl.mock.calls.filter(([args]) => args.file.file_id === 'first')).toHaveLength(1);
+ });
+
+ it('treats a declined embedding as a failure rather than a result', async () => {
+ /* The service resolves with embedded false when the vector store declines the file.
+ * That means the vectors are absent just as a throw does, so the file has to stay
+ * queued instead of search proceeding without it. */
+ const vectorImpl = jest.fn(async () => ({ embedded: false, fileUpdate: null }));
+ const { provisionFiles, agentToolContexts } = buildHarness({
+ contexts: [['agent-a', { provisionState: state([], [makeFile()]) }]],
+ vectorImpl,
+ });
+
+ await expect(provisionFiles(['file_search'], 'agent-a')).rejects.toThrow(
+ /aborting tool execution rather than searching without them/,
+ );
+ expect(agentToolContexts.get('agent-a')?.provisionState?.vectorDBFiles).toHaveLength(1);
+ });
+
+ it('aborts the turn when search provisioning fails', async () => {
+ const vectorImpl = jest.fn(async () => {
+ throw new Error('rag unreachable');
+ });
+ const { provisionFiles, agentToolContexts } = buildHarness({
+ contexts: [['agent-a', { provisionState: state([], [makeFile()]) }]],
+ vectorImpl,
+ });
+
+ await expect(provisionFiles(['file_search'], 'agent-a')).rejects.toThrow(
+ /aborting tool execution rather than searching without them/,
+ );
+ expect(agentToolContexts.get('agent-a')?.provisionState?.vectorDBFiles).toHaveLength(1);
+ });
+
+ it('ignores tool batches that need neither code nor search', async () => {
+ const { provisionFiles, provisionToCodeEnv, provisionToVectorDB } = buildHarness({
+ contexts: [['agent-a', { provisionState: state([makeFile()], [makeFile()]) }]],
+ });
+
+ await provisionFiles(['web_search'], 'agent-a');
+
+ expect(provisionToCodeEnv).not.toHaveBeenCalled();
+ expect(provisionToVectorDB).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/api/src/files/provision/callback.ts b/packages/api/src/files/provision/callback.ts
new file mode 100644
index 0000000000..d76e7090a3
--- /dev/null
+++ b/packages/api/src/files/provision/callback.ts
@@ -0,0 +1,437 @@
+import { Constants } from '@librechat/agents';
+import { logger } from '@librechat/data-schemas';
+import { EToolResources, resolveSandboxFilename } from 'librechat-data-provider';
+import type { AgentToolResources, TFile } from 'librechat-data-provider';
+import type { CodeEnvFile } from '@librechat/agents';
+import type { CodeEnvRefUpdate, CodeExecutionRoute, ProvisionService } from './service';
+import type { ProvisionState } from '~/agents/resources';
+import type { ServerRequest } from '~/types';
+import { claimCodeDestination, createCodeDestinationSet } from '~/files/code/destinations';
+import { isCodeFileToolName } from '~/agents/tools';
+
+/** Deferred database write produced by a successful provisioning call. */
+interface FileUpdate {
+ file_id: string;
+ metadata?: Record<string, unknown>;
+ embedded?: boolean;
+}
+
+/** One attempt plus one retry: a transient write failure would otherwise leave the record
+ * unprovisioned while the queue is cleared. */
+async function persistWithRetry(
+ write: () => Promise<unknown>,
+ onFailure: (error: unknown) => void,
+): Promise<boolean> {
+ for (let attempt = 0; attempt < 2; attempt++) {
+ try {
+ await write();
+ return true;
+ } catch (error) {
+ if (attempt === 1) {
+ onFailure(error);
+ }
+ }
+ }
+ return false;
+}
+
+/** The slice of a per-agent tool context this callback reads and updates. */
+export interface ProvisionToolContext {
+ provisionState?: ProvisionState;
+ tool_resources?: AgentToolResources;
+ /** Code API deployment this agent resolved, so uploads land where it will execute. */
+ codeExecutionContext?: CodeExecutionRoute;
+ /** Successful refs retained while another file in the same batch awaits retry. */
+ pendingProvisionedCodeFiles?: CodeEnvFile[];
+}
+
+export interface ProvisionCallbackDeps {
+ req: ServerRequest;
+ agentToolContexts: Map<string, ProvisionToolContext>;
+ resolvePrimaryAgentId?: () => string | undefined;
+ provisionToCodeEnv: ProvisionService['provisionToCodeEnv'];
+ provisionToVectorDB: ProvisionService['provisionToVectorDB'];
+ updateFile: (update: FileUpdate) => Promise<unknown>;
+ updateCodeEnvRef: (update: CodeEnvRefUpdate) => Promise<unknown>;
+ /** Records one vector namespace without disturbing the others already recorded. */
+ addEmbeddedEntity: (update: { file_id: string; entityId: string }) => Promise<unknown>;
+}
+
+/**
+ * Selects the tool context for a provisioning batch and reports which agent id it
+ * belongs to. The batch id is preferred, then the primary agent, then the sole context
+ * when only one exists, mirroring how the tool loaders resolve theirs.
+ *
+ */
+function resolveProvisionContext({
+ agentId,
+ agentToolContexts,
+ primaryAgentId,
+}: {
+ agentId?: string;
+ agentToolContexts: Map<string, ProvisionToolContext>;
+ primaryAgentId?: string;
+}): { ctx?: ProvisionToolContext; resolvedAgentId?: string } {
+ if (agentId != null && agentToolContexts.has(agentId)) {
+ return { ctx: agentToolContexts.get(agentId), resolvedAgentId: agentId };
+ }
+ if (primaryAgentId != null && agentToolContexts.has(primaryAgentId)) {
+ return { ctx: agentToolContexts.get(primaryAgentId), resolvedAgentId: primaryAgentId };
+ }
+ if (agentToolContexts.size === 1) {
+ const sole = agentToolContexts.entries().next().value;
+ if (sole) {
+ const [key, ctx] = sole;
+ return { ctx, resolvedAgentId: key };
+ }
+ }
+ return {};
+}
+
+/**
+ * Builds the ON_TOOL_EXECUTE provisioning callback. Shared by the chat path and the
+ * OpenAI-compatible controllers so every surface provisions queued attachments before
+ * the tool that needs them loads.
+ */
+export function createProvisionFilesCallback({
+ req,
+ agentToolContexts,
+ resolvePrimaryAgentId,
+ provisionToCodeEnv,
+ provisionToVectorDB,
+ updateFile,
+ updateCodeEnvRef,
+ addEmbeddedEntity,
+}: ProvisionCallbackDeps): (
+ toolNames: string[],
+ agentId?: string,
+ signal?: AbortSignal,
+) => Promise<CodeEnvFile[]> {
+ /* Agents in a handoff or parallel graph are initialized independently over the same
+ * request attachments, so each holds its own ProvisionState for the same file. Keyed
+ * per file, destination and scope, this makes the upload happen once for the request;
+ * every agent still applies the result to its own tool resources below. The shared
+ * work includes the database write, because the tools loaded right after this callback
+ * re-read the stored record and skip files whose reference is not there yet. */
+ const inFlight = new Map<string, Promise<unknown>>();
+
+ function shareProvisioning<T>(key: string | undefined, start: () => Promise<T>): Promise<T> {
+ if (key == null) {
+ return start();
+ }
+ const existing = inFlight.get(key) as Promise<T> | undefined;
+ if (existing) {
+ return existing;
+ }
+ const promise = start();
+ inFlight.set(key, promise);
+ /* Forget failures so a later tool call in the same request retries the upload
+ * instead of replaying the rejection. */
+ promise.catch(() => {
+ if (inFlight.get(key) === promise) {
+ inFlight.delete(key);
+ }
+ });
+ return promise;
+ }
+
+ return async function provisionFiles(
+ toolNames: string[],
+ agentId?: string,
+ signal?: AbortSignal,
+ ): Promise<CodeEnvFile[]> {
+ signal?.throwIfAborted();
+ /* agentId is optional on this callback and a batch for the primary agent may omit
+ * it, so fall back the way the tool loaders do. Otherwise the queue is missed and
+ * the tool runs without its attachments. */
+ /* Resolve the context and the id together. Scoping agent files by the raw argument
+ * while reading state from a fallback context would upload them as user-scoped,
+ * then reconstruct them as agent-scoped on the next turn, and the entity id used to
+ * query those vectors would no longer match the one they were stored under. */
+ const { ctx, resolvedAgentId } = resolveProvisionContext({
+ agentId,
+ agentToolContexts,
+ primaryAgentId: resolvePrimaryAgentId?.(),
+ });
+ if (!ctx?.provisionState) {
+ return [];
+ }
+
+ const { provisionState } = ctx;
+ /** The same set that decides whether an agent wants code-file provisioning at all,
+ * so a tool cannot be eligible in one place and unrecognized in the other. */
+ const needsCode = toolNames.some(isCodeFileToolName);
+ /** Programmatic tool calling orchestrates nested tools whose names never reach
+ * this predicate, so a file_search reachable only through PTC would otherwise
+ * run before its attachments were embedded. Provision when PTC is invoked. */
+ const needsSearch =
+ toolNames.includes('file_search') ||
+ toolNames.includes(Constants.PROGRAMMATIC_TOOL_CALLING) ||
+ toolNames.includes(Constants.BASH_PROGRAMMATIC_TOOL_CALLING);
+
+ if (!needsCode && !needsSearch) {
+ return [];
+ }
+
+ /** Chat attachments and generated code outputs stay in the user's sandbox and unscoped
+ * vector index; only this agent's own setup files are scoped to it. Membership decides
+ * that, not the record's context: a user may attach another agent's setup file to this
+ * conversation, and provisioning it under this agent would place it in a namespace
+ * this agent's other users can read. */
+ const entityIdForFile = (file: TFile) =>
+ file.file_id && provisionState.agentScopedFileIds.has(file.file_id)
+ ? resolvedAgentId
+ : undefined;
+
+ /** Which vector namespace holds the file after this upload. Unscoped uploads are
+ * partitioned by the requesting user, so recording only agent namespaces would leave
+ * a foreign setup file looking unembedded here forever, re-embedding every turn. */
+ const namespaceForFile = (file: TFile) => entityIdForFile(file) ?? req?.user?.id;
+
+ /** Two agents may resolve different code deployments, where the same file genuinely
+ * needs uploading to each, so the destination is part of the sharing key. */
+ const codeRouteKey =
+ ctx.codeExecutionContext?.executionRouteKey ??
+ ctx.codeExecutionContext?.executionProfile ??
+ 'default';
+ const shareKey = (resource: string, file: TFile, destination = '') =>
+ file.file_id
+ ? `${resource}:${file.file_id}:${entityIdForFile(file) ?? ''}:${destination}`
+ : undefined;
+
+ /** Surface a just-provisioned file to the tool loaded immediately after: the code
+ * and file_search primers read `tool_resources.<resource>.files`. */
+ if (!ctx.tool_resources) {
+ ctx.tool_resources = {};
+ }
+ const addProvisionedFile = (
+ file: TFile,
+ resourceType: EToolResources,
+ agentScoped?: boolean,
+ ) => {
+ if (!file.file_id) {
+ return;
+ }
+ const toolResources = ctx.tool_resources as Record<
+ string,
+ { files?: TFile[]; file_ids?: string[] } | undefined
+ >;
+ const resource = toolResources[resourceType] ?? {};
+ /** Agent-scoped file_search files are embedded under `entity_id: agentId`, so
+ * they must be queried by `file_ids` (primeFiles marks those `fromAgent` and
+ * passes `entity_id`); user chat attachments and code files live in `files`. */
+ if (agentScoped && resourceType === EToolResources.file_search) {
+ const fileIds = resource.file_ids ? [...resource.file_ids] : [];
+ if (!fileIds.includes(file.file_id)) {
+ fileIds.push(file.file_id);
+ }
+ toolResources[resourceType] = { ...resource, file_ids: fileIds };
+ return;
+ }
+ const files = resource.files ? [...resource.files] : [];
+ if (!files.some((existing) => existing.file_id === file.file_id)) {
+ files.push(file);
+ }
+ toolResources[resourceType] = { ...resource, files };
+ };
+
+ /** Files whose provisioning rejected this turn; kept queued so a transient
+ * outage can retry next turn instead of being silently dropped. */
+ const failedCodeFiles: TFile[] = [];
+ const failedVectorFiles: TFile[] = [];
+ /* The graph seeded each tool call's code-session context from the sessions that
+ * existed at run start, which predate this upload. Returning the refs lets the
+ * caller fold them into the current batch, since the sandbox receives files only
+ * through that context. */
+ const provisionedCodeFiles: CodeEnvFile[] = needsCode
+ ? [...(ctx.pendingProvisionedCodeFiles ?? [])]
+ : [];
+ if (needsCode && provisionState.codeEnvFiles.length > 0) {
+ const queuedCodeFiles = provisionState.codeEnvFiles;
+ const destinations = createCodeDestinationSet();
+ const existingCodeFiles = (
+ ctx.tool_resources as Record<string, { files?: TFile[] } | undefined>
+ )[EToolResources.execute_code]?.files;
+ const queuedFileIds = new Set(queuedCodeFiles.map((file) => file.file_id));
+ for (const existing of existingCodeFiles ?? []) {
+ if (queuedFileIds.has(existing.file_id)) {
+ continue;
+ }
+ claimCodeDestination(
+ destinations,
+ resolveSandboxFilename(existing.filename, existing.type),
+ existing.file_id,
+ );
+ }
+ for (const existing of provisionedCodeFiles) {
+ claimCodeDestination(destinations, existing.name, existing.id);
+ }
+ const results = await Promise.allSettled(
+ queuedCodeFiles.map(async (file) => {
+ const sandboxFilename = claimCodeDestination(
+ destinations,
+ resolveSandboxFilename(file.filename, file.type),
+ file.file_id,
+ );
+ const provisioned = await shareProvisioning(
+ shareKey(`code:${codeRouteKey}`, file, sandboxFilename),
+ async () => {
+ const {
+ referenceSet: refs,
+ refUpdate,
+ sandboxFilename: storedSandboxFilename,
+ } = await provisionToCodeEnv({
+ req,
+ file,
+ entity_id: entityIdForFile(file),
+ route: ctx.codeExecutionContext,
+ sandboxFilename,
+ signal,
+ });
+ signal?.throwIfAborted();
+ /* primeCodeFiles re-reads the database and skips files without a stored
+ * reference, so a tool loaded after an unpersisted upload would run against
+ * an attachment it cannot see. Fail instead of answering from missing input. */
+ const persisted = await persistWithRetry(
+ () => updateCodeEnvRef(refUpdate),
+ (error) =>
+ logger.error(
+ `[provisionFiles] Failed to persist code environment reference for file ${refUpdate.file_id}`,
+ error,
+ ),
+ );
+ if (!persisted) {
+ throw new Error(
+ `Failed to persist the code environment reference for file ${refUpdate.file_id}`,
+ );
+ }
+ return { refs, sandboxFilename: storedSandboxFilename };
+ },
+ );
+ const { refs: referenceSet, sandboxFilename: returnedSandboxFilename } = provisioned;
+ file.metadata = { ...file.metadata, ...referenceSet };
+ addProvisionedFile(file, EToolResources.execute_code);
+ const ref = referenceSet.codeEnvRefs?.[codeRouteKey];
+ if (ref?.storage_session_id && ref.file_id) {
+ const codeFile = {
+ id: ref.file_id,
+ resource_id: ref.id,
+ storage_session_id: ref.storage_session_id,
+ /* The name the sandbox stored it under: a converted image is renamed on
+ * upload, and telling the model the record's name sends it to a path that
+ * does not exist. */
+ name: returnedSandboxFilename,
+ kind: ref.kind,
+ } as CodeEnvFile;
+ const existingIndex = provisionedCodeFiles.findIndex(
+ (existing) => existing.id === codeFile.id && existing.name === codeFile.name,
+ );
+ if (existingIndex >= 0) {
+ provisionedCodeFiles[existingIndex] = codeFile;
+ } else {
+ provisionedCodeFiles.push(codeFile);
+ }
+ }
+ }),
+ );
+ results.forEach((result, index) => {
+ if (result.status === 'rejected') {
+ logger.error('[provisionFiles] Code env provisioning failed', result.reason);
+ failedCodeFiles.push(queuedCodeFiles[index]);
+ }
+ });
+ provisionState.codeEnvFiles = failedCodeFiles;
+ if (provisionedCodeFiles.length > 0) {
+ ctx.pendingProvisionedCodeFiles = provisionedCodeFiles;
+ }
+ }
+
+ if (needsSearch && provisionState.vectorDBFiles.length > 0) {
+ const queuedVectorFiles = provisionState.vectorDBFiles;
+ const results = await Promise.allSettled(
+ queuedVectorFiles.map(async (file) => {
+ const result = await shareProvisioning(shareKey('search', file), async () => {
+ const provisioned = await provisionToVectorDB({
+ req,
+ file,
+ entity_id: entityIdForFile(file),
+ signal,
+ });
+ signal?.throwIfAborted();
+ /* The vectors are already stored, so a failed flag write costs a re-embed next
+ * turn rather than this turn's results. Logged, not fatal. */
+ if (provisioned.embedded && provisioned.fileUpdate) {
+ const update = provisioned.fileUpdate;
+ /* Vectors live under the entity that provisioned them, so the namespace is
+ * recorded alongside the flag. Agents sharing a record, as a duplicate does
+ * with its source, each need their own embedding, and an unscoped upload
+ * lands in the user's namespace rather than in none. */
+ const namespace = namespaceForFile(file);
+ await persistWithRetry(
+ () =>
+ namespace != null
+ ? addEmbeddedEntity({ file_id: update.file_id, entityId: namespace })
+ : updateFile(update),
+ (error) =>
+ logger.error(
+ `[provisionFiles] Failed to persist embedding state for file ${update.file_id}`,
+ error,
+ ),
+ );
+ }
+ return provisioned;
+ });
+ if (result.embedded) {
+ file.embedded = true;
+ const namespace = namespaceForFile(file);
+ if (namespace != null) {
+ const recorded = new Set(file.metadata?.embeddedEntities ?? []);
+ recorded.add(namespace);
+ file.metadata = { ...file.metadata, embeddedEntities: [...recorded] };
+ }
+ addProvisionedFile(
+ file,
+ EToolResources.file_search,
+ entityIdForFile(file) !== undefined,
+ );
+ return;
+ }
+ /* Resolving with embedded false is a normal outcome of the service, returned
+ * when the vector store declines the file, and it means the same thing as a
+ * throw: the vectors are not there. Treated as a failure so the file stays
+ * queued and search does not proceed without it. */
+ throw new Error(`Vector store did not embed "${file.filename}" (${file.file_id})`);
+ }),
+ );
+ results.forEach((result, index) => {
+ if (result.status === 'rejected') {
+ logger.error('[provisionFiles] Vector DB provisioning failed', result.reason);
+ failedVectorFiles.push(queuedVectorFiles[index]);
+ }
+ });
+ /* Preserved for a later retry, and fatal for this turn like a code failure. An
+ * earlier version let search proceed on the grounds that a missing embedding only
+ * narrows results, but a search that silently omits the file the user asked about
+ * is a wrong answer, not a smaller one. */
+ provisionState.vectorDBFiles = failedVectorFiles;
+ }
+
+ /* Provisioning failed outright, so the sandbox or vector store does not have the
+ * attachment; running the tool anyway would answer from missing input. */
+ if (failedCodeFiles.length > 0) {
+ throw new Error(
+ `Failed to provision ${failedCodeFiles.length} file(s) to the code environment; aborting tool execution rather than running without them`,
+ );
+ }
+ if (failedVectorFiles.length > 0) {
+ throw new Error(
+ `Failed to provision ${failedVectorFiles.length} file(s) for search; aborting tool execution rather than searching without them`,
+ );
+ }
+
+ if (needsCode) {
+ ctx.pendingProvisionedCodeFiles = undefined;
+ }
+ return provisionedCodeFiles;
+ };
+}
diff --git a/packages/api/src/files/provision/index.ts b/packages/api/src/files/provision/index.ts
new file mode 100644
index 0000000000..df3d7f48a4
--- /dev/null
+++ b/packages/api/src/files/provision/index.ts
@@ -0,0 +1,2 @@
+export * from './service';
+export * from './callback';
diff --git a/packages/api/src/files/provision/service.spec.ts b/packages/api/src/files/provision/service.spec.ts
new file mode 100644
index 0000000000..5ed9f069b0
--- /dev/null
+++ b/packages/api/src/files/provision/service.spec.ts
@@ -0,0 +1,322 @@
+import { Readable } from 'node:stream';
+import type { TFile } from 'librechat-data-provider';
+import type { ServerRequest } from '~/types';
+
+const mockAxios = jest.fn();
+const mockGetCodeApiAuthHeaders = jest.fn();
+
+jest.mock('~/utils', () => ({
+ ...jest.requireActual('~/utils'),
+ createAxiosInstance: () => mockAxios,
+ logAxiosError: jest.fn(),
+}));
+
+jest.mock('~/auth/codeapi', () => ({
+ ...jest.requireActual('~/auth/codeapi'),
+ getCodeApiAuthHeaders: (...args: unknown[]) => mockGetCodeApiAuthHeaders(...args),
+}));
+
+jest.mock('@librechat/agents', () => ({
+ getCodeBaseURL: () => 'http://code.test/v1',
+}));
+
+import { createProvisionService } from './service';
+
+const req = { user: { id: 'u1' } } as unknown as ServerRequest;
+
+const makeFile = (overrides: Partial<TFile> = {}): TFile =>
+ ({
+ file_id: 'f1',
+ filename: 'data.csv',
+ filepath: '/x/data.csv',
+ type: 'text/csv',
+ source: 'local',
+ metadata: {},
+ ...overrides,
+ }) as TFile;
+
+const buildService = (overrides: Record<string, unknown> = {}) => {
+ const uploadCodeEnvFile = jest
+ .fn()
+ .mockResolvedValue({ storage_session_id: 's1', file_id: 'remote-1' });
+ const getDownloadStream = jest.fn().mockResolvedValue({ pipe: jest.fn(), on: jest.fn() });
+ const service = createProvisionService({
+ getStrategyFunctions: ((source: string) =>
+ source === 'execute_code'
+ ? { handleFileUpload: uploadCodeEnvFile }
+ : { getDownloadStream }) as never,
+ uploadVectors: jest.fn().mockResolvedValue({ embedded: true }),
+ loadAuthValues: jest.fn().mockResolvedValue({ LIBRECHAT_CODE_API_KEY: 'secret-key' }),
+ ...overrides,
+ } as never);
+ return { service, uploadCodeEnvFile, getDownloadStream };
+};
+
+describe('createProvisionService', () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ mockGetCodeApiAuthHeaders.mockResolvedValue({});
+ });
+
+ describe('loadCodeApiKey', () => {
+ it('reads the code key field without throwing when it is absent', async () => {
+ const loadAuthValues = jest.fn().mockResolvedValue({});
+ const { service } = buildService({ loadAuthValues });
+
+ await expect(service.loadCodeApiKey('u1')).resolves.toBeUndefined();
+ expect(loadAuthValues).toHaveBeenCalledWith({
+ userId: 'u1',
+ authFields: ['LIBRECHAT_CODE_API_KEY'],
+ throwError: false,
+ });
+ });
+ });
+
+ describe('provisionToCodeEnv', () => {
+ it('renames a converted image to match its stored MIME type', async () => {
+ const { service, uploadCodeEnvFile } = buildService();
+
+ const result = await service.provisionToCodeEnv({
+ req,
+ file: makeFile({ filename: 'photo.jpg', type: 'image/webp' }),
+ });
+
+ expect(uploadCodeEnvFile).toHaveBeenCalledWith(
+ expect.objectContaining({ filename: 'photo.webp' }),
+ );
+ expect(result.referenceSet.codeEnvRefs?.default?.file_id).toBe('remote-1');
+ });
+
+ it('refuses a source whose download contract differs', async () => {
+ const { service, uploadCodeEnvFile } = buildService();
+
+ await expect(
+ service.provisionToCodeEnv({ req, file: makeFile({ source: 'openai' as never }) }),
+ ).rejects.toThrow(/does not support download streams/);
+ expect(uploadCodeEnvFile).not.toHaveBeenCalled();
+ });
+
+ it('prefers a durable storage key when opening the backing object', async () => {
+ const { service, getDownloadStream } = buildService();
+
+ await service.provisionToCodeEnv({
+ req,
+ file: makeFile({ filepath: 'https://old.example/file', storageKey: 'uploads/u1/data.csv' }),
+ });
+
+ expect(getDownloadStream).toHaveBeenCalledWith(req, 'uploads/u1/data.csv', {
+ signal: undefined,
+ });
+ });
+
+ it('cancels storage acquisition and destroys a stream returned after cancellation', async () => {
+ const controller = new AbortController();
+ let resolveDownload!: (stream: Readable) => void;
+ const getDownloadStream = jest.fn(
+ () =>
+ new Promise<Readable>((resolve) => {
+ resolveDownload = resolve;
+ }),
+ );
+ const { service } = buildService({
+ getStrategyFunctions: (source: string) =>
+ source === 'execute_code' ? { handleFileUpload: jest.fn() } : { getDownloadStream },
+ });
+ const pending = service.provisionToCodeEnv({
+ req,
+ file: makeFile(),
+ signal: controller.signal,
+ });
+
+ controller.abort();
+ const stream = new Readable({ read() {} });
+ const destroy = jest.spyOn(stream, 'destroy');
+ resolveDownload(stream);
+
+ await expect(pending).rejects.toMatchObject({ name: 'AbortError' });
+ expect(getDownloadStream).toHaveBeenCalledWith(req, '/x/data.csv', {
+ signal: controller.signal,
+ });
+ expect(destroy).toHaveBeenCalled();
+ });
+
+ it('uploads to the agent resolved route and records its key', async () => {
+ const { service, uploadCodeEnvFile } = buildService();
+
+ const result = await service.provisionToCodeEnv({
+ req,
+ file: makeFile(),
+ route: {
+ baseUrl: 'http://stateful.test/v1',
+ executionProfile: 'stateful',
+ executionRouteKey: 'stateful:abc',
+ },
+ });
+
+ expect(uploadCodeEnvFile).toHaveBeenCalledWith(
+ expect.objectContaining({
+ codeApiBaseUrl: 'http://stateful.test/v1',
+ executionProfile: 'stateful',
+ }),
+ );
+ expect(result.referenceSet.codeEnvRefs?.['stateful:abc']?.executionProfile).toBe('stateful');
+ });
+
+ it('defaults to the default deployment when no route is resolved', async () => {
+ const { service, uploadCodeEnvFile } = buildService();
+
+ const result = await service.provisionToCodeEnv({ req, file: makeFile() });
+
+ expect(uploadCodeEnvFile).toHaveBeenCalledWith(
+ expect.objectContaining({ executionProfile: 'default' }),
+ );
+ expect(uploadCodeEnvFile.mock.calls[0][0].codeApiBaseUrl).toBeUndefined();
+ expect(result.referenceSet.codeEnvRefs?.default?.file_id).toBe('remote-1');
+ });
+
+ it('lets the injected vector backend define availability', async () => {
+ const previous = process.env.RAG_API_URL;
+ delete process.env.RAG_API_URL;
+ const uploadVectors = jest.fn().mockResolvedValue({ embedded: true });
+ const { service } = buildService({ uploadVectors });
+
+ await expect(
+ service.provisionToVectorDB({
+ req,
+ file: makeFile(),
+ existingStream: Readable.from('data'),
+ }),
+ ).resolves.toEqual({ embedded: true, fileUpdate: { file_id: 'f1', embedded: true } });
+ expect(uploadVectors).toHaveBeenCalledTimes(1);
+
+ if (previous != null) {
+ process.env.RAG_API_URL = previous;
+ }
+ });
+
+ it('preserves pointers for other code routes', async () => {
+ const { service } = buildService();
+ const statefulRef = {
+ kind: 'user',
+ id: 'u1',
+ storage_session_id: 's-stateful',
+ file_id: 'r-stateful',
+ executionProfile: 'stateful',
+ executionRouteKey: 'stateful:abc',
+ };
+
+ const result = await service.provisionToCodeEnv({
+ req,
+ file: makeFile({ metadata: { codeEnvRefs: { 'stateful:abc': statefulRef } } as never }),
+ });
+
+ expect(result.referenceSet.codeEnvRefs?.['stateful:abc']).toEqual(statefulRef);
+ expect(result.referenceSet.codeEnvRefs?.default?.file_id).toBe('remote-1');
+ });
+ });
+
+ describe('checkSessionsAlive', () => {
+ const staleFile = (id: string) =>
+ makeFile({
+ file_id: id,
+ metadata: {
+ codeEnvRef: {
+ kind: 'user',
+ id: 'u1',
+ storage_session_id: 'sess-1',
+ file_id: `remote-${id}`,
+ provisionedAt: 1,
+ },
+ } as never,
+ });
+
+ it('authenticates with bearer headers when no legacy key is set', async () => {
+ mockGetCodeApiAuthHeaders.mockResolvedValue({ Authorization: 'Bearer jwt' });
+ mockAxios.mockResolvedValue({ data: [{ fileId: 'remote-f1' }] });
+ const { service } = buildService();
+
+ const alive = await service.checkSessionsAlive({ files: [staleFile('f1')], req });
+
+ const headers = mockAxios.mock.calls[0][0].headers;
+ expect(headers.Authorization).toBe('Bearer jwt');
+ expect(headers['X-API-Key']).toBeUndefined();
+ expect(alive.has('f1')).toBe(true);
+ });
+
+ it('probes an agent-scoped session with the identity codeapi needs to resolve it', async () => {
+ /* Codeapi rebuilds the session key from kind and id for shared kinds. Without them
+ * it looks in the requester's own bucket, 404s on a live agent session, and this
+ * method reads that as expiry and queues a needless re-upload. */
+ mockAxios.mockResolvedValue({ data: [{ fileId: 'remote-agent' }] });
+ const { service } = buildService();
+ const agentFile = makeFile({
+ file_id: 'f-agent',
+ metadata: {
+ codeEnvRef: {
+ kind: 'agent',
+ id: 'agent_a1',
+ storage_session_id: 'sess-agent',
+ file_id: 'remote-agent',
+ provisionedAt: 1,
+ },
+ } as never,
+ });
+
+ const alive = await service.checkSessionsAlive({ files: [agentFile], req });
+
+ expect(mockAxios.mock.calls[0][0].params).toEqual(
+ expect.objectContaining({ kind: 'agent', id: 'agent_a1', detail: 'summary' }),
+ );
+ expect(alive.has('f-agent')).toBe(true);
+ });
+
+ it('sends the legacy key alongside minted headers', async () => {
+ mockAxios.mockResolvedValue({ data: [] });
+ const { service } = buildService();
+
+ await service.checkSessionsAlive({ files: [staleFile('f2')], apiKey: 'legacy-key' });
+
+ expect(mockAxios.mock.calls[0][0].headers['X-API-Key']).toBe('legacy-key');
+ });
+
+ it('preserves references when the probe itself fails', async () => {
+ mockAxios.mockRejectedValue(new Error('ETIMEDOUT'));
+ const { service } = buildService();
+
+ const alive = await service.checkSessionsAlive({ files: [staleFile('f3')], apiKey: 'k' });
+
+ expect(alive.has('f3')).toBe(true);
+ });
+
+ it('preserves references when auth headers cannot be built', async () => {
+ mockGetCodeApiAuthHeaders.mockRejectedValue(new Error('no tenant context'));
+ const { service } = buildService();
+
+ const alive = await service.checkSessionsAlive({ files: [staleFile('f4')], req });
+
+ expect(alive.has('f4')).toBe(true);
+ expect(mockAxios).not.toHaveBeenCalled();
+ });
+
+ it('expires references when the Code API reports the session is gone', async () => {
+ const notFound = Object.assign(new Error('Request failed with status code 404'), {
+ response: { status: 404 },
+ });
+ mockAxios.mockRejectedValue(notFound);
+ const { service } = buildService();
+
+ const alive = await service.checkSessionsAlive({ files: [staleFile('f6')], apiKey: 'k' });
+
+ expect(alive.has('f6')).toBe(false);
+ });
+
+ it('expires a reference the probe reports as absent', async () => {
+ mockAxios.mockResolvedValue({ data: [{ fileId: 'someone-else' }] });
+ const { service } = buildService();
+
+ const alive = await service.checkSessionsAlive({ files: [staleFile('f5')], apiKey: 'k' });
+
+ expect(alive.has('f5')).toBe(false);
+ });
+ });
+});
diff --git a/packages/api/src/files/provision/service.ts b/packages/api/src/files/provision/service.ts
new file mode 100644
index 0000000000..c5549bf90e
--- /dev/null
+++ b/packages/api/src/files/provision/service.ts
@@ -0,0 +1,597 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { pipeline } from 'node:stream/promises';
+import { logger } from '@librechat/data-schemas';
+import { getCodeBaseURL } from '@librechat/agents';
+import {
+ FileSources,
+ getCodeEnvRefs,
+ mergeCodeEnvRef,
+ resolveSandboxFilename,
+} from 'librechat-data-provider';
+import type { CodeEnvRef, CodeEnvRefMap, TFile } from 'librechat-data-provider';
+import type { Readable } from 'node:stream';
+import type { CodeEnvIdentity } from '~/files/code/identity';
+import type { ServerRequest } from '~/types';
+import {
+ logAxiosError,
+ createAxiosInstance,
+ codeServerHttpAgent,
+ codeServerHttpsAgent,
+} from '~/utils';
+import { buildCodeEnvIdentityParams } from '~/files/code/identity';
+import { getCodeApiAuthHeaders } from '~/auth/codeapi';
+import { resolveDownloadPath } from '~/storage/path';
+
+/** Storage strategy lookup, injected so this module stays free of the api workspace. */
+export interface ProvisionDeps {
+ getStrategyFunctions: (source: string) => {
+ getDownloadStream?: (
+ req: ServerRequest,
+ filepath: string,
+ options?: { signal?: AbortSignal },
+ ) => Promise<Readable>;
+ handleFileUpload?: (params: Record<string, unknown>) => Promise<{
+ storage_session_id: string;
+ file_id: string;
+ }>;
+ };
+ uploadVectors: (params: {
+ req: ServerRequest;
+ file: { path: string; originalname: string; mimetype?: string; size?: number };
+ file_id: string;
+ entity_id?: string;
+ signal?: AbortSignal;
+ }) => Promise<{ embedded?: boolean } | undefined>;
+ loadAuthValues: (params: {
+ userId: string;
+ authFields: string[];
+ throwError?: boolean;
+ }) => Promise<Record<string, string | undefined>>;
+}
+
+/** The Code API deployment an agent resolved for this turn. */
+export interface CodeExecutionRoute {
+ baseUrl?: string;
+ executionProfile?: 'default' | 'stateful';
+ executionRouteKey?: string;
+}
+
+/** Deferred database write produced by a successful provisioning call. */
+export interface ProvisionFileUpdate {
+ file_id: string;
+ metadata?: Record<string, unknown>;
+ embedded?: boolean;
+}
+
+/** One route pointer, written on its own so concurrent routes do not overwrite each other. */
+export interface CodeEnvRefUpdate {
+ file_id: string;
+ routeKey: string;
+ ref: CodeEnvRef;
+ legacyRef?: CodeEnvRef;
+}
+
+/** Merged code-environment pointers written after a successful sandbox upload. */
+export interface CodeEnvReferenceSetResult {
+ codeEnvRef?: CodeEnvRef;
+ codeEnvRefs?: CodeEnvRefMap;
+}
+
+export interface ProvisionService {
+ loadCodeApiKey: (userId: string) => Promise<string | undefined>;
+ provisionToCodeEnv: (params: {
+ req: ServerRequest;
+ file: TFile;
+ entity_id?: string;
+ route?: CodeExecutionRoute;
+ sandboxFilename?: string;
+ signal?: AbortSignal;
+ }) => Promise<{
+ referenceSet: CodeEnvReferenceSetResult;
+ refUpdate: CodeEnvRefUpdate;
+ /** The name the sandbox stored it under, which a converted image renames. */
+ sandboxFilename: string;
+ }>;
+ provisionToVectorDB: (params: {
+ req: ServerRequest;
+ file: TFile;
+ entity_id?: string;
+ existingStream?: Readable;
+ signal?: AbortSignal;
+ }) => Promise<{ embedded: boolean; fileUpdate: ProvisionFileUpdate | null }>;
+ checkCodeEnvFileAlive: (params: {
+ file: TFile;
+ apiKey?: string;
+ req?: ServerRequest;
+ }) => Promise<boolean>;
+ checkSessionsAlive: (params: {
+ files: TFile[];
+ apiKey?: string;
+ req?: ServerRequest;
+ staleSafeWindowMs?: number;
+ /** Deployment this turn runs on. Refs are deployment-local, so a ref is probed
+ * against the Code API that issued it, not against the default one. */
+ baseURL?: string;
+ routeKey?: string;
+ }) => Promise<Set<string>>;
+}
+
+/**
+ * Provisioning service for the code environment and vector store.
+ *
+ * Storage strategies, vector upload, and credential lookup live in the api workspace,
+ * so they are injected rather than imported: that keeps the logic here, where it is
+ * type checked, and leaves only wiring on the other side.
+ */
+/** The reference a given deployment issued, across both the per-route map and the
+ * legacy single pointer. A ref from another deployment answers for another Code API. */
+const codeEnvRefForRoute = (file: TFile, routeKey: string): CodeEnvRef | undefined =>
+ getCodeEnvRefs(file.metadata).find(([key]) => key === routeKey)?.[1];
+
+export function createProvisionService({
+ getStrategyFunctions,
+ uploadVectors,
+ loadAuthValues,
+}: ProvisionDeps): ProvisionService {
+ /* Created on first use rather than at module load: this module is pulled into the
+ * OpenAI-compatible controllers, whose tests partially mock @librechat/api, and a
+ * load-time call would throw before any provisioning is even requested. */
+ let axiosInstance;
+ const getAxios = () => (axiosInstance ??= createAxiosInstance());
+
+ /* Sources whose `getDownloadStream` takes `(req, filepath)` and returns a readable.
+ * Others diverge: `openai` takes `(file_id, client)` and `execute_code` takes
+ * `(fileIdentifier, identity, req)` returning an Axios response, so calling them
+ * through this contract fails. An allowlist keeps an unfamiliar source skipped
+ * rather than mis-invoked. */
+ const STORAGE_STREAM_SOURCES = new Set([
+ FileSources.local,
+ FileSources.s3,
+ FileSources.cloudfront,
+ FileSources.azure_blob,
+ FileSources.firebase,
+ ]);
+
+ /** Resolves a storage download stream, or null when the source uses a different contract. */
+ async function getStorageStream(
+ file: TFile,
+ req: ServerRequest,
+ signal?: AbortSignal,
+ ): Promise<Readable | null> {
+ if (file.source == null || !STORAGE_STREAM_SOURCES.has(file.source)) {
+ logger.warn(
+ `[provision] Cannot stream "${file.filename}" (${file.file_id}) from source "${file.source}": unsupported download contract`,
+ );
+ return null;
+ }
+ const { getDownloadStream } = getStrategyFunctions(file.source as string);
+ if (!getDownloadStream) {
+ return null;
+ }
+ signal?.throwIfAborted();
+ const stream = await getDownloadStream(req, resolveDownloadPath(file), { signal });
+ if (signal?.aborted) {
+ stream.destroy(signal.reason instanceof Error ? signal.reason : undefined);
+ signal.throwIfAborted();
+ }
+ return stream;
+ }
+
+ /** Composes code-API auth: legacy X-API-Key when configured, plus JWT bearer when enabled. */
+ async function buildCodeApiHeaders({
+ apiKey,
+ req,
+ }: {
+ apiKey?: string;
+ req?: ServerRequest;
+ }): Promise<Record<string, string>> {
+ return {
+ 'User-Agent': 'LibreChat/1.0',
+ ...(apiKey ? { 'X-API-Key': apiKey } : {}),
+ ...(await getCodeApiAuthHeaders(req)),
+ };
+ }
+
+ /** Env var holding the code-execution API key (symmetric with LIBRECHAT_CODE_BASEURL). */
+ const CODE_API_KEY_FIELD = 'LIBRECHAT_CODE_API_KEY';
+
+ /**
+ * Loads the code-execution API key for a user. Call once per request and pass the
+ * result to checkSessionsAlive to avoid redundant lookups. Returns undefined when
+ * no key is configured; JWT-mode code auth can still authorize provisioning.
+ *
+ * @param {string} userId
+ * @returns {Promise<string | undefined>} The code-execution API key, if configured
+ */
+ async function loadCodeApiKey(userId: string): Promise<string | undefined> {
+ const result = await loadAuthValues({
+ userId,
+ authFields: [CODE_API_KEY_FIELD],
+ throwError: false,
+ });
+ return result[CODE_API_KEY_FIELD];
+ }
+
+ /**
+ * Provisions a file to the code execution environment.
+ * Gets a read stream from our storage and uploads to the code env, persisting
+ * the resulting `codeEnvRef` so downstream readers (primeFiles, code env
+ * categorization) can locate the sandbox copy on subsequent turns.
+ *
+ * @param {object} params
+ * @param {object} params.req - Express request object (needs req.user.id)
+ * @param {import('librechat-data-provider').TFile} params.file - The file record from DB
+ * @param {string} [params.entity_id] - Optional entity ID (agent_id); when present the ref
+ * is scoped to `kind: 'agent'`, otherwise it falls back to `kind: 'user'`.
+ * @returns {Promise<{ referenceSet: { codeEnvRef: object, codeEnvRefs: object }, fileUpdate: object }>}
+ * Merged pointers plus the deferred DB update
+ */
+ async function provisionToCodeEnv({
+ req,
+ file,
+ entity_id,
+ route,
+ sandboxFilename: requestedSandboxFilename,
+ signal,
+ }: {
+ req: ServerRequest;
+ file: TFile;
+ entity_id?: string;
+ route?: CodeExecutionRoute;
+ sandboxFilename?: string;
+ signal?: AbortSignal;
+ }) {
+ signal?.throwIfAborted();
+ const { handleFileUpload: uploadCodeEnvFile } = getStrategyFunctions(FileSources.execute_code);
+ if (!uploadCodeEnvFile) {
+ throw new Error('Code environment upload strategy is unavailable');
+ }
+ const stream = await getStorageStream(file, req, signal);
+ signal?.throwIfAborted();
+ if (!stream) {
+ throw new Error(
+ `Cannot provision file "${file.filename}" to code env: storage source "${file.source}" does not support download streams`,
+ );
+ }
+
+ const kind: 'agent' | 'user' = entity_id ? 'agent' : 'user';
+ const id = entity_id ?? (req.user?.id as string);
+
+ /* Upload to the deployment this agent actually resolved. Hard-coding the default
+ * meant a stateful agent's file was uploaded to the wrong Code API and then had to
+ * be re-uploaded by priming, and a deployment whose only healthy Code API is the
+ * configured stateful one could not provision at all. */
+ const executionProfile = route?.executionProfile ?? 'default';
+ const sandboxFilename =
+ requestedSandboxFilename ?? resolveSandboxFilename(file.filename, file.type);
+ const uploaded = await uploadCodeEnvFile({
+ req,
+ stream,
+ filename: sandboxFilename,
+ kind,
+ id,
+ ...(route?.baseUrl ? { codeApiBaseUrl: route.baseUrl } : {}),
+ executionProfile,
+ signal,
+ });
+ signal?.throwIfAborted();
+
+ /* Merge rather than overwrite: the eager upload path persists the same shape via
+ * mergeCodeEnvRef, so both the legacy pointer and the route-keyed map stay in sync
+ * and pointers for other Code API routes survive re-provisioning. */
+ const ref: CodeEnvRef = {
+ kind,
+ id,
+ storage_session_id: uploaded.storage_session_id,
+ file_id: uploaded.file_id,
+ executionProfile,
+ ...(route?.executionRouteKey ? { executionRouteKey: route.executionRouteKey } : {}),
+ provisionedAt: Date.now(),
+ };
+ const referenceSet = mergeCodeEnvRef(file.metadata, ref);
+ const routeKey = route?.executionRouteKey ?? executionProfile;
+
+ logger.debug(
+ `[provisionToCodeEnv] Provisioned file "${file.filename}" (${file.file_id}) to code env`,
+ );
+
+ return {
+ referenceSet,
+ sandboxFilename,
+ refUpdate: {
+ file_id: file.file_id,
+ routeKey,
+ ref,
+ ...(referenceSet.codeEnvRef ? { legacyRef: referenceSet.codeEnvRef } : {}),
+ },
+ };
+ }
+
+ /**
+ * Provisions a file to the vector DB for file_search/RAG.
+ * Gets the file from our storage and uploads vectors/embeddings.
+ *
+ * @param {object} params
+ * @param {object} params.req - Express request object
+ * @param {import('librechat-data-provider').TFile} params.file - The file record from DB
+ * @param {string} [params.entity_id] - Optional entity ID (agent_id)
+ * @param {import('stream').Readable} [params.existingStream] - Pre-fetched download stream (avoids duplicate storage fetch)
+ * @returns {Promise<{ embedded: boolean, fileUpdate: object | null }>} Result with deferred DB update
+ */
+ async function provisionToVectorDB({
+ req,
+ file,
+ entity_id,
+ existingStream,
+ signal,
+ }: {
+ req: ServerRequest;
+ file: TFile;
+ entity_id?: string;
+ existingStream?: Readable;
+ signal?: AbortSignal;
+ }): Promise<{ embedded: boolean; fileUpdate: { file_id: string; embedded?: boolean } | null }> {
+ /* Unique per attempt: two concurrent requests provisioning the same file_id would
+ * otherwise share one path, and the first to finish unlinks it while the second is
+ * still streaming into uploadVectors. */
+ const tmpPath = path.join(
+ os.tmpdir(),
+ `provision-${file.file_id}-${randomUUID()}${path.extname(file.filename)}`,
+ );
+
+ try {
+ signal?.throwIfAborted();
+ let stream: Readable | undefined = existingStream;
+ if (!stream) {
+ stream = (await getStorageStream(file, req, signal)) ?? undefined;
+ if (!stream) {
+ throw new Error(
+ `Cannot provision file "${file.filename}" to vector DB: storage source "${file.source}" does not support download streams`,
+ );
+ }
+ }
+
+ // uploadVectors expects a file-like object with a `path` property for fs.createReadStream.
+ // Since we're provisioning from storage (not a multer upload), we stream to a temp file first.
+ await pipeline(stream, fs.createWriteStream(tmpPath), { signal });
+
+ const tempFile = {
+ path: tmpPath,
+ originalname: file.filename,
+ mimetype: file.type,
+ size: file.bytes,
+ };
+
+ const embeddingResult = await uploadVectors({
+ req,
+ file: tempFile,
+ file_id: file.file_id,
+ entity_id,
+ signal,
+ });
+ signal?.throwIfAborted();
+
+ const embedded = embeddingResult?.embedded ?? false;
+
+ logger.debug(
+ `[provisionToVectorDB] Provisioned file "${file.filename}" (${file.file_id}) to vector DB, embedded=${embedded}`,
+ );
+
+ return {
+ embedded,
+ fileUpdate: embedded ? { file_id: file.file_id, embedded } : null,
+ };
+ } finally {
+ try {
+ fs.unlinkSync(tmpPath);
+ } catch {
+ // Ignore cleanup errors
+ }
+ }
+ }
+
+ /**
+ * Check if a single code env file is still alive by querying its session.
+ *
+ * @param {object} params
+ * @param {import('librechat-data-provider').TFile} params.file - File with metadata.codeEnvRef
+ * @param {string} [params.apiKey] - Legacy CODE_API_KEY, when configured
+ * @param {object} [params.req] - Request used to mint JWT code auth, when enabled
+ * @returns {Promise<boolean>} true if the file is still accessible in the code env
+ */
+ async function checkCodeEnvFileAlive({
+ file,
+ apiKey,
+ req,
+ }: {
+ file: TFile;
+ apiKey?: string;
+ req?: ServerRequest;
+ }): Promise<boolean> {
+ const ref = file.metadata?.codeEnvRef;
+ if (!ref?.storage_session_id || !ref?.file_id) {
+ return false;
+ }
+
+ try {
+ const baseURL = getCodeBaseURL();
+ const response = await getAxios()({
+ method: 'get',
+ url: `${baseURL}/files/${ref.storage_session_id}`,
+ params: { detail: 'summary' },
+ headers: await buildCodeApiHeaders({ apiKey, req }),
+ httpAgent: codeServerHttpAgent,
+ httpsAgent: codeServerHttpsAgent,
+ timeout: 5000,
+ });
+
+ const found = (response.data as Array<{ fileId?: string }> | undefined)?.some(
+ (f) => f.fileId === ref.file_id,
+ );
+ return !!found;
+ } catch (error) {
+ logAxiosError({
+ message: `[checkCodeEnvFileAlive] Error checking file "${file.filename}": ${(error as Error).message}`,
+ error,
+ });
+ return false;
+ }
+ }
+
+ /**
+ * Batch-check code env file liveness by `storage_session_id`.
+ * Groups files by session, makes one API call per session.
+ *
+ * @param {object} params
+ * @param {import('librechat-data-provider').TFile[]} params.files - Files with metadata.codeEnvRef
+ * @param {string} [params.apiKey] - Pre-loaded legacy CODE_API_KEY, when configured
+ * @param {object} [params.req] - Request used to mint JWT code auth, when enabled
+ * @param {number} [params.staleSafeWindowMs=21600000] - Skip the live check if the file was provisioned to the code env within this window (default 6h)
+ * @returns {Promise<Set<string>>} file_ids that are not known to be expired: confirmed
+ * alive, within the safe window, or unverifiable because the probe itself failed
+ */
+ /** A definitive not-found from the Code API, as opposed to a transient probe failure. */
+ function isSessionNotFound(error: unknown): boolean {
+ const { response, status } = (error ?? {}) as {
+ response?: { status?: number };
+ status?: number;
+ };
+ return (response?.status ?? status) === 404;
+ }
+
+ async function checkSessionsAlive({
+ files,
+ apiKey,
+ req,
+ staleSafeWindowMs = 6 * 60 * 60 * 1000,
+ baseURL: routeBaseURL,
+ routeKey,
+ }: {
+ files: TFile[];
+ apiKey?: string;
+ req?: ServerRequest;
+ staleSafeWindowMs?: number;
+ baseURL?: string;
+ routeKey?: string;
+ }): Promise<Set<string>> {
+ const aliveFileIds = new Set<string>();
+ const now = Date.now();
+
+ /* Group by session AND resource identity, skipping recently-updated files. Codeapi
+ * reconstructs the session key from kind and id for shared kinds, so a probe that
+ * omits them asks about the requester's own bucket and 404s on a live agent
+ * session, which reads here as expiry and forces a needless re-upload. */
+ const sessionGroups = new Map<
+ string,
+ {
+ session_id: string;
+ identity: CodeEnvIdentity;
+ entries: Array<{ file_id: string; remoteFileId: string }>;
+ }
+ >();
+
+ for (const file of files) {
+ const ref = routeKey != null ? codeEnvRefForRoute(file, routeKey) : file.metadata?.codeEnvRef;
+ if (!ref?.storage_session_id || !ref?.file_id) {
+ continue;
+ }
+
+ // Trust only the code-env upload timestamp, not `updatedAt` (bumped by usage,
+ // e.g. updateFilesUsage on resend); a usage-touched file may still have an
+ // expired sandbox session. Refs without a marker fall through to a live check.
+ const provisionedAt = ref.provisionedAt ?? 0;
+ if (provisionedAt && now - provisionedAt < staleSafeWindowMs) {
+ aliveFileIds.add(file.file_id);
+ continue;
+ }
+
+ const identity: CodeEnvIdentity = {
+ kind: ref.kind,
+ id: ref.id,
+ ...(ref.kind === 'skill' ? { version: ref.version } : {}),
+ };
+ const groupKey = `${ref.storage_session_id}\0${identity.kind}\0${identity.id}\0${
+ identity.version ?? ''
+ }`;
+ let group = sessionGroups.get(groupKey);
+ if (!group) {
+ group = { session_id: ref.storage_session_id, identity, entries: [] };
+ sessionGroups.set(groupKey, group);
+ }
+ group.entries.push({ file_id: file.file_id, remoteFileId: ref.file_id });
+ }
+
+ // One API call per session (in parallel)
+ const baseURL = routeBaseURL ?? getCodeBaseURL();
+ /* Minting can fail on its own, for example when the request carries no tenant
+ * context. That is an unverifiable probe, not an expired file, so it is handled
+ * like any other probe failure: every ref stays alive rather than the rejection
+ * propagating out and aborting initialization for the whole turn. */
+ let headers;
+ try {
+ headers = await buildCodeApiHeaders({ apiKey, req });
+ } catch (error) {
+ logger.warn(
+ `[checkSessionsAlive] Could not build Code API auth headers; treating ${files.length} reference(s) as unverified: ${(error as Error).message}`,
+ );
+ for (const file of files) {
+ if (file?.file_id) {
+ aliveFileIds.add(file.file_id);
+ }
+ }
+ return aliveFileIds;
+ }
+ const sessionChecks = Array.from(sessionGroups.values()).map(
+ async ({ session_id, identity, entries: fileEntries }) => {
+ try {
+ const response = await getAxios()({
+ method: 'get',
+ url: `${baseURL}/files/${session_id}`,
+ params: { detail: 'summary', ...buildCodeEnvIdentityParams(identity) },
+ headers,
+ httpAgent: codeServerHttpAgent,
+ httpsAgent: codeServerHttpsAgent,
+ timeout: 5000,
+ });
+
+ const remoteFiles = response.data ?? [];
+ for (const { file_id, remoteFileId } of fileEntries) {
+ if (
+ (remoteFiles as Array<{ fileId?: string }>).some((f) => f.fileId === remoteFileId)
+ ) {
+ aliveFileIds.add(file_id);
+ }
+ }
+ } catch (error) {
+ logAxiosError({
+ message: `[checkSessionsAlive] Error checking session "${session_id}": ${(error as Error).message}`,
+ error,
+ });
+ /* A 404 is the Code API answering that the session is gone, so its files are
+ * expired and a replacement upload should be queued. Every other failure means
+ * unknown: a timeout or 5xx would otherwise clear a live ref and force a
+ * re-upload that the same outage will likely fail too. */
+ if (isSessionNotFound(error)) {
+ return;
+ }
+ for (const { file_id } of fileEntries) {
+ aliveFileIds.add(file_id);
+ }
+ }
+ },
+ );
+
+ await Promise.allSettled(sessionChecks);
+ return aliveFileIds;
+ }
+ return {
+ loadCodeApiKey,
+ provisionToCodeEnv,
+ provisionToVectorDB,
+ checkCodeEnvFileAlive,
+ checkSessionsAlive,
+ };
+}
diff --git a/packages/api/src/files/upload/diagnostics.spec.ts b/packages/api/src/files/upload/diagnostics.spec.ts
new file mode 100644
index 0000000000..51e2b5e35c
--- /dev/null
+++ b/packages/api/src/files/upload/diagnostics.spec.ts
@@ -0,0 +1,52 @@
+import { logger } from '@librechat/data-schemas';
+import { warnOnUnreachableDeliveryPaths } from './diagnostics';
+
+jest.mock('@librechat/data-schemas', () => ({
+ logger: { warn: jest.fn() },
+}));
+
+const warned = (): string[] => (logger.warn as jest.Mock).mock.calls.map(([msg]) => String(msg));
+
+describe('warnOnUnreachableDeliveryPaths', () => {
+ beforeEach(() => {
+ (logger.warn as jest.Mock).mockClear();
+ });
+
+ it('warns for a fallback that routes everything off the model path', () => {
+ /* The fallback covers every type no override names, so leaving it unannounced hides
+ * a wider change than any single override could make. */
+ warnOnUnreachableDeliveryPaths({
+ fileConfig: { defaultLLMDeliveryPath: { fallback: 'none' } },
+ });
+
+ expect(warned()).toEqual([expect.stringContaining('fallback is set to "none"')]);
+ });
+
+ it('warns for an override that routes one type off the model path', () => {
+ warnOnUnreachableDeliveryPaths({
+ fileConfig: { defaultLLMDeliveryPath: { overrides: { 'application/pdf': 'none' } } },
+ });
+
+ expect(warned()).toEqual([expect.stringContaining('"application/pdf" is set to "none"')]);
+ });
+
+ it('names the endpoint a warning came from', () => {
+ warnOnUnreachableDeliveryPaths({
+ fileConfig: {
+ endpoints: { openAI: { defaultLLMDeliveryPath: { fallback: 'none' } } },
+ },
+ });
+
+ expect(warned()).toEqual([expect.stringContaining('for "openAI"')]);
+ });
+
+ it('stays quiet when every type still reaches the model', () => {
+ warnOnUnreachableDeliveryPaths({
+ fileConfig: {
+ defaultLLMDeliveryPath: { fallback: 'text', overrides: { 'image/*': 'provider' } },
+ },
+ });
+
+ expect(warned()).toEqual([]);
+ });
+});
diff --git a/packages/api/src/files/upload/diagnostics.ts b/packages/api/src/files/upload/diagnostics.ts
new file mode 100644
index 0000000000..dbdaf1f21c
--- /dev/null
+++ b/packages/api/src/files/upload/diagnostics.ts
@@ -0,0 +1,44 @@
+import { logger } from '@librechat/data-schemas';
+import type { TDefaultLLMDeliveryPathConfig } from 'librechat-data-provider';
+import type { AppConfig } from '@librechat/data-schemas';
+
+/**
+ * Warns about delivery settings that keep a file off the model path. Routing a type to
+ * `none` is a legitimate choice, but a silent one: uploads still succeed and only a file
+ * tool can reach them, so an operator who set it by accident has nothing to notice. A
+ * `none` fallback is the louder case, since it covers every type no override names.
+ */
+export function warnOnUnreachableDeliveryPaths(appConfig?: Pick<AppConfig, 'fileConfig'>): void {
+ const warnForConfig = (
+ config: TDefaultLLMDeliveryPathConfig | undefined,
+ scope?: string,
+ ): void => {
+ if (!config) {
+ return;
+ }
+ const where = scope ? ` for "${scope}"` : '';
+ if (config.fallback === 'none') {
+ logger.warn(
+ `[Config] defaultLLMDeliveryPath${where}: fallback is set to "none" — every type without an override will only be accessible through tool provisioning`,
+ );
+ }
+ for (const [mimeType, destination] of Object.entries(config.overrides ?? {})) {
+ if (destination !== 'none') {
+ continue;
+ }
+ logger.warn(
+ `[Config] defaultLLMDeliveryPath${where}: "${mimeType}" is set to "none" — files of this type will only be accessible through tool provisioning`,
+ );
+ }
+ };
+
+ warnForConfig(appConfig?.fileConfig?.defaultLLMDeliveryPath);
+
+ const endpoints = appConfig?.fileConfig?.endpoints;
+ if (!endpoints) {
+ return;
+ }
+ for (const [endpoint, config] of Object.entries(endpoints)) {
+ warnForConfig(config?.defaultLLMDeliveryPath, endpoint);
+ }
+}
diff --git a/packages/api/src/files/upload/routing.spec.ts b/packages/api/src/files/upload/routing.spec.ts
new file mode 100644
index 0000000000..2d8de0dc8a
--- /dev/null
+++ b/packages/api/src/files/upload/routing.spec.ts
@@ -0,0 +1,106 @@
+import { EModelEndpoint } from 'librechat-data-provider';
+import type { ServerRequest } from '~/types';
+import { resolveUploadEndpoint, resolveEffectiveToolResource } from './routing';
+
+describe('resolveUploadEndpoint', () => {
+ const req = { user: { id: 'user-1' } } as unknown as ServerRequest;
+
+ beforeEach(() => {
+ delete (req as unknown as { _uploadAgentCache?: unknown })._uploadAgentCache;
+ });
+
+ it('reads the agent so its provider governs an agent upload', async () => {
+ const getAgent = jest.fn().mockResolvedValue({ provider: 'Custom Provider' });
+
+ const endpoint = await resolveUploadEndpoint({
+ req,
+ metadata: { endpoint: EModelEndpoint.agents, agent_id: 'agent_saved01' },
+ getAgent,
+ });
+
+ expect(endpoint).toBe('Custom Provider');
+ expect(getAgent).toHaveBeenCalled();
+ });
+
+ it('ignores an agent id on an assistants upload', async () => {
+ /* Assistants have their own pipeline and skip the agent authorization gate, so
+ * resolving the named agent here would let its provider shape the validation errors
+ * an unauthorized caller sees. */
+ const getAgent = jest.fn().mockResolvedValue({ provider: 'Custom Provider' });
+
+ const endpoint = await resolveUploadEndpoint({
+ req,
+ metadata: { endpoint: EModelEndpoint.assistants, agent_id: 'agent_victim01' },
+ getAgent,
+ });
+
+ expect(endpoint).toBe(EModelEndpoint.assistants);
+ expect(getAgent).not.toHaveBeenCalled();
+ });
+
+ it('leaves an upload naming no agent alone', async () => {
+ const getAgent = jest.fn();
+
+ const endpoint = await resolveUploadEndpoint({
+ req,
+ metadata: { endpoint: EModelEndpoint.openAI },
+ getAgent,
+ });
+
+ expect(endpoint).toBe(EModelEndpoint.openAI);
+ expect(getAgent).not.toHaveBeenCalled();
+ });
+});
+
+describe('resolveEffectiveToolResource Responses handling', () => {
+ const makeReq = () =>
+ ({
+ user: { id: 'user-1' },
+ file: { mimetype: 'application/pdf' },
+ config: { fileConfig: undefined },
+ }) as unknown as ServerRequest;
+
+ it('treats the multipart string form of the Responses flag as set', async () => {
+ /* Form data has no booleans, so the flag arrives as "true" and a strict comparison
+ * would route an Azure PDF to extracted text on a deployment that carries it. */
+ const withString = await resolveEffectiveToolResource({
+ req: makeReq(),
+ metadata: { endpoint: 'azureOpenAI', useResponsesApi: 'true' },
+ getAgent: jest.fn(),
+ });
+ const withoutFlag = await resolveEffectiveToolResource({
+ req: makeReq(),
+ metadata: { endpoint: 'azureOpenAI' },
+ getAgent: jest.fn(),
+ });
+
+ expect(withString).toBeUndefined();
+ expect(withoutFlag).toBe('context');
+ });
+
+ it('does not classify audio as a context upload when no STT provider is usable', async () => {
+ /* Transcription needs exactly one non-empty provider block. A schema holding only
+ * allowedAddresses reports STT present while the service refuses it, so calling this
+ * a context upload promises a transcript the preflight then waits on. */
+ const makeAudioReq = (stt: Record<string, unknown>) =>
+ ({
+ user: { id: 'user-1' },
+ file: { mimetype: 'audio/mpeg' },
+ config: { fileConfig: undefined, speech: { stt } },
+ }) as unknown as ServerRequest;
+
+ const unusable = await resolveEffectiveToolResource({
+ req: makeAudioReq({ allowedAddresses: ['127.0.0.1'] }),
+ metadata: { endpoint: EModelEndpoint.openAI },
+ getAgent: jest.fn(),
+ });
+ const usable = await resolveEffectiveToolResource({
+ req: makeAudioReq({ openai: { apiKey: 'sk-test' } }),
+ metadata: { endpoint: EModelEndpoint.openAI },
+ getAgent: jest.fn(),
+ });
+
+ expect(unusable).not.toBe('context');
+ expect(usable).toBe('context');
+ });
+});
diff --git a/packages/api/src/files/upload/routing.ts b/packages/api/src/files/upload/routing.ts
new file mode 100644
index 0000000000..31f571cbae
--- /dev/null
+++ b/packages/api/src/files/upload/routing.ts
@@ -0,0 +1,125 @@
+import {
+ EToolResources,
+ mergeFileConfig,
+ isAssistantsEndpoint,
+ isResponsesApiUpload,
+ getEndpointFileConfig,
+ resolveUploadLLMDeliveryPath,
+ isSpeechProviderConfigured,
+} from 'librechat-data-provider';
+import type { ServerRequest } from '~/types';
+
+/** The subset of an agent record this module reads. */
+export interface UploadAgent {
+ provider?: string;
+}
+
+/** The subset of upload metadata that determines where a file is routed. */
+export interface UploadMetadata {
+ endpoint?: string;
+ agent_id?: string;
+ tool_resource?: string | null;
+ /** Azure carries native documents only through the Responses API. Multipart form data
+ * carries it as a string, so it arrives as "true" rather than a boolean. */
+ useResponsesApi?: boolean | string;
+}
+
+/** The uploaded file fields routing depends on. */
+export interface UploadFile {
+ mimetype: string;
+}
+
+export type GetUploadAgent = (params: { id: string }) => Promise<UploadAgent | null>;
+
+/** Request-scoped cache of the upload's agent, keyed by agent id. */
+interface UploadAgentCarrier {
+ _uploadAgentCache?: Map<string, Promise<UploadAgent | null>>;
+}
+
+/**
+ * Reads the upload's agent once per request. Routing, authorization and processing each
+ * need it, and this runs before any bytes are handled, so repeating the read adds a round
+ * trip to every upload.
+ */
+export function resolveUploadAgent(
+ req: ServerRequest,
+ agentId: string | undefined,
+ getAgent: GetUploadAgent,
+): Promise<UploadAgent | null> {
+ if (!agentId) {
+ return Promise.resolve(null);
+ }
+ const carrier = req as ServerRequest & UploadAgentCarrier;
+ if (!carrier._uploadAgentCache) {
+ carrier._uploadAgentCache = new Map();
+ }
+ const cached = carrier._uploadAgentCache.get(agentId);
+ if (cached) {
+ return cached;
+ }
+ const pending = getAgent({ id: agentId });
+ carrier._uploadAgentCache.set(agentId, pending);
+ return pending;
+}
+
+/**
+ * Agent uploads carry endpoint `agents`; the agent's own provider governs both the file
+ * configuration used for validation and the delivery-path routing.
+ *
+ * An assistants upload has its own pipeline and never files anything against an agent, so
+ * an `agent_id` on one names a record the request has no business reading: the agent
+ * authorization gate does not run for assistants, and the provider it resolved would
+ * still shape the validation errors the caller sees.
+ */
+export async function resolveUploadEndpoint({
+ req,
+ metadata,
+ getAgent,
+}: {
+ req: ServerRequest;
+ metadata: UploadMetadata;
+ getAgent: GetUploadAgent;
+}): Promise<string | undefined> {
+ if (!metadata.agent_id || isAssistantsEndpoint(metadata.endpoint)) {
+ return metadata.endpoint;
+ }
+ const agent = await resolveUploadAgent(req, metadata.agent_id, getAgent);
+ return agent?.provider || metadata.endpoint;
+}
+
+/**
+ * The destination this upload will actually be processed under. A unified upload names no
+ * tool resource but is promoted to a text context when routing sends it there, and both
+ * the content preflight and the image route have to agree with the processing path about
+ * where the file is going.
+ */
+export async function resolveEffectiveToolResource({
+ req,
+ metadata,
+ getAgent,
+}: {
+ req: ServerRequest;
+ metadata: UploadMetadata;
+ getAgent: GetUploadAgent;
+}): Promise<string | undefined> {
+ if (metadata.tool_resource === EToolResources.ocr) {
+ return EToolResources.context;
+ }
+ if (metadata.tool_resource) {
+ return metadata.tool_resource;
+ }
+
+ const fileConfig = mergeFileConfig(req.config?.fileConfig);
+ const endpoint = await resolveUploadEndpoint({ req, metadata, getAgent });
+ const endpointConfig = getEndpointFileConfig({ fileConfig, endpoint });
+ const path = resolveUploadLLMDeliveryPath({
+ toolResource: metadata.tool_resource,
+ mimeType: (req.file as UploadFile).mimetype,
+ endpointConfig,
+ fileConfig,
+ endpoint,
+ useResponsesApi: isResponsesApiUpload(metadata.useResponsesApi),
+ sttConfigured: isSpeechProviderConfigured(req.config?.speech?.stt),
+ });
+ return path === 'text' ? EToolResources.context : undefined;
+}
diff --git a/packages/api/src/protection/files.spec.ts b/packages/api/src/protection/files.spec.ts
index 9dd6cf322e..c700e05e38 100644
--- a/packages/api/src/protection/files.spec.ts
+++ b/packages/api/src/protection/files.spec.ts
@@ -9,6 +9,7 @@ import {
getBlockedOpaqueFileField,
getBlockedUninspectableFileField,
getBlockedUninspectableSkillFileField,
+ getCanonicalFileInspectionCoverage,
getUploadExtractedTextPlan,
hasActiveFileFieldPolicy,
hasActiveFilePolicy,
@@ -65,6 +66,10 @@ describe('file content inspection policy', () => {
}),
).toBe(false);
+ /* An explicitly narrowed text list names types the built-in parser does not handle.
+ * Processing sends those to RAG with native fallback off and passes the result
+ * through extractInspectableFileText, so the extraction step exists and fail-closing
+ * here would reject an upload that does get inspected. */
const configuredNonDocumentText = mergeFileConfig({
ocr: { supportedMimeTypes: [] },
text: { supportedMimeTypes: ['application/x-rag-document'] },
@@ -76,6 +81,15 @@ describe('file content inspection policy', () => {
fileConfig: configuredNonDocumentText,
ragConfigured: true,
}),
+ ).toBe(true);
+ /* Only when RAG is actually configured: without it nothing extracts the type. */
+ expect(
+ canInspectUploadExtractedTextAfterProcessing({
+ ...baseInput,
+ mimeType: 'application/x-rag-document',
+ fileConfig: configuredNonDocumentText,
+ ragConfigured: false,
+ }),
).toBe(false);
const defaultExtraction = mergeFileConfig(undefined);
@@ -180,6 +194,38 @@ describe('file content inspection policy', () => {
).toBe(false);
});
+ it('treats a text-delivery audio file as carrying its own transcript', () => {
+ const coverage = getCanonicalFileInspectionCoverage({
+ type: 'audio/mpeg',
+ source: 'local',
+ llmDeliveryPath: 'text',
+ text: 'spoken words',
+ });
+
+ expect(coverage.transcript).toBe('spoken words');
+ expect(coverage.textProvidesTranscript).toBe(true);
+ });
+
+ it('still requires provenance before treating audio text as a transcript', () => {
+ const coverage = getCanonicalFileInspectionCoverage({
+ type: 'audio/mpeg',
+ source: 'local',
+ text: 'spoken words',
+ });
+
+ expect(coverage.transcript).toBeUndefined();
+ });
+
+ it('keeps recognizing the legacy text source as provenance', () => {
+ const coverage = getCanonicalFileInspectionCoverage({
+ type: 'audio/mpeg',
+ source: 'text',
+ text: 'spoken words',
+ });
+
+ expect(coverage.transcript).toBe('spoken words');
+ });
+
it('rejects applicable audio when no downstream transcript inspection is available', () => {
const filters = {
files: { pii: { fields: ['transcript'], uninspectable: 'block' } },
diff --git a/packages/api/src/protection/files.ts b/packages/api/src/protection/files.ts
index c1ffb014f2..6a20f35914 100644
--- a/packages/api/src/protection/files.ts
+++ b/packages/api/src/protection/files.ts
@@ -55,6 +55,9 @@ export interface CanonicalFileInspectionFile {
readonly preview?: string;
readonly type?: string;
readonly source?: string;
+ /** Unified uploads persist their extracted text alongside the backing storage
+ * source, so delivery path carries the provenance `source: 'text'` used to. */
+ readonly llmDeliveryPath?: string | null;
readonly content?: string | null;
readonly extractedText?: string | null;
readonly text?: string | null;
@@ -324,12 +327,10 @@ export function getUploadExtractedTextPlan(
) {
return UPLOAD_EXTRACTED_TEXT_PLANS.configuredOCR;
}
- const isDocumentParserEligible = documentParserMimeTypes.some((mimePattern) =>
- mimePattern.test(input.mimeType),
- );
- if (!isDocumentParserEligible) {
- return null;
- }
+ /* Ahead of the parser gate: an explicitly narrowed text list names types the built-in
+ * parser does not handle, and processing sends those to RAG with native fallback off
+ * and inspects what comes back. Judging them by the parser's list alone would
+ * fail-close an upload that does have an extraction step. */
if (
checkType != null &&
input.ragConfigured &&
@@ -338,6 +339,12 @@ export function getUploadExtractedTextPlan(
) {
return UPLOAD_EXTRACTED_TEXT_PLANS.configuredRAG;
}
+ const isDocumentParserEligible = documentParserMimeTypes.some((mimePattern) =>
+ mimePattern.test(input.mimeType),
+ );
+ if (!isDocumentParserEligible) {
+ return null;
+ }
return UPLOAD_EXTRACTED_TEXT_PLANS.documentParser;
}
@@ -959,7 +966,8 @@ export function getCanonicalFileInspectionCoverage(
const isAudio = transcriptApplicable === true;
const isTextual = mimeType.startsWith('text/') || TEXTUAL_APPLICATION_MIME_TYPES.has(mimeType);
const hasExtractedTextProvenance =
- typeof file.source === 'string' && file.source.toLowerCase() === 'text';
+ (typeof file.source === 'string' && file.source.toLowerCase() === 'text') ||
+ file.llmDeliveryPath === 'text';
const text = getNonBlankInspectionText(file.text);
const content = typeof file.content === 'string' ? file.content : undefined;
const extractedText = getNonBlankInspectionText(file.extractedText);
diff --git a/packages/api/src/storage/cloudfront/__tests__/crud.test.ts b/packages/api/src/storage/cloudfront/__tests__/crud.test.ts
index bb40b2cb3e..cde16c73e0 100644
--- a/packages/api/src/storage/cloudfront/__tests__/crud.test.ts
+++ b/packages/api/src/storage/cloudfront/__tests__/crud.test.ts
@@ -624,6 +624,7 @@ describe('CloudFront CRUD', () => {
expect(mockGetS3FileStream).toHaveBeenCalledWith(
mockReq,
'https://d123.cloudfront.net/images/u/f.webp',
+ undefined,
);
expect(result).toBe(readable);
});
diff --git a/packages/api/src/storage/cloudfront/crud.ts b/packages/api/src/storage/cloudfront/crud.ts
index 5636704b6e..21801728cf 100644
--- a/packages/api/src/storage/cloudfront/crud.ts
+++ b/packages/api/src/storage/cloudfront/crud.ts
@@ -271,8 +271,9 @@ export async function deleteFileFromCloudFront(req: ServerRequest, file: TFile):
export async function getCloudFrontFileStream(
req: ServerRequest,
filePath: string,
+ options?: { signal?: AbortSignal },
): Promise<Readable> {
- return getS3FileStream(req, filePath);
+ return getS3FileStream(req, filePath, options);
}
/** Get a signed CloudFront URL for an authorized file download. */
diff --git a/packages/api/src/storage/s3/crud.ts b/packages/api/src/storage/s3/crud.ts
index c11f3b0286..b818307795 100644
--- a/packages/api/src/storage/s3/crud.ts
+++ b/packages/api/src/storage/s3/crud.ts
@@ -877,7 +877,11 @@ export async function uploadFileToS3({
}
}
-export async function getS3FileStream(_req: ServerRequest, filePath: string): Promise<Readable> {
+export async function getS3FileStream(
+ _req: ServerRequest,
+ filePath: string,
+ { signal }: { signal?: AbortSignal } = {},
+): Promise<Readable> {
try {
const Key = extractKeyFromS3Url(filePath);
const params = { Bucket: bucketName, Key };
@@ -887,7 +891,7 @@ export async function getS3FileStream(_req: ServerRequest, filePath: string): Pr
throw new Error('[getS3FileStream] S3 not initialized');
}
- const data = await s3.send(new GetObjectCommand(params));
+ const data = await s3.send(new GetObjectCommand(params), { abortSignal: signal });
if (!data.Body) {
throw new Error(`[getS3FileStream] S3 response body is empty for key: ${Key}`);
}
diff --git a/packages/data-provider/src/codeEnvRef.ts b/packages/data-provider/src/codeEnvRef.ts
index b4ecc43bd0..e330f1fc07 100644
--- a/packages/data-provider/src/codeEnvRef.ts
+++ b/packages/data-provider/src/codeEnvRef.ts
@@ -58,6 +58,9 @@ interface CodeEnvRefBase {
* the same wire profile, so this key prevents their file IDs from being
* reused against a different Code API server. */
executionRouteKey?: string;
+ /** Epoch ms when the file was uploaded to the code env; drives the liveness
+ * fast-path (distinct from the usage-bumped `updatedAt`). */
+ provisionedAt?: number;
}
export type CodeExecutionProfile = 'default' | 'stateful';
diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts
index 90f31d15bd..142fc633ed 100644
--- a/packages/data-provider/src/config.ts
+++ b/packages/data-provider/src/config.ts
@@ -1656,6 +1656,33 @@ const sttSchema = z.object({
azureOpenAI: sttAzureOpenAISchema.optional(),
});
+/**
+ * The speech providers a schema actually configures. `allowedAddresses` is transport
+ * policy rather than a provider, and a provider key present but empty configures
+ * nothing. The speech services accept a schema only when exactly one survives here, so
+ * the upload router reads availability from the same list and never routes audio to a
+ * transcription that cannot run.
+ */
+export function listConfiguredSpeechProviders(
+ schema?: Record<string, unknown> | null,
+): Array<[string, Record<string, unknown>]> {
+ if (schema == null) {
+ return [];
+ }
+ return Object.entries(schema).filter(
+ ([key, value]) =>
+ key !== 'allowedAddresses' &&
+ value != null &&
+ typeof value === 'object' &&
+ Object.keys(value).length > 0,
+ ) as Array<[string, Record<string, unknown>]>;
+}
+
+/** Whether a speech schema names exactly one usable provider. */
+export function isSpeechProviderConfigured(schema?: Record<string, unknown> | null): boolean {
+ return listConfiguredSpeechProviders(schema).length === 1;
+}
+
const speechTab = z
.object({
conversationMode: z.boolean().optional(),
diff --git a/packages/data-provider/src/file-config.spec.ts b/packages/data-provider/src/file-config.spec.ts
index 414e3f1d4d..330ed85bf7 100644
--- a/packages/data-provider/src/file-config.spec.ts
+++ b/packages/data-provider/src/file-config.spec.ts
@@ -19,6 +19,7 @@ import {
inferMimeType,
textMimeTypes,
} from './file-config';
+import { resolveDefaultLLMDeliveryPath } from './resolve-llm-delivery-path';
import { EModelEndpoint } from './schemas';
describe('inferMimeType', () => {
@@ -1737,6 +1738,245 @@ describe('fileConfigSchema clientImageResize', () => {
});
});
+describe('defaultLLMDeliveryPath config merging', () => {
+ it('should include defaultLLMDeliveryPath and legacyFileUploadUX in merged endpoint config', () => {
+ const merged = mergeFileConfig({
+ endpoints: {
+ [EModelEndpoint.agents]: {
+ defaultLLMDeliveryPath: {
+ fallback: 'none',
+ overrides: { 'image/*': 'text' },
+ },
+ legacyFileUploadUX: true,
+ },
+ },
+ });
+ const endpointConfig = getEndpointFileConfig({
+ fileConfig: merged,
+ endpoint: EModelEndpoint.agents,
+ });
+ expect(endpointConfig.defaultLLMDeliveryPath).toEqual({
+ fallback: 'none',
+ overrides: { 'image/*': 'text' },
+ });
+ expect(endpointConfig.legacyFileUploadUX).toBe(true);
+ });
+
+ it('inherits the global fallback when an endpoint supplies only overrides', () => {
+ const merged = mergeFileConfig({
+ defaultLLMDeliveryPath: { fallback: 'none' },
+ endpoints: {
+ [EModelEndpoint.openAI]: {
+ defaultLLMDeliveryPath: { overrides: { 'image/*': 'provider' } },
+ },
+ },
+ });
+ const endpointConfig = getEndpointFileConfig({
+ fileConfig: merged,
+ endpoint: EModelEndpoint.openAI,
+ });
+
+ expect(endpointConfig.defaultLLMDeliveryPath).toEqual({
+ fallback: 'none',
+ overrides: { 'image/*': 'provider' },
+ });
+ });
+
+ it('lets an endpoint wildcard outrank a global exact override', () => {
+ const merged = mergeFileConfig({
+ defaultLLMDeliveryPath: {
+ fallback: 'text',
+ overrides: { 'image/png': 'text', 'audio/mpeg': 'none' },
+ },
+ endpoints: {
+ [EModelEndpoint.openAI]: {
+ defaultLLMDeliveryPath: { overrides: { 'image/*': 'provider' } },
+ },
+ },
+ });
+ const endpointConfig = getEndpointFileConfig({
+ fileConfig: merged,
+ endpoint: EModelEndpoint.openAI,
+ });
+
+ expect(
+ resolveDefaultLLMDeliveryPath(
+ 'image/png',
+ endpointConfig.defaultLLMDeliveryPath,
+ merged.defaultLLMDeliveryPath,
+ EModelEndpoint.openAI,
+ ),
+ ).toBe('provider');
+ expect(
+ resolveDefaultLLMDeliveryPath(
+ 'audio/mpeg',
+ endpointConfig.defaultLLMDeliveryPath,
+ merged.defaultLLMDeliveryPath,
+ EModelEndpoint.openAI,
+ ),
+ ).toBe('none');
+ });
+
+ it('keeps a global exact override the endpoint wildcard does not cover', () => {
+ const merged = mergeFileConfig({
+ defaultLLMDeliveryPath: { overrides: { 'image/png': 'text' } },
+ endpoints: {
+ [EModelEndpoint.openAI]: {
+ defaultLLMDeliveryPath: { overrides: { 'audio/*': 'none' } },
+ },
+ },
+ });
+ const endpointConfig = getEndpointFileConfig({
+ fileConfig: merged,
+ endpoint: EModelEndpoint.openAI,
+ });
+
+ expect(endpointConfig.defaultLLMDeliveryPath?.overrides?.['image/png']).toBe('text');
+ });
+
+ it('lets an endpoint exact override win inside its own wildcard family', () => {
+ const merged = mergeFileConfig({
+ defaultLLMDeliveryPath: { overrides: { 'image/png': 'none' } },
+ endpoints: {
+ [EModelEndpoint.openAI]: {
+ defaultLLMDeliveryPath: { overrides: { 'image/*': 'provider', 'image/png': 'text' } },
+ },
+ },
+ });
+ const endpointConfig = getEndpointFileConfig({
+ fileConfig: merged,
+ endpoint: EModelEndpoint.openAI,
+ });
+
+ expect(
+ resolveDefaultLLMDeliveryPath(
+ 'image/png',
+ endpointConfig.defaultLLMDeliveryPath,
+ merged.defaultLLMDeliveryPath,
+ EModelEndpoint.openAI,
+ ),
+ ).toBe('text');
+ });
+
+ it('merges override maps with the endpoint winning per key', () => {
+ const merged = mergeFileConfig({
+ defaultLLMDeliveryPath: {
+ fallback: 'text',
+ overrides: { 'image/*': 'provider', 'audio/*': 'none' },
+ },
+ endpoints: {
+ [EModelEndpoint.openAI]: {
+ defaultLLMDeliveryPath: { overrides: { 'audio/*': 'text' } },
+ },
+ },
+ });
+ const endpointConfig = getEndpointFileConfig({
+ fileConfig: merged,
+ endpoint: EModelEndpoint.openAI,
+ });
+
+ expect(endpointConfig.defaultLLMDeliveryPath).toEqual({
+ fallback: 'text',
+ overrides: { 'image/*': 'provider', 'audio/*': 'text' },
+ });
+ });
+
+ it('keeps an endpoint fallback ahead of inherited default overrides', () => {
+ const merged = mergeFileConfig({
+ endpoints: {
+ default: { defaultLLMDeliveryPath: { overrides: { 'image/*': 'text' } } },
+ [EModelEndpoint.openAI]: { defaultLLMDeliveryPath: { fallback: 'provider' } },
+ },
+ });
+ const endpointConfig = getEndpointFileConfig({
+ fileConfig: merged,
+ endpoint: EModelEndpoint.openAI,
+ });
+
+ expect(endpointConfig.defaultLLMDeliveryPath?.overrides?.['image/*']).toBeUndefined();
+ expect(endpointConfig.defaultLLMDeliveryPath?.fallback).toBe('provider');
+ });
+
+ it('lets an endpoint fallback override the global fallback', () => {
+ const merged = mergeFileConfig({
+ defaultLLMDeliveryPath: { fallback: 'none' },
+ endpoints: {
+ [EModelEndpoint.openAI]: {
+ defaultLLMDeliveryPath: { fallback: 'text' },
+ },
+ },
+ });
+ const endpointConfig = getEndpointFileConfig({
+ fileConfig: merged,
+ endpoint: EModelEndpoint.openAI,
+ });
+
+ expect(endpointConfig.defaultLLMDeliveryPath?.fallback).toBe('text');
+ });
+
+ it('should merge global defaultLLMDeliveryPath into mergedConfig', () => {
+ const merged = mergeFileConfig({
+ defaultLLMDeliveryPath: {
+ fallback: 'provider',
+ overrides: { 'audio/*': 'none' },
+ },
+ legacyFileUploadUX: true,
+ });
+ expect(merged.defaultLLMDeliveryPath).toEqual({
+ fallback: 'provider',
+ overrides: { 'audio/*': 'none' },
+ });
+ expect(merged.legacyFileUploadUX).toBe(true);
+ });
+
+ it('should inherit global legacyFileUploadUX into endpoint config', () => {
+ const merged = mergeFileConfig({
+ legacyFileUploadUX: true,
+ });
+ const endpointConfig = getEndpointFileConfig({
+ fileConfig: merged,
+ endpoint: EModelEndpoint.openAI,
+ });
+ expect(endpointConfig.legacyFileUploadUX).toBe(true);
+ });
+
+ it('should allow endpoint legacyFileUploadUX to override global legacyFileUploadUX', () => {
+ const merged = mergeFileConfig({
+ legacyFileUploadUX: true,
+ endpoints: {
+ [EModelEndpoint.openAI]: {
+ legacyFileUploadUX: false,
+ },
+ },
+ });
+ const endpointConfig = getEndpointFileConfig({
+ fileConfig: merged,
+ endpoint: EModelEndpoint.openAI,
+ });
+ expect(endpointConfig.legacyFileUploadUX).toBe(false);
+ });
+
+ it('should pass through endpoint defaultLLMDeliveryPath in mergeWithDefault', () => {
+ const merged = mergeFileConfig({
+ endpoints: {
+ [EModelEndpoint.openAI]: {
+ defaultLLMDeliveryPath: { overrides: { 'application/pdf': 'text' } },
+ },
+ },
+ });
+ const endpointConfig = getEndpointFileConfig({
+ fileConfig: merged,
+ endpoint: EModelEndpoint.openAI,
+ });
+ expect(endpointConfig.defaultLLMDeliveryPath?.overrides?.['application/pdf']).toBe('text');
+ });
+
+ it('should default legacyFileUploadUX to undefined when not set', () => {
+ const merged = mergeFileConfig(undefined);
+ expect(merged.legacyFileUploadUX).toBeUndefined();
+ });
+});
+
describe('agent attachment context limits', () => {
it('keeps the turn-memory ceiling separate from agent upload storage', () => {
expect(baseFileConfig.fileContextSizeLimit).toBe(128 * 1024 * 1024);
diff --git a/packages/data-provider/src/file-config.ts b/packages/data-provider/src/file-config.ts
index 2084f66ba0..62c85ddcb8 100644
--- a/packages/data-provider/src/file-config.ts
+++ b/packages/data-provider/src/file-config.ts
@@ -177,6 +177,60 @@ export const bedrockDocumentFormats: Record<string, BedrockDocumentFormat> = {
'text/markdown': 'md',
};
+/**
+ * Whether an upload belongs to the conversation rather than to the agent. The value
+ * arrives from multipart form data, so it can be the string "false", which is truthy.
+ * Shared so the route, the authorization check and processing cannot disagree about it.
+ */
+export const isMessageFileUpload = (value?: boolean | string | null): boolean =>
+ value === true || value === 'true';
+
+/**
+ * Whether the upload's conversation uses the Responses API, which decides whether Azure
+ * can carry a document natively. Multipart form data has no booleans, so it arrives as
+ * the string "true".
+ */
+export const isResponsesApiUpload = (value?: boolean | string | null): boolean =>
+ value === true || value === 'true';
+
+/**
+ * The name a file carries inside the code sandbox.
+ *
+ * Image uploads are converted to the configured output type while the record keeps the
+ * original filename, so the extension has to follow the stored bytes or the sandbox
+ * decoder is handed a mismatch. Provisioning and priming both resolve the mount path
+ * from here: deriving it twice under different rules leaves a later turn advertising a
+ * path that does not exist in the sandbox.
+ */
+export const resolveSandboxFilename = (filename: string, mimeType?: string | null): string => {
+ if (!mimeType?.startsWith('image/')) {
+ return filename;
+ }
+ const subtype = mimeType.slice('image/'.length);
+ if (!['webp', 'png', 'jpeg', 'gif'].includes(subtype)) {
+ return filename;
+ }
+ const accepted = subtype === 'jpeg' ? ['.jpg', '.jpeg'] : [`.${subtype}`];
+ const lastDot = filename.lastIndexOf('.');
+ const currentExt = lastDot > 0 ? filename.slice(lastDot).toLowerCase() : '';
+ if (accepted.includes(currentExt)) {
+ return filename;
+ }
+ const base = lastDot > 0 ? filename.slice(0, lastDot) : filename;
+ return `${base}${accepted[0]}`;
+};
+
+/**
+ * The Responses setting a turn actually runs on. A saved agent's own record wins, since
+ * execution reads its model parameters; a conversation only answers for itself. Upload
+ * and delivery must agree here, or a document is stored as raw provider content and then
+ * re-resolved to text it has no extraction for.
+ */
+export const resolveUseResponsesApi = (
+ agentValue?: boolean | null,
+ conversationValue?: boolean | null,
+): boolean | undefined => agentValue ?? conversationValue ?? undefined;
+
export const isBedrockDocumentType = (mimeType?: string): boolean =>
mimeType != null && mimeType in bedrockDocumentFormats;
@@ -511,12 +565,24 @@ export const fileConfig = {
const supportedMimeTypesSchema = z.array(z.string()).optional();
+export const DefaultLLMDeliveryPath = z.enum(['provider', 'text', 'none']);
+export type TDefaultLLMDeliveryPath = z.infer<typeof DefaultLLMDeliveryPath>;
+
+export const defaultLLMDeliveryPathSchema = z.object({
+ fallback: DefaultLLMDeliveryPath.optional(),
+ overrides: z.record(DefaultLLMDeliveryPath).optional(),
+});
+export type TDefaultLLMDeliveryPathConfig = z.infer<typeof defaultLLMDeliveryPathSchema>;
+type TDeliveryPathOverrides = NonNullable<TDefaultLLMDeliveryPathConfig['overrides']>;
+
export const endpointFileConfigSchema = z.object({
disabled: z.boolean().optional(),
fileLimit: z.number().min(0).optional(),
fileSizeLimit: z.number().min(0).optional(),
totalSizeLimit: z.number().min(0).optional(),
supportedMimeTypes: supportedMimeTypesSchema.optional(),
+ defaultLLMDeliveryPath: defaultLLMDeliveryPathSchema.optional(),
+ legacyFileUploadUX: z.boolean().optional(),
});
const skillFileConfigSchema = z.object({
@@ -531,6 +597,7 @@ export const fileConfigSchema = z.object({
fileTokenLimit: z.number().min(0).optional(),
fileContextSizeLimit: z.number().min(0).optional(),
fileContextCharLimit: z.number().min(0).optional(),
+ codeEnvLivenessSafeWindowMs: z.number().min(0).optional(),
imageGeneration: z
.object({
percentage: z.number().min(0).max(100).optional(),
@@ -555,6 +622,8 @@ export const fileConfigSchema = z.object({
supportedMimeTypes: supportedMimeTypesSchema.optional(),
})
.optional(),
+ defaultLLMDeliveryPath: defaultLLMDeliveryPathSchema.optional(),
+ legacyFileUploadUX: z.boolean().optional(),
});
export type TFileConfig = z.infer<typeof fileConfigSchema>;
@@ -877,9 +946,81 @@ function mergeWithDefault(
fileSizeLimit: endpointConfig.fileSizeLimit ?? defaultConfig.fileSizeLimit,
totalSizeLimit: endpointConfig.totalSizeLimit ?? defaultConfig.totalSizeLimit,
supportedMimeTypes: endpointConfig.supportedMimeTypes ?? defaultMimeTypes,
+ defaultLLMDeliveryPath: mergeDeliveryPathConfig(
+ endpointConfig.defaultLLMDeliveryPath,
+ defaultConfig.defaultLLMDeliveryPath,
+ ),
+ legacyFileUploadUX: endpointConfig.legacyFileUploadUX ?? defaultConfig.legacyFileUploadUX,
+ };
+}
+
+/**
+ * Deep-merges delivery-path config so an endpoint that supplies only one override
+ * still inherits the default's fallback and shared overrides. Whole-object
+ * replacement would silently drop the inherited routing.
+ */
+function mergeDeliveryPathConfig(
+ endpointValue?: TDefaultLLMDeliveryPathConfig,
+ defaultValue?: TDefaultLLMDeliveryPathConfig,
+): TDefaultLLMDeliveryPathConfig | undefined {
+ if (!endpointValue) {
+ return defaultValue;
+ }
+ if (!defaultValue) {
+ return endpointValue;
+ }
+ /* An endpoint fallback terminates resolution after that endpoint's own overrides,
+ * so inheriting the lower layer's overrides would promote them above it. Only when
+ * the endpoint declares no fallback does resolution continue downward, and then the
+ * merged map reproduces the chain exactly: endpoint overrides, default overrides,
+ * default fallback. */
+ if (endpointValue.fallback != null) {
+ return endpointValue;
+ }
+ const hasOverrides = endpointValue.overrides != null || defaultValue.overrides != null;
+ return {
+ ...(defaultValue.fallback != null ? { fallback: defaultValue.fallback } : {}),
+ ...(hasOverrides
+ ? { overrides: { ...shadowByWildcard(defaultValue.overrides, endpointValue.overrides) } }
+ : {}),
};
}
+/**
+ * Flattens two override layers into one map that still resolves like the layered chain.
+ * Resolution reads exact keys before wildcards, so a plain spread would let a lower
+ * layer's `image/png` outrank the upper layer's `image/*`. Dropping the entries an
+ * upper wildcard covers restores precedence without changing how lookups work.
+ */
+function shadowByWildcard(
+ lower?: TDeliveryPathOverrides,
+ upper?: TDeliveryPathOverrides,
+): TDeliveryPathOverrides {
+ if (!lower) {
+ return { ...upper };
+ }
+ const upperWildcards = new Set<string>();
+ for (const key in upper) {
+ if (key.endsWith('/*')) {
+ upperWildcards.add(key.slice(0, -1));
+ }
+ }
+ if (upperWildcards.size === 0) {
+ return { ...lower, ...upper };
+ }
+ const retained: TDeliveryPathOverrides = {};
+ for (const key in lower) {
+ const isShadowed =
+ !key.endsWith('/*') &&
+ upperWildcards.has(key.slice(0, key.indexOf('/') + 1)) &&
+ upper?.[key] == null;
+ if (!isShadowed) {
+ retained[key] = lower[key];
+ }
+ }
+ return { ...retained, ...upper };
+}
+
export function getEndpointFileConfig(params: {
fileConfig?: FileConfig | null;
endpoint?: string | null;
@@ -892,11 +1033,19 @@ export function getEndpointFileConfig(params: {
}
/** Compute an effective default by merging user-configured default over the base default */
- const baseDefaultConfig = fileConfig.endpoints.default;
+ const baseDefaultConfig: EndpointFileConfig = fileConfig.endpoints.default;
+ const globalDefaultConfig: EndpointFileConfig = {
+ ...baseDefaultConfig,
+ defaultLLMDeliveryPath: mergeDeliveryPathConfig(
+ mergedFileConfig.defaultLLMDeliveryPath,
+ baseDefaultConfig.defaultLLMDeliveryPath,
+ ),
+ legacyFileUploadUX: mergedFileConfig.legacyFileUploadUX ?? baseDefaultConfig.legacyFileUploadUX,
+ };
const userDefaultConfig = mergedFileConfig.endpoints.default;
const defaultConfig = userDefaultConfig
- ? mergeWithDefault(userDefaultConfig, baseDefaultConfig, 'default')
- : baseDefaultConfig;
+ ? mergeWithDefault(userDefaultConfig, globalDefaultConfig, 'default')
+ : globalDefaultConfig;
const normalizedEndpoint = normalizeEndpointName(endpoint ?? '');
const standardEndpoints = new Set([
@@ -1008,6 +1157,14 @@ export function mergeFileConfig(dynamic: z.infer<typeof fileConfigSchema> | unde
return mergedConfig;
}
+ if (dynamic.defaultLLMDeliveryPath !== undefined) {
+ mergedConfig.defaultLLMDeliveryPath = dynamic.defaultLLMDeliveryPath;
+ }
+
+ if (dynamic.legacyFileUploadUX !== undefined) {
+ mergedConfig.legacyFileUploadUX = dynamic.legacyFileUploadUX;
+ }
+
if (dynamic.serverFileSizeLimit !== undefined) {
mergedConfig.serverFileSizeLimit = mbToBytes(dynamic.serverFileSizeLimit);
}
@@ -1115,6 +1272,14 @@ export function mergeFileConfig(dynamic: z.infer<typeof fileConfigSchema> | unde
dynamicEndpoint.supportedMimeTypes as unknown as string[],
);
}
+
+ if (dynamicEndpoint.defaultLLMDeliveryPath !== undefined) {
+ mergedEndpoint.defaultLLMDeliveryPath = dynamicEndpoint.defaultLLMDeliveryPath;
+ }
+
+ if (dynamicEndpoint.legacyFileUploadUX !== undefined) {
+ mergedEndpoint.legacyFileUploadUX = dynamicEndpoint.legacyFileUploadUX;
+ }
}
return mergedConfig;
diff --git a/packages/data-provider/src/index.ts b/packages/data-provider/src/index.ts
index 992a329dba..6812446ab3 100644
--- a/packages/data-provider/src/index.ts
+++ b/packages/data-provider/src/index.ts
@@ -6,6 +6,7 @@ export * from './config';
export * from './langchain';
export * from './filters';
export * from './file-config';
+export * from './resolve-llm-delivery-path';
/* messages */
export * from './messages';
/* run steps */
diff --git a/packages/data-provider/src/resolve-llm-delivery-path.spec.ts b/packages/data-provider/src/resolve-llm-delivery-path.spec.ts
new file mode 100644
index 0000000000..520e60a63f
--- /dev/null
+++ b/packages/data-provider/src/resolve-llm-delivery-path.spec.ts
@@ -0,0 +1,636 @@
+import type { TDefaultLLMDeliveryPathConfig } from './file-config';
+import {
+ isNativelyReadableText,
+ canToolResourceConsume,
+ resolveUploadDestination,
+ resolveDefaultLLMDeliveryPath,
+ SYSTEM_LLM_DELIVERY_DEFAULTS,
+} from './resolve-llm-delivery-path';
+
+describe('resolveDefaultLLMDeliveryPath', () => {
+ it('should return system default for images when no config provided', () => {
+ expect(resolveDefaultLLMDeliveryPath('image/png')).toBe('provider');
+ });
+
+ it('should return system default for PDFs when no config provided', () => {
+ expect(resolveDefaultLLMDeliveryPath('application/pdf')).toBe('provider');
+ });
+
+ it('should return system default for videos when no config provided', () => {
+ expect(resolveDefaultLLMDeliveryPath('video/mp4')).toBe('provider');
+ });
+
+ it('should return system default for audio when no config provided', () => {
+ expect(resolveDefaultLLMDeliveryPath('audio/mpeg')).toBe('provider');
+ });
+
+ it('should return system fallback for unknown mime types', () => {
+ expect(resolveDefaultLLMDeliveryPath('text/plain')).toBe('text');
+ });
+
+ it('should match exact mime type before wildcard', () => {
+ const config: TDefaultLLMDeliveryPathConfig = {
+ overrides: { 'image/png': 'text', 'image/*': 'provider' },
+ };
+ expect(resolveDefaultLLMDeliveryPath('image/png', config)).toBe('text');
+ });
+
+ it('should match wildcard when no exact match', () => {
+ const config: TDefaultLLMDeliveryPathConfig = {
+ overrides: { 'image/*': 'none' },
+ };
+ expect(resolveDefaultLLMDeliveryPath('image/jpeg', config)).toBe('none');
+ });
+
+ it('should use config fallback when no override matches', () => {
+ const config: TDefaultLLMDeliveryPathConfig = {
+ fallback: 'none',
+ overrides: { 'image/*': 'provider' },
+ };
+ expect(resolveDefaultLLMDeliveryPath('text/plain', config)).toBe('none');
+ });
+
+ it('should resolve endpoint config before global config', () => {
+ const endpointConfig: TDefaultLLMDeliveryPathConfig = {
+ overrides: { 'image/*': 'text' },
+ };
+ const globalConfig: TDefaultLLMDeliveryPathConfig = {
+ overrides: { 'image/*': 'provider' },
+ };
+ expect(resolveDefaultLLMDeliveryPath('image/png', endpointConfig, globalConfig)).toBe('text');
+ });
+
+ it('should fall through to global config when endpoint has no match', () => {
+ const endpointConfig: TDefaultLLMDeliveryPathConfig = {
+ overrides: { 'audio/*': 'none' },
+ };
+ const globalConfig: TDefaultLLMDeliveryPathConfig = {
+ overrides: { 'image/*': 'text' },
+ };
+ expect(resolveDefaultLLMDeliveryPath('image/png', endpointConfig, globalConfig)).toBe('text');
+ });
+
+ it('should use endpoint fallback before global overrides', () => {
+ const endpointConfig: TDefaultLLMDeliveryPathConfig = {
+ fallback: 'none',
+ };
+ const globalConfig: TDefaultLLMDeliveryPathConfig = {
+ overrides: { 'text/*': 'provider' },
+ };
+ expect(resolveDefaultLLMDeliveryPath('text/plain', endpointConfig, globalConfig)).toBe('none');
+ });
+
+ it('should fall through entire chain to system defaults', () => {
+ const endpointConfig: TDefaultLLMDeliveryPathConfig = {};
+ const globalConfig: TDefaultLLMDeliveryPathConfig = {};
+ expect(resolveDefaultLLMDeliveryPath('image/png', endpointConfig, globalConfig)).toBe(
+ 'provider',
+ );
+ expect(resolveDefaultLLMDeliveryPath('application/pdf', endpointConfig, globalConfig)).toBe(
+ 'provider',
+ );
+ expect(resolveDefaultLLMDeliveryPath('text/csv', endpointConfig, globalConfig)).toBe('text');
+ });
+
+ it('should resolve none destination correctly', () => {
+ const config: TDefaultLLMDeliveryPathConfig = {
+ overrides: { 'audio/*': 'none' },
+ };
+ expect(resolveDefaultLLMDeliveryPath('audio/mpeg', config)).toBe('none');
+ });
+
+ it('should prefer exact match over wildcard in the same config', () => {
+ const config: TDefaultLLMDeliveryPathConfig = {
+ overrides: { 'image/*': 'provider', 'image/svg+xml': 'text' },
+ };
+ expect(resolveDefaultLLMDeliveryPath('image/svg+xml', config)).toBe('text');
+ expect(resolveDefaultLLMDeliveryPath('image/png', config)).toBe('provider');
+ });
+
+ it('should handle undefined configs gracefully', () => {
+ expect(resolveDefaultLLMDeliveryPath('text/plain', undefined, undefined)).toBe('text');
+ });
+
+ it('routes PDFs to text for a known endpoint without native document support', () => {
+ expect(
+ resolveDefaultLLMDeliveryPath('application/pdf', undefined, undefined, 'azureOpenAI'),
+ ).toBe('text');
+ expect(resolveDefaultLLMDeliveryPath('audio/mpeg', undefined, undefined, 'azureOpenAI')).toBe(
+ 'text',
+ );
+ });
+
+ it('keeps unsupported video off the model path rather than parsing it as text', () => {
+ /* Nothing extracts text from video: speech-to-text covers audio only, and the default
+ * text matcher accepts any well-formed type, so a downgrade to text ends in raw bytes
+ * decoded as UTF-8. */
+ expect(resolveDefaultLLMDeliveryPath('video/mp4', undefined, undefined, 'azureOpenAI')).toBe(
+ 'none',
+ );
+ expect(resolveDefaultLLMDeliveryPath('video/mp4', undefined, undefined, 'anthropic')).toBe(
+ 'none',
+ );
+ });
+
+ it('normalizes a known provider name before gating native media', () => {
+ expect(resolveDefaultLLMDeliveryPath('audio/mpeg', undefined, undefined, 'OpenRouter')).toBe(
+ 'provider',
+ );
+ });
+
+ it('normalizes a known provider name before gating native PDFs', () => {
+ expect(
+ resolveDefaultLLMDeliveryPath('application/pdf', undefined, undefined, 'OpenRouter'),
+ ).toBe('provider');
+ });
+
+ it('keeps archives and columnar data off the text fallback', () => {
+ /* These land on the text fallback rather than the capability gate, and the default
+ * text matcher accepts them, so they would be decoded as UTF-8 into the prompt. */
+ for (const mimeType of [
+ 'application/zip',
+ 'application/x-zip-compressed',
+ 'application/x-tar',
+ 'application/epub+zip',
+ 'application/vnd.apache.parquet',
+ /* No built-in parser handles presentations or drawings, so without OCR they would
+ * reach the same raw-bytes fallback. */
+ 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+ 'application/vnd.oasis.opendocument.presentation',
+ 'application/vnd.oasis.opendocument.graphics',
+ /* Legacy DOC is absent from documentParserMimeTypes, so it has no parser either. */
+ 'application/msword',
+ ]) {
+ expect(resolveDefaultLLMDeliveryPath(mimeType, undefined, undefined, 'openAI')).toBe('none');
+ }
+ });
+
+ it('keeps recoverable types on the text fallback', () => {
+ for (const mimeType of [
+ 'text/plain',
+ 'text/csv',
+ 'application/json',
+ 'application/vnd.oasis.opendocument.text',
+ 'application/vnd.oasis.opendocument.spreadsheet',
+ 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+ 'application/vnd.ms-excel',
+ 'message/rfc822',
+ ]) {
+ expect(resolveDefaultLLMDeliveryPath(mimeType, undefined, undefined, 'openAI')).toBe('text');
+ }
+ });
+
+ it('still honors an explicit override for an unparsable type', () => {
+ expect(
+ resolveDefaultLLMDeliveryPath(
+ 'application/zip',
+ { overrides: { 'application/zip': 'text' } },
+ undefined,
+ 'openAI',
+ ),
+ ).toBe('text');
+ });
+
+ it('still honors an explicit override for video', () => {
+ /* Capability gating applies to the system default only; an admin who configures a
+ * destination has made the decision. */
+ expect(
+ resolveDefaultLLMDeliveryPath(
+ 'video/mp4',
+ { overrides: { 'video/*': 'text' } },
+ undefined,
+ 'anthropic',
+ ),
+ ).toBe('text');
+ });
+
+ it('keeps provider delivery for endpoints that do support documents', () => {
+ expect(resolveDefaultLLMDeliveryPath('application/pdf', undefined, undefined, 'google')).toBe(
+ 'provider',
+ );
+ });
+
+ it('routes transcribable media to text for providers without media encoders', () => {
+ expect(resolveDefaultLLMDeliveryPath('audio/mpeg', undefined, undefined, 'openAI')).toBe(
+ 'text',
+ );
+ expect(resolveDefaultLLMDeliveryPath('application/pdf', undefined, undefined, 'openAI')).toBe(
+ 'provider',
+ );
+ });
+
+ it('keeps provider delivery for endpoints with real media encoders', () => {
+ expect(resolveDefaultLLMDeliveryPath('audio/mpeg', undefined, undefined, 'google')).toBe(
+ 'provider',
+ );
+ expect(resolveDefaultLLMDeliveryPath('video/mp4', undefined, undefined, 'openrouter')).toBe(
+ 'provider',
+ );
+ });
+
+ it('keeps images on the provider path regardless of document support', () => {
+ expect(resolveDefaultLLMDeliveryPath('image/png', undefined, undefined, 'azureOpenAI')).toBe(
+ 'provider',
+ );
+ });
+
+ it('does not downgrade when the endpoint is unknown', () => {
+ expect(resolveDefaultLLMDeliveryPath('application/pdf')).toBe('provider');
+ });
+
+ it('lets explicit config override the capability gate', () => {
+ expect(
+ resolveDefaultLLMDeliveryPath(
+ 'application/pdf',
+ { overrides: { 'application/pdf': 'provider' } },
+ undefined,
+ 'azureOpenAI',
+ ),
+ ).toBe('provider');
+ });
+
+ it('routes Bedrock document types through the provider on bedrock', () => {
+ const docx = 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
+ expect(resolveDefaultLLMDeliveryPath(docx, undefined, undefined, 'bedrock')).toBe('provider');
+ expect(
+ resolveDefaultLLMDeliveryPath('application/msword', undefined, undefined, 'bedrock'),
+ ).toBe('provider');
+ });
+
+ it('keeps Bedrock document types on text for other endpoints', () => {
+ const docx = 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
+ expect(resolveDefaultLLMDeliveryPath(docx, undefined, undefined, 'openAI')).toBe('text');
+ expect(resolveDefaultLLMDeliveryPath(docx)).toBe('text');
+ });
+
+ it('lets explicit config override the Bedrock document default', () => {
+ const docx = 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
+ expect(resolveDefaultLLMDeliveryPath(docx, { fallback: 'text' }, undefined, 'bedrock')).toBe(
+ 'text',
+ );
+ });
+
+ it('keeps the system default when the provider is unresolved (agents container)', () => {
+ expect(resolveDefaultLLMDeliveryPath('audio/mpeg', undefined, undefined, 'agents')).toBe(
+ 'provider',
+ );
+ expect(resolveDefaultLLMDeliveryPath('application/pdf', undefined, undefined, 'agents')).toBe(
+ 'provider',
+ );
+ });
+
+ it('keeps documents on the provider path for a custom endpoint name', () => {
+ /* A custom endpoint is usually OpenAI- or Anthropic-compatible, and both carry
+ * documents, so judging capability from a name we cannot identify would downgrade
+ * something the real provider delivers. */
+ expect(resolveDefaultLLMDeliveryPath('application/pdf', undefined, undefined, 'MyOpenAI')).toBe(
+ 'provider',
+ );
+ });
+
+ it('downgrades media for a custom endpoint name', () => {
+ /* Media is different: the encoders emit a payload only for the providers they name,
+ * so a custom endpoint receives nothing whatever it proxies to. Left on the provider
+ * path the model gets neither the media nor a transcript. */
+ expect(resolveDefaultLLMDeliveryPath('audio/mpeg', undefined, undefined, 'MyOpenAI')).toBe(
+ 'text',
+ );
+ expect(resolveDefaultLLMDeliveryPath('video/mp4', undefined, undefined, 'MyOpenAI')).toBe(
+ 'none',
+ );
+ });
+
+ it('leaves media alone when no endpoint is resolved at all', () => {
+ /* An ephemeral agent reports no usable endpoint, which is not the same as naming one
+ * we cannot identify. */
+ expect(resolveDefaultLLMDeliveryPath('audio/mpeg')).toBe('provider');
+ expect(resolveDefaultLLMDeliveryPath('audio/mpeg', undefined, undefined, 'agents')).toBe(
+ 'provider',
+ );
+ });
+
+ it('keeps audio off the text path where nothing transcribes it', () => {
+ /* Audio's text path is speech to text, so with no provider configured routing it
+ * there sends the upload to a service that is not running and fails it. */
+ expect(
+ resolveDefaultLLMDeliveryPath('audio/mpeg', undefined, undefined, 'openAI', undefined, false),
+ ).toBe('none');
+ expect(
+ resolveDefaultLLMDeliveryPath('audio/mpeg', undefined, undefined, 'openAI', undefined, true),
+ ).toBe('text');
+ /* Unknown is not absent: a caller that does not say keeps the existing answer. */
+ expect(resolveDefaultLLMDeliveryPath('audio/mpeg', undefined, undefined, 'openAI')).toBe(
+ 'text',
+ );
+ });
+
+ it('honors the Responses API when routing Azure documents', () => {
+ /* Azure is out of the document set because native documents need Responses, so the
+ * encoder's own condition decides rather than the endpoint alone. */
+ expect(
+ resolveDefaultLLMDeliveryPath('application/pdf', undefined, undefined, 'azureOpenAI'),
+ ).toBe('text');
+ expect(
+ resolveDefaultLLMDeliveryPath('application/pdf', undefined, undefined, 'azureOpenAI', true),
+ ).toBe('provider');
+ });
+
+ it('should export SYSTEM_LLM_DELIVERY_DEFAULTS with correct shape', () => {
+ expect(SYSTEM_LLM_DELIVERY_DEFAULTS.fallback).toBe('text');
+ expect(SYSTEM_LLM_DELIVERY_DEFAULTS.overrides).toEqual({
+ 'image/*': 'provider',
+ 'video/*': 'provider',
+ 'audio/*': 'provider',
+ 'application/pdf': 'provider',
+ });
+ });
+});
+
+describe('resolveUploadDestination', () => {
+ const base = { mimeType: 'application/zip', hasAgent: true, isMessageAttachment: false };
+
+ it('keeps an explicit resource and normalizes ocr to context', () => {
+ expect(
+ resolveUploadDestination({ ...base, toolResource: 'ocr', deliveryPath: 'text' }).toolResource,
+ ).toBe('context');
+ expect(
+ resolveUploadDestination({ ...base, toolResource: 'file_search', deliveryPath: 'none' })
+ .toolResource,
+ ).toBe('file_search');
+ });
+
+ it('promotes a text-routed upload to context', () => {
+ expect(resolveUploadDestination({ ...base, deliveryPath: 'text' }).toolResource).toBe(
+ 'context',
+ );
+ });
+
+ it('does not refuse an upload for having no consumer on the agent record', () => {
+ /* A skill can contribute file search or code execution for the turn without appearing
+ * in agent.tools, so an empty list is not evidence that nothing will read the file. */
+ expect(
+ resolveUploadDestination({
+ ...base,
+ deliveryPath: 'none',
+ agentTools: [],
+ isMessageAttachment: true,
+ allowUnknownMessageConsumer: true,
+ }).rejection,
+ ).toBeUndefined();
+ });
+
+ it('does not judge an unknown tool set', () => {
+ /* An ephemeral agent has no record, so its tools are unknown rather than absent. */
+ expect(resolveUploadDestination({ ...base, deliveryPath: 'none' }).rejection).toBe(
+ 'no-agent-resource',
+ );
+ expect(
+ resolveUploadDestination({
+ ...base,
+ deliveryPath: 'none',
+ isMessageAttachment: true,
+ allowUnknownMessageConsumer: true,
+ }).rejection,
+ ).toBeUndefined();
+ });
+
+ it('passes over a tool that cannot read the type, whatever order they are listed in', () => {
+ /* An archive: only code execution can take it, so search listed first must not win. */
+ for (const agentTools of [
+ ['file_search', 'execute_code'],
+ ['execute_code', 'file_search'],
+ ]) {
+ expect(
+ resolveUploadDestination({
+ ...base,
+ mimeType: 'application/zip',
+ deliveryPath: 'none',
+ agentTools,
+ }).toolResource,
+ ).toBe('execute_code');
+ }
+ });
+
+ it('picks a consumer that can read the type, whatever order the tools are listed in', () => {
+ /* file_search indexes extracted text and has nothing to do with an image, so choosing
+ * it would make the upload fail on a rule the agent's tool order decided. */
+ for (const agentTools of [
+ ['file_search', 'execute_code'],
+ ['execute_code', 'file_search'],
+ ]) {
+ expect(
+ resolveUploadDestination({
+ ...base,
+ mimeType: 'image/png',
+ deliveryPath: 'none',
+ agentTools,
+ }).toolResource,
+ ).toBe('execute_code');
+ }
+ });
+
+ it('files a permanent upload under the tool that will consume it', () => {
+ expect(
+ resolveUploadDestination({ ...base, deliveryPath: 'none', agentTools: ['execute_code'] })
+ .toolResource,
+ ).toBe('execute_code');
+ });
+
+ it('refuses a permanent text upload when the context capability is off', () => {
+ /* Priming skips context ids entirely when the capability is off, so storing one
+ * reports success and leaves the agent a file it can never open. */
+ expect(
+ resolveUploadDestination({
+ ...base,
+ deliveryPath: 'text',
+ contextEnabled: false,
+ }).rejection,
+ ).toBe('context-disabled');
+ expect(
+ resolveUploadDestination({
+ ...base,
+ toolResource: 'ocr',
+ deliveryPath: 'text',
+ contextEnabled: false,
+ }).rejection,
+ ).toBe('context-disabled');
+ });
+
+ it('leaves message attachments and unknown capability alone', () => {
+ /* A message attachment is delivered with the turn rather than stored on the agent,
+ * and an unlooked-up capability is not judged. */
+ expect(
+ resolveUploadDestination({
+ ...base,
+ deliveryPath: 'text',
+ isMessageAttachment: true,
+ contextEnabled: false,
+ }).toolResource,
+ ).toBe('context');
+ expect(resolveUploadDestination({ ...base, deliveryPath: 'text' }).toolResource).toBe(
+ 'context',
+ );
+ });
+
+ it('refuses a permanent upload that would land on no agent resource', () => {
+ expect(
+ resolveUploadDestination({
+ ...base,
+ deliveryPath: 'provider',
+ agentTools: [],
+ }).rejection,
+ ).toBe('no-agent-resource');
+ });
+
+ it('accepts a none-routed message attachment with no agent record behind it', () => {
+ /* The ephemeral agent that runs the turn takes its tools from per-turn state the
+ * upload cannot see, so refusing here rejects the file a user just enabled the code
+ * interpreter for. Storing it is what lets provisioning reach it when the tool runs. */
+ expect(
+ resolveUploadDestination({
+ ...base,
+ deliveryPath: 'none',
+ hasAgent: false,
+ isMessageAttachment: true,
+ allowUnknownMessageConsumer: true,
+ }),
+ ).toEqual({});
+ });
+
+ it('refuses a none-routed upload with no turn and no agent behind it', () => {
+ /* Nothing provisions this: no agent to file it under and no message to carry it. */
+ expect(
+ resolveUploadDestination({
+ ...base,
+ deliveryPath: 'none',
+ hasAgent: false,
+ isMessageAttachment: false,
+ }).rejection,
+ ).toBe('no-consumer');
+ });
+
+ it('does not judge an agent conversation the same way', () => {
+ /* An agent's tool set is not knowable at upload: a skill can contribute file search
+ * or code execution for the turn without appearing in agent.tools. */
+ expect(
+ resolveUploadDestination({
+ ...base,
+ deliveryPath: 'none',
+ agentTools: [],
+ isMessageAttachment: true,
+ allowUnknownMessageConsumer: true,
+ }).rejection,
+ ).toBeUndefined();
+ });
+
+ it('leaves a message attachment unclaimed', () => {
+ expect(
+ resolveUploadDestination({
+ ...base,
+ deliveryPath: 'provider',
+ isMessageAttachment: true,
+ }),
+ ).toEqual({});
+ });
+
+ it('refuses a none-routed ordinary chat attachment', () => {
+ expect(
+ resolveUploadDestination({
+ ...base,
+ deliveryPath: 'none',
+ hasAgent: false,
+ isMessageAttachment: true,
+ }).rejection,
+ ).toBe('no-consumer');
+ });
+});
+
+describe('isNativelyReadableText', () => {
+ it('admits the application types whose payload is text', () => {
+ /* Kept in step with the textual set in the content-protection code. Missing one sends
+ * a readable file down the extractor path, where no parser claims it and it is lost. */
+ for (const mimeType of [
+ 'application/json',
+ 'application/javascript',
+ 'application/sql',
+ 'application/xml',
+ 'application/x-yaml',
+ 'application/yaml',
+ 'text/markdown',
+ 'message/rfc822',
+ ]) {
+ expect(isNativelyReadableText(mimeType)).toBe(true);
+ }
+ });
+
+ it('rejects types whose bytes are not text', () => {
+ for (const mimeType of ['application/zip', 'application/pdf', 'image/png']) {
+ expect(isNativelyReadableText(mimeType)).toBe(false);
+ }
+ });
+
+ it('ignores parameters and case, as browsers send both', () => {
+ expect(isNativelyReadableText('text/plain; charset=utf-8')).toBe(true);
+ expect(isNativelyReadableText('Application/JSON')).toBe(true);
+ });
+});
+
+describe('canToolResourceConsume', () => {
+ it('accepts a presentation for file search, which RAG handles', () => {
+ /* The chooser offers file search for pptx from the retrieval set, so refusing it
+ * here rejects the destination the user was just given. The extraction set omits
+ * presentations because the document parser cannot read them, which is a different
+ * question from what the vector service can index. */
+ expect(
+ canToolResourceConsume(
+ 'file_search',
+ 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+ ),
+ ).toBe(true);
+ expect(
+ canToolResourceConsume(
+ 'file_search',
+ 'application/vnd.openxmlformats-officedocument.presentationml.template',
+ ),
+ ).toBe(true);
+ });
+
+ it('still accepts csv for file search, which the retrieval set omits', () => {
+ expect(canToolResourceConsume('file_search', 'text/csv')).toBe(true);
+ expect(canToolResourceConsume('file_search', 'application/vnd.ms-excel')).toBe(true);
+ });
+
+ it('judges each tool by the list the client offers it from', () => {
+ /* An archive is readable by the code interpreter and not by the vector store, so
+ * treating everything non-image as searchable sent it to RAG to be rejected. */
+ expect(canToolResourceConsume('file_search', 'image/png')).toBe(false);
+ expect(canToolResourceConsume('file_search', 'application/zip')).toBe(false);
+ expect(canToolResourceConsume('file_search', 'video/mp4')).toBe(false);
+ expect(canToolResourceConsume('file_search', 'audio/mpeg')).toBe(false);
+ expect(canToolResourceConsume('file_search', 'application/pdf')).toBe(true);
+ /* The vector store handles more than the historical retrieval list, and a data file
+ * is a normal thing to search. */
+ expect(canToolResourceConsume('file_search', 'text/csv')).toBe(true);
+ expect(canToolResourceConsume('execute_code', 'application/zip')).toBe(true);
+ expect(canToolResourceConsume('execute_code', 'image/png')).toBe(true);
+ });
+});
+
+describe('provider document capability', () => {
+ it('keeps Bedrock documents on the provider path', () => {
+ /* Bedrock is in documentSupportedProviders, so the capability downgrade does not
+ * apply to it. Pinned because the Converse document path handles more than PDF and a
+ * downgrade here would silently flatten it through extraction. */
+ expect(resolveDefaultLLMDeliveryPath('application/pdf', undefined, undefined, 'bedrock')).toBe(
+ 'provider',
+ );
+ expect(
+ resolveDefaultLLMDeliveryPath(
+ 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+ undefined,
+ undefined,
+ 'bedrock',
+ ),
+ ).toBe('provider');
+ });
+});
diff --git a/packages/data-provider/src/resolve-llm-delivery-path.ts b/packages/data-provider/src/resolve-llm-delivery-path.ts
new file mode 100644
index 0000000000..bb6148efaf
--- /dev/null
+++ b/packages/data-provider/src/resolve-llm-delivery-path.ts
@@ -0,0 +1,379 @@
+import type { TDefaultLLMDeliveryPath, TDefaultLLMDeliveryPathConfig } from './file-config';
+import type { EndpointFileConfig, FileConfig } from './types/files';
+import {
+ EModelEndpoint,
+ isDocumentSupportedProvider,
+ isKnownProviderIdentifier,
+ isMediaSupportedProvider,
+} from './schemas';
+import { retrievalMimeTypes, isBedrockDocumentType, codeInterpreterMimeTypes } from './file-config';
+import { EToolResources } from './types/assistants';
+
+/** Audio and video reach the model only through the media encoders, which support a
+ * narrower provider set than documents. Images use the broadly supported vision
+ * path and are never gated here. */
+const isProviderCapable = (
+ mimeType: string,
+ endpoint: string,
+ useResponsesApi?: boolean,
+): boolean => {
+ if (mimeType.startsWith('audio/') || mimeType.startsWith('video/')) {
+ return isMediaSupportedProvider(endpoint);
+ }
+ if (mimeType === 'application/pdf') {
+ /* Azure is out of the document set because it needs the Responses API for native
+ * documents, so the encoder's own condition decides rather than the endpoint alone. */
+ return useResponsesApi === true || isDocumentSupportedProvider(endpoint);
+ }
+ return true;
+};
+
+export const SYSTEM_LLM_DELIVERY_DEFAULTS: Required<TDefaultLLMDeliveryPathConfig> = {
+ fallback: 'text',
+ overrides: {
+ 'image/*': 'provider',
+ 'video/*': 'provider',
+ 'audio/*': 'provider',
+ 'application/pdf': 'provider',
+ },
+};
+
+/**
+ * Types some step in the upload pipeline can turn into text: natively readable text,
+ * documents a parser or OCR handles, images through OCR, and audio through transcription.
+ *
+ * Everything absent from this list, notably archives, tarballs, columnar data files and
+ * video, has no such step, and the default text matcher accepts any well-formed type, so
+ * routing them to text ends in their bytes being decoded as UTF-8.
+ */
+const TEXT_RECOVERABLE_MIME_TYPES: RegExp[] = [
+ /^text\//,
+ /^image\//,
+ /^audio\//,
+ /^application\/(json|javascript|xml|sql|yaml|x-yaml|csv|typescript|x-sh|vnd\.coffeescript)$/,
+ /^application\/pdf$/,
+ /* Only the formats the built-in document parser handles. Presentations and graphics
+ * are absent from documentParserMimeTypes, so on a deployment without OCR they would
+ * fall through to the permissive text matcher and be decoded as ZIP bytes. */
+ /^application\/vnd\.openxmlformats-officedocument\.(wordprocessingml\.document|spreadsheetml\.sheet)$/,
+ /^application\/vnd\.oasis\.opendocument\.(text|spreadsheet)$/,
+ /^application\/(vnd\.ms-excel|x-msexcel|msexcel|x-ms-excel|x-excel|x-dos_ms_excel|xls|x-xls)$/,
+ /^message\/rfc822$/,
+];
+
+/**
+ * Types whose bytes are text already, so reading them directly is meaningful. Everything
+ * else needs a real extractor: decoding it as UTF-8 produces mojibake rather than content.
+ */
+/** Application types whose payload is text. Mirrors the set the content-protection code
+ * treats as textual, plus the source and data formats this pipeline also accepts. */
+const TEXTUAL_APPLICATION_MIME_TYPES = new Set([
+ 'application/json',
+ 'application/javascript',
+ 'application/sql',
+ 'application/xml',
+ 'application/x-yaml',
+ 'application/yaml',
+ 'application/csv',
+ 'application/typescript',
+ 'application/x-sh',
+ 'application/vnd.coffeescript',
+]);
+
+export function isNativelyReadableText(mimeType: string): boolean {
+ const normalized = mimeType.split(';', 1)[0].trim().toLowerCase();
+ return (
+ normalized.startsWith('text/') ||
+ TEXTUAL_APPLICATION_MIME_TYPES.has(normalized) ||
+ normalized === 'message/rfc822'
+ );
+}
+
+export function hasTextExtractionPath(mimeType: string): boolean {
+ return TEXT_RECOVERABLE_MIME_TYPES.some((pattern) => pattern.test(mimeType));
+}
+
+/**
+ * Resolves the default file path destination for a given mime type.
+ * Resolution chain: endpoint overrides -> endpoint fallback -> global overrides -> global fallback -> system defaults.
+ */
+export function resolveDefaultLLMDeliveryPath(
+ mimeType: string,
+ endpointConfig?: TDefaultLLMDeliveryPathConfig,
+ globalConfig?: TDefaultLLMDeliveryPathConfig,
+ endpoint?: string,
+ useResponsesApi?: boolean,
+ sttConfigured?: boolean,
+): TDefaultLLMDeliveryPath {
+ const wildcard = mimeType.split('/')[0] + '/*';
+
+ if (endpointConfig?.overrides) {
+ if (endpointConfig.overrides[mimeType]) {
+ return endpointConfig.overrides[mimeType] as TDefaultLLMDeliveryPath;
+ }
+ if (endpointConfig.overrides[wildcard]) {
+ return endpointConfig.overrides[wildcard] as TDefaultLLMDeliveryPath;
+ }
+ }
+
+ if (endpointConfig?.fallback) {
+ return endpointConfig.fallback;
+ }
+
+ if (globalConfig?.overrides) {
+ if (globalConfig.overrides[mimeType]) {
+ return globalConfig.overrides[mimeType] as TDefaultLLMDeliveryPath;
+ }
+ if (globalConfig.overrides[wildcard]) {
+ return globalConfig.overrides[wildcard] as TDefaultLLMDeliveryPath;
+ }
+ }
+
+ if (globalConfig?.fallback) {
+ return globalConfig.fallback;
+ }
+
+ const systemDefault = (SYSTEM_LLM_DELIVERY_DEFAULTS.overrides[mimeType] ??
+ SYSTEM_LLM_DELIVERY_DEFAULTS.overrides[wildcard] ??
+ SYSTEM_LLM_DELIVERY_DEFAULTS.fallback) as TDefaultLLMDeliveryPath;
+
+ /** Only the system default is capability-gated: an explicit config above is the
+ * admin's decision. A known endpoint that cannot encode documents or media would
+ * otherwise accept the upload and hand the model nothing at all. */
+ /** `agents` is a container, not a provider: it is what an upload reports when the
+ * agent's real provider could not be resolved, as for ephemeral agents. A custom
+ * endpoint name is likewise unresolvable here, since its real provider is chosen
+ * at request time and is usually OpenAI- or Anthropic-compatible. Judging
+ * capability from either would downgrade media the actual provider can deliver,
+ * so an unresolved provider keeps the system default. */
+ const namedEndpoint = endpoint != null && endpoint !== EModelEndpoint.agents;
+ const providerKnown = namedEndpoint && isKnownProviderIdentifier(endpoint);
+ /* Media is judged for any named endpoint, identified or not. The media encoders emit a
+ * payload only for the providers they name, so a custom endpoint gets nothing whatever
+ * it proxies to, and leaving it on the provider path delivers neither media nor text.
+ * Documents keep the narrower rule: an unidentified endpoint is usually OpenAI- or
+ * Anthropic-compatible, both of which do carry them. */
+ const isMedia = mimeType.startsWith('audio/') || mimeType.startsWith('video/');
+ /* Audio's text path is transcription, so on a deployment with no speech provider it is
+ * not recoverable at all. Routing it to text there sends the upload to a service that
+ * is not there and fails it outright. Unknown is left alone; only an explicit absence
+ * closes the path. */
+ const canRecoverText = (type: string): boolean =>
+ type.startsWith('audio/') && sttConfigured === false ? false : hasTextExtractionPath(type);
+ const canJudgeCapability = isMedia ? namedEndpoint : providerKnown;
+ if (
+ systemDefault === 'provider' &&
+ canJudgeCapability &&
+ !isProviderCapable(mimeType, endpoint as string, useResponsesApi)
+ ) {
+ /* Downgrading is only useful where text can actually be recovered. Video has no
+ * extraction step: speech-to-text covers audio, and the default text matcher accepts
+ * any well-formed MIME type, so routing it to text ends in the raw bytes being
+ * decoded as UTF-8 and handed to the model. Keep it off the model path instead; the
+ * file is still stored and still reachable by tools. */
+ return canRecoverText(mimeType) ? 'text' : 'none';
+ }
+
+ /** Bedrock's Converse document path natively accepts more than PDF, so on that
+ * endpoint its document types belong on the provider path rather than being
+ * extracted, which would drop non-text content and layout. */
+ if (
+ systemDefault !== 'provider' &&
+ endpoint === EModelEndpoint.bedrock &&
+ isBedrockDocumentType(mimeType)
+ ) {
+ return 'provider';
+ }
+
+ /* The text fallback is only meaningful where text can be recovered. An archive or a
+ * columnar data file reaching it would be decoded as UTF-8 into the prompt, so keep it
+ * off the model path instead; the file is still stored and reachable by tools. An
+ * explicit configuration above has already returned, so this governs the system default
+ * alone. */
+ if (systemDefault === 'text' && !canRecoverText(mimeType)) {
+ return 'none';
+ }
+
+ return systemDefault;
+}
+
+/**
+ * Delivery path for an upload that named no tool resource. The legacy chooser makes the
+ * destination explicit, so nothing is inferred there.
+ */
+export function resolveDefaultUploadLLMDeliveryPath({
+ mimeType,
+ endpointConfig,
+ fileConfig,
+ endpoint,
+ useResponsesApi,
+ sttConfigured,
+}: {
+ mimeType: string;
+ endpointConfig?: EndpointFileConfig;
+ fileConfig?: FileConfig;
+ endpoint?: string;
+ useResponsesApi?: boolean;
+ sttConfigured?: boolean;
+}): TDefaultLLMDeliveryPath {
+ if (endpointConfig?.legacyFileUploadUX === true) {
+ return 'provider';
+ }
+ return resolveDefaultLLMDeliveryPath(
+ mimeType,
+ endpointConfig?.defaultLLMDeliveryPath,
+ fileConfig?.defaultLLMDeliveryPath,
+ endpoint,
+ useResponsesApi,
+ sttConfigured,
+ );
+}
+
+/** Delivery path for an upload, honoring an explicitly chosen tool resource. */
+export function resolveUploadLLMDeliveryPath({
+ toolResource,
+ mimeType,
+ endpointConfig,
+ fileConfig,
+ endpoint,
+ useResponsesApi,
+ sttConfigured,
+}: {
+ toolResource?: string | null;
+ mimeType: string;
+ endpointConfig?: EndpointFileConfig;
+ fileConfig?: FileConfig;
+ endpoint?: string;
+ useResponsesApi?: boolean;
+ sttConfigured?: boolean;
+}): TDefaultLLMDeliveryPath {
+ if (toolResource === EToolResources.context || toolResource === EToolResources.ocr) {
+ return 'text';
+ }
+ if (toolResource === EToolResources.file_search || toolResource === EToolResources.execute_code) {
+ return 'none';
+ }
+ return resolveDefaultUploadLLMDeliveryPath({
+ mimeType,
+ endpointConfig,
+ fileConfig,
+ endpoint,
+ useResponsesApi,
+ sttConfigured,
+ });
+}
+
+/**
+ * Whether a file tool can do anything with this type. `file_search` indexes extracted
+ * text, so it needs a type some step can turn into text and cannot use media, whose
+ * extraction paths are OCR and speech rather than the vector store. Code execution is
+ * judged by the list the client offers it from. Shared by upload-time selection and
+ * deferred provisioning so the two cannot queue a file the other would refuse.
+ */
+export function canToolResourceConsume(toolResource: string, mimeType: string): boolean {
+ if (toolResource === EToolResources.file_search) {
+ /* The union of both readers rather than either alone: the extraction set describes
+ * the document parser and omits presentations, which RAG does handle and the chooser
+ * already offers, while the retrieval set omits csv and the spreadsheet formats. */
+ return (
+ !mimeType.startsWith('image') &&
+ !mimeType.startsWith('audio') &&
+ !mimeType.startsWith('video') &&
+ (hasTextExtractionPath(mimeType) || matchesMimeList(mimeType, retrievalMimeTypes))
+ );
+ }
+ if (toolResource === EToolResources.execute_code) {
+ return matchesMimeList(mimeType, codeInterpreterMimeTypes);
+ }
+ return true;
+}
+
+const matchesMimeList = (mimeType: string, patterns: RegExp[]): boolean =>
+ patterns.some((pattern) => pattern.test(mimeType));
+
+/** Why an upload cannot be accepted, when nothing would be able to read it. */
+export type UploadRejection = 'no-agent-resource' | 'context-disabled' | 'no-consumer';
+
+/**
+ * Where a unified upload will end up, and whether it can be accepted at all.
+ *
+ * An upload has to be readable by something: the model, an extraction step, or a file
+ * tool. A permanent one has to land on an agent resource too, or storing it succeeds
+ * while leaving the agent no reference to it. Both outcomes are decided here rather than
+ * discovered later, so a request that would change nothing is refused with a reason.
+ *
+ * `agentTools` is undefined when no agent record backs the upload, as for an ephemeral
+ * agent that exists only for the request. An unknown tool set is not judged.
+ */
+export function resolveUploadDestination(params: {
+ toolResource?: string | null;
+ deliveryPath: TDefaultLLMDeliveryPath;
+ mimeType: string;
+ agentTools?: string[];
+ hasAgent: boolean;
+ isMessageAttachment: boolean;
+ /** True when a message attachment may acquire a compatible tool on a later turn. */
+ allowUnknownMessageConsumer?: boolean;
+ /** Undefined when not looked up, as for an upload that cannot land on context. */
+ contextEnabled?: boolean;
+}): { toolResource?: string; rejection?: UploadRejection } {
+ const {
+ toolResource,
+ deliveryPath,
+ mimeType,
+ agentTools,
+ hasAgent,
+ isMessageAttachment,
+ allowUnknownMessageConsumer = false,
+ contextEnabled,
+ } = params;
+
+ /* A permanent context resource is only readable while the capability is on: priming
+ * skips those ids entirely when it is off, so storing one reports success and leaves
+ * the agent a file it can never open. */
+ const refusesContext = (resource: string): boolean =>
+ resource === EToolResources.context &&
+ hasAgent &&
+ !isMessageAttachment &&
+ contextEnabled === false;
+
+ if (toolResource) {
+ const resolved =
+ toolResource === EToolResources.ocr ? EToolResources.context : (toolResource as string);
+ return refusesContext(resolved)
+ ? { rejection: 'context-disabled' }
+ : { toolResource: resolved };
+ }
+
+ if (deliveryPath === 'text') {
+ return refusesContext(EToolResources.context)
+ ? { rejection: 'context-disabled' }
+ : { toolResource: EToolResources.context };
+ }
+
+ /* Skills contribute file tools per turn without being stored on the agent, so this list
+ * can name a consumer but its silence proves nothing. Used to file an upload, never to
+ * refuse one, and matched on what each tool can actually read so the choice does not
+ * depend on the order the agent happens to list its tools in. */
+ const consumingTool = agentTools?.find(
+ (tool) =>
+ (tool === EToolResources.execute_code || tool === EToolResources.file_search) &&
+ canToolResourceConsume(tool, mimeType),
+ );
+
+ if (deliveryPath === 'none' && consumingTool) {
+ return { toolResource: consumingTool };
+ }
+
+ if (hasAgent && !isMessageAttachment) {
+ return { rejection: 'no-agent-resource' };
+ }
+
+ /* Message attachments may acquire a compatible tool after upload. Permanent agent files
+ * cannot: they must be assigned to a durable resource before this request returns. */
+ if (deliveryPath === 'none' && (!isMessageAttachment || !allowUnknownMessageConsumer)) {
+ return { rejection: 'no-consumer' };
+ }
+
+ return {};
+}
diff --git a/packages/data-provider/src/schemas.ts b/packages/data-provider/src/schemas.ts
index 14f79153f9..583e0225ee 100644
--- a/packages/data-provider/src/schemas.ts
+++ b/packages/data-provider/src/schemas.ts
@@ -109,7 +109,41 @@ export const inputTokensIncludesCache = (provider?: string | null): boolean => {
};
export const isDocumentSupportedProvider = (provider?: string | null): boolean => {
- return documentSupportedProviders.has(provider ?? '');
+ const normalized = provider?.toLowerCase() ?? '';
+ return Array.from(documentSupportedProviders).some(
+ (candidate) => candidate.toLowerCase() === normalized,
+ );
+};
+
+/**
+ * Endpoints whose encoders actually build native audio/video payloads. Narrower than
+ * `documentSupportedProviders`: a provider can accept PDFs and still emit nothing for
+ * media, in which case the upload has to fall back to text/STT.
+ */
+export const mediaSupportedProviders = new Set<string>([
+ EModelEndpoint.google,
+ Providers.VERTEXAI,
+ Providers.OPENROUTER,
+]);
+
+export const isMediaSupportedProvider = (provider?: string | null): boolean => {
+ return mediaSupportedProviders.has(provider?.toLowerCase() ?? '');
+};
+
+/**
+ * Built-in endpoint and provider identifiers. A name outside this set is a custom
+ * endpoint whose real provider is resolved at request time, so its capabilities
+ * cannot be judged from the name alone.
+ */
+const knownProviderIdentifiers = new Set<string>([
+ ...Object.values(EModelEndpoint),
+ ...Object.values(Providers),
+ ...Object.values(EModelEndpoint).map((provider) => provider.toLowerCase()),
+ ...Object.values(Providers).map((provider) => provider.toLowerCase()),
+]);
+
+export const isKnownProviderIdentifier = (provider?: string | null): boolean => {
+ return knownProviderIdentifiers.has(provider?.toLowerCase() ?? '');
};
export const paramEndpoints = new Set<EModelEndpoint | string>([
diff --git a/packages/data-provider/src/types/files.ts b/packages/data-provider/src/types/files.ts
index 1732e0458f..32b21f9b32 100644
--- a/packages/data-provider/src/types/files.ts
+++ b/packages/data-provider/src/types/files.ts
@@ -1,3 +1,4 @@
+import type { TDefaultLLMDeliveryPathConfig } from '../file-config';
import type { CodeEnvRef, CodeEnvRefMap } from '../codeEnvRef';
import { EToolResources } from './assistants';
@@ -48,6 +49,8 @@ export type EndpointFileConfig = {
fileSizeLimit?: number;
totalSizeLimit?: number;
supportedMimeTypes?: RegexLike[];
+ defaultLLMDeliveryPath?: TDefaultLLMDeliveryPathConfig;
+ legacyFileUploadUX?: boolean;
};
export type FileConfig = {
@@ -82,6 +85,8 @@ export type FileConfig = {
supportedMimeTypes?: RegexLike[];
};
checkType?: (fileType: string, supportedTypes: RegexLike[]) => boolean;
+ defaultLLMDeliveryPath?: TDefaultLLMDeliveryPathConfig;
+ legacyFileUploadUX?: boolean;
};
export type FileConfigInput = {
@@ -111,6 +116,8 @@ export type FileConfigInput = {
supportedMimeTypes?: string[];
};
checkType?: (fileType: string, supportedTypes: RegexLike[]) => boolean;
+ defaultLLMDeliveryPath?: TDefaultLLMDeliveryPathConfig;
+ legacyFileUploadUX?: boolean;
};
export type TFile = {
@@ -173,7 +180,14 @@ export type TFile = {
codeEnvRefs?: CodeEnvRefMap;
/** Dispatch-order stamp for the current source artifact generation. */
sourceDispatchedAt?: number;
+ /** Vector namespaces this file has been embedded into. */
+ embeddedEntities?: string[];
+ /** The user named this destination, so absent ones were declined. */
+ destinationChosen?: boolean;
+ /** The type the delivery route was resolved against, when conversion changed it. */
+ routingMimeType?: string;
};
+ llmDeliveryPath?: 'provider' | 'text' | 'none';
createdAt?: string | Date;
updatedAt?: string | Date;
};
diff --git a/packages/data-schemas/src/methods/file.spec.ts b/packages/data-schemas/src/methods/file.spec.ts
index e1ce4f49a9..47b32ef814 100644
--- a/packages/data-schemas/src/methods/file.spec.ts
+++ b/packages/data-schemas/src/methods/file.spec.ts
@@ -891,6 +891,502 @@ describe('File Methods', () => {
});
});
+ describe('getDeferredProvisionFiles', () => {
+ it('rejects route keys that cannot be used as MongoDB field segments', async () => {
+ const ownerScope = { userId: new mongoose.Types.ObjectId().toString() };
+
+ await expect(
+ fileMethods.getDeferredProvisionFiles([uuidv4()], ownerScope, {
+ code: true,
+ codeRouteKey: 'stateful.invalid',
+ }),
+ ).rejects.toThrow('Invalid code environment route key');
+ });
+
+ const makeFile = (
+ fileId: string,
+ ownerId: mongoose.Types.ObjectId,
+ overrides: Record<string, unknown> = {},
+ ) =>
+ runAsSystem(() =>
+ fileMethods.createFile({
+ file_id: fileId,
+ user: ownerId,
+ tenantId: 'tenant-a',
+ conversationId: 'conversation-a',
+ filename: `${fileId}.csv`,
+ filepath: `/uploads/${fileId}.csv`,
+ source: 'local',
+ type: 'text/csv',
+ bytes: 100,
+ context: FileContext.message_attachment,
+ ...overrides,
+ }),
+ );
+
+ it('returns attachments that carry neither an embedding nor a code reference', async () => {
+ const ownerId = new mongoose.Types.ObjectId();
+ const deferredId = uuidv4();
+ await makeFile(deferredId, ownerId);
+
+ const results = await fileMethods.getDeferredProvisionFiles([deferredId], {
+ userId: ownerId.toString(),
+ tenantId: 'tenant-a',
+ });
+
+ expect(results.map((file) => file.file_id)).toEqual([deferredId]);
+ });
+
+ it('returns an agent file embedded only in another agent namespace', async () => {
+ /* Its vectors are under the other agent's entity, so the namespace this turn
+ * searches has none of them. The record-wide flag cannot say that, and skipping
+ * hydration here means nothing downstream ever notices. */
+ const ownerId = new mongoose.Types.ObjectId();
+ const foreignId = uuidv4();
+ await makeFile(foreignId, ownerId, {
+ context: FileContext.agents,
+ embedded: true,
+ metadata: { embeddedEntities: ['other-agent'] },
+ });
+
+ const results = await fileMethods.getDeferredProvisionFiles(
+ [foreignId],
+ { userId: ownerId.toString(), tenantId: 'tenant-a' },
+ {
+ search: true,
+ searchNamespaces: ['this-agent', ownerId.toString()],
+ },
+ );
+
+ expect(results.map((file) => file.file_id)).toEqual([foreignId]);
+ });
+
+ it('leaves an agent file embedded in every candidate namespace alone', async () => {
+ const ownerId = new mongoose.Types.ObjectId();
+ const settledId = uuidv4();
+ await makeFile(settledId, ownerId, {
+ context: FileContext.agents,
+ embedded: true,
+ metadata: { embeddedEntities: ['this-agent', ownerId.toString()] },
+ });
+
+ const results = await fileMethods.getDeferredProvisionFiles(
+ [settledId],
+ { userId: ownerId.toString(), tenantId: 'tenant-a' },
+ {
+ search: true,
+ searchNamespaces: ['this-agent', ownerId.toString()],
+ },
+ );
+
+ expect(results).toEqual([]);
+ });
+
+ it('returns a default-route reference so liveness can screen it', async () => {
+ /* A usable reference is not a live one. With resendFiles off this is the only query
+ * that runs, so excluding it leaves an expired session unnoticed and the code tool
+ * running without the file. */
+ const ownerId = new mongoose.Types.ObjectId();
+ const refId = uuidv4();
+ await makeFile(refId, ownerId, {
+ metadata: {
+ codeEnvRef: { kind: 'user', id: 'u1', storage_session_id: 's1', file_id: 'r1' },
+ codeEnvRefs: {
+ default: { kind: 'user', id: 'u1', storage_session_id: 's1', file_id: 'r1' },
+ },
+ },
+ });
+
+ const results = await fileMethods.getDeferredProvisionFiles(
+ [refId],
+ { userId: ownerId.toString(), tenantId: 'tenant-a' },
+ { code: true, codeRouteKey: 'default', hydrateProvisioned: true },
+ );
+
+ expect(results.map((file) => file.file_id)).toEqual([refId]);
+ });
+
+ it('leaves a default reference alone when another query already hydrates it', async () => {
+ /* With resendFiles on, getToolFilesByIds loads provisioned files and the probe sees
+ * them there, so widening this query would only duplicate the read. */
+ const ownerId = new mongoose.Types.ObjectId();
+ const refId = uuidv4();
+ await makeFile(refId, ownerId, {
+ metadata: {
+ codeEnvRef: { kind: 'user', id: 'u1', storage_session_id: 's1', file_id: 'r1' },
+ codeEnvRefs: {
+ default: { kind: 'user', id: 'u1', storage_session_id: 's1', file_id: 'r1' },
+ },
+ },
+ });
+
+ const results = await fileMethods.getDeferredProvisionFiles(
+ [refId],
+ { userId: ownerId.toString(), tenantId: 'tenant-a' },
+ { code: true, codeRouteKey: 'default', hydrateProvisioned: false },
+ );
+
+ expect(results).toEqual([]);
+ });
+
+ it('returns a usable stateful reference so priming can add it to the tool resources', async () => {
+ /* Being provisioned already is not a reason to skip it: with no other query running,
+ * this is what puts the record into tool_resources. Omitting it drops the file the
+ * previous turn provisioned successfully while retrying the one that failed. */
+ const ownerId = new mongoose.Types.ObjectId();
+ const refId = uuidv4();
+ const statefulRef = {
+ kind: 'user',
+ id: 'u1',
+ storage_session_id: 's2',
+ file_id: 'r2',
+ executionRouteKey: 'stateful:a',
+ };
+ await makeFile(refId, ownerId, {
+ metadata: {
+ codeEnvRef: { kind: 'user', id: 'u1', storage_session_id: 's1', file_id: 'r1' },
+ codeEnvRefs: { 'stateful:a': statefulRef },
+ },
+ });
+
+ const results = await fileMethods.getDeferredProvisionFiles(
+ [refId],
+ { userId: ownerId.toString(), tenantId: 'tenant-a' },
+ { code: true, codeRouteKey: 'stateful:a', hydrateProvisioned: true },
+ );
+
+ expect(results.map((file) => file.file_id)).toEqual([refId]);
+ });
+
+ it('returns an embedded attachment to a search-only agent when nothing else hydrates', async () => {
+ /* With resendFiles off, getToolFilesByIds does not run, so this is the only query
+ * that can put an already-embedded attachment into tool_resources.file_search.
+ * Excluding it on the embedded flag leaves the next search with no reference to a
+ * file the previous turn embedded successfully. */
+ const ownerId = new mongoose.Types.ObjectId();
+ const fileId = uuidv4();
+ await makeFile(fileId, ownerId, { embedded: true });
+
+ const results = await fileMethods.getDeferredProvisionFiles(
+ [fileId],
+ { userId: ownerId.toString(), tenantId: 'tenant-a' },
+ { search: true, searchNamespaces: [ownerId.toString()], hydrateProvisioned: true },
+ );
+
+ expect(results.map((file) => file.file_id)).toEqual([fileId]);
+ });
+
+ it('leaves an embedded attachment alone when another query already hydrates it', async () => {
+ const ownerId = new mongoose.Types.ObjectId();
+ const fileId = uuidv4();
+ await makeFile(fileId, ownerId, { embedded: true });
+
+ const results = await fileMethods.getDeferredProvisionFiles(
+ [fileId],
+ { userId: ownerId.toString(), tenantId: 'tenant-a' },
+ { search: true, searchNamespaces: [ownerId.toString()], hydrateProvisioned: false },
+ );
+
+ expect(results).toEqual([]);
+ });
+
+ it('surfaces a read failure rather than reporting nothing to provision', async () => {
+ /* An empty list is indistinguishable from nothing needing provisioning, so a
+ * swallowed error would let the tool run without the attachment. */
+ const ownerId = new mongoose.Types.ObjectId();
+ const failing = createFileMethods({
+ ...mongoose,
+ models: {
+ ...mongoose.models,
+ File: {
+ find: () => {
+ throw new Error('mongo unavailable');
+ },
+ },
+ },
+ } as unknown as typeof mongoose);
+
+ await expect(
+ failing.getDeferredProvisionFiles([uuidv4()], { userId: ownerId.toString() }),
+ ).rejects.toThrow(/mongo unavailable/);
+ });
+
+ it('still queues a file whose only code reference is for another route', async () => {
+ const ownerId = new mongoose.Types.ObjectId();
+ const otherRouteId = uuidv4();
+ await makeFile(otherRouteId, ownerId, {
+ embedded: true,
+ metadata: {
+ codeEnvRefs: {
+ 'stateful:a': {
+ kind: 'user',
+ id: ownerId.toString(),
+ storage_session_id: 'session-a',
+ file_id: otherRouteId,
+ executionRouteKey: 'stateful:a',
+ },
+ },
+ },
+ });
+
+ const results = await fileMethods.getDeferredProvisionFiles(
+ [otherRouteId],
+ { userId: ownerId.toString(), tenantId: 'tenant-a' },
+ { code: true, codeRouteKey: 'stateful:b' },
+ );
+
+ expect(results.map((file) => file.file_id)).toEqual([otherRouteId]);
+ });
+
+ it('omits a file already provisioned for the active route', async () => {
+ const ownerId = new mongoose.Types.ObjectId();
+ const sameRouteId = uuidv4();
+ await makeFile(sameRouteId, ownerId, {
+ embedded: true,
+ metadata: {
+ codeEnvRefs: {
+ 'stateful:b': {
+ kind: 'user',
+ id: ownerId.toString(),
+ storage_session_id: 'session-b',
+ file_id: sameRouteId,
+ executionRouteKey: 'stateful:b',
+ },
+ },
+ },
+ });
+
+ const results = await fileMethods.getDeferredProvisionFiles(
+ [sameRouteId],
+ { userId: ownerId.toString(), tenantId: 'tenant-a' },
+ { code: true, codeRouteKey: 'stateful:b' },
+ );
+
+ expect(results).toEqual([]);
+ });
+
+ it('treats a legacy pointer without a route key as the default deployment', async () => {
+ const ownerId = new mongoose.Types.ObjectId();
+ const legacyId = uuidv4();
+ await makeFile(legacyId, ownerId, {
+ embedded: true,
+ metadata: {
+ codeEnvRef: {
+ kind: 'user',
+ id: ownerId.toString(),
+ storage_session_id: 'session',
+ file_id: legacyId,
+ },
+ },
+ });
+ const ownerScope = { userId: ownerId.toString(), tenantId: 'tenant-a' };
+
+ const onDefault = await fileMethods.getDeferredProvisionFiles([legacyId], ownerScope, {
+ code: true,
+ codeRouteKey: 'default',
+ });
+ const onStateful = await fileMethods.getDeferredProvisionFiles([legacyId], ownerScope, {
+ code: true,
+ codeRouteKey: 'stateful:b',
+ });
+
+ expect(onDefault).toEqual([]);
+ expect(onStateful.map((file) => file.file_id)).toEqual([legacyId]);
+ });
+
+ it('omits a file that already carries every requested result', async () => {
+ const ownerId = new mongoose.Types.ObjectId();
+ const embeddedId = uuidv4();
+ const provisionedId = uuidv4();
+ const generatedId = uuidv4();
+ await makeFile(embeddedId, ownerId, {
+ embedded: true,
+ metadata: {
+ codeEnvRef: {
+ kind: 'user',
+ id: ownerId.toString(),
+ storage_session_id: 'session',
+ file_id: embeddedId,
+ },
+ },
+ });
+ await makeFile(provisionedId, ownerId, {
+ embedded: true,
+ metadata: {
+ codeEnvRef: {
+ kind: 'user',
+ id: ownerId.toString(),
+ storage_session_id: 'session',
+ file_id: provisionedId,
+ },
+ },
+ });
+ await makeFile(generatedId, ownerId, { context: FileContext.execute_code });
+
+ const results = await fileMethods.getDeferredProvisionFiles(
+ [embeddedId, provisionedId, generatedId],
+ { userId: ownerId.toString(), tenantId: 'tenant-a' },
+ );
+
+ expect(results).toEqual([]);
+ });
+
+ it('returns a search-embedded file when the agent needs code provisioning', async () => {
+ const ownerId = new mongoose.Types.ObjectId();
+ const embeddedOnlyId = uuidv4();
+ await makeFile(embeddedOnlyId, ownerId, { embedded: true });
+
+ const forCode = await fileMethods.getDeferredProvisionFiles(
+ [embeddedOnlyId],
+ { userId: ownerId.toString(), tenantId: 'tenant-a' },
+ { code: true },
+ );
+ const forSearch = await fileMethods.getDeferredProvisionFiles(
+ [embeddedOnlyId],
+ { userId: ownerId.toString(), tenantId: 'tenant-a' },
+ { search: true },
+ );
+
+ expect(forCode.map((file) => file.file_id)).toEqual([embeddedOnlyId]);
+ expect(forSearch).toEqual([]);
+ });
+
+ it('returns a code-provisioned file when the agent needs search provisioning', async () => {
+ const ownerId = new mongoose.Types.ObjectId();
+ const codeOnlyId = uuidv4();
+ await makeFile(codeOnlyId, ownerId, {
+ metadata: {
+ codeEnvRef: {
+ kind: 'user',
+ id: ownerId.toString(),
+ storage_session_id: 'session',
+ file_id: codeOnlyId,
+ },
+ },
+ });
+
+ const forSearch = await fileMethods.getDeferredProvisionFiles(
+ [codeOnlyId],
+ { userId: ownerId.toString(), tenantId: 'tenant-a' },
+ { search: true },
+ );
+ const forCode = await fileMethods.getDeferredProvisionFiles(
+ [codeOnlyId],
+ { userId: ownerId.toString(), tenantId: 'tenant-a' },
+ { code: true },
+ );
+
+ expect(forSearch.map((file) => file.file_id)).toEqual([codeOnlyId]);
+ expect(forCode).toEqual([]);
+ });
+
+ it('does not cross the authenticated owner scope', async () => {
+ const ownerId = new mongoose.Types.ObjectId();
+ const victimId = new mongoose.Types.ObjectId();
+ const victimFileId = uuidv4();
+ await makeFile(victimFileId, victimId);
+
+ const results = await fileMethods.getDeferredProvisionFiles([victimFileId], {
+ userId: ownerId.toString(),
+ tenantId: 'tenant-a',
+ });
+
+ expect(results).toEqual([]);
+ });
+ });
+
+ describe('updateFileCodeEnvRef', () => {
+ const makeRefFile = (fileId: string, ownerId: mongoose.Types.ObjectId) =>
+ runAsSystem(() =>
+ fileMethods.createFile({
+ file_id: fileId,
+ user: ownerId,
+ tenantId: 'tenant-a',
+ conversationId: 'conversation-a',
+ filename: `${fileId}.csv`,
+ filepath: `/uploads/${fileId}.csv`,
+ source: 'local',
+ type: 'text/csv',
+ bytes: 100,
+ context: FileContext.message_attachment,
+ metadata: { sourceDispatchedAt: 42 },
+ }),
+ );
+
+ const ref = (routeKey: string, remoteId: string) => ({
+ kind: 'user' as const,
+ id: 'u1',
+ storage_session_id: `session-${routeKey}`,
+ file_id: remoteId,
+ executionRouteKey: routeKey,
+ });
+
+ it('keeps concurrently written sibling routes', async () => {
+ const ownerId = new mongoose.Types.ObjectId();
+ const fileId = uuidv4();
+ await makeRefFile(fileId, ownerId);
+
+ await Promise.all([
+ runAsSystem(() =>
+ fileMethods.updateFileCodeEnvRef({
+ file_id: fileId,
+ routeKey: 'default',
+ ref: ref('default', 'remote-default'),
+ }),
+ ),
+ runAsSystem(() =>
+ fileMethods.updateFileCodeEnvRef({
+ file_id: fileId,
+ routeKey: 'stateful:a',
+ ref: ref('stateful:a', 'remote-stateful'),
+ }),
+ ),
+ ]);
+
+ const stored = await runAsSystem(() => fileMethods.findFileById(fileId));
+ const refs = stored?.metadata?.codeEnvRefs as Record<string, { file_id: string }> | undefined;
+ expect(refs?.default?.file_id).toBe('remote-default');
+ expect(refs?.['stateful:a']?.file_id).toBe('remote-stateful');
+ });
+
+ it('leaves sibling metadata fields in place', async () => {
+ const ownerId = new mongoose.Types.ObjectId();
+ const fileId = uuidv4();
+ await makeRefFile(fileId, ownerId);
+
+ await runAsSystem(() =>
+ fileMethods.updateFileCodeEnvRef({
+ file_id: fileId,
+ routeKey: 'default',
+ ref: ref('default', 'remote-default'),
+ legacyRef: ref('default', 'remote-default'),
+ }),
+ );
+
+ const stored = await runAsSystem(() => fileMethods.findFileById(fileId));
+ expect(stored?.metadata?.sourceDispatchedAt).toBe(42);
+ expect((stored?.metadata?.codeEnvRef as { file_id: string } | undefined)?.file_id).toBe(
+ 'remote-default',
+ );
+ });
+
+ it('rejects a route key that would write outside its entry', async () => {
+ const ownerId = new mongoose.Types.ObjectId();
+ const fileId = uuidv4();
+ await makeRefFile(fileId, ownerId);
+
+ await expect(
+ runAsSystem(() =>
+ fileMethods.updateFileCodeEnvRef({
+ file_id: fileId,
+ routeKey: 'a.b',
+ ref: ref('a.b', 'remote'),
+ }),
+ ),
+ ).rejects.toThrow(/Invalid code environment route key/);
+ });
+ });
+
describe('getUserCodeFiles', () => {
it('returns only authenticated owner code-env uploads', async () => {
const ownerId = new mongoose.Types.ObjectId();
diff --git a/packages/data-schemas/src/methods/file.ts b/packages/data-schemas/src/methods/file.ts
index 97c704f694..4b262ff06d 100644
--- a/packages/data-schemas/src/methods/file.ts
+++ b/packages/data-schemas/src/methods/file.ts
@@ -1,5 +1,6 @@
import { EToolResources, FileContext } from 'librechat-data-provider';
import type { FilterQuery, SortOrder, Model } from 'mongoose';
+import type { CodeEnvRef } from 'librechat-data-provider';
import type { IMongoFile } from '~/types/file';
import { tenantSafeBulkWrite } from '~/utils/tenantBulkWrite';
import logger from '../config/winston';
@@ -13,6 +14,12 @@ export type ExpiredFileQueryOptions = {
now?: Date;
};
+function assertValidCodeEnvironmentRouteKey(routeKey: string): void {
+ if (routeKey.length === 0 || routeKey.includes('.') || routeKey.startsWith('$')) {
+ throw new Error(`Invalid code environment route key "${routeKey}"`);
+ }
+}
+
function withOwnerScope<T extends FilterQuery<IMongoFile>>(
filter: T,
ownerScope?: FileOwnerScope,
@@ -53,6 +60,17 @@ export function createFileMethods(mongoose: typeof import('mongoose')): {
ownerScope?: FileOwnerScope,
) => Promise<IMongoFile[]>;
getUserCodeFiles: (fileIds: string[], ownerScope: FileOwnerScope) => Promise<IMongoFile[]>;
+ getDeferredProvisionFiles: (
+ fileIds: string[],
+ ownerScope: FileOwnerScope,
+ resources?: {
+ code?: boolean;
+ search?: boolean;
+ codeRouteKey?: string;
+ searchNamespaces?: string[];
+ hydrateProvisioned?: boolean;
+ },
+ ) => Promise<IMongoFile[]>;
claimCodeFile: (data: {
filename: string;
conversationId: string;
@@ -66,6 +84,16 @@ export function createFileMethods(mongoose: typeof import('mongoose')): {
data: Partial<IMongoFile> & { file_id: string },
extraFilter?: FilterQuery<IMongoFile>,
) => Promise<IMongoFile | null>;
+ updateFileCodeEnvRef: (data: {
+ file_id: string;
+ routeKey: string;
+ ref: CodeEnvRef;
+ legacyRef?: CodeEnvRef;
+ }) => Promise<IMongoFile | null>;
+ addFileEmbeddedEntity: (data: {
+ file_id: string;
+ entityId: string;
+ }) => Promise<IMongoFile | null>;
updateFileUsage: (data: {
file_id: string;
inc?: number;
@@ -339,6 +367,136 @@ export function createFileMethods(mongoose: typeof import('mongoose')): {
}
}
+ /**
+ * Retrieves conversation attachments that were accepted but never provisioned, so a
+ * later turn can still queue them.
+ *
+ * Lazy provisioning defers the upload to the sandbox or vector store until a tool
+ * actually runs. The other hydration queries only return files that already carry
+ * the result of that work: `getToolFilesByIds` matches `embedded: true` for
+ * file_search, and `getUserCodeFiles` requires an existing `codeEnvRef`. A file
+ * whose tool was never called on its upload turn therefore satisfies neither and
+ * disappears. This fills exactly that gap: attachments with no code reference and
+ * no embedding.
+ *
+ * Kept separate from delivery hydration deliberately. These records are candidates
+ * for provisioning only; feeding them back into the model's attachments would
+ * re-send earlier uploads on every subsequent turn.
+ *
+ * Selection is per requested resource, not per file. A file embedded for an earlier
+ * file_search agent still has no code reference, so a later execute_code agent must
+ * see it; requiring both results to be absent would hide exactly that case.
+ *
+ * @param fileIds - Candidate file IDs from the current thread
+ * @param ownerScope - Authenticated owner scope
+ * @param resources - Which provisioning results the current agent needs
+ * @returns Attachments still awaiting a result the current agent needs
+ */
+ async function getDeferredProvisionFiles(
+ fileIds: string[],
+ ownerScope: FileOwnerScope,
+ resources: {
+ code?: boolean;
+ search?: boolean;
+ codeRouteKey?: string;
+ searchNamespaces?: string[];
+ /** Set when no other query hydrates already-provisioned files this turn. */
+ hydrateProvisioned?: boolean;
+ } = {
+ code: true,
+ search: true,
+ },
+ ): Promise<IMongoFile[]> {
+ if (!fileIds || fileIds.length === 0) {
+ return [];
+ }
+
+ const missingConditions: FilterQuery<IMongoFile>[] = [];
+ /* When no other query hydrates this turn's files, every eligible record has to be
+ * loaded, not only the unprovisioned ones: priming adds the provisioned ones to the
+ * tool resources, and the code probe screens a default-route session for liveness.
+ * Left behind, a file the previous turn provisioned successfully is the one that
+ * goes missing, while one that failed is retried. This holds for search as much as
+ * for code: an attachment embedded on an earlier turn is hydrated by nothing else,
+ * so the next search runs with no reference to it. */
+ const hydrateEverything =
+ resources.hydrateProvisioned === true &&
+ (resources.code === true || resources.search === true);
+ if (resources.code && !hydrateEverything) {
+ /* A reference for another deployment does not make the file usable here, and with
+ * resendFiles off nothing downstream re-reads the record to notice, so eligibility
+ * is judged against the route this turn will actually execute on. The legacy
+ * pointer counts only when it resolves to that same route, mirroring how
+ * mergeCodeEnvRef keys it: executionRouteKey, then executionProfile, then default. */
+ const routeKey = resources.codeRouteKey ?? 'default';
+ assertValidCodeEnvironmentRouteKey(routeKey);
+ const usableForRoute: FilterQuery<IMongoFile>[] = [
+ { [`metadata.codeEnvRefs.${routeKey}`]: { $exists: true } },
+ { 'metadata.codeEnvRef.executionRouteKey': routeKey },
+ {
+ 'metadata.codeEnvRef': { $exists: true },
+ 'metadata.codeEnvRef.executionRouteKey': { $exists: false },
+ 'metadata.codeEnvRef.executionProfile': routeKey,
+ },
+ ];
+ if (routeKey === 'default') {
+ usableForRoute.push({
+ 'metadata.codeEnvRef': { $exists: true },
+ 'metadata.codeEnvRef.executionRouteKey': { $exists: false },
+ 'metadata.codeEnvRef.executionProfile': { $in: [null, 'default'] },
+ });
+ }
+ missingConditions.push({ $nor: usableForRoute });
+ }
+ if (resources.search && !hydrateEverything) {
+ /* The record-wide flag only says the file was embedded somewhere, so for a record
+ * whose vectors live in an agent namespace it cannot answer whether the namespace
+ * this turn searches has them. Membership is not known here, so a record missing
+ * from any candidate namespace is loaded and judged later, where it is. */
+ const namespaces = resources.searchNamespaces ?? [];
+ if (namespaces.length === 0) {
+ missingConditions.push({ embedded: { $ne: true } });
+ } else {
+ missingConditions.push({
+ $or: [
+ { context: { $ne: FileContext.agents }, embedded: { $ne: true } },
+ ...namespaces.map((namespace) => ({
+ context: FileContext.agents,
+ 'metadata.embeddedEntities': { $ne: namespace },
+ })),
+ ],
+ });
+ }
+ }
+ if (!hydrateEverything && missingConditions.length === 0) {
+ return [];
+ }
+
+ try {
+ const filter = withOwnerScope(
+ {
+ file_id: { $in: fileIds },
+ context: { $ne: FileContext.execute_code },
+ ...(hydrateEverything ? {} : { $or: missingConditions }),
+ },
+ ownerScope,
+ );
+
+ const selectFields: SelectProjection = { text: 0 };
+ const sortOptions = { createdAt: 1 as SortOrder };
+
+ const results = await getFiles(filter, sortOptions, selectFields);
+ return results ?? [];
+ } catch (error) {
+ /* An empty list here is indistinguishable from nothing needing provisioning, so the
+ * turn would build no provisioning state and let the tool run without the
+ * attachment. The callback aborts on missing inputs precisely to avoid that, so a
+ * read failure has to surface rather than be flattened into a benign answer. */
+ logger.error('[getDeferredProvisionFiles] Error retrieving deferred files:', error);
+ throw error;
+ }
+ }
+
/**
* Retrieves user-uploaded execute_code files (not code-generated) by their file IDs.
* These are files with fileIdentifier metadata but context is NOT execute_code (e.g., agents or message_attachment).
@@ -486,6 +644,64 @@ export function createFileMethods(mongoose: typeof import('mongoose')): {
}).lean<IMongoFile>();
}
+ /**
+ * Records one code-environment route pointer without rewriting the rest of `metadata`.
+ * Agents provisioning the same file to different deployments write concurrently, and a
+ * whole-object `$set` built from each caller's pre-provisioning snapshot would drop the
+ * sibling route that landed in between.
+ *
+ * @param data - The file, its route key, the pointer to store, and an optional legacy pointer
+ * @returns A promise that resolves to the updated file document, or null when absent
+ */
+ async function updateFileCodeEnvRef(data: {
+ file_id: string;
+ routeKey: string;
+ ref: CodeEnvRef;
+ legacyRef?: CodeEnvRef;
+ }): Promise<IMongoFile | null> {
+ const { file_id, routeKey, ref, legacyRef } = data;
+ /* Route keys become dotted update paths, so a key carrying `.` or a leading `$` would
+ * write somewhere other than the intended entry. They come from server config, which
+ * makes a malformed one a configuration error worth surfacing. */
+ assertValidCodeEnvironmentRouteKey(routeKey);
+ const File = mongoose.models.File as Model<IMongoFile>;
+ const update: Record<string, CodeEnvRef> = {
+ [`metadata.codeEnvRefs.${routeKey}`]: ref,
+ };
+ if (legacyRef) {
+ update['metadata.codeEnvRef'] = legacyRef;
+ }
+ return File.findOneAndUpdate(
+ { file_id },
+ { $set: update, $unset: { expiresAt: '' } },
+ { new: true },
+ ).lean<IMongoFile>();
+ }
+
+ /**
+ * Records that a file has been embedded into one vector namespace, without disturbing
+ * the namespaces already recorded. Agents that share a file record, as a duplicate does
+ * with its source, each need their own embedding.
+ *
+ * @param data - The file and the entity whose namespace now holds its vectors
+ * @returns A promise that resolves to the updated file document, or null when absent
+ */
+ async function addFileEmbeddedEntity(data: {
+ file_id: string;
+ entityId: string;
+ }): Promise<IMongoFile | null> {
+ const File = mongoose.models.File as Model<IMongoFile>;
+ return File.findOneAndUpdate(
+ { file_id: data.file_id },
+ {
+ $set: { embedded: true },
+ $addToSet: { 'metadata.embeddedEntities': data.entityId },
+ $unset: { expiresAt: '' },
+ },
+ { new: true },
+ ).lean<IMongoFile>();
+ }
+
/**
* Increments the usage of a file identified by file_id.
* @param data - The data to update, must contain file_id and the increment value for usage
@@ -756,9 +972,12 @@ export function createFileMethods(mongoose: typeof import('mongoose')): {
getToolFilesByIds,
getCodeGeneratedFiles,
getUserCodeFiles,
+ getDeferredProvisionFiles,
claimCodeFile,
createFile,
updateFile,
+ updateFileCodeEnvRef,
+ addFileEmbeddedEntity,
updateFileUsage,
deleteFile,
deleteFiles,
diff --git a/packages/data-schemas/src/schema/codeEnvRef.ts b/packages/data-schemas/src/schema/codeEnvRef.ts
index 4069d755d3..ed442d3e44 100644
--- a/packages/data-schemas/src/schema/codeEnvRef.ts
+++ b/packages/data-schemas/src/schema/codeEnvRef.ts
@@ -16,6 +16,7 @@ export const codeEnvRefSchema: Schema = new Schema(
enum: ['default', 'stateful'],
},
executionRouteKey: { type: String },
+ provisionedAt: { type: Number },
},
{ _id: false },
);
diff --git a/packages/data-schemas/src/schema/file.ts b/packages/data-schemas/src/schema/file.ts
index 0b075eef68..9941b590a4 100644
--- a/packages/data-schemas/src/schema/file.ts
+++ b/packages/data-schemas/src/schema/file.ts
@@ -135,6 +135,34 @@ const file: Schema<IMongoFile> = new Schema(
type: Number,
default: undefined,
},
+ /** Vector namespaces this file has been embedded into. Vectors are stored per
+ * entity, so a duplicated agent needs its own embedding even though the record
+ * is shared. */
+ embeddedEntities: {
+ type: [String],
+ default: undefined,
+ },
+ /** The user named this file's destination, through the chooser or by requesting a
+ * tool resource, so the destinations absent from the record were declined rather
+ * than deferred. Unlike the endpoint setting, which the next turn may resolve
+ * differently, the choice belongs to the file. */
+ destinationChosen: {
+ type: Boolean,
+ default: undefined,
+ },
+ /** The type the delivery route was resolved against, kept when conversion changes
+ * the stored type so a later resolution asks the same question. */
+ routingMimeType: {
+ type: String,
+ default: undefined,
+ },
+ },
+ llmDeliveryPath: {
+ /* What upload time inferred about delivery, from the endpoint and MIME type it saw.
+ * Not a contract: the executing agent, its provider and its tools are all decided
+ * per turn, so a reader that needs the real destination resolves it there. */
+ type: String,
+ enum: ['provider', 'text', 'none'],
},
expiresAt: {
/* Short-lived upload TTL managed by MongoDB. This is separate from
diff --git a/packages/data-schemas/src/types/file.ts b/packages/data-schemas/src/types/file.ts
index 0e6b950aa0..bb4e71dd81 100644
--- a/packages/data-schemas/src/types/file.ts
+++ b/packages/data-schemas/src/types/file.ts
@@ -73,7 +73,15 @@ export interface IMongoFile extends Omit<Document, 'model'> {
codeEnvRefs?: CodeEnvRefMap;
/** Dispatch-order stamp for the current source artifact generation. */
sourceDispatchedAt?: number;
+ /** Vector namespaces this file has been embedded into. */
+ embeddedEntities?: string[];
+ /** The user named this destination, so absent ones were declined. */
+ destinationChosen?: boolean;
+ /** The type the delivery route was resolved against, when conversion changed it. */
+ routingMimeType?: string;
};
+ /** Upload-time inference, not a durable contract. See the schema field for why. */
+ llmDeliveryPath?: string;
expiresAt?: Date;
expiredAt?: Date | null;
/**