🍵 fix: Support Renewable MCP Credentials for Schedules (#15908)

* fix(schedules): forward renewable MCP credentials

* fix(schedules): require unattended MCP credentials

* fix(schedules): resolve MCP credentials during execution

* refactor(schedules): inject unattended credentials

* fix(schedules): scope renewable credential resolution

* fix: isolate lazy scheduled OBO credentials across MCP lifecycle

* fix: preserve MCP cancellation and retryable credential lookup

* fix: bind MCP cancellation to the owning run signal

* test: supply flow manager in OBO cancellation regression

* fix: preserve MCP cancellation across exchange and API ingress

* style: sort MCP manager imports

* fix: propagate cancellation through agent discovery

* test: preserve agent discovery edge literals

* fix: propagate agent initialization cancellation

* fix: expose initialization signal in OpenAI adapter
This commit is contained in:
Danny Avila 2026-09-14 10:27:47 -04:00 • committed by GitHub
parent b204216c64
commit 345cf8877f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
40 changed files with 1705 additions and 176 deletions

View file

@ -7,6 +7,7 @@ const {
checkToolRolePermission,
createSafeUser,
createAuthIdentityContext,
selectMCPUpstreamTokenProvider,
mcpToolPattern,
loadWebSearchAuth,
splitMCPToolKey,
@ -638,12 +639,18 @@ const loadTools = async ({
user: options.req?.user,
tenantId: getTenantId(),
});
const upstreamTokenProvider = createOpenIDSessionTokenProvider({
req: options.req,
res: options.res,
user: options.req?.user,
identityContext: oboIdentityContext,
tokenPreference: 'access_token',
const upstreamTokenProviderResolver = options.upstreamTokenProviderResolver;
const upstreamTokenProvider = selectMCPUpstreamTokenProvider({
upstreamTokenProvider: options.upstreamTokenProvider,
upstreamTokenProviderResolver,
createSessionProvider: () =>
createOpenIDSessionTokenProvider({
req: options.req,
res: options.res,
user: options.req?.user,
identityContext: oboIdentityContext,
tokenPreference: 'access_token',
}),
});
for (const [serverName, toolConfigs] of Object.entries(requestedMCPTools)) {
@ -666,6 +673,7 @@ const loadTools = async ({
requestScopedConnections,
res: options.res,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
streamId: options.req?._resumableStreamId || null,
jobCreatedAt: options.jobCreatedAt,

View file

@ -421,8 +421,9 @@ jest.mock('~/cache', () => ({
jest.mock('~/server/services/ToolService', () => ({
loadAgentTools: jest.fn().mockResolvedValue([]),
loadToolsForExecution: jest.fn().mockResolvedValue([]),
isFatalAgentInitializationError: (error) =>
isFatalAgentInitializationError: jest.fn((error) =>
['AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE', 'resource_recovery_required'].includes(error?.code),
),
}));
const mockGetMultiplier = jest.fn().mockReturnValue(1);
@ -630,6 +631,7 @@ describe('OpenAIChatCompletionController', () => {
expect.objectContaining({
primaryConfig,
rootConfigs: [primaryConfig],
signal: mockExecution.signal,
resourceType: ResourceType.REMOTE_AGENT,
memoryAvailable: true,
}),
@ -1435,6 +1437,9 @@ describe('OpenAIChatCompletionController', () => {
await OpenAIChatCompletionController(req, res);
expect(res.status).toHaveBeenCalledWith(503);
expect(
require('~/server/services/ToolService').isFatalAgentInitializationError,
).toHaveBeenCalledWith(toolError, { signal: loadAgentTools.mock.calls.at(-1)[0].signal });
});
it('returns the resource recovery status and code before model invocation', async () => {

View file

@ -462,8 +462,9 @@ jest.mock('@librechat/api', () => ({
jest.mock('~/server/services/ToolService', () => ({
loadAgentTools: jest.fn().mockResolvedValue([]),
loadToolsForExecution: jest.fn().mockResolvedValue([]),
isFatalAgentInitializationError: (error) =>
isFatalAgentInitializationError: jest.fn((error) =>
['AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE', 'resource_recovery_required'].includes(error?.code),
),
}));
const mockGetMultiplier = jest.fn().mockReturnValue(1);
@ -840,6 +841,7 @@ describe('createResponse controller', () => {
expect.objectContaining({
primaryConfig,
rootConfigs: [primaryConfig],
signal: mockExecution.signal,
resourceType: ResourceType.REMOTE_AGENT,
memoryAvailable: true,
}),
@ -920,6 +922,9 @@ describe('createResponse controller', () => {
'server_error',
'AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE',
);
expect(
require('~/server/services/ToolService').isFatalAgentInitializationError,
).toHaveBeenCalledWith(toolError, { signal: loadAgentTools.mock.calls.at(-1)[0].signal });
});
it('returns the resource recovery status and code before model invocation', async () => {

View file

@ -144,7 +144,7 @@ function createToolLoader({ req, res, signal, definitionsOnly = true }) {
streamId: null, // No resumable stream for OpenAI compat
});
} catch (error) {
if (isFatalAgentInitializationError(error) || isContentFilterError(error)) {
if (isFatalAgentInitializationError(error, { signal }) || isContentFilterError(error)) {
throw error;
}
logger.error('Error loading tools for agent ' + agentId, getSafeErrorMetadata(error));
@ -627,6 +627,7 @@ const executeOpenAIChatCompletion = async (envelope, { req, res }) => {
skillStates,
defaultActiveOnShare,
manualSkills,
signal: execution.signal,
},
dbMethods,
);
@ -663,6 +664,7 @@ const executeOpenAIChatCompletion = async (envelope, { req, res }) => {
const discoveryParams = {
req,
res,
signal: execution.signal,
primaryConfig,
endpointOption,
allowedProviders,

View file

@ -196,7 +196,7 @@ function createToolLoader({ req, res, signal, definitionsOnly = true }) {
streamId: null,
});
} catch (error) {
if (isFatalAgentInitializationError(error) || isContentFilterError(error)) {
if (isFatalAgentInitializationError(error, { signal }) || isContentFilterError(error)) {
throw error;
}
logger.error('Error loading tools for agent ' + agentId, getSafeErrorMetadata(error));
@ -883,6 +883,7 @@ const executeResponse = async (envelope, { req, res }) => {
skillStates,
defaultActiveOnShare,
manualSkills,
signal: execution.signal,
},
dbMethods,
);
@ -919,6 +920,7 @@ const executeResponse = async (envelope, { req, res }) => {
const discoveryParams = {
req,
res,
signal: execution.signal,
primaryConfig,
endpointOption,
allowedProviders,

View file

@ -66,6 +66,7 @@ const loadAddedAgent = (params) =>
* `codeEnvAvailable`. @see InitializeAgentParams.fileSearchAvailable.
* @param {boolean} [params.statefulSessionsAvailable] - `stateful_code_sessions`
* capability flag; forwarded verbatim alongside `codeEnvAvailable`.
* @param {AbortSignal} [params.signal] - Owning run cancellation signal.
* @returns {Promise<{userMCPAuthMap: Object|undefined}>} The updated userMCPAuthMap
*/
const processAddedConvo = async ({
@ -97,6 +98,7 @@ const processAddedConvo = async ({
toolIntentsAvailable,
statefulSessionsAvailable,
memoryAvailable,
signal,
}) => {
const addedConvo = endpointOption.addedConvo;
if (addedConvo == null) {
@ -200,6 +202,7 @@ const processAddedConvo = async ({
memoryAvailable,
skillStates,
defaultActiveOnShare,
signal,
},
{
getFiles: db.getFiles,
@ -240,7 +243,7 @@ const processAddedConvo = async ({
return { userMCPAuthMap };
} catch (err) {
if (isFatalAgentInitializationError(err)) {
if (isFatalAgentInitializationError(err, { signal })) {
throw err;
}
logger.error('[processAddedConvo] Error processing addedConvo for parallel agent', err);

View file

@ -42,7 +42,8 @@ jest.mock('~/server/services/MCP', () => ({
}));
jest.mock('~/server/services/ToolService', () => ({
isFatalAgentInitializationError: (error) =>
isFatalAgentInitializationError: (error, { signal } = {}) =>
(signal?.aborted === true && (error === signal.reason || error?.name === 'AbortError')) ||
['AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE', 'resource_recovery_required'].includes(error?.code),
}));
@ -173,6 +174,19 @@ describe('processAddedConvo', () => {
await expect(processAddedConvo(baseParams())).rejects.toBe(toolError);
});
it('forwards and propagates owning-run cancellation from added-agent initialization', async () => {
const controller = new AbortController();
const reason = new Error('parallel agent stopped');
controller.abort(reason);
mockInitializeAgent.mockRejectedValueOnce(reason);
await expect(processAddedConvo(baseParams({ signal: controller.signal }))).rejects.toBe(reason);
expect(mockInitializeAgent).toHaveBeenCalledWith(
expect.objectContaining({ signal: controller.signal }),
expect.anything(),
);
});
it('keeps deployment-aware skill metadata on a persisted added-agent config', async () => {
const deploymentSkillId = { toString: () => 'deployment-skill' };
const agentConfigs = new Map();

View file

@ -40,6 +40,7 @@ const {
encodeAndFormatAudios,
encodeAndFormatVideos,
extractFileContext,
createScheduleUpstreamTokenProviderResolver,
} = require('@librechat/api');
const {
ResourceType,
@ -123,6 +124,8 @@ function createToolLoader(
streamId = null,
definitionsOnly = false,
jobCreatedAt,
upstreamTokenProvider,
upstreamTokenProviderResolver,
) {
/**
* @param {object} params
@ -164,9 +167,11 @@ function createToolLoader(
codeExecutionContext,
definitionsOnly,
accessibleMcpServerNames,
upstreamTokenProvider,
upstreamTokenProviderResolver,
});
} catch (error) {
if (isFatalAgentInitializationError(error) || isContentFilterError(error)) {
if (isFatalAgentInitializationError(error, { signal }) || isContentFilterError(error)) {
throw error;
}
logger.error('Error loading tools for agent ' + agentId, error);
@ -185,8 +190,10 @@ function createToolLoader(
* @param {string} [params.checkpointNamespace] Immutable saver-level generation scope
* @param {string} [params.foregroundRunId] Canonical response identity for foreground execution
* @param {import('@librechat/api').MCPRuntimeRequestBody} [params.requestBody]
* @param {import('@librechat/api').UpstreamTokenProvider} [params.upstreamTokenProvider]
* @param {import('@librechat/api').UpstreamTokenProviderResolver} [params.upstreamTokenProviderResolver]
*/
const initializeClient = async ({
const initializeClientWithProvider = async ({
req,
res,
signal,
@ -195,6 +202,8 @@ const initializeClient = async ({
checkpointNamespace,
foregroundRunId,
requestBody,
upstreamTokenProvider,
upstreamTokenProviderResolver,
}) => {
if (!endpointOption) {
throw new Error('Endpoint option not provided');
@ -463,6 +472,8 @@ const initializeClient = async ({
mcpAvailableTools: ctx.mcpAvailableTools,
requestScopedConnections: ctx.requestScopedConnections,
userMCPAuthMap: ctx.userMCPAuthMap,
upstreamTokenProvider,
upstreamTokenProviderResolver,
tool_resources: ctx.tool_resources,
actionsEnabled: ctx.actionsEnabled,
accessibleMcpServerNames: ctx.accessibleMcpServerNames,
@ -624,7 +635,16 @@ 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(req, res, signal, streamId, true, jobCreatedAt);
const loadTools = createToolLoader(
req,
res,
signal,
streamId,
true,
jobCreatedAt,
upstreamTokenProvider,
upstreamTokenProviderResolver,
);
/** @type {Array<MongoFile>} */
const requestFiles = req.body.files ?? [];
/** @type {string | undefined} */
@ -712,6 +732,7 @@ const initializeClient = async ({
skillStates,
defaultActiveOnShare,
manualSkills,
signal,
},
{
getFiles: db.getFiles,
@ -760,6 +781,7 @@ const initializeClient = async ({
{
req,
res,
signal,
primaryConfig,
agent_ids: primaryConfig.agent_ids,
endpointOption,
@ -884,6 +906,7 @@ const initializeClient = async ({
toolIntentsAvailable,
statefulSessionsAvailable,
memoryAvailable,
signal,
});
if (updatedMCPAuthMap) {
@ -1160,7 +1183,7 @@ const initializeClient = async ({
try {
return await loading;
} catch (error) {
if (isFatalAgentInitializationError(error)) {
if (isFatalAgentInitializationError(error, { signal })) {
throw error;
}
logger.error(`[initializeClient] Error loading subagent metadata ${agentId}:`, error);
@ -1248,7 +1271,16 @@ const initializeClient = async ({
req,
res,
agent,
loadTools: createToolLoader(req, res, context.signal, streamId, true, jobCreatedAt),
loadTools: createToolLoader(
req,
res,
context.signal,
streamId,
true,
jobCreatedAt,
upstreamTokenProvider,
upstreamTokenProviderResolver,
),
requestFiles,
authorizedRunFiles: getAuthorizedRunFileSnapshot({
policy: appConfig.endpoints?.agents?.fileSharing,
@ -1277,6 +1309,7 @@ const initializeClient = async ({
memoryAvailable,
skillStates,
defaultActiveOnShare,
signal: context.signal,
},
{
getFiles: db.getFiles,
@ -1461,7 +1494,7 @@ const initializeClient = async ({
graphMemberConfigsById.set(memberId, config);
return config;
} catch (error) {
if (isFatalAgentInitializationError(error)) {
if (isFatalAgentInitializationError(error, { signal })) {
throw error;
}
logger.error(`[initializeClient] Error initializing graph member ${memberId}:`, error);
@ -1834,4 +1867,25 @@ const initializeClient = async ({
return { client, userMCPAuthMap };
};
module.exports = { initializeClient };
/**
* Creates an agent initializer whose host may resolve renewable credentials at
* the execution boundary. The resolver returns a provider closure rather than
* token material so refresh remains owned by the host integration.
*
* @param {object} [dependencies]
* @param {(user: import('@librechat/data-schemas').IUser, options: { signal?: AbortSignal }) => import('@librechat/api').UpstreamTokenProvider | undefined | Promise<import('@librechat/api').UpstreamTokenProvider | undefined>} [dependencies.resolveUpstreamTokenProvider]
*/
function createInitializeClient(dependencies = {}) {
return async (params) => {
const upstreamTokenProviderResolver = createScheduleUpstreamTokenProviderResolver(
params.req,
dependencies.resolveUpstreamTokenProvider,
params.signal,
);
return initializeClientWithProvider({ ...params, upstreamTokenProviderResolver });
};
}
const initializeClient = createInitializeClient();
module.exports = { createInitializeClient, initializeClient };

View file

@ -98,7 +98,7 @@ jest.mock('~/cache', () => ({
logViolation: jest.fn(),
}));
const { initializeClient } = require('./initialize');
const { createInitializeClient, initializeClient } = require('./initialize');
const { processAddedConvo } = require('./addedConvo');
const { getSkillDbMethods, getSkillToolDeps } = require('./skillDeps');
const { loadAgentTools } = require('~/server/services/ToolService');
@ -182,6 +182,53 @@ describe('initializeClient — processAgent ACL gate', () => {
},
});
it('defers host credential resolution during scheduled agent initialization', async () => {
const upstreamTokenProvider = jest.fn();
const resolveUpstreamTokenProvider = jest.fn().mockResolvedValue(upstreamTokenProvider);
const hostInitializeClient = createInitializeClient({ resolveUpstreamTokenProvider });
const req = makeReq();
req._isScheduledFire = true;
const signal = new AbortController().signal;
mockInitializeAgent.mockImplementationOnce(async ({ loadTools, agent }) => {
await loadTools({
tools: ['run_query_mcp_warehouse'],
model: agent.model,
agentId: agent.id,
provider: agent.provider,
});
return makePrimaryConfig([]);
});
await hostInitializeClient({
req,
res: {},
signal,
endpointOption: makeEndpointOption(),
});
expect(resolveUpstreamTokenProvider).not.toHaveBeenCalled();
const toolLoadParams = loadAgentTools.mock.calls[0][0];
expect(toolLoadParams.upstreamTokenProvider).toBeUndefined();
const resolver = toolLoadParams.upstreamTokenProviderResolver;
await expect(resolver({ signal })).resolves.toBe(upstreamTokenProvider);
expect(resolveUpstreamTokenProvider).toHaveBeenCalledWith(req.user, { signal });
});
it('keeps interactive agent initialization independent of the host resolver', async () => {
const resolveUpstreamTokenProvider = jest.fn();
const hostInitializeClient = createInitializeClient({ resolveUpstreamTokenProvider });
mockInitializeAgent.mockResolvedValue(makePrimaryConfig([]));
await hostInitializeClient({
req: makeReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(resolveUpstreamTokenProvider).not.toHaveBeenCalled();
});
it('replaces untrusted artifact route metadata with the executing agent context', async () => {
mockInitializeAgent.mockResolvedValue(makePrimaryConfig([]));

View file

@ -736,6 +736,7 @@ function resolveToolCallUserId({ effectiveUser, capturedUser, invocationUserId,
* @param {Object} params
* @param {ServerResponse} params.res - The Express response object for sending events.
* @param {import('@librechat/api').UpstreamTokenProvider} [params.upstreamTokenProvider] - Live upstream-token closure for OBO, built at the request boundary so this layer never receives the raw Express request.
* @param {import('@librechat/api').UpstreamTokenProviderResolver} [params.upstreamTokenProviderResolver]
* @param {import('@librechat/api').AuthIdentityContext} [params.oboIdentityContext] - Non-template-visible OBO identity context built from the real request user.
* @param {IUser} params.user - The user from the request object.
* @param {string} params.serverName
@ -761,6 +762,7 @@ async function reconnectServer({
requestBody,
requestScopedConnections,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
streamId = null,
jobCreatedAt,
@ -829,6 +831,7 @@ async function reconnectServer({
requestBody,
requestScopedConnections,
upstreamTokenProvider,
upstreamTokenProviderResolver,
recoveryPolicy,
oboIdentityContext,
forceNew: true,
@ -859,6 +862,7 @@ async function reconnectServer({
* @param {import('@librechat/api').RequestScopedMCPConnectionStore} [params.requestScopedConnections]
* @param {Record<string, Record<string, string>>} [params.userMCPAuthMap]
* @param {import('@librechat/api').UpstreamTokenProvider} [params.upstreamTokenProvider] - Live upstream-token closure for OBO, built at the request boundary.
* @param {import('@librechat/api').UpstreamTokenProviderResolver} [params.upstreamTokenProviderResolver]
* @param {import('@librechat/api').AuthIdentityContext} [params.oboIdentityContext] - Non-template-visible OBO identity context built from the real request user.
* @returns { Promise<Array<typeof tool | { _call: (toolInput: Object | string) => unknown}>> } An object with `_call` method to execute the tool input.
*/
@ -876,6 +880,7 @@ async function createMCPTools({
requestBody,
requestScopedConnections,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
streamId = null,
jobCreatedAt,
@ -920,6 +925,7 @@ async function createMCPTools({
requestBody,
requestScopedConnections,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
streamId,
jobCreatedAt,
@ -959,6 +965,7 @@ async function createMCPTools({
requestBody,
requestScopedConnections,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
config: serverConfig,
});
@ -988,6 +995,7 @@ async function createMCPTools({
* @param {Record<string, Record<string, string>>} [params.userMCPAuthMap]
* @param {import('@librechat/api').ParsedServerConfig} [params.config]
* @param {import('@librechat/api').UpstreamTokenProvider} [params.upstreamTokenProvider] - Live upstream-token closure for OBO, built at the request boundary.
* @param {import('@librechat/api').UpstreamTokenProviderResolver} [params.upstreamTokenProviderResolver]
* @param {import('@librechat/api').AuthIdentityContext} [params.oboIdentityContext] - Non-template-visible OBO identity context built from the real request user.
* @param {string} [params.serverName] - Resolved raw MCP server name from tool loading.
* @param {(availableTools: LCAvailableTools) => void} [params.onAvailableTools]
@ -1009,6 +1017,7 @@ async function createMCPTool({
config,
configServers,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
serverName: resolvedServerName,
onAvailableTools,
@ -1141,6 +1150,7 @@ async function createMCPTool({
requestBody,
requestScopedConnections,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
streamId,
jobCreatedAt,
@ -1186,6 +1196,7 @@ async function createMCPTool({
serverConfig,
toolDefinition: toolEntry['function'],
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
streamId,
jobCreatedAt,
@ -1207,6 +1218,7 @@ function createToolInstance({
toolDefinition,
provider: capturedProvider,
upstreamTokenProvider: capturedUpstreamTokenProvider = null,
upstreamTokenProviderResolver: capturedUpstreamTokenProviderResolver = null,
oboIdentityContext: capturedOboIdentityContext = null,
streamId = null,
jobCreatedAt,
@ -1337,6 +1349,7 @@ function createToolInstance({
oboTokenResolver: exchangeOboToken,
oboTrustChecker: createOboTrustChecker(),
upstreamTokenProvider: capturedUpstreamTokenProvider,
upstreamTokenProviderResolver: capturedUpstreamTokenProviderResolver,
oboIdentityContext: capturedOboIdentityContext,
});
@ -1350,10 +1363,14 @@ function createToolInstance({
* alerts; the wrapping below still reports it to the turn. The error has
* to look like an abort as well: a permission, OAuth, or upstream failure
* can reject in the same tick as the Stop and must stay visible. */
if (config?.signal?.aborted === true && isAbortError(error)) {
if (
config?.signal?.aborted === true &&
(isAbortError(error) || error === config.signal.reason)
) {
logger.debug(
`[MCP][${serverName}][${toolName}][User: ${userId}] Tool call cancelled by user abort`,
);
throw error;
} else {
logger.error(
`[MCP][${serverName}][${toolName}][User: ${userId}] Error calling MCP tool:`,

View file

@ -1684,6 +1684,51 @@ describe('User parameter passing tests', () => {
);
});
it('preserves AbortError from the MCP tool implementation', async () => {
const mockUser = { id: 'cancel-user', role: 'USER' };
const abortController = new AbortController();
const abort = Object.assign(new Error('Stopped'), { name: 'AbortError' });
const { getRoleByName } = require('~/models');
getRoleByName.mockResolvedValue({
permissions: {
[PermissionTypes.MCP_SERVERS]: {
[Permissions.USE]: true,
},
},
});
mockGetMCPManager.mockReturnValue({
callTool: jest.fn(async () => {
abortController.abort(abort);
throw abort;
}),
});
const mcpTool = await createMCPTool({
user: mockUser,
config: { url: 'https://cancel.example.com/mcp' },
toolKey: `test-tool${D}test-server`,
provider: 'openai',
userMCPAuthMap: {},
availableTools: {
[`test-tool${D}test-server`]: {
function: {
description: 'Cached tool',
parameters: { type: 'object', properties: {} },
},
},
},
});
await expect(
mcpTool.func({}, undefined, {
signal: abortController.signal,
configurable: { user: mockUser },
metadata: { provider: 'openai', thread_id: 'thread-1', run_id: 'run-1' },
toolCall: {},
}),
).rejects.toBe(abort);
});
it('keeps a real failure racing the Stop at error level', async () => {
const mockUser = { id: 'race-user', role: 'USER' };
const mockRes = { write: jest.fn(), flush: jest.fn() };

View file

@ -9,30 +9,44 @@ const { createOboTrustChecker } = require('~/server/services/OboPolicyService');
const { getLogStores } = require('~/cache');
const methods = require('~/models');
module.exports = createScheduleMCPPreflight({
getRoleByName: methods.getRoleByName,
resolveAgentGraphAccess: methods.resolveAgentGraphAccess,
getAgentGraphNodes: methods.getAgentGraphNodes,
getModelsConfig: (user) => getModelsConfig({ user }),
getUser: (id) => methods.findUser({ _id: id }),
getAppConfig,
ensureConfigServers: (config, limit) =>
getMCPServersRegistry().ensureConfigServers(config, limit),
getServerConfigs: (userId, config, role) =>
getMCPServersRegistry().getAllServerConfigs(userId, config, role),
findPluginAuthsByKeys: methods.findPluginAuthsByKeys,
connect: (options) =>
getMCPManager().getConnection({
...options,
flowManager: getFlowStateManager(getLogStores(CacheKeys.FLOWS)),
tokenMethods: {
findToken: methods.findToken,
updateToken: methods.updateToken,
createToken: methods.createToken,
deleteTokens: methods.deleteTokens,
},
graphTokenResolver: getGraphApiToken,
oboTokenResolver: exchangeOboToken,
oboTrustChecker: createOboTrustChecker(),
}),
});
/**
* Builds the schedule MCP preflight with an optional host-owned renewable
* credential resolver. The default application has no durable upstream
* credential source and therefore remains fail-closed for unattended OBO.
*
* @param {object} [options]
* @param {(user: import('@librechat/data-schemas').IUser, options: { signal?: AbortSignal }) => import('@librechat/api').UpstreamTokenProvider | undefined | Promise<import('@librechat/api').UpstreamTokenProvider | undefined>} [options.resolveUpstreamTokenProvider]
*/
function createMCPPreflight(options = {}) {
return createScheduleMCPPreflight({
getRoleByName: methods.getRoleByName,
resolveAgentGraphAccess: methods.resolveAgentGraphAccess,
getAgentGraphNodes: methods.getAgentGraphNodes,
getModelsConfig: (user) => getModelsConfig({ user }),
getUser: (id) => methods.findUser({ _id: id }),
getAppConfig,
ensureConfigServers: (config, limit) =>
getMCPServersRegistry().ensureConfigServers(config, limit),
getServerConfigs: (userId, config, role) =>
getMCPServersRegistry().getAllServerConfigs(userId, config, role),
findPluginAuthsByKeys: methods.findPluginAuthsByKeys,
resolveUpstreamTokenProvider: options.resolveUpstreamTokenProvider,
connect: (connectionOptions) =>
getMCPManager().getConnection({
...connectionOptions,
flowManager: getFlowStateManager(getLogStores(CacheKeys.FLOWS)),
tokenMethods: {
findToken: methods.findToken,
updateToken: methods.updateToken,
createToken: methods.createToken,
deleteTokens: methods.deleteTokens,
},
graphTokenResolver: getGraphApiToken,
oboTokenResolver: exchangeOboToken,
oboTrustChecker: createOboTrustChecker(),
}),
});
}
module.exports = createMCPPreflight();
module.exports.createMCPPreflight = createMCPPreflight;

View file

@ -12,6 +12,7 @@ const {
getToolkitKey,
getUserMCPAuthMap,
createAuthIdentityContext,
selectMCPUpstreamTokenProvider,
loadToolDefinitions,
GenerationJobManager,
isActionDomainAllowed,
@ -783,6 +784,8 @@ const isBuiltInTool = (toolName) =>
* @param {string|null} [params.streamId] - Stream ID for resumable mode
* @param {number} [params.jobCreatedAt] - The generation epoch that owns emitted tool events
* @param {AbortSignal} [params.signal] - Effective run cancellation signal
* @param {import('@librechat/api').UpstreamTokenProvider} [params.upstreamTokenProvider]
* @param {import('@librechat/api').UpstreamTokenProviderResolver} [params.upstreamTokenProviderResolver]
* @returns {Promise<{
* toolDefinitions?: import('@librechat/api').LCTool[];
* toolRegistry?: Map<string, import('@librechat/api').LCTool>;
@ -803,6 +806,8 @@ async function loadToolDefinitionsWrapper({
codeExecutionContext,
accessibleMcpServerNames,
signal,
upstreamTokenProvider: suppliedUpstreamTokenProvider,
upstreamTokenProviderResolver,
}) {
if (!agent.tools || agent.tools.length === 0) {
return { toolDefinitions: [] };
@ -988,22 +993,21 @@ async function loadToolDefinitionsWrapper({
/** @type {Record<string, import('@librechat/api').LCAvailableTools>} */
const mcpAvailableTools = {};
const requestScopedConnections = getMCPRequestContext(req, res);
/**
* Build the OBO upstream-token closure once at this request boundary and pass
* the function into MCP handling, so `reinitMCPServer` never receives the raw
* Express request. `res` is forwarded so a rotated refresh token can be
* mirrored to the `refreshToken` cookie when the response is still writable.
*/
const oboIdentityContext = createAuthIdentityContext({
user: req.user,
tenantId: getTenantId(),
});
const upstreamTokenProvider = createOpenIDSessionTokenProvider({
req,
res,
user: req.user,
identityContext: oboIdentityContext,
tokenPreference: 'access_token',
const upstreamTokenProvider = selectMCPUpstreamTokenProvider({
upstreamTokenProvider: suppliedUpstreamTokenProvider,
upstreamTokenProviderResolver,
createSessionProvider: () =>
createOpenIDSessionTokenProvider({
req,
res,
user: req.user,
identityContext: oboIdentityContext,
tokenPreference: 'access_token',
}),
});
const rememberMCPAvailableTools = (serverName, availableTools) => {
if (!availableTools || Object.keys(availableTools).length === 0) {
@ -1182,6 +1186,7 @@ async function loadToolDefinitionsWrapper({
};
const result = await reinitMCPServer({
signal,
user: req.user,
oauthStart,
flowManager,
@ -1191,6 +1196,7 @@ async function loadToolDefinitionsWrapper({
requestBody: runtimeRequestBody,
requestScopedConnections,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
recoveryPolicy: appConfig?.mcpSettings?.catalogRecovery,
});
@ -1211,6 +1217,7 @@ async function loadToolDefinitionsWrapper({
}
};
const result = await reinitMCPServer({
signal,
user: req.user,
forceNew: true,
oauthStart,
@ -1221,6 +1228,7 @@ async function loadToolDefinitionsWrapper({
requestBody: runtimeRequestBody,
requestScopedConnections,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
recoveryPolicy: appConfig?.mcpSettings?.catalogRecovery,
});
@ -1361,6 +1369,7 @@ async function loadToolDefinitionsWrapper({
}
const result = await reinitMCPServer({
signal,
user: req.user,
serverName,
configServers,
@ -1372,6 +1381,7 @@ async function loadToolDefinitionsWrapper({
oauthEnd: createOAuthEndEmitter(serverName),
connectionTimeout: Time.TWO_MINUTES,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
recoveryPolicy: appConfig?.mcpSettings?.catalogRecovery,
});
@ -1382,16 +1392,19 @@ async function loadToolDefinitionsWrapper({
return { serverName, success: true };
}
return { serverName, success: false };
} catch {
} catch (error) {
if (isFatalAgentInitializationError(error, { signal })) {
throw error;
}
logger.debug('[Tool Definitions] MCP OAuth wait failed for one server');
return { serverName, success: false };
}
});
const results = await Promise.allSettled(oauthWaitPromises);
const results = await Promise.all(oauthWaitPromises);
const successfulServers = results
.filter((r) => r.status === 'fulfilled' && r.value.success)
.map((r) => r.value.serverName);
.filter((result) => result.success)
.map((result) => result.serverName);
if (successfulServers.length > 0) {
logger.info(
@ -1477,7 +1490,7 @@ async function loadToolDefinitionsWrapper({
primedCodeFiles = files;
}
} catch (error) {
if (isFatalAgentInitializationError(error)) {
if (isFatalAgentInitializationError(error, { signal })) {
throw error;
}
logger.error(
@ -1567,6 +1580,8 @@ async function loadToolDefinitionsWrapper({
* @param {boolean} [params.definitionsOnly=true] - When true, returns only serializable
* tool definitions without creating full tool instances. Use for event-driven mode
* where tools are loaded on-demand during execution.
* @param {import('@librechat/api').UpstreamTokenProvider} [params.upstreamTokenProvider]
* @param {import('@librechat/api').UpstreamTokenProviderResolver} [params.upstreamTokenProviderResolver]
*/
async function loadAgentTools({
req,
@ -1582,6 +1597,8 @@ async function loadAgentTools({
definitionsOnly = true,
codeExecutionContext: providedCodeExecutionContext,
accessibleMcpServerNames,
upstreamTokenProvider,
upstreamTokenProviderResolver,
}) {
if (definitionsOnly) {
try {
@ -1597,10 +1614,12 @@ async function loadAgentTools({
codeExecutionContext: providedCodeExecutionContext,
accessibleMcpServerNames,
signal,
upstreamTokenProvider,
upstreamTokenProviderResolver,
});
} catch (error) {
if (
isFatalAgentInitializationError(error) ||
isFatalAgentInitializationError(error, { signal }) ||
isContentFilterError(error) ||
!agent.tools?.some(isExpectedMCPTool)
) {
@ -1759,6 +1778,8 @@ async function loadAgentTools({
returnMetadata: true,
mcpPermissionContext,
requestScopedConnections: getMCPRequestContext(req, res),
upstreamTokenProvider,
upstreamTokenProviderResolver,
codeExecutionContext,
[Tools.web_search]: webSearchCallbacks,
},
@ -2023,6 +2044,8 @@ async function loadAgentTools({
* @param {Record<string, import('@librechat/api').LCAvailableTools>} [params.mcpAvailableTools] - Run-scoped MCP tool definitions
* @param {import('@librechat/api').RequestScopedMCPConnectionStore} [params.requestScopedConnections] - Run-scoped MCP connections
* @param {Record<string, Record<string, string>>} [params.userMCPAuthMap] - User MCP auth map
* @param {import('@librechat/api').UpstreamTokenProvider} [params.upstreamTokenProvider]
* @param {import('@librechat/api').UpstreamTokenProviderResolver} [params.upstreamTokenProviderResolver]
* @param {Object} [params.tool_resources] - Tool resources
* @param {string|null} [params.streamId] - Stream ID for web search callbacks
* @param {number} [params.jobCreatedAt] - The generation epoch that owns emitted tool events
@ -2046,6 +2069,8 @@ async function loadToolsForExecution({
mcpAvailableTools,
requestScopedConnections,
userMCPAuthMap,
upstreamTokenProvider,
upstreamTokenProviderResolver,
tool_resources,
streamId = null,
jobCreatedAt,
@ -2355,6 +2380,8 @@ async function loadToolsForExecution({
* turn already advertised. */
accessibleMcpServerNames,
requestScopedConnections: mcpRequestScopedConnections,
upstreamTokenProvider,
upstreamTokenProviderResolver,
[Tools.web_search]: webSearchCallbacks,
},
webSearch: appConfig?.webSearch,

View file

@ -7,9 +7,7 @@ const {
resolveMCPReinitializeConfig,
requiresEphemeralUserConnection,
getMissingRuntimeBodyPlaceholderFields,
MCPAuthenticationRejectedError,
MCPAuthenticationRefreshError,
OpenIDReauthRequiredError,
isMCPInitializationError,
prepareMCPAuthorizationMutation,
} = require('@librechat/api');
const { CacheKeys, Constants } = require('librechat-data-provider');
@ -43,16 +41,12 @@ const MCP_REINITIALIZE_FAILURE_REASONS = {
INITIALIZATION_FAILED: 'initialization_failed',
};
const isMCPReauthenticationError = (error) =>
error instanceof MCPAuthenticationRejectedError ||
error instanceof MCPAuthenticationRefreshError ||
error instanceof OpenIDReauthRequiredError;
/** Wires application dependencies into the passive, request-local catalog recovery service.
* @param {Object} params
* @param {IUser} params.user
* @param {Array<{ serverName: string, serverConfig: object }>} params.servers
* @param {import('@librechat/api').UpstreamTokenProvider} [params.upstreamTokenProvider] - Live upstream-token closure for OBO discovery, built at the request boundary so this layer never receives the raw Express request.
* @param {import('@librechat/api').UpstreamTokenProviderResolver} [params.upstreamTokenProviderResolver]
* @param {import('@librechat/api').AuthIdentityContext} [params.oboIdentityContext] - Non-template-visible OBO identity context built from the real request user.
* @param {AbortSignal} [params.signal] - Cancels queued and in-flight catalog reads when the request ends.
* @param {import('@librechat/api').MCPServerCatalogRecoveryPolicy} [params.recoveryPolicy]
@ -61,6 +55,7 @@ async function loadMCPServerCatalogs({
user,
servers,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
signal,
recoveryPolicy,
@ -96,6 +91,7 @@ async function loadMCPServerCatalogs({
oboTokenResolver: exchangeOboToken,
oboTrustChecker: createOboTrustChecker(),
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
}),
onOAuthCredentialsChanging,
@ -117,6 +113,7 @@ async function loadMCPServerCatalogs({
* @param {Object} params
* @param {IUser} params.user - The user from the request object.
* @param {import('@librechat/api').UpstreamTokenProvider} [params.upstreamTokenProvider] - Live upstream-token closure for OBO connection establishment, built at the request boundary so this layer never receives the raw Express request.
* @param {import('@librechat/api').UpstreamTokenProviderResolver} [params.upstreamTokenProviderResolver]
* @param {import('@librechat/api').AuthIdentityContext} [params.oboIdentityContext] - Non-template-visible OBO identity context built from the real request user.
* @param {string} params.serverName - The name of the MCP server
* @param {boolean} params.returnOnOAuth - Whether to initiate OAuth and return, or wait for OAuth flow to finish
@ -146,6 +143,7 @@ async function reinitMCPServer({
requestBody,
requestScopedConnections,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
oauthEnd,
recoveryPolicy,
@ -281,12 +279,13 @@ async function reinitMCPServer({
oboTokenResolver: exchangeOboToken,
oboTrustChecker: createOboTrustChecker(),
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
});
logger.info('[MCP Reinitialize] Successfully established connection');
} catch (err) {
if (isMCPReauthenticationError(err)) {
if (isMCPInitializationError(err, signal)) {
throw err;
}
logger.info('[MCP Reinitialize] Connection attempt failed');
@ -322,6 +321,7 @@ async function reinitMCPServer({
oboTokenResolver: exchangeOboToken,
oboTrustChecker: createOboTrustChecker(),
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
});
@ -332,7 +332,7 @@ async function reinitMCPServer({
);
}
} catch (error) {
if (isMCPReauthenticationError(error)) {
if (isMCPInitializationError(error, signal)) {
throw error;
}
logger.debug('[MCP Reinitialize] Tool discovery failed');
@ -347,9 +347,9 @@ async function reinitMCPServer({
mcpManager.getToolPublicationGeneration(connection) ?? publicationGeneration;
let snapshot;
if (typeof connection.fetchOrderedToolsSnapshot === 'function') {
snapshot = await connection.fetchOrderedToolsSnapshot();
snapshot = await connection.fetchOrderedToolsSnapshot(undefined, signal);
} else if (typeof connection.fetchToolsSnapshot === 'function') {
snapshot = await connection.fetchToolsSnapshot();
snapshot = await connection.fetchToolsSnapshot(undefined, signal);
} else {
snapshot = { tools: await connection.fetchTools(), complete: true };
}
@ -451,7 +451,7 @@ async function reinitMCPServer({
return result;
} catch (error) {
if (isMCPReauthenticationError(error)) {
if (isMCPInitializationError(error, signal)) {
throw error;
}
logger.error('[MCP Reinitialize] Error loading MCP tools; servers may still be initializing');

View file

@ -314,6 +314,7 @@ describe('reinitMCPServer — customUserVars gating (issue #10969)', () => {
});
it('preserves cached tools when live recovery returns an incomplete snapshot', async () => {
const signal = new AbortController().signal;
const fetchOrderedToolsSnapshot = jest.fn().mockResolvedValue({
tools: [{ name: 'partial', inputSchema: { type: 'object' } }],
complete: false,
@ -325,11 +326,13 @@ describe('reinitMCPServer — customUserVars gating (issue #10969)', () => {
const result = await reinitMCPServer({
user,
serverName,
signal,
serverConfig: { type: 'streamable-http', url: 'https://thingy.example.com/mcp' },
});
expect(result.tools).toBeNull();
expect(fetchOrderedToolsSnapshot).toHaveBeenCalledTimes(1);
expect(fetchOrderedToolsSnapshot).toHaveBeenCalledWith(undefined, signal);
expect(mockUpdateMCPServerTools).not.toHaveBeenCalled();
});
@ -552,6 +555,47 @@ describe('reinitMCPServer — direct bearer authentication outcomes', () => {
}),
).rejects.toBe(rejection);
});
it('propagates cancellation instead of hiding the server tool', async () => {
const abort = new DOMException('Stopped', 'AbortError');
const controller = new AbortController();
controller.abort(abort);
mockGetConnection.mockRejectedValue(abort);
await expect(
reinitMCPServer({
user: { id: 'user-123' },
serverName: 'example-mcp',
signal: controller.signal,
serverConfig: { type: 'streamable-http', url: 'https://mcp.example.com', source: 'yaml' },
}),
).rejects.toBe(abort);
});
it.each([false, true])(
'preserves a typed OBO resolution failure (retryable=%s)',
async (retryable) => {
const { OboTokenResolutionError } = require('@librechat/api');
const rejection = new OboTokenResolutionError(
'session_refresh_failed',
'Sign-in expired.',
retryable,
);
mockGetConnection.mockRejectedValue(rejection);
await expect(
reinitMCPServer({
user: { id: 'user-123' },
serverName: 'private-mcp',
serverConfig: {
type: 'streamable-http',
url: 'https://mcp.example.com',
source: 'yaml',
obo: { scopes: 'api://mcp/.default' },
},
}),
).rejects.toBe(rejection);
},
);
});
describe('reinitMCPServer — runtime BODY placeholder pre-check (issue #14074)', () => {

View file

@ -94,8 +94,17 @@ const mockGetUserMCPAuthMap = jest.fn();
jest.mock('@librechat/api', () => ({
...jest.requireActual('@librechat/api'),
AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE: 'AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE',
isFatalAgentInitializationError: (error) =>
isFatalAgentInitializationError: (error, { signal } = {}) =>
(signal?.aborted === true && (error === signal.reason || error?.name === 'AbortError')) ||
['AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE', 'resource_recovery_required'].includes(error?.code),
selectMCPUpstreamTokenProvider: ({
upstreamTokenProvider,
upstreamTokenProviderResolver,
createSessionProvider,
}) =>
upstreamTokenProviderResolver
? upstreamTokenProvider
: (upstreamTokenProvider ?? createSessionProvider()),
loadToolDefinitions: (...args) => mockLoadToolDefinitions(...args),
getUserMCPAuthMap: (...args) => mockGetUserMCPAuthMap(...args),
createAuthIdentityContext: ({ user, tenantId }) => ({
@ -191,7 +200,6 @@ jest.mock('~/server/services/MCP', () => ({
jest.mock('~/cache', () => ({
getLogStores: jest.fn(() => ({})),
}));
const {
loadAgentTools,
loadToolsForExecution,
@ -1922,6 +1930,55 @@ describe('ToolService - Action Capability Gating', () => {
);
});
it('propagates owning-run cancellation from the pending OAuth fan-out', async () => {
const serverName = 'Google-Workspace';
const authorizationUrl = 'https://auth.example.com/Google-Workspace';
const mcpTool = `${Constants.mcp_all}${Constants.mcp_delimiter}${serverName}`;
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
const res = { writableEnded: false };
const controller = new AbortController();
const reason = new Error('generation stopped');
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockGetServerConfig.mockResolvedValue({
type: 'streamable-http',
url: 'https://demo.librechat.ai/mcp',
requiresOAuth: true,
});
mockGetMCPServerTools.mockResolvedValue(null);
mockFlowManager.getFlowState.mockResolvedValue({
status: 'PENDING',
createdAt: Date.now(),
metadata: { authorizationUrl },
});
mockLoadToolDefinitions.mockImplementation(async (params, deps) => {
await deps.getOrFetchMCPServerTools(params.userId, serverName);
return {
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
};
});
reinitMCPServer.mockImplementation(
({ signal }) =>
new Promise((_resolve, reject) => {
signal.addEventListener('abort', () => reject(signal.reason), { once: true });
}),
);
const loading = loadAgentTools({
req,
res,
signal: controller.signal,
agent: { id: 'agent_123', tools: [mcpTool] },
definitionsOnly: true,
});
await new Promise((resolve) => setImmediate(resolve));
controller.abort(reason);
await expect(loading).rejects.toBe(reason);
});
it('should re-emit pending MCP OAuth prompts when selected MCP tools are already concrete', async () => {
const serverName = `Google${Constants.mcp_delimiter}Workspace`;
const authorizationUrl = 'https://auth.example.com/Google-Workspace';
@ -2175,6 +2232,96 @@ describe('ToolService - Action Capability Gating', () => {
);
});
it('uses host-supplied renewable upstream credentials when loading tools', async () => {
const serverName = 'Scheduled-OBO';
const mcpTool = `search${Constants.mcp_delimiter}${serverName}`;
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
req.body = { conversationId: 'conv-123', messageId: 'msg-123' };
req.user = {
id: 'user_123',
provider: 'openid',
openidId: 'oidc-sub-123',
tenantId: 'tenant-1',
openidIssuer: 'https://issuer.example.com',
};
const scheduledProvider = jest.fn().mockResolvedValue({ access_token: 'renewed-token' });
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockGetServerConfig.mockResolvedValue({
type: 'streamable-http',
url: 'https://mcp.example.com/obo',
obo: { scopes: 'api://obo/Mcp.Tools.ReadWrite' },
});
mockLoadToolDefinitions.mockImplementation(async (params, dependencies) => {
await dependencies.refreshMCPServerTools(params.userId, serverName);
return {
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
};
});
reinitMCPServer.mockResolvedValue({ availableTools: {} });
const signal = new AbortController().signal;
await loadAgentTools({
req,
agent: { id: 'agent_123', tools: [mcpTool] },
definitionsOnly: true,
signal,
upstreamTokenProvider: scheduledProvider,
});
expect(reinitMCPServer).toHaveBeenCalledWith(
expect.objectContaining({
serverName,
forceNew: true,
upstreamTokenProvider: scheduledProvider,
}),
);
});
it('keeps a deferred OBO resolver separate from direct-bearer credentials', async () => {
const serverName = 'Scheduled-OBO';
const mcpTool = `search${Constants.mcp_delimiter}${serverName}`;
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
const upstreamTokenProviderResolver = jest.fn();
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockGetServerConfig.mockResolvedValue({
type: 'streamable-http',
url: 'https://mcp.example.com/obo',
obo: { scopes: 'api://obo/Mcp.Tools.ReadWrite' },
});
mockLoadToolDefinitions.mockImplementation(async (params, dependencies) => {
await dependencies.refreshMCPServerTools(params.userId, serverName);
return {
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
};
});
reinitMCPServer.mockResolvedValue({ availableTools: {} });
await loadAgentTools({
req,
agent: { id: 'agent_123', tools: [mcpTool] },
definitionsOnly: true,
upstreamTokenProviderResolver,
});
expect(reinitMCPServer).toHaveBeenCalledWith(
expect.objectContaining({
serverName,
forceNew: true,
upstreamTokenProvider: undefined,
upstreamTokenProviderResolver,
}),
);
expect(upstreamTokenProviderResolver).not.toHaveBeenCalled();
});
it('returns run-scoped MCP tool definitions for request-scoped servers', async () => {
const serverName = 'ClickHouse';
const mcpTool = `list_tables${Constants.mcp_delimiter}${serverName}`;

View file

@ -2236,6 +2236,49 @@ describe('initializeAgent — skill `allowed-tools` union (Phase 6)', () => {
expect(definedNames).not.toContain('mcp__broken__tool');
});
it.each([
['Error', new Error('run cancelled')],
['string', 'run cancelled'],
])(
'does not retry skill-added tools when the owning signal aborts with an %s reason',
async (_, reason) => {
const { agent, req, res, loadTools, db } = createMocks();
agent.tools = ['web_search'];
const { Types } = await import('mongoose');
const skillId = new Types.ObjectId();
const controller = new AbortController();
controller.abort(reason);
loadTools.mockRejectedValue(reason);
const getSkillByName = buildGetSkillByName(
'cancelled-tool-skill',
['mcp__warehouse__query'],
skillId,
req.user!.id,
);
await expect(
initializeAgent(
{
req,
res,
agent,
loadTools,
signal: controller.signal,
endpointOption: { endpoint: EModelEndpoint.agents },
allowedProviders: new Set([Providers.OPENAI]),
isInitialAgent: true,
accessibleSkillIds: [skillId],
manualSkills: ['cancelled-tool-skill'],
},
{ ...db, listSkillsByAccess: emptyListSkillsByAccess, getSkillByName },
),
).rejects.toBe(reason);
expect(loadTools).toHaveBeenCalledTimes(1);
},
);
it('does not retry a resource recovery failure when execute_code is skill-added', async () => {
const { agent, req, res, loadTools, db } = createMocks();
agent.tools = ['web_search'];

View file

@ -1205,6 +1205,90 @@ describe('discoverConnectedAgents', () => {
},
);
it.each([
['handoff', [{ from: 'A', to: 'B', edgeType: 'handoff' as const }], undefined],
['legacy chain', undefined, ['B']],
])('propagates owning-run cancellation during %s discovery', async (_case, edges, agentIds) => {
const controller = new AbortController();
controller.abort();
await expect(
discoverConnectedAgents(
{
req: makeReq(),
res: makeRes(),
signal: controller.signal,
primaryConfig: makeConfig('A', edges),
agent_ids: agentIds,
allowedProviders: new Set(),
modelsConfig: { openai: ['gpt-4o'] },
loadTools: jest.fn(),
},
{
getAgent: jest.fn(async () => makeAgent('B', [])),
checkPermission: jest.fn().mockResolvedValue(true),
logViolation: jest.fn(),
db: {} as never,
},
),
).rejects.toBe(controller.signal.reason);
});
it.each(['getAgent', 'checkPermission', 'validateAgentModel', 'initializeAgent'] as const)(
'detaches promptly when cancellation occurs during %s',
async (stage) => {
const controller = new AbortController();
const reason = new Error(`stopped during ${stage}`);
let settlePending!: (value: unknown) => void;
const pending = new Promise<unknown>((resolve) => {
settlePending = resolve;
});
const getAgent = jest.fn(async () => makeAgent('B', []));
const checkPermission = jest.fn().mockResolvedValue(true);
if (stage === 'getAgent') {
getAgent.mockReturnValueOnce(pending as Promise<Agent>);
} else if (stage === 'checkPermission') {
checkPermission.mockReturnValueOnce(pending as Promise<boolean>);
} else if (stage === 'validateAgentModel') {
mockValidateAgentModel.mockReturnValueOnce(pending as Promise<{ isValid: boolean }>);
} else {
mockInitializeAgent.mockReturnValueOnce(pending as Promise<InitializedAgent>);
}
const discovery = discoverConnectedAgents(
{
req: makeReq(),
res: makeRes(),
signal: controller.signal,
primaryConfig: makeConfig('A', [{ from: 'A', to: 'B', edgeType: 'handoff' as const }]),
allowedProviders: new Set(),
modelsConfig: { openai: ['gpt-4o'] },
loadTools: jest.fn(),
},
{
getAgent,
checkPermission,
logViolation: jest.fn(),
db: {} as never,
},
);
await new Promise((resolve) => setImmediate(resolve));
controller.abort(reason);
await expect(discovery).rejects.toBe(reason);
if (stage === 'getAgent') {
settlePending(makeAgent('B', []));
} else if (stage === 'checkPermission') {
settlePending(true);
} else if (stage === 'validateAgentModel') {
settlePending({ isValid: true });
} else {
settlePending(makeConfig('B'));
}
},
);
it('skips when request has no authenticated user', async () => {
const primaryConfig = makeConfig('A', [{ from: 'A', to: 'B', edgeType: 'handoff' }]);
@ -1310,6 +1394,48 @@ describe('resolveSubagentGraphs', () => {
});
});
it('propagates owning-run cancellation while resolving a graph member', async () => {
const controller = new AbortController();
controller.abort();
const primaryConfig = makeConfig('A') as GraphSubagentHostConfig;
primaryConfig.subagents = {
enabled: true,
graphs: [
{
type: 'team',
name: 'Team',
description: 'A remote graph team',
agent_ids: ['A', 'B'],
edges: [{ from: 'A', to: 'B', edgeType: 'direct' }],
entry_agent_id: 'A',
result_agent_id: 'B',
},
],
};
await expect(
resolveSubagentGraphs(
{
req: makeReq(),
res: makeRes(),
signal: controller.signal,
primaryConfig,
rootConfigs: [primaryConfig],
allowedProviders: new Set(),
modelsConfig: { openai: ['gpt-4o'] },
loadTools: jest.fn(),
resourceType: 'remote_agent',
},
{
getAgent: jest.fn(async ({ id }: { id: string }) => makeAgent(id)),
checkPermission: jest.fn().mockResolvedValue(true),
logViolation: jest.fn(),
db: {} as never,
},
),
).rejects.toBe(controller.signal.reason);
});
it('does not charge initialized root members against the graph load budget', async () => {
const rootConfigs = Array.from({ length: MAX_SUBAGENT_GRAPH_NODES }, (_, index) => {
const config = makeConfig(`root_${index}`) as GraphSubagentHostConfig;

View file

@ -26,6 +26,7 @@ import { createEdgeCollector, resolveReachableGraph } from './edges';
import { isFatalAgentInitializationError } from './errors';
import { createConcurrencyLimiter } from '~/utils/promise';
import { createSequentialChainEdges } from './chain';
import { detachOnAbort } from '~/utils/promises';
const SUBAGENT_GRAPH_LOAD_CONCURRENCY = 4;
@ -55,6 +56,8 @@ export type CheckAgentPermission = (params: {
export interface DiscoverConnectedAgentsParams {
req: ServerRequest;
res: ServerResponse;
/** Owning run signal used to distinguish cancellation from dependency aborts. */
signal?: AbortSignal;
/** The already-initialized primary agent config (starting point for BFS). */
primaryConfig: InitializedAgent;
/**
@ -195,7 +198,7 @@ async function initializeReferencedAgent(
params: DiscoverConnectedAgentsParams,
deps: DiscoverConnectedAgentsDeps,
): Promise<{ agent: Agent; config: InitializedAgent } | null> {
const agent = await deps.getAgent({ id: agentId });
const agent = await detachOnAbort(deps.getAgent({ id: agentId }), params.signal);
if (!agent) {
logger.warn(`[initializeReferencedAgent] Agent ${agentId} not found, skipping`);
deps.onAgentSkipped?.(agentId);
@ -209,13 +212,16 @@ async function initializeReferencedAgent(
return null;
}
const hasAccess = await deps.checkPermission({
userId,
role: params.req.user?.role,
resourceType: params.resourceType ?? ResourceType.AGENT,
resourceId: agent._id,
requiredPermission: PermissionBits.VIEW,
});
const hasAccess = await detachOnAbort(
deps.checkPermission({
userId,
role: params.req.user?.role,
resourceType: params.resourceType ?? ResourceType.AGENT,
resourceId: agent._id,
requiredPermission: PermissionBits.VIEW,
}),
params.signal,
);
if (!hasAccess) {
logger.warn(`[initializeReferencedAgent] User ${userId} lacks VIEW access to agent ${agentId}`);
deps.onAgentSkipped?.(agentId);
@ -223,48 +229,55 @@ async function initializeReferencedAgent(
}
const validateAgentModel = deps.validateAgentModel ?? defaultValidateAgentModel;
const validation = await validateAgentModel({
req: params.req,
res: params.res,
agent,
modelsConfig: params.modelsConfig,
logViolation: deps.logViolation,
});
const validation = await detachOnAbort(
validateAgentModel({
req: params.req,
res: params.res,
agent,
modelsConfig: params.modelsConfig,
logViolation: deps.logViolation,
}),
params.signal,
);
if (!validation.isValid) {
throw new Error(validation.error?.message);
}
const scopedSkillIds = params.computeAccessibleSkillIds?.(agent);
const initializeAgent = deps.initializeAgent ?? defaultInitializeAgent;
const config = await initializeAgent(
{
req: params.req,
res: params.res,
agent,
loadTools: params.loadTools,
requestFiles: params.requestFiles,
conversationId: params.conversationId,
parentMessageId: params.parentMessageId,
requestBody: params.requestBody,
endpointOption: {
...(params.endpointOption ?? {}),
endpoint: EModelEndpoint.agents,
const config = await detachOnAbort(
initializeAgent(
{
req: params.req,
res: params.res,
agent,
loadTools: params.loadTools,
requestFiles: params.requestFiles,
conversationId: params.conversationId,
parentMessageId: params.parentMessageId,
requestBody: params.requestBody,
endpointOption: {
...(params.endpointOption ?? {}),
endpoint: EModelEndpoint.agents,
},
allowedProviders: params.allowedProviders,
accessibleSkillIds: scopedSkillIds,
skillAuthoringAvailable: params.computeSkillAuthoringAvailable?.(agent, scopedSkillIds),
skillStates: params.skillStates,
defaultActiveOnShare: params.defaultActiveOnShare,
codeEnvAvailable: params.codeEnvAvailable,
fileSearchAvailable: params.fileSearchAvailable,
resolveWebSearchGrant: params.resolveWebSearchGrant,
backgroundToolsAvailable: params.backgroundToolsAvailable,
toolIntentsAvailable: params.toolIntentsAvailable,
statefulSessionsAvailable: params.statefulSessionsAvailable,
allowedStatefulCodeEnvironments: params.allowedStatefulCodeEnvironments,
memoryAvailable: params.memoryAvailable,
signal: params.signal,
},
allowedProviders: params.allowedProviders,
accessibleSkillIds: scopedSkillIds,
skillAuthoringAvailable: params.computeSkillAuthoringAvailable?.(agent, scopedSkillIds),
skillStates: params.skillStates,
defaultActiveOnShare: params.defaultActiveOnShare,
codeEnvAvailable: params.codeEnvAvailable,
fileSearchAvailable: params.fileSearchAvailable,
resolveWebSearchGrant: params.resolveWebSearchGrant,
backgroundToolsAvailable: params.backgroundToolsAvailable,
toolIntentsAvailable: params.toolIntentsAvailable,
statefulSessionsAvailable: params.statefulSessionsAvailable,
allowedStatefulCodeEnvironments: params.allowedStatefulCodeEnvironments,
memoryAvailable: params.memoryAvailable,
},
deps.db,
deps.db,
),
params.signal,
);
deps.onAgentInitialized?.(agentId, agent, config);
return { agent, config };
@ -329,7 +342,7 @@ export async function resolveSubagentGraphs(
}
return resolved;
} catch (error) {
if (isFatalAgentInitializationError(error)) {
if (isFatalAgentInitializationError(error, { signal: params.signal })) {
throw error;
}
failedMemberIds.add(memberId);
@ -458,7 +471,7 @@ export async function discoverConnectedAgents(
collectEdges(agent.edges);
}
} catch (err) {
if (isFatalAgentInitializationError(err)) {
if (isFatalAgentInitializationError(err, { signal: params.signal })) {
throw err;
}
logger.error(`[discoverConnectedAgents] Error processing agent ${agentId}:`, err);
@ -475,7 +488,7 @@ export async function discoverConnectedAgents(
try {
await processAgent(agentId);
} catch (err) {
if (isFatalAgentInitializationError(err)) {
if (isFatalAgentInitializationError(err, { signal: params.signal })) {
throw err;
}
logger.error(`[discoverConnectedAgents] Error processing chain agent ${agentId}:`, err);

View file

@ -12,13 +12,27 @@ import {
} from './errors';
describe('isFatalAgentInitializationError', () => {
it.each([
ErrorTypes.RESOURCE_RECOVERY_REQUIRED,
ErrorTypes.STATEFUL_CODE_ENVIRONMENT_NOT_ALLOWED,
ErrorTypes.CODE_WORKSPACE_UNAVAILABLE,
AGENT_ATTACHMENT_LIMIT_EXCEEDED,
AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE,
])('classifies %s as fatal', (code) => {
it('propagates cancellation even when optional MCP fallback is allowed', () => {
const abort = new DOMException('Stopped', 'AbortError');
const controller = new AbortController();
expect(isFatalAgentInitializationError(abort, { signal: controller.signal })).toBe(false);
controller.abort(abort);
expect(
isFatalAgentInitializationError(abort, {
allowExpectedMCPFallback: true,
signal: controller.signal,
}),
).toBe(true);
});
it.each(
[
ErrorTypes.RESOURCE_RECOVERY_REQUIRED,
ErrorTypes.STATEFUL_CODE_ENVIRONMENT_NOT_ALLOWED,
ErrorTypes.CODE_WORKSPACE_UNAVAILABLE,
AGENT_ATTACHMENT_LIMIT_EXCEEDED,
AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE,
].filter((code): code is string => typeof code === 'string'),
)('classifies %s as fatal', (code) => {
expect(isFatalAgentInitializationError({ code })).toBe(true);
});
@ -38,6 +52,10 @@ describe('isFatalAgentInitializationError', () => {
expect(isFatalAgentInitializationError(error)).toBe(false);
},
);
it('does not classify a missing code as fatal when an enum member is unavailable', () => {
expect(isFatalAgentInitializationError(new Error('ordinary failure'))).toBe(false);
});
});
describe('LangChain provider error text', () => {

View file

@ -3,10 +3,20 @@ import {
parseLangChainErrorCode,
stripLangChainTroubleshootingUrl,
} from 'librechat-data-provider';
import { isOwnedAbortError } from '~/utils/errors';
export const AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE = 'AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE';
export const AGENT_ATTACHMENT_LIMIT_EXCEEDED = 'AGENT_ATTACHMENT_LIMIT_EXCEEDED';
const FATAL_AGENT_INITIALIZATION_CODES = new Set(
[
AGENT_ATTACHMENT_LIMIT_EXCEEDED,
ErrorTypes.RESOURCE_RECOVERY_REQUIRED,
ErrorTypes.STATEFUL_CODE_ENVIRONMENT_NOT_ALLOWED,
ErrorTypes.CODE_WORKSPACE_UNAVAILABLE,
].filter((code): code is string => typeof code === 'string'),
);
export function createStatefulCodeEnvironmentPolicyError(environment: string): Error {
return Object.assign(
new Error(`Stateful code environment is not allowed by this deployment: ${environment}`),
@ -19,6 +29,7 @@ export function createStatefulCodeEnvironmentPolicyError(environment: string): E
}
export interface FatalAgentInitializationOptions {
signal?: AbortSignal;
/**
* Skill `allowed-tools` may add an MCP tool beyond the agent's configured
* baseline. That union load is allowed to retry without the skill extras;
@ -46,10 +57,8 @@ export function isFatalAgentInitializationError(
): boolean {
const code = getErrorCode(error);
return (
code === AGENT_ATTACHMENT_LIMIT_EXCEEDED ||
code === ErrorTypes.RESOURCE_RECOVERY_REQUIRED ||
code === ErrorTypes.STATEFUL_CODE_ENVIRONMENT_NOT_ALLOWED ||
code === ErrorTypes.CODE_WORKSPACE_UNAVAILABLE ||
isOwnedAbortError(error, options.signal) ||
FATAL_AGENT_INITIALIZATION_CODES.has(code as string) ||
(code === AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE && options.allowExpectedMCPFallback !== true)
);
}

View file

@ -1,7 +1,7 @@
import { ErrorTypes } from 'librechat-data-provider';
import type { SafeErrorMetadata } from '../../utils/errors';
import type { ModelErrorTrackerCallback } from './tracker';
import { getSafeErrorMetadata, isAbortError } from '../../utils/errors';
import { getSafeErrorMetadata, isOwnedAbortError } from '../../utils/errors';
import { traceIdForMessage } from '../../langfuse/trace';
import { createModelErrorTracker } from './tracker';
import { resolveLangChainError } from '../errors';
@ -36,9 +36,9 @@ export interface TerminalRunErrorObserver {
readonly getUserFacingError: (error: unknown, fallback: () => string) => string;
}
/** A run cancellation requires both host-owned abort state and an abort-shaped rejection. */
/** A run cancellation requires host-owned abort state plus its own reason or an abort shape. */
export function isAgentRunCancellation(error: unknown, signal?: AbortSignal): boolean {
return signal?.aborted === true && isAbortError(error);
return isOwnedAbortError(error, signal);
}
export function getUpstreamModelErrorMetadata(

View file

@ -790,6 +790,8 @@ export function optsOutOfAttachedCodeEnvironment(
* Matches the CJS signature from api/server/services/Endpoints/agents/agent.js
*/
export interface InitializeAgentParams {
/** Cancellation signal owned by the run performing initialization. */
signal?: AbortSignal;
/** Explicit transport-free execution state. */
runtime?: AgentExecutionContext;
/** Request-backed compatibility adapter for callers not yet migrated. */
@ -1815,7 +1817,12 @@ export async function initializeAgent(
try {
loadToolsResult = await callLoadTools(requestedToolNames);
} catch (err) {
if (isFatalAgentInitializationError(err, { allowExpectedMCPFallback: true })) {
if (
isFatalAgentInitializationError(err, {
signal: params.signal,
allowExpectedMCPFallback: true,
})
) {
throw err;
}
if (extraAllowedToolNames.length > 0) {

View file

@ -187,6 +187,8 @@ interface InitializedAgent {
interface InitializeAgentParams {
req: Request;
res: ServerResponse;
/** Cancellation signal owned by this chat-completion request. */
signal?: CoreInitializeAgentParams['signal'];
agent: Agent;
conversationId?: string | null;
parentMessageId?: string | null;
@ -777,6 +779,7 @@ export async function createAgentChatCompletion(
allowedStatefulCodeEnvironments,
backgroundToolsAvailable,
toolIntentsAvailable,
signal: abortController.signal,
});
const modelBoundAgents = collectReachableAgents([initializedAgent]);

View file

@ -11,7 +11,12 @@ import type {
OAuthStoredClientMetadata,
OAuthClientSource,
} from '~/mcp/oauth';
import type { OboTokenResolver, OboTrustChecker, UpstreamTokenProvider } from '~/mcp/oauth/obo';
import type {
OboTokenResolver,
OboTrustChecker,
UpstreamTokenProvider,
UpstreamTokenProviderResolver,
} from '~/mcp/oauth/obo';
import type { AuthIdentityContext } from '~/utils/identity';
import type { FlowStateManager } from '~/flow/manager';
import type * as t from './types';
@ -43,7 +48,9 @@ import {
createDeadlineAbortSignal,
} from './utils';
import { PENDING_STALE_MS, FlowStateNotFoundError, normalizeExpiresAt } from '~/flow/manager';
import { createLazyOboUpstreamTokenProvider, awaitOboOperation } from '~/mcp/oauth/obo';
import { preProcessGraphTokens } from '~/utils/graph';
import { isAbortError } from '~/utils/errors';
import { MCPConnection } from './connection';
import { processMCPEnv } from '~/utils';
import { mcpConfig } from './mcpConfig';
@ -103,6 +110,7 @@ export class MCPConnectionFactory {
protected readonly oboTokenResolver?: OboTokenResolver;
protected readonly oboTrustChecker?: OboTrustChecker;
protected upstreamTokenProvider?: UpstreamTokenProvider;
protected upstreamTokenProviderResolver?: UpstreamTokenProviderResolver;
protected readonly oboIdentityContext?: AuthIdentityContext;
/** Why the OBO re-exchange failed, when that is more actionable than the server's 401. */
private oboRefreshError?: Error;
@ -612,6 +620,7 @@ export class MCPConnectionFactory {
this.user = options?.user;
this.upstreamTokenProvider = options?.upstreamTokenProvider;
this.upstreamTokenProviderResolver = options?.upstreamTokenProviderResolver;
if (options != null && 'useOAuth' in options) {
this.useOAuth = true;
@ -641,6 +650,12 @@ export class MCPConnectionFactory {
return null;
}
if (!this.upstreamTokenProvider && this.upstreamTokenProviderResolver) {
this.upstreamTokenProvider = createLazyOboUpstreamTokenProvider(
this.upstreamTokenProviderResolver,
this.signal,
);
}
if (!this.upstreamTokenProvider) {
throw new Error(
`${this.logPrefix} Internal: upstreamTokenProvider not plumbed for OBO connection. ` +
@ -651,11 +666,14 @@ export class MCPConnectionFactory {
if (this.oboTrustChecker) {
const config = this.serverConfig as t.ParsedServerConfig;
const trusted = await this.oboTrustChecker({
source: config.source,
author: config.author,
dbId: config.dbId,
});
const trusted = await awaitOboOperation(
this.oboTrustChecker({
source: config.source,
author: config.author,
dbId: config.dbId,
}),
this.signal,
);
if (!trusted) {
logger.warn(
`${this.logPrefix} OBO config not trusted (author lacks CONFIGURE_OBO permission); skipping OBO token exchange`,
@ -665,13 +683,16 @@ export class MCPConnectionFactory {
}
logger.info(`${this.logPrefix} Resolving OBO token for scopes: ${oboConfig.scopes}`);
return resolveOboToken(
this.user,
oboConfig,
this.oboTokenResolver,
this.upstreamTokenProvider,
this.oboIdentityContext,
forceRefresh,
return awaitOboOperation(
resolveOboToken(
this.user,
oboConfig,
this.oboTokenResolver,
this.upstreamTokenProvider,
this.oboIdentityContext,
forceRefresh,
),
this.signal,
);
}
@ -680,7 +701,7 @@ export class MCPConnectionFactory {
return !!this.serverConfig.obo && !!this.oboTokenResolver && !!this.user;
}
protected createOboConnectionError(error: OboTokenResolutionError): Error {
protected createOboConnectionError(error: OboTokenResolutionError): OboTokenResolutionError {
let recoveryHint = 'Re-authenticate the user and retry.';
if (error.retryable) {
@ -689,8 +710,11 @@ export class MCPConnectionFactory {
recoveryHint = 'Re-authenticate the user or verify the configured OBO scopes and retry.';
}
return new Error(
return new OboTokenResolutionError(
error.reason,
`${error.userMessage} Unable to connect to OBO server "${this.serverName}". ${recoveryHint}`,
error.retryable,
error,
);
}
@ -784,6 +808,7 @@ export class MCPConnectionFactory {
this.oauthEnd = undefined;
this.returnOnOAuth = false;
this.upstreamTokenProvider = undefined;
this.upstreamTokenProviderResolver = undefined;
}
private getServerUrl(): string | undefined {
@ -1438,7 +1463,11 @@ export class MCPConnectionFactory {
logger.info(`${this.logPrefix} OBO token re-exchanged; retrying connection`);
connection.emit('oauthHandled');
} catch (error) {
logger.error(`${this.logPrefix} OBO token re-exchange failed`, error);
if (isAbortError(error)) {
logger.debug(`${this.logPrefix} OBO token re-exchange cancelled`);
} else {
logger.error(`${this.logPrefix} OBO token re-exchange failed`, error);
}
/**
* `connectClient` rejects its handling promise with this error and then
* rethrows the server's original 401, so a diagnosis like an unrefreshable
@ -1465,6 +1494,11 @@ export class MCPConnectionFactory {
if (error instanceof Error) {
return error;
}
if (isAbortError(error)) {
return Object.assign(new Error('The operation was aborted.', { cause: error }), {
name: 'AbortError',
});
}
return new Error(`OBO token re-exchange failed for "${this.serverName}".`);
}

View file

@ -4,7 +4,12 @@ import { Permissions, PermissionTypes } from 'librechat-data-provider';
import { CallToolResultSchema, ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
import type { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';
import type { TokenMethods, IUser } from '@librechat/data-schemas';
import type { OboTokenResolver, OboTrustChecker, UpstreamTokenProvider } from '~/mcp/oauth/obo';
import type {
OboTokenResolver,
OboTrustChecker,
UpstreamTokenProvider,
UpstreamTokenProviderResolver,
} from '~/mcp/oauth/obo';
import type { AuthIdentityContext } from '~/utils/identity';
import type { GraphTokenResolver } from '~/utils/graph';
import type { FlowStateManager } from '~/flow/manager';
@ -25,6 +30,7 @@ import {
import { getMCPAppToolsPublicationGeneration, getMCPToolsChangedGeneration } from './toolsChanged';
import { MCPAuthenticationRejectedError, isMCPTransportAuthenticationError } from './errors';
import { resolveDirectOpenIDBearerConfig, usesDirectOpenIDBearerRecovery } from './openid';
import { createLazyOboUpstreamTokenProvider, awaitOboOperation } from '~/mcp/oauth/obo';
import { MCPServersInitializer } from './registry/MCPServersInitializer';
import { OboTokenResolutionError, resolveOboToken } from '~/mcp/oauth';
import { MCPServerCatalogRecoveryTracker } from './catalog/recovery';
@ -36,7 +42,7 @@ import { MCPConnectionFactory } from './MCPConnectionFactory';
import { processMCPEnv, isPluginSourced } from '~/utils/env';
import { OAuthLifecycleRelay } from './oauth/pending';
import { preProcessGraphTokens } from '~/utils/graph';
import { isAbortError } from '~/utils/errors';
import { isOwnedAbortError } from '~/utils/errors';
import { formatToolContent } from './parsers';
import { MCPConnection } from './connection';
import { mcpConfig } from './mcpConfig';
@ -500,6 +506,7 @@ export class MCPManager extends UserConnectionManager {
requestBody: args.requestBody,
graphTokenResolver: args.graphTokenResolver,
upstreamTokenProvider: args.upstreamTokenProvider,
upstreamTokenProviderResolver: args.upstreamTokenProviderResolver,
connectionTimeout: args.connectionTimeout,
deadlineMs: args.deadlineMs,
signal: args.signal,
@ -535,6 +542,7 @@ export class MCPManager extends UserConnectionManager {
oboTokenResolver: args.oboTokenResolver,
oboTrustChecker: args.oboTrustChecker,
upstreamTokenProvider: args.upstreamTokenProvider,
upstreamTokenProviderResolver: args.upstreamTokenProviderResolver,
oboIdentityContext: args.oboIdentityContext,
});
@ -841,6 +849,7 @@ Please follow these instructions when using tools from the respective MCP server
requestScopedConnections,
graphTokenResolver,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
onOAuthCredentialsChanged,
onOAuthCredentialsChanging,
@ -860,6 +869,7 @@ Please follow these instructions when using tools from the respective MCP server
requestScopedConnections?: t.RequestScopedMCPConnectionStore;
graphTokenResolver?: GraphTokenResolver;
upstreamTokenProvider?: UpstreamTokenProvider;
upstreamTokenProviderResolver?: UpstreamTokenProviderResolver;
oboIdentityContext?: AuthIdentityContext;
onOAuthCredentialsChanged?: t.UserConnectionContext['onOAuthCredentialsChanged'];
onOAuthCredentialsChanging?: t.UserConnectionContext['onOAuthCredentialsChanging'];
@ -919,6 +929,7 @@ Please follow these instructions when using tools from the respective MCP server
requestScopedConnections,
graphTokenResolver,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
onOAuthCredentialsChanged,
onOAuthCredentialsChanging,
@ -1093,6 +1104,7 @@ Please follow these instructions when using tools from the respective MCP server
oboTokenResolver,
oboTrustChecker,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
onOAuthCredentialsChanged,
onOAuthCredentialsChanging,
@ -1116,6 +1128,7 @@ Please follow these instructions when using tools from the respective MCP server
oboTokenResolver?: OboTokenResolver;
oboTrustChecker?: OboTrustChecker;
upstreamTokenProvider?: UpstreamTokenProvider;
upstreamTokenProviderResolver?: UpstreamTokenProviderResolver;
oboIdentityContext?: AuthIdentityContext;
onOAuthCredentialsChanged?: t.UserConnectionContext['onOAuthCredentialsChanged'];
onOAuthCredentialsChanging?: t.UserConnectionContext['onOAuthCredentialsChanging'];
@ -1180,6 +1193,7 @@ Please follow these instructions when using tools from the respective MCP server
oboTokenResolver,
oboTrustChecker,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
onOAuthCredentialsChanged,
onOAuthCredentialsChanging,
@ -1272,6 +1286,7 @@ Please follow these instructions when using tools from the respective MCP server
const oboConfig = rawConfig.obo;
const usesObo = Boolean(oboConfig && oboTokenResolver && user);
let oboUpstreamTokenProvider = upstreamTokenProvider;
/**
* Resolves the downstream token for this call and installs it as the request
@ -1283,7 +1298,13 @@ Please follow these instructions when using tools from the respective MCP server
if (!oboConfig || !oboTokenResolver || !user) {
return;
}
if (!upstreamTokenProvider) {
if (!oboUpstreamTokenProvider && upstreamTokenProviderResolver) {
oboUpstreamTokenProvider = createLazyOboUpstreamTokenProvider(
upstreamTokenProviderResolver,
options?.signal,
);
}
if (!oboUpstreamTokenProvider) {
throw new McpError(
ErrorCode.InternalError,
`${logPrefix} Internal: upstreamTokenProvider not plumbed for OBO tool call. ` +
@ -1309,13 +1330,16 @@ Please follow these instructions when using tools from the respective MCP server
}
let oboTokens: MCPOAuthTokens;
try {
oboTokens = await resolveOboToken(
user,
oboConfig,
oboTokenResolver,
upstreamTokenProvider,
oboIdentityContext,
forceRefresh,
oboTokens = await awaitOboOperation(
resolveOboToken(
user,
oboConfig,
oboTokenResolver,
oboUpstreamTokenProvider,
oboIdentityContext,
forceRefresh,
),
options?.signal,
);
} catch (error) {
if (error instanceof OboTokenResolutionError) {
@ -1425,6 +1449,7 @@ Please follow these instructions when using tools from the respective MCP server
requestScopedConnections,
graphTokenResolver,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
onOAuthCredentialsChanged,
onOAuthCredentialsChanging,
@ -1515,6 +1540,7 @@ Please follow these instructions when using tools from the respective MCP server
requestScopedConnections,
graphTokenResolver,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
onOAuthCredentialsChanged,
onOAuthCredentialsChanging,
@ -1594,7 +1620,7 @@ Please follow these instructions when using tools from the respective MCP server
* cancellation working, not a fault, so it stays out of the error log.
* The error must look like an abort too — a real failure can reject in
* the same tick as the Stop and has to stay visible. */
if (options?.signal?.aborted === true && isAbortError(error)) {
if (isOwnedAbortError(error, options?.signal)) {
logger.debug(`${logPrefix}[${toolName}] Tool call cancelled by user abort`);
throw error;
}

View file

@ -583,6 +583,7 @@ export abstract class UserConnectionManager {
oboTokenResolver,
oboTrustChecker,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
onOAuthCredentialsChanged,
onOAuthCredentialsChanging,
@ -858,6 +859,7 @@ export abstract class UserConnectionManager {
oboTokenResolver: oboTokenResolver,
oboTrustChecker: oboTrustChecker,
upstreamTokenProvider: upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
graphTokenResolver,
returnOnOAuth: returnOnOAuth,
@ -875,6 +877,7 @@ export abstract class UserConnectionManager {
requestBody,
graphTokenResolver,
upstreamTokenProvider,
upstreamTokenProviderResolver,
connectionTimeout,
signal,
};
@ -948,6 +951,7 @@ export abstract class UserConnectionManager {
oboTokenResolver,
oboTrustChecker,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
signal,
returnOnOAuth,

View file

@ -5551,6 +5551,165 @@ describe('MCPConnectionFactory', () => {
);
});
it('resolves a provider lazily after the server is confirmed to use OBO', async () => {
const { resolveOboToken } = jest.requireMock('~/mcp/oauth') as {
resolveOboToken: jest.Mock;
};
resolveOboToken.mockImplementationOnce(async (_user, _config, _exchange, provider) => {
await provider();
return {
access_token: 'connection-time-obo-token',
token_type: 'Bearer',
obtained_at: Date.now(),
expires_at: Date.now() + 3600_000,
};
});
const upstreamTokenProvider = jest.fn();
const upstreamTokenProviderResolver = jest.fn().mockResolvedValue(upstreamTokenProvider);
const oboTokenResolver = jest.fn();
await MCPConnectionFactory.create(
{ serverName: 'obo-srv', serverConfig: oboServerConfig },
{
useOAuth: true,
user: mockUser,
flowManager: mockFlowManager,
tokenMethods: {
findToken: jest.fn(),
createToken: jest.fn(),
updateToken: jest.fn(),
deleteTokens: jest.fn(),
},
oboTokenResolver,
upstreamTokenProviderResolver,
},
);
expect(upstreamTokenProviderResolver).toHaveBeenCalledTimes(1);
expect(resolveOboToken).toHaveBeenCalledWith(
mockUser,
oboServerConfig.obo,
oboTokenResolver,
expect.any(Function),
undefined,
false,
);
});
it.each([undefined, new Error('owner stopped'), 'stopped'])(
'detaches connection initialization from an uncooperative OBO exchange (%s)',
async (reason) => {
const controller = new AbortController();
const { resolveOboToken } = jest.requireMock('~/mcp/oauth');
resolveOboToken.mockImplementationOnce(() => {
queueMicrotask(() => controller.abort(reason));
return new Promise(() => {});
});
await expect(
MCPConnectionFactory.create(
{ serverName: 'obo-srv', serverConfig: oboServerConfig },
{
useOAuth: true,
user: mockUser,
flowManager: mockFlowManager,
tokenMethods: {
findToken: jest.fn(),
createToken: jest.fn(),
updateToken: jest.fn(),
deleteTokens: jest.fn(),
},
signal: controller.signal,
oboTokenResolver: jest.fn(),
upstreamTokenProvider: jest.fn(),
},
),
).rejects.toMatchObject({ name: 'AbortError' });
},
);
it.each([undefined, new Error('owner stopped during trust check'), 'stopped'])(
'detaches connection initialization from a pending OBO trust check (%s)',
async (reason) => {
const controller = new AbortController();
const oboTrustChecker = jest.fn().mockImplementation(
() =>
new Promise<boolean>(() => {
queueMicrotask(() => controller.abort(reason));
}),
);
const { resolveOboToken } = jest.requireMock('~/mcp/oauth');
resolveOboToken.mockClear();
await expect(
MCPConnectionFactory.create(
{ serverName: 'obo-srv', serverConfig: oboServerConfig },
{
useOAuth: true,
user: mockUser,
flowManager: mockFlowManager,
tokenMethods: {
findToken: jest.fn(),
createToken: jest.fn(),
updateToken: jest.fn(),
deleteTokens: jest.fn(),
},
signal: controller.signal,
oboTokenResolver: jest.fn(),
upstreamTokenProvider: jest.fn(),
oboTrustChecker,
},
),
).rejects.toMatchObject({ name: 'AbortError' });
expect(resolveOboToken).not.toHaveBeenCalled();
},
);
it('does not look up credentials for an untrusted OBO configuration', async () => {
const upstreamTokenProviderResolver = jest.fn();
const oboTrustChecker = jest.fn().mockResolvedValue(false);
const { resolveOboToken } = jest.requireMock('~/mcp/oauth');
resolveOboToken.mockClear();
await expect(
MCPConnectionFactory.create(
{ serverName: 'obo-srv', serverConfig: oboServerConfig },
{
useOAuth: true,
user: mockUser,
flowManager: mockFlowManager,
tokenMethods: {
findToken: jest.fn(),
createToken: jest.fn(),
updateToken: jest.fn(),
deleteTokens: jest.fn(),
},
oboTokenResolver: jest.fn(),
oboTrustChecker,
upstreamTokenProviderResolver,
},
),
).rejects.toThrow('OBO token exchange failed');
expect(oboTrustChecker).toHaveBeenCalled();
expect(upstreamTokenProviderResolver).not.toHaveBeenCalled();
expect(resolveOboToken).not.toHaveBeenCalled();
});
it('does not invoke the resolver for a non-OBO direct-bearer server', async () => {
const directBearerConfig = {
type: 'streamable-http' as const,
url: 'https://direct.example.com',
headers: { Authorization: 'Bearer static-token' },
} as unknown as t.MCPOptions;
mockProcessMCPEnv.mockReturnValue(directBearerConfig);
const upstreamTokenProviderResolver = jest.fn();
await MCPConnectionFactory.create(
{ serverName: 'direct-srv', serverConfig: directBearerConfig },
{ user: mockUser, upstreamTokenProviderResolver },
);
expect(upstreamTokenProviderResolver).not.toHaveBeenCalled();
});
it('throws an internal error when upstreamTokenProvider is omitted on an OBO connection', async () => {
const { resolveOboToken } = jest.requireMock('~/mcp/oauth') as {
resolveOboToken: jest.Mock;
@ -5578,6 +5737,52 @@ describe('MCPConnectionFactory', () => {
).rejects.toThrow(/upstreamTokenProvider not plumbed/);
expect(resolveOboToken).not.toHaveBeenCalled();
});
it('preserves OBO resolution failure metadata at connection establishment', async () => {
const { resolveOboToken } = jest.requireMock('~/mcp/oauth') as {
resolveOboToken: jest.Mock;
};
const OboError = OboTokenResolutionError as unknown as jest.Mock;
OboError.mockImplementation(
(reason: string, userMessage: string, retryable = false, cause?: unknown) => {
const error = new Error(userMessage);
Object.setPrototypeOf(error, OboError.prototype);
return Object.assign(error, {
name: 'OboTokenResolutionError',
reason,
retryable,
userMessage,
cause,
});
},
);
resolveOboToken.mockRejectedValueOnce(
new OboTokenResolutionError('session_refresh_failed', 'Sign-in expired.'),
);
await expect(
MCPConnectionFactory.create(
{ serverName: 'obo-srv', serverConfig: oboServerConfig },
{
useOAuth: true,
user: mockUser,
flowManager: mockFlowManager,
tokenMethods: {
findToken: jest.fn(),
createToken: jest.fn(),
updateToken: jest.fn(),
deleteTokens: jest.fn(),
},
oboTokenResolver: jest.fn(),
upstreamTokenProvider: jest.fn(),
},
),
).rejects.toMatchObject({
name: 'OboTokenResolutionError',
reason: 'session_refresh_failed',
retryable: false,
});
});
});
describe('OBO authentication failures', () => {
@ -5674,6 +5879,18 @@ describe('MCPConnectionFactory', () => {
expect(mockConnectionInstance.stopReconnecting).not.toHaveBeenCalled();
});
it('preserves a cancelled re-exchange without logging a sign-in failure', async () => {
const abort = new DOMException('Stopped', 'AbortError');
resolveOboToken.mockResolvedValueOnce(connectionTokens).mockRejectedValueOnce(abort);
mockConnectionInstance.connect.mockImplementationOnce(async () => {
await getAuthHandler()();
throw new Error('HTTP 401 Unauthorized');
});
await expect(createOboConnection()).rejects.toMatchObject({ name: 'AbortError' });
expect(mockLogger.error).not.toHaveBeenCalled();
expect(mockConnectionInstance.stopReconnecting).toHaveBeenCalled();
});
it('retires the connection when the re-exchange fails', async () => {
resolveOboToken
.mockResolvedValueOnce(connectionTokens)

View file

@ -2855,6 +2855,102 @@ describe('MCPManager', () => {
expect(mockConnection.client.request).toHaveBeenCalled();
});
it.each([undefined, new Error('owner stopped'), 'stopped'])(
'detaches a cancelled tool from an uncooperative OBO exchange (%s)',
async (reason) => {
const controller = new AbortController();
mockResolveOboToken.mockImplementationOnce(() => {
queueMicrotask(() => controller.abort(reason));
return new Promise(() => {});
});
mockAppConnections({ get: jest.fn().mockResolvedValue(mockConnection) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
jest.spyOn(manager, 'getUserConnection').mockResolvedValue(mockConnection);
await expect(
manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
options: { signal: controller.signal },
oboTokenResolver: mockOboTokenResolver,
upstreamTokenProvider: mockUpstreamTokenProvider,
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
}),
).rejects.toMatchObject({ name: 'AbortError' });
expect(mockConnection.client.request).not.toHaveBeenCalled();
},
);
it('lazily resolves the upstream provider for an OBO tool call', async () => {
mockResolveOboToken.mockImplementationOnce(async (_user, _config, _exchange, provider) => {
await provider();
return {
access_token: 'fresh-obo-token',
token_type: 'Bearer',
obtained_at: Date.now(),
expires_at: Date.now() + 3600_000,
};
});
mockAppConnections({ get: jest.fn().mockResolvedValue(mockConnection) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
jest.spyOn(manager, 'getUserConnection').mockResolvedValue(mockConnection);
const upstreamTokenProviderResolver = jest.fn().mockResolvedValue(mockUpstreamTokenProvider);
await manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
oboTokenResolver: mockOboTokenResolver,
upstreamTokenProviderResolver,
});
expect(upstreamTokenProviderResolver).toHaveBeenCalledTimes(1);
expect(mockResolveOboToken).toHaveBeenCalledWith(
mockUser,
serverConfig.obo,
mockOboTokenResolver,
expect.any(Function),
undefined,
false,
);
});
it('does not resolve an OBO provider for a non-OBO tool call', async () => {
const directConfig = {
type: 'streamable-http',
url: 'https://direct.example.com',
headers: { Authorization: 'Bearer static-token' },
} as t.ParsedServerConfig;
mockAppConnections({ get: jest.fn().mockResolvedValue(mockConnection) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(directConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
jest.spyOn(manager, 'getUserConnection').mockResolvedValue(mockConnection);
const upstreamTokenProviderResolver = jest.fn();
await manager.callTool({
user: mockUser as IUser,
serverName,
serverConfig: directConfig,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
upstreamTokenProviderResolver,
});
expect(upstreamTokenProviderResolver).not.toHaveBeenCalled();
});
it('passes the OBO-cleaned config into runtime header processing', async () => {
const mixedConfig = {
...serverConfig,

View file

@ -3,7 +3,35 @@ import { SseError } from '@modelcontextprotocol/sdk/client/sse.js';
import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
import { UnauthorizedError } from '@modelcontextprotocol/sdk/client/auth.js';
import { StreamableHTTPError } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import { isMCPTransportAuthenticationError, MCPTransportAuthenticationError } from './errors';
import {
isMCPTransportAuthenticationError,
MCPTransportAuthenticationError,
isMCPInitializationError,
} from './errors';
import { OboTokenResolutionError } from './oauth/obo';
describe('MCP initialization propagation', () => {
it.each([
new DOMException('Stopped', 'AbortError'),
new OboTokenResolutionError('session_refresh_failed', 'Retry later', true),
new OboTokenResolutionError('session_refresh_failed', 'Sign in', false),
])('propagates cancellation and typed credential failures: %s', (error) => {
const controller = new AbortController();
controller.abort(error);
expect(isMCPInitializationError(error, controller.signal)).toBe(true);
});
it('does not confuse a dependency abort with cancellation of a live run', () => {
expect(
isMCPInitializationError(
new DOMException('timeout', 'AbortError'),
new AbortController().signal,
),
).toBe(false);
});
it('keeps unrelated optional-tool failures eligible for fallback', () => {
expect(isMCPInitializationError(new Error('optional tool unavailable'))).toBe(false);
});
});
describe('direct bearer transport rejection classification', () => {
it.each([

View file

@ -5,6 +5,20 @@ import { McpError } from '@modelcontextprotocol/sdk/types.js';
import { SseError } from '@modelcontextprotocol/sdk/client/sse.js';
import { UnauthorizedError } from '@modelcontextprotocol/sdk/client/auth.js';
import { StreamableHTTPError } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import { OpenIDReauthRequiredError } from '~/utils/oidc';
import { OboTokenResolutionError } from './oauth/obo';
import { isOwnedAbortError } from '~/utils/errors';
/** These outcomes must reach the owning run instead of hiding a tool during discovery. */
export function isMCPInitializationError(error: unknown, signal?: AbortSignal): boolean {
return (
isOwnedAbortError(error, signal) ||
error instanceof MCPAuthenticationRejectedError ||
error instanceof MCPAuthenticationRefreshError ||
error instanceof OboTokenResolutionError ||
error instanceof OpenIDReauthRequiredError
);
}
export const MCPErrorCodes = {
DOMAIN_NOT_ALLOWED: 'MCP_DOMAIN_NOT_ALLOWED',

View file

@ -1,7 +1,12 @@
import { Permissions, PermissionTypes } from 'librechat-data-provider';
import type { IUser } from '@librechat/data-schemas';
import type { OboTokenResolver, UpstreamTokenProvider } from './obo';
import { isOboConfigStillTrusted, resolveOboToken } from './obo';
import {
createLazyOboUpstreamTokenProvider,
isOboConfigStillTrusted,
resolveOboToken,
selectMCPUpstreamTokenProvider,
} from './obo';
jest.mock('@librechat/data-schemas', () => ({
logger: {
@ -33,6 +38,36 @@ const liveTokens = {
const liveProvider: UpstreamTokenProvider = jest.fn().mockResolvedValue(liveTokens);
const nullProvider: UpstreamTokenProvider = jest.fn().mockResolvedValue(null);
describe('selectMCPUpstreamTokenProvider', () => {
it.each([false, true])(
'keeps explicit credentials regardless of deferred OBO lookup (%s)',
(deferred) => {
const createSessionProvider = jest.fn();
expect(
selectMCPUpstreamTokenProvider({
upstreamTokenProvider: liveProvider,
upstreamTokenProviderResolver: deferred ? jest.fn() : undefined,
createSessionProvider,
}),
).toBe(liveProvider);
expect(createSessionProvider).not.toHaveBeenCalled();
},
);
it('creates browser credentials only when no deferred OBO source is present', () => {
const createSessionProvider = jest.fn().mockReturnValue(liveProvider);
expect(
selectMCPUpstreamTokenProvider({
upstreamTokenProviderResolver: jest.fn(),
createSessionProvider,
}),
).toBeUndefined();
expect(createSessionProvider).not.toHaveBeenCalled();
expect(selectMCPUpstreamTokenProvider({ createSessionProvider })).toBe(liveProvider);
expect(createSessionProvider).toHaveBeenCalledTimes(1);
});
});
describe('resolveOboToken', () => {
const mockUser: Partial<IUser> = {
id: 'user-123',
@ -61,6 +96,123 @@ describe('resolveOboToken', () => {
});
});
it.each([undefined, new Error('stopped by owner')])(
'preserves pending lookup cancellation (%s)',
async (reason) => {
const controller = new AbortController();
const lookup = jest.fn(() => new Promise<UpstreamTokenProvider>(() => {}));
const result = resolveOboToken(
mockUser as IUser,
oboConfig,
mockResolver,
createLazyOboUpstreamTokenProvider(lookup, controller.signal),
);
await Promise.resolve();
controller.abort(reason);
await expect(result).rejects.toMatchObject({ name: 'AbortError' });
expect(mockResolver).not.toHaveBeenCalled();
expect(jest.requireMock('@librechat/data-schemas').logger.error).not.toHaveBeenCalled();
},
);
it('stops waiting for token retrieval that ignores cancellation', async () => {
const controller = new AbortController();
let started!: () => void;
const retrieving = new Promise<void>((resolve) => {
started = resolve;
});
const provider = jest.fn(() => {
started();
return new Promise<null>(() => {});
});
const result = resolveOboToken(
mockUser as IUser,
oboConfig,
mockResolver,
createLazyOboUpstreamTokenProvider(async () => provider, controller.signal),
);
await retrieving;
controller.abort();
await expect(result).rejects.toMatchObject({ name: 'AbortError' });
expect(mockResolver).not.toHaveBeenCalled();
});
it('preserves cancellation during token retrieval and exchange', async () => {
const abort = new DOMException('Stopped', 'AbortError');
const provider = jest.fn().mockRejectedValue(abort);
await expect(
resolveOboToken(mockUser as IUser, oboConfig, mockResolver, provider),
).rejects.toBe(abort);
(mockResolver as jest.Mock).mockRejectedValueOnce(abort);
await expect(
resolveOboToken(mockUser as IUser, oboConfig, mockResolver, liveProvider),
).rejects.toBe(abort);
expect(jest.requireMock('@librechat/data-schemas').logger.error).not.toHaveBeenCalled();
});
it('retries failed lookups but shares each in-flight attempt', async () => {
const lookup = jest
.fn()
.mockRejectedValueOnce(Object.assign(new Error('unavailable'), { status: 503 }))
.mockResolvedValue(liveProvider);
const provider = createLazyOboUpstreamTokenProvider(lookup);
const failed = await Promise.allSettled([provider(), provider()]);
expect(failed.map((result) => result.status)).toEqual(['rejected', 'rejected']);
expect(lookup).toHaveBeenCalledTimes(1);
await expect(
resolveOboToken(mockUser as IUser, oboConfig, mockResolver, provider),
).resolves.toMatchObject({ access_token: 'exchanged-mcp-token' });
expect(lookup).toHaveBeenCalledTimes(2);
});
it.each([false, true])('preserves lookup failure retryability (%s)', async (retryable) => {
const lookup = jest
.fn()
.mockRejectedValue(
Object.assign(new Error('credential lookup failed'), { status: retryable ? 503 : 401 }),
);
await expect(
resolveOboToken(
mockUser as IUser,
oboConfig,
mockResolver,
createLazyOboUpstreamTokenProvider(lookup),
),
).rejects.toMatchObject({ reason: 'session_refresh_failed', retryable });
expect(mockResolver).not.toHaveBeenCalled();
});
it('does not fall back to a snapshot when durable credential lookup returns no provider', async () => {
mockExtractOpenIDTokenInfo.mockReturnValue({ accessToken: 'stale-snapshot' });
const lookup = jest.fn().mockResolvedValue(undefined);
await expect(
resolveOboToken(
mockUser as IUser,
oboConfig,
mockResolver,
createLazyOboUpstreamTokenProvider(lookup),
),
).rejects.toMatchObject({ reason: 'session_refresh_failed', retryable: false });
expect(mockExtractOpenIDTokenInfo).not.toHaveBeenCalled();
expect(mockResolver).not.toHaveBeenCalled();
});
it('does not look up credentials after cancellation', async () => {
const controller = new AbortController();
controller.abort();
const lookup = jest.fn();
await expect(createLazyOboUpstreamTokenProvider(lookup, controller.signal)()).rejects.toThrow();
expect(lookup).not.toHaveBeenCalled();
});
it('shares lookup while obtaining fresh tokens on every invocation', async () => {
const lookup = jest.fn().mockResolvedValue(liveProvider);
const provider = createLazyOboUpstreamTokenProvider(lookup);
await Promise.all([provider(), provider()]);
expect(lookup).toHaveBeenCalledTimes(1);
expect(liveProvider).toHaveBeenCalledTimes(2);
});
it('throws missing_upstream_token when provider returns null and no federated fallback', async () => {
await expect(
resolveOboToken(mockUser as IUser, oboConfig, mockResolver, nullProvider),

View file

@ -7,6 +7,8 @@ import type { OpenIDTokenInfo } from '~/utils/oidc';
import type { MCPOAuthTokens } from './types';
import { getSkewedTokenExpiresAtMs, getTokenExpiresAtMs } from '~/oauth/expiry';
import { extractOpenIDTokenInfo, isOpenIDTokenValid } from '~/utils/oidc';
import { detachOnAbort } from '~/utils/promises';
import { isAbortError } from '~/utils/errors';
export interface OboConfig {
scopes: string;
@ -43,6 +45,82 @@ export type UpstreamTokenProvider = (options?: {
signal?: AbortSignal;
}) => Promise<OIDCTokens | null>;
/** Lazily supplies a renewable upstream-token provider when an OBO server actually needs one. */
export type UpstreamTokenProviderResolver = (options?: {
signal?: AbortSignal;
}) => UpstreamTokenProvider | undefined | Promise<UpstreamTokenProvider | undefined>;
/** Scheduled OBO credentials must not replace the browser's direct-bearer source. */
export function selectMCPUpstreamTokenProvider({
upstreamTokenProvider,
upstreamTokenProviderResolver,
createSessionProvider,
}: {
upstreamTokenProvider?: UpstreamTokenProvider | null;
upstreamTokenProviderResolver?: UpstreamTokenProviderResolver | null;
createSessionProvider: () => UpstreamTokenProvider;
}): UpstreamTokenProvider | null | undefined {
return upstreamTokenProviderResolver
? upstreamTokenProvider
: (upstreamTokenProvider ?? createSessionProvider());
}
function normalizeOboCancellation(error: unknown, signal?: AbortSignal): unknown {
if (signal?.aborted && error === signal.reason && !isAbortError(error)) {
return Object.assign(new Error('The operation was aborted.', { cause: error }), {
name: 'AbortError',
});
}
return error;
}
/** Detach cancelled callers and preserve cancellation for arbitrary AbortController reasons. */
export async function awaitOboOperation<T>(
operation: Promise<T>,
signal?: AbortSignal,
): Promise<T> {
try {
return await detachOnAbort(operation, signal);
} catch (error) {
throw normalizeOboCancellation(error, signal);
}
}
/** Keep lookup failures inside resolveOboToken's typed failure boundary. */
export function createLazyOboUpstreamTokenProvider(
resolver: UpstreamTokenProviderResolver,
signal?: AbortSignal,
): UpstreamTokenProvider {
let pending: Promise<UpstreamTokenProvider | undefined> | undefined;
return async (options) => {
const effectiveSignal = options?.signal ?? signal;
try {
effectiveSignal?.throwIfAborted();
pending ??= Promise.resolve()
.then(() => {
effectiveSignal?.throwIfAborted();
return resolver({ signal: effectiveSignal });
})
.catch((error) => {
pending = undefined;
throw error;
});
const provider = await detachOnAbort(pending, effectiveSignal);
effectiveSignal?.throwIfAborted();
if (!provider) {
pending = undefined;
throw new Error('Renewable upstream credentials are unavailable.');
}
return await detachOnAbort(
provider({ ...options, signal: effectiveSignal }),
effectiveSignal,
);
} catch (error) {
throw normalizeOboCancellation(error, effectiveSignal);
}
};
}
export type OboTokenResolutionReason =
| 'missing_upstream_token'
| 'missing_upstream_access_token'
@ -212,6 +290,7 @@ export async function resolveOboToken(
try {
liveTokens = await upstreamTokenProvider();
} catch (error) {
if (isAbortError(error)) throw error;
logger.error('[OBO] Upstream session refresh failed:', error);
const retryable = isRetryableOboExchangeError(error);
throw new OboTokenResolutionError(
@ -292,6 +371,7 @@ export async function resolveOboToken(
expires_at: skewedExpiresAt,
};
} catch (error) {
if (isAbortError(error)) throw error;
if (error instanceof OboTokenResolutionError) {
throw error;
}

View file

@ -20,7 +20,12 @@ import type {
import type { SearchResultData, UIResource, TPlugin } from 'librechat-data-provider';
import type { TokenMethods, IUser } from '@librechat/data-schemas';
import type { LCTool } from '@librechat/agents';
import type { OboTokenResolver, OboTrustChecker, UpstreamTokenProvider } from '~/mcp/oauth/obo';
import type {
OboTokenResolver,
OboTrustChecker,
UpstreamTokenProvider,
UpstreamTokenProviderResolver,
} from '~/mcp/oauth/obo';
import type { AuthIdentityContext } from '~/utils/identity';
import type { GraphTokenResolver } from '~/utils/graph';
import type { FlowStateManager } from '~/flow/manager';
@ -253,6 +258,8 @@ export interface UserConnectionContext {
graphTokenResolver?: GraphTokenResolver;
/** Live OpenID session credential source for trusted direct bearer and OBO configurations. */
upstreamTokenProvider?: UpstreamTokenProvider;
/** Deferred credential source used only after a server is confirmed to require OBO. */
upstreamTokenProviderResolver?: UpstreamTokenProviderResolver;
connectionTimeout?: number;
/** Cancels the connection's SDK requests when the caller itself is cancelled; previously only
* OAuth connections could carry a signal, leaving non-OAuth discovery uncancellable. */
@ -362,6 +369,7 @@ export interface ToolDiscoveryOptions {
oboTokenResolver?: OboTokenResolver;
oboTrustChecker?: OboTrustChecker;
upstreamTokenProvider?: UpstreamTokenProvider;
upstreamTokenProviderResolver?: UpstreamTokenProviderResolver;
oboIdentityContext?: AuthIdentityContext;
}

View file

@ -1,11 +1,54 @@
import { AgentCapabilities, Permissions, PermissionTypes } from 'librechat-data-provider';
import type { IUser, IRole, AppConfig, AgentGraphNode } from '@librechat/data-schemas';
import type { UpstreamTokenProvider } from '../mcp/oauth/obo';
import type { ParsedServerConfig } from '../mcp/types';
import { createScheduleMCPPreflight, ScheduleMCPError } from './mcp';
import {
bindUpstreamTokenProviderResolver,
createScheduleMCPPreflight,
ScheduleMCPError,
} from './mcp';
import { OboTokenResolutionError, createLazyOboUpstreamTokenProvider } from '../mcp/oauth/obo';
const principal = { id: 'owner', role: 'USER' };
const server: ParsedServerConfig = { type: 'streamable-http', url: 'https://mcp.example.test/mcp' };
it('retries through both run-bound and consumer lookup caches after failure', async () => {
const tokenProvider = jest.fn().mockResolvedValue({ access_token: 'fresh' });
const lookup = jest
.fn()
.mockRejectedValueOnce(new Error('temporary unavailable'))
.mockResolvedValue(tokenProvider);
const bound = bindUpstreamTokenProviderResolver(principal as IUser, lookup)!;
const first = createLazyOboUpstreamTokenProvider(bound);
const second = createLazyOboUpstreamTokenProvider(bound);
const results = await Promise.allSettled([first(), second()]);
expect(results.map((r) => r.status)).toEqual(['rejected', 'rejected']);
expect(lookup).toHaveBeenCalledTimes(1);
await expect(Promise.all([first(), second()])).resolves.toEqual([
{ access_token: 'fresh' },
{ access_token: 'fresh' },
]);
expect(lookup).toHaveBeenCalledTimes(2);
});
it('shares credential lookup across sibling consumers without adopting child cancellation', async () => {
const owner = new AbortController();
const child = new AbortController();
child.abort();
const provider = jest.fn();
const lookup = jest.fn().mockResolvedValue(provider);
const resolve = bindUpstreamTokenProviderResolver(principal as IUser, lookup, owner.signal)!;
expect(lookup).not.toHaveBeenCalled();
await expect(Promise.all([resolve({ signal: child.signal }), resolve()])).resolves.toEqual([
provider,
provider,
]);
expect(lookup).toHaveBeenCalledTimes(1);
expect(lookup).toHaveBeenCalledWith(principal, { signal: owner.signal });
owner.abort();
expect(() => resolve()).toThrow();
});
function graphNode(id: string, fields: Partial<AgentGraphNode> = {}): AgentGraphNode {
return { id, provider: 'openAI', model: 'gpt-test', ...fields };
}
@ -78,6 +121,69 @@ it('uses persisted identity with isolated connections and disposes them after di
expect(disconnect).toHaveBeenCalledTimes(1);
});
it('lazily resolves an upstream token provider for an OBO preflight', async () => {
const { check, deps } = setup();
deps.getServerConfigs = jest.fn(async () => ({
docs: { ...server, obo: { scopes: 'api://mcp/.default' } },
}));
const upstreamTokenProvider: UpstreamTokenProvider = jest.fn(async () => ({
access_token: 'current-token',
}));
deps.resolveUpstreamTokenProvider = jest.fn(async () => upstreamTokenProvider);
const connect = deps.connect;
deps.connect = jest.fn(async (options) => {
await options.upstreamTokenProviderResolver?.({ signal: options.signal });
return connect(options);
});
await check('agent', principal);
expect(deps.resolveUpstreamTokenProvider).toHaveBeenCalledWith(
expect.objectContaining({ id: 'owner' }),
{ signal: undefined },
);
expect(deps.connect).toHaveBeenCalledWith(
expect.objectContaining({ upstreamTokenProviderResolver: expect.any(Function) }),
);
});
it('does not resolve upstream credentials for non-OBO servers', async () => {
const { check, deps } = setup();
deps.resolveUpstreamTokenProvider = jest.fn(async () => {
throw new Error('credential service unavailable');
});
await expect(check('agent', principal)).resolves.toEqual([{ server: 'docs', status: 'ready' }]);
expect(deps.resolveUpstreamTokenProvider).not.toHaveBeenCalled();
});
it('does not expose an OBO provider to a sibling direct-bearer server', async () => {
const { check, deps } = setup(['search_mcp_obo', 'search_mcp_direct']);
deps.getServerConfigs = jest.fn(async () => ({
obo: { ...server, obo: { scopes: 'api://mcp/.default' } },
direct: { ...server, headers: { Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}' } },
}));
const upstreamTokenProvider: UpstreamTokenProvider = jest.fn(async () => ({
access_token: 'current-token',
}));
deps.resolveUpstreamTokenProvider = jest.fn(async () => upstreamTokenProvider);
const connect = deps.connect;
deps.connect = jest.fn(async (options) => {
if (options.serverConfig?.obo) {
await options.upstreamTokenProviderResolver?.({ signal: options.signal });
}
return connect(options);
});
await check('agent', principal);
expect(deps.resolveUpstreamTokenProvider).toHaveBeenCalledTimes(1);
const directOptions = (deps.connect as jest.Mock).mock.calls.find(
([options]) => options.serverName === 'direct',
)?.[0];
expect(directOptions.upstreamTokenProvider).toBeUndefined();
});
it('rejects partial readiness and reports each server without exception details', async () => {
const { check, deps, disconnect } = setup(['search_mcp_docs', 'read_mcp_private']);
deps.getServerConfigs = async () => ({ docs: server, private: server });
@ -130,6 +236,28 @@ it('classifies a transport outage as retryable', async () => {
});
});
it('classifies a permanent OBO credential failure as requiring reauthentication', async () => {
const { check, deps } = setup();
deps.connect = async () => {
throw new OboTokenResolutionError('session_refresh_failed', 'Sign-in expired.');
};
await expect(check('agent', principal)).rejects.toMatchObject({
code: 'mcp_reauth_required',
});
});
it('classifies a retryable OBO credential failure as unavailable', async () => {
const { check, deps } = setup();
deps.connect = async () => {
throw new OboTokenResolutionError('session_refresh_failed', 'Refresh unavailable.', true);
};
await expect(check('agent', principal)).rejects.toMatchObject({
code: 'mcp_unavailable',
});
});
it('checks graph agents once even when edges cycle', async () => {
const { check, deps } = setup();
deps.getAgentGraphNodes = jest.fn(async (ids) =>

View file

@ -22,6 +22,7 @@ import type {
AgentGraphAccessContext,
} from '@librechat/data-schemas';
import type { TModelsConfig, ScheduleMCPStatus, ScheduleMCPOutcome } from 'librechat-data-provider';
import type { UpstreamTokenProvider, UpstreamTokenProviderResolver } from '../mcp/oauth/obo';
import type { ParsedServerConfig, UserMCPConnectionOptions } from '../mcp/types';
import type { CheckAccessParams } from '../middleware/access';
import type { MCPToolsSnapshot } from '../mcp/connection';
@ -42,12 +43,56 @@ import { MCPConfigInitializationCanceledError } from '../mcp/registry/MCPServers
import { createMCPRequestContext, cleanupMCPRequestContext } from '../mcp/request';
import { getAppConfigOptionsFromUser } from '../app/service';
import { createConcurrencyLimiter } from '../utils/promise';
import { OboTokenResolutionError } from '../mcp/oauth/obo';
import { OpenIDReauthRequiredError } from '../utils/oidc';
import { resolveReachableGraph } from '../agents/edges';
import { formatMCPServerTools } from '../mcp/tools';
import { checkAccess } from '../middleware/access';
import { detachOnAbort } from '../utils/promises';
import { getPluginAuthMap } from '../agents/auth';
import { isScheduleFireRequest } from './trigger';
type HostUpstreamTokenProviderResolver = (
user: IUser,
options: { signal?: AbortSignal },
) => ReturnType<UpstreamTokenProviderResolver>;
/** Bind a credential lookup to the trusted principal and owning run's cancellation. */
export function bindUpstreamTokenProviderResolver(
user: IUser,
resolve: HostUpstreamTokenProviderResolver | undefined,
signal?: AbortSignal,
): UpstreamTokenProviderResolver | undefined {
if (!resolve) return undefined;
let pending: Promise<UpstreamTokenProvider | undefined> | undefined;
return () => {
signal?.throwIfAborted();
pending ??= Promise.resolve()
.then(() => {
signal?.throwIfAborted();
return resolve(user, { signal });
})
.then((provider) => {
if (!provider) pending = undefined;
return provider;
})
.catch((error) => {
pending = undefined;
throw error;
});
return pending;
};
}
export function createScheduleUpstreamTokenProviderResolver(
req: Parameters<typeof isScheduleFireRequest>[0] & { user: IUser },
resolve: HostUpstreamTokenProviderResolver | undefined,
signal?: AbortSignal,
): UpstreamTokenProviderResolver | undefined {
return isScheduleFireRequest(req)
? bindUpstreamTokenProviderResolver(req.user, resolve, signal)
: undefined;
}
// The public schedule schema caps mcpPreflightConcurrency at 10. Keep the same
// ceiling across every preflight owned by this process so concurrent schedules
@ -100,12 +145,16 @@ interface ScheduleMCPDeps {
role?: string,
) => Promise<Record<string, ParsedServerConfig>>;
findPluginAuthsByKeys: PluginAuthMethods['findPluginAuthsByKeys'];
resolveUpstreamTokenProvider?: (
user: IUser,
options: { signal?: AbortSignal },
) => UpstreamTokenProvider | undefined | Promise<UpstreamTokenProvider | undefined>;
connect: (options: UserMCPConnectionOptions) => Promise<{
fetchToolsSnapshot: (deadlineMs?: number, signal?: AbortSignal) => Promise<MCPToolsSnapshot>;
}>;
}
/** Probes only persisted identity and credentials, with isolated user connections and no OAuth wait. */
/** Probes MCP readiness with isolated user connections and no interactive OAuth wait. */
export function createScheduleMCPPreflight(deps: ScheduleMCPDeps): ScheduleMCPPreflight {
const sharedProbeLimit = createConcurrencyLimiter(MAX_SHARED_MCP_PREFLIGHT_CONCURRENCY);
const runPreflight: ScheduleMCPPreflight = async (agentId, principal, options) => {
@ -571,6 +620,12 @@ export function createScheduleMCPPreflight(deps: ScheduleMCPDeps): ScheduleMCPPr
throwError: true,
findPluginAuthsByKeys: deps.findPluginAuthsByKeys,
});
const upstreamTokenProviderResolver = bindUpstreamTokenProviderResolver(
user,
deps.resolveUpstreamTokenProvider,
options.signal,
);
throwIfAborted();
const requestBody = {
messageId: randomUUID(),
conversationId: randomUUID(),
@ -602,6 +657,7 @@ export function createScheduleMCPPreflight(deps: ScheduleMCPDeps): ScheduleMCPPr
customUserVars,
requestBody,
requestScopedConnections: context,
upstreamTokenProviderResolver,
ephemeralConnection: true,
returnOnOAuth: true,
oauthStart: async () => {
@ -651,6 +707,7 @@ export function createScheduleMCPPreflight(deps: ScheduleMCPDeps): ScheduleMCPPr
reauth ||
error instanceof MCPAuthenticationRejectedError ||
error instanceof OpenIDReauthRequiredError ||
(error instanceof OboTokenResolutionError && !error.retryable) ||
error instanceof MCPOAuthSecretReentryRequiredError ||
isOAuthAuthenticationError(error)
? 'mcp_reauth_required'

View file

@ -1,4 +1,4 @@
import { getSafeErrorMetadata, getSafeErrorText, isAbortError } from './errors';
import { getSafeErrorMetadata, getSafeErrorText, isAbortError, isOwnedAbortError } from './errors';
describe('getSafeErrorMetadata', () => {
it('keeps bounded diagnostic fields without serializing raw provider data', () => {
@ -182,3 +182,22 @@ describe('isAbortError', () => {
expect(isAbortError('aborted')).toBe(false);
});
});
describe('isOwnedAbortError', () => {
it.each([new Error('stopped'), 'stopped'])(
'recognizes the owning signal reason (%s)',
(reason) => {
const controller = new AbortController();
controller.abort(reason);
expect(isOwnedAbortError(reason, controller.signal)).toBe(true);
},
);
it('does not hide an unrelated failure that races cancellation', () => {
const controller = new AbortController();
controller.abort(new Error('stopped'));
expect(isOwnedAbortError(new Error('upstream failed'), controller.signal)).toBe(false);
});
});

View file

@ -133,3 +133,8 @@ export function isAbortError(error: unknown): boolean {
return false;
}
/** Whether an error represents cancellation by this specific owning signal. */
export function isOwnedAbortError(error: unknown, signal?: AbortSignal | null): boolean {
return signal?.aborted === true && (isAbortError(error) || error === signal.reason);
}

View file

@ -5,6 +5,10 @@ describe('detachOnAbort', () => {
await expect(detachOnAbort(Promise.resolve('value'))).resolves.toBe('value');
});
it('accepts an already-resolved operation value', async () => {
await expect(detachOnAbort('value', new AbortController().signal)).resolves.toBe('value');
});
it('resolves normally when the signal never aborts', async () => {
const controller = new AbortController();
await expect(detachOnAbort(Promise.resolve('value'), controller.signal)).resolves.toBe('value');

View file

@ -12,7 +12,11 @@
* The detached promise's later settlement is swallowed rather than surfacing as
* an unhandled rejection.
*/
export function detachOnAbort<T>(promise: Promise<T>, signal?: AbortSignal | null): Promise<T> {
export function detachOnAbort<T>(
operation: T | PromiseLike<T>,
signal?: AbortSignal | null,
): Promise<T> {
const promise = Promise.resolve(operation);
if (signal == null) {
return promise;
}