Skip to content

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

🎻 refactor: Orchestrate Agent Runs Through a Request-Free Host (#15366)

Danny Avila30124f21b216
diff --git a/CONTEXT.md b/CONTEXT.md
index b51a341892..30f79289b6 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -1,6 +1,8 @@
# Domain language
- **Agent run envelope**: the versioned, JSON-safe request contract created after ingress authentication and protocol validation but before agent, provider, tool, or MCP initialization. It carries only the validated protocol payload and the minimum trusted principal identifiers. The execution host rehydrates all runtime state from those identifiers.
+- **Agent execution context**: runtime-only, transport-free state rehydrated beside an Agent run envelope. It contains the authenticated user, application configuration, normalized request metadata, and resolved conversation facts needed by initialization, but never Express request/response objects or serialized credentials.
+- **Agent execution host**: the protocol-neutral module that owns run admission, disconnect cancellation, provider-start fencing, and terminal settlement. Protocol implementations execute behind its callback interface; HTTP adapters retain validation and final stream rendering.
- **Agent execution enrollment**: the durable, protocol-neutral lifecycle authority for an admitted Agent run. It is created under the authenticated user and tenant before user-owned initialization, rechecks the shared owner-deletion admission fence after registration, exposes the only provider abort signal, fences exact provider start, terminalizes the run, waits for every trailing usage, artifact, and stored-response write, and acknowledges provider drain last. A transient terminalization failure is reconciled after trailing writes; provider drain is never acknowledged while the exact job remains nonterminal. Delete-all holds the owner fence, drains every owner run before selecting its first persistence snapshot, and repeats both the drain and an idempotent owner-persistence sweep after any recovered fence lapse before releasing admission. Exact-conversation deletion additionally performs an unconditional idempotent cleanup over its immutable deleted-ID set because a fully drained run may leave the active index after racing the first delete; only the explicit empty result is benign, while storage failures remain fatal. Chat Completions, Responses, Channels, and future ingress adapters share this authority without moving LibreChat persistence policy into the Agents SDK.
- **Agent turn execution plan**: the immutable, request-local decision compiled once after authentication, agent resolution, and tool initialization. It records the trusted turn origin, conversation lineage, pause capability, binding/action context, and the preferred checkpoint, history, or fresh state-loading strategy without executing the model or owning persistence. Checkpoint failure falls back to durable history within the same Agents lifecycle.
- **Effective agent selection**: the resolved endpoint and agent identity after an enforced model spec is applied. Authorization and agent loading must consume this same identity before the Agent run envelope is initialized.
diff --git a/api/server/controllers/agents/__tests__/openai.spec.js b/api/server/controllers/agents/__tests__/openai.spec.js
index 758816235b..b1897a08cc 100644
--- a/api/server/controllers/agents/__tests__/openai.spec.js
+++ b/api/server/controllers/agents/__tests__/openai.spec.js
@@ -173,6 +173,7 @@ jest.mock('@librechat/agents', () => ({
}));
jest.mock('@librechat/api', () => ({
+ createAgentExecutionContext: (context) => context,
collectReachableAgents: (roots) => {
const agents = [];
const pending = [...roots];
@@ -295,7 +296,48 @@ jest.mock('@librechat/api', () => ({
userMCPAuthMap: undefined,
}),
resolveSubagentGraphs: jest.fn().mockResolvedValue(undefined),
- enrollAgentExecution: (...args) => mockEnrollAgentExecution(...args),
+ executeAgentRun: async ({
+ envelope,
+ runId,
+ conversationId,
+ connection,
+ isPrincipalActive,
+ execute,
+ handleExecutionError,
+ beforeSettle,
+ }) => {
+ let execution;
+ let executionError;
+ let closed = connection?.isClosed() ?? false;
+ const removeCloseListener =
+ connection?.onClose(() => {
+ closed = true;
+ execution?.abort();
+ }) ?? (() => undefined);
+ try {
+ execution = await mockEnrollAgentExecution({
+ runId,
+ userId: envelope.principal.userId,
+ conversationId,
+ agentId: envelope.payload.model,
+ protocol: envelope.protocol,
+ isPrincipalActive,
+ });
+ if (closed || connection?.isClosed() === true) execution.abort();
+ await execution.beginProviderExecution();
+ return await execute(execution);
+ } catch (error) {
+ executionError = error;
+ if (handleExecutionError) return await handleExecutionError(error);
+ throw error;
+ } finally {
+ removeCloseListener();
+ if (execution) {
+ await beforeSettle?.(execution, executionError);
+ await execution.settle(executionError);
+ }
+ }
+ },
waitForAgentExecutionWrites: async (writes) => {
const results = await Promise.allSettled(writes);
const failure = results.find((result) => result.status === 'rejected');
diff --git a/api/server/controllers/agents/__tests__/responses.unit.spec.js b/api/server/controllers/agents/__tests__/responses.unit.spec.js
index 5ffa6e554d..2ad9558aa9 100644
--- a/api/server/controllers/agents/__tests__/responses.unit.spec.js
+++ b/api/server/controllers/agents/__tests__/responses.unit.spec.js
@@ -196,6 +196,7 @@ jest.mock('@librechat/agents', () => ({
}));
jest.mock('@librechat/api', () => ({
+ createAgentExecutionContext: (context) => context,
SAFE_CONVERSATION_TITLE: 'New Chat',
resolveConversationTitle: (...args) => mockResolveConversationTitle(...args),
/** Pass-through: the controller strips UI-only activity-label parts
@@ -361,7 +362,48 @@ jest.mock('@librechat/api', () => ({
on_run_step_delta: { handle: jest.fn() },
on_chat_model_end: { handle: jest.fn() },
}),
- enrollAgentExecution: (...args) => mockEnrollAgentExecution(...args),
+ executeAgentRun: async ({
+ envelope,
+ runId,
+ conversationId,
+ connection,
+ isPrincipalActive,
+ execute,
+ handleExecutionError,
+ beforeSettle,
+ }) => {
+ let execution;
+ let executionError;
+ let closed = connection?.isClosed() ?? false;
+ const removeCloseListener =
+ connection?.onClose(() => {
+ closed = true;
+ execution?.abort();
+ }) ?? (() => undefined);
+ try {
+ execution = await mockEnrollAgentExecution({
+ runId,
+ userId: envelope.principal.userId,
+ conversationId,
+ agentId: envelope.payload.model,
+ protocol: envelope.protocol,
+ isPrincipalActive,
+ });
+ if (closed || connection?.isClosed() === true) execution.abort();
+ await execution.beginProviderExecution();
+ return await execute(execution);
+ } catch (error) {
+ executionError = error;
+ if (handleExecutionError) return await handleExecutionError(error);
+ throw error;
+ } finally {
+ removeCloseListener();
+ if (execution) {
+ await beforeSettle?.(execution, executionError);
+ await execution.settle(executionError);
+ }
+ }
+ },
waitForAgentExecutionWrites: async (writes) => {
const results = await Promise.allSettled(writes);
const failure = results.find((result) => result.status === 'rejected');
diff --git a/api/server/controllers/agents/openai.js b/api/server/controllers/agents/openai.js
index 226e9215c2..8872f0aeab 100644
--- a/api/server/controllers/agents/openai.js
+++ b/api/server/controllers/agents/openai.js
@@ -20,6 +20,7 @@ const {
buildAgentContextAttachmentsByAgentId,
AgentRunEnvelopeError,
createAgentRunEnvelope,
+ createAgentExecutionContext,
createMCPRuntimeRequestBody,
loadSkillStates,
sendFinalChunk,
@@ -60,7 +61,7 @@ const {
createOpenAIContentAggregator,
isChatCompletionValidationFailure,
stripActivityLabelParts,
- enrollAgentExecution,
+ executeAgentRun,
waitForAgentExecutionWrites,
} = require('@librechat/api');
const {
@@ -108,14 +109,15 @@ function getUserFacingProviderError(error, protectionEnabled) {
/**
* Creates a tool loader function for the agent.
- * @param {AbortSignal} signal - The abort signal
- * @param {boolean} [definitionsOnly=true] - When true, returns only serializable
+ * @param {Object} runtime - Request-backed tool adapter state
+ * @param {import('express').Request} runtime.req
+ * @param {import('express').Response} runtime.res
+ * @param {AbortSignal} runtime.signal - The abort signal
+ * @param {boolean} [runtime.definitionsOnly=true] - When true, returns only serializable
* tool definitions without creating full tool instances (for event-driven mode)
*/
-function createToolLoader(signal, definitionsOnly = true) {
+function createToolLoader({ req, res, signal, definitionsOnly = true }) {
return async function loadTools({
- req,
- res,
tools,
model,
agentId,
@@ -231,6 +233,40 @@ function sendErrorResponse(res, statusCode, message, type = 'invalid_request_err
res.status(statusCode).json(createErrorResponse(message, type, code));
}
+function handleExecutionError({ error, res, context, appConfig }) {
+ logger.error('[OpenAI API] Error:', getSafeErrorMetadata(error));
+ const protectionEnabled = hasModelBoundContentProtection(
+ appConfig?.filters,
+ appConfig?.messageFilter?.pii,
+ );
+ const errorMessage = getUserFacingProviderError(error, protectionEnabled);
+
+ if (res.headersSent) {
+ const errorChunk = createChunk(context, { content: `\n\nError: ${errorMessage}` }, 'stop');
+ writeSSE(res, errorChunk);
+ writeSSE(res, '[DONE]');
+ res.end();
+ return;
+ }
+ if (isContentFilterError(error)) {
+ return sendErrorResponse(
+ res,
+ error.statusCode,
+ error.body.message,
+ 'invalid_request_error',
+ error.body.error,
+ );
+ }
+ const statusCode =
+ typeof error?.status === 'number' && error.status >= 400 && error.status < 600
+ ? error.status
+ : 500;
+ const errorType =
+ statusCode >= 400 && statusCode < 500 ? 'invalid_request_error' : 'server_error';
+ const errorCode = !protectionEnabled && typeof error?.code === 'string' ? error.code : null;
+ sendErrorResponse(res, statusCode, errorMessage, errorType, errorCode);
+}
+
/**
* Runs a validated chat-completions envelope in the current process.
* Express remains runtime-only state while the envelope is the portable run input.
@@ -243,9 +279,17 @@ const executeOpenAIChatCompletion = async (envelope, { req, res }) => {
const requestStartTime = envelope.receivedAt;
const request = envelope.payload;
const { principal } = envelope;
- // The local executor keeps the current Express-dependent initialization path,
- // but all request-body reads now observe the detached envelope payload.
+ // Request-backed tool adapters still observe the validated envelope payload;
+ // shared initialization receives the transport-free runtime below.
req.body = request;
+ const agentRuntime = createAgentExecutionContext({
+ user: req.user,
+ appConfig,
+ requestBody: request,
+ conversationCreatedAt: req.conversationCreatedAt,
+ resolvedConversation: req.resolvedConversation,
+ hasResolvedConversation: Object.prototype.hasOwnProperty.call(req, 'resolvedConversation'),
+ });
const agentId = request.model;
const manualSkills = extractManualSkills(req.body);
@@ -348,832 +392,801 @@ const executeOpenAIChatCompletion = async (envelope, { req, res }) => {
);
const conversationId = request.conversation_id ?? nanoid();
- let execution;
- let executionError;
- let responseClosed = res.destroyed === true && res.writableEnded !== true;
/** @type {Promise<import('librechat-data-provider').TAttachment | null>[]} */
const artifactPromises = [];
let artifactWritesCovered = false;
- const abortOnResponseClose = () => {
- if (res.writableEnded === true) {
- return;
- }
- responseClosed = true;
- if (execution && !execution.signal.aborted) {
- execution.abort();
- logger.debug('[OpenAI API] Client disconnected, aborting');
- }
- };
- res.once('close', abortOnResponseClose);
- try {
- execution = await enrollAgentExecution({
- runId: responseId,
- userId: principal.userId,
- conversationId,
- agentId,
- protocol: 'chat.completions',
- /** Conversation delete-all uses the shared owner-admission fence. Remote
- * execution must observe it after durable enrollment and before provider work. */
- isPrincipalActive: db.isSubagentOwnerAdmissible,
- });
- if (responseClosed || (res.destroyed === true && res.writableEnded !== true)) {
- execution.abort();
- }
- await execution.beginProviderExecution();
-
- if (request.conversation_id != null) {
- if (typeof request.conversation_id !== 'string') {
- return sendErrorResponse(
- res,
- 400,
- 'conversation_id must be a string',
- 'invalid_request_error',
+ return executeAgentRun({
+ envelope,
+ runId: responseId,
+ conversationId,
+ connection: {
+ isClosed: () => res.destroyed === true && res.writableEnded !== true,
+ onClose: (listener) => {
+ const abortOnResponseClose = () => {
+ if (res.writableEnded !== true) {
+ logger.debug('[OpenAI API] Client disconnected, aborting');
+ listener();
+ }
+ };
+ res.once('close', abortOnResponseClose);
+ return () => res.off('close', abortOnResponseClose);
+ },
+ },
+ /** Conversation delete-all uses the shared owner-admission fence. Remote
+ * execution must observe it after durable enrollment and before provider work. */
+ isPrincipalActive: db.isSubagentOwnerAdmissible,
+ beforeSettle: (execution) => {
+ if (!artifactWritesCovered && artifactPromises.length > 0) {
+ execution.track(
+ waitForAgentExecutionWrites(artifactPromises).catch((artifactError) => {
+ logger.warn(
+ '[OpenAI API] Error processing artifacts:',
+ getSafeErrorMetadata(artifactError),
+ );
+ }),
);
}
- if (!(await db.getConvo(principal.userId, request.conversation_id))) {
- return sendErrorResponse(res, 404, 'Conversation not found', 'invalid_request_error');
+ },
+ onSettlementError: (error) => {
+ logger.error('[OpenAI API] Failed to settle execution:', getSafeErrorMetadata(error));
+ },
+ handleExecutionError: (error) => handleExecutionError({ error, res, context, appConfig }),
+ execute: async (execution) => {
+ if (request.conversation_id != null) {
+ if (typeof request.conversation_id !== 'string') {
+ return sendErrorResponse(
+ res,
+ 400,
+ 'conversation_id must be a string',
+ 'invalid_request_error',
+ );
+ }
+ if (!(await db.getConvo(principal.userId, request.conversation_id))) {
+ return sendErrorResponse(res, 404, 'Conversation not found', 'invalid_request_error');
+ }
}
- }
- const parentMessageId = request.parent_message_id ?? null;
- let mcpParentMessageId;
- if (typeof request.parent_message_id === 'string' && request.parent_message_id.trim() !== '') {
- mcpParentMessageId = request.parent_message_id;
- } else if (request.conversation_id == null) {
- mcpParentMessageId = null;
- }
- const mcpRequestBody = createMCPRuntimeRequestBody({
- messageId: responseId,
- conversationId,
- parentMessageId: mcpParentMessageId,
- });
+ const parentMessageId = request.parent_message_id ?? null;
+ let mcpParentMessageId;
+ if (
+ typeof request.parent_message_id === 'string' &&
+ request.parent_message_id.trim() !== ''
+ ) {
+ mcpParentMessageId = request.parent_message_id;
+ } else if (request.conversation_id == null) {
+ mcpParentMessageId = null;
+ }
+ const mcpRequestBody = createMCPRuntimeRequestBody({
+ messageId: responseId,
+ conversationId,
+ parentMessageId: mcpParentMessageId,
+ });
- const agentsEConfig = appConfig?.endpoints?.[EModelEndpoint.agents];
- const allowedProviders = new Set(agentsEConfig?.allowedProviders);
+ const agentsEConfig = appConfig?.endpoints?.[EModelEndpoint.agents];
+ const allowedProviders = new Set(agentsEConfig?.allowedProviders);
- // Create tool loader
- const loadTools = createToolLoader(execution.signal);
+ // Create tool loader
+ const loadTools = createToolLoader({ req, res, signal: execution.signal });
- // Initialize the agent first to check for disableStreaming
- const endpointOption = {
- endpoint: agent.provider,
- model_parameters: agent.model_parameters ?? {},
- };
- const skillDbMethods = getSkillDbMethods();
-
- const dbMethods = {
- getConvoFiles: db.getConvoFiles,
- getFiles: db.getFiles,
- filterFilesByAgentAccess: filterFilesByRemoteAgentAccess,
- getUserKey: db.getUserKey,
- getMessages: db.getMessages,
- getAccessibleMcpServerNames,
- updateFilesUsage: db.updateFilesUsage,
- getUserKeyValues: db.getUserKeyValues,
- getUserCodeFiles: db.getUserCodeFiles,
- getToolFilesByIds: db.getToolFilesByIds,
- getCodeGeneratedFiles: db.getCodeGeneratedFiles,
- listSkillsByAccess: skillDbMethods.listSkillsByAccess,
- listAlwaysApplySkills: skillDbMethods.listAlwaysApplySkills,
- getSkillByName: skillDbMethods.getSkillByName,
- };
+ // Initialize the agent first to check for disableStreaming
+ const endpointOption = {
+ endpoint: agent.provider,
+ model_parameters: agent.model_parameters ?? {},
+ };
+ const skillDbMethods = getSkillDbMethods();
+
+ const dbMethods = {
+ getConvoFiles: db.getConvoFiles,
+ getFiles: db.getFiles,
+ filterFilesByAgentAccess: filterFilesByRemoteAgentAccess,
+ getUserKey: db.getUserKey,
+ getMessages: db.getMessages,
+ getAccessibleMcpServerNames,
+ updateFilesUsage: db.updateFilesUsage,
+ getUserKeyValues: db.getUserKeyValues,
+ getUserCodeFiles: db.getUserCodeFiles,
+ getToolFilesByIds: db.getToolFilesByIds,
+ getCodeGeneratedFiles: db.getCodeGeneratedFiles,
+ listSkillsByAccess: skillDbMethods.listSkillsByAccess,
+ listAlwaysApplySkills: skillDbMethods.listAlwaysApplySkills,
+ getSkillByName: skillDbMethods.getSkillByName,
+ };
- const enabledCapabilities = new Set(agentsEConfig?.capabilities);
- const memoryAvailable = await resolveMemoryAvailability({
- enabledCapabilities,
- memoryConfig: appConfig?.memory,
- user: req.user,
- getRoleByName: db.getRoleByName,
- });
- const skillsCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.skills);
- const ephemeralSkillsToggle = request.ephemeralAgent?.skills === true;
- const accessibleSkillIds = skillsCapabilityEnabled
- ? withDeploymentSkillIds(
- await findAccessibleResources({
+ const enabledCapabilities = new Set(agentsEConfig?.capabilities);
+ const memoryAvailable = await resolveMemoryAvailability({
+ enabledCapabilities,
+ memoryConfig: appConfig?.memory,
+ user: req.user,
+ getRoleByName: db.getRoleByName,
+ });
+ const skillsCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.skills);
+ const ephemeralSkillsToggle = request.ephemeralAgent?.skills === true;
+ const accessibleSkillIds = skillsCapabilityEnabled
+ ? withDeploymentSkillIds(
+ await findAccessibleResources({
+ userId: principal.userId,
+ role: principal.role,
+ resourceType: ResourceType.SKILL,
+ requiredPermissions: PermissionBits.VIEW,
+ }),
+ )
+ : [];
+ const editableSkillIds = skillsCapabilityEnabled
+ ? await findAccessibleResources({
userId: principal.userId,
role: principal.role,
resourceType: ResourceType.SKILL,
- requiredPermissions: PermissionBits.VIEW,
- }),
- )
- : [];
- const editableSkillIds = skillsCapabilityEnabled
- ? await findAccessibleResources({
- userId: principal.userId,
- role: principal.role,
- resourceType: ResourceType.SKILL,
- requiredPermissions: PermissionBits.EDIT,
- })
- : [];
- const skillCreateAllowed = skillsCapabilityEnabled
- ? await getSkillToolDeps().canCreateSkill({ req })
- : false;
-
- const { skillStates, defaultActiveOnShare } = await loadSkillStates({
- userId: principal.userId,
- appConfig,
- getUserById: db.getUserById,
- accessibleSkillIds,
- });
-
- const primaryScopedSkillIds = resolveAgentScopedSkillIds({
- agent,
- accessibleSkillIds,
- skillsCapabilityEnabled,
- ephemeralSkillsToggle,
- });
- const primaryScopedEditableSkillIds = resolveAgentScopedSkillIds({
- agent,
- accessibleSkillIds: editableSkillIds,
- skillsCapabilityEnabled,
- ephemeralSkillsToggle,
- });
+ requiredPermissions: PermissionBits.EDIT,
+ })
+ : [];
+ const skillCreateAllowed = skillsCapabilityEnabled
+ ? await getSkillToolDeps().canCreateSkill({ req })
+ : false;
+
+ const { skillStates, defaultActiveOnShare } = await loadSkillStates({
+ userId: principal.userId,
+ appConfig,
+ getUserById: db.getUserById,
+ accessibleSkillIds,
+ });
- const primaryConfig = await initializeAgent(
- {
- req,
- res,
- loadTools,
- requestFiles: [],
- conversationId,
- parentMessageId,
- requestBody: mcpRequestBody,
+ const primaryScopedSkillIds = resolveAgentScopedSkillIds({
agent,
- endpointOption,
- allowedProviders,
- isInitialAgent: true,
- accessibleSkillIds: primaryScopedSkillIds,
- skillAuthoringAvailable: canAuthorSkillFiles({
- agent,
- scopedEditableSkillIds: primaryScopedEditableSkillIds,
- skillCreateAllowed,
- skillsCapabilityEnabled,
- ephemeralSkillsToggle,
- }),
- codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
- backgroundToolsAvailable: enabledCapabilities.has(AgentCapabilities.run_in_background),
- toolIntentsAvailable: enabledCapabilities.has(AgentCapabilities.tool_intents),
- statefulSessionsAvailable: enabledCapabilities.has(
- AgentCapabilities.stateful_code_sessions,
- ),
- allowedStatefulCodeEnvironments: agentsEConfig?.statefulCodeSessions?.allowedEnvironments,
- memoryAvailable,
- skillStates,
- defaultActiveOnShare,
- manualSkills,
- },
- dbMethods,
- );
-
- /**
- * Per-agent tool-execution context map, keyed by agentId.
- * Needed so the ON_TOOL_EXECUTE callback routes each sub-agent's tool calls
- * to the correct toolRegistry / userMCPAuthMap / tool_resources.
- * @type {Map<string, {
- * agent: object,
- * toolRegistry?: import('@librechat/agents').LCToolRegistry,
- * requestScopedConnections?: import('@librechat/api').RequestScopedMCPConnectionStore,
- * userMCPAuthMap?: Record<string, Record<string, string>>,
- * tool_resources?: object,
- * actionsEnabled?: boolean,
- * }>}
- */
- const agentToolContexts = new Map();
- agentToolContexts.set(
- primaryConfig.id,
- buildAgentToolContext({ agent, config: primaryConfig }),
- );
+ accessibleSkillIds,
+ skillsCapabilityEnabled,
+ ephemeralSkillsToggle,
+ });
+ const primaryScopedEditableSkillIds = resolveAgentScopedSkillIds({
+ agent,
+ accessibleSkillIds: editableSkillIds,
+ skillsCapabilityEnabled,
+ ephemeralSkillsToggle,
+ });
- let handoffAgentConfigs = new Map();
- let discoveredEdges = [];
- let discoveredMCPAuthMap;
- const subagentsCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.subagents);
- const primaryHasGraphSubagents =
- subagentsCapabilityEnabled &&
- primaryConfig.subagents?.enabled === true &&
- (primaryConfig.subagents.graphs?.length ?? 0) > 0;
- if (primaryConfig.edges?.length || primaryHasGraphSubagents) {
- const modelsConfig = await getModelsConfig(req);
- const discoveryParams = {
- req,
- res,
- primaryConfig,
- endpointOption,
- allowedProviders,
- modelsConfig,
- loadTools,
- requestFiles: [],
- conversationId,
- parentMessageId,
- requestBody: mcpRequestBody,
- resourceType: ResourceType.REMOTE_AGENT,
- computeAccessibleSkillIds: (handoffAgent) =>
- resolveAgentScopedSkillIds({
- agent: handoffAgent,
- accessibleSkillIds,
+ const primaryConfig = await initializeAgent(
+ {
+ runtime: agentRuntime,
+ loadTools,
+ requestFiles: [],
+ conversationId,
+ parentMessageId,
+ requestBody: mcpRequestBody,
+ agent,
+ endpointOption,
+ allowedProviders,
+ isInitialAgent: true,
+ accessibleSkillIds: primaryScopedSkillIds,
+ skillAuthoringAvailable: canAuthorSkillFiles({
+ agent,
+ scopedEditableSkillIds: primaryScopedEditableSkillIds,
+ skillCreateAllowed,
skillsCapabilityEnabled,
ephemeralSkillsToggle,
}),
- computeSkillAuthoringAvailable: (handoffAgent) =>
- canAuthorSkillFiles({
- agent: handoffAgent,
- scopedEditableSkillIds: resolveAgentScopedSkillIds({
+ codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
+ backgroundToolsAvailable: enabledCapabilities.has(AgentCapabilities.run_in_background),
+ toolIntentsAvailable: enabledCapabilities.has(AgentCapabilities.tool_intents),
+ statefulSessionsAvailable: enabledCapabilities.has(
+ AgentCapabilities.stateful_code_sessions,
+ ),
+ allowedStatefulCodeEnvironments: agentsEConfig?.statefulCodeSessions?.allowedEnvironments,
+ memoryAvailable,
+ skillStates,
+ defaultActiveOnShare,
+ manualSkills,
+ },
+ dbMethods,
+ );
+
+ /**
+ * Per-agent tool-execution context map, keyed by agentId.
+ * Needed so the ON_TOOL_EXECUTE callback routes each sub-agent's tool calls
+ * to the correct toolRegistry / userMCPAuthMap / tool_resources.
+ * @type {Map<string, {
+ * agent: object,
+ * toolRegistry?: import('@librechat/agents').LCToolRegistry,
+ * requestScopedConnections?: import('@librechat/api').RequestScopedMCPConnectionStore,
+ * userMCPAuthMap?: Record<string, Record<string, string>>,
+ * tool_resources?: object,
+ * actionsEnabled?: boolean,
+ * }>}
+ */
+ const agentToolContexts = new Map();
+ agentToolContexts.set(
+ primaryConfig.id,
+ buildAgentToolContext({ agent, config: primaryConfig }),
+ );
+
+ let handoffAgentConfigs = new Map();
+ let discoveredEdges = [];
+ let discoveredMCPAuthMap;
+ const subagentsCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.subagents);
+ const primaryHasGraphSubagents =
+ subagentsCapabilityEnabled &&
+ primaryConfig.subagents?.enabled === true &&
+ (primaryConfig.subagents.graphs?.length ?? 0) > 0;
+ if (primaryConfig.edges?.length || primaryHasGraphSubagents) {
+ const modelsConfig = await getModelsConfig(req);
+ const discoveryParams = {
+ req,
+ res,
+ primaryConfig,
+ endpointOption,
+ allowedProviders,
+ modelsConfig,
+ loadTools,
+ requestFiles: [],
+ conversationId,
+ parentMessageId,
+ requestBody: mcpRequestBody,
+ resourceType: ResourceType.REMOTE_AGENT,
+ computeAccessibleSkillIds: (handoffAgent) =>
+ resolveAgentScopedSkillIds({
agent: handoffAgent,
- accessibleSkillIds: editableSkillIds,
+ accessibleSkillIds,
skillsCapabilityEnabled,
ephemeralSkillsToggle,
}),
- skillCreateAllowed,
- skillsCapabilityEnabled,
- ephemeralSkillsToggle,
- }),
- skillStates,
- defaultActiveOnShare,
- codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
- backgroundToolsAvailable: enabledCapabilities.has(AgentCapabilities.run_in_background),
- toolIntentsAvailable: enabledCapabilities.has(AgentCapabilities.tool_intents),
- statefulSessionsAvailable: enabledCapabilities.has(
- AgentCapabilities.stateful_code_sessions,
- ),
- allowedStatefulCodeEnvironments: agentsEConfig?.statefulCodeSessions?.allowedEnvironments,
- memoryAvailable,
- };
- const discoveryDeps = {
- getAgent: db.getAgent,
- checkPermission: async ({ userId, role, resourceId, requiredPermission }) => {
- const permissions = await getRemoteAgentPermissions(
- { getEffectivePermissions },
- userId,
- role,
- resourceId,
- );
- return hasPermissions(permissions, requiredPermission);
- },
- logViolation,
- db: dbMethods,
- onAgentInitialized: (loadedAgentId, loadedAgent, config) => {
- agentToolContexts.set(
- loadedAgentId,
- buildAgentToolContext({ agent: loadedAgent, config }),
- );
- },
- initializeAgent,
- };
- if (primaryConfig.edges?.length) {
- ({
- agentConfigs: handoffAgentConfigs,
- edges: discoveredEdges,
- userMCPAuthMap: discoveredMCPAuthMap,
- } = await discoverConnectedAgents(discoveryParams, discoveryDeps));
- }
- if (subagentsCapabilityEnabled) {
- discoveredMCPAuthMap = await resolveSubagentGraphs(
- {
- ...discoveryParams,
- rootConfigs: [primaryConfig, ...handoffAgentConfigs.values()],
+ computeSkillAuthoringAvailable: (handoffAgent) =>
+ canAuthorSkillFiles({
+ agent: handoffAgent,
+ scopedEditableSkillIds: resolveAgentScopedSkillIds({
+ agent: handoffAgent,
+ accessibleSkillIds: editableSkillIds,
+ skillsCapabilityEnabled,
+ ephemeralSkillsToggle,
+ }),
+ skillCreateAllowed,
+ skillsCapabilityEnabled,
+ ephemeralSkillsToggle,
+ }),
+ skillStates,
+ defaultActiveOnShare,
+ codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
+ backgroundToolsAvailable: enabledCapabilities.has(AgentCapabilities.run_in_background),
+ toolIntentsAvailable: enabledCapabilities.has(AgentCapabilities.tool_intents),
+ statefulSessionsAvailable: enabledCapabilities.has(
+ AgentCapabilities.stateful_code_sessions,
+ ),
+ allowedStatefulCodeEnvironments: agentsEConfig?.statefulCodeSessions?.allowedEnvironments,
+ memoryAvailable,
+ };
+ const discoveryDeps = {
+ getAgent: db.getAgent,
+ checkPermission: async ({ userId, role, resourceId, requiredPermission }) => {
+ const permissions = await getRemoteAgentPermissions(
+ { getEffectivePermissions },
+ userId,
+ role,
+ resourceId,
+ );
+ return hasPermissions(permissions, requiredPermission);
},
- discoveryDeps,
- );
+ logViolation,
+ db: dbMethods,
+ onAgentInitialized: (loadedAgentId, loadedAgent, config) => {
+ agentToolContexts.set(
+ loadedAgentId,
+ buildAgentToolContext({ agent: loadedAgent, config }),
+ );
+ },
+ initializeAgent,
+ };
+ if (primaryConfig.edges?.length) {
+ ({
+ agentConfigs: handoffAgentConfigs,
+ edges: discoveredEdges,
+ userMCPAuthMap: discoveredMCPAuthMap,
+ } = await discoverConnectedAgents(discoveryParams, discoveryDeps));
+ }
+ if (subagentsCapabilityEnabled) {
+ discoveredMCPAuthMap = await resolveSubagentGraphs(
+ {
+ ...discoveryParams,
+ rootConfigs: [primaryConfig, ...handoffAgentConfigs.values()],
+ },
+ discoveryDeps,
+ );
+ }
}
- }
- primaryConfig.edges = discoveredEdges;
- const runAgents = [primaryConfig, ...handoffAgentConfigs.values()];
- const endpointTokenConfigByAgentId = new Map();
- for (const [agentId, context] of agentToolContexts) {
- endpointTokenConfigByAgentId.set(agentId, context.endpointTokenConfig);
- }
- const resolveEndpointTokenConfig = (usage) =>
- resolveAgentTokenConfig({
- agentId: usage?.agentId,
- byAgentId: endpointTokenConfigByAgentId,
- fallback: primaryConfig.endpointTokenConfig,
- });
- const modelBoundAgentsById = new Map();
- const pendingModelBoundAgents = [...runAgents];
- for (let index = 0; index < pendingModelBoundAgents.length; index++) {
- const runAgent = pendingModelBoundAgents[index];
- if (!runAgent?.id || modelBoundAgentsById.has(runAgent.id)) {
- continue;
- }
- modelBoundAgentsById.set(runAgent.id, runAgent);
- for (const subagent of runAgent.subagentAgentConfigs?.values?.() ?? []) {
- pendingModelBoundAgents.push(subagent);
+ primaryConfig.edges = discoveredEdges;
+ const runAgents = [primaryConfig, ...handoffAgentConfigs.values()];
+ const endpointTokenConfigByAgentId = new Map();
+ for (const [agentId, context] of agentToolContexts) {
+ endpointTokenConfigByAgentId.set(agentId, context.endpointTokenConfig);
}
- for (const graph of runAgent.subagentGraphConfigs ?? []) {
- pendingModelBoundAgents.push(...graph.memberConfigs);
+ const resolveEndpointTokenConfig = (usage) =>
+ resolveAgentTokenConfig({
+ agentId: usage?.agentId,
+ byAgentId: endpointTokenConfigByAgentId,
+ fallback: primaryConfig.endpointTokenConfig,
+ });
+ const modelBoundAgentsById = new Map();
+ const pendingModelBoundAgents = [...runAgents];
+ for (let index = 0; index < pendingModelBoundAgents.length; index++) {
+ const runAgent = pendingModelBoundAgents[index];
+ if (!runAgent?.id || modelBoundAgentsById.has(runAgent.id)) {
+ continue;
+ }
+ modelBoundAgentsById.set(runAgent.id, runAgent);
+ for (const subagent of runAgent.subagentAgentConfigs?.values?.() ?? []) {
+ pendingModelBoundAgents.push(subagent);
+ }
+ for (const graph of runAgent.subagentGraphConfigs ?? []) {
+ pendingModelBoundAgents.push(...graph.memberConfigs);
+ }
}
- }
- const modelBoundAgents = [...modelBoundAgentsById.values()];
- const manualSkillPrimes = primaryConfig.manualSkillPrimes;
- const alwaysApplySkillPrimes = primaryConfig.alwaysApplySkillPrimes;
- assertModelBoundContent({
- filters: appConfig?.filters,
- legacyPii: appConfig?.messageFilter?.pii,
- submittedMessages: request.messages,
- agents: modelBoundAgents,
- skills: [...(manualSkillPrimes ?? []), ...(alwaysApplySkillPrimes ?? [])],
- files: collectModelBoundAgentFiles(modelBoundAgents),
- });
+ const modelBoundAgents = [...modelBoundAgentsById.values()];
+ const manualSkillPrimes = primaryConfig.manualSkillPrimes;
+ const alwaysApplySkillPrimes = primaryConfig.alwaysApplySkillPrimes;
+ assertModelBoundContent({
+ filters: appConfig?.filters,
+ legacyPii: appConfig?.messageFilter?.pii,
+ submittedMessages: request.messages,
+ agents: modelBoundAgents,
+ skills: [...(manualSkillPrimes ?? []), ...(alwaysApplySkillPrimes ?? [])],
+ files: collectModelBoundAgentFiles(modelBoundAgents),
+ });
- // Determine if streaming is enabled (check both request and agent config)
- const streamingDisabled = !!primaryConfig.model_parameters?.disableStreaming;
- const isStreaming = request.stream === true && !streamingDisabled;
-
- // Create tracker for streaming or aggregator for non-streaming
- const tracker = isStreaming ? createOpenAIStreamTracker() : null;
- const aggregator = isStreaming ? null : createOpenAIContentAggregator();
- // Set up response for streaming
- if (isStreaming) {
- res.setHeader('Content-Type', 'text/event-stream');
- res.setHeader('Cache-Control', 'no-cache');
- res.setHeader('Connection', 'keep-alive');
- res.setHeader('X-Accel-Buffering', 'no');
- res.flushHeaders();
-
- // Send initial chunk with role
- const initialChunk = createChunk(context, { role: 'assistant' });
- writeSSE(res, initialChunk);
- }
+ // Determine if streaming is enabled (check both request and agent config)
+ const streamingDisabled = !!primaryConfig.model_parameters?.disableStreaming;
+ const isStreaming = request.stream === true && !streamingDisabled;
- // Create handler config for OpenAI streaming (only used when streaming)
- const handlerConfig = isStreaming
- ? {
- res,
- context,
- tracker,
- }
- : null;
+ // Create tracker for streaming or aggregator for non-streaming
+ const tracker = isStreaming ? createOpenAIStreamTracker() : null;
+ const aggregator = isStreaming ? null : createOpenAIContentAggregator();
+ // Set up response for streaming
+ if (isStreaming) {
+ res.setHeader('Content-Type', 'text/event-stream');
+ res.setHeader('Cache-Control', 'no-cache');
+ res.setHeader('Connection', 'keep-alive');
+ res.setHeader('X-Accel-Buffering', 'no');
+ res.flushHeaders();
+
+ // Send initial chunk with role
+ const initialChunk = createChunk(context, { role: 'assistant' });
+ writeSSE(res, initialChunk);
+ }
- const collectedUsage = [];
- const toolEndCallback = createToolEndCallback({ req, res, artifactPromises, streamId: null });
+ // Create handler config for OpenAI streaming (only used when streaming)
+ const handlerConfig = isStreaming
+ ? {
+ res,
+ context,
+ tracker,
+ }
+ : null;
- /* Stable for the turn: the primary prime list is fixed once
+ const collectedUsage = [];
+ const toolEndCallback = createToolEndCallback({
+ req,
+ res,
+ artifactPromises,
+ streamId: null,
+ });
+
+ /* Stable for the turn: the primary prime list is fixed once
`initializeAgent` resolves and is used as the fallback when a
specific agent context is unavailable. `codeEnvAvailable` is read
per-agent from the stored tool context (admin cap AND that
agent's `tools` list includes `execute_code`) — a skills-only
agent never gains sandbox access even if the admin enabled the
capability globally. */
- const toolExecuteOptions = {
- loadTools: async (toolNames, agentId, _configurable, callerCapabilityProjection) => {
- const ctx = agentToolContexts.get(agentId) ?? agentToolContexts.get(primaryConfig.id) ?? {};
- const result = await loadToolsForExecution({
- req,
- res,
- agentResourceType: ResourceType.REMOTE_AGENT,
- conversationId,
- requestBody: mcpRequestBody,
- toolNames,
- agent: ctx.agent ?? agent,
- signal: execution.signal,
- toolRegistry: ctx.toolRegistry,
- callerCapabilityProjection,
- backgroundToolNames: ctx.backgroundToolNames,
- intentToolNames: ctx.intentToolNames,
- mcpAvailableTools: ctx.mcpAvailableTools,
- requestScopedConnections: ctx.requestScopedConnections,
- userMCPAuthMap: ctx.userMCPAuthMap,
- tool_resources: ctx.tool_resources,
- actionsEnabled: ctx.actionsEnabled,
- accessibleMcpServerNames: ctx.accessibleMcpServerNames,
- });
- return enrichLoadedToolsWithAgentContext({
- result,
- req,
- ctx,
- });
- },
- toolEndCallback,
- ...getSkillToolDeps(),
- };
+ const toolExecuteOptions = {
+ loadTools: async (toolNames, agentId, _configurable, callerCapabilityProjection) => {
+ const ctx =
+ agentToolContexts.get(agentId) ?? agentToolContexts.get(primaryConfig.id) ?? {};
+ const result = await loadToolsForExecution({
+ req,
+ res,
+ agentResourceType: ResourceType.REMOTE_AGENT,
+ conversationId,
+ requestBody: mcpRequestBody,
+ toolNames,
+ agent: ctx.agent ?? agent,
+ signal: execution.signal,
+ toolRegistry: ctx.toolRegistry,
+ callerCapabilityProjection,
+ backgroundToolNames: ctx.backgroundToolNames,
+ intentToolNames: ctx.intentToolNames,
+ mcpAvailableTools: ctx.mcpAvailableTools,
+ requestScopedConnections: ctx.requestScopedConnections,
+ userMCPAuthMap: ctx.userMCPAuthMap,
+ tool_resources: ctx.tool_resources,
+ actionsEnabled: ctx.actionsEnabled,
+ accessibleMcpServerNames: ctx.accessibleMcpServerNames,
+ });
+ return enrichLoadedToolsWithAgentContext({
+ result,
+ req,
+ ctx,
+ });
+ },
+ toolEndCallback,
+ ...getSkillToolDeps(),
+ };
- const summarizationConfig = appConfig?.summarization;
-
- const openaiMessages = convertMessages(request.messages);
-
- const toolSet = buildToolSet(primaryConfig);
- const formatted = formatAgentMessages(stripActivityLabelParts(openaiMessages), {}, toolSet);
- const formattedMessages = formatted.messages;
- const initialSummary = formatted.summary;
- let indexTokenCountMap = formatted.indexTokenCountMap;
-
- /**
- * Inject manual + always-apply skill primes so the model sees SKILL.md
- * bodies for this turn — parity with AgentClient's chat path. OpenAI-
- * compatible streaming uses its own tracker/aggregator shape, so the
- * LibreChat-style card SSE events don't apply here; only the
- * message-context part carries over.
- */
- if (
- (manualSkillPrimes && manualSkillPrimes.length > 0) ||
- (alwaysApplySkillPrimes && alwaysApplySkillPrimes.length > 0)
- ) {
- const primeResult = injectSkillPrimes({
- initialMessages: formattedMessages,
- indexTokenCountMap,
- manualSkillPrimes,
- alwaysApplySkillPrimes,
- });
- indexTokenCountMap = primeResult.indexTokenCountMap;
- /* Surface the cap-driven always-apply truncation at the controller
+ const summarizationConfig = appConfig?.summarization;
+
+ const openaiMessages = convertMessages(request.messages);
+
+ const toolSet = buildToolSet(primaryConfig);
+ const formatted = formatAgentMessages(stripActivityLabelParts(openaiMessages), {}, toolSet);
+ const formattedMessages = formatted.messages;
+ const initialSummary = formatted.summary;
+ let indexTokenCountMap = formatted.indexTokenCountMap;
+
+ /**
+ * Inject manual + always-apply skill primes so the model sees SKILL.md
+ * bodies for this turn — parity with AgentClient's chat path. OpenAI-
+ * compatible streaming uses its own tracker/aggregator shape, so the
+ * LibreChat-style card SSE events don't apply here; only the
+ * message-context part carries over.
+ */
+ if (
+ (manualSkillPrimes && manualSkillPrimes.length > 0) ||
+ (alwaysApplySkillPrimes && alwaysApplySkillPrimes.length > 0)
+ ) {
+ const primeResult = injectSkillPrimes({
+ initialMessages: formattedMessages,
+ indexTokenCountMap,
+ manualSkillPrimes,
+ alwaysApplySkillPrimes,
+ });
+ indexTokenCountMap = primeResult.indexTokenCountMap;
+ /* Surface the cap-driven always-apply truncation at the controller
layer too — `injectSkillPrimes` already logs internally, but the
controller-level warn includes endpoint context so operators can
tell at a glance which path hit the cap. Mirrors AgentClient's
warn in `client.js`. */
- if (primeResult.alwaysApplyDropped > 0) {
- logger.warn(
- `[OpenAI API] Dropped ${primeResult.alwaysApplyDropped} always-apply prime(s) to stay within MAX_PRIMED_SKILLS_PER_TURN.`,
- );
+ if (primeResult.alwaysApplyDropped > 0) {
+ logger.warn(
+ `[OpenAI API] Dropped ${primeResult.alwaysApplyDropped} always-apply prime(s) to stay within MAX_PRIMED_SKILLS_PER_TURN.`,
+ );
+ }
}
- }
- /**
- * Create a simple handler that processes data
- */
- const createHandler = (processor) => ({
- handle: (_event, data) => {
- if (processor) {
- processor(data);
- }
- },
- });
+ /**
+ * Create a simple handler that processes data
+ */
+ const createHandler = (processor) => ({
+ handle: (_event, data) => {
+ if (processor) {
+ processor(data);
+ }
+ },
+ });
- /**
- * Stream text content in OpenAI format
- */
- const streamText = (text) => {
- if (!text) {
- return;
- }
- if (isStreaming) {
- tracker.addText();
- writeSSE(res, createChunk(context, { content: text }));
- } else {
- aggregator.addText(text);
- }
- };
+ /**
+ * Stream text content in OpenAI format
+ */
+ const streamText = (text) => {
+ if (!text) {
+ return;
+ }
+ if (isStreaming) {
+ tracker.addText();
+ writeSSE(res, createChunk(context, { content: text }));
+ } else {
+ aggregator.addText(text);
+ }
+ };
- /**
- * Stream reasoning content in OpenAI format (OpenRouter convention)
- */
- const streamReasoning = (text) => {
- if (!text) {
- return;
- }
- if (isStreaming) {
- tracker.addReasoning();
- writeSSE(res, createChunk(context, { reasoning: text }));
- } else {
- aggregator.addReasoning(text);
- }
- };
+ /**
+ * Stream reasoning content in OpenAI format (OpenRouter convention)
+ */
+ const streamReasoning = (text) => {
+ if (!text) {
+ return;
+ }
+ if (isStreaming) {
+ tracker.addReasoning();
+ writeSSE(res, createChunk(context, { reasoning: text }));
+ } else {
+ aggregator.addReasoning(text);
+ }
+ };
- // Event handlers for OpenAI-compatible streaming
- const handlers = {
- // Text content streaming
- on_message_delta: createHandler((data) => {
- const content = data?.delta?.content;
- if (Array.isArray(content)) {
- for (const part of content) {
- if (part.type === 'text' && part.text) {
- streamText(part.text);
+ // Event handlers for OpenAI-compatible streaming
+ const handlers = {
+ // Text content streaming
+ on_message_delta: createHandler((data) => {
+ const content = data?.delta?.content;
+ if (Array.isArray(content)) {
+ for (const part of content) {
+ if (part.type === 'text' && part.text) {
+ streamText(part.text);
+ }
}
}
- }
- }),
-
- // Reasoning/thinking content streaming
- on_reasoning_delta: createHandler((data) => {
- const content = data?.delta?.content;
- if (Array.isArray(content)) {
- for (const part of content) {
- const text = part.think || part.text;
- if (text) {
- streamReasoning(text);
+ }),
+
+ // Reasoning/thinking content streaming
+ on_reasoning_delta: createHandler((data) => {
+ const content = data?.delta?.content;
+ if (Array.isArray(content)) {
+ for (const part of content) {
+ const text = part.think || part.text;
+ if (text) {
+ streamReasoning(text);
+ }
}
}
- }
- }),
-
- // Tool call initiation - streams id and name (from on_run_step)
- on_run_step: createHandler((data) => {
- const stepDetails = data?.stepDetails;
- if (stepDetails?.type === 'tool_calls' && stepDetails.tool_calls) {
- for (const tc of stepDetails.tool_calls) {
- const toolIndex = data.index ?? 0;
- const toolId = tc.id ?? '';
- const toolName = tc.name ?? '';
- const toolCall = {
- id: toolId,
- type: 'function',
- function: { name: toolName, arguments: '' },
- };
-
- // Track tool call in tracker or aggregator
- if (isStreaming) {
- if (!tracker.toolCalls.has(toolIndex)) {
- tracker.toolCalls.set(toolIndex, toolCall);
- }
- // Stream initial tool call chunk (like OpenAI does)
- writeSSE(
- res,
- createChunk(context, {
- tool_calls: [{ index: toolIndex, ...toolCall }],
- }),
- );
- } else {
- if (!aggregator.toolCalls.has(toolIndex)) {
- aggregator.toolCalls.set(toolIndex, toolCall);
+ }),
+
+ // Tool call initiation - streams id and name (from on_run_step)
+ on_run_step: createHandler((data) => {
+ const stepDetails = data?.stepDetails;
+ if (stepDetails?.type === 'tool_calls' && stepDetails.tool_calls) {
+ for (const tc of stepDetails.tool_calls) {
+ const toolIndex = data.index ?? 0;
+ const toolId = tc.id ?? '';
+ const toolName = tc.name ?? '';
+ const toolCall = {
+ id: toolId,
+ type: 'function',
+ function: { name: toolName, arguments: '' },
+ };
+
+ // Track tool call in tracker or aggregator
+ if (isStreaming) {
+ if (!tracker.toolCalls.has(toolIndex)) {
+ tracker.toolCalls.set(toolIndex, toolCall);
+ }
+ // Stream initial tool call chunk (like OpenAI does)
+ writeSSE(
+ res,
+ createChunk(context, {
+ tool_calls: [{ index: toolIndex, ...toolCall }],
+ }),
+ );
+ } else {
+ if (!aggregator.toolCalls.has(toolIndex)) {
+ aggregator.toolCalls.set(toolIndex, toolCall);
+ }
}
}
}
- }
- }),
-
- // Tool call argument streaming (from on_run_step_delta)
- on_run_step_delta: createHandler((data) => {
- const delta = data?.delta;
- if (delta?.type === 'tool_calls' && delta.tool_calls) {
- for (const tc of delta.tool_calls) {
- const args = tc.args ?? '';
- if (!args) {
- continue;
- }
+ }),
- const toolIndex = tc.index ?? 0;
+ // Tool call argument streaming (from on_run_step_delta)
+ on_run_step_delta: createHandler((data) => {
+ const delta = data?.delta;
+ if (delta?.type === 'tool_calls' && delta.tool_calls) {
+ for (const tc of delta.tool_calls) {
+ const args = tc.args ?? '';
+ if (!args) {
+ continue;
+ }
- // Update tool call arguments
- const targetMap = isStreaming ? tracker.toolCalls : aggregator.toolCalls;
- const tracked = targetMap.get(toolIndex);
- if (tracked) {
- tracked.function.arguments += args;
- }
+ const toolIndex = tc.index ?? 0;
- // Stream argument delta (only for streaming)
- if (isStreaming) {
- writeSSE(
- res,
- createChunk(context, {
- tool_calls: [
- {
- index: toolIndex,
- function: { arguments: args },
- },
- ],
- }),
- );
+ // Update tool call arguments
+ const targetMap = isStreaming ? tracker.toolCalls : aggregator.toolCalls;
+ const tracked = targetMap.get(toolIndex);
+ if (tracked) {
+ tracked.function.arguments += args;
+ }
+
+ // Stream argument delta (only for streaming)
+ if (isStreaming) {
+ writeSSE(
+ res,
+ createChunk(context, {
+ tool_calls: [
+ {
+ index: toolIndex,
+ function: { arguments: args },
+ },
+ ],
+ }),
+ );
+ }
}
}
- }
- }),
-
- // Usage tracking
- on_chat_model_end: {
- handle: (_event, data, metadata, graph) => {
- const usage = data?.output?.usage_metadata;
- if (usage) {
- const agentContext = graph?.getAgentContext?.(metadata);
- const taggedUsage = contextualizeModelUsage(usage, metadata, agentContext);
- collectedUsage.push(taggedUsage);
- }
+ }),
+
+ // Usage tracking
+ on_chat_model_end: {
+ handle: (_event, data, metadata, graph) => {
+ const usage = data?.output?.usage_metadata;
+ if (usage) {
+ const agentContext = graph?.getAgentContext?.(metadata);
+ const taggedUsage = contextualizeModelUsage(usage, metadata, agentContext);
+ collectedUsage.push(taggedUsage);
+ }
+ },
},
- },
- on_run_step_completed: createHandler(),
- // Use proper ToolEndHandler for processing artifacts (images, file citations, code output)
- on_tool_end: new ToolEndHandler(toolEndCallback, logger),
- on_chain_stream: createHandler(),
- on_chain_end: createHandler(),
- on_agent_update: createHandler(),
- on_agent_log: agentLogHandlerObj,
- on_custom_event: createHandler(),
- on_tool_execute: createToolExecuteHandler(toolExecuteOptions),
- ...(summarizationConfig?.enabled !== false
- ? buildSummarizationHandlers({ isStreaming, res })
- : {}),
- };
+ on_run_step_completed: createHandler(),
+ // Use proper ToolEndHandler for processing artifacts (images, file citations, code output)
+ on_tool_end: new ToolEndHandler(toolEndCallback, logger),
+ on_chain_stream: createHandler(),
+ on_chain_end: createHandler(),
+ on_agent_update: createHandler(),
+ on_agent_log: agentLogHandlerObj,
+ on_custom_event: createHandler(),
+ on_tool_execute: createToolExecuteHandler(toolExecuteOptions),
+ ...(summarizationConfig?.enabled !== false
+ ? buildSummarizationHandlers({ isStreaming, res })
+ : {}),
+ };
- // Create and run the agent
- const userId = principal.userId;
+ // Create and run the agent
+ const userId = principal.userId;
- // Extract merged userMCPAuthMap (needed for MCP tool connections across
- // the primary and any discovered handoff sub-agents)
- const userMCPAuthMap = discoveredMCPAuthMap ?? primaryConfig.userMCPAuthMap;
+ // Extract merged userMCPAuthMap (needed for MCP tool connections across
+ // the primary and any discovered handoff sub-agents)
+ const userMCPAuthMap = discoveredMCPAuthMap ?? primaryConfig.userMCPAuthMap;
- const contextAgentsById = new Map(runAgents.map((runAgent) => [runAgent.id, runAgent]));
- for (const runAgent of runAgents) {
- for (const graph of runAgent.subagentGraphConfigs ?? []) {
- for (const memberConfig of graph.memberConfigs) {
- contextAgentsById.set(memberConfig.id, memberConfig);
+ const contextAgentsById = new Map(runAgents.map((runAgent) => [runAgent.id, runAgent]));
+ for (const runAgent of runAgents) {
+ for (const graph of runAgent.subagentGraphConfigs ?? []) {
+ for (const memberConfig of graph.memberConfigs) {
+ contextAgentsById.set(memberConfig.id, memberConfig);
+ }
}
}
- }
- const contextAgents = [...contextAgentsById.values()];
- const agentScopedContext = await buildAgentScopedContext({
- agentIds: contextAgents.map(({ id }) => id),
- attachmentsByAgentId: buildAgentContextAttachmentsByAgentId(contextAgents),
- req,
- });
- const mcpManager = getMCPManager();
- const configServers = await resolveConfigServers(req);
- await Promise.all(
- contextAgents.map(async (runAgent) => {
- const memoryContext = await buildInlineMemoryContext({
- agent: runAgent,
- req,
- userId,
- memoryAvailable,
- getFormattedMemories: db.getFormattedMemories,
- });
- return applyContextToAgent({
- agent: runAgent,
- agentId: runAgent.id,
- logger,
- mcpManager,
- configServers,
- sharedRunContext: [memoryContext, agentScopedContext.get(runAgent.id)]
- .filter(Boolean)
- .join('\n\n'),
- });
- }),
- );
- const initialSessions = buildInitialToolSessions({ agents: runAgents });
-
- const run = await createRun({
- agents: runAgents,
- messages: formattedMessages,
- indexTokenCountMap,
- initialSessions,
- initialSummary,
- runId: responseId,
- summarizationConfig,
- appConfig,
- signal: execution.signal,
- customHandlers: handlers,
- requestBody: mcpRequestBody,
- user: { id: userId },
- tenantId: principal.tenantId,
- /** Bills subagent child-run model calls (reported outside the
- * streamEvents loop) into the same collectedUsage array. */
- subagentUsageSink: createSubagentUsageSink(collectedUsage),
- });
-
- if (!run) {
- throw new Error('Failed to create agent run');
- }
+ const contextAgents = [...contextAgentsById.values()];
+ const agentScopedContext = await buildAgentScopedContext({
+ agentIds: contextAgents.map(({ id }) => id),
+ attachmentsByAgentId: buildAgentContextAttachmentsByAgentId(contextAgents),
+ req,
+ });
+ const mcpManager = getMCPManager();
+ const configServers = await resolveConfigServers(req);
+ await Promise.all(
+ contextAgents.map(async (runAgent) => {
+ const memoryContext = await buildInlineMemoryContext({
+ agent: runAgent,
+ req,
+ userId,
+ memoryAvailable,
+ getFormattedMemories: db.getFormattedMemories,
+ });
+ return applyContextToAgent({
+ agent: runAgent,
+ agentId: runAgent.id,
+ logger,
+ mcpManager,
+ configServers,
+ sharedRunContext: [memoryContext, agentScopedContext.get(runAgent.id)]
+ .filter(Boolean)
+ .join('\n\n'),
+ });
+ }),
+ );
+ const initialSessions = buildInitialToolSessions({ agents: runAgents });
- const config = {
- runName: 'AgentRun',
- configurable: {
- thread_id: conversationId,
- user_id: userId,
- user: createSafeUser(req.user),
+ const run = await createRun({
+ agents: runAgents,
+ messages: formattedMessages,
+ indexTokenCountMap,
+ initialSessions,
+ initialSummary,
+ runId: responseId,
+ summarizationConfig,
+ appConfig,
+ signal: execution.signal,
+ customHandlers: handlers,
requestBody: mcpRequestBody,
- ...(userMCPAuthMap != null && { userMCPAuthMap }),
- },
- recursionLimit: resolveRecursionLimit(agentsEConfig, agent),
- signal: execution.signal,
- streamMode: 'values',
- version: 'v2',
- };
+ user: { id: userId },
+ tenantId: principal.tenantId,
+ /** Bills subagent child-run model calls (reported outside the
+ * streamEvents loop) into the same collectedUsage array. */
+ subagentUsageSink: createSubagentUsageSink(collectedUsage),
+ });
- await run.processStream({ messages: formattedMessages }, config, {
- callbacks: {
- [Callback.TOOL_ERROR]: (graph, error, toolId) => {
- logger.error(`[OpenAI API] Tool Error "${toolId}"`, getSafeErrorMetadata(error));
- },
- },
- });
+ if (!run) {
+ throw new Error('Failed to create agent run');
+ }
- // Record token usage against balance
- const balanceConfig = getBalanceConfig(appConfig);
- const transactionsConfig = getTransactionsConfig(appConfig);
- execution.track(
- recordCollectedUsage(
- {
- spendTokens: db.spendTokens,
- spendStructuredTokens: db.spendStructuredTokens,
- pricing: { getMultiplier: db.getMultiplier, getCacheMultiplier: db.getCacheMultiplier },
- bulkWriteOps: { insertMany: db.bulkInsertTransactions, updateBalance: db.updateBalance },
+ const config = {
+ runName: 'AgentRun',
+ configurable: {
+ thread_id: conversationId,
+ user_id: userId,
+ user: createSafeUser(req.user),
+ requestBody: mcpRequestBody,
+ ...(userMCPAuthMap != null && { userMCPAuthMap }),
},
- {
- user: userId,
- conversationId,
- collectedUsage,
- context: 'message',
- messageId: responseId,
- balance: balanceConfig,
- transactions: transactionsConfig,
- model: primaryConfig.model || agent.model_parameters?.model,
- endpointTokenConfig: primaryConfig.endpointTokenConfig,
- resolveEndpointTokenConfig,
+ recursionLimit: resolveRecursionLimit(agentsEConfig, agent),
+ signal: execution.signal,
+ streamMode: 'values',
+ version: 'v2',
+ };
+
+ await run.processStream({ messages: formattedMessages }, config, {
+ callbacks: {
+ [Callback.TOOL_ERROR]: (graph, error, toolId) => {
+ logger.error(`[OpenAI API] Tool Error "${toolId}"`, getSafeErrorMetadata(error));
+ },
},
- ).catch((err) => {
- logger.error('[OpenAI API] Error recording usage:', getSafeErrorMetadata(err));
- }),
- );
+ });
- const usage = buildCompletionUsage(collectedUsage);
+ // Record token usage against balance
+ const balanceConfig = getBalanceConfig(appConfig);
+ const transactionsConfig = getTransactionsConfig(appConfig);
+ execution.track(
+ recordCollectedUsage(
+ {
+ spendTokens: db.spendTokens,
+ spendStructuredTokens: db.spendStructuredTokens,
+ pricing: {
+ getMultiplier: db.getMultiplier,
+ getCacheMultiplier: db.getCacheMultiplier,
+ },
+ bulkWriteOps: {
+ insertMany: db.bulkInsertTransactions,
+ updateBalance: db.updateBalance,
+ },
+ },
+ {
+ user: userId,
+ conversationId,
+ collectedUsage,
+ context: 'message',
+ messageId: responseId,
+ balance: balanceConfig,
+ transactions: transactionsConfig,
+ model: primaryConfig.model || agent.model_parameters?.model,
+ endpointTokenConfig: primaryConfig.endpointTokenConfig,
+ resolveEndpointTokenConfig,
+ },
+ ).catch((err) => {
+ logger.error('[OpenAI API] Error recording usage:', getSafeErrorMetadata(err));
+ }),
+ );
- // Finalize response
- const duration = Date.now() - requestStartTime;
- if (isStreaming) {
- sendFinalChunk(handlerConfig, 'stop', usage);
- res.end();
- logger.debug(`[OpenAI API] Response ${responseId} completed in ${duration}ms (streaming)`);
+ const usage = buildCompletionUsage(collectedUsage);
- // The HTTP response is complete, while destructive cleanup still waits for artifacts.
- if (artifactPromises.length > 0) {
- execution.track(
- waitForAgentExecutionWrites(artifactPromises).catch((artifactError) => {
+ // Finalize response
+ const duration = Date.now() - requestStartTime;
+ if (isStreaming) {
+ sendFinalChunk(handlerConfig, 'stop', usage);
+ res.end();
+ logger.debug(`[OpenAI API] Response ${responseId} completed in ${duration}ms (streaming)`);
+
+ // The HTTP response is complete, while destructive cleanup still waits for artifacts.
+ if (artifactPromises.length > 0) {
+ execution.track(
+ waitForAgentExecutionWrites(artifactPromises).catch((artifactError) => {
+ logger.warn(
+ '[OpenAI API] Error processing artifacts:',
+ getSafeErrorMetadata(artifactError),
+ );
+ }),
+ );
+ artifactWritesCovered = true;
+ }
+ } else {
+ // For non-streaming, wait for artifacts before sending response
+ if (artifactPromises.length > 0) {
+ try {
+ await waitForAgentExecutionWrites(artifactPromises);
+ } catch (artifactError) {
logger.warn(
'[OpenAI API] Error processing artifacts:',
getSafeErrorMetadata(artifactError),
);
- }),
- );
- artifactWritesCovered = true;
- }
- } else {
- // For non-streaming, wait for artifacts before sending response
- if (artifactPromises.length > 0) {
- try {
- await waitForAgentExecutionWrites(artifactPromises);
- } catch (artifactError) {
- logger.warn(
- '[OpenAI API] Error processing artifacts:',
- getSafeErrorMetadata(artifactError),
- );
+ }
+ artifactWritesCovered = true;
}
- artifactWritesCovered = true;
- }
- const response = buildNonStreamingResponse(
- context,
- aggregator.getText(),
- aggregator.getReasoning(),
- aggregator.toolCalls,
- usage,
- );
- res.json(response);
- logger.debug(
- `[OpenAI API] Response ${responseId} completed in ${duration}ms (non-streaming)`,
- );
- }
- } catch (error) {
- executionError = error;
- logger.error('[OpenAI API] Error:', getSafeErrorMetadata(error));
- const protectionEnabled = hasModelBoundContentProtection(
- appConfig?.filters,
- appConfig?.messageFilter?.pii,
- );
- const errorMessage = getUserFacingProviderError(error, protectionEnabled);
-
- // Check if we already started streaming (headers sent)
- if (res.headersSent) {
- // Headers already sent, send error in stream
- const errorChunk = createChunk(context, { content: `\n\nError: ${errorMessage}` }, 'stop');
- writeSSE(res, errorChunk);
- writeSSE(res, '[DONE]');
- res.end();
- } else {
- if (isContentFilterError(error)) {
- return sendErrorResponse(
- res,
- error.statusCode,
- error.body.message,
- 'invalid_request_error',
- error.body.error,
+ const response = buildNonStreamingResponse(
+ context,
+ aggregator.getText(),
+ aggregator.getReasoning(),
+ aggregator.toolCalls,
+ usage,
);
- }
- // Forward upstream provider status codes (e.g., Anthropic 400s) instead of masking as 500
- const statusCode =
- typeof error?.status === 'number' && error.status >= 400 && error.status < 600
- ? error.status
- : 500;
- const errorType =
- statusCode >= 400 && statusCode < 500 ? 'invalid_request_error' : 'server_error';
- const errorCode = !protectionEnabled && typeof error?.code === 'string' ? error.code : null;
- sendErrorResponse(res, statusCode, errorMessage, errorType, errorCode);
- }
- } finally {
- res.off('close', abortOnResponseClose);
- if (execution) {
- if (!artifactWritesCovered && artifactPromises.length > 0) {
- execution.track(
- waitForAgentExecutionWrites(artifactPromises).catch((artifactError) => {
- logger.warn(
- '[OpenAI API] Error processing artifacts:',
- getSafeErrorMetadata(artifactError),
- );
- }),
+ res.json(response);
+ logger.debug(
+ `[OpenAI API] Response ${responseId} completed in ${duration}ms (non-streaming)`,
);
}
- await execution.settle(executionError).catch((error) => {
- logger.error('[OpenAI API] Failed to settle execution:', getSafeErrorMetadata(error));
- });
- }
- }
+ },
+ });
};
/**
diff --git a/api/server/controllers/agents/responses.js b/api/server/controllers/agents/responses.js
index e664b65d9b..481abaf8c2 100644
--- a/api/server/controllers/agents/responses.js
+++ b/api/server/controllers/agents/responses.js
@@ -16,6 +16,7 @@ const {
buildToolSet,
AgentRunEnvelopeError,
createAgentRunEnvelope,
+ createAgentExecutionContext,
createMCPRuntimeRequestBody,
buildAgentScopedContext,
buildInlineMemoryContext,
@@ -74,7 +75,7 @@ const {
getLangfuseTraceMessageFields,
stripActivityLabelParts,
CHILD_THREAD_READ_ONLY_ERROR,
- enrollAgentExecution,
+ executeAgentRun,
waitForAgentExecutionWrites,
} = require('@librechat/api');
const {
@@ -121,16 +122,52 @@ function getUserFacingProviderError(error, protectionEnabled) {
return error instanceof Error ? error.message : 'An error occurred';
}
+function handleExecutionError({ error, res, appConfig }) {
+ logger.error('[Responses API] Error:', getSafeErrorMetadata(error));
+ const protectionEnabled = hasModelBoundContentProtection(
+ appConfig?.filters,
+ appConfig?.messageFilter?.pii,
+ );
+ const errorMessage = getUserFacingProviderError(error, protectionEnabled);
+
+ if (res.headersSent) {
+ writeDone(res);
+ res.end();
+ return;
+ }
+ if (isContentFilterError(error)) {
+ return sendResponsesErrorResponse(
+ res,
+ error.statusCode,
+ error.body.message,
+ 'invalid_request',
+ error.body.error,
+ );
+ }
+ const statusCode =
+ typeof error?.status === 'number' && error.status >= 400 && error.status < 600
+ ? error.status
+ : 500;
+ const errorType = statusCode >= 400 && statusCode < 500 ? 'invalid_request' : 'server_error';
+ const errorCode = !protectionEnabled && typeof error?.code === 'string' ? error.code : undefined;
+ if (errorCode === undefined) {
+ sendResponsesErrorResponse(res, statusCode, errorMessage, errorType);
+ } else {
+ sendResponsesErrorResponse(res, statusCode, errorMessage, errorType, errorCode);
+ }
+}
+
/**
* Creates a tool loader function for the agent.
- * @param {AbortSignal} signal - The abort signal
- * @param {boolean} [definitionsOnly=true] - When true, returns only serializable
+ * @param {Object} runtime - Request-backed tool adapter state
+ * @param {import('express').Request} runtime.req
+ * @param {import('express').Response} runtime.res
+ * @param {AbortSignal} runtime.signal - The abort signal
+ * @param {boolean} [runtime.definitionsOnly=true] - When true, returns only serializable
* tool definitions without creating full tool instances (for event-driven mode)
*/
-function createToolLoader(signal, definitionsOnly = true) {
+function createToolLoader({ req, res, signal, definitionsOnly = true }) {
return async function loadTools({
- req,
- res,
tools,
model,
agentId,
@@ -471,9 +508,17 @@ const executeResponse = async (envelope, { req, res }) => {
const requestStartTime = envelope.receivedAt;
const request = envelope.payload;
const { principal } = envelope;
- // The local executor keeps the current Express-dependent initialization path,
- // but all request-body reads now observe the detached envelope payload.
+ // Request-backed tool adapters still observe the validated envelope payload;
+ // shared initialization receives the transport-free runtime below.
req.body = request;
+ const agentRuntime = createAgentExecutionContext({
+ user: req.user,
+ appConfig,
+ requestBody: request,
+ conversationCreatedAt: req.conversationCreatedAt,
+ resolvedConversation: req.resolvedConversation,
+ hasResolvedConversation: Object.prototype.hasOwnProperty.call(req, 'resolvedConversation'),
+ });
const agentId = request.model;
const manualSkills = extractManualSkills(req.body);
const isStreaming = request.stream === true;
@@ -576,925 +621,893 @@ const executeResponse = async (envelope, { req, res }) => {
);
const conversationId = request.previous_response_id ?? uuidv4();
- let execution;
- let executionError;
- let responseClosed = res.destroyed === true && res.writableEnded !== true;
/** @type {Promise<import('librechat-data-provider').TAttachment | null>[]} */
const artifactPromises = [];
let artifactWritesCovered = false;
- const abortOnResponseClose = () => {
- if (res.writableEnded === true) {
- return;
- }
- responseClosed = true;
- if (execution && !execution.signal.aborted) {
- execution.abort();
- logger.debug('[Responses API] Client disconnected, aborting');
- }
- };
- res.once('close', abortOnResponseClose);
- try {
- execution = await enrollAgentExecution({
- runId: responseId,
- userId: principal.userId,
- conversationId,
- agentId,
- protocol: 'responses',
- /** Conversation delete-all uses the shared owner-admission fence. Remote
- * execution must observe it after durable enrollment and before provider work. */
- isPrincipalActive: db.isSubagentOwnerAdmissible,
- });
- if (responseClosed || (res.destroyed === true && res.writableEnded !== true)) {
- execution.abort();
- }
- await execution.beginProviderExecution();
-
- if (request.previous_response_id != null) {
- if (typeof request.previous_response_id !== 'string') {
- return sendResponsesErrorResponse(
- res,
- 400,
- 'previous_response_id must be a string',
- 'invalid_request',
+ return executeAgentRun({
+ envelope,
+ runId: responseId,
+ conversationId,
+ connection: {
+ isClosed: () => res.destroyed === true && res.writableEnded !== true,
+ onClose: (listener) => {
+ const abortOnResponseClose = () => {
+ if (res.writableEnded !== true) {
+ logger.debug('[Responses API] Client disconnected, aborting');
+ listener();
+ }
+ };
+ res.once('close', abortOnResponseClose);
+ return () => res.off('close', abortOnResponseClose);
+ },
+ },
+ /** Conversation delete-all uses the shared owner-admission fence. Remote
+ * execution must observe it after durable enrollment and before provider work. */
+ isPrincipalActive: db.isSubagentOwnerAdmissible,
+ beforeSettle: (execution) => {
+ if (!artifactWritesCovered && artifactPromises.length > 0) {
+ execution.track(
+ waitForAgentExecutionWrites(artifactPromises).catch((artifactError) => {
+ logger.warn(
+ '[Responses API] Error processing artifacts:',
+ getSafeErrorMetadata(artifactError),
+ );
+ }),
);
}
- const previousConversation = await db.getConvo(
- principal.userId,
- request.previous_response_id,
- );
- if (!previousConversation) {
- return sendResponsesErrorResponse(res, 404, 'Conversation not found', 'not_found');
- }
- if (previousConversation.subagentThread != null) {
- return sendResponsesErrorResponse(
- res,
- 409,
- CHILD_THREAD_READ_ONLY_ERROR,
- 'invalid_request',
- 'conversation_read_only',
+ },
+ onSettlementError: (error) => {
+ logger.error('[Responses API] Failed to settle execution:', getSafeErrorMetadata(error));
+ },
+ handleExecutionError: (error) => handleExecutionError({ error, res, appConfig }),
+ execute: async (execution) => {
+ if (request.previous_response_id != null) {
+ if (typeof request.previous_response_id !== 'string') {
+ return sendResponsesErrorResponse(
+ res,
+ 400,
+ 'previous_response_id must be a string',
+ 'invalid_request',
+ );
+ }
+ const previousConversation = await db.getConvo(
+ principal.userId,
+ request.previous_response_id,
);
+ if (!previousConversation) {
+ return sendResponsesErrorResponse(res, 404, 'Conversation not found', 'not_found');
+ }
+ if (previousConversation.subagentThread != null) {
+ return sendResponsesErrorResponse(
+ res,
+ 409,
+ CHILD_THREAD_READ_ONLY_ERROR,
+ 'invalid_request',
+ 'conversation_read_only',
+ );
+ }
}
- }
- const parentMessageId = null;
- const mcpRequestBody = createMCPRuntimeRequestBody({ messageId: responseId, conversationId });
- const agentsEConfig = appConfig?.endpoints?.[EModelEndpoint.agents];
- const previousMessages = request.previous_response_id
- ? await loadPreviousMessages(request.previous_response_id, principal.userId)
- : [];
- if (request.previous_response_id) {
- assertModelBoundContent({
- filters: appConfig?.filters,
- legacyPii: appConfig?.messageFilter?.pii,
- storedMessages: previousMessages,
+ const parentMessageId = null;
+ const mcpRequestBody = createMCPRuntimeRequestBody({
+ messageId: responseId,
+ conversationId,
});
- }
+ const agentsEConfig = appConfig?.endpoints?.[EModelEndpoint.agents];
+ const previousMessages = request.previous_response_id
+ ? await loadPreviousMessages(request.previous_response_id, principal.userId)
+ : [];
+ if (request.previous_response_id) {
+ assertModelBoundContent({
+ filters: appConfig?.filters,
+ legacyPii: appConfig?.messageFilter?.pii,
+ storedMessages: previousMessages,
+ });
+ }
- // Build allowed providers set
- const allowedProviders = new Set(agentsEConfig?.allowedProviders);
+ // Build allowed providers set
+ const allowedProviders = new Set(agentsEConfig?.allowedProviders);
- // Create tool loader
- const loadTools = createToolLoader(execution.signal);
- const skillDbMethods = getSkillDbMethods();
+ // Create tool loader
+ const loadTools = createToolLoader({ req, res, signal: execution.signal });
+ const skillDbMethods = getSkillDbMethods();
- // Initialize the agent first to check for disableStreaming
- const endpointOption = {
- endpoint: agent.provider,
- model_parameters: agent.model_parameters ?? {},
- };
+ // Initialize the agent first to check for disableStreaming
+ const endpointOption = {
+ endpoint: agent.provider,
+ model_parameters: agent.model_parameters ?? {},
+ };
- const dbMethods = {
- getConvoFiles: db.getConvoFiles,
- getFiles: db.getFiles,
- filterFilesByAgentAccess: filterFilesByRemoteAgentAccess,
- getUserKey: db.getUserKey,
- getMessages: db.getMessages,
- getAccessibleMcpServerNames,
- updateFilesUsage: db.updateFilesUsage,
- getUserKeyValues: db.getUserKeyValues,
- getUserCodeFiles: db.getUserCodeFiles,
- getToolFilesByIds: db.getToolFilesByIds,
- getCodeGeneratedFiles: db.getCodeGeneratedFiles,
- listSkillsByAccess: skillDbMethods.listSkillsByAccess,
- listAlwaysApplySkills: skillDbMethods.listAlwaysApplySkills,
- getSkillByName: skillDbMethods.getSkillByName,
- };
+ const dbMethods = {
+ getConvoFiles: db.getConvoFiles,
+ getFiles: db.getFiles,
+ filterFilesByAgentAccess: filterFilesByRemoteAgentAccess,
+ getUserKey: db.getUserKey,
+ getMessages: db.getMessages,
+ getAccessibleMcpServerNames,
+ updateFilesUsage: db.updateFilesUsage,
+ getUserKeyValues: db.getUserKeyValues,
+ getUserCodeFiles: db.getUserCodeFiles,
+ getToolFilesByIds: db.getToolFilesByIds,
+ getCodeGeneratedFiles: db.getCodeGeneratedFiles,
+ listSkillsByAccess: skillDbMethods.listSkillsByAccess,
+ listAlwaysApplySkills: skillDbMethods.listAlwaysApplySkills,
+ getSkillByName: skillDbMethods.getSkillByName,
+ };
- const enabledCapabilities = new Set(agentsEConfig?.capabilities);
- const memoryAvailable = await resolveMemoryAvailability({
- enabledCapabilities,
- memoryConfig: appConfig?.memory,
- user: req.user,
- getRoleByName: db.getRoleByName,
- });
- const skillsCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.skills);
- const ephemeralSkillsToggle = request.ephemeralAgent?.skills === true;
- const accessibleSkillIds = skillsCapabilityEnabled
- ? withDeploymentSkillIds(
- await findAccessibleResources({
+ const enabledCapabilities = new Set(agentsEConfig?.capabilities);
+ const memoryAvailable = await resolveMemoryAvailability({
+ enabledCapabilities,
+ memoryConfig: appConfig?.memory,
+ user: req.user,
+ getRoleByName: db.getRoleByName,
+ });
+ const skillsCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.skills);
+ const ephemeralSkillsToggle = request.ephemeralAgent?.skills === true;
+ const accessibleSkillIds = skillsCapabilityEnabled
+ ? withDeploymentSkillIds(
+ await findAccessibleResources({
+ userId: principal.userId,
+ role: principal.role,
+ resourceType: ResourceType.SKILL,
+ requiredPermissions: PermissionBits.VIEW,
+ }),
+ )
+ : [];
+ const editableSkillIds = skillsCapabilityEnabled
+ ? await findAccessibleResources({
userId: principal.userId,
role: principal.role,
resourceType: ResourceType.SKILL,
- requiredPermissions: PermissionBits.VIEW,
- }),
- )
- : [];
- const editableSkillIds = skillsCapabilityEnabled
- ? await findAccessibleResources({
- userId: principal.userId,
- role: principal.role,
- resourceType: ResourceType.SKILL,
- requiredPermissions: PermissionBits.EDIT,
- })
- : [];
- const skillCreateAllowed = skillsCapabilityEnabled
- ? await getSkillToolDeps().canCreateSkill({ req })
- : false;
-
- const { skillStates, defaultActiveOnShare } = await loadSkillStates({
- userId: principal.userId,
- appConfig,
- getUserById: db.getUserById,
- accessibleSkillIds,
- });
-
- const primaryScopedSkillIds = resolveAgentScopedSkillIds({
- agent,
- accessibleSkillIds,
- skillsCapabilityEnabled,
- ephemeralSkillsToggle,
- });
- const primaryScopedEditableSkillIds = resolveAgentScopedSkillIds({
- agent,
- accessibleSkillIds: editableSkillIds,
- skillsCapabilityEnabled,
- ephemeralSkillsToggle,
- });
+ requiredPermissions: PermissionBits.EDIT,
+ })
+ : [];
+ const skillCreateAllowed = skillsCapabilityEnabled
+ ? await getSkillToolDeps().canCreateSkill({ req })
+ : false;
+
+ const { skillStates, defaultActiveOnShare } = await loadSkillStates({
+ userId: principal.userId,
+ appConfig,
+ getUserById: db.getUserById,
+ accessibleSkillIds,
+ });
- const primaryConfig = await initializeAgent(
- {
- req,
- res,
- loadTools,
- requestFiles: [],
- conversationId,
- parentMessageId,
- requestBody: mcpRequestBody,
+ const primaryScopedSkillIds = resolveAgentScopedSkillIds({
agent,
- endpointOption,
- allowedProviders,
- isInitialAgent: true,
- accessibleSkillIds: primaryScopedSkillIds,
- skillAuthoringAvailable: canAuthorSkillFiles({
- agent,
- scopedEditableSkillIds: primaryScopedEditableSkillIds,
- skillCreateAllowed,
- skillsCapabilityEnabled,
- ephemeralSkillsToggle,
- }),
- codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
- backgroundToolsAvailable: enabledCapabilities.has(AgentCapabilities.run_in_background),
- toolIntentsAvailable: enabledCapabilities.has(AgentCapabilities.tool_intents),
- statefulSessionsAvailable: enabledCapabilities.has(
- AgentCapabilities.stateful_code_sessions,
- ),
- allowedStatefulCodeEnvironments: agentsEConfig?.statefulCodeSessions?.allowedEnvironments,
- memoryAvailable,
- skillStates,
- defaultActiveOnShare,
- manualSkills,
- },
- dbMethods,
- );
-
- /**
- * Per-agent tool-execution context map, keyed by agentId. Ensures the
- * ON_TOOL_EXECUTE callback routes each sub-agent's tool calls to the
- * correct toolRegistry / userMCPAuthMap / tool_resources.
- * @type {Map<string, {
- * agent: object,
- * toolRegistry?: import('@librechat/agents').LCToolRegistry,
- * requestScopedConnections?: import('@librechat/api').RequestScopedMCPConnectionStore,
- * userMCPAuthMap?: Record<string, Record<string, string>>,
- * tool_resources?: object,
- * actionsEnabled?: boolean,
- * }>}
- */
- const agentToolContexts = new Map();
- agentToolContexts.set(
- primaryConfig.id,
- buildAgentToolContext({ agent, config: primaryConfig }),
- );
+ accessibleSkillIds,
+ skillsCapabilityEnabled,
+ ephemeralSkillsToggle,
+ });
+ const primaryScopedEditableSkillIds = resolveAgentScopedSkillIds({
+ agent,
+ accessibleSkillIds: editableSkillIds,
+ skillsCapabilityEnabled,
+ ephemeralSkillsToggle,
+ });
- let handoffAgentConfigs = new Map();
- let discoveredEdges = [];
- let discoveredMCPAuthMap;
- const subagentsCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.subagents);
- const primaryHasGraphSubagents =
- subagentsCapabilityEnabled &&
- primaryConfig.subagents?.enabled === true &&
- (primaryConfig.subagents.graphs?.length ?? 0) > 0;
- if (primaryConfig.edges?.length || primaryHasGraphSubagents) {
- const modelsConfig = await getModelsConfig(req);
- const discoveryParams = {
- req,
- res,
- primaryConfig,
- endpointOption,
- allowedProviders,
- modelsConfig,
- loadTools,
- requestFiles: [],
- conversationId,
- parentMessageId,
- requestBody: mcpRequestBody,
- resourceType: ResourceType.REMOTE_AGENT,
- computeAccessibleSkillIds: (handoffAgent) =>
- resolveAgentScopedSkillIds({
- agent: handoffAgent,
- accessibleSkillIds,
+ const primaryConfig = await initializeAgent(
+ {
+ runtime: agentRuntime,
+ loadTools,
+ requestFiles: [],
+ conversationId,
+ parentMessageId,
+ requestBody: mcpRequestBody,
+ agent,
+ endpointOption,
+ allowedProviders,
+ isInitialAgent: true,
+ accessibleSkillIds: primaryScopedSkillIds,
+ skillAuthoringAvailable: canAuthorSkillFiles({
+ agent,
+ scopedEditableSkillIds: primaryScopedEditableSkillIds,
+ skillCreateAllowed,
skillsCapabilityEnabled,
ephemeralSkillsToggle,
}),
- computeSkillAuthoringAvailable: (handoffAgent) =>
- canAuthorSkillFiles({
- agent: handoffAgent,
- scopedEditableSkillIds: resolveAgentScopedSkillIds({
+ codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
+ backgroundToolsAvailable: enabledCapabilities.has(AgentCapabilities.run_in_background),
+ toolIntentsAvailable: enabledCapabilities.has(AgentCapabilities.tool_intents),
+ statefulSessionsAvailable: enabledCapabilities.has(
+ AgentCapabilities.stateful_code_sessions,
+ ),
+ allowedStatefulCodeEnvironments: agentsEConfig?.statefulCodeSessions?.allowedEnvironments,
+ memoryAvailable,
+ skillStates,
+ defaultActiveOnShare,
+ manualSkills,
+ },
+ dbMethods,
+ );
+
+ /**
+ * Per-agent tool-execution context map, keyed by agentId. Ensures the
+ * ON_TOOL_EXECUTE callback routes each sub-agent's tool calls to the
+ * correct toolRegistry / userMCPAuthMap / tool_resources.
+ * @type {Map<string, {
+ * agent: object,
+ * toolRegistry?: import('@librechat/agents').LCToolRegistry,
+ * requestScopedConnections?: import('@librechat/api').RequestScopedMCPConnectionStore,
+ * userMCPAuthMap?: Record<string, Record<string, string>>,
+ * tool_resources?: object,
+ * actionsEnabled?: boolean,
+ * }>}
+ */
+ const agentToolContexts = new Map();
+ agentToolContexts.set(
+ primaryConfig.id,
+ buildAgentToolContext({ agent, config: primaryConfig }),
+ );
+
+ let handoffAgentConfigs = new Map();
+ let discoveredEdges = [];
+ let discoveredMCPAuthMap;
+ const subagentsCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.subagents);
+ const primaryHasGraphSubagents =
+ subagentsCapabilityEnabled &&
+ primaryConfig.subagents?.enabled === true &&
+ (primaryConfig.subagents.graphs?.length ?? 0) > 0;
+ if (primaryConfig.edges?.length || primaryHasGraphSubagents) {
+ const modelsConfig = await getModelsConfig(req);
+ const discoveryParams = {
+ req,
+ res,
+ primaryConfig,
+ endpointOption,
+ allowedProviders,
+ modelsConfig,
+ loadTools,
+ requestFiles: [],
+ conversationId,
+ parentMessageId,
+ requestBody: mcpRequestBody,
+ resourceType: ResourceType.REMOTE_AGENT,
+ computeAccessibleSkillIds: (handoffAgent) =>
+ resolveAgentScopedSkillIds({
agent: handoffAgent,
- accessibleSkillIds: editableSkillIds,
+ accessibleSkillIds,
skillsCapabilityEnabled,
ephemeralSkillsToggle,
}),
- skillCreateAllowed,
- skillsCapabilityEnabled,
- ephemeralSkillsToggle,
- }),
- skillStates,
- defaultActiveOnShare,
- codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
- backgroundToolsAvailable: enabledCapabilities.has(AgentCapabilities.run_in_background),
- toolIntentsAvailable: enabledCapabilities.has(AgentCapabilities.tool_intents),
- statefulSessionsAvailable: enabledCapabilities.has(
- AgentCapabilities.stateful_code_sessions,
- ),
- allowedStatefulCodeEnvironments: agentsEConfig?.statefulCodeSessions?.allowedEnvironments,
- memoryAvailable,
- };
- const discoveryDeps = {
- getAgent: db.getAgent,
- checkPermission: async ({ userId, role, resourceId, requiredPermission }) => {
- const permissions = await getRemoteAgentPermissions(
- { getEffectivePermissions },
- userId,
- role,
- resourceId,
- );
- return hasPermissions(permissions, requiredPermission);
- },
- logViolation,
- db: dbMethods,
- onAgentInitialized: (loadedAgentId, loadedAgent, config) => {
- agentToolContexts.set(
- loadedAgentId,
- buildAgentToolContext({ agent: loadedAgent, config }),
- );
- },
- initializeAgent,
- };
- if (primaryConfig.edges?.length) {
- ({
- agentConfigs: handoffAgentConfigs,
- edges: discoveredEdges,
- userMCPAuthMap: discoveredMCPAuthMap,
- } = await discoverConnectedAgents(discoveryParams, discoveryDeps));
- }
- if (subagentsCapabilityEnabled) {
- discoveredMCPAuthMap = await resolveSubagentGraphs(
- {
- ...discoveryParams,
- rootConfigs: [primaryConfig, ...handoffAgentConfigs.values()],
+ computeSkillAuthoringAvailable: (handoffAgent) =>
+ canAuthorSkillFiles({
+ agent: handoffAgent,
+ scopedEditableSkillIds: resolveAgentScopedSkillIds({
+ agent: handoffAgent,
+ accessibleSkillIds: editableSkillIds,
+ skillsCapabilityEnabled,
+ ephemeralSkillsToggle,
+ }),
+ skillCreateAllowed,
+ skillsCapabilityEnabled,
+ ephemeralSkillsToggle,
+ }),
+ skillStates,
+ defaultActiveOnShare,
+ codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
+ backgroundToolsAvailable: enabledCapabilities.has(AgentCapabilities.run_in_background),
+ toolIntentsAvailable: enabledCapabilities.has(AgentCapabilities.tool_intents),
+ statefulSessionsAvailable: enabledCapabilities.has(
+ AgentCapabilities.stateful_code_sessions,
+ ),
+ allowedStatefulCodeEnvironments: agentsEConfig?.statefulCodeSessions?.allowedEnvironments,
+ memoryAvailable,
+ };
+ const discoveryDeps = {
+ getAgent: db.getAgent,
+ checkPermission: async ({ userId, role, resourceId, requiredPermission }) => {
+ const permissions = await getRemoteAgentPermissions(
+ { getEffectivePermissions },
+ userId,
+ role,
+ resourceId,
+ );
+ return hasPermissions(permissions, requiredPermission);
},
- discoveryDeps,
- );
+ logViolation,
+ db: dbMethods,
+ onAgentInitialized: (loadedAgentId, loadedAgent, config) => {
+ agentToolContexts.set(
+ loadedAgentId,
+ buildAgentToolContext({ agent: loadedAgent, config }),
+ );
+ },
+ initializeAgent,
+ };
+ if (primaryConfig.edges?.length) {
+ ({
+ agentConfigs: handoffAgentConfigs,
+ edges: discoveredEdges,
+ userMCPAuthMap: discoveredMCPAuthMap,
+ } = await discoverConnectedAgents(discoveryParams, discoveryDeps));
+ }
+ if (subagentsCapabilityEnabled) {
+ discoveredMCPAuthMap = await resolveSubagentGraphs(
+ {
+ ...discoveryParams,
+ rootConfigs: [primaryConfig, ...handoffAgentConfigs.values()],
+ },
+ discoveryDeps,
+ );
+ }
}
- }
- primaryConfig.edges = discoveredEdges;
- const endpointTokenConfigByAgentId = new Map();
- for (const [agentId, context] of agentToolContexts) {
- endpointTokenConfigByAgentId.set(agentId, context.endpointTokenConfig);
- }
- const resolveEndpointTokenConfig = (usage) =>
- resolveAgentTokenConfig({
- agentId: usage?.agentId,
- byAgentId: endpointTokenConfigByAgentId,
- fallback: primaryConfig.endpointTokenConfig,
- });
- const runAgents = [primaryConfig, ...handoffAgentConfigs.values()];
- const initialSessions = buildInitialToolSessions({ agents: runAgents });
- const modelBoundAgentsById = new Map();
- const pendingModelBoundAgents = [...runAgents];
- for (let index = 0; index < pendingModelBoundAgents.length; index++) {
- const runAgent = pendingModelBoundAgents[index];
- if (!runAgent?.id || modelBoundAgentsById.has(runAgent.id)) {
- continue;
- }
- modelBoundAgentsById.set(runAgent.id, runAgent);
- for (const subagent of runAgent.subagentAgentConfigs?.values?.() ?? []) {
- pendingModelBoundAgents.push(subagent);
+ primaryConfig.edges = discoveredEdges;
+ const endpointTokenConfigByAgentId = new Map();
+ for (const [agentId, context] of agentToolContexts) {
+ endpointTokenConfigByAgentId.set(agentId, context.endpointTokenConfig);
}
- for (const graph of runAgent.subagentGraphConfigs ?? []) {
- pendingModelBoundAgents.push(...graph.memberConfigs);
+ const resolveEndpointTokenConfig = (usage) =>
+ resolveAgentTokenConfig({
+ agentId: usage?.agentId,
+ byAgentId: endpointTokenConfigByAgentId,
+ fallback: primaryConfig.endpointTokenConfig,
+ });
+ const runAgents = [primaryConfig, ...handoffAgentConfigs.values()];
+ const initialSessions = buildInitialToolSessions({ agents: runAgents });
+ const modelBoundAgentsById = new Map();
+ const pendingModelBoundAgents = [...runAgents];
+ for (let index = 0; index < pendingModelBoundAgents.length; index++) {
+ const runAgent = pendingModelBoundAgents[index];
+ if (!runAgent?.id || modelBoundAgentsById.has(runAgent.id)) {
+ continue;
+ }
+ modelBoundAgentsById.set(runAgent.id, runAgent);
+ for (const subagent of runAgent.subagentAgentConfigs?.values?.() ?? []) {
+ pendingModelBoundAgents.push(subagent);
+ }
+ for (const graph of runAgent.subagentGraphConfigs ?? []) {
+ pendingModelBoundAgents.push(...graph.memberConfigs);
+ }
}
- }
- const modelBoundAgents = [...modelBoundAgentsById.values()];
- const mergedMCPAuthMap = discoveredMCPAuthMap ?? primaryConfig.userMCPAuthMap;
- assertModelBoundContent({
- filters: appConfig?.filters,
- legacyPii: appConfig?.messageFilter?.pii,
- agents: modelBoundAgents,
- });
+ const modelBoundAgents = [...modelBoundAgentsById.values()];
+ const mergedMCPAuthMap = discoveredMCPAuthMap ?? primaryConfig.userMCPAuthMap;
+ assertModelBoundContent({
+ filters: appConfig?.filters,
+ legacyPii: appConfig?.messageFilter?.pii,
+ agents: modelBoundAgents,
+ });
- const agentContextAttachmentsByAgentId =
- buildAgentContextAttachmentsByAgentId(modelBoundAgents);
- const agentScopedContext = await buildAgentScopedContext({
- agentIds: modelBoundAgents.map(({ id }) => id),
- attachmentsByAgentId: agentContextAttachmentsByAgentId,
- req,
- });
+ const agentContextAttachmentsByAgentId =
+ buildAgentContextAttachmentsByAgentId(modelBoundAgents);
+ const agentScopedContext = await buildAgentScopedContext({
+ agentIds: modelBoundAgents.map(({ id }) => id),
+ attachmentsByAgentId: agentContextAttachmentsByAgentId,
+ req,
+ });
- const mcpManager = getMCPManager();
- const configServers = await resolveConfigServers(req);
+ const mcpManager = getMCPManager();
+ const configServers = await resolveConfigServers(req);
- await Promise.all(
- modelBoundAgents.map(async (runAgent) => {
- const memoryContext = await buildInlineMemoryContext({
- agent: runAgent,
- req,
- userId: principal.userId,
- memoryAvailable,
- getFormattedMemories: db.getFormattedMemories,
- });
- return applyContextToAgent({
- agent: runAgent,
- agentId: runAgent.id,
- logger,
- mcpManager,
- configServers,
- sharedRunContext: [memoryContext, agentScopedContext.get(runAgent.id)]
- .filter(Boolean)
- .join('\n\n'),
- });
- }),
- );
+ await Promise.all(
+ modelBoundAgents.map(async (runAgent) => {
+ const memoryContext = await buildInlineMemoryContext({
+ agent: runAgent,
+ req,
+ userId: principal.userId,
+ memoryAvailable,
+ getFormattedMemories: db.getFormattedMemories,
+ });
+ return applyContextToAgent({
+ agent: runAgent,
+ agentId: runAgent.id,
+ logger,
+ mcpManager,
+ configServers,
+ sharedRunContext: [memoryContext, agentScopedContext.get(runAgent.id)]
+ .filter(Boolean)
+ .join('\n\n'),
+ });
+ }),
+ );
- // Determine if streaming is enabled (check both request and agent config)
- const streamingDisabled = !!primaryConfig.model_parameters?.disableStreaming;
- const actuallyStreaming = isStreaming && !streamingDisabled;
-
- // Merge previous messages with new input
- const allMessages = [...previousMessages, ...inputMessages];
-
- const toolSet = buildToolSet(primaryConfig);
- const formatted = formatAgentMessages(stripActivityLabelParts(allMessages), {}, toolSet);
- const formattedMessages = formatted.messages;
- const initialSummary = formatted.summary;
- let indexTokenCountMap = formatted.indexTokenCountMap;
-
- /**
- * Inject manual + always-apply skill primes so the model sees SKILL.md
- * bodies for this turn — parity with AgentClient's chat path. The
- * Responses API uses its own response-builder shape, so LibreChat-
- * style card SSE events don't apply; only the message-context part
- * carries over.
- */
- const manualSkillPrimes = primaryConfig.manualSkillPrimes;
- const alwaysApplySkillPrimes = primaryConfig.alwaysApplySkillPrimes;
- if (
- (manualSkillPrimes && manualSkillPrimes.length > 0) ||
- (alwaysApplySkillPrimes && alwaysApplySkillPrimes.length > 0)
- ) {
- const primeResult = injectSkillPrimes({
- initialMessages: formattedMessages,
- indexTokenCountMap,
- manualSkillPrimes,
- alwaysApplySkillPrimes,
- });
- indexTokenCountMap = primeResult.indexTokenCountMap;
- /* Surface the cap-driven always-apply truncation at the controller
+ // Determine if streaming is enabled (check both request and agent config)
+ const streamingDisabled = !!primaryConfig.model_parameters?.disableStreaming;
+ const actuallyStreaming = isStreaming && !streamingDisabled;
+
+ // Merge previous messages with new input
+ const allMessages = [...previousMessages, ...inputMessages];
+
+ const toolSet = buildToolSet(primaryConfig);
+ const formatted = formatAgentMessages(stripActivityLabelParts(allMessages), {}, toolSet);
+ const formattedMessages = formatted.messages;
+ const initialSummary = formatted.summary;
+ let indexTokenCountMap = formatted.indexTokenCountMap;
+
+ /**
+ * Inject manual + always-apply skill primes so the model sees SKILL.md
+ * bodies for this turn — parity with AgentClient's chat path. The
+ * Responses API uses its own response-builder shape, so LibreChat-
+ * style card SSE events don't apply; only the message-context part
+ * carries over.
+ */
+ const manualSkillPrimes = primaryConfig.manualSkillPrimes;
+ const alwaysApplySkillPrimes = primaryConfig.alwaysApplySkillPrimes;
+ if (
+ (manualSkillPrimes && manualSkillPrimes.length > 0) ||
+ (alwaysApplySkillPrimes && alwaysApplySkillPrimes.length > 0)
+ ) {
+ const primeResult = injectSkillPrimes({
+ initialMessages: formattedMessages,
+ indexTokenCountMap,
+ manualSkillPrimes,
+ alwaysApplySkillPrimes,
+ });
+ indexTokenCountMap = primeResult.indexTokenCountMap;
+ /* Surface the cap-driven always-apply truncation at the controller
layer too — `injectSkillPrimes` already logs internally, but the
controller-level warn includes endpoint context so operators can
tell at a glance which path hit the cap. Mirrors AgentClient's
warn in `client.js`. */
- if (primeResult.alwaysApplyDropped > 0) {
- logger.warn(
- `[Responses API] Dropped ${primeResult.alwaysApplyDropped} always-apply prime(s) to stay within MAX_PRIMED_SKILLS_PER_TURN.`,
- );
+ if (primeResult.alwaysApplyDropped > 0) {
+ logger.warn(
+ `[Responses API] Dropped ${primeResult.alwaysApplyDropped} always-apply prime(s) to stay within MAX_PRIMED_SKILLS_PER_TURN.`,
+ );
+ }
}
- }
- assertModelBoundContent({
- filters: appConfig?.filters,
- legacyPii: appConfig?.messageFilter?.pii,
- submittedMessages: inputMessages,
- agents: modelBoundAgents,
- skills: [...(manualSkillPrimes ?? []), ...(alwaysApplySkillPrimes ?? [])],
- files: collectModelBoundAgentFiles(modelBoundAgents),
- });
+ assertModelBoundContent({
+ filters: appConfig?.filters,
+ legacyPii: appConfig?.messageFilter?.pii,
+ submittedMessages: inputMessages,
+ agents: modelBoundAgents,
+ skills: [...(manualSkillPrimes ?? []), ...(alwaysApplySkillPrimes ?? [])],
+ files: collectModelBoundAgentFiles(modelBoundAgents),
+ });
- /* Stable for the turn: the primary prime list is fixed once
+ /* Stable for the turn: the primary prime list is fixed once
`initializeAgent` resolves and is used as the fallback when a
specific agent context is unavailable. `codeEnvAvailable` is read
per-agent from the stored tool context (admin cap AND that
agent's `tools` list includes `execute_code`) — a skills-only
agent never gains sandbox access even if the admin enabled the
capability globally. */
- // Create tracker for streaming or aggregator for non-streaming
- const tracker = actuallyStreaming ? createResponseTracker() : null;
- const aggregator = actuallyStreaming ? null : createResponseAggregator();
-
- // Set up response for streaming
- if (actuallyStreaming) {
- setupStreamingResponse(res);
+ // Create tracker for streaming or aggregator for non-streaming
+ const tracker = actuallyStreaming ? createResponseTracker() : null;
+ const aggregator = actuallyStreaming ? null : createResponseAggregator();
- // Create handler config
- const handlerConfig = {
- res,
- context,
- tracker,
- };
+ // Set up response for streaming
+ if (actuallyStreaming) {
+ setupStreamingResponse(res);
- // Emit response.created then response.in_progress per Open Responses spec
- emitResponseCreated(handlerConfig);
- emitResponseInProgress(handlerConfig);
+ // Create handler config
+ const handlerConfig = {
+ res,
+ context,
+ tracker,
+ };
- // Create event handlers
- const { handlers: responsesHandlers, finalizeStream } =
- createResponsesEventHandlers(handlerConfig);
+ // Emit response.created then response.in_progress per Open Responses spec
+ emitResponseCreated(handlerConfig);
+ emitResponseInProgress(handlerConfig);
- // Collect usage for balance tracking
- const collectedUsage = [];
+ // Create event handlers
+ const { handlers: responsesHandlers, finalizeStream } =
+ createResponsesEventHandlers(handlerConfig);
- // Artifact promises for processing tool outputs
- // Use Responses API-specific callback that emits librechat:attachment events
- const toolEndCallback = createResponsesToolEndCallback({
- req,
- res,
- tracker,
- artifactPromises,
- });
+ // Collect usage for balance tracking
+ const collectedUsage = [];
- // Create tool execute options for event-driven tool execution
- const toolExecuteOptions = {
- loadTools: async (toolNames, agentId, _configurable, callerCapabilityProjection) => {
- const ctx =
- agentToolContexts.get(agentId) ?? agentToolContexts.get(primaryConfig.id) ?? {};
- const result = await loadToolsForExecution({
- req,
- res,
- agentResourceType: ResourceType.REMOTE_AGENT,
- conversationId,
- requestBody: mcpRequestBody,
- toolNames,
- agent: ctx.agent ?? agent,
- signal: execution.signal,
- toolRegistry: ctx.toolRegistry,
- callerCapabilityProjection,
- backgroundToolNames: ctx.backgroundToolNames,
- intentToolNames: ctx.intentToolNames,
- mcpAvailableTools: ctx.mcpAvailableTools,
- requestScopedConnections: ctx.requestScopedConnections,
- userMCPAuthMap: ctx.userMCPAuthMap,
- tool_resources: ctx.tool_resources,
- actionsEnabled: ctx.actionsEnabled,
- accessibleMcpServerNames: ctx.accessibleMcpServerNames,
- });
- return enrichLoadedToolsWithAgentContext({
- result,
- req,
- ctx,
- });
- },
- toolEndCallback,
- ...getSkillToolDeps(),
- };
+ // Artifact promises for processing tool outputs
+ // Use Responses API-specific callback that emits librechat:attachment events
+ const toolEndCallback = createResponsesToolEndCallback({
+ req,
+ res,
+ tracker,
+ artifactPromises,
+ });
- // Combine handlers
- const handlers = {
- on_message_delta: responsesHandlers.on_message_delta,
- on_reasoning_delta: responsesHandlers.on_reasoning_delta,
- on_run_step: responsesHandlers.on_run_step,
- on_run_step_delta: responsesHandlers.on_run_step_delta,
- on_chat_model_end: {
- handle: (event, data, metadata, graph) => {
- responsesHandlers.on_chat_model_end.handle(event, data);
- const usage = data?.output?.usage_metadata;
- if (usage) {
- const agentContext = graph?.getAgentContext?.(metadata);
- const taggedUsage = contextualizeModelUsage(usage, metadata, agentContext);
- collectedUsage.push(taggedUsage);
- }
+ // Create tool execute options for event-driven tool execution
+ const toolExecuteOptions = {
+ loadTools: async (toolNames, agentId, _configurable, callerCapabilityProjection) => {
+ const ctx =
+ agentToolContexts.get(agentId) ?? agentToolContexts.get(primaryConfig.id) ?? {};
+ const result = await loadToolsForExecution({
+ req,
+ res,
+ agentResourceType: ResourceType.REMOTE_AGENT,
+ conversationId,
+ requestBody: mcpRequestBody,
+ toolNames,
+ agent: ctx.agent ?? agent,
+ signal: execution.signal,
+ toolRegistry: ctx.toolRegistry,
+ callerCapabilityProjection,
+ backgroundToolNames: ctx.backgroundToolNames,
+ intentToolNames: ctx.intentToolNames,
+ mcpAvailableTools: ctx.mcpAvailableTools,
+ requestScopedConnections: ctx.requestScopedConnections,
+ userMCPAuthMap: ctx.userMCPAuthMap,
+ tool_resources: ctx.tool_resources,
+ actionsEnabled: ctx.actionsEnabled,
+ accessibleMcpServerNames: ctx.accessibleMcpServerNames,
+ });
+ return enrichLoadedToolsWithAgentContext({
+ result,
+ req,
+ ctx,
+ });
},
- },
- on_tool_end: new ToolEndHandler(toolEndCallback, logger),
- on_run_step_completed: { handle: () => {} },
- on_chain_stream: { handle: () => {} },
- on_chain_end: { handle: () => {} },
- on_agent_update: { handle: () => {} },
- on_custom_event: { handle: () => {} },
- on_tool_execute: createToolExecuteHandler(toolExecuteOptions),
- on_agent_log: agentLogHandlerObj,
- ...(summarizationConfig?.enabled !== false
- ? buildSummarizationHandlers({ isStreaming: actuallyStreaming, res })
- : {}),
- };
-
- // Create and run the agent
- const userId = principal.userId;
- const userMCPAuthMap = mergedMCPAuthMap;
-
- const run = await createRun({
- agents: runAgents,
- messages: formattedMessages,
- indexTokenCountMap,
- initialSummary,
- runId: responseId,
- summarizationConfig,
- appConfig,
- signal: execution.signal,
- customHandlers: handlers,
- initialSessions,
- requestBody: mcpRequestBody,
- user: { id: userId },
- tenantId: principal.tenantId,
- /** Bills subagent child-run model calls (reported outside the
- * streamEvents loop) into the same collectedUsage array. */
- subagentUsageSink: createSubagentUsageSink(collectedUsage),
- });
-
- if (!run) {
- throw new Error('Failed to create agent run');
- }
-
- // Process the stream
- const config = {
- runName: 'AgentRun',
- configurable: {
- thread_id: conversationId,
- user_id: userId,
- user: createSafeUser(req.user),
+ toolEndCallback,
+ ...getSkillToolDeps(),
+ };
+
+ // Combine handlers
+ const handlers = {
+ on_message_delta: responsesHandlers.on_message_delta,
+ on_reasoning_delta: responsesHandlers.on_reasoning_delta,
+ on_run_step: responsesHandlers.on_run_step,
+ on_run_step_delta: responsesHandlers.on_run_step_delta,
+ on_chat_model_end: {
+ handle: (event, data, metadata, graph) => {
+ responsesHandlers.on_chat_model_end.handle(event, data);
+ const usage = data?.output?.usage_metadata;
+ if (usage) {
+ const agentContext = graph?.getAgentContext?.(metadata);
+ const taggedUsage = contextualizeModelUsage(usage, metadata, agentContext);
+ collectedUsage.push(taggedUsage);
+ }
+ },
+ },
+ on_tool_end: new ToolEndHandler(toolEndCallback, logger),
+ on_run_step_completed: { handle: () => {} },
+ on_chain_stream: { handle: () => {} },
+ on_chain_end: { handle: () => {} },
+ on_agent_update: { handle: () => {} },
+ on_custom_event: { handle: () => {} },
+ on_tool_execute: createToolExecuteHandler(toolExecuteOptions),
+ on_agent_log: agentLogHandlerObj,
+ ...(summarizationConfig?.enabled !== false
+ ? buildSummarizationHandlers({ isStreaming: actuallyStreaming, res })
+ : {}),
+ };
+
+ // Create and run the agent
+ const userId = principal.userId;
+ const userMCPAuthMap = mergedMCPAuthMap;
+
+ const run = await createRun({
+ agents: runAgents,
+ messages: formattedMessages,
+ indexTokenCountMap,
+ initialSummary,
+ runId: responseId,
+ summarizationConfig,
+ appConfig,
+ signal: execution.signal,
+ customHandlers: handlers,
+ initialSessions,
requestBody: mcpRequestBody,
- ...(userMCPAuthMap != null && { userMCPAuthMap }),
- },
- signal: execution.signal,
- streamMode: 'values',
- version: 'v2',
- };
+ user: { id: userId },
+ tenantId: principal.tenantId,
+ /** Bills subagent child-run model calls (reported outside the
+ * streamEvents loop) into the same collectedUsage array. */
+ subagentUsageSink: createSubagentUsageSink(collectedUsage),
+ });
- await run.processStream({ messages: formattedMessages }, config, {
- callbacks: {
- [Callback.TOOL_ERROR]: (graph, error, toolId) => {
- logger.error(`[Responses API] Tool Error "${toolId}"`, getSafeErrorMetadata(error));
- },
- },
- });
+ if (!run) {
+ throw new Error('Failed to create agent run');
+ }
- // Record token usage against balance
- const balanceConfig = getBalanceConfig(appConfig);
- const transactionsConfig = getTransactionsConfig(appConfig);
- execution.track(
- recordCollectedUsage(
- {
- spendTokens: db.spendTokens,
- spendStructuredTokens: db.spendStructuredTokens,
- pricing: { getMultiplier: db.getMultiplier, getCacheMultiplier: db.getCacheMultiplier },
- bulkWriteOps: {
- insertMany: db.bulkInsertTransactions,
- updateBalance: db.updateBalance,
- },
+ // Process the stream
+ const config = {
+ runName: 'AgentRun',
+ configurable: {
+ thread_id: conversationId,
+ user_id: userId,
+ user: createSafeUser(req.user),
+ requestBody: mcpRequestBody,
+ ...(userMCPAuthMap != null && { userMCPAuthMap }),
},
- {
- user: userId,
- conversationId,
- collectedUsage,
- context: 'message',
- messageId: responseId,
- balance: balanceConfig,
- transactions: transactionsConfig,
- model: primaryConfig.model || agent.model_parameters?.model,
- endpointTokenConfig: primaryConfig.endpointTokenConfig,
- resolveEndpointTokenConfig,
+ signal: execution.signal,
+ streamMode: 'values',
+ version: 'v2',
+ };
+
+ await run.processStream({ messages: formattedMessages }, config, {
+ callbacks: {
+ [Callback.TOOL_ERROR]: (graph, error, toolId) => {
+ logger.error(`[Responses API] Tool Error "${toolId}"`, getSafeErrorMetadata(error));
+ },
},
- ).catch((err) => {
- logger.error('[Responses API] Error recording usage:', getSafeErrorMetadata(err));
- }),
- );
+ });
- const usage = buildResponsesUsage(collectedUsage);
+ // Record token usage against balance
+ const balanceConfig = getBalanceConfig(appConfig);
+ const transactionsConfig = getTransactionsConfig(appConfig);
+ execution.track(
+ recordCollectedUsage(
+ {
+ spendTokens: db.spendTokens,
+ spendStructuredTokens: db.spendStructuredTokens,
+ pricing: {
+ getMultiplier: db.getMultiplier,
+ getCacheMultiplier: db.getCacheMultiplier,
+ },
+ bulkWriteOps: {
+ insertMany: db.bulkInsertTransactions,
+ updateBalance: db.updateBalance,
+ },
+ },
+ {
+ user: userId,
+ conversationId,
+ collectedUsage,
+ context: 'message',
+ messageId: responseId,
+ balance: balanceConfig,
+ transactions: transactionsConfig,
+ model: primaryConfig.model || agent.model_parameters?.model,
+ endpointTokenConfig: primaryConfig.endpointTokenConfig,
+ resolveEndpointTokenConfig,
+ },
+ ).catch((err) => {
+ logger.error('[Responses API] Error recording usage:', getSafeErrorMetadata(err));
+ }),
+ );
- // Finalize the stream
- finalizeStream(usage);
- res.end();
+ const usage = buildResponsesUsage(collectedUsage);
- const duration = Date.now() - requestStartTime;
- logger.debug(`[Responses API] Request ${responseId} completed in ${duration}ms (streaming)`);
+ // Finalize the stream
+ finalizeStream(usage);
+ res.end();
- // Save to database if store: true
- if (request.store === true) {
- try {
- // Save conversation
- await saveConversation(req, conversationId, agentId, agent);
+ const duration = Date.now() - requestStartTime;
+ logger.debug(
+ `[Responses API] Request ${responseId} completed in ${duration}ms (streaming)`,
+ );
- // Save input messages
- await saveInputMessages(req, conversationId, inputMessages, agentId);
+ // Save to database if store: true
+ if (request.store === true) {
+ try {
+ // Save conversation
+ await saveConversation(req, conversationId, agentId, agent);
+
+ // Save input messages
+ await saveInputMessages(req, conversationId, inputMessages, agentId);
+
+ // Build response for saving (use tracker with buildResponse for streaming)
+ const finalResponse = buildResponse(context, tracker, 'completed');
+ await saveResponseOutput(
+ req,
+ conversationId,
+ responseId,
+ finalResponse,
+ agentId,
+ tracker.usage.outputTokens,
+ );
- // Build response for saving (use tracker with buildResponse for streaming)
- const finalResponse = buildResponse(context, tracker, 'completed');
- await saveResponseOutput(
- req,
- conversationId,
- responseId,
- finalResponse,
- agentId,
- tracker.usage.outputTokens,
- );
+ logger.debug(
+ `[Responses API] Stored response ${responseId} in conversation ${conversationId}`,
+ );
+ } catch (saveError) {
+ logger.error('[Responses API] Error saving response:', getSafeErrorMetadata(saveError));
+ // Don't fail the request if saving fails
+ }
+ }
- logger.debug(
- `[Responses API] Stored response ${responseId} in conversation ${conversationId}`,
+ // The HTTP response is complete, while destructive cleanup still waits for artifacts.
+ if (artifactPromises.length > 0) {
+ execution.track(
+ waitForAgentExecutionWrites(artifactPromises).catch((artifactError) => {
+ logger.warn(
+ '[Responses API] Error processing artifacts:',
+ getSafeErrorMetadata(artifactError),
+ );
+ }),
);
- } catch (saveError) {
- logger.error('[Responses API] Error saving response:', getSafeErrorMetadata(saveError));
- // Don't fail the request if saving fails
+ artifactWritesCovered = true;
}
- }
-
- // The HTTP response is complete, while destructive cleanup still waits for artifacts.
- if (artifactPromises.length > 0) {
- execution.track(
- waitForAgentExecutionWrites(artifactPromises).catch((artifactError) => {
- logger.warn(
- '[Responses API] Error processing artifacts:',
- getSafeErrorMetadata(artifactError),
- );
- }),
- );
- artifactWritesCovered = true;
- }
- } else {
- const aggregatorHandlers = createAggregatorEventHandlers(aggregator);
-
- // Collect usage for balance tracking
- const collectedUsage = [];
+ } else {
+ const aggregatorHandlers = createAggregatorEventHandlers(aggregator);
- const toolEndCallback = createToolEndCallback({ req, res, artifactPromises, streamId: null });
+ // Collect usage for balance tracking
+ const collectedUsage = [];
- const toolExecuteOptions = {
- loadTools: async (toolNames, agentId, _configurable, callerCapabilityProjection) => {
- const ctx =
- agentToolContexts.get(agentId) ?? agentToolContexts.get(primaryConfig.id) ?? {};
- const result = await loadToolsForExecution({
- req,
- res,
- agentResourceType: ResourceType.REMOTE_AGENT,
- conversationId,
- requestBody: mcpRequestBody,
- toolNames,
- agent: ctx.agent ?? agent,
- signal: execution.signal,
- toolRegistry: ctx.toolRegistry,
- callerCapabilityProjection,
- backgroundToolNames: ctx.backgroundToolNames,
- intentToolNames: ctx.intentToolNames,
- mcpAvailableTools: ctx.mcpAvailableTools,
- requestScopedConnections: ctx.requestScopedConnections,
- userMCPAuthMap: ctx.userMCPAuthMap,
- tool_resources: ctx.tool_resources,
- actionsEnabled: ctx.actionsEnabled,
- accessibleMcpServerNames: ctx.accessibleMcpServerNames,
- });
- return enrichLoadedToolsWithAgentContext({
- result,
- req,
- ctx,
- });
- },
- toolEndCallback,
- ...getSkillToolDeps(),
- };
+ const toolEndCallback = createToolEndCallback({
+ req,
+ res,
+ artifactPromises,
+ streamId: null,
+ });
- const handlers = {
- on_message_delta: aggregatorHandlers.on_message_delta,
- on_reasoning_delta: aggregatorHandlers.on_reasoning_delta,
- on_run_step: aggregatorHandlers.on_run_step,
- on_run_step_delta: aggregatorHandlers.on_run_step_delta,
- on_chat_model_end: {
- handle: (event, data, metadata, graph) => {
- aggregatorHandlers.on_chat_model_end.handle(event, data);
- const usage = data?.output?.usage_metadata;
- if (usage) {
- const agentContext = graph?.getAgentContext?.(metadata);
- const taggedUsage = contextualizeModelUsage(usage, metadata, agentContext);
- collectedUsage.push(taggedUsage);
- }
+ const toolExecuteOptions = {
+ loadTools: async (toolNames, agentId, _configurable, callerCapabilityProjection) => {
+ const ctx =
+ agentToolContexts.get(agentId) ?? agentToolContexts.get(primaryConfig.id) ?? {};
+ const result = await loadToolsForExecution({
+ req,
+ res,
+ agentResourceType: ResourceType.REMOTE_AGENT,
+ conversationId,
+ requestBody: mcpRequestBody,
+ toolNames,
+ agent: ctx.agent ?? agent,
+ signal: execution.signal,
+ toolRegistry: ctx.toolRegistry,
+ callerCapabilityProjection,
+ backgroundToolNames: ctx.backgroundToolNames,
+ intentToolNames: ctx.intentToolNames,
+ mcpAvailableTools: ctx.mcpAvailableTools,
+ requestScopedConnections: ctx.requestScopedConnections,
+ userMCPAuthMap: ctx.userMCPAuthMap,
+ tool_resources: ctx.tool_resources,
+ actionsEnabled: ctx.actionsEnabled,
+ accessibleMcpServerNames: ctx.accessibleMcpServerNames,
+ });
+ return enrichLoadedToolsWithAgentContext({
+ result,
+ req,
+ ctx,
+ });
},
- },
- on_tool_end: new ToolEndHandler(toolEndCallback, logger),
- on_run_step_completed: { handle: () => {} },
- on_chain_stream: { handle: () => {} },
- on_chain_end: { handle: () => {} },
- on_agent_update: { handle: () => {} },
- on_custom_event: { handle: () => {} },
- on_tool_execute: createToolExecuteHandler(toolExecuteOptions),
- on_agent_log: agentLogHandlerObj,
- ...(summarizationConfig?.enabled !== false
- ? buildSummarizationHandlers({ isStreaming: false, res })
- : {}),
- };
-
- const userId = principal.userId;
- const userMCPAuthMap = mergedMCPAuthMap;
-
- const run = await createRun({
- agents: runAgents,
- messages: formattedMessages,
- indexTokenCountMap,
- initialSummary,
- runId: responseId,
- summarizationConfig,
- appConfig,
- signal: execution.signal,
- customHandlers: handlers,
- initialSessions,
- requestBody: mcpRequestBody,
- user: { id: userId },
- tenantId: principal.tenantId,
- /** Bills subagent child-run model calls (reported outside the
- * streamEvents loop) into the same collectedUsage array. */
- subagentUsageSink: createSubagentUsageSink(collectedUsage),
- });
-
- if (!run) {
- throw new Error('Failed to create agent run');
- }
-
- const config = {
- runName: 'AgentRun',
- configurable: {
- thread_id: conversationId,
- user_id: userId,
- user: createSafeUser(req.user),
+ toolEndCallback,
+ ...getSkillToolDeps(),
+ };
+
+ const handlers = {
+ on_message_delta: aggregatorHandlers.on_message_delta,
+ on_reasoning_delta: aggregatorHandlers.on_reasoning_delta,
+ on_run_step: aggregatorHandlers.on_run_step,
+ on_run_step_delta: aggregatorHandlers.on_run_step_delta,
+ on_chat_model_end: {
+ handle: (event, data, metadata, graph) => {
+ aggregatorHandlers.on_chat_model_end.handle(event, data);
+ const usage = data?.output?.usage_metadata;
+ if (usage) {
+ const agentContext = graph?.getAgentContext?.(metadata);
+ const taggedUsage = contextualizeModelUsage(usage, metadata, agentContext);
+ collectedUsage.push(taggedUsage);
+ }
+ },
+ },
+ on_tool_end: new ToolEndHandler(toolEndCallback, logger),
+ on_run_step_completed: { handle: () => {} },
+ on_chain_stream: { handle: () => {} },
+ on_chain_end: { handle: () => {} },
+ on_agent_update: { handle: () => {} },
+ on_custom_event: { handle: () => {} },
+ on_tool_execute: createToolExecuteHandler(toolExecuteOptions),
+ on_agent_log: agentLogHandlerObj,
+ ...(summarizationConfig?.enabled !== false
+ ? buildSummarizationHandlers({ isStreaming: false, res })
+ : {}),
+ };
+
+ const userId = principal.userId;
+ const userMCPAuthMap = mergedMCPAuthMap;
+
+ const run = await createRun({
+ agents: runAgents,
+ messages: formattedMessages,
+ indexTokenCountMap,
+ initialSummary,
+ runId: responseId,
+ summarizationConfig,
+ appConfig,
+ signal: execution.signal,
+ customHandlers: handlers,
+ initialSessions,
requestBody: mcpRequestBody,
- ...(userMCPAuthMap != null && { userMCPAuthMap }),
- },
- signal: execution.signal,
- streamMode: 'values',
- version: 'v2',
- };
+ user: { id: userId },
+ tenantId: principal.tenantId,
+ /** Bills subagent child-run model calls (reported outside the
+ * streamEvents loop) into the same collectedUsage array. */
+ subagentUsageSink: createSubagentUsageSink(collectedUsage),
+ });
- await run.processStream({ messages: formattedMessages }, config, {
- callbacks: {
- [Callback.TOOL_ERROR]: (graph, error, toolId) => {
- logger.error(`[Responses API] Tool Error "${toolId}"`, getSafeErrorMetadata(error));
- },
- },
- });
+ if (!run) {
+ throw new Error('Failed to create agent run');
+ }
- // Record token usage against balance
- const balanceConfig = getBalanceConfig(appConfig);
- const transactionsConfig = getTransactionsConfig(appConfig);
- execution.track(
- recordCollectedUsage(
- {
- spendTokens: db.spendTokens,
- spendStructuredTokens: db.spendStructuredTokens,
- pricing: { getMultiplier: db.getMultiplier, getCacheMultiplier: db.getCacheMultiplier },
- bulkWriteOps: {
- insertMany: db.bulkInsertTransactions,
- updateBalance: db.updateBalance,
- },
+ const config = {
+ runName: 'AgentRun',
+ configurable: {
+ thread_id: conversationId,
+ user_id: userId,
+ user: createSafeUser(req.user),
+ requestBody: mcpRequestBody,
+ ...(userMCPAuthMap != null && { userMCPAuthMap }),
},
- {
- user: userId,
- conversationId,
- collectedUsage,
- context: 'message',
- messageId: responseId,
- balance: balanceConfig,
- transactions: transactionsConfig,
- model: primaryConfig.model || agent.model_parameters?.model,
- endpointTokenConfig: primaryConfig.endpointTokenConfig,
- resolveEndpointTokenConfig,
+ signal: execution.signal,
+ streamMode: 'values',
+ version: 'v2',
+ };
+
+ await run.processStream({ messages: formattedMessages }, config, {
+ callbacks: {
+ [Callback.TOOL_ERROR]: (graph, error, toolId) => {
+ logger.error(`[Responses API] Tool Error "${toolId}"`, getSafeErrorMetadata(error));
+ },
},
- ).catch((err) => {
- logger.error('[Responses API] Error recording usage:', getSafeErrorMetadata(err));
- }),
- );
+ });
- if (artifactPromises.length > 0) {
- try {
- await waitForAgentExecutionWrites(artifactPromises);
- } catch (artifactError) {
- logger.warn(
- '[Responses API] Error processing artifacts:',
- getSafeErrorMetadata(artifactError),
- );
+ // Record token usage against balance
+ const balanceConfig = getBalanceConfig(appConfig);
+ const transactionsConfig = getTransactionsConfig(appConfig);
+ execution.track(
+ recordCollectedUsage(
+ {
+ spendTokens: db.spendTokens,
+ spendStructuredTokens: db.spendStructuredTokens,
+ pricing: {
+ getMultiplier: db.getMultiplier,
+ getCacheMultiplier: db.getCacheMultiplier,
+ },
+ bulkWriteOps: {
+ insertMany: db.bulkInsertTransactions,
+ updateBalance: db.updateBalance,
+ },
+ },
+ {
+ user: userId,
+ conversationId,
+ collectedUsage,
+ context: 'message',
+ messageId: responseId,
+ balance: balanceConfig,
+ transactions: transactionsConfig,
+ model: primaryConfig.model || agent.model_parameters?.model,
+ endpointTokenConfig: primaryConfig.endpointTokenConfig,
+ resolveEndpointTokenConfig,
+ },
+ ).catch((err) => {
+ logger.error('[Responses API] Error recording usage:', getSafeErrorMetadata(err));
+ }),
+ );
+
+ if (artifactPromises.length > 0) {
+ try {
+ await waitForAgentExecutionWrites(artifactPromises);
+ } catch (artifactError) {
+ logger.warn(
+ '[Responses API] Error processing artifacts:',
+ getSafeErrorMetadata(artifactError),
+ );
+ }
+ artifactWritesCovered = true;
}
- artifactWritesCovered = true;
- }
- const response = buildAggregatedResponse(
- context,
- aggregator,
- buildResponsesUsage(collectedUsage),
- );
+ const response = buildAggregatedResponse(
+ context,
+ aggregator,
+ buildResponsesUsage(collectedUsage),
+ );
- if (request.store === true) {
- try {
- await saveConversation(req, conversationId, agentId, agent);
+ if (request.store === true) {
+ try {
+ await saveConversation(req, conversationId, agentId, agent);
- await saveInputMessages(req, conversationId, inputMessages, agentId);
+ await saveInputMessages(req, conversationId, inputMessages, agentId);
- await saveResponseOutput(
- req,
- conversationId,
- responseId,
- response,
- agentId,
- aggregator.usage.outputTokens,
- );
+ await saveResponseOutput(
+ req,
+ conversationId,
+ responseId,
+ response,
+ agentId,
+ aggregator.usage.outputTokens,
+ );
- logger.debug(
- `[Responses API] Stored response ${responseId} in conversation ${conversationId}`,
- );
- } catch (saveError) {
- logger.error('[Responses API] Error saving response:', getSafeErrorMetadata(saveError));
- // Don't fail the request if saving fails
+ logger.debug(
+ `[Responses API] Stored response ${responseId} in conversation ${conversationId}`,
+ );
+ } catch (saveError) {
+ logger.error('[Responses API] Error saving response:', getSafeErrorMetadata(saveError));
+ // Don't fail the request if saving fails
+ }
}
- }
- res.json(response);
+ res.json(response);
- const duration = Date.now() - requestStartTime;
- logger.debug(
- `[Responses API] Request ${responseId} completed in ${duration}ms (non-streaming)`,
- );
- }
- } catch (error) {
- executionError = error;
- logger.error('[Responses API] Error:', getSafeErrorMetadata(error));
- const protectionEnabled = hasModelBoundContentProtection(
- appConfig?.filters,
- appConfig?.messageFilter?.pii,
- );
- const errorMessage = getUserFacingProviderError(error, protectionEnabled);
-
- // Check if we already started streaming (headers sent)
- if (res.headersSent) {
- // Headers already sent, write error event and close
- writeDone(res);
- res.end();
- } else {
- if (isContentFilterError(error)) {
- return sendResponsesErrorResponse(
- res,
- error.statusCode,
- error.body.message,
- 'invalid_request',
- error.body.error,
- );
- }
- // Forward upstream provider status codes (e.g., Anthropic 400s) instead of masking as 500
- const statusCode =
- typeof error?.status === 'number' && error.status >= 400 && error.status < 600
- ? error.status
- : 500;
- const errorType = statusCode >= 400 && statusCode < 500 ? 'invalid_request' : 'server_error';
- const errorCode =
- !protectionEnabled && typeof error?.code === 'string' ? error.code : undefined;
- if (errorCode === undefined) {
- sendResponsesErrorResponse(res, statusCode, errorMessage, errorType);
- } else {
- sendResponsesErrorResponse(res, statusCode, errorMessage, errorType, errorCode);
- }
- }
- } finally {
- res.off('close', abortOnResponseClose);
- if (execution) {
- if (!artifactWritesCovered && artifactPromises.length > 0) {
- execution.track(
- waitForAgentExecutionWrites(artifactPromises).catch((artifactError) => {
- logger.warn(
- '[Responses API] Error processing artifacts:',
- getSafeErrorMetadata(artifactError),
- );
- }),
+ const duration = Date.now() - requestStartTime;
+ logger.debug(
+ `[Responses API] Request ${responseId} completed in ${duration}ms (non-streaming)`,
);
}
- await execution.settle(executionError).catch((error) => {
- logger.error('[Responses API] Failed to settle execution:', getSafeErrorMetadata(error));
- });
- }
- }
+ },
+ });
};
/**
diff --git a/api/server/services/Endpoints/agents/initialize.js b/api/server/services/Endpoints/agents/initialize.js
index 024246b80b..42c0f82ccb 100644
--- a/api/server/services/Endpoints/agents/initialize.js
+++ b/api/server/services/Endpoints/agents/initialize.js
@@ -79,17 +79,24 @@ const SUBAGENT_GRAPH_LOAD_CONCURRENCY = 4;
/**
* Creates a tool loader function for the agent.
+ * @param {ServerRequest} req - Request-backed tool adapter input
+ * @param {ServerResponse} res - Response-backed tool adapter input
* @param {AbortSignal} signal - The abort signal
* @param {string | null} [streamId] - The stream ID for resumable mode
* @param {boolean} [definitionsOnly=false] - When true, returns only serializable
* tool definitions without creating full tool instances (for event-driven mode)
* @param {number} [jobCreatedAt] - The generation epoch that owns emitted tool events
*/
-function createToolLoader(signal, streamId = null, definitionsOnly = false, jobCreatedAt) {
+function createToolLoader(
+ req,
+ res,
+ signal,
+ streamId = null,
+ definitionsOnly = false,
+ jobCreatedAt,
+) {
/**
* @param {object} params
- * @param {ServerRequest} params.req
- * @param {ServerResponse} params.res
* @param {string} params.agentId
* @param {string[]} params.tools
* @param {string} params.provider
@@ -104,8 +111,6 @@ function createToolLoader(signal, streamId = null, definitionsOnly = false, jobC
* } | undefined>}
*/
return async function loadTools({
- req,
- res,
tools,
model,
agentId,
@@ -499,7 +504,7 @@ const initializeClient = async ({
const allowedProviders = new Set(appConfig?.endpoints?.[EModelEndpoint.agents]?.allowedProviders);
/** Event-driven mode: only load tool definitions, not full instances */
- const loadTools = createToolLoader(signal, streamId, true, jobCreatedAt);
+ const loadTools = createToolLoader(req, res, signal, streamId, true, jobCreatedAt);
/** @type {Array<MongoFile>} */
const requestFiles = req.body.files ?? [];
/** @type {string | undefined} */
@@ -1074,7 +1079,7 @@ const initializeClient = async ({
req,
res,
agent,
- loadTools: createToolLoader(context.signal, streamId, true, jobCreatedAt),
+ loadTools: createToolLoader(req, res, context.signal, streamId, true, jobCreatedAt),
requestFiles,
conversationId,
parentMessageId,
diff --git a/packages/api/src/agents/__tests__/initialize.test.ts b/packages/api/src/agents/__tests__/initialize.test.ts
index c260d1ba38..3455003831 100644
--- a/packages/api/src/agents/__tests__/initialize.test.ts
+++ b/packages/api/src/agents/__tests__/initialize.test.ts
@@ -96,6 +96,7 @@ jest.mock('~/endpoints', () => ({
jest.mock('~/files', () => ({
filterFilesByEndpointConfig: jest.fn(() => []),
+ filterFilesByEndpointRuntimeConfig: jest.fn(() => []),
}));
jest.mock('~/prompts', () => ({
@@ -258,6 +259,37 @@ function countUrlContextTools(tools: unknown[] | undefined): number {
);
}
+describe('initializeAgent — execution context', () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ });
+
+ it('initializes without Express request or response objects', async () => {
+ const { agent, loadTools, db } = createMocks();
+
+ await expect(
+ initializeAgent(
+ {
+ runtime: {
+ user: { id: 'user-1' } as never,
+ appConfig: {} as never,
+ requestBody: { timezone: 'America/New_York' },
+ },
+ agent,
+ loadTools,
+ endpointOption: { endpoint: EModelEndpoint.agents },
+ allowedProviders: new Set([Providers.OPENAI]),
+ isInitialAgent: true,
+ },
+ db,
+ ),
+ ).resolves.toBeDefined();
+
+ expect(loadTools).toHaveBeenCalledWith(expect.not.objectContaining({ req: expect.anything() }));
+ expect(loadTools).toHaveBeenCalledWith(expect.not.objectContaining({ res: expect.anything() }));
+ });
+});
+
describe('initializeAgent — current content policy preflight', () => {
beforeEach(() => {
jest.clearAllMocks();
@@ -1272,8 +1304,8 @@ describe('initializeAgent — attachment scoping', () => {
const { primeResources } = jest.requireMock('../resources') as {
primeResources: jest.Mock;
};
- const { filterFilesByEndpointConfig } = jest.requireMock('~/files') as {
- filterFilesByEndpointConfig: jest.Mock;
+ const { filterFilesByEndpointRuntimeConfig } = jest.requireMock('~/files') as {
+ filterFilesByEndpointRuntimeConfig: jest.Mock;
};
const requestFile = { file_id: 'request-file', filename: 'request.txt' } as IMongoFile;
const toolFile = { file_id: 'tool-file', filename: 'tool.txt' } as IMongoFile;
@@ -1291,7 +1323,7 @@ describe('initializeAgent — attachment scoping', () => {
(db.updateFilesUsage as jest.Mock)
.mockResolvedValueOnce([{ ...requestFile, filename: 'post-mutation-request.txt' }])
.mockResolvedValueOnce([{ ...toolFile, filename: 'post-mutation-tool.txt' }]);
- filterFilesByEndpointConfig.mockImplementationOnce(
+ filterFilesByEndpointRuntimeConfig.mockImplementationOnce(
(_req: ServerRequest, { files }: { files: IMongoFile[] }) => files,
);
@@ -1341,8 +1373,8 @@ describe('initializeAgent — attachment scoping', () => {
const { primeResources } = jest.requireMock('../resources') as {
primeResources: jest.Mock;
};
- const { filterFilesByEndpointConfig } = jest.requireMock('~/files') as {
- filterFilesByEndpointConfig: jest.Mock;
+ const { filterFilesByEndpointRuntimeConfig } = jest.requireMock('~/files') as {
+ filterFilesByEndpointRuntimeConfig: jest.Mock;
};
const blockedFile = {
file_id: 'blocked-file',
@@ -1376,7 +1408,7 @@ describe('initializeAgent — attachment scoping', () => {
(db.getConvoFiles as jest.Mock).mockResolvedValueOnce([blockedFile.file_id]);
(db.getToolFilesByIds as jest.Mock).mockResolvedValueOnce([blockedFile]);
(db.getFiles as jest.Mock).mockResolvedValueOnce([blockedFile]);
- filterFilesByEndpointConfig.mockImplementationOnce(
+ filterFilesByEndpointRuntimeConfig.mockImplementationOnce(
(_req: ServerRequest, { files }: { files: IMongoFile[] }) => files,
);
diff --git a/packages/api/src/agents/index.ts b/packages/api/src/agents/index.ts
index 3f3d9cfa95..f33d702b4b 100644
--- a/packages/api/src/agents/index.ts
+++ b/packages/api/src/agents/index.ts
@@ -49,6 +49,7 @@ export * from './skillConfigurable';
export * from './skillFiles';
export * from './codeFilesSession';
export * from './run';
+export * from './runtime';
export * from './testHook';
export * from './tools';
export * from './validation';
diff --git a/packages/api/src/agents/initialize.ts b/packages/api/src/agents/initialize.ts
index b12605556f..369983520f 100644
--- a/packages/api/src/agents/initialize.ts
+++ b/packages/api/src/agents/initialize.ts
@@ -48,6 +48,7 @@ import type { SkillContentInput } from '../protection/adapters/submissions';
import type { TextContentFragment } from '../protection/types';
import type { TFilterFilesByAgentAccess } from './resources';
import type { MCPToolAlias } from '~/tools/classification';
+import type { AgentExecutionContext } from './runtime';
import {
injectSkillCatalog,
resolveSkillCatalog,
@@ -94,9 +95,10 @@ import { assertModelBoundContent } from '../middleware/modelBoundContent';
import { registerMemoryTools, memoryToolUsageGuard } from './memory';
import { applyIntentLabels, sanitizeIntentLabels } from './intent';
import { ContentFilterError } from '../middleware/contentFilter';
+import { createRequestAgentExecutionContext } from './runtime';
+import { filterFilesByEndpointRuntimeConfig } from '~/files';
import { PARTIAL_RESOLVED_CONVERSATION } from './guard';
import { applyBackgroundToolCalls } from './background';
-import { filterFilesByEndpointConfig } from '~/files';
import { generateArtifactsPrompt } from '~/prompts';
import { getProviderConfig } from '~/endpoints';
import { primeResources } from './resources';
@@ -195,13 +197,13 @@ function appendAdditionalInstructions(agent: Agent, text?: string | null): void
* partial from a bound agent-event continuation cannot speak for the database.
*/
export function readResolvedConversationFiles(
- req: Pick<ServerRequest, 'resolvedConversation'>,
+ runtime: Pick<AgentExecutionContext, 'resolvedConversation'>,
conversationId: string,
): string[] | undefined {
- if (!Object.prototype.hasOwnProperty.call(req, 'resolvedConversation')) {
+ if (!Object.prototype.hasOwnProperty.call(runtime, 'resolvedConversation')) {
return undefined;
}
- const resolved = req.resolvedConversation;
+ const resolved = runtime.resolvedConversation;
if (resolved === null) {
return [];
}
@@ -215,8 +217,8 @@ export function readResolvedConversationFiles(
return resolved.files ?? [];
}
-function getMaxCatalogSkills(req: ServerRequest): number | undefined {
- const endpoints = req.config?.endpoints as
+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;
@@ -514,10 +516,12 @@ export const DEFAULT_MAX_CONTEXT_TOKENS = 32000;
* Matches the CJS signature from api/server/services/Endpoints/agents/agent.js
*/
export interface InitializeAgentParams {
- /** Request object */
- req: ServerRequest;
- /** Response object */
- res: ServerResponse;
+ /** 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) */
@@ -530,8 +534,6 @@ export interface InitializeAgentParams {
requestFiles?: IMongoFile[];
/** Function to load agent tools */
loadTools?: (params: {
- req: ServerRequest;
- res: ServerResponse;
provider: string;
agentId: string;
tools: string[];
@@ -717,8 +719,6 @@ export async function initializeAgent(
db?: InitializeAgentDbMethods,
): Promise<InitializedAgent> {
const {
- req,
- res,
agent,
loadTools,
requestFiles = [],
@@ -729,9 +729,15 @@ export async function initializeAgent(
allowedProviders,
isInitialAgent = false,
} = params;
- const requestFileOwnerId = req.user?.id;
+ const runtime =
+ params.runtime ?? (params.req ? createRequestAgentExecutionContext(params.req) : null);
+ if (runtime == null) {
+ throw new Error('initializeAgent requires an explicit execution context');
+ }
+ const { user, appConfig } = runtime;
+ const requestFileOwnerId = user?.id;
const requestFileOwnerScope: FileOwnerScope | undefined = requestFileOwnerId
- ? { userId: requestFileOwnerId, tenantId: req.user?.tenantId }
+ ? { userId: requestFileOwnerId, tenantId: user?.tenantId }
: undefined;
if (!db) {
@@ -758,7 +764,7 @@ export async function initializeAgent(
agentTraversalError = error;
}
const agentDefinitionFinding = inspectContent(agentFragments, {
- filters: req.config?.filters,
+ filters: appConfig?.filters,
});
if (agentDefinitionFinding != null) {
throw new ContentFilterError(agentDefinitionFinding);
@@ -767,7 +773,7 @@ export async function initializeAgent(
agentTraversalError != null &&
isContentTraversalProtected({
error: agentTraversalError,
- filters: req.config?.filters,
+ filters: appConfig?.filters,
})
) {
throw agentTraversalError;
@@ -782,7 +788,7 @@ export async function initializeAgent(
* defer/programmatic classification, the background and intent passes —
* reads `agent.tools` / `agent.tool_options` after this point.
*/
- const configRawServerNames = Object.keys(req.config?.mcpConfig ?? {});
+ const configRawServerNames = Object.keys(appConfig?.mcpConfig ?? {});
const configNeedsNormalization = configRawServerNames.some(
(name) => normalizeServerName(name) !== name,
);
@@ -806,7 +812,7 @@ export async function initializeAgent(
return Promise.resolve(null);
}
healNamesPromise ??= db
- .getAccessibleMcpServerNames(req.user?.id, req.user?.role)
+ .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. */
@@ -874,7 +880,7 @@ export async function initializeAgent(
names: params.manualSkills,
getSkillByName: db.getSkillByName,
accessibleSkillIds: params.accessibleSkillIds!,
- userId: req.user?.id,
+ userId: user?.id,
skillStates: params.skillStates,
defaultActiveOnShare: params.defaultActiveOnShare,
})
@@ -883,19 +889,19 @@ export async function initializeAgent(
? resolveAlwaysApplySkills({
listAlwaysApplySkills: db.listAlwaysApplySkills,
accessibleSkillIds: params.accessibleSkillIds!,
- userId: req.user?.id,
+ userId: user?.id,
skillStates: params.skillStates,
defaultActiveOnShare: params.defaultActiveOnShare,
})
: Promise.resolve<ResolvedAlwaysApplySkill[] | undefined>(undefined),
- hasActivePiiFields(req.config?.filters?.skills?.pii, ['name', 'description'])
+ hasActivePiiFields(appConfig?.filters?.skills?.pii, ['name', 'description'])
? resolveSkillCatalog({
accessibleSkillIds: params.accessibleSkillIds!,
listSkillsByAccess: db.listSkillsByAccess,
- userId: req.user?.id,
+ userId: user?.id,
skillStates: params.skillStates,
defaultActiveOnShare: params.defaultActiveOnShare,
- maxCatalogSkills: getMaxCatalogSkills(req),
+ maxCatalogSkills: getMaxCatalogSkills(runtime),
})
: Promise.resolve<ResolvedSkillCatalog | undefined>(undefined),
]);
@@ -930,7 +936,7 @@ export async function initializeAgent(
(skill) => skill.disableModelInvocation !== true,
) ?? []),
],
- req.config?.filters,
+ appConfig?.filters,
);
}
@@ -964,7 +970,7 @@ export async function initializeAgent(
if (effectiveStatefulSessions) {
const allowedStatefulCodeEnvironments = resolveAllowedStatefulCodeEnvironments(
params.allowedStatefulCodeEnvironments ??
- req.config?.endpoints?.[EModelEndpoint.agents]?.statefulCodeSessions?.allowedEnvironments,
+ appConfig?.endpoints?.[EModelEndpoint.agents]?.statefulCodeSessions?.allowedEnvironments,
);
if (!allowedStatefulCodeEnvironments.includes(statefulCodeEnvironment)) {
throw createStatefulCodeEnvironmentPolicyError(statefulCodeEnvironment);
@@ -1023,7 +1029,7 @@ export async function initializeAgent(
* every code-output ref.
*/
const [convoFileIds, threadMessages] = await Promise.all([
- readResolvedConversationFiles(req, conversationId) ?? db.getConvoFiles(conversationId),
+ readResolvedConversationFiles(runtime, conversationId) ?? db.getConvoFiles(conversationId),
needsThreadWalk && getThreadMessages
? getThreadMessages({ conversationId }, 'messageId parentMessageId files attachments')
: null,
@@ -1131,7 +1137,7 @@ export async function initializeAgent(
endpointType = EModelEndpoint.custom;
}
- currentFiles = filterFilesByEndpointConfig(req, {
+ currentFiles = filterFilesByEndpointRuntimeConfig(appConfig, {
files: currentFiles,
endpoint: agent.endpoint ?? '',
endpointType,
@@ -1139,7 +1145,7 @@ export async function initializeAgent(
}
assertModelBoundContent({
- filters: req.config?.filters,
+ filters: appConfig?.filters,
files: currentFiles,
});
@@ -1152,13 +1158,13 @@ export async function initializeAgent(
if (requestFileOwnerId && requestUsageFiles.length > 0) {
await db.updateFilesUsage(requestUsageFiles, undefined, {
user: requestFileOwnerId,
- tenantId: req.user?.tenantId,
+ tenantId: user?.tenantId,
});
}
if (requestFileOwnerId && toolUsageFiles.length > 0) {
await db.updateFilesUsage(toolUsageFiles, undefined, {
user: requestFileOwnerId,
- tenantId: req.user?.tenantId,
+ tenantId: user?.tenantId,
});
}
@@ -1168,10 +1174,10 @@ export async function initializeAgent(
agentContextAttachments: primedAgentContextAttachments,
tool_resources,
} = await primeResources({
- req: req as never,
+ principal: user,
getFiles: db.getFiles as never,
filterFiles: db.filterFilesByAgentAccess,
- appConfig: req.config,
+ appConfig,
agentId: agent.id,
attachments: currentFiles
? (Promise.resolve(currentFiles) as unknown as Promise<TFile[]>)
@@ -1264,8 +1270,6 @@ export async function initializeAgent(
*/
const callLoadTools = async (tools: string[]) =>
loadTools?.({
- req,
- res,
provider,
agentId: agent.id,
tools,
@@ -1358,7 +1362,7 @@ export async function initializeAgent(
const { getOptions, overrideProvider, customEndpointConfig } = getProviderConfig({
provider,
- appConfig: req.config,
+ appConfig,
});
if (overrideProvider !== agent.provider) {
agent.provider = overrideProvider;
@@ -1370,7 +1374,11 @@ export async function initializeAgent(
};
const options: InitializeResultBase = await getOptions({
- req,
+ runtime: {
+ appConfig,
+ user,
+ requestBody: runtime.requestBody,
+ },
endpoint: provider,
model_parameters: finalModelOptions,
db,
@@ -1487,7 +1495,7 @@ export async function initializeAgent(
const memoryResult = registerMemoryTools({
toolRegistry,
toolDefinitions,
- validKeys: req.config?.memory?.validKeys,
+ validKeys: appConfig?.memory?.validKeys,
});
toolDefinitions = memoryResult.toolDefinitions;
recordCapabilityToolNames(AgentCapabilities.memory, memoryResult.toolNames);
@@ -1544,7 +1552,7 @@ export async function initializeAgent(
* 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(req.config?.mcpConfig ?? {})) {
+ for (const [serverName, serverConfig] of Object.entries(appConfig?.mcpConfig ?? {})) {
if (serverConfig != null && requiresEphemeralUserConnection(serverConfig)) {
ephemeralServerNames.add(normalizeServerName(serverName));
}
@@ -1552,7 +1560,7 @@ export async function initializeAgent(
/** 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(req.config?.mcpConfig ?? {}).map(normalizeServerName);
+ const allServerNames = Object.keys(appConfig?.mcpConfig ?? {}).map(normalizeServerName);
const oauthActionNames = new Set(oauthActionToolNames ?? []);
const backgroundResult = applyBackgroundToolCalls({
toolDefinitions,
@@ -1625,9 +1633,9 @@ export async function initializeAgent(
if (agent.instructions && agent.instructions !== '') {
const resolvedInstructions = replaceSpecialVars({
text: agent.instructions,
- user: req.user ? (req.user as unknown as TUser) : null,
- now: req.conversationCreatedAt,
- timezone: req.body?.timezone,
+ user: user ? (user as unknown as TUser) : null,
+ now: runtime.conversationCreatedAt,
+ timezone: runtime.requestBody.timezone,
});
if (hasTemporalSpecialVars(agent.instructions)) {
agent.instructions = undefined;
@@ -1665,10 +1673,10 @@ export async function initializeAgent(
listSkillsByAccess: db?.listSkillsByAccess,
codeEnvAvailable: effectiveCodeEnvAvailable,
statefulSessions: effectiveStatefulSessions,
- userId: req.user?.id,
+ userId: user?.id,
skillStates: params.skillStates,
defaultActiveOnShare: params.defaultActiveOnShare,
- maxCatalogSkills: getMaxCatalogSkills(req),
+ maxCatalogSkills: getMaxCatalogSkills(runtime),
resolvedCatalog: resolvedSkillCatalog,
});
toolDefinitions = skillResult.toolDefinitions;
@@ -1748,7 +1756,7 @@ export async function initializeAgent(
? finalAttachments
: requestAttachments.concat(agentContextAttachments);
- const endpointConfigs = req.config?.endpoints;
+ const endpointConfigs = appConfig?.endpoints;
const providerConfig =
customEndpointConfig ?? endpointConfigs?.[agent.provider as keyof typeof endpointConfigs];
const providerMaxToolResultChars =
diff --git a/packages/api/src/agents/openai/service.spec.ts b/packages/api/src/agents/openai/service.spec.ts
index 541c37c841..a1f7a25dba 100644
--- a/packages/api/src/agents/openai/service.spec.ts
+++ b/packages/api/src/agents/openai/service.spec.ts
@@ -141,6 +141,57 @@ describe('createAgentChatCompletion - MCP permission user propagation', () => {
expect(streamConfig.configurable?.user).not.toHaveProperty('role');
});
+ it('adapts runtime tool loading to the request-backed public dependency', async () => {
+ const req = createMockReq({ id: 'user-123', role: 'USER' });
+ const res = createMockRes();
+ const loadAgentTools = jest.fn().mockResolvedValue({
+ tools: [],
+ toolContextMap: {},
+ });
+ deps.loadAgentTools = loadAgentTools;
+ (deps.initializeAgent as jest.Mock).mockImplementation(
+ async ({
+ loadTools,
+ }: {
+ loadTools?: (params: Record<string, unknown>) => Promise<unknown>;
+ }) => {
+ await loadTools?.({
+ provider: 'openai',
+ agentId: 'agent_test',
+ tools: ['tool-a'],
+ model: 'gpt-4o-mini',
+ tool_options: undefined,
+ tool_resources: undefined,
+ requestBody: { conversationId: 'conversation-123' },
+ codeExecutionContext: { endpoint: 'openai' },
+ });
+ return {
+ id: 'agent_test',
+ provider: 'openai',
+ model: 'gpt-4o-mini',
+ tools: [],
+ attachments: [],
+ toolContextMap: {},
+ maxContextTokens: 1000,
+ model_parameters: {},
+ };
+ },
+ );
+
+ await createAgentChatCompletion(req, res, deps);
+
+ expect(loadAgentTools).toHaveBeenCalledWith(
+ expect.objectContaining({
+ req,
+ res,
+ provider: 'openai',
+ agentId: 'agent_test',
+ tools: ['tool-a'],
+ codeExecutionContext: { endpoint: 'openai' },
+ }),
+ );
+ });
+
it('threads the parent message id into the run and execution context', async () => {
const req = createMockReq({ id: 'user-123', role: 'USER' }) as unknown as {
body: Record<string, unknown>;
diff --git a/packages/api/src/agents/openai/service.ts b/packages/api/src/agents/openai/service.ts
index 9fb817e7ad..11cce34216 100644
--- a/packages/api/src/agents/openai/service.ts
+++ b/packages/api/src/agents/openai/service.ts
@@ -43,6 +43,7 @@ import type {
TextContentFragment,
FileContentInput,
} from '~/protection';
+import type { InitializeAgentParams as CoreInitializeAgentParams } from '../initialize';
import type { OpenAIStreamHandlerConfig, EventHandler } from './handlers';
import type { MCPRuntimeRequestBody } from '~/mcp/request';
import type { ToolExecuteOptions } from '../handlers';
@@ -185,7 +186,7 @@ interface InitializeAgentParams {
parentMessageId?: string | null;
requestBody?: MCPRuntimeRequestBody;
requestFiles?: unknown[];
- loadTools?: LoadToolsFn;
+ loadTools?: NonNullable<CoreInitializeAgentParams['loadTools']>;
endpointOption?: Record<string, unknown>;
allowedProviders: Set<string>;
isInitialAgent?: boolean;
@@ -691,6 +692,17 @@ export async function createAgentChatCompletion(
const backgroundToolsAvailable = capabilityEnabled(AgentCapabilities.run_in_background);
/** Same gate for the injected `intent` label param. */
const toolIntentsAvailable = capabilityEnabled(AgentCapabilities.tool_intents);
+ const loadTools: InitializeAgentParams['loadTools'] = deps.loadAgentTools
+ ? async (params) => {
+ const result = await deps.loadAgentTools!({
+ req,
+ res,
+ ...params,
+ requestBody: mcpRequestBody,
+ });
+ return result as Awaited<ReturnType<NonNullable<CoreInitializeAgentParams['loadTools']>>>;
+ }
+ : undefined;
// Initialize the agent first to check for disableStreaming
const initializedAgent = await deps.initializeAgent({
@@ -700,7 +712,7 @@ export async function createAgentChatCompletion(
conversationId,
parentMessageId: request.parent_message_id,
requestBody: mcpRequestBody,
- loadTools: deps.loadAgentTools,
+ loadTools,
endpointOption: {
endpoint: agent.provider,
model_parameters: agent.model_parameters ?? {},
diff --git a/packages/api/src/agents/remote/host.spec.ts b/packages/api/src/agents/remote/host.spec.ts
new file mode 100644
index 0000000000..b327a0aaef
--- /dev/null
+++ b/packages/api/src/agents/remote/host.spec.ts
@@ -0,0 +1,151 @@
+import type { ChatCompletionRunEnvelope } from '../envelope';
+import type { AgentExecutionConnection } from './host';
+import { GenerationJobManager } from '~/stream';
+import { executeAgentRun } from './host';
+
+jest.mock('~/stream', () => ({
+ GenerationJobManager: {
+ createJob: jest.fn(),
+ beginProviderExecution: jest.fn(),
+ completeJob: jest.fn(),
+ markProviderExecutionDrained: jest.fn(),
+ },
+}));
+
+const manager = GenerationJobManager as jest.Mocked<typeof GenerationJobManager>;
+
+function createEnvelope(): ChatCompletionRunEnvelope {
+ return {
+ version: 1,
+ protocol: 'chat.completions',
+ requestId: 'request-1',
+ receivedAt: 1,
+ principal: { userId: 'user-1' },
+ payload: {
+ model: 'agent-1',
+ messages: [{ role: 'user', content: 'hello' }],
+ },
+ };
+}
+
+describe('executeAgentRun', () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ manager.createJob.mockResolvedValue({
+ streamId: 'run-1',
+ createdAt: 10,
+ status: 'running',
+ abortController: new AbortController(),
+ metadata: { providerExecutionId: 'provider-1' },
+ } as never);
+ manager.beginProviderExecution.mockResolvedValue(true);
+ manager.completeJob.mockResolvedValue(true);
+ manager.markProviderExecutionDrained.mockResolvedValue(true);
+ });
+
+ it('executes and settles from an envelope without HTTP request or response objects', async () => {
+ const execute = jest.fn(async () => 'done');
+
+ await expect(
+ executeAgentRun({
+ envelope: createEnvelope(),
+ runId: 'run-1',
+ conversationId: 'conversation-1',
+ isPrincipalActive: async () => true,
+ execute,
+ }),
+ ).resolves.toBe('done');
+
+ expect(execute).toHaveBeenCalledWith(expect.objectContaining({ runId: 'run-1' }));
+ expect(manager.completeJob).toHaveBeenCalledWith('run-1', undefined, 10);
+ expect(manager.markProviderExecutionDrained).toHaveBeenCalledWith('run-1', 10, 'provider-1');
+ });
+
+ it('aborts the enrolled run when the transport closes', async () => {
+ let closeListener: (() => void) | undefined;
+ const connection: AgentExecutionConnection = {
+ isClosed: () => false,
+ onClose: (listener) => {
+ closeListener = listener;
+ return () => {
+ closeListener = undefined;
+ };
+ },
+ };
+
+ await executeAgentRun({
+ envelope: createEnvelope(),
+ runId: 'run-1',
+ conversationId: 'conversation-1',
+ connection,
+ isPrincipalActive: async () => true,
+ execute: async (execution) => {
+ closeListener?.();
+ expect(execution.signal.aborted).toBe(true);
+ },
+ });
+ });
+
+ it('settles failed execution with terminal error evidence', async () => {
+ const failure = new Error('provider failed');
+
+ await expect(
+ executeAgentRun({
+ envelope: createEnvelope(),
+ runId: 'run-1',
+ conversationId: 'conversation-1',
+ isPrincipalActive: async () => true,
+ execute: async () => {
+ throw failure;
+ },
+ }),
+ ).rejects.toBe(failure);
+
+ expect(manager.completeJob).toHaveBeenCalledWith('run-1', 'Remote agent execution failed', 10);
+ });
+
+ it('renders an execution error before terminal settlement', async () => {
+ const events: string[] = [];
+ manager.completeJob.mockImplementation(async () => {
+ events.push('settled');
+ return true;
+ });
+
+ await expect(
+ executeAgentRun({
+ envelope: createEnvelope(),
+ runId: 'run-1',
+ conversationId: 'conversation-1',
+ isPrincipalActive: async () => true,
+ execute: async () => {
+ throw new Error('provider failed');
+ },
+ handleExecutionError: () => {
+ events.push('rendered');
+ return 'handled';
+ },
+ }),
+ ).resolves.toBe('handled');
+
+ expect(events).toEqual(['rendered', 'settled']);
+ });
+
+ it('settles even when trailing-write registration fails', async () => {
+ const failure = new Error('trailing write registration failed');
+
+ await expect(
+ executeAgentRun({
+ envelope: createEnvelope(),
+ runId: 'run-1',
+ conversationId: 'conversation-1',
+ isPrincipalActive: async () => true,
+ execute: async () => 'done',
+ beforeSettle: async () => {
+ throw failure;
+ },
+ }),
+ ).resolves.toBe('done');
+
+ expect(manager.completeJob).toHaveBeenCalledWith('run-1', 'Remote agent execution failed', 10);
+ });
+});
diff --git a/packages/api/src/agents/remote/host.ts b/packages/api/src/agents/remote/host.ts
new file mode 100644
index 0000000000..1522a2a139
--- /dev/null
+++ b/packages/api/src/agents/remote/host.ts
@@ -0,0 +1,85 @@
+import type { AgentExecutionEnrollment } from './lifecycle';
+import type { AgentRunEnvelope } from '../envelope';
+import { enrollAgentExecution } from './lifecycle';
+
+/** Transport connection observed by the execution host for cancellation only. */
+export interface AgentExecutionConnection {
+ isClosed: () => boolean;
+ onClose: (listener: () => void) => () => void;
+}
+
+export interface ExecuteAgentRunParams<Result> {
+ envelope: AgentRunEnvelope;
+ runId: string;
+ conversationId: string;
+ connection?: AgentExecutionConnection;
+ isPrincipalActive: (userId: string) => Promise<boolean>;
+ execute: (execution: AgentExecutionEnrollment) => Promise<Result>;
+ handleExecutionError?: (error: unknown) => Result | Promise<Result>;
+ beforeSettle?: (
+ execution: AgentExecutionEnrollment,
+ executionError: unknown,
+ ) => void | Promise<void>;
+ onSettlementError?: (error: unknown) => void;
+}
+
+/**
+ * Owns admission, cancellation, provider-start fencing, and settlement for a
+ * validated Agent run. Protocol implementations own only execution semantics;
+ * ingress adapters own transport validation and final rendering.
+ */
+export async function executeAgentRun<Result>({
+ envelope,
+ runId,
+ conversationId,
+ connection,
+ isPrincipalActive,
+ execute,
+ handleExecutionError,
+ beforeSettle,
+ onSettlementError,
+}: ExecuteAgentRunParams<Result>): Promise<Result> {
+ const agentId = envelope.payload.model;
+ let execution: AgentExecutionEnrollment | undefined;
+ let executionError: unknown;
+ let responseClosed = connection?.isClosed() ?? false;
+ const removeCloseListener =
+ connection?.onClose(() => {
+ responseClosed = true;
+ execution?.abort();
+ }) ?? (() => undefined);
+
+ try {
+ execution = await enrollAgentExecution({
+ runId,
+ userId: envelope.principal.userId,
+ conversationId,
+ agentId,
+ protocol: envelope.protocol,
+ isPrincipalActive,
+ });
+ if (responseClosed || connection?.isClosed() === true) {
+ execution.abort();
+ }
+ await execution.beginProviderExecution();
+ return await execute(execution);
+ } catch (error) {
+ executionError = error;
+ if (handleExecutionError != null) {
+ return await handleExecutionError(error);
+ }
+ throw error;
+ } finally {
+ removeCloseListener();
+ if (execution != null) {
+ try {
+ await beforeSettle?.(execution, executionError);
+ } catch (error) {
+ executionError ??= error;
+ }
+ await execution.settle(executionError).catch((error: unknown) => {
+ onSettlementError?.(error);
+ });
+ }
+ }
+}
diff --git a/packages/api/src/agents/remote/index.ts b/packages/api/src/agents/remote/index.ts
index b55497afb2..a4ca0ed9e8 100644
--- a/packages/api/src/agents/remote/index.ts
+++ b/packages/api/src/agents/remote/index.ts
@@ -1 +1,2 @@
export * from './lifecycle';
+export * from './host';
diff --git a/packages/api/src/agents/resources.ts b/packages/api/src/agents/resources.ts
index c66f51bbca..e1260276c6 100644
--- a/packages/api/src/agents/resources.ts
+++ b/packages/api/src/agents/resources.ts
@@ -175,6 +175,7 @@ const categorizeFileForToolResources = ({
*/
export const primeResources = async ({
req,
+ principal,
appConfig,
getFiles,
filterFiles,
@@ -183,7 +184,8 @@ export const primeResources = async ({
tool_resources: _tool_resources,
agentId,
}: {
- req: ServerRequest & { user?: IUser };
+ req?: ServerRequest & { user?: IUser };
+ principal?: Pick<IUser, 'id' | 'role'>;
appConfig?: AppConfig;
requestFileSet: Set<string>;
attachments: Promise<Array<TFile | null>> | undefined;
@@ -197,6 +199,7 @@ export const primeResources = async ({
agentContextAttachments: Array<TFile | undefined> | undefined;
tool_resources: AgentToolResources | undefined;
}> => {
+ const resourcePrincipal = principal ?? req?.user;
const requestAttachments: Array<TFile> = [];
const agentContextAttachments: Array<TFile> = [];
const persistedToolResources = sanitizePersistedToolResources(_tool_resources);
@@ -287,11 +290,11 @@ export const primeResources = async ({
{},
);
- if (filterFiles && req.user?.id && agentId) {
+ if (filterFiles && resourcePrincipal?.id && agentId) {
persistedResourceFiles = await filterFiles({
files: persistedResourceFiles,
- userId: req.user.id,
- role: req.user.role,
+ userId: resourcePrincipal.id,
+ role: resourcePrincipal.role,
agentId,
});
}
diff --git a/packages/api/src/agents/runtime.ts b/packages/api/src/agents/runtime.ts
new file mode 100644
index 0000000000..d43f08c4f9
--- /dev/null
+++ b/packages/api/src/agents/runtime.ts
@@ -0,0 +1,62 @@
+import type { AppConfig, IConversation, IUser } from '@librechat/data-schemas';
+import type { RequestBody, ServerRequest } from '~/types';
+
+/**
+ * Runtime-only state required to initialize and execute an Agent run.
+ *
+ * This context deliberately contains no transport objects. Ingress adapters
+ * may derive it from HTTP, while future execution hosts can rehydrate it from
+ * an authenticated principal and deployment configuration.
+ */
+export interface AgentExecutionContext {
+ user?: IUser;
+ appConfig?: AppConfig;
+ requestBody: RequestBody;
+ /** Server-captured conversation creation time used by prompt variables. */
+ conversationCreatedAt?: string;
+ /** Conversation already resolved by ingress. Presence distinguishes "not read" from absent. */
+ resolvedConversation?: Partial<IConversation> | null;
+}
+
+/** Creates the transport-free context at the existing HTTP adapter seam. */
+export function createAgentExecutionContext({
+ user,
+ appConfig,
+ requestBody,
+ conversationCreatedAt,
+ resolvedConversation,
+ hasResolvedConversation = false,
+}: {
+ user?: IUser;
+ appConfig?: AppConfig;
+ requestBody: RequestBody;
+ conversationCreatedAt?: string;
+ resolvedConversation?: Partial<IConversation> | null;
+ hasResolvedConversation?: boolean;
+}): AgentExecutionContext {
+ const context: AgentExecutionContext = {
+ user,
+ appConfig,
+ requestBody,
+ conversationCreatedAt,
+ };
+ if (hasResolvedConversation) {
+ context.resolvedConversation = resolvedConversation ?? null;
+ }
+ return context;
+}
+
+/** Temporary adapter for request-backed Agent entry points. */
+export function createRequestAgentExecutionContext(
+ req: ServerRequest,
+ requestBody: RequestBody = req.body ?? {},
+): AgentExecutionContext {
+ return createAgentExecutionContext({
+ user: req.user,
+ appConfig: req.config,
+ requestBody,
+ conversationCreatedAt: req.conversationCreatedAt,
+ resolvedConversation: req.resolvedConversation,
+ hasResolvedConversation: Object.prototype.hasOwnProperty.call(req, 'resolvedConversation'),
+ });
+}
diff --git a/packages/api/src/endpoints/anthropic/initialize.ts b/packages/api/src/endpoints/anthropic/initialize.ts
index 232ff80405..8a8ece5754 100644
--- a/packages/api/src/endpoints/anthropic/initialize.ts
+++ b/packages/api/src/endpoints/anthropic/initialize.ts
@@ -1,7 +1,12 @@
import { EModelEndpoint, AuthKeys } from 'librechat-data-provider';
-import type { BaseInitializeParams, InitializeResultBase, AnthropicConfigOptions } from '~/types';
+import type {
+ InitializeResultBase,
+ AnthropicConfigOptions,
+ ProviderInitializeParams,
+} from '~/types';
import { loadAnthropicVertexCredentials, getVertexCredentialOptions } from './vertex';
import { checkUserKeyExpiry, isEnabled, mergeHeaders } from '~/utils';
+import { resolveEndpointRuntime } from '~/types';
import { getLLMConfig } from './llm';
/**
@@ -12,16 +17,14 @@ import { getLLMConfig } from './llm';
* @returns Promise resolving to Anthropic configuration options
* @throws Error if API key is not provided (when not using Vertex AI)
*/
-export async function initializeAnthropic({
- req,
- endpoint,
- model_parameters,
- db,
-}: BaseInitializeParams): Promise<InitializeResultBase> {
+export async function initializeAnthropic(
+ params: ProviderInitializeParams,
+): Promise<InitializeResultBase> {
+ const { endpoint, model_parameters, db } = params;
+ const { appConfig, user, requestBody } = resolveEndpointRuntime(params);
void endpoint;
- const appConfig = req.config;
const { ANTHROPIC_API_KEY, ANTHROPIC_REVERSE_PROXY, PROXY } = process.env;
- const { key: expiresAt } = req.body;
+ const { key: expiresAt } = requestBody;
let credentials: Record<string, unknown> = {};
let vertexOptions: { region?: string; projectId?: string } | undefined;
@@ -50,7 +53,7 @@ export async function initializeAnthropic({
const isUserProvided = ANTHROPIC_API_KEY === 'user_provided';
const anthropicApiKey = isUserProvided
- ? await db.getUserKey({ userId: req.user?.id ?? '', name: EModelEndpoint.anthropic })
+ ? await db.getUserKey({ userId: user?.id ?? '', name: EModelEndpoint.anthropic })
: ANTHROPIC_API_KEY;
if (!anthropicApiKey) {
@@ -74,7 +77,7 @@ export async function initializeAnthropic({
reverseProxyUrl: ANTHROPIC_REVERSE_PROXY ?? undefined,
modelOptions: {
...(model_parameters ?? {}),
- user: req.user?.id,
+ user: user?.id,
},
...(headers && { headers }),
// Pass Vertex AI options if configured
diff --git a/packages/api/src/endpoints/bedrock/initialize.ts b/packages/api/src/endpoints/bedrock/initialize.ts
index 7686da24dd..7ac7ccf947 100644
--- a/packages/api/src/endpoints/bedrock/initialize.ts
+++ b/packages/api/src/endpoints/bedrock/initialize.ts
@@ -11,13 +11,14 @@ import {
} from 'librechat-data-provider';
import type { BedrockRuntimeClientConfig } from '@aws-sdk/client-bedrock-runtime';
import type {
- BaseInitializeParams,
InitializeResultBase,
BedrockCredentials,
GuardrailConfiguration,
InferenceProfileConfig,
+ ProviderInitializeParams,
} from '~/types';
import { getHttpsProxyAgent } from '~/utils/proxy';
+import { resolveEndpointRuntime } from '~/types';
import { checkUserKeyExpiry } from '~/utils';
const BEDROCK_CREDENTIALS_ERROR = 'Bedrock credentials not provided. Please provide them again.';
@@ -104,14 +105,12 @@ function getUserCredentialValue(
* @returns Promise resolving to Bedrock configuration options
* @throws Error if credentials are not provided when required
*/
-export async function initializeBedrock({
- req,
- endpoint,
- model_parameters,
- db,
-}: BaseInitializeParams): Promise<InitializeResultBase> {
+export async function initializeBedrock(
+ params: ProviderInitializeParams,
+): Promise<InitializeResultBase> {
+ const { endpoint, model_parameters, db } = params;
+ const { appConfig, user, requestBody } = resolveEndpointRuntime(params);
void endpoint;
- const appConfig = req.config;
const bedrockConfig = appConfig?.endpoints?.[EModelEndpoint.bedrock] as
| ({
guardrailConfig?: GuardrailConfiguration;
@@ -129,7 +128,7 @@ export async function initializeBedrock({
BEDROCK_AWS_DEFAULT_REGION,
} = process.env;
- const { key: expiresAt } = req.body;
+ const { key: expiresAt } = requestBody;
const userProvidesAccessKeyId = BEDROCK_AWS_ACCESS_KEY_ID === AuthType.USER_PROVIDED;
const userProvidesSecretAccessKey = BEDROCK_AWS_SECRET_ACCESS_KEY === AuthType.USER_PROVIDED;
const userProvidesSessionToken = BEDROCK_AWS_SESSION_TOKEN === AuthType.USER_PROVIDED;
@@ -154,7 +153,7 @@ export async function initializeBedrock({
if (isUserProvided) {
const userKey = await db.getUserKey({
- userId: req.user?.id ?? '',
+ userId: user?.id ?? '',
name: EModelEndpoint.bedrock,
});
diff --git a/packages/api/src/endpoints/config/providers.ts b/packages/api/src/endpoints/config/providers.ts
index 0ad90143cf..642007c668 100644
--- a/packages/api/src/endpoints/config/providers.ts
+++ b/packages/api/src/endpoints/config/providers.ts
@@ -2,7 +2,7 @@ import { Providers } from '@librechat/agents';
import { EModelEndpoint } from 'librechat-data-provider';
import type { TEndpoint } from 'librechat-data-provider';
import type { AppConfig } from '@librechat/data-schemas';
-import type { BaseInitializeParams, InitializeResultBase } from '~/types';
+import type { InitializeResultBase, ProviderInitializeParams } from '~/types';
import { resolveCustomEndpointSecrets } from '~/admin/secrets';
import { initializeAnthropic } from '../anthropic/initialize';
import { initializeBedrock } from '../bedrock/initialize';
@@ -14,7 +14,7 @@ import { getCustomEndpointConfig } from '~/app/config';
/**
* Type for initialize functions
*/
-export type InitializeFn = (params: BaseInitializeParams) => Promise<InitializeResultBase>;
+export type InitializeFn = (params: ProviderInitializeParams) => Promise<InitializeResultBase>;
/**
* Check if the provider is a known custom provider
diff --git a/packages/api/src/endpoints/custom/initialize.ts b/packages/api/src/endpoints/custom/initialize.ts
index a896ec6966..8966d4c9c2 100644
--- a/packages/api/src/endpoints/custom/initialize.ts
+++ b/packages/api/src/endpoints/custom/initialize.ts
@@ -9,10 +9,10 @@ import {
import type { TEndpoint } from 'librechat-data-provider';
import type { AppConfig } from '@librechat/data-schemas';
import type {
- BaseInitializeParams,
InitializeResultBase,
EndpointTokenConfig,
AnthropicModelOptions,
+ ProviderInitializeParams,
} from '~/types';
import { getLLMConfig as getAnthropicLLMConfig } from '~/endpoints/anthropic/llm';
import { extractDefaultParams } from '~/endpoints/openai/llm';
@@ -20,6 +20,7 @@ import { isUserProvided, checkUserKeyExpiry } from '~/utils';
import { getOpenAIConfig } from '~/endpoints/openai/config';
import { getScopedTokenConfigKey } from '~/endpoints/keys';
import { getCustomEndpointConfig } from '~/app/config';
+import { resolveEndpointRuntime } from '~/types';
import { fetchModels } from '~/endpoints/models';
import { validateEndpointURL } from '~/auth';
import { tokenConfigCache } from '~/cache';
@@ -173,14 +174,12 @@ function buildAnthropicCustomConfig({
* @returns Promise resolving to endpoint configuration options
* @throws Error if config is missing, API key is not provided, or base URL is missing
*/
-export async function initializeCustom({
- req,
- endpoint,
- model_parameters,
- db,
-}: BaseInitializeParams): Promise<InitializeResultBase> {
- const appConfig = req.config;
- const { key: expiresAt } = req.body;
+export async function initializeCustom(
+ params: ProviderInitializeParams,
+): Promise<InitializeResultBase> {
+ const { endpoint, model_parameters, db } = params;
+ const { appConfig, user, requestBody } = resolveEndpointRuntime(params);
+ const { key: expiresAt } = requestBody;
const endpointConfig = getCustomEndpointConfig({
endpoint,
@@ -214,7 +213,7 @@ export async function initializeCustom({
let userValues = null;
if (userProvidesKey || userProvidesURL) {
- userValues = await db.getUserKeyValues({ userId: req.user?.id ?? '', name: endpoint });
+ userValues = await db.getUserKeyValues({ userId: user?.id ?? '', name: endpoint });
}
const apiKey = userProvidesKey || userProvidesURL ? userValues?.apiKey : CUSTOM_API_KEY;
@@ -250,8 +249,8 @@ export async function initializeCustom({
let endpointTokenConfig: EndpointTokenConfig | undefined;
- const userId = req.user?.id ?? '';
- const tenantId = req.user?.tenantId;
+ const userId = user?.id ?? '';
+ const tenantId = user?.tenantId;
const cache = tokenConfigCache();
const hasTokenConfig = endpointConfig.tokenConfig != null;
@@ -286,7 +285,7 @@ export async function initializeCustom({
name: endpoint,
user: userId,
tokenKey,
- userObject: req.user,
+ userObject: user,
// Mirror the security guard in `loadConfigModels`: never forward
// header overrides when the base URL is user-supplied — configured
// templates like {{LIBRECHAT_OPENID_ID_TOKEN}} would otherwise resolve
diff --git a/packages/api/src/endpoints/google/initialize.ts b/packages/api/src/endpoints/google/initialize.ts
index 4543171875..94dc6654b3 100644
--- a/packages/api/src/endpoints/google/initialize.ts
+++ b/packages/api/src/endpoints/google/initialize.ts
@@ -2,10 +2,10 @@ import path from 'path';
import { Providers } from '@librechat/agents';
import { EModelEndpoint, AuthKeys } from 'librechat-data-provider';
import type {
- BaseInitializeParams,
InitializeResultBase,
GoogleConfigOptions,
GoogleCredentials,
+ ProviderInitializeParams,
} from '~/types';
import {
isEnabled,
@@ -14,6 +14,7 @@ import {
mergeHeaders,
resolveHeaders,
} from '~/utils';
+import { resolveEndpointRuntime } from '~/types';
import { getGoogleConfig } from './llm';
/**
@@ -24,23 +25,21 @@ import { getGoogleConfig } from './llm';
* @returns Promise resolving to Google configuration options
* @throws Error if no valid credentials are provided
*/
-export async function initializeGoogle({
- req,
- endpoint,
- model_parameters,
- db,
-}: BaseInitializeParams): Promise<InitializeResultBase> {
- const appConfig = req.config;
+export async function initializeGoogle(
+ params: ProviderInitializeParams,
+): Promise<InitializeResultBase> {
+ const { endpoint, model_parameters, db } = params;
+ const { appConfig, user, requestBody } = resolveEndpointRuntime(params);
const { GOOGLE_KEY, GOOGLE_REVERSE_PROXY, GOOGLE_AUTH_HEADER, PROXY } = process.env;
const isUserProvided = GOOGLE_KEY === 'user_provided';
const isVertexEndpoint = endpoint === Providers.VERTEXAI;
const useUserProvidedGoogleKey = !isVertexEndpoint && isUserProvided;
- const { key: expiresAt } = req.body;
+ const { key: expiresAt } = requestBody;
let userKey = null;
if (expiresAt && useUserProvidedGoogleKey) {
checkUserKeyExpiry(expiresAt, EModelEndpoint.google);
- userKey = await db.getUserKey({ userId: req.user?.id ?? '', name: EModelEndpoint.google });
+ userKey = await db.getUserKey({ userId: user?.id ?? '', name: EModelEndpoint.google });
}
let serviceKey: Record<string, unknown> = {};
@@ -95,15 +94,16 @@ export async function initializeGoogle({
* admin templates here — before that key-derived header is added — keeps the
* key out of placeholder/env expansion (a user-provided `${ENV}` key can't leak
* server env) while still resolving admin headers (env, user, conversationId).
- * `req.body` lacks the assistant message id at init, so `{{LIBRECHAT_BODY_MESSAGEID}}`
+ * The initialization request body lacks the assistant message id, so
+ * `{{LIBRECHAT_BODY_MESSAGEID}}`
* is the one body placeholder unavailable here.
*/
const mergedHeaders = mergeHeaders(allConfig?.headers, googleConfig?.headers);
const headers = mergedHeaders
? resolveHeaders({
headers: mergedHeaders,
- user: req.user,
- body: req.body,
+ user,
+ body: requestBody,
stripUnresolved: true,
})
: undefined;
diff --git a/packages/api/src/endpoints/openai/initialize.ts b/packages/api/src/endpoints/openai/initialize.ts
index 3423a87584..e662b20810 100644
--- a/packages/api/src/endpoints/openai/initialize.ts
+++ b/packages/api/src/endpoints/openai/initialize.ts
@@ -1,8 +1,8 @@
import { ErrorTypes, EModelEndpoint, mapModelToAzureConfig } from 'librechat-data-provider';
import type {
- BaseInitializeParams,
InitializeResultBase,
OpenAIConfigOptions,
+ ProviderInitializeParams,
UserKeyValues,
} from '~/types';
import {
@@ -12,6 +12,7 @@ import {
checkUserKeyExpiry,
getAzureCredentials,
} from '~/utils';
+import { resolveEndpointRuntime } from '~/types';
import { validateEndpointURL } from '~/auth';
import { getOpenAIConfig } from './config';
@@ -23,19 +24,17 @@ import { getOpenAIConfig } from './config';
* @returns Promise resolving to OpenAI configuration options
* @throws Error if API key is missing or user key has expired
*/
-export async function initializeOpenAI({
- req,
- endpoint,
- model_parameters,
- db,
-}: BaseInitializeParams): Promise<InitializeResultBase> {
- const appConfig = req.config;
+export async function initializeOpenAI(
+ params: ProviderInitializeParams,
+): Promise<InitializeResultBase> {
+ const { endpoint, model_parameters, db } = params;
+ const { appConfig, user, requestBody } = resolveEndpointRuntime(params);
const openAIConfig = appConfig?.endpoints?.[EModelEndpoint.openAI];
const allConfig = appConfig?.endpoints?.all;
const { PROXY, OPENAI_API_KEY, AZURE_API_KEY, OPENAI_REVERSE_PROXY, AZURE_OPENAI_BASEURL } =
process.env;
- const { key: expiresAt } = req.body;
+ const { key: expiresAt } = requestBody;
const modelName = model_parameters?.model as string | undefined;
const credentials = {
@@ -54,7 +53,7 @@ export async function initializeOpenAI({
let userValues: UserKeyValues | null = null;
if (expiresAt && (userProvidesKey || userProvidesURL)) {
checkUserKeyExpiry(expiresAt, endpoint);
- userValues = await db.getUserKeyValues({ userId: req.user?.id ?? '', name: endpoint });
+ userValues = await db.getUserKeyValues({ userId: user?.id ?? '', name: endpoint });
}
let apiKey = userProvidesKey
@@ -108,7 +107,7 @@ export async function initializeOpenAI({
}
clientOptions.headers = resolveHeaders({
headers: { ...headers, ...(clientOptions.headers ?? {}) },
- user: req.user,
+ user,
});
/** `endpoints.all` headers apply globally, but stay unresolved here — they are
* resolved once at request time by `resolveConfigHeaders`. Resolving them now
@@ -179,7 +178,7 @@ export async function initializeOpenAI({
const modelOptions = {
...(model_parameters ?? {}),
model: modelName,
- user: req.user?.id,
+ user: user?.id,
};
const finalClientOptions: OpenAIConfigOptions = {
diff --git a/packages/api/src/files/filter.ts b/packages/api/src/files/filter.ts
index 805aa94bc3..0e02315955 100644
--- a/packages/api/src/files/filter.ts
+++ b/packages/api/src/files/filter.ts
@@ -1,5 +1,5 @@
import { getEndpointFileConfig, mergeFileConfig, fileConfig } from 'librechat-data-provider';
-import type { IMongoFile } from '@librechat/data-schemas';
+import type { AppConfig, IMongoFile } from '@librechat/data-schemas';
import type { RegexLike } from 'librechat-data-provider';
import type { ServerRequest } from '~/types';
@@ -36,6 +36,18 @@ export function filterFilesByEndpointConfig(
endpoint?: string | null;
endpointType?: string | null;
},
+): IMongoFile[] {
+ return filterFilesByEndpointRuntimeConfig(req.config, params);
+}
+
+/** Request-free endpoint file-policy adapter used by Agent execution hosts. */
+export function filterFilesByEndpointRuntimeConfig(
+ appConfig: AppConfig | undefined,
+ params: {
+ files: IMongoFile[] | undefined;
+ endpoint?: string | null;
+ endpointType?: string | null;
+ },
): IMongoFile[] {
const { files, endpoint, endpointType } = params;
@@ -43,7 +55,7 @@ export function filterFilesByEndpointConfig(
return [];
}
- const mergedFileConfig = mergeFileConfig(req.config?.fileConfig);
+ const mergedFileConfig = mergeFileConfig(appConfig?.fileConfig);
const endpointFileConfig = getEndpointFileConfig({
fileConfig: mergedFileConfig,
endpoint,
diff --git a/packages/api/src/types/endpoints.ts b/packages/api/src/types/endpoints.ts
index 1071f43616..39f20eabb9 100644
--- a/packages/api/src/types/endpoints.ts
+++ b/packages/api/src/types/endpoints.ts
@@ -1,7 +1,8 @@
import type { ClientOptions, OpenAIClientOptions } from '@librechat/agents';
+import type { AppConfig, IUser } from '@librechat/data-schemas';
import type { TConfig } from 'librechat-data-provider';
+import type { RequestBody, ServerRequest } from './http';
import type { EndpointTokenConfig } from './tokens';
-import type { ServerRequest } from './http';
export type TCustomEndpointsConfig = Partial<{ [key: string]: Omit<TConfig, 'order'> }>;
@@ -37,12 +38,17 @@ export interface EndpointDbMethods {
getUserKeyValues: GetUserKeyValuesFunction;
}
+/** Transport-free state consumed while resolving provider credentials and configuration. */
+export interface EndpointRuntimeContext {
+ appConfig?: AppConfig;
+ user?: IUser;
+ requestBody: RequestBody;
+}
+
/**
* Base parameters for all endpoint initialization functions
*/
-export interface BaseInitializeParams {
- /** Request data containing user and body information (includes req.config) */
- req: ServerRequest;
+interface InitializeParamsBase {
/** The endpoint name/identifier (e.g., 'openAI', 'anthropic', 'custom-endpoint-name') */
endpoint: string;
/** Model parameters from the request (includes model, temperature, topP, etc.) */
@@ -51,6 +57,31 @@ export interface BaseInitializeParams {
db: EndpointDbMethods;
}
+/** Request-backed compatibility contract retained for existing endpoint callers. */
+export interface BaseInitializeParams extends InitializeParamsBase {
+ req: ServerRequest;
+ runtime?: never;
+}
+
+/** Request-free provider initialization contract used by Agent execution hosts. */
+export interface RuntimeInitializeParams extends InitializeParamsBase {
+ runtime: EndpointRuntimeContext;
+ req?: never;
+}
+
+export type ProviderInitializeParams = BaseInitializeParams | RuntimeInitializeParams;
+
+export function resolveEndpointRuntime(params: ProviderInitializeParams): EndpointRuntimeContext {
+ if ('runtime' in params && params.runtime != null) {
+ return params.runtime;
+ }
+ return {
+ appConfig: params.req.config,
+ user: params.req.user,
+ requestBody: params.req.body,
+ };
+}
+
/**
* Base result type that all initialize functions return
* Using a more permissive type to accommodate different provider-specific results