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 { Providers } from '@librechat/agents';
import { logger } from '@librechat/data-schemas';
import {
Tools,
Constants,
ErrorTypes,
EModelEndpoint,
EToolResources,
canToolResourceConsume,
paramEndpoints,
isAgentsEndpoint,
AgentCapabilities,
resolveAllowedStatefulCodeEnvironments,
hasActivePiiFields,
hasActivePiiPatterns,
replaceSpecialVars,
providerEndpointMap,
normalizeEndpointName,
} from 'librechat-data-provider';
import type {
AgentToolResources,
AgentToolOptions,
TEndpointOption,
ReasoningResponseKey,
StatefulCodeEnvironment,
TurnDeliveryRouting,
ImageDetail,
TFile,
Agent,
TUser,
TurnFileConsumers,
} from 'librechat-data-provider';
import type { GenericTool, LCToolRegistry, ToolMap, LCTool } from '@librechat/agents';
import type { AppConfig, IMongoFile, FileOwnerScope } from '@librechat/data-schemas';
import type { Request, Response as ServerResponse } from 'express';
import type {
TFileUpdate,
ProvisionState,
TFilterFilesByAgentAccess,
TProvisionToCodeEnv,
TProvisionToVectorDB,
TAdoptLegacySearchEmbeddings,
THasEntityEmbeddings,
TCheckSessionsAlive,
TLoadCodeApiKey,
} from './resources';
import type {
ResolvedManualSkill,
ResolvedAlwaysApplySkill,
ResolvedSkillCatalog,
TListSkillsByAccess,
TGetSkillByName,
} from './skills';
import type {
ServerRequest,
RequestBody,
EndpointDbMethods,
EndpointTokenConfig,
InitializeResultBase,
} from '~/types';
import type { ResolveLinkedInstructions, LinkedInstructionsFacts } from './instructions/linked';
import type { LCAvailableTools, RequestScopedMCPConnectionStore } from '../mcp/types';
import type { ContentTraversalLimitError } from '../protection/adapters/nested';
import type { SkillContentInput } from '../protection/adapters/submissions';
import type { RepositoryInstructionSource } from '../code/instructions';
import type { ResolvedChatProjectContext } from '../projects/context';
import type { TextContentFragment } from '../protection/types';
import type { CheckAccessParams } from '../middleware/access';
import type { GetProjectFiles } from '../projects/resources';
import type { CodeContextEntry } from '~/files/code/priming';
import type { MCPToolAlias } from '~/tools/classification';
import type { CodeExecutionContext } from './execution';
import type { AgentExecutionContext } from './runtime';
import {
injectSkillCatalog,
resolveSkillCatalog,
resolveManualSkills,
resolveAlwaysApplySkills,
selectSkillPrimesForTurn,
unionPrimeAllowedTools,
MAX_PRIMED_SKILLS_PER_TURN,
} from './skills';
import {
resolveChatProjectFiles,
resolveChatProjectPolicyFiles,
toCanonicalProjectResource,
toRuntimeFile,
} from '../projects/resources';
import {
getContentTraversalFragments,
isContentTraversalProtected,
isContentTraversalLimitError,
} from '../protection/adapters/nested';
import {
optionalChainWithEmptyCheck,
extractLibreChatParams,
getSafeErrorMetadata,
getModelMaxTokens,
getThreadData,
} from '~/utils';
import {
isCodeFileToolName,
registerCodeExecutionTools,
registerFileAuthoringTools,
isFileAuthoringToolDefinition,
} from './tools';
import {
normalizeServerName,
requiresEphemeralUserConnection,
splitMCPToolKey,
normalizeAgentToolKeys,
} from '~/mcp/utils';
import {
resolveAttachedWorkspaceCommandTimeoutMax,
resolveAttachedWorkspaceCommandTimeoutDefault,
} from '~/code/command';
import {
resolveAgentInferenceParameters,
restoreAgentInferenceInput,
retainAgentInferenceInput,
} from './inference';
import {
formatChatProjectInstructions,
hydrateChatProjectContextResources,
} from '../projects/context';
import { assertChatProjectInstructions, ChatProjectResourcesChangedError } from '../projects/turn';
import { extractAgentContent, extractSkillContent } from '../protection/adapters/submissions';
import { createConfiguredContentInspector, inspectContent } from '../protection/runtime';
import { assertAgentAttachmentLimits, isModelBoundAttachmentFile } from './attachments';
import { assertModelBoundContent } from '../middleware/modelBoundContent';
import { resolveAttachedWorkspaceReadFileLines } from '~/code/workspace';
import { isValidInstructionsPromptLink } from './instructions/linked';
import { PARTIAL_RESOLVED_CONVERSATION } from './conversationSymbols';
import { registerMemoryTools, memoryToolUsageGuard } from './memory';
import { isImplicitStatefulCodeRouteAvailable } from '~/code/config';
import { applyIntentLabels, sanitizeIntentLabels } from './intent';
import { prepareQueuedCodeFileContext } from '~/files/code/queued';
import { ContentFilterError } from '../middleware/contentFilter';
import { resolveToolRoleGrants } from '~/tools/rolePermissions';
import { createRequestAgentExecutionContext } from './runtime';
import { resolveTurnDeliveryRouting } from './files/delivery';
import { filterFilesByEndpointRuntimeConfig } from '~/files';
import { isFatalAgentInitializationError } from './errors';
import { assertToolOptionsWithinLimits } from './options';
import { hasActiveFilePolicy } from '../protection/files';
import { resolveAgentCodeExecution } from '~/code/agent';
import { hasActiveFileFieldPolicy } from '~/protection';
import { applyBackgroundToolCalls } from './background';
import { admitCurrentFileBudget } from './files/budget';
import { applyTurnDelivery } from './files/delivery';
import { generateArtifactsPrompt } from '~/prompts';
import { getAgentInferencePolicy } from './input';
import { getProviderConfig } from '~/endpoints';
import { primeResources } from './resources';
import { pinAgentModel } from './pin';
/**
* Fraction of context budget reserved as headroom when no explicit maxContextTokens is set.
* Reduced from 0.10 to 0.05 alongside the introduction of summarization, which actively
* 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[] = [];
const seen = new Set<string>();
for (const file of files) {
if (file.file_id != null) {
if (seen.has(file.file_id)) continue;
seen.add(file.file_id);
}
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 = [
'gemini-3-flash-preview',
'gemini-3-pro-preview',
'gemini-3.1-flash-lite',
'gemini-3.1-pro-preview',
];
const googleToolCombinationExcludedModalityRegex =
/(?:^|-)image(?:-|$)|(?:^|-)live(?:-|$)|(?:^|-)tts(?:-|$)/;
function assertResolvedSkillContentAllowed(
skills: readonly SkillContentInput[],
filters: NonNullable<ServerRequest['config']>['filters'] | undefined,
): void {
const pii = filters?.skills?.pii;
if (!hasActivePiiPatterns(pii) || skills.length === 0) {
return;
}
const inspectionSession = createConfiguredContentInspector({ filters })?.createSession();
if (inspectionSession == null) {
return;
}
const selectedFields = pii?.fields == null ? null : new Set<string>(pii.fields);
const selected = (field: string): boolean => selectedFields == null || selectedFields.has(field);
const traversalErrors: ContentTraversalLimitError[] = [];
let firstFinding: ReturnType<typeof inspectionSession.inspect> = null;
for (const skill of skills) {
const projected: SkillContentInput = {
...(selected('name') && { name: skill.name }),
...(selected('display_title') && { displayTitle: skill.displayTitle }),
...(selected('description') && { description: skill.description }),
...(selected('category') && { category: skill.category }),
...(selected('instructions') && {
body: skill.body,
instructions: skill.instructions,
}),
...(selected('imported_text') && { importedText: skill.importedText }),
...(selected('frontmatter') && { frontmatter: skill.frontmatter }),
...((selected('file_name') || selected('file_text')) && {
files: skill.files?.map((file) => ({
...(selected('file_name') && { name: file?.name, filename: file?.filename }),
...(selected('file_text') && { text: file?.text, content: file?.content }),
})),
}),
};
let fragments: readonly TextContentFragment[];
try {
fragments = extractSkillContent(projected);
} catch (error) {
if (!isContentTraversalLimitError(error)) {
throw error;
}
fragments = getContentTraversalFragments(error);
traversalErrors.push(error);
}
const finding = inspectionSession.inspect(fragments);
if (finding != null) {
firstFinding ??= finding;
if (!inspectionSession.hasAuditRules) {
throw new ContentFilterError(finding);
}
}
}
if (firstFinding != null) {
throw new ContentFilterError(firstFinding);
}
const protectedTraversal = traversalErrors.find((error) =>
isContentTraversalProtected({ error, filters }),
);
if (protectedTraversal != null) {
throw protectedTraversal;
}
}
function hasTemporalSpecialVars(text: string): boolean {
return temporalSpecialVarRegex.test(text);
}
function appendAdditionalInstructions(agent: Agent, text?: string | null): void {
if (text == null || text === '') {
return;
}
agent.additional_instructions = [agent.additional_instructions ?? '', text]
.filter(Boolean)
.join('\n\n');
}
function appendProjectContextInstructions(
agent: Agent,
context: ResolvedChatProjectContext | null | undefined,
): void {
const instruction = formatChatProjectInstructions(context);
if (instruction === '' || agent.additional_instructions?.includes(instruction)) {
return;
}
appendAdditionalInstructions(agent, instruction);
}
function addProjectFilesToFileSearch(
resources: AgentToolResources | undefined,
files: readonly TFile[] | undefined,
effectiveToolNames: readonly string[],
appConfig: AppConfig | undefined,
fileSearchAvailable?: boolean,
provisionState?: ProvisionState,
): { resources: AgentToolResources | undefined; provisionState?: ProvisionState } {
if (files == null || files.length === 0) {
return { resources, provisionState };
}
const capabilities = appConfig?.endpoints?.[EModelEndpoint.agents]?.capabilities ?? [];
if (!capabilities.includes(AgentCapabilities.file_search)) {
return { resources, provisionState };
}
if (fileSearchAvailable === false) {
return { resources, provisionState };
}
if (!effectiveToolNames.includes(Tools.file_search)) {
return { resources, provisionState };
}
const current = resources?.[EToolResources.file_search] ?? {};
const currentFiles = current.files ?? [];
const seen = new Set(currentFiles.map((file) => file.file_id));
const projectFiles: TFile[] = [];
const queuedIds = new Set(provisionState?.vectorDBFiles.map((file) => file.file_id));
for (const file of files) {
if (!seen.has(file.file_id)) {
projectFiles.push(file);
seen.add(file.file_id);
}
if (
file.embedded === true ||
file.metadata?.searchDestination !== true ||
!canToolResourceConsume(EToolResources.file_search, file.type) ||
queuedIds.has(file.file_id)
) {
continue;
}
provisionState ??= {
codeEnvFiles: [],
vectorDBFiles: [],
aliveFileIds: new Set(),
agentScopedFileIds: new Set(),
};
provisionState.vectorDBFiles.push(file);
queuedIds.add(file.file_id);
}
if (projectFiles.length === 0) {
return { resources, provisionState };
}
return {
provisionState,
resources: {
...(resources ?? {}),
[EToolResources.file_search]: {
...current,
files: currentFiles.concat(projectFiles),
},
},
};
}
async function resolveRuntimeProjectFiles({
context,
scope,
getProjectFiles,
filters,
}: {
context: ResolvedChatProjectContext;
scope: FileOwnerScope;
getProjectFiles: GetProjectFiles;
filters?: AppConfig['filters'];
}): Promise<TFile[]> {
const files = await resolveChatProjectFiles({
project: context,
resources: context.resources,
userId: scope.userId,
tenantId: scope.tenantId ?? undefined,
getProjectFiles,
});
if (!hasActiveFilePolicy(filters) || files.length === 0) {
return files;
}
const policyFiles = await resolveChatProjectPolicyFiles({
project: { file_ids: files.map((file) => file.file_id) },
userId: scope.userId,
tenantId: scope.tenantId ?? undefined,
getProjectFiles,
});
const admittedById = new Map(context.resources.map((resource) => [resource.file_id, resource]));
if (policyFiles.length !== files.length) {
throw new ChatProjectResourcesChangedError();
}
for (const file of policyFiles) {
const admitted = admittedById.get(file.file_id);
const current = toCanonicalProjectResource(file);
if (
admitted?.availability !== 'ready' ||
current.availability !== 'ready' ||
current.identity !== admitted.identity ||
current.version !== admitted.version
) {
throw new ChatProjectResourcesChangedError();
}
}
assertModelBoundContent({ filters, files: policyFiles });
return policyFiles.map(toRuntimeFile);
}
/**
* The request middleware already read this conversation once (`null` = looked up, absent).
* A stored document without `files` genuinely has none; only the branded lineage-only
* partial from a bound agent-event continuation cannot speak for the database.
*/
export function readResolvedConversationFiles(
runtime: Pick<AgentExecutionContext, 'resolvedConversation'>,
conversationId: string,
): string[] | undefined {
if (!Object.prototype.hasOwnProperty.call(runtime, 'resolvedConversation')) {
return undefined;
}
const resolved = runtime.resolvedConversation;
if (resolved === null) {
return [];
}
if (
resolved == null ||
resolved.conversationId !== conversationId ||
(resolved as Record<symbol, unknown>)[PARTIAL_RESOLVED_CONVERSATION] === true
) {
return undefined;
}
return resolved.files ?? [];
}
export interface ResolveResendToolResourcesParams {
/** Tool names as configured on the agent. */
tools?: string[] | null;
/** `execute_code` capability AND the caller's `RUN_CODE` grant. */
codeEnvAvailable: boolean;
/**
* `file_search` capability AND the caller's `FILE_SEARCH` grant. `undefined`
* where the caller resolved neither, which leaves priming as it was.
*/
fileSearchAvailable?: boolean;
}
/**
* Tool resources whose prior-turn files this run re-hydrates on resend.
*
* Both role-gated tools are filtered here rather than after hydration, because
* priming is not free: the files are read, their usage counters are bumped, and
* they are primed into `tool_resources` for a tool the loader is about to drop.
* Each flag is the deployment capability AND the role grant, so this reaches the
* same verdict the loader will.
*/
export function resolveResendToolResources({
tools,
codeEnvAvailable,
fileSearchAvailable,
}: ResolveResendToolResourcesParams): Set<EToolResources> {
const toolResourceSet = new Set<EToolResources>();
for (const tool of tools ?? []) {
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]);
}
}
return toolResourceSet;
}
function getMaxCatalogSkills(runtime: AgentExecutionContext): number | undefined {
const endpoints = runtime.appConfig?.endpoints as
| Record<string, { skills?: { maxCatalogSkills?: number } } | undefined>
| undefined;
return endpoints?.[EModelEndpoint.agents]?.skills?.maxCatalogSkills;
}
function getToolName(tool: unknown): string | undefined {
if (tool == null || typeof tool !== 'object') {
return undefined;
}
const { name } = tool as { name?: unknown };
return typeof name === 'string' ? name : undefined;
}
function hasToolDefinition(toolDefinitions: LCTool[] | undefined, name: string): boolean {
return toolDefinitions?.some((toolDefinition) => toolDefinition.name === name) === true;
}
function hasGoogleSearchTool(tool: unknown): boolean {
if (tool == null || typeof tool !== 'object') {
return false;
}
return 'googleSearch' in tool || 'googleSearchRetrieval' in tool;
}
/**
* Whether a provider-built tool is that provider's own web search.
*
* Each provider spells it differently — OpenAI `{ type: 'web_search' }`, Anthropic
* `{ type: 'web_search_20250305', name: 'web_search' }`, Google `{ googleSearch: {} }` —
* and the tool is already built by the time it reaches here, so the shape is what
* identifies it rather than the parameter that asked for it.
*/
function isProviderWebSearchTool(tool: unknown): boolean {
if (tool == null || typeof tool !== 'object') {
return false;
}
if (hasGoogleSearchTool(tool)) {
return true;
}
if (getToolName(tool) === Tools.web_search) {
return true;
}
const { type } = tool as { type?: unknown };
return typeof type === 'string' && type.startsWith(Tools.web_search);
}
/**
* Removes OpenRouter's web-search plugin from a built LLM config.
*
* OpenRouter does not receive web search as a tool — `getOpenAIConfig` encodes it
* as `modelKwargs.plugins: [{ id: 'web' }]` and pushes no tool at all — so the
* provider-tool filter has nothing to strip on that path and the plugin would
* still reach the provider for a role that was denied.
*/
function stripWebSearchPlugin(llmConfig: Record<string, unknown>): number {
const modelKwargs = llmConfig.modelKwargs as { plugins?: unknown } | undefined;
if (modelKwargs == null || !Array.isArray(modelKwargs.plugins)) {
return 0;
}
const plugins = modelKwargs.plugins as Array<{ id?: unknown }>;
const remaining = plugins.filter((plugin) => !isWebSearchPlugin(plugin));
const removed = plugins.length - remaining.length;
if (removed === 0) {
return 0;
}
if (remaining.length > 0) {
modelKwargs.plugins = remaining;
} else {
delete modelKwargs.plugins;
}
return removed;
}
function isWebSearchPlugin(plugin: unknown): boolean {
return (plugin as { id?: unknown } | null)?.id === 'web';
}
/**
* Whether a built provider config turns native web search on, as a tool or as
* OpenRouter's plugin.
*
* Read from the builder's output rather than from `model_parameters.web_search`:
* the parameter is one of several inputs — an endpoint's `defaultParams`,
* `customParams` defaults and `addParams` all reach the same switch, and
* `addParams` is applied last — so the output is the only place every route
* has already converged.
*/
function hasProviderWebSearch(
tools: unknown[] | undefined,
llmConfig: Record<string, unknown>,
): boolean {
if (tools?.some(isProviderWebSearchTool) === true) {
return true;
}
const plugins = (llmConfig.modelKwargs as { plugins?: unknown } | undefined)?.plugins;
return Array.isArray(plugins) && plugins.some(isWebSearchPlugin);
}
/**
* Resolves the `WEB_SEARCH` grant for provider-native search.
*
* A caller-supplied resolver wins, so a route that memoizes grants on its own
* request — and reaches here with `runtime` and no `req` — joins that read
* instead of issuing another. Without one, the grant is resolved for `user`
* through `db.getRoleByName`; with neither there is no role to consult.
*
* Fails closed: a resolver that throws denies.
*/
async function resolveWebSearchGrant({
req,
user,
resolve,
getRoleByName,
}: {
req?: Request;
user?: CheckAccessParams['user'] | null;
resolve?: () => Promise<boolean>;
getRoleByName?: CheckAccessParams['getRoleByName'];
}): Promise<boolean> {
try {
if (resolve != null) {
return await resolve();
}
if (getRoleByName == null) {
return true;
}
const grants = await resolveToolRoleGrants({
req,
user,
getRoleByName,
context: 'initializeAgent',
});
return grants.webSearch;
} catch {
logger.error(
`[initializeAgent][User: ${user?.id}] Failed to resolve the WEB_SEARCH grant; denying provider-native web search`,
);
return false;
}
}
function normalizeGoogleModelName(model: string): string {
const normalized = model.trim().toLowerCase();
return normalized.split('/').pop() ?? normalized;
}
function isKnownGoogleToolCombinationTextModel(model: string): boolean {
return googleToolCombinationTextModels.some(
(knownModel) => model === knownModel || model.startsWith(`${knownModel}-`),
);
}
function isGemini35OrLater(model: string): boolean {
const match = geminiModelVersionRegex.exec(model);
if (!match) {
return false;
}
const major = Number(match[1]);
const minor = Number(match[2] ?? '0');
return major > 3 || (major === 3 && minor >= 5);
}
function supportsGoogleToolCombination(model: unknown): boolean {
if (typeof model !== 'string') {
return false;
}
const normalized = normalizeGoogleModelName(model);
if (googleToolCombinationExcludedModalityRegex.test(normalized)) {
return false;
}
return isKnownGoogleToolCombinationTextModel(normalized) || isGemini35OrLater(normalized);
}
function isGoogleToolCombinationProvider(provider?: string): boolean {
return provider === Providers.GOOGLE || provider === Providers.VERTEXAI;
}
function shouldIncludeGoogleServerSideToolInvocations({
provider,
hasProviderTools,
hasAgentTools,
}: {
provider?: string;
hasProviderTools: boolean;
hasAgentTools: boolean;
}): boolean {
return isGoogleToolCombinationProvider(provider) && hasProviderTools && hasAgentTools;
}
function assertGoogleToolCombinationSupport(model: unknown): void {
if (!supportsGoogleToolCombination(model)) {
throw new Error(`{ "type": "${ErrorTypes.GOOGLE_TOOL_CONFLICT}"}`);
}
}
function enableGoogleServerSideToolInvocations({
agent,
llmConfig,
}: {
agent: Agent;
llmConfig: Record<string, unknown>;
}): void {
llmConfig.includeServerSideToolInvocations = true;
if (agent.model_parameters) {
(agent.model_parameters as Record<string, unknown>).includeServerSideToolInvocations = true;
}
}
function resolveProviderToolConflicts({
provider,
tools,
toolDefinitions,
webSearchDenied = false,
}: {
provider?: string;
tools?: unknown[];
toolDefinitions?: LCTool[];
/**
* Whether the build turned native web search on for a role that denies
* `WEB_SEARCH.USE`. The built tool is stripped, which holds however the build
* was asked for it.
*/
webSearchDenied?: boolean;
}): unknown[] | undefined {
if (!tools?.length) {
return tools;
}
if (!webSearchDenied && !hasToolDefinition(toolDefinitions, Tools.web_search)) {
return tools;
}
const shouldRemoveTool = (tool: unknown): boolean => {
if (webSearchDenied) {
return isProviderWebSearchTool(tool);
}
if (provider === Providers.ANTHROPIC) {
return getToolName(tool) === Tools.web_search;
}
if (provider === Providers.GOOGLE || provider === Providers.VERTEXAI) {
return hasGoogleSearchTool(tool);
}
return false;
};
let removed = 0;
const resolvedTools = tools.filter((tool) => {
const shouldRemove = shouldRemoveTool(tool);
if (shouldRemove) {
removed += 1;
}
return !shouldRemove;
});
if (removed > 0) {
logger.debug(
webSearchDenied
? `[initializeAgent] Removed ${removed} ${provider} native web search tool(s); role denies WEB_SEARCH.`
: `[initializeAgent] Removed ${removed} ${provider} native web search tool(s); LibreChat web_search is enabled.`,
);
}
return resolvedTools;
}
/**
* Extended agent type with additional fields needed after initialization
*/
export type InitializedAgent = Agent & {
/** Request-resolved Azure identity for self-summarization; never persisted on the agent. */
azureOptions?: InitializeResultBase['azureOptions'];
tools: GenericTool[];
/** @deprecated use requestAttachments or agentContextAttachments based on sharing semantics. */
attachments: IMongoFile[];
/** Message files admitted for this agent, including historical files when resend is enabled. */
requestAttachments: IMongoFile[];
/** Only hydrated attachments from the current request; excludes history and agent setup files. */
currentRequestAttachments: TFile[];
/** Files attached to this agent's permanent context via tool_resources. */
agentContextAttachments: IMongoFile[];
/** File-reading tools this turn runs, which decide when a tool-routed file falls back to text. */
fileConsumers?: TurnFileConsumers;
toolContextMap: Record<string, unknown>;
dynamicToolContextMap?: Record<string, unknown>;
maxContextTokens: number;
/** Pre-ratio context budget (agentMaxContextNum - maxOutputTokensNum). Used by createRun to apply a configurable reserve ratio. */
baseContextTokens?: number;
useLegacyContent: boolean;
resendFiles: boolean;
/** Detail level LibreChat encodes image content blocks with, from the agent's
* model parameters. Absent when the agent does not configure one. */
imageDetail?: ImageDetail;
/** How this agent receives its attachments this turn, settled once every routing input is final. */
deliveryRouting: TurnDeliveryRouting;
tool_resources?: AgentToolResources;
userMCPAuthMap?: Record<string, Record<string, string>>;
/** Tool map for ToolNode to use when executing tools (required for PTC) */
toolMap?: ToolMap;
/** Tool registry for PTC and tool search (only present when MCP tools with env classification exist) */
toolRegistry?: LCToolRegistry;
/** Run-scoped MCP tool definitions for request-scoped servers. */
mcpAvailableTools?: Record<string, LCAvailableTools>;
/** Run-scoped MCP connections for request-scoped servers. */
requestScopedConnections?: RequestScopedMCPConnectionStore;
/** Serializable tool definitions for event-driven execution */
toolDefinitions?: LCTool[];
/** Both-direction identity aliases for MCP tools whose key spelling changed */
mcpToolAliases?: MCPToolAlias[];
/** Precomputed flag indicating if any tools have defer_loading enabled (for efficient runtime checks) */
hasDeferredTools?: boolean;
/**
* Names of this agent's tools that were injected with the `run_in_background`
* param (capability enabled AND per-tool opt-in AND eligible). Threaded to the
* tool executor via `configurable` so it can enforce the per-tool background
* opt-in and gate the `check_background_task` poll tool at execution time.
*/
backgroundToolNames?: string[];
/**
* Names of this agent's tools that received the host-injected `intent`
* param (capability enabled AND opted in AND eligible). Threaded to the
* tool executor via `configurable` so the arg is stripped before invoking
* tools that don't declare it, and stripped from schemas a self-spawn
* child or PTC sandbox inherits. SDK-native intent schemas are the tools'
* own and are never listed here.
*/
intentToolNames?: string[];
/** Marker-verified tool names whose model-authored intent labels are safe compaction guidance. */
semanticIntentToolNames?: string[];
/** Tool names whose unverified schemas veto global semantic-intent trust for same-name calls. */
semanticIntentBlockedToolNames?: string[];
/** Whether the inline memory tools (`set_memory`/`delete_memory`) were
* registered for this agent. Authoritative LibreChat-only signal of the
* inline memory opt-in for the execution path, since some contexts hold the
* initialized config (the `memory` marker already expanded out of `tools`)
* rather than the raw agent document. */
memoryToolsRegistered?: boolean;
/** Whether the actions capability is enabled (resolved during tool loading) */
actionsEnabled?: boolean;
/**
* The COMPLETE accessible-server audit this initialization resolved (via
* the agent-key or skill-prime heal). Retained so deferred/event-driven
* execution reuses the same snapshot instead of repeating the merged
* registry read — a transient failure there would fail-closed a tool the
* turn already advertised from the successful first audit.
*/
accessibleMcpServerNames?: readonly string[];
/** Maximum characters allowed in a single tool result before truncation. */
maxToolResultChars?: number;
/** Response field to read model reasoning from for custom OpenAI-compatible endpoints. */
reasoningKey?: ReasoningResponseKey;
/** Whether to reconstruct `reasoning_content` from persisted history across turns (custom endpoint opt-in). */
includeReasoningHistory?: boolean;
/**
* Whether the code-execution environment is available *for this agent*.
* Narrower than the incoming `params.codeEnvAvailable` admin flag — this
* is `admin_capability_enabled && agent.tools.includes('execute_code')`,
* computed once here so downstream code (`injectSkillCatalog`,
* `enrichWithSkillConfigurable`, `primeInvokedSkills`) doesn't have to
* re-scan the tool list on every runtime handler invocation.
* Authoritative for both persisted and ephemeral agents: the
* ephemeral-agent toggle is reconciled into `agent.tools` upstream
* (`packages/api/src/agents/added.ts`), so the check is uniform.
*/
codeEnvAvailable: boolean;
/**
* Whether stateful code sessions are active *for this agent*: the admin
* `stateful_code_sessions` capability AND the agent's builder opt-in
* (`agent.stateful_code_sessions`) AND `codeEnvAvailable`. Resolved once
* here and carried with the agent so execution routing never needs a
* graph-global stateful flag.
*/
statefulCodeSessions: boolean;
/** Sharing scope for this agent's stateful code environment. */
statefulCodeEnvironment: Agent['stateful_code_environment'];
/** Trusted partition for transient code session ids and file references. */
codeSessionKey: string;
/** Trusted endpoint/profile context for artifact processing and runtime tools. */
codeExecutionContext: CodeExecutionContext;
/** Whether host-side skill file authoring is available for this agent/run. */
skillAuthoringAvailable: boolean;
/** Host-side file authoring tool names registered for this run. */
fileAuthoringToolNames?: Set<string>;
/** Accessible skill IDs for ACL checking at execute time */
accessibleSkillIds?: import('mongoose').Types.ObjectId[];
/**
* Names of skills the runtime can resolve, mirroring `accessibleSkillIds`.
* Surfaced to the runtime so handlers like `read_file` can decide if a
* `{firstSegment}/...` path refers to a real skill (vs. a code-env path
* that should be routed to the bash fallback) without an extra DB lookup.
*/
activeSkillNames?: Set<string>;
/** Number of skills in the catalog (used to determine if SkillTool should be registered) */
skillCount?: number;
/**
* Skills the user manually invoked for this turn via the `$` popover, resolved
* to their SKILL.md bodies. The AgentClient injects these as meta user
* messages right before the latest user message in the LLM's formatted
* message array — deterministic priming without a tool roundtrip.
*/
manualSkillPrimes?: ResolvedManualSkill[];
/**
* Skills auto-primed this turn because their `always-apply` frontmatter
* flag is set. Resolved against the same `accessibleSkillIds` set and
* subjected to the same active-state / ACL filters as the catalog, then
* handed to the AgentClient for splicing alongside manual primes. Their
* `allowedTools` entries also union into the agent's effective tool set
* via `unionPrimeAllowedTools` (same pipeline as manual primes).
*/
alwaysApplySkillPrimes?: ResolvedAlwaysApplySkill[];
/**
* Pre-uploaded code-env file refs from `tool_resources.execute_code`
* (carries the conversation's prior-turn generated artifacts and any
* user uploads). Captured by the `loadTools` callback; the AgentClient
* merges these across all run agents into `Graph.sessions[EXECUTE_CODE]`
* before run start so the very first `execute_code` / `bash_tool` call
* sees them as `_injected_files`. Without this seed the agents-side
* `CodeExecutor` falls back to `/files/{session_id}` — but `session_id`
* is itself only populated by a previous successful execution, so on
* call #1 the sandbox can't see the files at all.
*/
primedCodeFiles?: import('@librechat/agents').CodeEnvFile[];
/** Files the primed code-file note described on an attached workspace, so the note can be
* rebuilt once attachments are copied in (`primeWorkspaceAttachments`). */
codeContextEntries?: CodeContextEntry[];
/**
* Resolved token/pricing config for this agent's endpoint (admin static
* `tokenConfig` and/or fetched custom-endpoint config). Surfaced from the
* provider `getOptions` result so the AgentClient bills, prices, and resolves
* 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;
/** Facts about a resolved `instructionsPrompt` link, shaped per source. Never persisted. */
instructionsPromptFacts?: LinkedInstructionsFacts;
};
export const DEFAULT_MAX_CONTEXT_TOKENS = 32000;
/**
* Parameters for initializing an agent
* Matches the CJS signature from api/server/services/Endpoints/agents/agent.js
*/
export interface InitializeAgentParams {
/** Cancellation signal owned by the run performing initialization. */
signal?: AbortSignal;
/** Explicit transport-free execution state. */
runtime?: AgentExecutionContext;
/** Request-backed compatibility adapter for callers not yet migrated. */
req?: ServerRequest;
/** Deprecated response adapter retained only for source compatibility. */
res?: ServerResponse;
/** Agent to initialize */
agent: Agent;
/** Conversation ID (optional) */
conversationId?: string | null;
/** Parent message ID for determining the current thread (optional) */
parentMessageId?: string | null;
/** Normalized body used by MCP runtime placeholders during tool discovery. */
requestBody?: RequestBody;
/** Request files */
requestFiles?: IMongoFile[];
/** Host-authorized, hydrated inputs for an isolated execution. Suppresses parent history reads. */
authorizedRunFiles?: readonly TFile[];
/** Function to load agent tools */
loadTools?: (params: {
provider: string;
agentId: string;
tools: string[];
model: string | null;
tool_options: AgentToolOptions | undefined;
tool_resources: AgentToolResources | undefined;
requestBody?: RequestBody;
/** Trusted endpoint/profile resolved for this agent before any code-file priming. */
codeExecutionContext: CodeExecutionContext;
/** The conversation's "No workspace" decision removed this agent's code tools. */
attachedEnvironmentOptOut?: boolean;
/** Full accessible MCP server names (operator + user DB) when the heal
* already fetched them — lets execution-side collision guards see
* cross-tier shadowing without another registry round-trip. */
accessibleMcpServerNames?: readonly string[];
}) => Promise<{
/** Full tool instances (only present when definitionsOnly=false) */
tools?: GenericTool[];
toolContextMap?: Record<string, unknown>;
dynamicToolContextMap?: Record<string, unknown>;
userMCPAuthMap?: Record<string, Record<string, string>>;
toolRegistry?: LCToolRegistry;
mcpAvailableTools?: Record<string, LCAvailableTools>;
requestScopedConnections?: RequestScopedMCPConnectionStore;
/** Serializable tool definitions for event-driven mode */
toolDefinitions?: LCTool[];
hasDeferredTools?: boolean;
mcpToolAliases?: MCPToolAlias[];
actionsEnabled?: boolean;
/** Action tool names backed by OAuth — excluded from background dispatch. */
oauthActionToolNames?: string[];
/**
* Pre-uploaded code-env file refs for the agent's
* `tool_resources.execute_code`. Bubbled up so the run host can seed
* `Graph.sessions[EXECUTE_CODE]` before the first tool call —
* otherwise `_injected_files` is empty on call #1 and prior-turn
* artifacts don't reach the sandbox.
*/
primedCodeFiles?: import('@librechat/agents').CodeEnvFile[];
/** Structured form of the primed code-file note on an attached workspace. */
codeContextEntries?: CodeContextEntry[];
/** Live workspace binding resolved by the execution-side loader. */
codeExecutionContext?: CodeExecutionContext;
repositoryInstructionSource?: RepositoryInstructionSource;
} | null>;
/** Endpoint option (contains model_parameters and endpoint info) */
endpointOption?: Partial<TEndpointOption>;
/** Set of allowed providers */
allowedProviders: Set<string>;
/** Whether this is the initial agent */
isInitialAgent?: boolean;
/** Enables authoritative ChatProject guidance/resources for conversation graph agents. */
useChatProjectContext?: boolean;
/** Accessible skill IDs for this user (pre-computed by the caller via ACL query) */
accessibleSkillIds?: import('mongoose').Types.ObjectId[];
/** Whether skill file authoring should be exposed even before a user has viewable skills. */
skillAuthoringAvailable?: boolean;
/** Whether the code execution environment is available (execute_code capability enabled) */
codeEnvAvailable?: boolean;
/**
* Whether `file_search` is available to this caller — the capability AND the
* `FILE_SEARCH` role grant. Read only when re-hydrating a conversation's
* prior-turn files: `false` skips priming resources for a tool the loader will
* drop anyway. Absent leaves priming unconditional, so a caller that has not
* resolved the grant keeps its current behavior.
*/
fileSearchAvailable?: boolean;
/**
* Resolves this caller's `WEB_SEARCH` role grant for provider-native web search.
* Called only when the built provider config turns native search on, so an
* agent without it costs no role read. Callers that reach `initializeAgent`
* with `runtime` and no `req` — the OpenAI-compatible and Responses routes,
* and the embedder surface in `agents/openai/service.ts` — pass one that joins
* the grants their request already memoizes. Absent, the grant is resolved
* from `db.getRoleByName`.
*/
resolveWebSearchGrant?: () => Promise<boolean>;
/** With none supplied, a linked agent falls back to empty instructions. */
resolveLinkedInstructions?: ResolveLinkedInstructions;
/**
* Whether resolving `agent.instructionsPrompt` should record a usage
* generation on the linked prompt group. Defaults to `true`. Callers on the
* resume path set this to `false` because the turn that already counted the
* generation is being replayed, not repeated.
*/
recordLinkedPromptUsage?: boolean;
/**
* Whether the `run_in_background` capability is enabled for this run. When
* true, tools the agent opted in via `tool_options[name].run_in_background`
* (plus the background-native code pair, unless explicitly opted out) get a
* `run_in_background` schema param and the `check_background_task` poll
* tool is registered.
*/
backgroundToolsAvailable?: boolean;
/**
* Whether the `tool_intents` capability is enabled for this run. When true,
* tools opted in via `tool_options[name].describe_intent` (native host
* tools default on) get an `intent` string injected as the FIRST schema
* property, rendered by the client as the call's live status label.
*/
toolIntentsAvailable?: boolean;
/** Whether stateful code sessions are available (stateful_code_sessions capability enabled) */
statefulSessionsAvailable?: boolean;
/** Explicit deployment allowlist for request types that do not carry LibreChat config on req. */
allowedStatefulCodeEnvironments?: readonly StatefulCodeEnvironment[];
/** Whether inline memory tools are available (memory capability enabled, memory
* configured, and the user permitted). When true and the agent lists the `memory`
* capability, `set_memory` + `delete_memory` are registered for the LLM. */
memoryAvailable?: boolean;
/** Per-user skill active/inactive overrides for filtering the skill catalog. */
skillStates?: Record<string, boolean>;
/** Admin-configured default for shared skills (`true` = shared skills auto-activate). */
defaultActiveOnShare?: boolean;
/**
* Skill names the user invoked manually for this turn via the `$` popover.
* Resolved here (ACL + active-state filtered) and attached to the returned
* InitializedAgent as `manualSkillPrimes` for the AgentClient to inject as
* meta user messages before the LLM call.
*/
manualSkills?: string[];
}
/**
* Database methods required for agent initialization
* Most methods come from data-schemas via createMethods()
* getConvoFiles not yet in data-schemas but included here for consistency
*/
export interface InitializeAgentDbMethods extends EndpointDbMethods {
/**
* Names of every MCP server the user can reach (operator config + user DB).
* Consulted by the legacy-key heal ONLY when a configured name needs
* normalization: collision detection must see user-DB servers, or healing a
* raw key could produce a key that direct-first resolution routes to a
* different (DB) server. Optional — without it the heal falls back to the
* operator-config names.
*/
getAccessibleMcpServerNames?: (userId?: string, role?: string) => Promise<string[]>;
/** Update usage tracking for multiple files */
updateFilesUsage: (
files: Array<{ file_id: string }>,
fileIds?: string[],
options?: { user?: string; tenantId?: string | null },
) => Promise<unknown[]>;
/** Get owner-scoped project files with optional content. */
getProjectFiles: GetProjectFiles;
/** Get files from database */
getFiles: (filter: unknown, sort: unknown, select: unknown) => Promise<unknown[]>;
/** Filter files by agent access permissions (ownership or agent attachment) */
filterFilesByAgentAccess?: TFilterFilesByAgentAccess;
/** Get tool files by IDs (user-uploaded files only, code files handled separately) */
getToolFilesByIds: (
fileIds: string[],
toolSet: Set<EToolResources>,
ownerScope?: FileOwnerScope,
) => Promise<unknown[]>;
/** Get conversation file IDs */
getConvoFiles: (conversationId: string) => Promise<string[] | null>;
/** Get code-generated files by conversation ID and the file_ids
* referenced from messages in the current thread (collected via
* `messages.files[].file_id` during thread walk). */
getCodeGeneratedFiles?: (
conversationId: string,
threadFileIds?: string[],
ownerScope?: FileOwnerScope,
) => 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 },
select?: string,
) => Promise<Array<{
messageId: string;
parentMessageId?: string;
files?: Array<{ file_id: string }>;
}> | null>;
/** List skill summaries for catalog injection (paginated, omits body/frontmatter) */
listSkillsByAccess?: TListSkillsByAccess;
/** Load a single skill by name, constrained to an ACL-accessible ID set. */
getSkillByName?: TGetSkillByName;
/**
* Load accessible skills with `alwaysApply: true`, eagerly including
* `body` so the priming pipeline can splice at turn start without a
* per-skill round-trip. Cursor-paginated so the resolver can fill its
* active-state budget even when early-sorted rows are inactive for
* the current user.
*/
listAlwaysApplySkills?: (params: {
accessibleIds: import('mongoose').Types.ObjectId[];
limit: number;
cursor?: string | null;
}) => Promise<{
skills: Array<{
_id: import('mongoose').Types.ObjectId;
name: string;
body: string;
author: import('mongoose').Types.ObjectId;
allowedTools?: string[];
/** True for deployment-directory skills that are loaded in memory. */
deployment?: boolean;
}>;
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: record the agent's namespace on legacy File Search embeddings confirmed there */
adoptLegacySearchEmbeddings?: TAdoptLegacySearchEmbeddings;
/** Optional: ask the vector store whether a file's chunks are in an entity's namespace */
hasEntityEmbeddings?: THasEntityEmbeddings;
/** Optional: load CODE_API_KEY once per request */
loadCodeApiKey?: TLoadCodeApiKey;
/** Optional: persist file metadata updates after provisioning */
updateFile?: (data: TFileUpdate) => Promise<unknown>;
/** Resolves a role by name for the tool role-permission grants. Optional: when
* absent the role half of the web-search gate is not applied. */
getRoleByName?: CheckAccessParams['getRoleByName'];
}
/**
* Initializes an agent for use in requests.
* Handles file processing, tool loading, provider configuration, and context token calculations.
*
* This function is exported from @librechat/api and replaces the CJS version from
* api/server/services/Endpoints/agents/agent.js
*
* @param params - Initialization parameters
* @param deps - Optional dependency injection for testing
* @returns Promise resolving to initialized agent with tools and configuration
* @throws Error if agent provider is not allowed or if required dependencies are missing
*/
export async function initializeAgent(
params: InitializeAgentParams,
db?: InitializeAgentDbMethods,
): Promise<InitializedAgent> {
const {
agent: suppliedAgent,
loadTools,
requestFiles = [],
authorizedRunFiles,
conversationId,
endpointOption,
parentMessageId,
requestBody,
allowedProviders,
isInitialAgent = false,
useChatProjectContext,
} = params;
const runtime =
params.runtime ?? (params.req ? createRequestAgentExecutionContext(params.req) : null);
if (runtime == null) {
throw new Error('initializeAgent requires an explicit execution context');
}
const shouldUseChatProjectContext =
useChatProjectContext ?? params.req?.chatProjectContextEnabled === true;
assertToolOptionsWithinLimits(suppliedAgent.tool_options);
const inputAgent = restoreAgentInferenceInput(suppliedAgent);
const agent = shouldUseChatProjectContext ? { ...inputAgent } : inputAgent;
const { user, appConfig } = runtime;
const requestFileOwnerId = user?.id;
const requestFileOwnerScope: FileOwnerScope | undefined = requestFileOwnerId
? { userId: requestFileOwnerId, tenantId: user?.tenantId }
: undefined;
if (shouldUseChatProjectContext && runtime.chatProjectContext?.instructions.trim()) {
assertChatProjectInstructions({
context: runtime.chatProjectContext,
filters: appConfig?.filters,
});
appendProjectContextInstructions(agent, runtime.chatProjectContext);
}
if (!db) {
throw new Error('initializeAgent requires db methods to be passed');
}
/**
* Computed up front, before the definition-content check below, because
* that check needs it: a valid link means the stored inline `instructions`
* is dead text — it is overwritten below with the resolved prompt, or with
* `''` when the link can't resolve — so it is excluded from the scan
* rather than inspected and then discarded.
*/
const instructionsPromptLink = isValidInstructionsPromptLink(agent.instructionsPrompt)
? agent.instructionsPrompt
: undefined;
/**
* Reject the stored agent definition before initialization performs usage
* accounting, resource priming, tool/MCP loading, or provider setup. Inspect
* definition fragments directly here: the raw agent may still contain
* canonical file IDs that can only be validated after resource hydration.
*/
let agentFragments: readonly TextContentFragment[] = [];
let agentTraversalError: ContentTraversalLimitError | null = null;
const agentDefinitionInput = (instructionsPromptLink
? { ...agent, instructions: undefined }
: agent) as unknown as Parameters<typeof extractAgentContent>[0];
try {
agentFragments = extractAgentContent(agentDefinitionInput);
} catch (error) {
if (!isContentTraversalLimitError(error)) {
throw error;
}
agentFragments = getContentTraversalFragments(error);
agentTraversalError = error;
}
const agentDefinitionFinding = inspectContent(agentFragments, {
filters: appConfig?.filters,
});
if (agentDefinitionFinding != null) {
throw new ContentFilterError(agentDefinitionFinding);
}
if (
agentTraversalError != null &&
isContentTraversalProtected({
error: agentTraversalError,
filters: appConfig?.filters,
})
) {
throw agentTraversalError;
}
/**
* Independent of every other step below (tool loading, resource priming,
* provider setup), so it starts as soon as the definition-content check
* above has passed — rather than waiting until the instructions block,
* well below, is reached — but never before that check: a rejected agent
* definition must never trigger an external prompt-service call. A valid
* link with no resolver never calls out, matching the "no resolver"
* fallback this same shape has always had.
*/
const linkedInstructionsPromise =
instructionsPromptLink && params.resolveLinkedInstructions
? params.resolveLinkedInstructions({
link: instructionsPromptLink,
signal: params.signal,
filters: appConfig?.filters,
config: appConfig?.endpoints?.agents?.linkedInstructions,
})
: undefined;
/**
* Started well before its result is needed at the instructions block below.
* An abort (or any other rejection) that lands before that await must not
* surface as an unhandled rejection; this no-op handler only silences that
* warning — the promise itself, awaited later, still carries the real
* outcome, rejection included.
*/
linkedInstructionsPromise?.catch(() => {});
/**
* Heal legacy MCP tool keys ONCE, before anything reads them: model-facing
* keys embed the normalized server name (cache keys, definition names,
* runtime instance names), so an agent document persisted with raw-named
* keys would neither load those tools nor have any of its per-tool
* `tool_options` honored. Every downstream consumer — the tool loader, the
* defer/programmatic classification, the background and intent passes —
* reads `agent.tools` / `agent.tool_options` after this point.
*/
const configRawServerNames = Object.keys(appConfig?.mcpConfig ?? {});
const configNeedsNormalization = configRawServerNames.some(
(name) => normalizeServerName(name) !== name,
);
/**
* Rewriting legacy keys requires a COMPLETE collision audit: the normalized
* form of an operator name may belong to a user-DB server, and healing into
* that key would route the tool to the wrong server. The audit therefore
* uses the full accessible set — fetched lazily, once, and ONLY when a
* configured name actually needs normalization AND the caller has
* delimiter-bearing keys to heal (a non-MCP agent never pays the lookup).
* When the audit cannot complete (no dep, or a transient failure), healing
* is SKIPPED entirely: un-healed raw keys still resolve through the
* direct-first candidates, so skipping is safe while rewriting is not.
*/
let healNamesPromise: Promise<readonly string[] | null> | undefined;
const resolveHealNames = (): Promise<readonly string[] | null> => {
if (!configNeedsNormalization) {
return Promise.resolve(configRawServerNames);
}
if (db.getAccessibleMcpServerNames == null) {
return Promise.resolve(null);
}
healNamesPromise ??= db
.getAccessibleMcpServerNames(user?.id, user?.role)
/** The merged registry read tolerates config-server init failures and
* can silently omit config-only servers; the snapshot-derived config
* names restore them so the audit stays genuinely complete. */
.then((names): readonly string[] => [...new Set([...names, ...configRawServerNames])])
.catch((error): null => {
logger.warn(
'[initializeAgent] Failed to resolve accessible MCP server names; skipping legacy-key healing (collision audit unavailable):',
error,
);
return null;
});
return healNamesPromise;
};
const hasMCPKeyCandidates =
(agent.tools ?? []).some(
(tool) => typeof tool === 'string' && tool.includes(Constants.mcp_delimiter),
) || Object.keys(agent.tool_options ?? {}).some((key) => key.includes(Constants.mcp_delimiter));
/**
* The COMPLETE audit set actually resolved this initialization — from the
* agent-key heal or the skill-prime heal — threaded to the tool loader so
* its collision guards neither repeat the lookup nor mistake the
* operator-only list for a complete audit.
*/
let resolvedAuditNames: readonly string[] | undefined;
if (hasMCPKeyCandidates) {
const mcpHealNames = await resolveHealNames();
if (mcpHealNames != null) {
resolvedAuditNames = mcpHealNames;
const healedKeys = normalizeAgentToolKeys({
tools: agent.tools ?? undefined,
toolOptions: agent.tool_options,
rawServerNames: mcpHealNames,
});
agent.tools = healedKeys.tools;
agent.tool_options = healedKeys.toolOptions;
}
}
/**
* An agent saved under another spelling of a folded endpoint name (`Ollama`) runs on the
* endpoint the runtime serves (`ollama`). Folded once, before anything keys on it: the
* `allowedProviders` check (served names, `normalizeEndpointReferences`), provider setup,
* user key lookups and token configs all read the served name.
*/
const servedProvider = normalizeEndpointName(agent.provider);
if (servedProvider !== agent.provider) {
agent.provider = servedProvider;
}
if (
isAgentsEndpoint(endpointOption?.endpoint) &&
allowedProviders.size > 0 &&
!allowedProviders.has(agent.provider)
) {
throw new Error(
`{ "type": "${ErrorTypes.INVALID_AGENT_PROVIDER}", "info": "${agent.provider}" }`,
);
}
/**
* Manual and always-apply skill resolution is read-only. Resolve and inspect
* those exact model-bound skill bodies before file usage/resource priming or
* tool loading, then reuse the results below when expanding allowed tools.
*/
const hasSkillAccess = (params.accessibleSkillIds?.length ?? 0) > 0;
const skillAuthoringAvailable = params.skillAuthoringAvailable === true;
let manualSkillPrimes: ResolvedManualSkill[] | undefined;
let alwaysApplySkillPrimes: ResolvedAlwaysApplySkill[] | undefined;
let extraAllowedToolNames: string[] = [];
let perSkillExtras: Map<string, string[]> = new Map();
let resolvedSkillCatalog: ResolvedSkillCatalog | undefined;
if (hasSkillAccess) {
const [manualPrimesResult, alwaysApplyPrimesResult, catalogResult] = await Promise.all([
params.manualSkills?.length && db.getSkillByName
? resolveManualSkills({
names: params.manualSkills,
getSkillByName: db.getSkillByName,
accessibleSkillIds: params.accessibleSkillIds!,
userId: user?.id,
skillStates: params.skillStates,
defaultActiveOnShare: params.defaultActiveOnShare,
})
: Promise.resolve<ResolvedManualSkill[] | undefined>(undefined),
db.listAlwaysApplySkills
? resolveAlwaysApplySkills({
listAlwaysApplySkills: db.listAlwaysApplySkills,
accessibleSkillIds: params.accessibleSkillIds!,
userId: user?.id,
skillStates: params.skillStates,
defaultActiveOnShare: params.defaultActiveOnShare,
})
: Promise.resolve<ResolvedAlwaysApplySkill[] | undefined>(undefined),
hasActivePiiFields(appConfig?.filters?.skills?.pii, ['name', 'description'])
? resolveSkillCatalog({
accessibleSkillIds: params.accessibleSkillIds!,
listSkillsByAccess: db.listSkillsByAccess,
userId: user?.id,
skillStates: params.skillStates,
defaultActiveOnShare: params.defaultActiveOnShare,
maxCatalogSkills: getMaxCatalogSkills(runtime),
})
: Promise.resolve<ResolvedSkillCatalog | undefined>(undefined),
]);
manualSkillPrimes = manualPrimesResult;
alwaysApplySkillPrimes = alwaysApplyPrimesResult;
resolvedSkillCatalog = catalogResult;
const selectedPrimes = selectSkillPrimesForTurn({
manualSkillPrimes: manualSkillPrimes ?? [],
alwaysApplySkillPrimes: alwaysApplySkillPrimes ?? [],
});
if (selectedPrimes.alwaysApplyDedupedFromManual > 0) {
logger.info(
`[initializeAgent] Dropped ${selectedPrimes.alwaysApplyDedupedFromManual} always-apply prime(s) already present in the manual list; same-named skills prime only once per turn.`,
);
}
if (selectedPrimes.alwaysApplyDropped > 0) {
logger.warn(
`[initializeAgent] Combined primes exceeds MAX_PRIMED_SKILLS_PER_TURN (${MAX_PRIMED_SKILLS_PER_TURN}); truncating ${selectedPrimes.alwaysApplyDropped} always-apply prime(s) so every initializer consumer sees the model-bound set.`,
);
}
manualSkillPrimes = manualSkillPrimes == null ? undefined : selectedPrimes.manualSkillPrimes;
alwaysApplySkillPrimes =
alwaysApplySkillPrimes == null ? undefined : selectedPrimes.alwaysApplySkillPrimes;
assertResolvedSkillContentAllowed(
[
...(manualSkillPrimes ?? []),
...(alwaysApplySkillPrimes ?? []),
...(resolvedSkillCatalog?.activeSkills.filter(
(skill) => skill.disableModelInvocation !== true,
) ?? []),
],
appConfig?.filters,
);
}
let currentFiles: Array<IMongoFile | TFile> | undefined;
const baseToolNames = agent.tools ?? [];
/**
* Pre-resolve manually-invoked + always-apply skill primes so their
* `allowed-tools` can be unioned into the agent's effective tool set
* BEFORE project resource hydration and `loadTools` run. Project files
* must follow this same effective set, otherwise a skill-added
* `file_search` tool cannot see its eligible Project files.
*/
if (hasSkillAccess) {
/** Skill `allowed-tools` are legacy-heal candidates too: a raw MCP key
* declared before the normalized-key convention would neither dedupe
* against the healed agent tools nor match the normalized-keyed tool
* map, silently dropping the skill-contributed tool. Same lazy audit
* and skip-on-unavailable semantics as the agent-key heal. */
const combinedPrimes = [...(manualSkillPrimes ?? []), ...(alwaysApplySkillPrimes ?? [])];
const primesNeedHeal = combinedPrimes.some((prime) =>
prime.allowedTools?.some((name) => name.includes(Constants.mcp_delimiter)),
);
const primeHealNames = primesNeedHeal ? await resolveHealNames() : null;
if (primeHealNames != null) {
resolvedAuditNames = primeHealNames;
}
const primesForUnion =
primeHealNames != null
? combinedPrimes.map((prime) =>
prime.allowedTools?.length
? {
...prime,
allowedTools: normalizeAgentToolKeys({
tools: prime.allowedTools,
toolOptions: undefined,
rawServerNames: primeHealNames,
}).tools,
}
: prime,
)
: combinedPrimes;
if (primesForUnion.length > 0) {
const union = unionPrimeAllowedTools({
primes: primesForUnion,
agentToolNames: baseToolNames,
});
extraAllowedToolNames = union.extraToolNames;
perSkillExtras = union.perSkillExtras;
}
}
const effectiveToolNames =
extraAllowedToolNames.length > 0 ? [...baseToolNames, ...extraAllowedToolNames] : baseToolNames;
const requestedToolNames = effectiveToolNames;
const provider = agent.provider;
agent.endpoint = provider;
/** Settle the provider and its client options before any attachment is judged. The file
* policy reads the endpoint's own name, but the route each attachment takes also depends on
* the backing client and on the Responses API decision `getOptions` makes, and nothing
* between here and tool loading feeds either. */
const { getOptions, overrideProvider, customEndpointConfig } = getProviderConfig({
provider,
appConfig,
});
if (overrideProvider !== agent.provider) {
agent.provider = overrideProvider;
}
const inference = resolveAgentInferenceParameters({
parameters: {
...agent.model_parameters,
...(isInitialAgent === true ? endpointOption?.model_parameters : undefined),
},
...getAgentInferencePolicy(provider, appConfig, customEndpointConfig),
model: agent.model ?? '',
});
const { resendFiles, maxContextTokens, imageDetail, modelOptions } = extractLibreChatParams(
inference.parameters,
);
const finalModelOptions = pinAgentModel(modelOptions, agent.model);
const options: InitializeResultBase = await getOptions({
runtime: {
appConfig,
user,
requestBody: runtime.requestBody,
},
endpoint: provider,
model_parameters: finalModelOptions,
inferenceParameters: inference.customParameters,
db,
});
const llmConfig = options.llmConfig as Record<string, unknown>;
const webSearchDenied =
hasProviderWebSearch(options.tools, llmConfig) &&
!(await resolveWebSearchGrant({
req: params.req as Request | undefined,
user,
resolve: params.resolveWebSearchGrant,
getRoleByName: db.getRoleByName,
}));
if (webSearchDenied) {
stripWebSearchPlugin(llmConfig);
logger.warn(
'[initializeAgent] Provider-native web search was requested but blocked by WEB_SEARCH.USE. Restore the role grant explicitly; removing interface.webSearch does not reset stored permissions.',
);
}
const tokensModel =
agent.provider === EModelEndpoint.azureOpenAI ? agent.model : (llmConfig?.model as string);
const maxOutputTokens = optionalChainWithEmptyCheck(
llmConfig?.maxOutputTokens as number | undefined,
llmConfig?.maxTokens as number | undefined,
0,
);
const agentMaxContextTokens = optionalChainWithEmptyCheck(
maxContextTokens,
getModelMaxTokens(
tokensModel ?? '',
providerEndpointMap[overrideProvider as keyof typeof providerEndpointMap],
options.endpointTokenConfig,
),
DEFAULT_MAX_CONTEXT_TOKENS,
);
if (
agent.endpoint === EModelEndpoint.azureOpenAI &&
(llmConfig?.azureOpenAIApiInstanceName as string | undefined) == null
) {
agent.provider = Providers.OPENAI;
}
if (options.provider != null) {
agent.provider = options.provider;
}
const deliveryRouting = resolveTurnDeliveryRouting({
agent: {
provider: agent.provider,
endpoint: agent.endpoint,
model_parameters: {
useResponsesApi:
typeof llmConfig.useResponsesApi === 'boolean' ? llmConfig.useResponsesApi : undefined,
},
},
config: appConfig,
});
/** Resolve the per-agent Code API route before resource/tool priming. A
* stateful agent must perform freshness checks and recovery uploads against
* the same isolated deployment its eventual `/exec` request will use. */
const agentRequestsCodeExec = (agent.tools ?? []).includes(Tools.execute_code);
const configuredCodeEnvironments =
appConfig?.endpoints?.[EModelEndpoint.agents]?.statefulCodeSessions?.environments;
const {
attachedEnvironmentOptOut,
codeEnvAvailable: effectiveCodeEnvAvailable,
statefulSessions: effectiveStatefulSessions,
statefulCodeEnvironment,
context: codeExecutionContext,
} = resolveAgentCodeExecution({
agent,
requestBody,
conversation: runtime.resolvedConversation,
codeExecutionAvailable: params.codeEnvAvailable === true,
statefulSessionsAvailable: params.statefulSessionsAvailable === true,
allowedStatefulCodeEnvironments: resolveAllowedStatefulCodeEnvironments(
params.allowedStatefulCodeEnvironments ??
appConfig?.endpoints?.[EModelEndpoint.agents]?.statefulCodeSessions?.allowedEnvironments,
),
allowEnvironmentSelection:
appConfig?.endpoints?.agents?.statefulCodeSessions?.allowEnvironmentSelection,
inheritedEnvironments: runtime.codeWorkspaceInheritance,
environments: configuredCodeEnvironments,
implicitStatefulRouteAvailable: isImplicitStatefulCodeRouteAvailable(
process.env.CODE_ENVIRONMENT_DECISION_VERSION,
process.env.LIBRECHAT_CODE_BASEURL_STATEFUL,
),
userId: requestFileOwnerId,
conversationId,
});
const attachedWorkspaceTools =
effectiveCodeEnvAvailable && codeExecutionContext.environmentType === 'attached';
const requestFileIds = [
...new Set(
requestFiles
.map((file) => file.file_id)
.filter((fileId): fileId is string => typeof fileId === 'string' && fileId.length > 0),
),
];
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 && !attachedEnvironmentOptOut,
fileSearchAvailable: params.fileSearchAvailable,
});
/**
* Load conversation files for ALL agents, not just the initial agent.
* This enables handoff agents to access files that were uploaded earlier
* in the conversation. Without this, file_search and execute_code tools
* on handoff agents would fail to find previously attached files.
*/
/* `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 fileConsumers: TurnFileConsumers = {
executeCode: wantsCodeFiles,
fileSearch: wantsSearchFiles,
};
const wantsProvisioning = wantsCodeFiles || wantsSearchFiles;
if (
authorizedRunFiles === undefined &&
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;
/* A turn sent at the root has no history at all. The conversation's file refs then
* belong to sibling roots (an edited first message, or one retried without its files),
* so a root turn takes none of them, unlike a continuation that names no anchor. */
const isRootTurn = parentMessageId === Constants.NO_PARENT;
/* 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
* together. Both gate the model call, and this runs on every turn — each serialized
* round trip here is time-to-first-token the user waits through.
*
* Thread walk selects only the fields traversal needs. Both `files` (user uploads)
* and `attachments` (code-execution outputs from `processCodeOutput`) carry the
* `file_id` refs the next turn must prime — selecting only `files` silently drops
* every code-output ref.
*/
const [convoFileIds, threadMessages] = await Promise.all([
isRootTurn
? []
: (readResolvedConversationFiles(runtime, conversationId) ??
db.getConvoFiles(conversationId)),
needsThreadWalk && getThreadMessages
? getThreadMessages({ conversationId }, 'messageId parentMessageId files attachments')
: null,
]);
const fileIds = convoFileIds ?? [];
/** Walk the parent chain and collect file_ids referenced by
* any message in the thread (`messages.files[].file_id` +
* `messages.attachments[].file_id`). Used as the primary
* anchor for both `getCodeGeneratedFiles` and
* `getUserCodeFiles` — message ids no longer needed at
* this layer. */
const threadFileIds =
threadMessages && threadMessages.length > 0
? 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 ?? []);
/* Conversation.files can omit a previous turn's embedded upload. Follow the same
* parent chain for provisioned tool files so search restores it without loading a
* sibling branch; unanchored continuations retain the conversation-level list. */
const replayToolFileIds = needsThreadWalk ? (threadFileIds ?? []) : fileIds;
/**
* Retrieve execute_code files filtered to the current thread.
* This includes both code-generated files and user-uploaded execute_code files.
*
* Code-generated and user-uploaded execute_code files share the same primary anchor:
* file_ids referenced by messages in the current thread. The two queries differ only
* by `context` (`execute_code` for generated outputs, others for uploads). Anchoring
* both on `threadFileIds` reaches files regardless of which sibling first generated
* them — see `getCodeGeneratedFiles` for the branched-conversation rationale.
*/
/* 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(
replayToolFileIds,
toolResourceSet,
requestFileOwnerScope,
) as Promise<IMongoFile[]>)
: ([] as IMongoFile[]),
resendFiles && wantsCodeFiles && db.getCodeGeneratedFiles && requestFileOwnerScope
? (db.getCodeGeneratedFiles(
conversationId,
threadFileIds,
requestFileOwnerScope,
) as Promise<IMongoFile[]>)
: ([] as IMongoFile[]),
resendFiles &&
wantsCodeFiles &&
db.getUserCodeFiles &&
requestFileOwnerScope &&
threadFileIds &&
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) {
if (typeof file.file_id !== 'string' || snapshotFileIds.has(file.file_id)) {
continue;
}
snapshotFileIds.add(file.file_id);
toolFileIds.push(file.file_id);
}
}
/**
* Hydrate the complete candidate set through one owner-scoped, read-only
* query. Some discovery queries intentionally omit file text; this snapshot
* includes the content fields needed by policy checks. `updateFilesUsage`
* both mutates usage and returns hydrated rows, so it cannot be the hydrator:
* keep this exact snapshot authoritative for inspection, priming, and the
* later usage update to avoid a post-inspection re-read.
*/
const snapshotFileIds = [...requestFileIds, ...toolFileIds, ...deferredProvisionFileIds];
let requestUsageFiles: IMongoFile[] = [];
let toolUsageFiles: IMongoFile[] = [];
if (authorizedRunFiles === undefined && requestFileOwnerScope && snapshotFileIds.length > 0) {
const hydratedFiles =
((await db.getFiles(
{
file_id: { $in: snapshotFileIds },
user: requestFileOwnerScope.userId,
...(requestFileOwnerScope.tenantId != null && {
tenantId: requestFileOwnerScope.tenantId,
}),
},
{},
{},
)) as IMongoFile[] | null) ?? [];
const hydratedFilesById = new Map(
hydratedFiles
.filter((file) => snapshotFileIds.includes(file.file_id))
.map((file) => [file.file_id, file]),
);
requestUsageFiles = requestFileIds
.map((fileId) => hydratedFilesById.get(fileId))
.filter((file): file is IMongoFile => file != null);
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 (authorizedRunFiles !== undefined) {
for (const file of authorizedRunFiles) {
if (
file.user !== requestFileOwnerId ||
(file.tenantId ?? null) !== (user?.tenantId ?? null)
) {
throw new Error('Run file inputs do not match the authenticated owner');
}
}
currentFiles = authorizedRunFiles.map((file) => structuredClone(file));
} else if (requestFiles.length > 0 || toolFileIds.length > 0) {
currentFiles = requestUsageFiles.concat(toolUsageFiles);
}
if (currentFiles?.length) {
/* Before any check reads the route: endpoint filtering, model-bound limits and content
* inspection below all have to judge each file by the route this turn delivers it by. */
currentFiles = applyTurnDelivery(currentFiles, {
routing: deliveryRouting,
consumers: fileConsumers,
});
}
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,
endpoint: agent.endpoint ?? '',
endpointType,
skipTotalSizeLimit: true,
preserveTextSources: true,
});
const requestUsageFileIds = new Set(
(authorizedRunFiles ?? requestUsageFiles).map((file) => file.file_id),
);
assertAgentAttachmentLimits({
attachments: currentFiles.filter(
(file) => requestUsageFileIds.has(file.file_id) && isModelBoundAttachmentFile(file),
),
fileConfig: appConfig?.fileConfig,
endpoint: agent.endpoint ?? '',
endpointType,
});
currentFiles = admitCurrentFileBudget(
currentFiles,
deliveryRouting.endpointConfig.totalSizeLimit,
);
/* 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) {
const { committed, pending } = partitionCommittedFiles(deferredProvisionFiles, currentFiles);
/* Current admission is final. Charge only new deferred identities against its
* remainder, regardless of their order relative to overlapping current files. */
deferredProvisionFiles = committed.concat(
filterFilesByEndpointRuntimeConfig(appConfig, {
files: pending,
endpoint: agent.endpoint ?? '',
endpointType,
consumedBytes: sumUniqueBytes(currentFiles),
}) as IMongoFile[],
);
}
}
assertModelBoundContent({
filters: appConfig?.filters,
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;
}
});
}
const canUseProjectFileSearch =
shouldUseChatProjectContext &&
runtime.chatProjectContext != null &&
effectiveToolNames.includes(Tools.file_search) &&
params.fileSearchAvailable !== false &&
(appConfig?.endpoints?.[EModelEndpoint.agents]?.capabilities ?? []).includes(
AgentCapabilities.file_search,
);
let projectRuntimeFiles: TFile[] = [];
if (canUseProjectFileSearch && runtime.chatProjectContext != null && requestFileOwnerScope) {
runtime.chatProjectContextResourcesPromise ??=
params.req?.chatProjectContextResourcesPromise ??
hydrateChatProjectContextResources(runtime.chatProjectContext, {
userId: requestFileOwnerScope.userId,
tenantId: requestFileOwnerScope.tenantId,
getProjectFiles: db.getProjectFiles,
});
if (params.req) {
params.req.chatProjectContextResourcesPromise = runtime.chatProjectContextResourcesPromise;
}
runtime.chatProjectContext = await runtime.chatProjectContextResourcesPromise;
if (params.req) {
params.req.chatProjectContext = runtime.chatProjectContext;
}
runtime.chatProjectFilesPromise ??=
params.req?.chatProjectFilesPromise ??
resolveRuntimeProjectFiles({
context: runtime.chatProjectContext,
getProjectFiles: db.getProjectFiles,
scope: requestFileOwnerScope,
filters: appConfig?.filters,
});
if (params.req) {
params.req.chatProjectFilesPromise = runtime.chatProjectFilesPromise;
}
projectRuntimeFiles = await runtime.chatProjectFilesPromise;
runtime.chatProjectFiles = projectRuntimeFiles;
if (params.req) {
params.req.chatProjectFiles = projectRuntimeFiles;
}
}
/**
* Usage accounting is the first file mutation. It runs only after every
* hydrated file in the exact snapshot above has passed endpoint filtering
* and current content policy checks. Ignore returned rows so priming cannot
* observe a different post-inspection snapshot.
*/
if (requestFileOwnerId && requestUsageFiles.length > 0) {
await db.updateFilesUsage(requestUsageFiles, undefined, {
user: requestFileOwnerId,
tenantId: user?.tenantId,
});
}
if (requestFileOwnerId && toolUsageFiles.length > 0) {
await db.updateFilesUsage(toolUsageFiles, undefined, {
user: requestFileOwnerId,
tenantId: user?.tenantId,
});
}
let runtimeToolResources = agent.tool_resources;
if (attachedEnvironmentOptOut && runtimeToolResources != null) {
runtimeToolResources = { ...runtimeToolResources };
delete runtimeToolResources[EToolResources.execute_code];
}
let admittedPersistentFiles: TFile[] = [];
const {
attachments: primedAttachments,
requestAttachments: primedRequestAttachments,
agentContextAttachments: primedAgentContextAttachments,
tool_resources,
provisionState: primedProvisionState,
warnings: provisionWarnings,
} = await primeResources({
req: params.req,
principal: user,
getFiles: db.getFiles as never,
filterFiles: db.filterFilesByAgentAccess,
appConfig,
agentId: agent.id,
attachments: currentFiles
? (Promise.resolve(currentFiles) as unknown as Promise<TFile[]>)
: undefined,
tool_resources: runtimeToolResources,
requestFileSet: new Set((authorizedRunFiles ?? requestFiles).map((file) => file.file_id)),
enabledToolResources: toolResourceSet,
checkSessionsAlive: db.checkSessionsAlive,
loadCodeApiKey: db.loadCodeApiKey,
adoptLegacySearchEmbeddings: db.adoptLegacySearchEmbeddings,
hasEntityEmbeddings: db.hasEntityEmbeddings,
provisionCandidates: deferredProvisionFiles as unknown as TFile[],
codeRouteKey: codeExecutionContext.executionRouteKey ?? codeExecutionContext.executionProfile,
codeBaseUrl: codeExecutionContext.baseUrl,
codeExecutionProfile: codeExecutionContext.executionProfile,
codeBridgeWorkerId: codeExecutionContext.bridgeWorkerId,
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. */
admittedPersistentFiles = 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;
}
});
return admittedPersistentFiles;
},
});
if (projectRuntimeFiles.length > 0) {
/* Project repairs join after priming, but spend the same allowance as the files
* already admitted above. Reuse their snapshots without charging overlaps twice. */
const committedFiles = [
...(currentFiles ?? []),
...deferredProvisionFiles,
...admittedPersistentFiles,
];
const { committed, pending } = partitionCommittedFiles(projectRuntimeFiles, committedFiles);
projectRuntimeFiles = committed.concat(
filterFilesByEndpointRuntimeConfig(appConfig, {
files: pending,
endpoint: agent.endpoint ?? '',
endpointType: endpointFileType,
consumedBytes: sumUniqueBytes(committedFiles),
}),
);
}
const projectResources = addProjectFilesToFileSearch(
tool_resources,
projectRuntimeFiles,
effectiveToolNames,
appConfig,
params.fileSearchAvailable,
primedProvisionState,
);
runtimeToolResources = projectResources.resources;
const provisionState = projectResources.provisionState;
const dropFileSearchResources = (): void => {
if (runtimeToolResources?.[EToolResources.file_search] == null) {
return;
}
const { [EToolResources.file_search]: _fileSearch, ...remaining } = runtimeToolResources;
runtimeToolResources = Object.keys(remaining).length > 0 ? remaining : undefined;
};
if (params.fileSearchAvailable === false || !effectiveToolNames.includes(Tools.file_search)) {
dropFileSearchResources();
}
/**
* `loadTools` failures take two forms:
* 1. The wrapper throws — rare; only when something around the
* try/catch in `createToolLoader` itself fails.
* 2. The wrapper returns `undefined` — the typical CJS path for errors
* that remain soft-failures. Runtime loaders rethrow invariant
* failures such as an explicitly configured MCP tool set resolving
* to zero, but preserve the legacy `undefined` result for unrelated
* failures. Without explicit handling, the empty
* fallback object below would silently drop the agent's baseline
* tools for the turn (not just the skill-added extras).
*
* If a skill-contributed `allowed-tools` entry is the culprit, retry
* with just `agent.tools` so the agent's own tools still load (the
* dropped-tools debug log below picks up which extras vanished). If
* the retry-without-extras also fails, propagate / fall through with
* the empty fallback — the agent's own tools are the problem.
*/
const callLoadTools = async (tools: string[]) =>
loadTools?.({
provider,
agentId: agent.id,
tools,
model: agent.model,
tool_options: agent.tool_options,
tool_resources: runtimeToolResources,
requestBody,
codeExecutionContext,
attachedEnvironmentOptOut,
accessibleMcpServerNames: resolvedAuditNames,
});
let loadToolsResult;
const initialFailedSilently = (result: unknown) =>
result == null && extraAllowedToolNames.length > 0;
try {
loadToolsResult = await callLoadTools(requestedToolNames);
} catch (err) {
if (
isFatalAgentInitializationError(err, {
signal: params.signal,
allowExpectedMCPFallback: true,
})
) {
throw err;
}
if (extraAllowedToolNames.length > 0) {
logger.warn(
`[allowedTools] loadTools threw with ${extraAllowedToolNames.length} skill-added extra(s); retrying without them`,
{ errorName: err instanceof Error ? err.name : 'UnknownError' },
);
if (!baseToolNames.includes(Tools.file_search)) {
dropFileSearchResources();
}
loadToolsResult = await callLoadTools(baseToolNames);
} else {
throw err;
}
}
if (initialFailedSilently(loadToolsResult)) {
/* Runtime loaders may swallow non-invariant errors and return undefined. Treat that
the same as a throw when extras were requested — the agent's own
tools must still load. */
logger.warn(
`[allowedTools] loadTools returned no result with ${extraAllowedToolNames.length} skill-added extra(s); retrying without them.`,
);
if (!baseToolNames.includes(Tools.file_search)) {
dropFileSearchResources();
}
loadToolsResult = await callLoadTools(baseToolNames);
}
const {
toolRegistry,
toolContextMap,
dynamicToolContextMap,
userMCPAuthMap,
toolDefinitions: loadedToolDefinitions,
mcpAvailableTools,
requestScopedConnections,
hasDeferredTools,
mcpToolAliases,
actionsEnabled,
oauthActionToolNames,
tools: structuredTools,
primedCodeFiles,
codeContextEntries,
codeExecutionContext: loadedCodeExecutionContext,
repositoryInstructionSource,
} = loadToolsResult ?? {
tools: [],
toolContextMap: {},
dynamicToolContextMap: {},
userMCPAuthMap: undefined,
toolRegistry: undefined,
mcpAvailableTools: undefined,
requestScopedConnections: undefined,
toolDefinitions: [],
hasDeferredTools: false,
mcpToolAliases: [],
actionsEnabled: undefined,
oauthActionToolNames: undefined,
primedCodeFiles: undefined,
codeContextEntries: undefined,
codeExecutionContext: undefined,
repositoryInstructionSource: undefined,
};
const trustedCodeExecutionContext = loadedCodeExecutionContext ?? codeExecutionContext;
const attachedWorkspaceOperations =
trustedCodeExecutionContext.environmentType === 'attached'
? new Set(trustedCodeExecutionContext.codeWorkspace?.operations ?? [])
: undefined;
const attachedWorkspaceCommandTimeoutMaxMs =
trustedCodeExecutionContext.environmentType === 'attached'
? resolveAttachedWorkspaceCommandTimeoutMax(
trustedCodeExecutionContext.codeEnvironmentConfigSchema,
trustedCodeExecutionContext.codeWorkspace?.maxCommandTimeoutMs,
)
: undefined;
const attachedWorkspaceCommandTimeoutDefaultMs =
trustedCodeExecutionContext.environmentType === 'attached'
? resolveAttachedWorkspaceCommandTimeoutDefault(
trustedCodeExecutionContext.codeEnvironmentConfigSchema?.limits?.defaultCommandTimeoutMs,
attachedWorkspaceCommandTimeoutMaxMs,
)
: undefined;
const attachedWorkspaceReadFileDefaultLines =
trustedCodeExecutionContext.environmentType === 'attached'
? resolveAttachedWorkspaceReadFileLines(
trustedCodeExecutionContext.codeEnvironmentConfigSchema,
)
: undefined;
if (
attachedWorkspaceOperations &&
!attachedWorkspaceOperations.has('preview_edit') &&
hasActiveFileFieldPolicy(appConfig?.filters, ['content', 'extracted_text'])
) {
attachedWorkspaceOperations.delete('edit_file');
}
let toolDefinitions = loadedToolDefinitions;
/**
* Tolerant filter: anything `loadTools` couldn't resolve (capability
* disabled, plugin missing, name unknown to the registry) is silently
* dropped with an attributed debug log. Cross-ecosystem skills authored
* against tools LibreChat hasn't shipped yet (Claude Code's `edit_file`,
* etc.) import without breaking — they light up automatically once
* support lands. Skips when there were no extras to begin with.
*/
if (extraAllowedToolNames.length > 0) {
const loadedNames = new Set((toolDefinitions ?? []).map((d) => d.name));
const dropped = extraAllowedToolNames.filter((n) => !loadedNames.has(n));
if (dropped.length > 0) {
logger.debug(
`[allowedTools] Dropped ${dropped.length} unrecognized tool name(s) from ${perSkillExtras.size} skill(s)`,
);
}
}
/**
* Unify code-execution tools around `bash_tool` + `read_file` when the
* agent explicitly lists `execute_code` in its tools and the admin
* capability is enabled for the run. The legacy `execute_code` tool
* (backed by `CodeExecutionToolDefinition` + `primeCodeFiles`) is no
* longer registered; the string `execute_code` on the agent document
* stays as the capability-trigger marker but expands into the
* `bash_tool` + `read_file` pair here. The initial `read_file`
* definition is code-only; `injectSkillCatalog` upgrades it later in
* this initializer when skill files are actually available.
*
* `effectiveCodeEnvAvailable` is the per-agent truth: the admin-level
* `params.codeEnvAvailable` AND the agent actually asking for code
* execution. Computed once and reused by the expansion block below,
* the `injectSkillCatalog` call, and the returned `InitializedAgent`.
* Downstream handlers (runtime `configurable`, `primeInvokedSkills`)
* read it from the stored per-agent value so a skills-only agent
* never accidentally registers `bash_tool` or primes sandbox files
* just because the admin globally enabled code execution.
*
* Done before provider-tool merging so execute-code-only agents on
* Google/Vertex still surface as external function definitions when
* provider-specific tools are also configured. Also before
* `injectSkillCatalog` so the skill path's own
* `registerCodeExecutionTools` call upgrades `read_file` from the
* code-only description to the skill-aware description without adding a
* duplicate — exactly one copy of each tool reaches the LLM.
*/
/**
* Capability marker → definition names its registration produced this run,
* reported by the registrars themselves. `tool_options` entries keyed by a
* marker (`execute_code`, `memory`, `skills`) — from a model-spec selection
* or a hand-edited saved agent — resolve onto exactly these names in the
* background/intent passes, so the projection cannot drift from what
* actually got registered.
*/
const capabilityToolNames = new Map<string, readonly string[]>();
const recordCapabilityToolNames = (capability: string, toolNames: readonly string[]): void => {
if (toolNames.length === 0) {
return;
}
const existing = capabilityToolNames.get(capability);
capabilityToolNames.set(capability, existing ? [...existing, ...toolNames] : toolNames);
};
if (effectiveCodeEnvAvailable) {
const codeExecResult = registerCodeExecutionTools({
toolRegistry,
toolDefinitions,
includeBash: true,
includeSkillFileInstructions: false,
enableToolOutputReferences: effectiveCodeEnvAvailable,
statefulSessions: effectiveStatefulSessions,
workspaceTools: attachedWorkspaceTools,
workspaceOperations: attachedWorkspaceOperations,
workspaceCommandTimeoutMaxMs: attachedWorkspaceCommandTimeoutMaxMs,
workspaceCommandTimeoutDefaultMs: attachedWorkspaceCommandTimeoutDefaultMs,
workspaceReadFileDefaultLines: attachedWorkspaceReadFileDefaultLines,
workspaceEnvironment: trustedCodeExecutionContext.codeWorkspace?.environment,
workspaceLinkedWorktrees: trustedCodeExecutionContext.codeWorkspace?.linkedWorktrees,
workspaceNativeSandbox: trustedCodeExecutionContext.codeWorkspace?.nativeSandbox,
});
toolDefinitions = codeExecResult.toolDefinitions;
recordCapabilityToolNames(AgentCapabilities.execute_code, codeExecResult.toolNames);
} else if (agentRequestsCodeExec) {
/**
* Agent asked for `execute_code` but the admin-level gate is off —
* surface a debug log so operators tracing "why isn't code
* interpreter working?" get a clear signal. The event-driven tool
* loader (`loadToolDefinitionsWrapper`) doesn't log capability-
* disabled warnings for the definitions-only path, so without this,
* the tool silently vanishes from the LLM's definitions with no trace.
*/
logger.debug(
`[initializeAgent] Agent "${agent.id}" requests execute_code but codeEnvAvailable=${String(params.codeEnvAvailable)}; skipping bash_tool + read_file registration.`,
);
}
/**
* Expand the `memory` capability marker into the inline `set_memory` +
* `delete_memory` tool pair, mirroring the `execute_code` expansion above.
* `params.memoryAvailable` is the full run-level gate (capability enabled,
* memory configured, user permitted); the marker on `agent.tools` is the
* per-agent opt-in. The runtime instances are created in the tool service.
*/
const agentRequestsMemory = (agent.tools ?? []).includes(Tools.memory);
const inlineMemoryRegistered = params.memoryAvailable === true && agentRequestsMemory;
if (inlineMemoryRegistered) {
const memoryResult = registerMemoryTools({
toolRegistry,
toolDefinitions,
validKeys: appConfig?.memory?.validKeys,
});
toolDefinitions = memoryResult.toolDefinitions;
recordCapabilityToolNames(AgentCapabilities.memory, memoryResult.toolNames);
appendAdditionalInstructions(agent, memoryToolUsageGuard);
} else if (agentRequestsMemory) {
logger.debug(
`[initializeAgent] Agent "${agent.id}" requests memory but memoryAvailable=${String(params.memoryAvailable)}; skipping set_memory + delete_memory registration.`,
);
}
if (skillAuthoringAvailable) {
const skillReadResult = registerCodeExecutionTools({
toolRegistry,
toolDefinitions,
includeBash: false,
includeSkillFileInstructions: true,
enableToolOutputReferences: effectiveCodeEnvAvailable,
workspaceTools: attachedWorkspaceTools,
workspaceOperations: attachedWorkspaceOperations,
workspaceCommandTimeoutMaxMs: attachedWorkspaceCommandTimeoutMaxMs,
workspaceCommandTimeoutDefaultMs: attachedWorkspaceCommandTimeoutDefaultMs,
workspaceReadFileDefaultLines: attachedWorkspaceReadFileDefaultLines,
});
toolDefinitions = skillReadResult.toolDefinitions;
recordCapabilityToolNames(AgentCapabilities.skills, skillReadResult.toolNames);
}
if (effectiveCodeEnvAvailable || skillAuthoringAvailable) {
const fileAuthoringResult = registerFileAuthoringTools({
toolRegistry,
toolDefinitions,
includeSkillFileInstructions: skillAuthoringAvailable,
workspaceTools: attachedWorkspaceTools,
workspaceOperations: attachedWorkspaceOperations,
});
toolDefinitions = fileAuthoringResult.toolDefinitions;
/** File authoring is owned by whichever capability switched it on —
* both, when both are active, so either marker's selection governs. */
if (effectiveCodeEnvAvailable) {
recordCapabilityToolNames(AgentCapabilities.execute_code, fileAuthoringResult.toolNames);
}
if (skillAuthoringAvailable) {
recordCapabilityToolNames(AgentCapabilities.skills, fileAuthoringResult.toolNames);
}
}
let intentToolNames: string[] | undefined;
let semanticIntentToolNames: string[] | undefined;
let semanticIntentBlockedToolNames: string[] | undefined;
/**
* Inject the `run_in_background` param into eligible opted-in tools and
* register the `check_background_task` poll tool. Runs after all built-in
* tool registration so the full, final `toolDefinitions` set is considered.
* Opt-in is per-tool via `tool_options` for both saved and ephemeral agents;
* the code-execution pair is background-native and needs no opt-in.
*/
let backgroundToolNames: string[] | undefined;
if (params.backgroundToolsAvailable === true) {
/** Tool names embed `normalizeServerName(server)` (see MCP.js tool keys)
* while `mcpConfig` keys the original name, so index the ephemeral
* servers by their normalized form. */
const ephemeralServerNames = new Set<string>();
for (const [serverName, serverConfig] of Object.entries(appConfig?.mcpConfig ?? {})) {
if (serverConfig != null && requiresEphemeralUserConnection(serverConfig)) {
ephemeralServerNames.add(normalizeServerName(serverName));
}
}
/** Resolve the boundary against every configured server, not just the
* ephemeral subset: a non-ephemeral name ending in an ephemeral one would
* otherwise be misread as ephemeral. */
const allServerNames = Object.keys(appConfig?.mcpConfig ?? {}).map(normalizeServerName);
const oauthActionNames = new Set(oauthActionToolNames ?? []);
const backgroundResult = applyBackgroundToolCalls({
toolDefinitions,
toolRegistry,
toolOptions: agent.tool_options,
capabilityToolNames,
/** Tools of ephemeral request-scoped MCP servers (runtime body
* placeholders) never get the param: their connection dies at request
* end, so the executor would only downgrade the call to foreground.
* Unknown servers stay eligible — the executor's per-instance tag is
* the fail-safe for those. OAuth-backed action tools are excluded too:
* a detached call can block on an interactive login prompt the user
* never sees. */
excludeTool: (toolName) => {
if (oauthActionNames.has(toolName)) {
return true;
}
const [, serverName] = splitMCPToolKey(toolName, allServerNames);
return serverName != null && ephemeralServerNames.has(serverName);
},
});
toolDefinitions = backgroundResult.toolDefinitions;
if (backgroundResult.backgroundToolNames.length > 0) {
backgroundToolNames = backgroundResult.backgroundToolNames;
}
}
/** Check for tool presence from either full instances or definitions (event-driven mode) */
const hasAgentTools = (structuredTools?.length ?? 0) > 0 || (toolDefinitions?.length ?? 0) > 0;
const providerTools = resolveProviderToolConflicts({
provider: agent.provider,
tools: options.tools,
toolDefinitions,
webSearchDenied,
});
const hasProviderTools = (providerTools?.length ?? 0) > 0;
let tools: GenericTool[] = hasProviderTools
? (providerTools as GenericTool[])
: (structuredTools ?? []);
if (isGoogleToolCombinationProvider(agent.provider) && hasProviderTools && hasAgentTools) {
assertGoogleToolCombinationSupport(llmConfig.model);
if (
shouldIncludeGoogleServerSideToolInvocations({
provider: agent.provider,
hasProviderTools,
hasAgentTools,
})
) {
enableGoogleServerSideToolInvocations({ agent, llmConfig });
}
if (structuredTools?.length) {
tools = structuredTools.concat(providerTools as GenericTool[]);
}
} else if (
(agent.provider === Providers.OPENAI ||
agent.provider === Providers.AZURE ||
agent.provider === Providers.ANTHROPIC) &&
hasProviderTools &&
structuredTools?.length
) {
tools = structuredTools.concat(providerTools as GenericTool[]);
}
agent.model_parameters = { ...options.llmConfig } as Agent['model_parameters'];
if (options.configOptions) {
(agent.model_parameters as Record<string, unknown>).configuration = options.configOptions;
}
retainAgentInferenceInput(agent, provider, {
...inference.parameters,
...inference.customParameters,
});
/**
* Resolves an `instructionsPrompt` link before special-vars substitution, so
* a linked prompt's `{{current_date}}`-style placeholders are replaced the
* same way inline instructions are. A link without a resolver, or one that
* resolves to `unavailable`, continues the turn with empty instructions
* rather than failing initialization — the inline-text fallback is AI-2150.
* The resolution itself started well above, in parallel with everything
* between; this only awaits it.
*/
let instructionsPromptFacts: LinkedInstructionsFacts | undefined;
if (instructionsPromptLink) {
if (linkedInstructionsPromise) {
const linkedResult = await linkedInstructionsPromise;
if (linkedResult.status === 'resolved') {
agent.instructions = linkedResult.prompt;
instructionsPromptFacts = linkedResult.facts;
} else {
agent.instructions = '';
logger.warn(
`[initializeAgent] Linked instructions unavailable for agent ${agent.id} (group ${instructionsPromptLink.groupId}): ${linkedResult.reason}`,
);
}
} else {
agent.instructions = '';
logger.warn(
`[initializeAgent] Agent ${agent.id} links instructions to group ${instructionsPromptLink.groupId} but no resolver was provided; continuing with empty instructions`,
);
}
}
if (agent.instructions && agent.instructions !== '') {
const resolvedInstructions = replaceSpecialVars({
text: agent.instructions,
user: user ? (user as unknown as TUser) : null,
now: runtime.turnStartedAt,
timezone: runtime.requestBody.timezone,
});
if (hasTemporalSpecialVars(agent.instructions)) {
agent.instructions = undefined;
appendAdditionalInstructions(agent, resolvedInstructions);
} else {
agent.instructions = resolvedInstructions;
}
}
const repositoryInstructionBlock = repositoryInstructionSource
? await repositoryInstructionSource.load({
...repositoryInstructionSource,
mode: agent.repositoryInstructions,
signal: params.signal,
timeoutMs: appConfig?.endpoints?.agents?.repositoryInstructions?.timeoutMs,
assertContent: (content) =>
assertModelBoundContent({
filters: appConfig?.filters,
agents: [{ instructions: content }],
}),
})
: undefined;
if (repositoryInstructionBlock) {
agent.instructions = [agent.instructions, repositoryInstructionBlock]
.filter(Boolean)
.join('\n\n');
}
if (typeof agent.artifacts === 'string' && agent.artifacts !== '') {
const artifactsPromptResult = generateArtifactsPrompt({
endpoint: agent.provider,
artifacts: agent.artifacts as never,
});
appendAdditionalInstructions(agent, artifactsPromptResult);
}
let skillCount = 0;
/**
* IDs authorized for runtime skill execution — starts as the ACL-scoped set
* and gets replaced with the active-filtered subset after catalog injection.
* Ensures `getSkillByName` cannot resolve a deactivated skill even if the
* LLM (or a direct-invocation path) names one.
*/
let executableSkillIds = params.accessibleSkillIds;
let activeSkillNames: Set<string> | undefined;
const { accessibleSkillIds } = params;
/**
* Authoring runs go through catalog injection even with nothing accessible:
* `injectSkillCatalog` owns the `skill` tool registration, and a model that
* can write `skills/{skillName}/SKILL.md` needs the tool bound at init to
* invoke what it creates later in the same conversation.
*/
if ((accessibleSkillIds && accessibleSkillIds.length > 0) || skillAuthoringAvailable) {
const skillResult = await injectSkillCatalog({
agent,
toolDefinitions,
toolRegistry,
accessibleSkillIds: accessibleSkillIds ?? [],
skillAuthoringAvailable,
contextWindowTokens: Number(agentMaxContextTokens) || 200_000,
listSkillsByAccess: db?.listSkillsByAccess,
codeEnvAvailable: effectiveCodeEnvAvailable,
statefulSessions: effectiveStatefulSessions,
workspaceTools: attachedWorkspaceTools,
workspaceOperations: attachedWorkspaceOperations,
userId: user?.id,
workspaceCommandTimeoutMaxMs: attachedWorkspaceCommandTimeoutMaxMs,
workspaceCommandTimeoutDefaultMs: attachedWorkspaceCommandTimeoutDefaultMs,
workspaceReadFileDefaultLines: attachedWorkspaceReadFileDefaultLines,
workspaceEnvironment: trustedCodeExecutionContext.codeWorkspace?.environment,
workspaceLinkedWorktrees: trustedCodeExecutionContext.codeWorkspace?.linkedWorktrees,
workspaceNativeSandbox: trustedCodeExecutionContext.codeWorkspace?.nativeSandbox,
skillStates: params.skillStates,
defaultActiveOnShare: params.defaultActiveOnShare,
maxCatalogSkills: getMaxCatalogSkills(runtime),
resolvedCatalog: resolvedSkillCatalog,
});
toolDefinitions = skillResult.toolDefinitions;
skillCount = skillResult.skillCount;
executableSkillIds = skillResult.activeSkillIds;
activeSkillNames = skillResult.activeSkillNames;
recordCapabilityToolNames(AgentCapabilities.skills, skillResult.toolNames);
}
/**
* Intent labels run LAST, after every registration step — the skill
* catalog above both appends its own definition and REPLACES upgraded ones
* (e.g. the skill-aware `read_file`), so an earlier injection would be
* clobbered. Injection PREPENDS while background's param APPENDS, so
* `intent` is the first schema property regardless of this ordering.
* The sanitize pass then enforces the flip side: with the capability off
* it strips SDK-native intent labels (a real admin kill switch); with it
* on it enforces explicit per-tool opt-outs on late-registered
* definitions. Both are marker-guarded — a tool's own `intent` business
* parameter is never touched.
*/
if (params.toolIntentsAvailable === true) {
const intentResult = applyIntentLabels({
toolDefinitions,
toolRegistry,
toolOptions: agent.tool_options,
capabilityToolNames,
});
toolDefinitions = intentResult.toolDefinitions;
if (intentResult.intentToolNames.length > 0) {
intentToolNames = intentResult.intentToolNames;
}
}
const intentSanitized = sanitizeIntentLabels({
toolDefinitions,
toolRegistry,
toolOptions: agent.tool_options,
capabilityEnabled: params.toolIntentsAvailable === true,
capabilityToolNames,
});
toolDefinitions = intentSanitized.toolDefinitions;
if (intentSanitized.semanticIntentToolNames.length > 0) {
semanticIntentToolNames = intentSanitized.semanticIntentToolNames;
}
if (intentSanitized.semanticIntentBlockedToolNames.length > 0) {
semanticIntentBlockedToolNames = intentSanitized.semanticIntentBlockedToolNames;
}
const hasFinalAgentTools =
(structuredTools?.length ?? 0) > 0 || (toolDefinitions?.length ?? 0) > 0;
if (isGoogleToolCombinationProvider(agent.provider) && hasProviderTools && hasFinalAgentTools) {
assertGoogleToolCombinationSupport(llmConfig.model);
if (
shouldIncludeGoogleServerSideToolInvocations({
provider: agent.provider,
hasProviderTools,
hasAgentTools: hasFinalAgentTools,
})
) {
enableGoogleServerSideToolInvocations({ agent, llmConfig });
}
}
const agentMaxContextNum = Number(agentMaxContextTokens) || DEFAULT_MAX_CONTEXT_TOKENS;
const maxOutputTokensNum = Number(maxOutputTokens) || 0;
const baseContextTokens = Math.max(0, agentMaxContextNum - maxOutputTokensNum);
const toMongoFiles = (files: Array<TFile | undefined> | undefined): IMongoFile[] =>
(files ?? []).filter((a): a is TFile => a != null).map((a) => a as unknown as IMongoFile);
const loadedFileToolNames = new Set([
...(structuredTools ?? []).map((tool) => tool.name),
...(toolDefinitions ?? []).map((tool) => tool.name),
]);
const finalFileConsumers: TurnFileConsumers = {
executeCode:
wantsCodeFiles &&
(loadedFileToolNames.has(Tools.execute_code) ||
(loadedFileToolNames.has('bash_tool') && loadedFileToolNames.has('read_file'))),
fileSearch: wantsSearchFiles && loadedFileToolNames.has(Tools.file_search),
};
const consumersChanged =
fileConsumers.executeCode !== finalFileConsumers.executeCode ||
fileConsumers.fileSearch !== finalFileConsumers.fileSearch;
Object.assign(fileConsumers, finalFileConsumers);
const finalizeAttachments = (files: Array<TFile | undefined> | undefined): IMongoFile[] => {
const hydrated = toMongoFiles(files);
return consumersChanged
? applyTurnDelivery(hydrated, { routing: deliveryRouting, consumers: fileConsumers })
: hydrated;
};
const finalAttachments = finalizeAttachments(primedAttachments);
const finalRequestAttachments = consumersChanged
? applyTurnDelivery(
(primedRequestAttachments ?? []).filter((file): file is TFile => file != null),
{
routing: deliveryRouting,
consumers: fileConsumers,
},
)
: primedRequestAttachments;
const requestAttachments = toMongoFiles(finalRequestAttachments);
const agentContextAttachments = finalizeAttachments(primedAgentContextAttachments);
if (consumersChanged) {
/* A loader may drop a reader, including a skill extra on retry. Newly model-bound text
* must pass admission before it can escape initialization, just like initial fallback. */
const admissionFileIds = new Set(
(authorizedRunFiles ?? requestUsageFiles).map((file) => file.file_id),
);
assertAgentAttachmentLimits({
attachments: requestAttachments.filter(
(file) => admissionFileIds.has(file.file_id) && isModelBoundAttachmentFile(file),
),
fileConfig: appConfig?.fileConfig,
endpoint: agent.endpoint ?? '',
endpointType: endpointFileType,
});
assertModelBoundContent({
filters: appConfig?.filters,
files: [...finalAttachments, ...requestAttachments, ...agentContextAttachments],
});
}
const currentRequestFileIds = new Set(requestFileIds);
const currentRequestAttachments: TFile[] = (finalRequestAttachments ?? [])
.filter((file): file is TFile => file != null && currentRequestFileIds.has(file.file_id))
.map((file) => ({
...file,
user: String(file.user),
...(file._id == null ? {} : { _id: String(file._id) }),
}));
const compatibilityAttachments =
finalAttachments.length > 0
? finalAttachments
: requestAttachments.concat(agentContextAttachments);
const endpointConfigs = appConfig?.endpoints;
const providerConfig =
customEndpointConfig ?? endpointConfigs?.[agent.provider as keyof typeof endpointConfigs];
const providerMaxToolResultChars =
providerConfig != null &&
typeof providerConfig === 'object' &&
!Array.isArray(providerConfig) &&
'maxToolResultChars' in providerConfig
? (providerConfig.maxToolResultChars as number | undefined)
: undefined;
const maxToolResultCharsResolved =
providerMaxToolResultChars ?? endpointConfigs?.all?.maxToolResultChars;
const fileAuthoringToolNames = new Set(
(toolDefinitions ?? [])
.filter((toolDefinition) => isFileAuthoringToolDefinition(toolDefinition))
.map((toolDefinition) => toolDefinition.name),
);
const initializedAgent: InitializedAgent = {
...agent,
azureOptions: options.azureOptions,
resendFiles,
imageDetail,
deliveryRouting,
toolRegistry,
mcpAvailableTools,
requestScopedConnections,
tool_resources: runtimeToolResources,
userMCPAuthMap,
toolDefinitions,
hasDeferredTools,
mcpToolAliases,
backgroundToolNames,
intentToolNames,
semanticIntentToolNames,
semanticIntentBlockedToolNames,
actionsEnabled,
accessibleMcpServerNames: resolvedAuditNames,
baseContextTokens,
memoryToolsRegistered: inlineMemoryRegistered,
codeEnvAvailable: effectiveCodeEnvAvailable,
statefulCodeSessions: effectiveStatefulSessions,
statefulCodeEnvironment,
codeSessionKey: trustedCodeExecutionContext.codeSessionKey,
codeExecutionContext: trustedCodeExecutionContext,
reasoningKey: customEndpointConfig?.customParams?.reasoningKey,
includeReasoningHistory: customEndpointConfig?.customParams?.includeReasoningHistory,
skillAuthoringAvailable,
fileAuthoringToolNames: fileAuthoringToolNames.size > 0 ? fileAuthoringToolNames : undefined,
skillCount,
accessibleSkillIds: executableSkillIds,
activeSkillNames,
manualSkillPrimes,
alwaysApplySkillPrimes,
attachments: compatibilityAttachments,
requestAttachments,
currentRequestAttachments,
agentContextAttachments,
fileConsumers,
toolContextMap: toolContextMap ?? {},
dynamicToolContextMap: dynamicToolContextMap ?? {},
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
: Math.max(1024, Math.round(baseContextTokens * (1 - DEFAULT_RESERVE_RATIO))),
primedCodeFiles,
codeContextEntries,
endpointTokenConfig: options.endpointTokenConfig,
instructionsPromptFacts,
};
prepareQueuedCodeFileContext(initializedAgent, [initializedAgent], user?.id);
const queuedFileContext = initializedAgent.dynamicToolContextMap?.queued_code_files;
if (typeof queuedFileContext === 'string') {
assertModelBoundContent({
filters: appConfig?.filters,
files: [{ content: queuedFileContext }],
});
}
/**
* Usage is recorded only once initialization has fully succeeded — every
* step above (tool loading, resource priming, provider setup, the queued
* code file content check just above) has already run without throwing. A
* resolved link with no `instructionsPromptFacts` never reaches here; an
* initialization that throws after resolution never reaches here either,
* so it records no use. Fire-and-forget: the turn does not wait on the
* increment, and `recordUse` itself catches and logs its own errors. The
* `typeof` guard is load-bearing, not defensive noise: `resolveLinkedInstructions`
* is typed as a plain callable in `InitializeAgentParams`, so a
* caller-supplied plain function (matching the type but not the resolver's
* `Object.assign(resolve, { recordUse })` shape) would otherwise throw here
* — after initialization has already fully succeeded — rather than
* silently recording no usage.
*/
if (
instructionsPromptFacts &&
(params.recordLinkedPromptUsage ?? true) &&
typeof params.resolveLinkedInstructions?.recordUse === 'function'
) {
params.resolveLinkedInstructions.recordUse(instructionsPromptFacts);
}
return initializedAgent;
}