LibreChat/api/server/services/__tests__/ToolService.spec.js
Marco Beretta 65d0ba8563
🧯 fix: Return Approved Tool and Generation Error Text Instead of Raw Exceptions (#17508)
* fix: Return approved tool and generation error text instead of raw exceptions

* fix: Redact generation error text without the data-schemas helper

* fix: Redact credentials and emails from shown generation errors

* refactor: Move the Wolfram status policy into packages/api

* test: Fix the Wolfram probe constructor and jest summary match

* test: Match the jest pass count through color codes

* fix: Redact credentials a tool input error echoes from its arguments

* fix: Drop free-text fields from typed generation errors under a content policy

* fix: Keep only the code and numeric fields of typed errors under a content policy
2026-10-28 00:39:01 +01:00

5004 lines
179 KiB
JavaScript

const { createHash } = require('node:crypto');
const { Constants: AgentConstants } = require('@librechat/agents');
const {
Tools,
Constants,
ResourceType,
ErrorTypes,
Permissions,
EToolResources,
EModelEndpoint,
isActionTool,
actionDelimiter,
PermissionTypes,
AgentCapabilities,
defaultAgentCapabilities,
} = require('librechat-data-provider');
const mockGetEndpointsConfig = jest.fn();
const mockGetAppConfig = jest.fn();
const mockGetMCPServerTools = jest.fn();
const mockGetCachedTools = jest.fn();
const mockSendEvent = jest.fn();
const mockEmitChunk = jest.fn();
const mockCreateAttachedWorkspaceBashTool = jest.fn(() => ({ name: AgentConstants.BASH_TOOL }));
const mockLaneGitRecorder = jest.fn();
const mockCreateLaneGitRecorder = jest.fn(() => mockLaneGitRecorder);
const mockSetConvoLaneGit = jest.fn();
const mockGetConvoLaneContext = jest.fn();
const mockReserveConvoLaneGitSeq = jest.fn();
const attachedWorkspaceOperations = [
'read_file',
'search_text',
'list_files',
'write_file',
'preview_edit',
'edit_file',
'execute_command',
];
const fingerprint = (...parts) =>
createHash('sha256').update(JSON.stringify(parts)).digest('hex').slice(0, 32);
const attachedEnvironment = (overrides = {}) => ({
id: 'personal-machine',
name: 'Personal machine',
type: 'attached',
owner: 'deployment',
baseURL: 'http://attached-code.test/v1',
workerId: 'worker-abc',
...overrides,
});
const mockResolveCodeExecutionWorkspaceContext = jest.fn(async ({ context }) => {
if (context.environmentType !== 'attached') {
return context;
}
const environmentId = context.environmentId ?? 'personal-machine';
return {
...context,
environmentId,
codeWorkspace: {
environmentId,
workspaceId: 'project-a',
operations: attachedWorkspaceOperations,
},
};
});
const mockPrimeSearchFiles = jest.fn().mockResolvedValue({});
const mockPrimeCodeFiles = jest.fn().mockResolvedValue({});
jest.mock('~/server/services/Config', () => ({
getEndpointsConfig: (...args) => mockGetEndpointsConfig(...args),
getAppConfig: (...args) => mockGetAppConfig(...args),
getMCPServerTools: (...args) => mockGetMCPServerTools(...args),
getCachedTools: (...args) => mockGetCachedTools(...args),
}));
const mockLoadToolDefinitions = jest.fn();
const mockGetUserMCPAuthMap = jest.fn();
jest.mock('@librechat/api', () => ({
...jest.requireActual('@librechat/api'),
AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE: 'AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE',
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 }) => ({
appUserId: user?._id?.toString?.() ?? user?.id,
openidSubject: user?.openidId,
tenantId: tenantId ?? user?.tenantId,
openidIssuer: user?.openidIssuer,
}),
sendEvent: (...args) => mockSendEvent(...args),
GenerationJobManager: {
emitChunk: (...args) => mockEmitChunk(...args),
},
resolveCodeExecutionWorkspaceContext: (...args) =>
mockResolveCodeExecutionWorkspaceContext(...args),
createAttachedWorkspaceBashTool: (...args) => mockCreateAttachedWorkspaceBashTool(...args),
createLaneGitRecorder: (...args) => mockCreateLaneGitRecorder(...args),
}));
const mockLoadToolsUtil = jest.fn();
jest.mock('~/app/clients/tools/util', () => ({
loadTools: (...args) => mockLoadToolsUtil(...args),
}));
const mockLoadActionSets = jest.fn();
const mockDomainParser = jest.fn();
const mockLegacyDomainEncode = jest.fn();
const mockDecryptMetadata = jest.fn();
const mockCreateActionTool = jest.fn();
const mockGetServerConfig = jest.fn();
const mockFlowManager = { getFlowState: jest.fn() };
const mockResolveConfigServers = jest.fn();
const mockResolveMcpServerNames = jest.fn();
const mockUserCanUseMCPServers = jest.fn().mockResolvedValue(true);
jest.mock('~/server/services/Tools/credentials', () => ({
loadAuthValues: jest.fn().mockResolvedValue({}),
}));
jest.mock('~/server/services/Tools/search', () => ({
createOnSearchResults: jest.fn(),
}));
jest.mock('~/server/services/Tools/mcp', () => ({
reinitMCPServer: jest.fn(),
}));
jest.mock('~/server/services/Files/process', () => ({
processFileURL: jest.fn(),
uploadImageBuffer: jest.fn(),
}));
jest.mock('~/app/clients/tools/util/fileSearch', () => ({
primeFiles: (...args) => mockPrimeSearchFiles(...args),
}));
jest.mock('~/server/services/Files/Code/process', () => ({
primeFiles: (...args) => mockPrimeCodeFiles(...args),
}));
jest.mock('../ActionService', () => ({
loadActionSets: (...args) => mockLoadActionSets(...args),
decryptMetadata: (...args) => mockDecryptMetadata(...args),
createActionTool: (...args) => mockCreateActionTool(...args),
domainParser: (...args) => mockDomainParser(...args),
legacyDomainEncode: (...args) => mockLegacyDomainEncode(...args),
}));
jest.mock('~/server/services/Threads', () => ({
recordUsage: jest.fn(),
}));
const mockGetRoleByName = jest.fn();
jest.mock('~/models', () => ({
findPluginAuthsByKeys: jest.fn(),
getRoleByName: (...args) => mockGetRoleByName(...args),
setConvoLaneGit: (...args) => mockSetConvoLaneGit(...args),
getConvoLaneContext: (...args) => mockGetConvoLaneContext(...args),
reserveConvoLaneGitSeq: (...args) => mockReserveConvoLaneGitSeq(...args),
}));
jest.mock('~/config', () => ({
getFlowStateManager: jest.fn(() => mockFlowManager),
getMCPServersRegistry: jest.fn(() => ({
getServerConfig: (...args) => mockGetServerConfig(...args),
})),
}));
jest.mock('~/server/services/MCP', () => ({
resolveConfigServers: (...args) => mockResolveConfigServers(...args),
resolveMcpServerNames: (...args) => mockResolveMcpServerNames(...args),
resolveMcpServerContext: async (...args) => {
const configServers = (await mockResolveConfigServers(...args)) ?? {};
const serverNames = Object.keys(configServers);
return { configServers, serverNames, rawServerNames: serverNames };
},
/** Mirrors the real resolver's shape; these fixtures use safe names, so the
* raw set is always the complete audit. */
resolveCollisionAuditNames: jest.fn(async ({ rawServerNames, accessibleServerNames }) => ({
names: accessibleServerNames?.length ? accessibleServerNames : rawServerNames,
complete: true,
})),
createMCPPermissionContext: jest.fn((req) => ({
canUseServers: (user) => mockUserCanUseMCPServers(user, req),
})),
userCanUseMCPServers: mockUserCanUseMCPServers,
}));
jest.mock('~/cache', () => ({
getLogStores: jest.fn(() => ({})),
}));
const {
loadAgentTools,
loadToolsForExecution,
processRequiredActions,
resolveAgentCapabilities,
} = require('../ToolService');
const { createOnSearchResults } = require('~/server/services/Tools/search');
const { reinitMCPServer } = require('~/server/services/Tools/mcp');
const { ContentFilterError, PENDING_STALE_MS, ToolInputError } = require('@librechat/api');
/** Role document shape `checkAccess` reads; all three role-gated tools granted. */
function buildRole(overrides = {}) {
return {
name: 'USER',
permissions: {
[PermissionTypes.FILE_SEARCH]: { [Permissions.USE]: true },
[PermissionTypes.RUN_CODE]: { [Permissions.USE]: true },
[PermissionTypes.WEB_SEARCH]: { [Permissions.USE]: true },
...overrides,
},
};
}
function createMockReq(capabilities) {
return {
user: { id: 'user_123', role: 'USER' },
config: {
endpoints: {
[EModelEndpoint.agents]: {
capabilities,
},
},
},
};
}
function createEndpointsConfig(capabilities) {
return {
[EModelEndpoint.agents]: { capabilities },
};
}
beforeAll(() => {
process.env.GITHUB_TOKEN = process.env.GITHUB_TOKEN || 'ghp_test';
});
describe('ToolService - Action Capability Gating', () => {
beforeEach(() => {
jest.clearAllMocks();
mockLoadToolDefinitions.mockResolvedValue({
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
});
mockLoadToolsUtil.mockResolvedValue({ loadedTools: [], toolContextMap: {} });
mockLoadActionSets.mockResolvedValue([]);
mockDecryptMetadata.mockImplementation(async (metadata) => metadata);
mockGetMCPServerTools.mockResolvedValue(null);
mockGetCachedTools.mockResolvedValue(null);
mockGetUserMCPAuthMap.mockResolvedValue({});
mockGetRoleByName.mockResolvedValue(buildRole());
mockGetServerConfig.mockImplementation(async (name, _userId, candidates) => candidates?.[name]);
mockFlowManager.getFlowState.mockResolvedValue(undefined);
mockResolveConfigServers.mockResolvedValue({});
mockResolveMcpServerNames.mockResolvedValue([]);
mockPrimeSearchFiles.mockResolvedValue({});
mockPrimeCodeFiles.mockResolvedValue({});
});
describe('processRequiredActions content protection', () => {
afterEach(() => {
jest.restoreAllMocks();
});
const buildFilters = (field, sentinel) => ({
toolArguments: {
pii: {
fields: [field],
starterPatterns: [],
customPatterns: [
{
id: 'private',
label: 'private value',
regex: sentinel,
},
],
},
},
});
const buildClient = (filters) => ({
req: {
user: { id: 'user_123' },
body: {
assistant_id: 'assistant_content_filter',
model: 'gpt-4o-mini',
endpoint: 'openAI',
},
config: { filters },
},
res: {},
apiKey: 'test-key',
mappedOrder: new Map([['call_1', 0]]),
seenToolCalls: new Map(),
addContentData: jest.fn(),
});
const buildAction = (overrides = {}) => ({
tool: 'safe_tool',
toolInput: { value: 'safe' },
toolCallId: 'call_1',
thread_id: 'thread_1',
run_id: 'run_1',
...overrides,
});
it('blocks a filtered tool name before lookup, logging, or execution', async () => {
const privateName = 'PRIVATE-NAME';
const client = buildClient(buildFilters('name', privateName));
const debugSpy = jest.spyOn(require('@librechat/data-schemas').logger, 'debug');
await expect(
processRequiredActions(client, [buildAction({ tool: privateName })]),
).rejects.toMatchObject({
code: 'content_filter_block',
message: expect.not.stringContaining(privateName),
});
expect(mockGetCachedTools).not.toHaveBeenCalled();
expect(mockLoadToolsUtil).not.toHaveBeenCalled();
expect(debugSpy).not.toHaveBeenCalled();
});
it('blocks filtered arguments before tool execution', async () => {
const privateArgument = 'PRIVATE-ARGUMENT';
const client = buildClient(buildFilters('arguments', privateArgument));
await expect(
processRequiredActions(client, [
buildAction({ toolInput: { nested: { value: privateArgument } } }),
]),
).rejects.toMatchObject({
code: 'content_filter_block',
message: expect.not.stringContaining(privateArgument),
});
expect(mockGetCachedTools).not.toHaveBeenCalled();
expect(mockLoadToolsUtil).not.toHaveBeenCalled();
});
it('blocks a visible argument match before enforcing its traversal overflow', async () => {
const privateArgument = 'PRIVATE-ARGUMENT';
const deeplyNestedArguments = { visible: privateArgument };
let current = deeplyNestedArguments;
for (let depth = 0; depth < 30; depth++) {
current.nested = {};
current = current.nested;
}
const client = buildClient(buildFilters('arguments', privateArgument));
await expect(
processRequiredActions(client, [buildAction({ toolInput: deeplyNestedArguments })]),
).rejects.toMatchObject({
code: 'content_filter_block',
message: expect.not.stringContaining(privateArgument),
});
expect(mockGetCachedTools).not.toHaveBeenCalled();
expect(mockLoadToolsUtil).not.toHaveBeenCalled();
});
it('fails closed before execution when selected arguments exhaust traversal', async () => {
const deeplyNestedArguments = { visible: 'safe' };
let current = deeplyNestedArguments;
for (let depth = 0; depth < 30; depth++) {
current.nested = {};
current = current.nested;
}
const client = buildClient(buildFilters('arguments', 'PRIVATE-ARGUMENT'));
await expect(
processRequiredActions(client, [buildAction({ toolInput: deeplyNestedArguments })]),
).rejects.toMatchObject({
code: 'content_filter_uninspectable',
body: {
error: 'content_filter_uninspectable',
source: 'tool_argument',
field: 'arguments',
},
});
expect(mockGetCachedTools).not.toHaveBeenCalled();
expect(mockLoadToolsUtil).not.toHaveBeenCalled();
});
it('does not inspect required-action values when the source has no active patterns', async () => {
const opaqueArguments = new Proxy(
{},
{
ownKeys: () => {
throw new Error('inactive arguments were traversed');
},
},
);
const client = buildClient({
toolArguments: {
pii: {
fields: ['arguments'],
starterPatterns: [],
},
},
});
await expect(
processRequiredActions(client, [buildAction({ toolInput: opaqueArguments })]),
).resolves.toEqual({ tool_outputs: [] });
expect(mockGetCachedTools).toHaveBeenCalledTimes(1);
expect(mockLoadToolsUtil).toHaveBeenCalledTimes(1);
});
it('does not traverse unselected required-action arguments', async () => {
const opaqueArguments = new Proxy(
{},
{
ownKeys: () => {
throw new Error('unselected arguments were traversed');
},
},
);
const client = buildClient(buildFilters('name', 'PRIVATE-NAME'));
await expect(
processRequiredActions(client, [buildAction({ toolInput: opaqueArguments })]),
).resolves.toEqual({ tool_outputs: [] });
expect(mockGetCachedTools).toHaveBeenCalledTimes(1);
expect(mockLoadToolsUtil).toHaveBeenCalledTimes(1);
});
it('does not traverse unselected required-action output', async () => {
const opaqueOutput = new Proxy(
{},
{
ownKeys: () => {
throw new Error('unselected output was traversed');
},
},
);
const toolCall = jest.fn().mockResolvedValue(opaqueOutput);
mockLoadToolsUtil.mockResolvedValue({
loadedTools: [{ name: 'safe_tool', _call: toolCall }],
toolContextMap: {},
});
const client = buildClient(buildFilters('arguments', 'PRIVATE-ARGUMENT'));
const result = await processRequiredActions(client, [buildAction()]);
expect(result.tool_outputs[0].tool_call_id).toBe('call_1');
expect(result.tool_outputs[0].output).toBe(opaqueOutput);
});
it('does not traverse unselected required-action arguments for output-only policies', async () => {
const deeplyNestedArguments = { value: 'safe' };
let current = deeplyNestedArguments;
for (let depth = 0; depth < 30; depth++) {
current.nested = {};
current = current.nested;
}
const toolCall = jest.fn().mockResolvedValue('safe output');
mockLoadToolsUtil.mockResolvedValue({
loadedTools: [{ name: 'safe_tool', _call: toolCall }],
toolContextMap: {},
});
const client = buildClient(buildFilters('output', 'PRIVATE-OUTPUT'));
await expect(
processRequiredActions(client, [buildAction({ toolInput: deeplyNestedArguments })]),
).resolves.toEqual({
tool_outputs: [{ tool_call_id: 'call_1', output: 'safe output' }],
});
expect(toolCall).toHaveBeenCalledWith(deeplyNestedArguments);
});
it('replaces a filtered tool output before UI or model submission', async () => {
const privateOutput = 'PRIVATE-OUTPUT';
const toolCall = jest.fn().mockResolvedValue(privateOutput);
mockLoadToolsUtil.mockResolvedValue({
loadedTools: [{ name: 'safe_tool', _call: toolCall }],
toolContextMap: {},
});
const client = buildClient(buildFilters('output', privateOutput));
const action = buildAction();
const result = await processRequiredActions(client, [action]);
expect(toolCall).toHaveBeenCalledWith(action.toolInput);
expect(result.tool_outputs).toEqual([
{
tool_call_id: 'call_1',
output: JSON.stringify({
error: 'content_filter_block',
message: 'Submitted content was blocked by content policy.',
source: 'tool_argument',
field: 'output',
}),
},
]);
expect(action.output).not.toContain(privateOutput);
expect(client.addContentData).toHaveBeenCalledWith(
expect.objectContaining({
tool_call: expect.objectContaining({
function: expect.objectContaining({
output: expect.not.stringContaining(privateOutput),
}),
}),
}),
);
});
it('submits canonical MCP output and persists its App attachment', async () => {
const uiResources = [{ uri: 'ui://app', mimeType: 'text/html;profile=mcp-app' }];
mockLoadToolsUtil.mockResolvedValue({
loadedTools: [
{
name: 'safe_tool',
mcp: true,
_call: jest
.fn()
.mockResolvedValue(['safe output', { [Tools.ui_resources]: { data: uiResources } }]),
},
],
toolContextMap: {},
});
const client = buildClient(buildFilters('output', 'PRIVATE-OUTPUT'));
client.responseMessage = {
messageId: 'message_1',
conversationId: 'conversation_1',
attachments: [],
};
client.res = { write: jest.fn() };
await expect(processRequiredActions(client, [buildAction()])).resolves.toEqual({
tool_outputs: [{ tool_call_id: 'call_1', output: 'safe output' }],
});
expect(client.responseMessage.attachments).toEqual([
expect.objectContaining({
type: Tools.ui_resources,
toolCallId: 'call_1',
[Tools.ui_resources]: uiResources,
}),
]);
expect(client.res.write).toHaveBeenCalledWith(expect.stringContaining('event: attachment\n'));
});
it('omits an MCP App attachment when canonical output is substituted', async () => {
const privateOutput = 'PRIVATE-OUTPUT';
mockLoadToolsUtil.mockResolvedValue({
loadedTools: [
{
name: 'safe_tool',
mcp: true,
_call: jest
.fn()
.mockResolvedValue([
privateOutput,
{ [Tools.ui_resources]: { data: [{ uri: 'ui://app' }] } },
]),
},
],
toolContextMap: {},
});
const client = buildClient(buildFilters('output', privateOutput));
client.responseMessage = {
messageId: 'message_1',
conversationId: 'conversation_1',
attachments: [],
};
client.res = { write: jest.fn() };
const result = await processRequiredActions(client, [buildAction()]);
expect(JSON.parse(result.tool_outputs[0].output)).toMatchObject({
error: 'content_filter_block',
field: 'output',
});
expect(client.responseMessage.attachments).toEqual([]);
expect(client.res.write).not.toHaveBeenCalled();
});
it('replaces an uninspectable tool output before UI or model submission', async () => {
const deeplyNestedOutput = { visible: 'safe' };
let current = deeplyNestedOutput;
for (let depth = 0; depth < 30; depth++) {
current.nested = {};
current = current.nested;
}
const toolCall = jest.fn().mockResolvedValue(deeplyNestedOutput);
mockLoadToolsUtil.mockResolvedValue({
loadedTools: [{ name: 'safe_tool', _call: toolCall }],
toolContextMap: {},
});
const client = buildClient(buildFilters('output', 'PRIVATE-OUTPUT'));
const action = buildAction();
const result = await processRequiredActions(client, [action]);
const output = result.tool_outputs[0].output;
expect(JSON.parse(output)).toEqual({
error: 'content_filter_uninspectable',
message: 'Submitted content could not be completely inspected before processing.',
source: 'tool_argument',
field: 'output',
});
expect(action.output).toBe(output);
expect(output).not.toContain('PRIVATE-OUTPUT');
expect(client.addContentData).toHaveBeenCalledWith(
expect.objectContaining({
tool_call: expect.objectContaining({
function: expect.objectContaining({ output }),
}),
}),
);
});
it.each([
['bearer_header', 'Authorization: Bearer required-action-token', 'Bearer token'],
['api_key_header', 'api-key: required-action-token', 'api-key header'],
])(
'returns a stable required-action %s block output',
async (starterPattern, privateOutput, detectorLabel) => {
mockLoadToolsUtil.mockResolvedValue({
loadedTools: [{ name: 'safe_tool', _call: jest.fn().mockResolvedValue(privateOutput) }],
toolContextMap: {},
});
const client = buildClient({
toolArguments: {
pii: {
fields: ['output'],
starterPatterns: [starterPattern],
},
},
});
const result = await processRequiredActions(client, [buildAction()]);
const output = result.tool_outputs[0].output;
expect(JSON.parse(output)).toEqual({
error: 'content_filter_block',
message: 'Submitted content was blocked by content policy.',
source: 'tool_argument',
field: 'output',
});
expect(output).not.toContain(privateOutput);
expect(output).not.toContain(detectorLabel);
},
);
it('normalizes a required-action policy error without tool-output filtering', async () => {
const privateOutput = 'Authorization: Bearer generated-file-token';
const policyError = new ContentFilterError({
detectorId: 'pii-pattern',
ruleId: 'bearer_header',
label: 'Bearer token',
source: 'file',
field: 'content',
provenance: 'tool',
fragmentId: 'generated-file',
fragmentPath: '/content',
});
mockLoadToolsUtil.mockResolvedValue({
loadedTools: [
{
name: 'safe_tool',
_call: jest.fn().mockRejectedValue(policyError),
},
],
toolContextMap: {},
});
const client = buildClient({
files: {
pii: {
fields: ['content'],
starterPatterns: ['bearer_header'],
},
},
});
const result = await processRequiredActions(client, [buildAction()]);
const output = result.tool_outputs[0].output;
expect(JSON.parse(output)).toEqual({
error: 'content_filter_block',
message: 'Submitted content was blocked by content policy.',
source: 'file',
field: 'content',
});
expect(output).not.toContain(privateOutput);
expect(output).not.toContain('Bearer token');
expect(output).not.toContain('bearer_header');
});
it('returns approved tool error text instead of a raw exception message', async () => {
const rawMessage =
'connect ECONNREFUSED 10.0.0.5:443 for https://api.example.test/?q=PRIVATE';
mockLoadToolsUtil.mockResolvedValue({
loadedTools: [
{ name: 'safe_tool', _call: jest.fn().mockRejectedValue(new Error(rawMessage)) },
],
toolContextMap: {},
});
const result = await processRequiredActions(buildClient(undefined), [buildAction()]);
expect(result.tool_outputs).toEqual([
{
tool_call_id: 'call_1',
output: 'Error processing tool safe_tool: The tool request failed.',
},
]);
});
it('keeps the message of a tool input error the tool wrote for the model', async () => {
mockLoadToolsUtil.mockResolvedValue({
loadedTools: [
{
name: 'safe_tool',
_call: jest
.fn()
.mockRejectedValue(new ToolInputError('Could not find coordinates for city: Rome')),
},
],
toolContextMap: {},
});
const result = await processRequiredActions(buildClient(undefined), [buildAction()]);
expect(result.tool_outputs[0].output).toBe(
'Error processing tool safe_tool: Could not find coordinates for city: Rome',
);
});
it('blocks persisted Assistant action metadata before required-action execution', async () => {
const actionToolName = `get_weather${actionDelimiter}api_example_com`;
const filters = {
actionMetadata: {
pii: {
fields: ['api_key'],
starterPatterns: [],
customPatterns: [
{
id: 'private',
label: 'private value',
regex: 'PRIVATE-[A-Z]+',
},
],
},
},
};
const metadata = {
domain: 'https://api.example.com',
raw_spec: '{}',
api_key: 'encrypted-value',
};
const client = buildClient(filters);
mockLoadActionSets.mockResolvedValue([
{
action_id: 'assistant_action_private_auth',
metadata,
},
]);
mockDecryptMetadata.mockResolvedValue({
...metadata,
api_key: 'PRIVATE-AUTH',
});
await expect(
processRequiredActions(client, [buildAction({ tool: actionToolName })]),
).rejects.toMatchObject({
code: 'content_filter_block',
body: {
source: 'action_metadata',
field: 'api_key',
},
});
expect(mockDomainParser).not.toHaveBeenCalled();
expect(mockCreateActionTool).not.toHaveBeenCalled();
});
});
describe('resolveAgentCapabilities', () => {
it('should return capabilities from endpoints config', async () => {
const capabilities = [AgentCapabilities.tools, AgentCapabilities.actions];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
const result = await resolveAgentCapabilities(req, req.config, 'agent_123');
expect(result).toBeInstanceOf(Set);
expect(result.has(AgentCapabilities.tools)).toBe(true);
expect(result.has(AgentCapabilities.actions)).toBe(true);
expect(result.has(AgentCapabilities.web_search)).toBe(false);
});
it('should fall back to default capabilities for ephemeral agents with empty config', async () => {
const req = createMockReq(defaultAgentCapabilities);
mockGetEndpointsConfig.mockResolvedValue({});
const result = await resolveAgentCapabilities(req, req.config, Constants.EPHEMERAL_AGENT_ID);
for (const cap of defaultAgentCapabilities) {
expect(result.has(cap)).toBe(true);
}
});
it('should return empty set when no capabilities and not ephemeral', async () => {
const req = createMockReq([]);
mockGetEndpointsConfig.mockResolvedValue({});
const result = await resolveAgentCapabilities(req, req.config, 'agent_123');
expect(result.size).toBe(0);
});
});
it.each([true, false])(
'passes the Code API retry limit to repository instructions (definitionsOnly=%s)',
async (definitionsOnly) => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.execute_code,
AgentCapabilities.stateful_code_sessions,
];
const req = createMockReq(capabilities);
req.config.endpoints[EModelEndpoint.agents].codeApiMaxRetryWaitMs = 0;
req.config.endpoints[EModelEndpoint.agents].statefulCodeSessions = {
environments: [attachedEnvironment()],
};
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
const result = await loadAgentTools({
req,
res: {},
agent: {
id: 'attached-agent',
tools: [Tools.execute_code],
stateful_code_sessions: true,
code_environment_id: 'personal-machine',
},
definitionsOnly,
});
expect(result.repositoryInstructionSource).toEqual(
expect.objectContaining({ codeApiMaxRetryWaitMs: 0 }),
);
},
);
describe('isActionTool — cross-delimiter collision guard', () => {
it('should identify real action tools', () => {
expect(isActionTool(`get_weather${actionDelimiter}api_example_com`)).toBe(true);
expect(isActionTool(`fetch_data${actionDelimiter}my---domain---com`)).toBe(true);
});
it('should identify action tools whose operationId contains _mcp_', () => {
expect(isActionTool(`sync_mcp_state${actionDelimiter}api---example---com`)).toBe(true);
expect(isActionTool(`get_mcp_config${actionDelimiter}internal---api---com`)).toBe(true);
});
it('should reject MCP tools whose name ends with _action', () => {
expect(isActionTool(`get_action${Constants.mcp_delimiter}myserver`)).toBe(false);
expect(isActionTool(`fetch_action${Constants.mcp_delimiter}server_name`)).toBe(false);
expect(isActionTool(`retrieve_action${Constants.mcp_delimiter}srv`)).toBe(false);
});
it('should reject MCP tools with _action_ in the middle of their name', () => {
expect(isActionTool(`get_action_data${Constants.mcp_delimiter}myserver`)).toBe(false);
expect(isActionTool(`create_action_item${Constants.mcp_delimiter}server`)).toBe(false);
});
it('should reject tools without the action delimiter', () => {
expect(isActionTool('calculator')).toBe(false);
expect(isActionTool(`web_search${Constants.mcp_delimiter}myserver`)).toBe(false);
});
it('known limitation: non-RFC domain with _mcp_ substring yields false negative', () => {
// RFC 952/1123 prohibit underscores in hostnames, so this is not expected in practice.
// Encoded domain `api_mcp_internal_com` places `_mcp_` after `_action_`, which
// the guard interprets as the MCP suffix.
const edgeCaseTool = `getData${actionDelimiter}api_mcp_internal_com`;
expect(isActionTool(edgeCaseTool)).toBe(false);
});
});
describe('loadAgentTools tool-resource content protection', () => {
const opaqueFileFilters = {
files: {
pii: {
fields: ['content'],
starterPatterns: ['sk_prefix'],
uninspectable: 'block',
},
},
};
const patternFilters = (source, fields, regex) => ({
[source]: {
pii: {
fields,
starterPatterns: [],
customPatterns: [{ id: 'private', label: 'private value', regex }],
},
},
});
it.each([true, false])(
'blocks historical execute-code resources before code-file priming (definitionsOnly=%s)',
async (definitionsOnly) => {
const privateFileId = 'file-historical-code';
const req = createMockReq([AgentCapabilities.execute_code]);
req.config.filters = opaqueFileFilters;
mockGetEndpointsConfig.mockResolvedValue(
createEndpointsConfig([AgentCapabilities.execute_code]),
);
await expect(
loadAgentTools({
req,
res: {},
agent: { id: 'agent_code', tools: [Tools.execute_code] },
tool_resources: {
[EToolResources.execute_code]: { file_ids: [privateFileId] },
},
definitionsOnly,
}),
).rejects.toMatchObject({
code: 'content_filter_uninspectable',
message: expect.not.stringContaining(privateFileId),
});
expect(mockLoadToolDefinitions).not.toHaveBeenCalled();
expect(mockPrimeCodeFiles).not.toHaveBeenCalled();
expect(mockPrimeSearchFiles).not.toHaveBeenCalled();
},
);
it.each([true, false])(
'blocks historical file-search resources before search-file priming (definitionsOnly=%s)',
async (definitionsOnly) => {
const privateFileId = 'file-historical-search';
const req = createMockReq([AgentCapabilities.file_search]);
req.config.filters = opaqueFileFilters;
mockGetEndpointsConfig.mockResolvedValue(
createEndpointsConfig([AgentCapabilities.file_search]),
);
await expect(
loadAgentTools({
req,
res: {},
agent: { id: 'agent_search', tools: [Tools.file_search] },
tool_resources: {
[EToolResources.file_search]: { file_ids: [privateFileId] },
},
definitionsOnly,
}),
).rejects.toMatchObject({
code: 'content_filter_uninspectable',
message: expect.not.stringContaining(privateFileId),
});
expect(mockLoadToolDefinitions).not.toHaveBeenCalled();
expect(mockPrimeCodeFiles).not.toHaveBeenCalled();
expect(mockPrimeSearchFiles).not.toHaveBeenCalled();
},
);
it('does not apply prompt policy to canonical file-resource content', async () => {
const privateFilename = 'PRIVATE-FILE.txt';
const req = createMockReq([AgentCapabilities.file_search]);
req.config.filters = patternFilters('prompts', ['name'], privateFilename);
mockGetEndpointsConfig.mockResolvedValue(
createEndpointsConfig([AgentCapabilities.file_search]),
);
await expect(
loadAgentTools({
req,
res: {},
agent: { id: 'agent_search', tools: [Tools.file_search] },
tool_resources: {
[EToolResources.file_search]: {
files: [{ file_id: 'file-safe', filename: privateFilename }],
},
},
definitionsOnly: true,
}),
).resolves.toBeDefined();
expect(mockPrimeSearchFiles).toHaveBeenCalledTimes(1);
expect(mockPrimeCodeFiles).not.toHaveBeenCalled();
});
it('does not apply an unselected file field to canonical resource content', async () => {
const privateContent = 'PRIVATE-CONTENT';
const req = createMockReq([AgentCapabilities.execute_code]);
req.config.filters = patternFilters('files', ['name'], privateContent);
mockGetEndpointsConfig.mockResolvedValue(
createEndpointsConfig([AgentCapabilities.execute_code]),
);
await expect(
loadAgentTools({
req,
res: {},
agent: { id: 'agent_code', tools: [Tools.execute_code] },
tool_resources: {
[EToolResources.execute_code]: {
files: [
{
file_id: 'file-safe',
filename: 'safe.txt',
text: privateContent,
},
],
},
},
definitionsOnly: true,
}),
).resolves.toBeDefined();
expect(mockPrimeCodeFiles).toHaveBeenCalledTimes(1);
expect(mockPrimeSearchFiles).not.toHaveBeenCalled();
});
it('does not log raw code-file priming errors', async () => {
const { logger } = require('@librechat/data-schemas');
const rawValue = 'PRIVATE-CODE-FILE-PROVIDER-ECHO';
const errorSpy = jest.spyOn(logger, 'error');
const providerError = Object.assign(new Error(`Provider echoed ${rawValue}`), {
response: { status: 502, data: { file: rawValue } },
});
mockPrimeCodeFiles.mockRejectedValueOnce(providerError);
const req = createMockReq([AgentCapabilities.execute_code]);
mockGetEndpointsConfig.mockResolvedValue(
createEndpointsConfig([AgentCapabilities.execute_code]),
);
await loadAgentTools({
req,
res: {},
agent: { id: 'agent_code', tools: [Tools.execute_code] },
tool_resources: {
[EToolResources.execute_code]: { file_ids: ['file-safe'] },
},
definitionsOnly: true,
});
expect(errorSpy).toHaveBeenCalledWith(
'[loadToolDefinitionsWrapper] Error priming code files:',
{ type: 'Error', status: 502 },
);
expect(JSON.stringify(errorSpy.mock.calls)).not.toContain(rawValue);
errorSpy.mockRestore();
});
it('does not log raw search-file priming errors', async () => {
const { logger } = require('@librechat/data-schemas');
const rawValue = 'PRIVATE-SEARCH-FILE-PROVIDER-ECHO';
const errorSpy = jest.spyOn(logger, 'error');
const providerError = Object.assign(new Error(`Provider echoed ${rawValue}`), {
response: { status: 503, data: { file: rawValue } },
});
mockPrimeSearchFiles.mockRejectedValueOnce(providerError);
const req = createMockReq([AgentCapabilities.file_search]);
mockGetEndpointsConfig.mockResolvedValue(
createEndpointsConfig([AgentCapabilities.file_search]),
);
await loadAgentTools({
req,
res: {},
agent: { id: 'agent_search', tools: [Tools.file_search] },
tool_resources: {
[EToolResources.file_search]: { file_ids: ['file-safe'] },
},
definitionsOnly: true,
});
expect(errorSpy).toHaveBeenCalledWith(
'[loadToolDefinitionsWrapper] Error priming search files:',
{ type: 'Error', status: 503 },
);
expect(JSON.stringify(errorSpy.mock.calls)).not.toContain(rawValue);
errorSpy.mockRestore();
});
});
describe('loadAgentTools (definitionsOnly=true) — action tool filtering', () => {
const actionToolName = `get_weather${actionDelimiter}api_example_com`;
const regularTool = 'calculator';
it('should preserve the remote-agent permission boundary while priming files', async () => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.file_search,
AgentCapabilities.execute_code,
];
const req = createMockReq(capabilities);
const tool_resources = {
file_search: { file_ids: ['search-file'] },
execute_code: { file_ids: ['code-file'] },
};
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await loadAgentTools({
req,
res: {},
agent: { id: 'agent_123', tools: [Tools.file_search, Tools.execute_code] },
tool_resources,
agentResourceType: ResourceType.REMOTE_AGENT,
definitionsOnly: true,
});
const expectedParams = {
req,
tool_resources,
agentId: 'agent_123',
agentResourceType: ResourceType.REMOTE_AGENT,
};
expect(mockPrimeSearchFiles).toHaveBeenCalledWith(expectedParams);
expect(mockPrimeCodeFiles).toHaveBeenCalledWith({
...expectedParams,
codeApiBaseUrl: 'https://api.librechat.ai/v1',
executionProfile: 'default',
codeFileLocation: 'sandbox',
});
});
it('primes code files through the initializer-selected stateful route', async () => {
const capabilities = [AgentCapabilities.tools, AgentCapabilities.execute_code];
const req = createMockReq(capabilities);
const tool_resources = { execute_code: { file_ids: ['stateful-file'] } };
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await loadAgentTools({
req,
res: {},
agent: { id: 'stateful-agent', tools: [Tools.execute_code] },
tool_resources,
definitionsOnly: true,
codeExecutionContext: {
baseUrl: 'https://stateful-code.example.com',
codeSessionKey: 'execute_code:stateful:v2:user:abc',
executionProfile: 'stateful',
runtimeSessionHint: 'v2:user:abc',
statefulSessions: true,
bridgeWorkerId: 'worker-abc',
},
});
expect(mockPrimeCodeFiles).toHaveBeenCalledWith({
req,
tool_resources,
agentId: 'stateful-agent',
agentResourceType: undefined,
codeApiBaseUrl: 'https://stateful-code.example.com',
executionProfile: 'stateful',
bridgeWorkerId: 'worker-abc',
codeFileLocation: 'sandbox',
});
});
it('primes code files for an attached workspace as unavailable to workspace tools', async () => {
const capabilities = [AgentCapabilities.tools, AgentCapabilities.execute_code];
const req = createMockReq(capabilities);
req.body = {
codeWorkspaces: [{ environmentId: 'personal-machine', workspaceId: 'project-a' }],
};
const tool_resources = { execute_code: { file_ids: ['attached-file'] } };
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await loadAgentTools({
req,
res: {},
agent: { id: 'attached-agent', tools: [Tools.execute_code] },
tool_resources,
definitionsOnly: true,
codeExecutionContext: {
baseUrl: 'http://attached-code.test/v1',
codeSessionKey: 'execute_code:stateful:attached',
executionProfile: 'stateful',
statefulSessions: true,
environmentType: 'attached',
environmentId: 'personal-machine',
bridgeWorkerId: 'worker-abc',
},
});
expect(mockPrimeCodeFiles).toHaveBeenCalledWith(
expect.objectContaining({
tool_resources,
bridgeWorkerId: 'worker-abc',
codeFileLocation: 'programmatic',
}),
);
});
it('propagates a typed CodeAPI resource recovery failure before model invocation', async () => {
const capabilities = [AgentCapabilities.tools, AgentCapabilities.execute_code];
const req = createMockReq(capabilities);
const resourceRecoveryError = Object.assign(new Error('resource recovery required'), {
code: ErrorTypes.RESOURCE_RECOVERY_REQUIRED,
});
mockPrimeCodeFiles.mockRejectedValueOnce(resourceRecoveryError);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await expect(
loadAgentTools({
req,
res: {},
agent: {
id: 'agent_123',
tools: [Tools.execute_code, 'run_query_mcp_warehouse'],
},
tool_resources: { execute_code: { file_ids: ['stale-file'] } },
definitionsOnly: true,
}),
).rejects.toBe(resourceRecoveryError);
});
it('should exclude action tools from definitions when actions capability is disabled', async () => {
const capabilities = [AgentCapabilities.tools, AgentCapabilities.web_search];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await loadAgentTools({
req,
res: {},
agent: { id: 'agent_123', tools: [regularTool, actionToolName] },
definitionsOnly: true,
});
expect(mockLoadToolDefinitions).toHaveBeenCalledTimes(1);
const [callArgs] = mockLoadToolDefinitions.mock.calls[0];
expect(callArgs.tools).toContain(regularTool);
expect(callArgs.tools).not.toContain(actionToolName);
});
it('should include action tools in definitions when actions capability is enabled', async () => {
const capabilities = [AgentCapabilities.tools, AgentCapabilities.actions];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await loadAgentTools({
req,
res: {},
agent: { id: 'agent_123', tools: [regularTool, actionToolName] },
definitionsOnly: true,
});
expect(mockLoadToolDefinitions).toHaveBeenCalledTimes(1);
const [callArgs] = mockLoadToolDefinitions.mock.calls[0];
expect(callArgs.tools).toContain(regularTool);
expect(callArgs.tools).toContain(actionToolName);
});
it('blocks a persisted action schema before domain parsing during definition loading', async () => {
const capabilities = [AgentCapabilities.tools, AgentCapabilities.actions];
const req = createMockReq(capabilities);
req.config.filters = {
toolArguments: {
pii: {
fields: ['arguments'],
starterPatterns: [],
customPatterns: [
{
id: 'private',
label: 'private value',
regex: 'PRIVATE-[A-Z]+',
},
],
},
},
};
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockLoadActionSets.mockResolvedValue([
{
action_id: 'action_private_schema',
metadata: {
domain: 'https://api.example.com',
raw_spec: '{"description":"PRIVATE-SCHEMA"}',
},
},
]);
mockLoadToolDefinitions.mockImplementationOnce(async (_options, dependencies) => {
await dependencies.getActionToolDefinitions('agent_123', [actionToolName]);
return {
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
};
});
await expect(
loadAgentTools({
req,
res: {},
agent: { id: 'agent_123', tools: [actionToolName] },
definitionsOnly: true,
}),
).rejects.toMatchObject({
code: 'content_filter_block',
body: {
source: 'tool_argument',
field: 'arguments',
},
});
expect(mockDecryptMetadata).not.toHaveBeenCalled();
expect(mockDomainParser).not.toHaveBeenCalled();
});
it('blocks decrypted persisted action secrets before definition-time domain work', async () => {
const capabilities = [AgentCapabilities.tools, AgentCapabilities.actions];
const req = createMockReq(capabilities);
req.config.filters = {
actionMetadata: {
pii: {
fields: ['api_key'],
starterPatterns: [],
customPatterns: [
{
id: 'private',
label: 'private value',
regex: 'PRIVATE-[A-Z]+',
},
],
},
},
};
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
const metadata = {
domain: 'https://api.example.com',
raw_spec: '{}',
api_key: 'encrypted-value',
};
mockLoadActionSets.mockResolvedValue([
{
action_id: 'action_private_auth',
metadata,
},
]);
mockDecryptMetadata.mockResolvedValue({
...metadata,
api_key: 'PRIVATE-AUTH',
});
mockLoadToolDefinitions.mockImplementationOnce(async (_options, dependencies) => {
await dependencies.getActionToolDefinitions('agent_123', [actionToolName]);
return {
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
};
});
await expect(
loadAgentTools({
req,
res: {},
agent: { id: 'agent_123', tools: [actionToolName] },
definitionsOnly: true,
}),
).rejects.toMatchObject({
code: 'content_filter_block',
body: {
source: 'action_metadata',
field: 'api_key',
},
});
expect(mockDecryptMetadata).toHaveBeenCalledWith(metadata);
expect(mockDomainParser).not.toHaveBeenCalled();
});
it.each([
[
'inactive secret-field policy',
{
actionMetadata: {
pii: {
fields: ['api_key'],
starterPatterns: [],
},
},
},
],
[
'active plaintext-field policy',
{
actionMetadata: {
pii: {
fields: ['raw_spec'],
starterPatterns: [],
customPatterns: [
{
id: 'private',
label: 'private value',
regex: 'PRIVATE-[A-Z]+',
},
],
},
},
},
],
])('does not decrypt action metadata for an %s', async (_label, filters) => {
const capabilities = [AgentCapabilities.tools, AgentCapabilities.actions];
const req = createMockReq(capabilities);
req.config.filters = filters;
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockLoadToolDefinitions.mockReset().mockResolvedValue({
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
});
mockLoadActionSets.mockResolvedValue([
{
action_id: 'action_safe_metadata',
metadata: {
domain: 'https://api.example.com',
raw_spec: '{}',
api_key: 'encrypted-value',
},
},
]);
await loadAgentTools({
req,
res: {},
agent: { id: 'agent_123', tools: [actionToolName] },
definitionsOnly: true,
});
expect(mockDecryptMetadata).not.toHaveBeenCalled();
});
it('blocks persisted action metadata before MCP definition initialization', async () => {
const capabilities = [AgentCapabilities.tools, AgentCapabilities.actions];
const req = createMockReq(capabilities);
const mcpTool = `search${Constants.mcp_delimiter}private-server`;
req.config.filters = {
actionMetadata: {
pii: {
fields: ['raw_spec'],
starterPatterns: [],
customPatterns: [
{
id: 'private',
label: 'private value',
regex: 'PRIVATE-[A-Z]+',
},
],
},
},
};
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockLoadActionSets.mockResolvedValue([
{
action_id: 'action_private_before_mcp',
metadata: {
domain: 'https://api.example.com',
raw_spec: '{"description":"PRIVATE-ACTION"}',
},
},
]);
mockLoadToolDefinitions.mockImplementationOnce(async (options, dependencies) => {
await dependencies.getOrFetchMCPServerTools(options.userId, 'private-server');
await dependencies.getActionToolDefinitions('agent_123', [actionToolName]);
return {
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
};
});
await expect(
loadAgentTools({
req,
res: {},
agent: { id: 'agent_123', tools: [mcpTool, actionToolName] },
definitionsOnly: true,
}),
).rejects.toMatchObject({
code: 'content_filter_block',
body: {
source: 'action_metadata',
field: 'raw_spec',
},
});
expect(mockLoadToolDefinitions).not.toHaveBeenCalled();
expect(mockGetUserMCPAuthMap).not.toHaveBeenCalled();
expect(mockResolveConfigServers).not.toHaveBeenCalled();
expect(reinitMCPServer).not.toHaveBeenCalled();
});
it('should exclude ask_user_question when its capability is disabled (even if tools is enabled)', async () => {
// ask_user_question is gated by its OWN capability, like execute_code —
// NOT the generic `tools` capability. Here `tools` is on but the ask
// capability is not, so the tool must be filtered out.
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await loadAgentTools({
req,
res: {},
agent: { id: 'agent_123', tools: [regularTool, 'ask_user_question'] },
definitionsOnly: true,
});
expect(mockLoadToolDefinitions).toHaveBeenCalledTimes(1);
const [callArgs] = mockLoadToolDefinitions.mock.calls[0];
expect(callArgs.tools).toContain(regularTool);
expect(callArgs.tools).not.toContain('ask_user_question');
});
it('should include ask_user_question when its capability is enabled', async () => {
const capabilities = [AgentCapabilities.tools, AgentCapabilities.ask_user_question];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await loadAgentTools({
req,
res: {},
agent: { id: 'agent_123', tools: [regularTool, 'ask_user_question'] },
definitionsOnly: true,
});
expect(mockLoadToolDefinitions).toHaveBeenCalledTimes(1);
const [callArgs] = mockLoadToolDefinitions.mock.calls[0];
expect(callArgs.tools).toContain('ask_user_question');
});
it('should not filter MCP tools whose name contains _action (cross-delimiter collision)', async () => {
const mcpToolWithAction = `get_action${Constants.mcp_delimiter}myserver`;
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await loadAgentTools({
req,
res: {},
agent: { id: 'agent_123', tools: [regularTool, mcpToolWithAction] },
definitionsOnly: true,
});
expect(mockLoadToolDefinitions).toHaveBeenCalledTimes(1);
const [callArgs] = mockLoadToolDefinitions.mock.calls[0];
expect(callArgs.tools).toContain(mcpToolWithAction);
expect(callArgs.tools).toContain(regularTool);
});
it('fails initialization when an explicitly selected MCP tool cannot be resolved', async () => {
const mcpTool = `search${Constants.mcp_delimiter}warehouse`;
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockResolveConfigServers.mockResolvedValue({
warehouse: {
type: 'streamable-http',
url: 'https://mcp.example.com/warehouse',
},
});
mockLoadToolDefinitions.mockResolvedValueOnce({
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
mcpResolution: { expectedToolCount: 1, resolvedToolCount: 0 },
});
await expect(
loadAgentTools({
req,
res: {},
agent: { id: 'agent_123', name: 'Target Agent', tools: [mcpTool] },
definitionsOnly: true,
}),
).rejects.toMatchObject({
code: 'AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE',
statusCode: 503,
message: expect.stringContaining('can access its selected tools'),
});
});
it('fails closed when MCP definition loading throws before resolution completes', async () => {
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockLoadToolDefinitions.mockRejectedValueOnce(new Error('MCP registry unavailable'));
await expect(
loadAgentTools({
req,
res: {},
agent: {
id: 'agent_123',
name: 'Target Agent',
tools: [`run_query${Constants.mcp_delimiter}warehouse`],
},
definitionsOnly: true,
}),
).rejects.toMatchObject({
code: 'AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE',
statusCode: 503,
cause: expect.objectContaining({ message: 'MCP registry unavailable' }),
});
});
it('allows a server pin with no explicitly selected MCP tools', async () => {
const serverPin = `${Constants.mcp_server}${Constants.mcp_delimiter}warehouse`;
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockLoadToolDefinitions.mockResolvedValueOnce({
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
mcpResolution: { expectedToolCount: 0, resolvedToolCount: 0 },
});
await expect(
loadAgentTools({
req,
res: {},
agent: { id: 'agent_123', tools: [serverPin] },
definitionsOnly: true,
}),
).resolves.toMatchObject({ toolDefinitions: [] });
});
it('allows partial MCP resolution when at least one expected tool is available', async () => {
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockLoadToolDefinitions.mockResolvedValueOnce({
toolDefinitions: [{ name: 'list_sources_mcp_warehouse', toolType: 'mcp' }],
toolRegistry: new Map(),
hasDeferredTools: false,
mcpResolution: { expectedToolCount: 2, resolvedToolCount: 1 },
});
await expect(
loadAgentTools({
req,
res: {},
agent: {
id: 'agent_123',
tools: [
`list_sources${Constants.mcp_delimiter}warehouse`,
`run_query${Constants.mcp_delimiter}warehouse`,
],
},
definitionsOnly: true,
}),
).resolves.toMatchObject({
toolDefinitions: [expect.objectContaining({ name: 'list_sources_mcp_warehouse' })],
});
});
it('should filter MCP tool definitions when user lacks MCP server use permission', async () => {
const { userCanUseMCPServers } = require('~/server/services/MCP');
userCanUseMCPServers.mockResolvedValueOnce(false);
const mcpTool = `search${Constants.mcp_delimiter}myserver`;
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await loadAgentTools({
req,
res: {},
agent: { id: 'agent_123', tools: [regularTool, mcpTool] },
definitionsOnly: true,
});
expect(mockLoadToolDefinitions).toHaveBeenCalledTimes(1);
const [callArgs] = mockLoadToolDefinitions.mock.calls[0];
expect(callArgs.tools).toContain(regularTool);
expect(callArgs.tools).not.toContain(mcpTool);
});
it('fails explicitly when MCP permission filtering removes every expected tool', async () => {
const { userCanUseMCPServers } = require('~/server/services/MCP');
userCanUseMCPServers.mockResolvedValueOnce(false);
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await expect(
loadAgentTools({
req,
res: {},
agent: {
id: 'agent_123',
tools: [`run_query${Constants.mcp_delimiter}warehouse`],
},
definitionsOnly: true,
}),
).rejects.toMatchObject({
code: 'AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE',
statusCode: 503,
});
expect(mockLoadToolDefinitions).not.toHaveBeenCalled();
});
it('should return actionsEnabled in the result', async () => {
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
const result = await loadAgentTools({
req,
res: {},
agent: { id: 'agent_123', tools: [regularTool] },
definitionsOnly: true,
});
expect(result.actionsEnabled).toBe(false);
});
it('emits separate MCP OAuth login steps and completion events for multiple pending servers', async () => {
const req = createMockReq([AgentCapabilities.tools]);
const res = { writableEnded: false };
const servers = ['ELI', 'Vespa'];
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig([AgentCapabilities.tools]));
mockResolveConfigServers.mockResolvedValue(
Object.fromEntries(
servers.map((serverName) => [
serverName,
{
type: 'streamable-http',
url: `https://mcp.example.com/${serverName}`,
requiresOAuth: true,
},
]),
),
);
mockLoadToolDefinitions
.mockImplementationOnce(async (_args, deps) => {
await deps.getOrFetchMCPServerTools(req.user.id, servers[0]);
await deps.getOrFetchMCPServerTools(req.user.id, servers[1]);
return {
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
};
})
.mockResolvedValue({
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
});
reinitMCPServer.mockImplementation(
async ({ serverName, returnOnOAuth, oauthStart, oauthEnd }) => {
if (returnOnOAuth === false) {
await oauthStart(`https://auth.example.com/${serverName}`);
await oauthEnd();
return { availableTools: { [`tool_${serverName}`]: {} } };
}
await oauthStart(`https://auth.example.com/${serverName}`);
return { availableTools: null };
},
);
await loadAgentTools({
req,
res,
agent: {
id: 'agent_123',
tools: servers.map((server) => `search${Constants.mcp_delimiter}${server}`),
},
definitionsOnly: true,
});
const runStepEvents = mockSendEvent.mock.calls
.map(([, event]) => event)
.filter((event) => event.data?.stepDetails?.type === 'tool_calls');
const deltaEvents = mockSendEvent.mock.calls
.map(([, event]) => event)
.filter((event) => event.data?.delta?.type === 'tool_calls');
const authDeltaEvents = deltaEvents.filter((event) => event.data.delta.auth);
const completionEvents = mockSendEvent.mock.calls
.map(([, event]) => event)
.filter((event) => event.data?.result?.tool_call?.name?.startsWith('oauth'));
expect(runStepEvents.map((event) => event.data.index)).toEqual([0, 1]);
expect(authDeltaEvents.map((event) => event.data.id)).toEqual([
'step_oauth_login_ELI',
'step_oauth_login_Vespa',
]);
expect(completionEvents.map((event) => event.data.result.id)).toEqual([
'step_oauth_login_ELI',
'step_oauth_login_Vespa',
]);
});
it('does not count an empty post-OAuth catalog as tools available or reload definitions', async () => {
const req = createMockReq([AgentCapabilities.tools]);
const res = { writableEnded: false };
const serverName = 'Empty-Catalog';
const mcpTool = `search${Constants.mcp_delimiter}${serverName}`;
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig([AgentCapabilities.tools]));
mockResolveConfigServers.mockResolvedValue({
[serverName]: {
type: 'streamable-http',
url: 'https://mcp.example.com/empty',
requiresOAuth: true,
},
});
mockGetMCPServerTools.mockResolvedValue(null);
mockFlowManager.getFlowState.mockResolvedValue(null);
mockLoadToolDefinitions.mockImplementationOnce(async (params, deps) => {
await deps.getOrFetchMCPServerTools(params.userId, serverName);
return {
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
mcpResolution: { resolvedToolCount: 1 },
};
});
reinitMCPServer
.mockImplementationOnce(async ({ oauthStart }) => {
await oauthStart(`https://auth.example.com/${serverName}`);
return { availableTools: null };
})
.mockResolvedValueOnce({ availableTools: {} });
const result = await loadAgentTools({
req,
res,
agent: { id: 'agent_123', tools: [mcpTool] },
definitionsOnly: true,
});
expect(result.toolDefinitions).toEqual([]);
expect(result.mcpAvailableTools).toEqual({});
expect(mockLoadToolDefinitions).toHaveBeenCalledTimes(1);
});
describe('sign-in deferred to the first tool call', () => {
const serverName = 'Sheets';
const mcpTool = `read${Constants.mcp_delimiter}${serverName}`;
const ownCatalog = {
[mcpTool]: {
type: 'function',
function: { name: mcpTool, description: 'Read a sheet', parameters: {} },
},
};
const declaredCatalog = {
[mcpTool]: {
type: 'function',
function: {
name: mcpTool,
description: 'Read a sheet',
parameters: { type: 'object', properties: {} },
},
},
};
const capabilities = [AgentCapabilities.tools, AgentCapabilities.deferred_tools];
const deferredAgent = {
id: 'agent_123',
tools: [mcpTool],
tool_options: { [mcpTool]: { defer_loading: true } },
};
const setUp = (serverConfig) => {
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockResolveConfigServers.mockResolvedValue({
[serverName]: {
type: 'streamable-http',
url: 'https://mcp.example.com/sheets',
requiresOAuth: true,
oauthPrompt: 'on_use',
oauthToolCatalog: [{ name: 'read', description: 'Read a sheet' }],
...serverConfig,
},
});
mockGetMCPServerTools.mockResolvedValue(null);
mockFlowManager.getFlowState.mockResolvedValue(null);
mockLoadToolDefinitions.mockImplementation(async (params, deps) => {
const fetched = await deps.getOrFetchMCPServerTools(params.userId, serverName);
return {
toolDefinitions: fetched ? [{ name: mcpTool }] : [],
toolRegistry: new Map(),
hasDeferredTools: fetched != null,
mcpResolution: { resolvedToolCount: fetched ? 1 : 0 },
};
});
reinitMCPServer.mockImplementation(async ({ returnOnOAuth, oauthStart }) => {
if (returnOnOAuth === false) {
return { availableTools: ownCatalog };
}
await oauthStart('https://auth.example.com/sheets');
return { availableTools: null };
});
};
const oauthEvents = () =>
mockSendEvent.mock.calls.filter(([, event]) =>
event.data?.stepDetails?.tool_calls?.some((call) => call.name?.startsWith('oauth')),
);
it('offers the declared catalog without prompting or waiting', async () => {
setUp();
const result = await loadAgentTools({
req: createMockReq(capabilities),
res: { writableEnded: false },
agent: deferredAgent,
definitionsOnly: true,
});
expect(result.toolDefinitions).toEqual([{ name: mcpTool }]);
expect(result.mcpAvailableTools).toEqual({ [serverName]: declaredCatalog });
expect(reinitMCPServer).toHaveBeenCalledTimes(1);
expect(reinitMCPServer).not.toHaveBeenCalledWith(
expect.objectContaining({ returnOnOAuth: false }),
);
expect(oauthEvents()).toHaveLength(0);
});
it('does not replay an earlier pending sign-in at turn start', async () => {
setUp();
mockFlowManager.getFlowState.mockResolvedValue({
status: 'PENDING',
createdAt: Date.now(),
metadata: { authorizationUrl: 'https://auth.example.com/sheets' },
});
const result = await loadAgentTools({
req: createMockReq(capabilities),
res: { writableEnded: false },
agent: deferredAgent,
definitionsOnly: true,
});
expect(result.mcpAvailableTools).toEqual({ [serverName]: declaredCatalog });
expect(reinitMCPServer).not.toHaveBeenCalled();
expect(oauthEvents()).toHaveLength(0);
});
it("uses the user's own cached catalog without replaying a pending sign-in", async () => {
setUp();
mockGetMCPServerTools.mockResolvedValue(ownCatalog);
mockFlowManager.getFlowState.mockResolvedValue({
status: 'PENDING',
createdAt: Date.now(),
metadata: { authorizationUrl: 'https://auth.example.com/sheets' },
});
const result = await loadAgentTools({
req: createMockReq(capabilities),
res: { writableEnded: false },
agent: deferredAgent,
definitionsOnly: true,
});
expect(result.mcpAvailableTools).toEqual({ [serverName]: ownCatalog });
expect(reinitMCPServer).not.toHaveBeenCalled();
expect(oauthEvents()).toHaveLength(0);
});
it('signs in at turn start when the operator declared no catalog', async () => {
setUp({ oauthToolCatalog: undefined });
await loadAgentTools({
req: createMockReq(capabilities),
res: { writableEnded: false },
agent: deferredAgent,
definitionsOnly: true,
});
expect(reinitMCPServer).toHaveBeenCalledWith(
expect.objectContaining({ serverName, returnOnOAuth: false }),
);
expect(oauthEvents()).toHaveLength(1);
});
it.each([
['the server keeps the default prompt', { oauthPrompt: undefined }, deferredAgent],
[
'a selected tool is not deferred',
{},
{ ...deferredAgent, tool_options: { [mcpTool]: { defer_loading: false } } },
],
])('signs in at turn start when %s', async (_label, serverConfig, agent) => {
setUp(serverConfig);
await loadAgentTools({
req: createMockReq(capabilities),
res: { writableEnded: false },
agent,
definitionsOnly: true,
});
expect(oauthEvents()).toHaveLength(1);
});
});
it('fences resumable MCP OAuth definition events to the owning job epoch', async () => {
const req = createMockReq([AgentCapabilities.tools]);
const res = { writableEnded: false };
const serverName = 'Epoch-Server';
const streamId = 'stream-epoch';
const jobCreatedAt = 1234;
const mcpTool = `search${Constants.mcp_delimiter}${serverName}`;
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig([AgentCapabilities.tools]));
mockResolveConfigServers.mockResolvedValue({
[serverName]: {
type: 'streamable-http',
url: `https://mcp.example.com/${serverName}`,
requiresOAuth: true,
},
});
mockLoadToolDefinitions
.mockImplementationOnce(async (_args, deps) => {
await deps.getOrFetchMCPServerTools(req.user.id, serverName);
return {
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
};
})
.mockResolvedValue({
toolDefinitions: [mcpTool],
toolRegistry: new Map(),
hasDeferredTools: false,
});
reinitMCPServer.mockImplementation(async ({ returnOnOAuth, oauthStart, oauthEnd }) => {
await oauthStart(`https://auth.example.com/${serverName}`);
if (returnOnOAuth === false) {
await oauthEnd();
return { availableTools: { [mcpTool]: {} } };
}
return { availableTools: null };
});
await loadAgentTools({
req,
res,
agent: { id: 'agent_123', tools: [mcpTool] },
definitionsOnly: true,
streamId,
jobCreatedAt,
});
expect(mockSendEvent).not.toHaveBeenCalled();
expect(mockEmitChunk).toHaveBeenCalledTimes(3);
expect(mockEmitChunk.mock.calls.map(([, event]) => event.event)).toEqual([
'on_run_step',
'on_run_step_delta',
'on_run_step_completed',
]);
for (const [emittedStreamId, , options] of mockEmitChunk.mock.calls) {
expect(emittedStreamId).toBe(streamId);
expect(options).toEqual({ expectedCreatedAt: jobCreatedAt });
}
for (const [reinitInput] of reinitMCPServer.mock.calls) {
expect(reinitInput).toEqual(expect.objectContaining({ streamId, jobCreatedAt }));
}
});
it('should not expose cached MCP tool definitions when the registry lookup fails', async () => {
const serverName = 'PRIVATE-MCP-SERVER-NAME';
const privateRegistryError = 'PRIVATE-MCP-REGISTRY-ERROR';
const mcpTool = `search${Constants.mcp_delimiter}${serverName}`;
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
const warnSpy = jest
.spyOn(require('@librechat/data-schemas').logger, 'warn')
.mockImplementation(() => {});
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockGetServerConfig.mockImplementation(() => {
throw new Error(privateRegistryError);
});
mockGetMCPServerTools.mockResolvedValue({
[mcpTool]: {
function: {
name: mcpTool,
description: 'Cached private search',
parameters: {},
},
},
});
mockLoadToolDefinitions.mockImplementation(async (params, deps) => {
const serverTools = await deps.getOrFetchMCPServerTools(params.userId, serverName);
return {
toolDefinitions: serverTools ? Object.keys(serverTools) : [],
toolRegistry: new Map(),
hasDeferredTools: false,
};
});
const result = await loadAgentTools({
req,
res: {},
agent: { id: 'agent_123', tools: [mcpTool] },
definitionsOnly: true,
});
const loggedText = warnSpy.mock.calls.flat().map(String).join('\n');
expect(result.toolDefinitions).toEqual([]);
expect(mockGetMCPServerTools).not.toHaveBeenCalled();
expect(loggedText).not.toContain(serverName);
expect(loggedText).not.toContain(privateRegistryError);
expect(warnSpy).toHaveBeenCalledWith(
'[Tool Definitions] MCP registry unavailable; skipping tool exposure for one server',
);
warnSpy.mockRestore();
});
it('should re-emit pending MCP OAuth prompts when cached tool definitions exist', async () => {
const serverName = 'Google-Workspace';
const authorizationUrl = 'https://auth.example.com/Google-Workspace';
const mcpTool = `search${Constants.mcp_delimiter}${serverName}`;
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
const res = { writableEnded: false };
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockGetServerConfig.mockResolvedValue({
type: 'streamable-http',
url: 'https://demo.librechat.ai/mcp',
requiresOAuth: true,
});
mockGetMCPServerTools.mockResolvedValue({
[mcpTool]: {
function: {
name: mcpTool,
description: 'Cached search',
parameters: {},
},
},
});
mockFlowManager.getFlowState.mockResolvedValue({
status: 'PENDING',
createdAt: Date.now(),
metadata: { authorizationUrl },
});
mockLoadToolDefinitions.mockImplementation(async (params, deps) => {
const serverTools = await deps.getOrFetchMCPServerTools(params.userId, serverName);
return {
toolDefinitions: serverTools ? Object.keys(serverTools) : [],
toolRegistry: new Map(),
hasDeferredTools: false,
};
});
reinitMCPServer.mockImplementation(async ({ oauthStart }) => {
await oauthStart(authorizationUrl);
return { availableTools: { [mcpTool]: {} } };
});
const result = await loadAgentTools({
req,
res,
agent: { id: 'agent_123', tools: [mcpTool] },
definitionsOnly: true,
});
expect(result.toolDefinitions).toEqual([mcpTool]);
expect(mockGetMCPServerTools).toHaveBeenCalledWith(
req.user.id,
serverName,
expect.objectContaining({ requiresOAuth: true }),
'standard',
);
expect(reinitMCPServer).toHaveBeenCalledWith(
expect.objectContaining({
serverName,
returnOnOAuth: false,
oauthStart: expect.any(Function),
}),
);
expect(mockSendEvent).toHaveBeenCalledWith(
res,
expect.objectContaining({
event: 'on_run_step',
data: expect.objectContaining({
id: `step_oauth_login_${serverName}`,
}),
}),
);
expect(mockSendEvent).toHaveBeenCalledWith(
res,
expect.objectContaining({
event: 'on_run_step_delta',
data: expect.objectContaining({
id: `step_oauth_login_${serverName}`,
delta: expect.objectContaining({
auth: authorizationUrl,
}),
}),
}),
);
});
it('should not join in-flight MCP initialization before replaying pending OAuth prompts', 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 };
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(async ({ oauthStart }) => {
await oauthStart(authorizationUrl);
return { availableTools: null };
});
await loadAgentTools({
req,
res,
agent: { id: 'agent_123', tools: [mcpTool] },
definitionsOnly: true,
});
expect(mockGetMCPServerTools).toHaveBeenCalledWith(
req.user.id,
serverName,
expect.objectContaining({ requiresOAuth: true }),
'standard',
);
expect(reinitMCPServer).toHaveBeenCalledTimes(1);
expect(reinitMCPServer).toHaveBeenCalledWith(
expect.objectContaining({
serverName,
returnOnOAuth: false,
oauthStart: expect.any(Function),
}),
);
expect(mockSendEvent).toHaveBeenCalledWith(
res,
expect.objectContaining({
event: 'on_run_step_delta',
data: expect.objectContaining({
id: `step_oauth_login_${serverName}`,
delta: expect.objectContaining({
auth: authorizationUrl,
}),
}),
}),
);
});
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';
const mcpTool = `search${Constants.mcp_delimiter}${serverName}`;
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
/** A server whose own name contains the delimiter is only resolvable
* against the configured set, so the key boundary is unambiguous. */
mockResolveConfigServers.mockResolvedValue({ [serverName]: {} });
const res = { writableEnded: false };
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockFlowManager.getFlowState.mockResolvedValue({
status: 'PENDING',
createdAt: Date.now(),
metadata: { authorizationUrl },
});
mockLoadToolDefinitions.mockResolvedValue({
toolDefinitions: [mcpTool],
toolRegistry: new Map(),
hasDeferredTools: false,
});
reinitMCPServer.mockImplementation(async ({ oauthStart }) => {
await oauthStart(authorizationUrl);
return { availableTools: { [mcpTool]: {} } };
});
const result = await loadAgentTools({
req,
res,
agent: { id: 'agent_123', tools: [mcpTool] },
definitionsOnly: true,
});
expect(result.toolDefinitions).toEqual([mcpTool]);
expect(mockGetMCPServerTools).not.toHaveBeenCalled();
expect(reinitMCPServer).toHaveBeenCalledWith(
expect.objectContaining({
serverName,
returnOnOAuth: false,
oauthStart: expect.any(Function),
}),
);
expect(mockSendEvent).toHaveBeenCalledWith(
res,
expect.objectContaining({
event: 'on_run_step_delta',
data: expect.objectContaining({
id: `step_oauth_login_${serverName}`,
delta: expect.objectContaining({
auth: authorizationUrl,
}),
}),
}),
);
});
it('should emit stored pending MCP OAuth prompts before waiting on a silent in-flight join', async () => {
const serverName = 'Google-Workspace';
const authorizationUrl = 'https://auth.example.com/Google-Workspace';
const mcpTool = `search${Constants.mcp_delimiter}${serverName}`;
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
const res = { writableEnded: false };
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockFlowManager.getFlowState.mockResolvedValue({
status: 'PENDING',
createdAt: Date.now(),
metadata: { authorizationUrl },
});
mockLoadToolDefinitions.mockResolvedValue({
toolDefinitions: [mcpTool],
toolRegistry: new Map(),
hasDeferredTools: false,
});
reinitMCPServer.mockResolvedValue({ availableTools: null });
const result = await loadAgentTools({
req,
res,
agent: { id: 'agent_123', tools: [mcpTool] },
definitionsOnly: true,
});
expect(result.toolDefinitions).toEqual([mcpTool]);
expect(reinitMCPServer).toHaveBeenCalledWith(
expect.objectContaining({
serverName,
returnOnOAuth: false,
oauthStart: expect.any(Function),
}),
);
expect(mockSendEvent).toHaveBeenCalledWith(
res,
expect.objectContaining({
event: 'on_run_step_delta',
data: expect.objectContaining({
id: `step_oauth_login_${serverName}`,
delta: expect.objectContaining({
auth: authorizationUrl,
}),
}),
}),
);
});
it('should preserve OAuth URLs emitted while discovering MCP tools before a silent wait join', async () => {
const serverName = 'Google-Workspace';
const authorizationUrl = 'https://auth.example.com/Google-Workspace';
const mcpTool = `search${Constants.mcp_delimiter}${serverName}`;
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
const res = { writableEnded: false };
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockGetServerConfig.mockResolvedValue({
type: 'streamable-http',
url: 'https://demo.librechat.ai/mcp',
requiresOAuth: true,
});
mockGetMCPServerTools.mockResolvedValue(null);
mockFlowManager.getFlowState.mockResolvedValue(null);
mockLoadToolDefinitions.mockImplementation(async (params, deps) => {
await deps.getOrFetchMCPServerTools(params.userId, serverName);
return {
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
};
});
reinitMCPServer
.mockImplementationOnce(async ({ oauthStart }) => {
await oauthStart(authorizationUrl, { expiresAt: Date.now() + 60_000 });
return { availableTools: null };
})
.mockResolvedValue({ availableTools: null });
await loadAgentTools({
req,
res,
agent: { id: 'agent_123', tools: [mcpTool] },
definitionsOnly: true,
});
expect(reinitMCPServer).toHaveBeenCalledTimes(2);
expect(mockSendEvent).toHaveBeenCalledWith(
res,
expect.objectContaining({
event: 'on_run_step_delta',
data: expect.objectContaining({
id: `step_oauth_login_${serverName}`,
delta: expect.objectContaining({
auth: authorizationUrl,
}),
}),
}),
);
});
it('should pass request body context into MCP tool definition reinitialization', async () => {
const serverName = 'Body-Scoped';
const mcpTool = `search${Constants.mcp_delimiter}${serverName}`;
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
req.body = { conversationId: 'conv-123', messageId: 'msg-123' };
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockGetServerConfig.mockResolvedValue({
type: 'streamable-http',
url: 'https://demo.librechat.ai/messages/{{LIBRECHAT_BODY_MESSAGEID}}/mcp',
source: 'yaml',
});
mockGetMCPServerTools.mockResolvedValue(null);
mockFlowManager.getFlowState.mockResolvedValue(null);
mockLoadToolDefinitions.mockImplementation(async (params, deps) => {
await deps.getOrFetchMCPServerTools(params.userId, serverName);
return {
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
};
});
reinitMCPServer.mockResolvedValue({ availableTools: null });
await loadAgentTools({
req,
agent: { id: 'agent_123', tools: [mcpTool] },
definitionsOnly: true,
});
expect(reinitMCPServer).toHaveBeenCalledWith(
expect.objectContaining({
serverName,
requestBody: req.body,
}),
);
expect(mockGetMCPServerTools).toHaveBeenCalledWith(
req.user.id,
serverName,
expect.objectContaining({
url: expect.stringContaining('LIBRECHAT_BODY_MESSAGEID'),
}),
'standard',
);
});
it('forwards OBO context through forced MCP catalog refreshes', async () => {
const serverName = 'OBO-Refresh';
const mcpTool = `search${Constants.mcp_delimiter}${serverName}`;
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
req.user = {
id: 'user_123',
provider: 'openid',
openidId: 'oidc-sub-123',
tenantId: 'tenant-1',
openidIssuer: 'https://issuer.example.com',
};
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,
});
expect(reinitMCPServer).toHaveBeenCalledWith(
expect.objectContaining({
serverName,
forceNew: true,
upstreamTokenProvider: expect.any(Function),
oboIdentityContext: expect.objectContaining({
appUserId: 'user_123',
openidSubject: 'oidc-sub-123',
tenantId: 'tenant-1',
openidIssuer: 'https://issuer.example.com',
}),
}),
);
});
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,
streamId: 'scheduled-stream',
jobCreatedAt: 42,
});
expect(reinitMCPServer).toHaveBeenCalledWith(
expect.objectContaining({
serverName,
forceNew: true,
upstreamTokenProvider: scheduledProvider,
streamId: 'scheduled-stream',
jobCreatedAt: 42,
}),
);
});
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}`;
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
req.body = { conversationId: 'conv-123', messageId: 'msg-123' };
const availableTools = {
[mcpTool]: {
function: {
name: mcpTool,
description: 'List tables',
parameters: { type: 'object', properties: {} },
},
},
};
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockGetServerConfig.mockResolvedValue({
type: 'streamable-http',
url: 'https://mcp.example.com/{{LIBRECHAT_BODY_MESSAGEID}}/mcp',
source: 'yaml',
});
mockGetMCPServerTools.mockResolvedValue(null);
mockFlowManager.getFlowState.mockResolvedValue(null);
mockLoadToolDefinitions.mockImplementation(async (params, deps) => {
const serverTools = await deps.getOrFetchMCPServerTools(params.userId, serverName);
return {
toolDefinitions: serverTools ? Object.keys(serverTools) : [],
toolRegistry: new Map([[mcpTool, { name: mcpTool }]]),
hasDeferredTools: false,
};
});
reinitMCPServer.mockResolvedValue({ availableTools });
const result = await loadAgentTools({
req,
agent: { id: 'agent_123', tools: [mcpTool] },
definitionsOnly: true,
});
expect(result.toolDefinitions).toEqual([mcpTool]);
expect(result.mcpAvailableTools).toEqual({ [serverName]: availableTools });
expect(mockGetMCPServerTools).toHaveBeenCalledWith(
req.user.id,
serverName,
expect.objectContaining({
url: expect.stringContaining('LIBRECHAT_BODY_MESSAGEID'),
}),
'standard',
);
});
it('should preserve pending-flow expiry for OAuth URLs captured during discovery', async () => {
const serverName = 'Google-Workspace';
const authorizationUrl = 'https://auth.example.com/Google-Workspace';
const mcpTool = `search${Constants.mcp_delimiter}${serverName}`;
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
const res = { writableEnded: false };
const createdAt = Date.now() - 45_000;
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockGetServerConfig.mockResolvedValue({
type: 'streamable-http',
url: 'https://demo.librechat.ai/mcp',
requiresOAuth: true,
});
mockGetMCPServerTools.mockResolvedValue(null);
mockFlowManager.getFlowState.mockResolvedValueOnce(null).mockResolvedValueOnce({
status: 'PENDING',
createdAt,
metadata: { authorizationUrl },
});
mockLoadToolDefinitions.mockImplementation(async (params, deps) => {
await deps.getOrFetchMCPServerTools(params.userId, serverName);
return {
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
};
});
reinitMCPServer
.mockImplementationOnce(async ({ oauthStart }) => {
await oauthStart(authorizationUrl);
return { availableTools: null };
})
.mockResolvedValue({ availableTools: null });
await loadAgentTools({
req,
res,
agent: { id: 'agent_123', tools: [mcpTool] },
definitionsOnly: true,
});
const authDeltaEvent = mockSendEvent.mock.calls
.map(([, event]) => event)
.find((event) => event.data?.delta?.auth === authorizationUrl);
expect(authDeltaEvent?.data.delta.expires_at).toBe(createdAt + PENDING_STALE_MS);
});
it('approval binding follows the user-tier authority instead of a same-name config candidate', async () => {
const { getToolApprovalBinding, buildMCPToolApprovalBinding, getToolApprovalAuthKind } =
jest.requireActual('@librechat/api');
const serverName = 'shared-server';
const name = `query${Constants.mcp_delimiter}${serverName}`;
const req = createMockReq([AgentCapabilities.tools]);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig([AgentCapabilities.tools]));
const candidate = {
type: 'streamable-http',
source: 'config',
url: 'https://config.example.com/mcp',
};
const firstAuthority = {
type: 'streamable-http',
source: 'user',
url: 'https://user.example.com/mcp',
dbId: 'server-id',
};
mockResolveConfigServers.mockResolvedValue({ [serverName]: candidate });
mockGetServerConfig.mockResolvedValue(firstAuthority);
mockGetMCPServerTools.mockResolvedValue({
[name]: { function: { name, parameters: { type: 'object' } } },
});
mockLoadToolDefinitions.mockImplementation(async (params, deps) => {
await deps.getOrFetchMCPServerTools(params.userId, serverName);
return {
toolDefinitions: [{ name, serverName, parameters: { type: 'object' } }],
toolRegistry: new Map(),
hasDeferredTools: false,
};
});
const first = await loadAgentTools({
req,
res: {},
agent: { id: 'agent-a', tools: [name] },
definitionsOnly: true,
});
expect(getToolApprovalAuthKind(first.toolDefinitions[0])).toBe('other');
expect(getToolApprovalBinding(first.toolDefinitions[0])).toBe(
buildMCPToolApprovalBinding(serverName, firstAuthority),
);
expect(getToolApprovalBinding(first.toolDefinitions[0])).not.toBe(
buildMCPToolApprovalBinding(serverName, candidate),
);
mockGetServerConfig.mockResolvedValue({
...firstAuthority,
url: 'https://new-user.example.com/mcp',
requiresOAuth: true,
});
const second = await loadAgentTools({
req,
res: {},
agent: { id: 'agent-a', tools: [name] },
definitionsOnly: true,
});
expect(getToolApprovalAuthKind(second.toolDefinitions[0])).toBe('oauth');
expect(getToolApprovalBinding(second.toolDefinitions[0])).not.toBe(
getToolApprovalBinding(first.toolDefinitions[0]),
);
});
it('resolves request-scoped MCP candidates through the effective registry', async () => {
const serverName = 'config-server';
const mcpTool = `search${Constants.mcp_delimiter}${serverName}`;
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockResolveConfigServers.mockResolvedValue({
[serverName]: {
type: 'streamable-http',
url: 'https://config.example.com/mcp',
customUserVars: {
TOKEN: { title: 'Token', description: 'Token' },
},
},
});
mockGetServerConfig.mockImplementation(
async (_name, _userId, candidates) => candidates[serverName],
);
mockGetUserMCPAuthMap.mockResolvedValue({
[`${Constants.mcp_prefix}${serverName}`]: { TOKEN: 'secret' },
});
mockGetMCPServerTools.mockResolvedValue({
[mcpTool]: {
function: {
name: mcpTool,
description: 'Config search',
parameters: {},
},
},
});
mockLoadToolDefinitions.mockImplementation(async (params, deps) => {
const serverTools = await deps.getOrFetchMCPServerTools(params.userId, serverName);
return {
toolDefinitions: serverTools ? Object.keys(serverTools) : [],
toolRegistry: new Map(),
hasDeferredTools: false,
};
});
const result = await loadAgentTools({
req,
res: {},
agent: { id: 'agent_123', tools: [mcpTool] },
definitionsOnly: true,
});
expect(result.toolDefinitions).toEqual([mcpTool]);
expect(mockGetServerConfig).toHaveBeenCalledWith(
serverName,
req.user.id,
expect.objectContaining({ [serverName]: expect.any(Object) }),
req.user.role,
{ idOnTheSource: req.user.idOnTheSource },
);
expect(mockGetMCPServerTools).toHaveBeenCalledWith(
req.user.id,
serverName,
expect.objectContaining({ url: 'https://config.example.com/mcp' }),
'standard',
);
});
});
describe('loadAgentTools (definitionsOnly=false) — action tool filtering', () => {
const actionToolName = `get_weather${actionDelimiter}api_example_com`;
const regularTool = 'calculator';
it('threads the owning job epoch into web-search attachment callbacks', async () => {
const capabilities = [AgentCapabilities.tools, AgentCapabilities.web_search];
const req = createMockReq(capabilities);
const res = {};
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await loadAgentTools({
req,
res,
streamId: 'conversation-1',
jobCreatedAt: 1234,
agent: { id: 'agent_123', tools: [Tools.web_search] },
definitionsOnly: false,
});
expect(createOnSearchResults).toHaveBeenCalledWith(res, 'conversation-1', 1234);
});
it('should not load action sets when actions capability is disabled', async () => {
const capabilities = [AgentCapabilities.tools, AgentCapabilities.web_search];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await loadAgentTools({
req,
res: {},
agent: { id: 'agent_123', tools: [regularTool, actionToolName] },
definitionsOnly: false,
});
expect(mockLoadActionSets).not.toHaveBeenCalled();
});
it('should load action sets when actions capability is enabled and action tools present', async () => {
const capabilities = [AgentCapabilities.tools, AgentCapabilities.actions];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await loadAgentTools({
req,
res: {},
agent: { id: 'agent_123', tools: [regularTool, actionToolName] },
definitionsOnly: false,
});
expect(mockLoadActionSets).toHaveBeenCalledWith({ agentId: 'agent_123' });
});
it('blocks persisted action metadata before generic tool initialization', async () => {
const capabilities = [AgentCapabilities.tools, AgentCapabilities.actions];
const req = createMockReq(capabilities);
req.config.filters = {
actionMetadata: {
pii: {
fields: ['raw_spec'],
starterPatterns: [],
customPatterns: [
{
id: 'private',
label: 'private value',
regex: 'PRIVATE-[A-Z]+',
},
],
},
},
};
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockLoadActionSets.mockResolvedValue([
{
action_id: 'action_private_before_generic',
metadata: {
domain: 'https://api.example.com',
raw_spec: '{"description":"PRIVATE-ACTION"}',
},
},
]);
await expect(
loadAgentTools({
req,
res: {},
agent: { id: 'agent_123', tools: [regularTool, actionToolName] },
definitionsOnly: false,
}),
).rejects.toMatchObject({
code: 'content_filter_block',
body: {
source: 'action_metadata',
field: 'raw_spec',
},
});
expect(mockLoadToolsUtil).not.toHaveBeenCalled();
expect(mockDomainParser).not.toHaveBeenCalled();
expect(mockCreateActionTool).not.toHaveBeenCalled();
});
});
describe('GitHub comparison loader policy', () => {
it.each([false, true])(
'threads explicit deployment opt-in into definition loading (%p)',
async (enabled) => {
const req = createMockReq([AgentCapabilities.tools]);
req.config.githubCompare = { enabled };
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig([AgentCapabilities.tools]));
await loadAgentTools({
req,
res: {},
agent: { id: 'reviewer', tools: ['github_compare'] },
});
expect(mockLoadToolDefinitions).toHaveBeenCalledWith(
expect.objectContaining({ tools: ['github_compare'], githubCompareEnabled: enabled }),
expect.any(Object),
);
},
);
it('passes the executing registry unchanged instead of manufacturing compare authority', async () => {
const req = createMockReq([AgentCapabilities.tools]);
req.config.githubCompare = { enabled: true };
const toolRegistry = new Map([['calculator', { name: 'calculator' }]]);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig([AgentCapabilities.tools]));
await loadToolsForExecution({
req,
res: {},
agent: { id: 'reviewer', tools: ['calculator'] },
toolNames: ['github_compare'],
toolRegistry,
actionsEnabled: false,
});
expect(mockLoadToolsUtil).toHaveBeenCalledWith(
expect.objectContaining({
tools: ['github_compare'],
options: expect.objectContaining({ toolRegistry }),
}),
);
expect(mockLoadToolsUtil.mock.calls[0][0].options.toolRegistry).toBe(toolRegistry);
expect(toolRegistry.has('github_compare')).toBe(false);
});
it('builds compare authority only from the legacy initialization selection', async () => {
const req = createMockReq([AgentCapabilities.tools]);
req.config.githubCompare = { enabled: true };
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig([AgentCapabilities.tools]));
await loadAgentTools({
req,
res: {},
agent: { id: 'reviewer', tools: ['github_compare'] },
definitionsOnly: false,
});
expect(mockLoadToolsUtil.mock.calls[0][0].options.toolRegistry.has('github_compare')).toBe(
true,
);
});
});
describe('loadToolsForExecution — action tool gating', () => {
it('should preserve the remote-agent permission boundary for deferred tool loading', async () => {
const capabilities = [AgentCapabilities.tools, AgentCapabilities.file_search];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await loadToolsForExecution({
req,
res: {},
agent: { id: 'agent_123', tools: [Tools.file_search] },
toolNames: [Tools.file_search],
agentResourceType: ResourceType.REMOTE_AGENT,
actionsEnabled: false,
});
expect(mockLoadToolsUtil).toHaveBeenCalledWith(
expect.objectContaining({
options: expect.objectContaining({
agentResourceType: ResourceType.REMOTE_AGENT,
}),
}),
);
});
it('threads the normalized MCP body through deferred tool loading', async () => {
const capabilities = [AgentCapabilities.tools, AgentCapabilities.web_search];
const req = createMockReq(capabilities);
const requestBody = {
messageId: 'response-1',
conversationId: 'conversation-1',
parentMessageId: 'parent-1',
};
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
const result = await loadToolsForExecution({
req,
res: {},
requestBody,
agent: { id: 'agent_123', tools: [Tools.web_search] },
toolNames: [Tools.web_search],
actionsEnabled: false,
});
expect(mockLoadToolsUtil).toHaveBeenCalledWith(
expect.objectContaining({
options: expect.objectContaining({ requestBody }),
}),
);
expect(result.configurable.requestBody).toBe(requestBody);
});
const actionToolName = `get_weather${actionDelimiter}api_example_com`;
const regularTool = Tools.web_search;
it('threads the owning job epoch into web-search attachment callbacks', async () => {
const capabilities = [AgentCapabilities.tools, AgentCapabilities.web_search];
const req = createMockReq(capabilities);
const res = {};
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await loadToolsForExecution({
req,
res,
streamId: 'conversation-1',
jobCreatedAt: 1234,
agent: { id: 'agent_123', tools: [Tools.web_search] },
toolNames: [Tools.web_search],
actionsEnabled: false,
});
expect(createOnSearchResults).toHaveBeenCalledWith(res, 'conversation-1', 1234);
});
it('does not load code execution tools that were not registered for the agent', async () => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.web_search,
AgentCapabilities.execute_code,
];
const req = createMockReq(capabilities);
const toolRegistry = new Map([[Tools.web_search, { name: Tools.web_search }]]);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
const result = await loadToolsForExecution({
req,
res: {},
agent: { id: 'agent_without_code', tools: [Tools.web_search] },
toolNames: [AgentConstants.BASH_TOOL, Tools.execute_code],
toolRegistry,
actionsEnabled: false,
});
expect(result.loadedTools.map((tool) => tool.name)).toEqual([]);
expect(mockLoadToolsUtil).not.toHaveBeenCalled();
});
it('keeps stateless and stateful agents on isolated execution profiles in one run', async () => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.execute_code,
AgentCapabilities.stateful_code_sessions,
];
const req = createMockReq(capabilities);
req.body = { conversationId: 'conversation-1' };
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
process.env.LIBRECHAT_CODE_BASEURL = 'http://code-default.test/v1';
process.env.LIBRECHAT_CODE_BASEURL_STATEFUL = 'http://code-stateful.test/v1';
try {
const stateless = await loadToolsForExecution({
req,
res: {},
agent: { id: 'stateless-agent', tools: [Tools.execute_code] },
toolNames: [],
});
const stateful = await loadToolsForExecution({
req,
res: {},
agent: {
id: 'stateful-agent',
tools: [Tools.execute_code],
stateful_code_sessions: true,
stateful_code_environment: 'agent-user',
},
toolNames: [],
});
expect(stateless.configurable.codeExecutionContext).toEqual({
baseUrl: 'http://code-default.test/v1',
codeSessionKey: 'execute_code',
executionProfile: 'default',
statefulSessions: false,
});
expect(stateful.configurable.codeExecutionContext).toEqual({
baseUrl: 'http://code-stateful.test/v1',
codeSessionKey: 'execute_code:stateful:v2:agent-user:7c684f0773d9642c122f67aa30e9e0f4',
executionProfile: 'stateful',
runtimeSessionHint: 'v2:agent-user:7c684f0773d9642c122f67aa30e9e0f4',
statefulSessions: true,
});
} finally {
delete process.env.LIBRECHAT_CODE_BASEURL;
delete process.env.LIBRECHAT_CODE_BASEURL_STATEFUL;
}
});
it.each(['read_file', 'create_file', 'edit_file'])(
'resolves stateful routing for standalone %s with the controller conversation ID',
async (toolName) => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.execute_code,
AgentCapabilities.stateful_code_sessions,
];
const req = createMockReq(capabilities);
req.body = {};
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
process.env.LIBRECHAT_CODE_BASEURL_STATEFUL = 'http://code-stateful.test/v1';
try {
const result = await loadToolsForExecution({
req,
res: {},
conversationId: 'resolved-api-conversation',
agent: {
id: 'stateful-agent',
tools: [Tools.execute_code],
stateful_code_sessions: true,
stateful_code_environment: 'conversation',
},
toolNames: [toolName],
actionsEnabled: false,
});
expect(result.configurable.codeExecutionContext).toEqual(
expect.objectContaining({
executionProfile: 'stateful',
runtimeSessionHint: `v2:conversation:${fingerprint('user_123', 'resolved-api-conversation')}`,
}),
);
} finally {
delete process.env.LIBRECHAT_CODE_BASEURL_STATEFUL;
}
},
);
it.each(['read_file', 'create_file', 'edit_file'])(
'keeps standalone %s on the selected attached worker',
async (toolName) => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.execute_code,
AgentCapabilities.stateful_code_sessions,
];
const req = createMockReq(capabilities);
req.config.endpoints.agents.statefulCodeSessions = {
environments: [
{
id: 'personal-machine',
type: 'attached',
baseURL: 'https://attached-code.test/v1',
workerId: 'worker-personal',
},
],
};
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
const result = await loadToolsForExecution({
req,
res: {},
conversationId: 'resolved-api-conversation',
agent: {
id: 'attached-agent',
tools: [Tools.execute_code],
stateful_code_sessions: true,
code_environment_id: 'personal-machine',
},
toolNames: [toolName],
actionsEnabled: false,
});
expect(result.configurable.codeExecutionContext).toEqual(
expect.objectContaining({
baseUrl: 'https://attached-code.test/v1',
executionProfile: 'stateful',
environmentType: 'attached',
environmentId: 'personal-machine',
bridgeWorkerId: 'worker-personal',
}),
);
},
);
it('preserves attached routing when workspace search is the only requested tool', async () => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.execute_code,
AgentCapabilities.stateful_code_sessions,
];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
process.env.LIBRECHAT_CODE_BASEURL_STATEFUL = 'http://code-stateful.test/v1';
try {
const result = await loadToolsForExecution({
req,
res: {},
agent: {
id: 'stateful-agent',
tools: [Tools.execute_code],
stateful_code_sessions: true,
stateful_code_environment: 'agent-user',
},
toolNames: ['search_workspace'],
actionsEnabled: false,
});
expect(result.configurable.codeExecutionContext).toEqual(
expect.objectContaining({
executionProfile: 'stateful',
runtimeSessionHint: `v2:agent-user:${fingerprint('user_123', 'stateful-agent')}`,
}),
);
} finally {
delete process.env.LIBRECHAT_CODE_BASEURL_STATEFUL;
}
});
it('preserves attached routing when workspace listing is the only requested tool', async () => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.execute_code,
AgentCapabilities.stateful_code_sessions,
];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
process.env.LIBRECHAT_CODE_BASEURL_STATEFUL = 'http://code-stateful.test/v1';
try {
const result = await loadToolsForExecution({
req,
res: {},
agent: {
id: 'stateful-agent',
tools: [Tools.execute_code],
stateful_code_sessions: true,
stateful_code_environment: 'agent-user',
},
toolNames: ['list_workspace_files'],
actionsEnabled: false,
});
expect(result.configurable.codeExecutionContext).toEqual(
expect.objectContaining({
executionProfile: 'stateful',
runtimeSessionHint: `v2:agent-user:${fingerprint('user_123', 'stateful-agent')}`,
}),
);
} finally {
delete process.env.LIBRECHAT_CODE_BASEURL_STATEFUL;
}
});
it('loads bash execution through the attached worker transport', async () => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.execute_code,
AgentCapabilities.stateful_code_sessions,
];
const req = createMockReq(capabilities);
req.config.endpoints[EModelEndpoint.agents].codeApiMaxRetryWaitMs = 0;
req.body = {
codeWorkspaces: [{ environmentId: 'personal-machine', workspaceId: 'project-a' }],
};
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
req.config.endpoints[EModelEndpoint.agents].statefulCodeSessions = {
environments: [
attachedEnvironment({
configSchema: {
limits: {
maxCommandTimeoutMs: 80_000,
defaultCommandTimeoutMs: 60_000,
maxQueueWaitMs: 0,
maxRequestTimeoutMs: 90_000,
maxRunTimeoutMs: 180_000,
minCommandAdmissionMs: 15_000,
},
admission: {
queueWaitMs: 60_000,
initialDelayMs: 1_000,
maxDelayMs: 30_000,
multiplier: 2,
jitterRatio: 0.2,
},
},
}),
],
};
const toolRegistry = new Map([
[AgentConstants.BASH_TOOL, { name: AgentConstants.BASH_TOOL }],
]);
const result = await loadToolsForExecution({
req,
res: {},
agent: {
id: 'attached-agent',
tools: [Tools.execute_code],
stateful_code_sessions: true,
stateful_code_environment: 'agent-user',
code_environment_id: 'personal-machine',
git_identity: { name: 'LibreChat Agent', email: 'agent@example.com' },
},
toolNames: [AgentConstants.BASH_TOOL],
toolRegistry,
actionsEnabled: false,
});
expect(mockCreateAttachedWorkspaceBashTool).toHaveBeenCalledWith({
authHeaders: expect.any(Function),
baseUrl: 'http://attached-code.test/v1',
workspaceId: 'project-a',
onLaneGit: mockLaneGitRecorder,
gitIdentity: { name: 'LibreChat Agent', email: 'agent@example.com' },
maxTimeoutMs: 65_000,
defaultTimeoutMs: 60_000,
maxQueueWaitMs: 0,
codeApiMaxRetryWaitMs: 0,
maxRequestTimeoutMs: 90_000,
maxRunTimeoutMs: 180_000,
admission: {
queueWaitMs: 60_000,
initialDelayMs: 1_000,
maxDelayMs: 30_000,
multiplier: 2,
jitterRatio: 0.2,
},
minCommandAdmissionMs: 15_000,
});
expect(mockResolveCodeExecutionWorkspaceContext).toHaveBeenCalledWith(
expect.objectContaining({ requestedSelections: req.body.codeWorkspaces }),
);
expect(result.loadedTools).toContainEqual({ name: AgentConstants.BASH_TOOL });
});
it('records the lane for the requesting user and the resolved conversation', async () => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.execute_code,
AgentCapabilities.stateful_code_sessions,
];
const req = createMockReq(capabilities);
req.config.endpoints[EModelEndpoint.agents].pullRequests = { allowAllRepositories: true };
req.body = {
conversationId: 'body-convo',
codeWorkspaces: [{ environmentId: 'personal-machine', workspaceId: 'project-a' }],
};
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
req.config.endpoints[EModelEndpoint.agents].statefulCodeSessions = {
environments: [attachedEnvironment()],
};
mockCreateLaneGitRecorder.mockClear();
await loadToolsForExecution({
req,
res: {},
agent: {
id: 'attached-agent',
tools: [Tools.execute_code],
stateful_code_sessions: true,
stateful_code_environment: 'agent-user',
code_environment_id: 'personal-machine',
},
conversationId: 'resolved-convo',
toolNames: [AgentConstants.BASH_TOOL],
toolRegistry: new Map([[AgentConstants.BASH_TOOL, { name: AgentConstants.BASH_TOOL }]]),
actionsEnabled: false,
});
expect(mockCreateLaneGitRecorder).toHaveBeenCalledWith(
expect.objectContaining({
enabled: true,
user: req.user.id,
conversationId: 'resolved-convo',
workspace: { environmentId: 'personal-machine', workspaceId: 'project-a' },
getConvoLaneContext: expect.any(Function),
reserveConvoLaneGitSeq: expect.any(Function),
setConvoLaneGit: expect.any(Function),
}),
);
const { setConvoLaneGit } = mockCreateLaneGitRecorder.mock.calls[0][0];
const input = { user: 'u', conversationId: 'c', laneGit: { branch: 'main', head: null } };
await setConvoLaneGit(input);
expect(mockSetConvoLaneGit).toHaveBeenCalledWith(input);
});
it.each([
['a moved conversation', 3, 3],
['a conversation never moved', 0, 0],
['a conversation whose admitted read carried no epoch', undefined, undefined],
])(
'fences the lane report by the epoch of the admitted decision for %s',
async (_label, admitted, expected) => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.execute_code,
AgentCapabilities.stateful_code_sessions,
];
const req = createMockReq(capabilities);
req.config.endpoints[EModelEndpoint.agents].pullRequests = { allowAllRepositories: true };
req.resolvedConversation = {
conversationId: 'resolved-convo',
codeWorkspaces: [{ environmentId: 'personal-machine', workspaceId: 'project-a' }],
...(admitted === undefined ? {} : { codeAttachmentEpoch: admitted }),
};
req.body = {
conversationId: 'resolved-convo',
codeWorkspaces: [{ environmentId: 'personal-machine', workspaceId: 'project-a' }],
};
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
req.config.endpoints[EModelEndpoint.agents].statefulCodeSessions = {
environments: [attachedEnvironment()],
};
mockCreateLaneGitRecorder.mockClear();
await loadToolsForExecution({
req,
res: {},
agent: {
id: 'attached-agent',
tools: [Tools.execute_code],
stateful_code_sessions: true,
stateful_code_environment: 'agent-user',
code_environment_id: 'personal-machine',
},
conversationId: 'resolved-convo',
toolNames: [AgentConstants.BASH_TOOL],
toolRegistry: new Map([[AgentConstants.BASH_TOOL, { name: AgentConstants.BASH_TOOL }]]),
actionsEnabled: false,
});
expect(mockCreateLaneGitRecorder.mock.calls[0][0].admittedEpoch).toBe(expected);
},
);
it.each([
['unset', undefined],
['disabled', { enabled: false }],
])('does not enable lane recording when pull requests are %s', async (_label, setting) => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.execute_code,
AgentCapabilities.stateful_code_sessions,
];
const req = createMockReq(capabilities);
if (setting) req.config.endpoints[EModelEndpoint.agents].pullRequests = setting;
req.body = {
codeWorkspaces: [{ environmentId: 'personal-machine', workspaceId: 'project-a' }],
};
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
req.config.endpoints[EModelEndpoint.agents].statefulCodeSessions = {
environments: [attachedEnvironment()],
};
mockCreateLaneGitRecorder.mockClear();
await loadToolsForExecution({
req,
res: {},
agent: {
id: 'attached-agent',
tools: [Tools.execute_code],
stateful_code_sessions: true,
stateful_code_environment: 'agent-user',
code_environment_id: 'personal-machine',
},
conversationId: 'resolved-convo',
toolNames: [AgentConstants.BASH_TOOL],
toolRegistry: new Map([[AgentConstants.BASH_TOOL, { name: AgentConstants.BASH_TOOL }]]),
actionsEnabled: false,
});
expect(mockCreateLaneGitRecorder).toHaveBeenCalledWith(
expect.objectContaining({ enabled: false }),
);
});
it('passes negotiated lane and native sandbox capabilities to the attached bash tool', async () => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.execute_code,
AgentCapabilities.stateful_code_sessions,
];
const req = createMockReq(capabilities);
req.body = {
codeWorkspaces: [{ environmentId: 'personal-machine', workspaceId: 'project-a' }],
};
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
req.config.endpoints[EModelEndpoint.agents].statefulCodeSessions = {
environments: [attachedEnvironment()],
};
mockResolveCodeExecutionWorkspaceContext.mockImplementationOnce(async ({ context }) => ({
...context,
codeWorkspace: {
environmentId: 'personal-machine',
workspaceId: 'project-a',
operations: attachedWorkspaceOperations,
linkedWorktrees: true,
nativeSandbox: true,
},
}));
await loadToolsForExecution({
req,
res: {},
agent: {
id: 'attached-agent',
tools: [Tools.execute_code],
stateful_code_sessions: true,
stateful_code_environment: 'agent-user',
code_environment_id: 'personal-machine',
},
toolNames: [AgentConstants.BASH_TOOL],
toolRegistry: new Map([[AgentConstants.BASH_TOOL, { name: AgentConstants.BASH_TOOL }]]),
actionsEnabled: false,
});
expect(mockCreateAttachedWorkspaceBashTool).toHaveBeenLastCalledWith(
expect.objectContaining({ linkedWorktrees: true, nativeSandbox: true }),
);
});
describe('in a conversation that chose no workspace', () => {
const SKYNET = 'code-yuwoQAAPhY1WMaDD6oIk';
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.skills,
AgentCapabilities.execute_code,
AgentCapabilities.stateful_code_sessions,
];
const terra = {
id: 'agent_nw3URLZi7gDH4kDgHGsWF',
tools: [Tools.execute_code],
stateful_code_sessions: true,
code_environment_id: SKYNET,
};
const createDecisionReq = (codeEnvironmentMode) => {
const req = createMockReq(capabilities);
req.config.endpoints.agents.statefulCodeSessions = {
environments: [attachedEnvironment({ id: SKYNET, name: 'Skynet' })],
};
req.body = { codeEnvironmentMode };
req.resolvedConversation = { conversationId: 'convo-nows', codeEnvironmentMode };
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockResolveCodeExecutionWorkspaceContext.mockImplementationOnce(
jest.requireActual('@librechat/api').resolveCodeExecutionWorkspaceContext,
);
return req;
};
const loadFor = (req, toolNames, toolRegistry) =>
loadToolsForExecution({
req,
res: {},
conversationId: 'convo-nows',
requestBody: req.body,
agent: terra,
toolNames,
toolRegistry,
actionsEnabled: false,
});
it('loads a skill on the managed route instead of requiring an attached workspace', async () => {
const result = await loadFor(createDecisionReq('without_attached'), [
AgentConstants.SKILL_TOOL,
]);
expect(result.configurable.codeExecutionContext).toEqual(
expect.objectContaining({ executionProfile: 'default', statefulSessions: false }),
);
expect(result.configurable.codeExecutionContext.environmentType).toBeUndefined();
expect(mockResolveCodeExecutionWorkspaceContext).toHaveBeenCalledTimes(1);
});
it('offers none of the attached machine tools', async () => {
const toolRegistry = new Map(
[AgentConstants.BASH_TOOL, Tools.execute_code].map((name) => [name, { name }]),
);
const result = await loadFor(
createDecisionReq('without_attached'),
[AgentConstants.BASH_TOOL, Tools.execute_code],
toolRegistry,
);
expect(result.loadedTools).toEqual([]);
expect(mockCreateAttachedWorkspaceBashTool).not.toHaveBeenCalled();
expect(mockLoadToolsUtil).not.toHaveBeenCalled();
});
it('keeps the initializer opt-out for the definitions of a partial agent record', async () => {
const req = createDecisionReq('without_attached');
req.config.endpoints.agents.capabilities.push(AgentCapabilities.programmatic_tools);
mockGetEndpointsConfig.mockResolvedValue(
createEndpointsConfig(req.config.endpoints.agents.capabilities),
);
const loadDefinitions = (attachedEnvironmentOptOut) =>
loadAgentTools({
req,
res: {},
agent: { id: terra.id, tools: [Tools.execute_code, 'calculator'] },
definitionsOnly: true,
codeExecutionContext: {
baseUrl: 'https://api.librechat.ai/v1',
codeSessionKey: 'execute_code',
executionProfile: 'default',
statefulSessions: false,
},
attachedEnvironmentOptOut,
});
await loadDefinitions(true);
const optedOut = mockLoadToolDefinitions.mock.calls.at(-1)[0];
await loadDefinitions(undefined);
const kept = mockLoadToolDefinitions.mock.calls.at(-1)[0];
expect(optedOut.codeExecutionEnabled).toBe(false);
expect(kept.codeExecutionEnabled).toBe(true);
});
it('still requires a workspace selection when the conversation runs on attached machines', async () => {
await expect(
loadFor(createDecisionReq('attached'), [AgentConstants.SKILL_TOOL]),
).rejects.toMatchObject({
name: 'CodeWorkspaceSelectionError',
reason: 'required',
code: ErrorTypes.CODE_WORKSPACE_UNAVAILABLE,
});
});
});
it('resolves stateful routing when handle_skill is the only requested tool', async () => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.execute_code,
AgentCapabilities.stateful_code_sessions,
];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
process.env.LIBRECHAT_CODE_BASEURL_STATEFUL = 'http://code-stateful.test/v1';
try {
const result = await loadToolsForExecution({
req,
res: {},
agent: {
id: 'stateful-agent',
tools: [Tools.execute_code],
stateful_code_sessions: true,
stateful_code_environment: 'agent-user',
},
toolNames: [AgentConstants.SKILL_TOOL],
actionsEnabled: false,
});
expect(result.configurable.codeExecutionContext).toEqual(
expect.objectContaining({
executionProfile: 'stateful',
runtimeSessionHint: `v2:agent-user:${fingerprint('user_123', 'stateful-agent')}`,
}),
);
} finally {
delete process.env.LIBRECHAT_CODE_BASEURL_STATEFUL;
}
});
it('loads bash PTC under the legacy programmatic tool name when code capabilities are enabled', async () => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.programmatic_tools,
AgentCapabilities.execute_code,
];
const req = createMockReq(capabilities);
const toolRegistry = new Map([['custom_tool', { name: 'custom_tool' }]]);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
const result = await loadToolsForExecution({
req,
res: {},
agent: { id: 'agent_ptc', tools: [Tools.execute_code] },
toolNames: [Constants.PROGRAMMATIC_TOOL_CALLING],
toolRegistry,
actionsEnabled: false,
});
expect(result.loadedTools.map((tool) => tool.name)).toEqual([
Constants.PROGRAMMATIC_TOOL_CALLING,
]);
expect(result.configurable.toolRegistry).toBe(toolRegistry);
expect(result.configurable.ptcToolMap.size).toBe(0);
});
it('passes run-scoped MCP tool definitions into PTC execution loading', async () => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.programmatic_tools,
AgentCapabilities.execute_code,
];
const req = createMockReq(capabilities);
const serverName = 'ClickHouse';
const mcpTool = `list_tables${Constants.mcp_delimiter}${serverName}`;
const mcpAvailableTools = {
[serverName]: {
[mcpTool]: {
function: {
name: mcpTool,
description: 'List tables',
parameters: { type: 'object', properties: {} },
},
},
},
};
const toolRegistry = new Map([
[mcpTool, { name: mcpTool, allowed_callers: ['code_execution'] }],
]);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await loadToolsForExecution({
req,
res: {},
agent: { id: 'agent_ptc', tools: [Tools.execute_code] },
toolNames: [Constants.BASH_PROGRAMMATIC_TOOL_CALLING],
toolRegistry,
mcpAvailableTools,
actionsEnabled: false,
});
expect(mockLoadToolsUtil).toHaveBeenCalledWith(
expect.objectContaining({
tools: [mcpTool],
options: expect.objectContaining({
mcpAvailableTools,
}),
}),
);
});
it('loads only code_execution tools into the PTC execution map', async () => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.programmatic_tools,
AgentCapabilities.execute_code,
];
const req = createMockReq(capabilities);
const programmaticTool = {
name: 'programmatic_tool',
invoke: jest.fn(),
};
const toolRegistry = new Map([
[
programmaticTool.name,
{ name: programmaticTool.name, allowed_callers: ['code_execution'] },
],
['direct_tool', { name: 'direct_tool', allowed_callers: ['direct'] }],
]);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockLoadToolsUtil.mockResolvedValue({
loadedTools: [programmaticTool],
toolContextMap: {},
});
const result = await loadToolsForExecution({
req,
res: {},
agent: { id: 'agent_ptc', tools: [Tools.execute_code] },
toolNames: [Constants.BASH_PROGRAMMATIC_TOOL_CALLING],
toolRegistry,
actionsEnabled: false,
});
expect(mockLoadToolsUtil).toHaveBeenCalledWith(
expect.objectContaining({ tools: ['programmatic_tool'] }),
);
expect([...result.configurable.ptcToolMap.keys()]).toEqual(['programmatic_tool']);
});
it('intersects PTC loading with the SDK live caller projection', async () => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.programmatic_tools,
AgentCapabilities.execute_code,
];
const req = createMockReq(capabilities);
const activeTool = { name: 'active_programmatic_tool', invoke: jest.fn() };
const deferredTool = { name: 'deferred_programmatic_tool', invoke: jest.fn() };
const toolRegistry = new Map([
[activeTool.name, { name: activeTool.name, allowed_callers: ['code_execution'] }],
[
deferredTool.name,
{
name: deferredTool.name,
allowed_callers: ['code_execution'],
defer_loading: true,
},
],
]);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockLoadToolsUtil.mockResolvedValue({
loadedTools: [activeTool],
toolContextMap: {},
});
const result = await loadToolsForExecution({
req,
res: {},
agent: { id: 'agent_ptc', tools: [Tools.execute_code] },
toolNames: [Constants.BASH_PROGRAMMATIC_TOOL_CALLING],
toolRegistry,
callerCapabilityProjection: {
version: 1,
directToolNames: [],
codeExecutionToolNames: [activeTool.name],
directOnlyToolNames: [],
codeExecutionOnlyToolNames: [activeTool.name],
},
actionsEnabled: false,
});
expect(mockLoadToolsUtil).toHaveBeenCalledWith(
expect.objectContaining({ tools: [activeTool.name] }),
);
expect([...result.configurable.ptcToolMap.keys()]).toEqual([activeTool.name]);
});
it('treats an empty versioned caller projection as authoritative', async () => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.programmatic_tools,
AgentCapabilities.execute_code,
];
const req = createMockReq(capabilities);
const toolRegistry = new Map([
[
'deferred_programmatic_tool',
{ name: 'deferred_programmatic_tool', allowed_callers: ['code_execution'] },
],
]);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
const result = await loadToolsForExecution({
req,
res: {},
agent: { id: 'agent_ptc', tools: [Tools.execute_code] },
toolNames: [Constants.BASH_PROGRAMMATIC_TOOL_CALLING],
toolRegistry,
callerCapabilityProjection: {
version: 1,
directToolNames: [],
codeExecutionToolNames: [],
directOnlyToolNames: [],
codeExecutionOnlyToolNames: [],
},
actionsEnabled: false,
});
expect(mockLoadToolsUtil).not.toHaveBeenCalled();
expect(result.configurable.ptcToolMap).toEqual(new Map());
});
it('falls back to registry projection for unknown snapshot versions', async () => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.programmatic_tools,
AgentCapabilities.execute_code,
];
const req = createMockReq(capabilities);
const programmaticTool = { name: 'programmatic_tool', invoke: jest.fn() };
const toolRegistry = new Map([
[
programmaticTool.name,
{ name: programmaticTool.name, allowed_callers: ['code_execution'] },
],
]);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockLoadToolsUtil.mockResolvedValue({
loadedTools: [programmaticTool],
toolContextMap: {},
});
await loadToolsForExecution({
req,
res: {},
agent: { id: 'agent_ptc', tools: [Tools.execute_code] },
toolNames: [Constants.BASH_PROGRAMMATIC_TOOL_CALLING],
toolRegistry,
callerCapabilityProjection: {
version: 2,
directToolNames: [],
codeExecutionToolNames: [],
directOnlyToolNames: [],
codeExecutionOnlyToolNames: [],
},
actionsEnabled: false,
});
expect(mockLoadToolsUtil).toHaveBeenCalledWith(
expect.objectContaining({ tools: [programmaticTool.name] }),
);
});
it('does not lazily load PTC for an attached worker without confirmed stateful support', async () => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.programmatic_tools,
AgentCapabilities.execute_code,
AgentCapabilities.stateful_code_sessions,
];
const req = createMockReq(capabilities);
req.config.endpoints.agents.statefulCodeSessions = {
environments: [
{
id: 'personal',
name: 'Personal',
type: 'attached',
owner: 'deployment',
baseURL: 'https://attached.example',
workerId: 'worker',
},
],
};
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
const result = await loadToolsForExecution({
req,
res: {},
agent: {
id: 'agent_ptc',
tools: [Tools.execute_code],
stateful_code_sessions: true,
code_environment_id: 'personal',
},
toolNames: [Constants.BASH_PROGRAMMATIC_TOOL_CALLING],
toolRegistry: new Map(),
actionsEnabled: false,
});
expect(result.loadedTools.map((tool) => tool.name)).not.toContain(
Constants.BASH_PROGRAMMATIC_TOOL_CALLING,
);
});
it.each([
{ statefulWorkspace: false, runtimes: ['bash'], supported: false },
{ statefulWorkspace: true, runtimes: ['py'], supported: false },
{ statefulWorkspace: true, runtimes: ['bash'], supported: false },
])(
'suppresses workspace-unaware attached PTC: stateful=$statefulWorkspace runtimes=$runtimes',
async ({ statefulWorkspace, runtimes, supported }) => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.programmatic_tools,
AgentCapabilities.execute_code,
AgentCapabilities.stateful_code_sessions,
];
const req = createMockReq(capabilities);
const environment = {
id: 'personal',
name: 'Personal',
type: 'attached',
owner: 'deployment',
baseURL: 'https://attached.example',
workerId: `worker-${statefulWorkspace}-${runtimes[0]}`,
pairing: {
workerId: `worker-${statefulWorkspace}-${runtimes[0]}`,
tokenEnv: 'TEST_PTC_DEPLOYMENT_TOKEN',
},
};
req.config.endpoints.agents.statefulCodeSessions = { environments: [environment] };
mockGetAppConfig.mockResolvedValueOnce({
endpoints: { agents: { statefulCodeSessions: { environments: [environment] } } },
});
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
process.env.TEST_PTC_DEPLOYMENT_TOKEN = `deployment-token-${statefulWorkspace}`;
const fetchSpy = jest.spyOn(globalThis, 'fetch').mockResolvedValue(
new Response(
JSON.stringify({
protocolVersion: 1,
workerId: environment.workerId,
online: true,
ready: true,
leaseExpiresInMs: 45_000,
capabilities: { statefulWorkspace, sandboxProfile: 'native-srt', runtimes },
}),
),
);
try {
const result = await loadToolsForExecution({
req,
res: {},
agent: {
id: 'agent_ptc',
tools: [Tools.execute_code],
stateful_code_sessions: true,
code_environment_id: 'personal',
},
toolNames: [Constants.BASH_PROGRAMMATIC_TOOL_CALLING],
toolRegistry: new Map(),
actionsEnabled: false,
});
expect(
result.loadedTools.some(
(tool) => tool.name === Constants.BASH_PROGRAMMATIC_TOOL_CALLING,
),
).toBe(supported);
expect(mockGetAppConfig).toHaveBeenCalledTimes(1);
expect(fetchSpy).toHaveBeenCalledTimes(1);
} finally {
fetchSpy.mockRestore();
delete process.env.TEST_PTC_DEPLOYMENT_TOKEN;
}
},
);
it('does not load PTC when programmatic tools capability is disabled', async () => {
const capabilities = [AgentCapabilities.tools, AgentCapabilities.execute_code];
const req = createMockReq(capabilities);
const toolRegistry = new Map([['custom_tool', { name: 'custom_tool' }]]);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
const result = await loadToolsForExecution({
req,
res: {},
agent: { id: 'agent_ptc', tools: [Tools.execute_code] },
toolNames: [Constants.BASH_PROGRAMMATIC_TOOL_CALLING],
toolRegistry,
actionsEnabled: false,
});
expect(result.loadedTools.map((tool) => tool.name)).toEqual([]);
expect(result.configurable.toolRegistry).toBeUndefined();
expect(result.configurable.ptcToolMap).toBeUndefined();
});
it('does not load PTC when agent did not request execute_code', async () => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.programmatic_tools,
AgentCapabilities.execute_code,
];
const req = createMockReq(capabilities);
const toolRegistry = new Map([['custom_tool', { name: 'custom_tool' }]]);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
const result = await loadToolsForExecution({
req,
res: {},
agent: { id: 'agent_ptc', tools: [] },
toolNames: [Constants.BASH_PROGRAMMATIC_TOOL_CALLING],
toolRegistry,
actionsEnabled: false,
});
expect(result.loadedTools.map((tool) => tool.name)).toEqual([]);
expect(result.configurable.toolRegistry).toBeUndefined();
expect(result.configurable.ptcToolMap).toBeUndefined();
});
it('should skip action tool loading when actionsEnabled=false', async () => {
const req = createMockReq([]);
req.config = {};
const result = await loadToolsForExecution({
req,
res: {},
agent: { id: 'agent_123' },
toolNames: [regularTool, actionToolName],
actionsEnabled: false,
});
expect(mockLoadActionSets).not.toHaveBeenCalled();
expect(result.loadedTools).toBeDefined();
});
it('should load action tools when actionsEnabled=true', async () => {
const req = createMockReq([AgentCapabilities.actions]);
req.config = {};
await loadToolsForExecution({
req,
res: {},
agent: { id: 'agent_123' },
toolNames: [actionToolName],
actionsEnabled: true,
});
expect(mockLoadActionSets).toHaveBeenCalledWith({ agentId: 'agent_123' });
});
it('blocks decrypted persisted action secrets before execution-time domain work', async () => {
const req = createMockReq([AgentCapabilities.actions]);
req.config.filters = {
actionMetadata: {
pii: {
fields: ['oauth_client_secret'],
starterPatterns: [],
customPatterns: [
{
id: 'private',
label: 'private value',
regex: 'PRIVATE-[A-Z]+',
},
],
},
},
};
const metadata = {
domain: 'https://api.example.com',
raw_spec: '{}',
oauth_client_secret: 'encrypted-value',
};
mockLoadActionSets.mockResolvedValue([
{
action_id: 'action_private_auth',
metadata,
},
]);
mockDecryptMetadata.mockResolvedValue({
...metadata,
oauth_client_secret: 'PRIVATE-OAUTH',
});
await expect(
loadToolsForExecution({
req,
res: {},
agent: { id: 'agent_123' },
toolNames: [actionToolName],
actionsEnabled: true,
}),
).rejects.toMatchObject({
code: 'content_filter_block',
body: {
source: 'action_metadata',
field: 'oauth_client_secret',
},
});
expect(mockDecryptMetadata).toHaveBeenCalledWith(metadata);
expect(mockDomainParser).not.toHaveBeenCalled();
expect(mockCreateActionTool).not.toHaveBeenCalled();
});
it('should resolve actionsEnabled from capabilities when not explicitly provided', async () => {
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await loadToolsForExecution({
req,
res: {},
agent: { id: 'agent_123' },
toolNames: [actionToolName],
});
expect(mockGetEndpointsConfig).toHaveBeenCalled();
expect(mockLoadActionSets).not.toHaveBeenCalled();
});
it('should not call loadActionSets when there are no action tools', async () => {
const req = createMockReq([AgentCapabilities.actions]);
req.config = {};
await loadToolsForExecution({
req,
res: {},
agent: { id: 'agent_123' },
toolNames: [regularTool],
actionsEnabled: true,
});
expect(mockLoadActionSets).not.toHaveBeenCalled();
});
});
describe('checkCapability logic', () => {
const createCheckCapability = (enabledCapabilities, logger = { warn: jest.fn() }) => {
return (capability) => {
const enabled = enabledCapabilities.has(capability);
if (!enabled) {
const isToolCapability = [
AgentCapabilities.file_search,
AgentCapabilities.execute_code,
AgentCapabilities.web_search,
].includes(capability);
const suffix = isToolCapability ? ' despite configured tool.' : '.';
logger.warn(`Capability "${capability}" disabled${suffix}`);
}
return enabled;
};
};
it('should return true when capability is enabled', () => {
const enabledCapabilities = new Set([AgentCapabilities.deferred_tools]);
const checkCapability = createCheckCapability(enabledCapabilities);
expect(checkCapability(AgentCapabilities.deferred_tools)).toBe(true);
});
it('should return false when capability is not enabled', () => {
const enabledCapabilities = new Set([]);
const checkCapability = createCheckCapability(enabledCapabilities);
expect(checkCapability(AgentCapabilities.deferred_tools)).toBe(false);
});
it('should log warning with "despite configured tool" for tool capabilities', () => {
const logger = { warn: jest.fn() };
const enabledCapabilities = new Set([]);
const checkCapability = createCheckCapability(enabledCapabilities, logger);
checkCapability(AgentCapabilities.file_search);
expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('despite configured tool'));
logger.warn.mockClear();
checkCapability(AgentCapabilities.execute_code);
expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('despite configured tool'));
logger.warn.mockClear();
checkCapability(AgentCapabilities.web_search);
expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('despite configured tool'));
});
it('should log warning without "despite configured tool" for non-tool capabilities', () => {
const logger = { warn: jest.fn() };
const enabledCapabilities = new Set([]);
const checkCapability = createCheckCapability(enabledCapabilities, logger);
checkCapability(AgentCapabilities.deferred_tools);
expect(logger.warn).toHaveBeenCalledWith(
expect.stringContaining('Capability "deferred_tools" disabled.'),
);
expect(logger.warn).not.toHaveBeenCalledWith(
expect.stringContaining('despite configured tool'),
);
logger.warn.mockClear();
checkCapability(AgentCapabilities.tools);
expect(logger.warn).toHaveBeenCalledWith(
expect.stringContaining('Capability "tools" disabled.'),
);
expect(logger.warn).not.toHaveBeenCalledWith(
expect.stringContaining('despite configured tool'),
);
logger.warn.mockClear();
checkCapability(AgentCapabilities.actions);
expect(logger.warn).toHaveBeenCalledWith(
expect.stringContaining('Capability "actions" disabled.'),
);
});
it('should not log warning when capability is enabled', () => {
const logger = { warn: jest.fn() };
const enabledCapabilities = new Set([
AgentCapabilities.deferred_tools,
AgentCapabilities.file_search,
]);
const checkCapability = createCheckCapability(enabledCapabilities, logger);
checkCapability(AgentCapabilities.deferred_tools);
checkCapability(AgentCapabilities.file_search);
expect(logger.warn).not.toHaveBeenCalled();
});
});
describe('defaultAgentCapabilities', () => {
it('should include deferred_tools capability by default', () => {
expect(defaultAgentCapabilities).toContain(AgentCapabilities.deferred_tools);
});
it('should include all expected default capabilities', () => {
expect(defaultAgentCapabilities).toContain(AgentCapabilities.execute_code);
expect(defaultAgentCapabilities).toContain(AgentCapabilities.file_search);
expect(defaultAgentCapabilities).toContain(AgentCapabilities.web_search);
expect(defaultAgentCapabilities).toContain(AgentCapabilities.artifacts);
expect(defaultAgentCapabilities).toContain(AgentCapabilities.actions);
expect(defaultAgentCapabilities).toContain(AgentCapabilities.context);
expect(defaultAgentCapabilities).toContain(AgentCapabilities.ask_user_question);
expect(defaultAgentCapabilities).toContain(AgentCapabilities.tools);
expect(defaultAgentCapabilities).not.toContain(AgentCapabilities.chain);
expect(defaultAgentCapabilities).toContain(AgentCapabilities.ocr);
});
});
describe('userMCPAuthMap gating', () => {
const shouldFetchMCPAuth = (tools) =>
tools?.some((t) => t.includes(Constants.mcp_delimiter)) ?? false;
it('should return true when agent has MCP tools', () => {
const tools = ['web_search', `search${Constants.mcp_delimiter}my-mcp-server`, 'calculator'];
expect(shouldFetchMCPAuth(tools)).toBe(true);
});
it('should return false when agent has no MCP tools', () => {
const tools = ['web_search', 'calculator', 'code_interpreter'];
expect(shouldFetchMCPAuth(tools)).toBe(false);
});
it('should return false when tools is empty', () => {
expect(shouldFetchMCPAuth([])).toBe(false);
});
it('should return false when tools is undefined', () => {
expect(shouldFetchMCPAuth(undefined)).toBe(false);
});
it('should return false when tools is null', () => {
expect(shouldFetchMCPAuth(null)).toBe(false);
});
it('should detect MCP tools with different server names', () => {
const tools = [
`listFiles${Constants.mcp_delimiter}file-server`,
`query${Constants.mcp_delimiter}db-server`,
];
expect(shouldFetchMCPAuth(tools)).toBe(true);
});
it('should return true even when only one tool is MCP', () => {
const tools = [
'web_search',
'calculator',
'code_interpreter',
`echo${Constants.mcp_delimiter}test-server`,
];
expect(shouldFetchMCPAuth(tools)).toBe(true);
});
});
describe('deferredToolsEnabled integration', () => {
it('should correctly determine deferredToolsEnabled from capabilities set', () => {
const createCheckCapability = (enabledCapabilities) => {
return (capability) => enabledCapabilities.has(capability);
};
const withDeferred = new Set([AgentCapabilities.deferred_tools, AgentCapabilities.tools]);
const checkWithDeferred = createCheckCapability(withDeferred);
expect(checkWithDeferred(AgentCapabilities.deferred_tools)).toBe(true);
const withoutDeferred = new Set([AgentCapabilities.tools, AgentCapabilities.actions]);
const checkWithoutDeferred = createCheckCapability(withoutDeferred);
expect(checkWithoutDeferred(AgentCapabilities.deferred_tools)).toBe(false);
});
it('should use defaultAgentCapabilities when no capabilities configured', () => {
const endpointsConfig = {};
const enabledCapabilities = new Set(
endpointsConfig?.capabilities ?? defaultAgentCapabilities,
);
expect(enabledCapabilities.has(AgentCapabilities.deferred_tools)).toBe(true);
});
});
describe('multi-action domain collision regression', () => {
// Two distinct OpenAPI Actions whose `servers[0].url` resolves to the
// same hostname must both contribute their tools to the agent. The
// previous implementation indexed processed action sets by encoded
// domain, so the second action overwrote the first in the map and one
// action's tools silently disappeared from the LLM payload.
//
// The encoded domain we use as the lookup key for the action sets is
// mocked to a fixed string for both actions to make the collision
// condition deterministic without depending on the real base64
// truncation rules.
const SHARED_DOMAIN = 'https://api.example.com';
const ENCODED_DOMAIN = 'shared_dom';
const LEGACY_ENCODED_DOMAIN = 'legacy_dom';
const buildSpec = (operationId, path) =>
JSON.stringify({
openapi: '3.0.3',
info: { title: `Mock ${operationId}`, version: '1.0.0' },
servers: [{ url: SHARED_DOMAIN }],
paths: {
[path]: {
get: {
operationId,
summary: `Mock ${operationId}`,
responses: {
200: {
description: 'OK',
content: { 'application/json': { schema: { type: 'object' } } },
},
},
},
},
},
});
const actionA = {
action_id: 'action_a',
metadata: {
domain: SHARED_DOMAIN,
raw_spec: buildSpec('echoMessage', '/echo'),
},
};
const actionB = {
action_id: 'action_b',
metadata: {
domain: SHARED_DOMAIN,
raw_spec: buildSpec('listItems', '/items'),
},
};
const toolNameA = `echoMessage${actionDelimiter}${ENCODED_DOMAIN}`;
const toolNameB = `listItems${actionDelimiter}${ENCODED_DOMAIN}`;
beforeEach(() => {
// Both actions share a hostname → both call sites get the same encoded
// value back. This is precisely the collision shape that triggered
// the bug in production.
mockDomainParser.mockResolvedValue(ENCODED_DOMAIN);
mockLegacyDomainEncode.mockReturnValue(LEGACY_ENCODED_DOMAIN);
mockDecryptMetadata.mockImplementation(async (metadata) => metadata);
mockCreateActionTool.mockImplementation(async ({ name, requestBuilder }) => ({
name,
// Surface the request builder identity on the returned tool so
// assertions can verify each tool was wired to the correct action's
// builder, not its sibling's.
_builder: requestBuilder,
// Resolve instead of returning undefined — processRequiredActions
// chains `.then(handleToolOutput)` directly onto this call, which
// would throw synchronously on an undefined return and mask the
// test as a simulated runtime crash.
_call: jest.fn().mockResolvedValue('{"status":"ok"}'),
schema: {},
description: '',
}));
});
const expectBothActionsResolved = (calls) => {
const callsByName = new Map(calls.map((c) => [c[0].name, c[0]]));
expect(callsByName.has(toolNameA)).toBe(true);
expect(callsByName.has(toolNameB)).toBe(true);
// Each tool's request builder must come from the matching action's
// own parsed spec — not the sibling's. The previous bug would either
// route both to the same action's builders (and drop one as
// undefined) or silently skip one entirely.
const builderA = callsByName.get(toolNameA).requestBuilder;
const builderB = callsByName.get(toolNameB).requestBuilder;
expect(builderA).toBeDefined();
expect(builderB).toBeDefined();
expect(builderA).not.toBe(builderB);
// Each builder targets its own operation path — confirms the
// request builder lookup didn't cross-contaminate between actions.
expect(builderA.path).toBe('/echo');
expect(builderB.path).toBe('/items');
};
it('loadAgentTools resolves both actions when they share a hostname', async () => {
mockLoadActionSets.mockResolvedValue([actionA, actionB]);
const capabilities = [AgentCapabilities.tools, AgentCapabilities.actions];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await loadAgentTools({
req,
res: {},
agent: { id: 'agent_collision', tools: [toolNameA, toolNameB] },
definitionsOnly: false,
});
expect(mockCreateActionTool).toHaveBeenCalledTimes(2);
expectBothActionsResolved(mockCreateActionTool.mock.calls);
});
it('loadAgentTools is order-invariant for two actions sharing a hostname', async () => {
// Reverse the actionSets order — what used to flip the "winner" of
// the encoded-domain Map overwrite must now make zero observable
// difference.
mockLoadActionSets.mockResolvedValue([actionB, actionA]);
const capabilities = [AgentCapabilities.tools, AgentCapabilities.actions];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await loadAgentTools({
req,
res: {},
agent: { id: 'agent_collision', tools: [toolNameA, toolNameB] },
definitionsOnly: false,
});
expect(mockCreateActionTool).toHaveBeenCalledTimes(2);
expectBothActionsResolved(mockCreateActionTool.mock.calls);
});
it('loadToolsForExecution resolves both actions when they share a hostname', async () => {
mockLoadActionSets.mockResolvedValue([actionA, actionB]);
const req = createMockReq([AgentCapabilities.actions]);
req.config = {};
await loadToolsForExecution({
req,
res: {},
agent: { id: 'agent_collision' },
toolNames: [toolNameA, toolNameB],
actionsEnabled: true,
});
expect(mockCreateActionTool).toHaveBeenCalledTimes(2);
expectBothActionsResolved(mockCreateActionTool.mock.calls);
});
it('processRequiredActions resolves both actions when they share a hostname', async () => {
// The assistants/threads path received the same structural rewrite
// as the agent paths. Cover it directly so future regressions in the
// `toolToAction` map shape or the lookup normalization don't slip
// through just because the agent-path tests still pass.
mockLoadActionSets.mockResolvedValue([actionA, actionB]);
const client = {
req: {
user: { id: 'user_123' },
body: {
assistant_id: 'assistant_collision',
model: 'gpt-4o-mini',
endpoint: 'openAI',
},
config: {},
},
res: {},
apiKey: 'sk-test',
mappedOrder: new Map(),
seenToolCalls: new Map(),
addContentData: jest.fn(),
};
await processRequiredActions(client, [
{
tool: toolNameA,
toolInput: {},
toolCallId: 'call_a',
thread_id: 'thread_1',
run_id: 'run_1',
},
{
tool: toolNameB,
toolInput: {},
toolCallId: 'call_b',
thread_id: 'thread_1',
run_id: 'run_1',
},
]);
// The assistants path intentionally doesn't forward `name` to
// createActionTool (see ToolService.js — "intentionally not passing
// zodSchema, name, and description for assistants API"), so key
// resolution assertions off the request builder path instead.
expect(mockCreateActionTool).toHaveBeenCalledTimes(2);
expect(mockLoadToolsUtil).toHaveBeenCalledWith(
expect.objectContaining({
options: expect.objectContaining({ res: client.res }),
}),
);
const builderPaths = mockCreateActionTool.mock.calls.map((c) => c[0].requestBuilder?.path);
expect(builderPaths).toEqual(expect.arrayContaining(['/echo', '/items']));
// Each call must carry a distinct builder — guards against the bug
// where the surviving action's builders got routed to every tool.
expect(builderPaths[0]).not.toBe(builderPaths[1]);
});
it('loadAgentTools resolves legacy-format tool names via the legacy encoding branch', async () => {
// Agents whose tool names predate the current domain encoding store
// them under `legacyDomainEncode`'s output. The map registers both
// encodings per function so these keep resolving after the fix;
// this test exercises the `if (legacyNormalized !== normalizedDomain)`
// branch, which was previously never hit by any test.
mockLoadActionSets.mockResolvedValue([actionA]);
const legacyToolName = `echoMessage${actionDelimiter}${LEGACY_ENCODED_DOMAIN}`;
const capabilities = [AgentCapabilities.tools, AgentCapabilities.actions];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await loadAgentTools({
req,
res: {},
agent: { id: 'agent_legacy', tools: [legacyToolName] },
definitionsOnly: false,
});
expect(mockCreateActionTool).toHaveBeenCalledTimes(1);
const [callArgs] = mockCreateActionTool.mock.calls[0];
expect(callArgs.name).toBe(legacyToolName);
expect(callArgs.requestBuilder.path).toBe('/echo');
});
it('definitions-only loading emits the selected legacy action name', async () => {
mockLoadActionSets.mockResolvedValue([actionA]);
const legacyToolName = `echoMessage${actionDelimiter}${LEGACY_ENCODED_DOMAIN}`;
const capabilities = [AgentCapabilities.tools, AgentCapabilities.actions];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockLoadToolDefinitions.mockImplementationOnce(async (_options, dependencies) => {
const definitions = await dependencies.getActionToolDefinitions('agent_legacy', [
legacyToolName,
]);
expect(definitions).toEqual([
expect.objectContaining({ name: legacyToolName, description: 'Mock echoMessage' }),
]);
return {
toolDefinitions: definitions,
toolRegistry: new Map(),
hasDeferredTools: false,
};
});
await loadAgentTools({
req,
res: {},
agent: {
id: 'agent_legacy',
tools: [legacyToolName],
tool_options: { [legacyToolName]: { run_in_background: true } },
},
definitionsOnly: true,
});
expect(mockLoadToolDefinitions).toHaveBeenCalledTimes(1);
});
it('loadAgentTools distinguishes operationIds that differ only by `---` vs `_`', async () => {
// `openapiToFunction` uses the user-supplied operationId verbatim
// and only sanitizes the synthetic `<method>_<path>` fallback, and
// `sanitizeOperationId` preserves `-`. So two operations whose
// operationIds differ only by `---` vs `_` (e.g. `get_foo---bar`
// and `get_foo_bar`) are legitimately distinct on the same spec —
// or, here, on two actions sharing a hostname.
//
// Normalization must only touch the encoded-domain suffix after
// `actionDelimiter`; if it also collapsed the operationId, both
// tools would write to the same map slot and resolve to the
// surviving entry's request builder.
const hyphenSpec = {
action_id: 'action_hyphen',
metadata: {
domain: SHARED_DOMAIN,
raw_spec: buildSpec('get_foo---bar', '/foo-bar'),
},
};
const underscoreSpec = {
action_id: 'action_underscore',
metadata: {
domain: SHARED_DOMAIN,
raw_spec: buildSpec('get_foo_bar', '/foo_bar'),
},
};
mockLoadActionSets.mockResolvedValue([hyphenSpec, underscoreSpec]);
const hyphenTool = `get_foo---bar${actionDelimiter}${ENCODED_DOMAIN}`;
const underscoreTool = `get_foo_bar${actionDelimiter}${ENCODED_DOMAIN}`;
const capabilities = [AgentCapabilities.tools, AgentCapabilities.actions];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await loadAgentTools({
req,
res: {},
agent: { id: 'agent_hyphen', tools: [hyphenTool, underscoreTool] },
definitionsOnly: false,
});
expect(mockCreateActionTool).toHaveBeenCalledTimes(2);
const callsByName = new Map(mockCreateActionTool.mock.calls.map((c) => [c[0].name, c[0]]));
expect(callsByName.has(hyphenTool)).toBe(true);
expect(callsByName.has(underscoreTool)).toBe(true);
expect(callsByName.get(hyphenTool).requestBuilder.path).toBe('/foo-bar');
expect(callsByName.get(underscoreTool).requestBuilder.path).toBe('/foo_bar');
// Critical: the two must resolve to distinct builders. If the
// operationId half of the key is normalized, both collapse to
// the same map slot and one silently overwrites the other.
expect(callsByName.get(hyphenTool).requestBuilder).not.toBe(
callsByName.get(underscoreTool).requestBuilder,
);
});
it('loadAgentTools resolves raw `---`-separated tool names from agent.tools', async () => {
// Hostnames at or below ENCODED_DOMAIN_LENGTH round-trip through
// `domainParser(..., true)` as a `---`-separated string, and agents
// persist that raw form in `agent.tools`. The map is always keyed
// with the `_`-collapsed form, so the lookup must normalize the
// incoming name or short-hostname tools silently drop out.
mockDomainParser.mockResolvedValue('shared---dom');
mockLoadActionSets.mockResolvedValue([actionA, actionB]);
const rawNameA = `echoMessage${actionDelimiter}shared---dom`;
const rawNameB = `listItems${actionDelimiter}shared---dom`;
const capabilities = [AgentCapabilities.tools, AgentCapabilities.actions];
const req = createMockReq(capabilities);
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
await loadAgentTools({
req,
res: {},
agent: { id: 'agent_short', tools: [rawNameA, rawNameB] },
definitionsOnly: false,
});
expect(mockCreateActionTool).toHaveBeenCalledTimes(2);
const callsByName = new Map(mockCreateActionTool.mock.calls.map((c) => [c[0].name, c[0]]));
expect(callsByName.has(rawNameA)).toBe(true);
expect(callsByName.has(rawNameB)).toBe(true);
expect(callsByName.get(rawNameA).requestBuilder.path).toBe('/echo');
expect(callsByName.get(rawNameB).requestBuilder.path).toBe('/items');
});
});
/**
* `AgentCapabilities` is the instance-wide switch; `FILE_SEARCH`/`RUN_CODE` are
* the per-role grants. A tool has to clear both, on the definitions path and the
* runtime path alike — otherwise a denied user is handed a definition the model
* will call and the loader will refuse.
*/
describe('loadAgentTools — tool role permission gating', () => {
const capabilities = [
AgentCapabilities.tools,
AgentCapabilities.file_search,
AgentCapabilities.execute_code,
AgentCapabilities.web_search,
];
const denyPermission = (deniedType) =>
mockGetRoleByName.mockResolvedValue(
buildRole({ [deniedType]: { [Permissions.USE]: false } }),
);
beforeEach(() => {
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
});
it('omits file_search from definitions when FILE_SEARCH.USE is denied', async () => {
denyPermission(PermissionTypes.FILE_SEARCH);
await loadAgentTools({
req: createMockReq(capabilities),
res: {},
agent: { id: 'agent_123', tools: [Tools.file_search, Tools.execute_code] },
tool_resources: { file_search: { file_ids: ['search-file'] } },
definitionsOnly: true,
});
expect(mockLoadToolDefinitions).toHaveBeenCalledTimes(1);
const [callArgs] = mockLoadToolDefinitions.mock.calls[0];
expect(callArgs.tools).not.toContain(Tools.file_search);
expect(callArgs.tools).toContain(Tools.execute_code);
});
it('does not prime search files for a denied user', async () => {
denyPermission(PermissionTypes.FILE_SEARCH);
await loadAgentTools({
req: createMockReq(capabilities),
res: {},
agent: { id: 'agent_123', tools: [Tools.file_search] },
tool_resources: { file_search: { file_ids: ['search-file'] } },
definitionsOnly: true,
});
expect(mockPrimeSearchFiles).not.toHaveBeenCalled();
});
it('omits file_search from the runtime loader when FILE_SEARCH.USE is denied', async () => {
denyPermission(PermissionTypes.FILE_SEARCH);
await loadAgentTools({
req: createMockReq(capabilities),
res: {},
agent: { id: 'agent_123', tools: [Tools.file_search, Tools.execute_code] },
definitionsOnly: false,
});
expect(mockLoadToolsUtil).toHaveBeenCalledTimes(1);
const [callArgs] = mockLoadToolsUtil.mock.calls[0];
expect(callArgs.tools).not.toContain(Tools.file_search);
expect(callArgs.tools).toContain(Tools.execute_code);
});
it('omits execute_code when RUN_CODE.USE is denied', async () => {
denyPermission(PermissionTypes.RUN_CODE);
await loadAgentTools({
req: createMockReq(capabilities),
res: {},
agent: { id: 'agent_123', tools: [Tools.file_search, Tools.execute_code] },
tool_resources: { execute_code: { file_ids: ['code-file'] } },
definitionsOnly: true,
});
const [callArgs] = mockLoadToolDefinitions.mock.calls[0];
expect(callArgs.tools).not.toContain(Tools.execute_code);
expect(callArgs.tools).toContain(Tools.file_search);
expect(mockPrimeCodeFiles).not.toHaveBeenCalled();
});
/** Dropping `execute_code` from the tool list is not enough: this flag also
* reaches tool classification and the programmatic bash tool, either of
* which would otherwise run code for a role denied `RUN_CODE`. */
it('clears codeExecutionEnabled for the definitions payload when RUN_CODE is denied', async () => {
denyPermission(PermissionTypes.RUN_CODE);
await loadAgentTools({
req: createMockReq([...capabilities, AgentCapabilities.programmatic_tools]),
res: {},
agent: { id: 'agent_123', tools: [Tools.execute_code, 'calculator'] },
definitionsOnly: true,
});
const [callArgs] = mockLoadToolDefinitions.mock.calls[0];
expect(callArgs.codeExecutionEnabled).toBe(false);
});
it('keeps both tools when the role grants them', async () => {
await loadAgentTools({
req: createMockReq(capabilities),
res: {},
agent: { id: 'agent_123', tools: [Tools.file_search, Tools.execute_code] },
definitionsOnly: true,
});
const [callArgs] = mockLoadToolDefinitions.mock.calls[0];
expect(callArgs.tools).toEqual(
expect.arrayContaining([Tools.file_search, Tools.execute_code]),
);
expect(callArgs.codeExecutionEnabled).toBe(true);
});
it('omits web_search from definitions when WEB_SEARCH.USE is denied', async () => {
denyPermission(PermissionTypes.WEB_SEARCH);
await loadAgentTools({
req: createMockReq(capabilities),
res: {},
agent: { id: 'agent_123', tools: [Tools.web_search, Tools.execute_code] },
definitionsOnly: true,
});
const [callArgs] = mockLoadToolDefinitions.mock.calls[0];
expect(callArgs.tools).not.toContain(Tools.web_search);
expect(callArgs.tools).toContain(Tools.execute_code);
});
it('omits web_search from the runtime loader when WEB_SEARCH.USE is denied', async () => {
denyPermission(PermissionTypes.WEB_SEARCH);
await loadAgentTools({
req: createMockReq(capabilities),
res: {},
agent: { id: 'agent_123', tools: [Tools.web_search, Tools.execute_code] },
definitionsOnly: false,
});
expect(mockLoadToolsUtil).toHaveBeenCalledTimes(1);
const [callArgs] = mockLoadToolsUtil.mock.calls[0];
expect(callArgs.tools).not.toContain(Tools.web_search);
expect(callArgs.tools).toContain(Tools.execute_code);
});
it('keeps web_search when the role grants it', async () => {
await loadAgentTools({
req: createMockReq(capabilities),
res: {},
agent: { id: 'agent_123', tools: [Tools.web_search] },
definitionsOnly: true,
});
const [callArgs] = mockLoadToolDefinitions.mock.calls[0];
expect(callArgs.tools).toContain(Tools.web_search);
});
it('keeps web_search in the runtime loader when the role grants it', async () => {
await loadAgentTools({
req: createMockReq(capabilities),
res: {},
agent: { id: 'agent_123', tools: [Tools.web_search] },
definitionsOnly: false,
});
const [callArgs] = mockLoadToolsUtil.mock.calls[0];
expect(callArgs.tools).toContain(Tools.web_search);
});
it('fails closed when the role lookup throws', async () => {
mockGetRoleByName.mockRejectedValue(new Error('role lookup failed'));
await loadAgentTools({
req: createMockReq(capabilities),
res: {},
agent: { id: 'agent_123', tools: [Tools.file_search, Tools.execute_code, 'calculator'] },
definitionsOnly: true,
});
const [callArgs] = mockLoadToolDefinitions.mock.calls[0];
expect(callArgs.tools).toEqual(['calculator']);
});
it('skips the permission check when the capability is already disabled', async () => {
const toolsOnly = [AgentCapabilities.tools];
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(toolsOnly));
await loadAgentTools({
req: createMockReq(toolsOnly),
res: {},
agent: { id: 'agent_123', tools: [Tools.file_search, Tools.execute_code, 'calculator'] },
definitionsOnly: true,
});
expect(mockGetRoleByName).not.toHaveBeenCalled();
const [callArgs] = mockLoadToolDefinitions.mock.calls[0];
expect(callArgs.tools).toEqual(['calculator']);
});
});
});