Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
import { logger } from '@librechat/data-schemas';
import {
EModelEndpoint,
EToolResources,
AgentCapabilities,
FileContext,
FileSources,
getCodeEnvRefs,
canToolResourceConsume,
hasToolResourceDestination,
} 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 { CodeExecutionContext } from './execution';
import type { ServerRequest } from '~/types';
import { getSafeErrorMetadata } from '~/utils/errors';
import { TOOL_RESOURCE_KEYS } from './orphans';
/** Removes runtime-only file records before persisted Agent resources enter tool initialization. */
const sanitizePersistedToolResources = (
tool_resources: AgentToolResources | undefined,
): AgentToolResources => {
const sanitized: AgentToolResources = {};
for (const key of TOOL_RESOURCE_KEYS) {
const resource = tool_resources?.[key];
if (!resource) {
continue;
}
const persistedResource = { ...resource };
delete persistedResource.files;
sanitized[key] = persistedResource;
}
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;
executionProfile?: CodeExecutionContext['executionProfile'];
bridgeWorkerId?: string;
}) => Promise<Set<string>>;
/** Loads CODE_API_KEY for a user. Call once per request. */
export type TLoadCodeApiKey = (userId: string) => Promise<string>;
/**
* Records the agent's namespace on legacy embedded files already confirmed to have vectors
* there, and returns the ids it recorded.
*/
export type TAdoptLegacySearchEmbeddings = (params: {
files: Array<{ file_id: string; user: string; tenantId?: string }>;
agentId: string;
}) => Promise<string[]>;
/**
* Whether the vector store holds chunks of a file in an entity's namespace. Records from
* before namespaces were tracked say only that a file was embedded somewhere, so this is
* the evidence that decides whether embedding it again would store a second copy.
*/
export type THasEntityEmbeddings = (params: {
userId: string;
file_id: string;
entity_id: string;
query: string;
timeoutMs?: number;
}) => Promise<boolean>;
/** How long priming waits on a legacy File Search check before embedding the file anyway. */
const DEFAULT_LEGACY_SEARCH_PROBE_TIMEOUT_MS = 5000;
/** 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[];
/** Names from cleared refs on this state's active route; never reusable storage pointers. */
codeEnvRecoveryNames?: Map<string, { name: string; isTargetScope: boolean }>;
/** Destination names advertised to the model before lazy code-file provisioning. */
codeEnvDestinations?: Map<string, string>;
/** 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>;
/** Files an attached workspace's attachment note already describes; the queued-file note
* leaves them out rather than pointing at a second location. */
describedFileIds?: Set<string>;
};
/**
* Function type for retrieving files from the database
* @param filter - MongoDB filter query for files
* @param _sortOptions - Sorting options (currently unused)
* @param selectFields - Field selection options
* @returns Promise resolving to array of files
*/
export type TGetFiles = (
filter: FilterQuery<IMongoFile>,
_sortOptions: ProjectionType<IMongoFile> | null | undefined,
selectFields: QueryOptions<IMongoFile> | null | undefined,
) => Promise<Array<TFile>>;
/**
* Function type for filtering files by agent access permissions.
* Used to enforce that only files the user has access to (via ownership or agent attachment)
* are returned after a raw DB query.
*/
export type TFilterFilesByAgentAccess = (params: {
files: Array<TFile>;
userId: string;
role?: string;
agentId: string;
}) => Promise<Array<TFile>>;
/**
* Helper function to add a file to a specific tool resource category
* Prevents duplicate files within the same resource category
* @param params - Parameters object
* @param params.file - The file to add to the resource
* @param params.resourceType - The type of tool resource (e.g., execute_code, file_search, image_edit)
* @param params.tool_resources - The agent's tool resources object to update
* @param params.processedResourceFiles - Set tracking processed files per resource type
*/
export const addFileToResource = ({
file,
resourceType,
tool_resources,
processedResourceFiles,
}: {
file: TFile;
resourceType: EToolResources;
tool_resources: AgentToolResources;
processedResourceFiles: Set<string>;
}): void => {
if (!file.file_id) {
return;
}
const resourceKey = `${resourceType}:${file.file_id}`;
if (processedResourceFiles.has(resourceKey)) {
return;
}
const resource = tool_resources[resourceType as keyof AgentToolResources] ?? {};
if (!resource.files) {
(tool_resources[resourceType as keyof AgentToolResources] as AgentBaseResource) = {
...resource,
files: [],
};
}
// Check if already exists in the files array
const resourceFiles = tool_resources[resourceType as keyof AgentToolResources]?.files;
const alreadyExists = resourceFiles?.some((f: TFile) => f.file_id === file.file_id);
if (!alreadyExists) {
resourceFiles?.push(file);
processedResourceFiles.add(resourceKey);
}
};
/** 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, unless
* the vector store confirms the vectors are already there (see isUnrecordedSearchFile).
*/
const isEmbeddedForNamespace = (file: TFile, namespaceId?: string): boolean => {
if (!isAgentScopedFile(file)) {
return file.embedded === true;
}
return namespaceId != null && file.metadata?.embeddedEntities?.includes(namespaceId) === true;
};
/**
* Whether an embedded File Search file of the active agent records no embedding for its
* namespace. Records from before namespaces were tracked can hold vectors there regardless:
* a file another agent embedded first lists only that agent, while this agent's own older
* vectors went unrecorded. Only the vector store can say; see THasEntityEmbeddings.
*/
const isUnrecordedSearchFile = (
file: TFile,
agentId: string,
membership?: ReadonlyMap<EToolResources, ReadonlySet<string>>,
): boolean =>
isAgentScopedFile(file) &&
file.embedded === true &&
!isEmbeddedForNamespace(file, agentId) &&
file.file_id != null &&
membership?.get(EToolResources.file_search)?.has(file.file_id) === 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:
* - execute_code: Files with a code-environment ref (`codeEnvRef`)
* - file_search: Files marked as embedded
* - image_edit: Image files in the request file set with dimensions
* @param params - Parameters object
* @param params.file - The file to categorize
* @param params.tool_resources - The agent's tool resources to update
* @param params.requestFileSet - Set of file IDs from the current request
* @param params.processedResourceFiles - Set tracking processed files per resource type
*/
const categorizeFileForToolResources = ({
file,
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({
file,
resourceType: EToolResources.execute_code,
tool_resources,
processedResourceFiles,
});
}
/* 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 (
requestFileSet.has(file.file_id) &&
file.type.startsWith('image') &&
file.height &&
file.width
) {
addFileToResource({
file,
resourceType: EToolResources.image_edit,
tool_resources,
processedResourceFiles,
});
}
};
/**
* Primes resources for agent execution by processing attachments and tool resources
* This function:
* 1. Fetches context/OCR files (filtered by agent access control when available)
* 2. Processes attachment files
* 3. Categorizes files into appropriate tool resources
* 4. Prevents duplicate files across all sources
*
* @param params - Parameters object
* @param params.req - Express request object
* @param params.appConfig - Application configuration object
* @param params.getFiles - Function to retrieve files from database
* @param params.filterFiles - Optional function to enforce agent-based file access control
* @param params.requestFileSet - Set of file IDs from the current request
* @param params.attachments - Promise resolving to array of attachment files
* @param params.tool_resources - Existing tool resources for the agent
* @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,
codeExecutionProfile,
codeBridgeWorkerId,
agentScopedFileIds,
persistedResourceMembership,
adoptLegacySearchEmbeddings,
hasEntityEmbeddings,
legacySearchProbeTimeoutMs = DEFAULT_LEGACY_SEARCH_PROBE_TIMEOUT_MS,
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;
/** Wire profile and worker of that deployment, which decide the probe's auth. */
codeExecutionProfile?: CodeExecutionContext['executionProfile'];
codeBridgeWorkerId?: 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>>;
adoptLegacySearchEmbeddings?: TAdoptLegacySearchEmbeddings;
hasEntityEmbeddings?: THasEntityEmbeddings;
legacySearchProbeTimeoutMs?: number;
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;
};
/* Search intent survives vector cleanup without claiming the vectors still exist.
* A chooser's other destinations remain declined unless membership or a copy proves them. */
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 || hasToolResourceDestination(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;
}
/* Started before the liveness probe, with which it shares nothing. Adoption only spares a
* re-embed, so a failure at any step leaves the files queued rather than failing priming. */
const legacySearchFiles =
needsVectorDB && agentId != null && resourcePrincipal?.id != null
? provisionable.filter((file) =>
isUnrecordedSearchFile(file, agentId, persistedResourceMembership),
)
: [];
const adoptLegacy = async (): Promise<Set<string>> => {
if (
agentId == null ||
resourcePrincipal?.id == null ||
!hasEntityEmbeddings ||
!adoptLegacySearchEmbeddings
) {
return new Set();
}
const present = await Promise.all(
legacySearchFiles.map((file) =>
hasEntityEmbeddings({
userId: resourcePrincipal.id as string,
file_id: file.file_id,
entity_id: agentId,
query: file.filename || file.file_id,
timeoutMs: legacySearchProbeTimeoutMs,
}).catch((error) => {
logger.error(
`[primeResources] Could not check legacy embeddings for file ${file.file_id}`,
getSafeErrorMetadata(error),
);
return false;
}),
),
);
const confirmed = legacySearchFiles.filter((_file, index) => present[index]);
if (confirmed.length === 0) {
return new Set();
}
/* The vector store has confirmed the vectors, so this turn uses them whether or not the
* namespace is recorded; recording only spares the next turn the same check. */
await adoptLegacySearchEmbeddings({
files: confirmed.map((file) => ({
file_id: file.file_id,
user: String(file.user),
...(file.tenantId ? { tenantId: file.tenantId } : {}),
})),
agentId,
}).catch((error) => {
logger.error(
'[primeResources] Failed to record legacy File Search namespaces',
getSafeErrorMetadata(error),
);
});
return new Set(confirmed.map((file) => file.file_id));
};
const legacyAdoption: Promise<Set<string>> =
legacySearchFiles.length > 0
? adoptLegacy().catch((error) => {
logger.error(
'[primeResources] Failed to adopt legacy File Search embeddings',
getSafeErrorMetadata(error),
);
return new Set<string>();
})
: Promise.resolve(new Set<string>());
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. The
* legacy key authorizes only the default Code API, so another route never loads it. */
let codeApiKey: string | undefined;
if (
filesWithIdentifiers.length > 0 &&
activeCodeRouteKey === 'default' &&
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,
executionProfile: codeExecutionProfile,
bridgeWorkerId: codeBridgeWorkerId,
staleSafeWindowMs,
});
}
const adopted = await legacyAdoption;
for (const file of provisionable) {
if (agentId != null && adopted.has(file.file_id)) {
const recorded = new Set(file.metadata?.embeddedEntities ?? []);
recorded.add(agentId);
file.metadata = { ...file.metadata, embeddedEntities: [...recorded] };
}
}
const scopedIds = agentScopedFileIds ?? new Set<string>();
const codeEnvFiles: TFile[] = [];
const codeEnvRecoveryNames: NonNullable<ProvisionState['codeEnvRecoveryNames']> = new Map();
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;
const routeRef = codeEnvRefForRoute(file, activeCodeRouteKey);
/* Liveness answers only for the route it was probed on, so a ref belonging to
* another deployment is never cleared on the strength of this turn's answer. */
const isStale = routeRef != null && aliveFileIds != null && !aliveFileIds.has(file.file_id);
/** Staleness must be repaired even for files that pre-categorization already
* added to execute_code resources, so the check runs before the processed
* guard. Clear both the legacy ref and its route entry, else getCodeEnvRefs
* keeps resolving the dead session over the re-provisioned one. */
if (isStale) {
if (routeRef?.sandboxFilename) {
codeEnvRecoveryNames.set(file.file_id, {
name: routeRef.sandboxFilename,
isTargetScope: hasCodeRefForRoute(file, activeCodeRouteKey, codeScope),
});
}
logger.info(
`[primeResources] Code env file expired for "${file.filename}" (${file.file_id}), will re-provision on tool use`,
);
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,
codeEnvRecoveryNames,
vectorDBFiles,
aliveFileIds: aliveFileIds ?? new Set(),
agentScopedFileIds: new Set(scopedIds),
};
};
export const primeResources = async ({
req,
principal,
appConfig,
getFiles,
filterFiles,
requestFileSet,
attachments: _attachments,
tool_resources: _tool_resources,
agentId,
enabledToolResources,
checkSessionsAlive,
loadCodeApiKey,
provisionCandidates,
screenPersistentFiles,
adoptLegacySearchEmbeddings,
hasEntityEmbeddings,
codeRouteKey,
codeBaseUrl,
codeExecutionProfile,
codeBridgeWorkerId,
}: {
req?: ServerRequest;
principal?: Pick<IUser, 'id' | 'role'>;
appConfig?: AppConfig;
requestFileSet: Set<string>;
attachments: Promise<Array<TFile | null>> | undefined;
tool_resources: AgentToolResources | undefined;
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>;
/** Records the agent's namespace on legacy File Search embeddings confirmed to be there. */
adoptLegacySearchEmbeddings?: TAdoptLegacySearchEmbeddings;
/** Asks the vector store whether a legacy file's chunks are in the agent's namespace. */
hasEntityEmbeddings?: THasEntityEmbeddings;
/** 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;
/** Wire profile and worker of that deployment. The probe authenticates to it the way
* its uploads and executions do, so a worker-bound route gets a worker-bound bearer. */
codeExecutionProfile?: CodeExecutionContext['executionProfile'];
codeBridgeWorkerId?: 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
* Pre-populated with files from non-OCR tool_resources to prevent re-adding them
*/
const attachmentFileIds = new Set<string>();
/**
* Set tracking which files have been added to specific tool resource categories
* Format: "resourceType:fileId" (e.g., "execute_code:file123")
* Prevents the same file from being added multiple times to the same resource
*/
const processedResourceFiles = new Set<string>();
/**
* The agent's tool resources object that will be updated with categorized files
* 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)) {
if (!resource) {
continue;
}
// Deep copy the resource to avoid mutations
tool_resources[resourceType as keyof AgentToolResources] = {
...resource,
// Deep copy arrays to prevent mutations
...(resource.files && { files: [...resource.files] }),
...(resource.file_ids && { file_ids: [...resource.file_ids] }),
...(resource.vector_store_ids && { vector_store_ids: [...resource.vector_store_ids] }),
} as AgentBaseResource;
// Now track existing files
if (resource.files && Array.isArray(resource.files)) {
for (const file of resource.files) {
if (file?.file_id) {
processedResourceFiles.add(`${resourceType}:${file.file_id}`);
// Files from non-context resources should not be added to attachments from _attachments
if (resourceType !== EToolResources.context && resourceType !== EToolResources.ocr) {
attachmentFileIds.add(file.file_id);
}
}
}
}
}
const isContextEnabled = (
appConfig?.endpoints?.[EModelEndpoint.agents]?.capabilities ?? []
).includes(AgentCapabilities.context);
const fileIds = tool_resources[EToolResources.context]?.file_ids ?? [];
const ocrFileIds = tool_resources[EToolResources.ocr]?.file_ids;
if (ocrFileIds != null) {
fileIds.push(...ocrFileIds);
delete tool_resources[EToolResources.ocr];
}
const shouldLoadContext = fileIds.length > 0 && isContextEnabled;
const contextFileIds = new Set(shouldLoadContext ? fileIds : []);
const imageEditFileIds = tool_resources[EToolResources.image_edit]?.file_ids ?? [];
const imageEditFileIdSet = new Set(imageEditFileIds);
const persistedResourceFileIds = new Set(contextFileIds);
for (const fileId of imageEditFileIds) {
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];
}
let persistedResourceFiles: Array<TFile> = [];
if (persistedResourceFileIds.size > 0) {
persistedResourceFiles = await getFiles(
{
file_id: { $in: Array.from(persistedResourceFileIds) },
},
{},
{},
);
if (filterFiles && resourcePrincipal?.id && agentId) {
persistedResourceFiles = await filterFiles({
files: persistedResourceFiles,
userId: resourcePrincipal.id,
role: resourcePrincipal.role,
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) {
if (!file?.file_id) {
continue;
}
if (contextFileIds.has(file.file_id)) {
attachmentFileIds.delete(file.file_id);
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)) {
addFileToResource({
file,
resourceType: EToolResources.image_edit,
tool_resources,
processedResourceFiles,
});
attachmentFileIds.add(file.file_id);
}
}
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,
codeExecutionProfile,
codeBridgeWorkerId,
agentScopedFileIds: persistedResourceFileIds,
persistedResourceMembership,
adoptLegacySearchEmbeddings,
hasEntityEmbeddings,
legacySearchProbeTimeoutMs: appConfig?.fileConfig?.legacySearchProbeTimeoutMs,
staleSafeWindowMs: appConfig?.fileConfig?.codeEnvLivenessSafeWindowMs,
});
return {
attachments: attachments.length > 0 ? attachments : undefined,
requestAttachments: undefined,
agentContextAttachments:
agentContextAttachments.length > 0 ? agentContextAttachments : undefined,
tool_resources,
provisionState: contextProvisionState,
warnings,
};
}
const files = await _attachments;
const requestAttachmentFileIds = new Set<string>();
for (const file of files) {
if (!file) {
continue;
}
categorizeFileForToolResources({
file,
tool_resources,
requestFileSet,
processedResourceFiles,
userId: resourcePrincipal?.id,
});
if (file.file_id && attachmentFileIds.has(file.file_id)) {
if (!requestAttachmentFileIds.has(file.file_id)) {
requestAttachments.push(file);
requestAttachmentFileIds.add(file.file_id);
}
continue;
}
attachments.push(file);
if (!file.file_id || !requestAttachmentFileIds.has(file.file_id)) {
requestAttachments.push(file);
}
if (file.file_id) {
attachmentFileIds.add(file.file_id);
requestAttachmentFileIds.add(file.file_id);
}
}
const provisionState = await computeProvisionState({
req,
attachments: withDeferredCandidates(attachments, [
...(provisionCandidates ?? []),
...resourceProvisionCandidates,
]),
resourcePrincipal,
enabledToolResources,
tool_resources,
processedResourceFiles,
checkSessionsAlive,
loadCodeApiKey,
agentId,
codeRouteKey,
codeBaseUrl,
codeExecutionProfile,
codeBridgeWorkerId,
agentScopedFileIds: persistedResourceFileIds,
persistedResourceMembership,
adoptLegacySearchEmbeddings,
hasEntityEmbeddings,
legacySearchProbeTimeoutMs: appConfig?.fileConfig?.legacySearchProbeTimeoutMs,
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);
// Safely try to get attachments without rethrowing
let safeAttachments: Array<TFile | undefined> = [];
if (_attachments) {
try {
const attachmentFiles = await _attachments;
safeAttachments = (attachmentFiles?.filter((file) => !!file) ?? []) as Array<TFile>;
} catch (attachmentError) {
// If attachments promise is also rejected, just use empty array
logger.error('Error resolving attachments in catch block', attachmentError);
safeAttachments = [];
}
}
return {
attachments: safeAttachments,
requestAttachments: safeAttachments,
agentContextAttachments:
agentContextAttachments.length > 0 ? agentContextAttachments : undefined,
tool_resources: safeToolResources,
provisionState: undefined,
warnings: [],
};
}
};