🚚 feat: Route Attachments and Provision Tools Lazily (#15763)

This commit is contained in:
Danny Avila 2026-09-08 23:28:52 -04:00 • committed by GitHub
parent e6376f6df4
commit ec15075dc8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
112 changed files with 12570 additions and 478 deletions

View file

@ -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.

View file

@ -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', () => {

View file

@ -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

View file

@ -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();

View file

@ -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

View file

@ -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 =

View file

@ -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 }),

View file

@ -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,6 +72,19 @@ import {
isContentTraversalProtected,
isContentTraversalLimitError,
} from '../protection/adapters/nested';
import {
optionalChainWithEmptyCheck,
extractLibreChatParams,
getSafeErrorMetadata,
getModelMaxTokens,
getThreadData,
} from '~/utils';
import {
isCodeFileToolName,
registerCodeExecutionTools,
registerFileAuthoringTools,
isFileAuthoringToolDefinition,
} from './tools';
import {
normalizeServerName,
requiresEphemeralUserConnection,
@ -75,17 +96,6 @@ import {
resolveCodeExecutionContext,
type CodeExecutionContext,
} from './execution';
import {
optionalChainWithEmptyCheck,
extractLibreChatParams,
getModelMaxTokens,
getThreadData,
} from '~/utils';
import {
registerCodeExecutionTools,
registerFileAuthoringTools,
isFileAuthoringToolDefinition,
} from './tools';
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

File diff suppressed because it is too large Load diff

View file

@ -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: [],
};
}
};

View file

@ -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',

View file

@ -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>,

View file

@ -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);
});
});

View file

@ -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) {
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 };
}
const agent = await getAgent({ id: agentId });
if (!agent) {
return { allowed: false, status: 404, error: 'Not Found', message: 'Agent not found' };
}
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;
}

View file

@ -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 });

View file

@ -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');
});
});

View file

@ -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,

View file

@ -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);

View file

@ -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 */

View file

@ -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++) {

View file

@ -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';

View file

@ -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();
});
});

View file

@ -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;
};
}

View file

@ -0,0 +1,2 @@
export * from './service';
export * from './callback';

View file

@ -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);
});
});
});

View file

@ -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,
};
}

View file

@ -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([]);
});
});

View file

@ -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);
}
}

View file

@ -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');
});
});

View file

@ -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;
}

View file

@ -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' } },

View file

@ -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);

View file

@ -624,6 +624,7 @@ describe('CloudFront CRUD', () => {
expect(mockGetS3FileStream).toHaveBeenCalledWith(
mockReq,
'https://d123.cloudfront.net/images/u/f.webp',
undefined,
);
expect(result).toBe(readable);
});

View file

@ -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. */

View file

@ -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}`);
}