LibreChat/api/server/services/Endpoints/agents/initialize.spec.js
Danny Avila 6189220697
Some checks failed
Backend Unit Tests / Build packages (push) Waiting to run
Backend Unit Tests / Codegraph select (push) Waiting to run
Backend Unit Tests / TypeScript type checks (push) Blocked by required conditions
Backend Unit Tests / Circular dependency checks (push) Waiting to run
Backend Unit Tests / Tests: api (shard 1/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: api (shard 2/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: api (shard 3/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: data-provider (push) Blocked by required conditions
Backend Unit Tests / Tests: data-schemas (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 1/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 2/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 3/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 4/4) (push) Blocked by required conditions
Codegraph E2E Votes / vote (shard 1/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 10/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 2/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 3/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 4/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 5/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 6/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 7/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 8/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 9/10) (push) Waiting to run
Docker Dev Branch Images Build / publish (push) Waiting to run
Frontend Unit Tests / Client build recovery regression (push) Waiting to run
Frontend Unit Tests / Codegraph select (push) Waiting to run
Frontend Unit Tests / Build packages (push) Waiting to run
Frontend Unit Tests / TypeScript type checks (client) (push) Blocked by required conditions
Frontend Unit Tests / Tests: @librechat/chat (push) Blocked by required conditions
Frontend Unit Tests / Tests: @librechat/client (push) Blocked by required conditions
Frontend Unit Tests / Tests: Ubuntu (shard 1/2) (push) Blocked by required conditions
Frontend Unit Tests / Tests: Ubuntu (shard 2/2) (push) Blocked by required conditions
Frontend Unit Tests / Vite build verification (push) Blocked by required conditions
Publish `@librechat/client` to NPM / pack (push) Waiting to run
Publish `@librechat/client` to NPM / publish-npm (push) Blocked by required conditions
Docker Dev Images Build / publish (push) Waiting to run
Sync Helm Chart Tags / Ignore non-main push (push) Waiting to run
Sync Helm Chart Tags / Sync chart tags (push) Waiting to run
Sync Locize Translations & Create Translation PR / Sync Translation Keys with Locize (push) Has been cancelled
Publish `librechat-data-provider` to NPM / pack (push) Has been cancelled
Publish `@librechat/data-schemas` to NPM / pack (push) Has been cancelled
Sync Locize Translations & Create Translation PR / Create Translation PR on Version Published (push) Has been cancelled
Publish `librechat-data-provider` to NPM / publish-npm (push) Has been cancelled
Publish `@librechat/data-schemas` to NPM / publish-npm (push) Has been cancelled
🏷️ fix: Resolve endpoints.all Title Settings per Field and Fold Ollama Endpoint Names (#17316)
* 🏷️ fix: Resolve endpoints.all Title Settings per Field and Fold Ollama Endpoint Names

Conversation titles picked `endpoints.all` as a whole block, so any `all`
block (even one holding only streamRate, headers or activity label keys)
hid every per-endpoint titleConvo, titleModel, titleMethod, titleEndpoint
and title prompt. `resolveTitleConfig` resolves each field from `all`,
then the named endpoint, then the custom endpoint entry, keeping
titleEndpoint and titleModel as one choice from the first layer that sets
either.

Config overrides merged `endpoints.custom` by exact name while the runtime
serves names through `normalizeEndpointName`, so an override `ollama`
survived beside the YAML `Ollama` and split the endpoint between two
baseURLs and keys. The merge key now folds the same way (the YAML spelling
is kept), merge-key issues, issue attribution and secret preservation use
the same identity, and the effective config serves
`modelSpecs.addedEndpoints`, `modelSpecs.list[].preset.endpoint` and
`endpoints.agents.allowedProviders` in served names without repeats.

A stored document that already names one endpoint in two spellings is
combined at merge in document order, so requests keep the host and key
of the first item instead of moving to the YAML entry; omit-to-keep
secret preservation reads the same combined entry. A new write naming
both spellings is rejected as a duplicate.

An agent saved as `Ollama` now runs on the served `ollama`: the model
catalog lookup (`resolveModelCatalogKey`) falls back to the served name,
and `initializeAgent` folds the provider before the allowedProviders
check and provider setup.

* 🏷️ fix: Report Per-Field endpoints.all Title Resolution in the Admin Config Meta

resolveTitleConfig resolves endpoints.all title settings one field at a time, so GET /api/admin/config/meta now reports rules.titleResolution as 'field'. meta.spec ties the reported value to resolveTitleConfig: with endpoints.all = { streamRate: 1 } and openAI.titleModel = 'x', the rule is 'field' exactly when the endpoint's titleModel survives.

* 🧪 test: Expect Segments on the Folded duplicate_merge_key Write Issue

Admin config write issues carry segments since #17322; the folded Ollama/ollama duplicate test now asserts them.

* 🏷️ fix: Match Folded Custom Endpoint Names in Admin Config Change Ops

The changes endpoint from dev matched entry keys exactly, while the config
merge, merge-key issues and secret preservation fold `Ollama`/`ollama` into
one custom endpoint. An upsertEntry `ollama` over a stored `Ollama` copied the
stored key, appended a second entry and failed as duplicate_merge_key;
removeEntry `ollama` left a stored `Ollama` in place; a rename onto another
spelling passed entry_exists; and the librechat.yaml entry check missed
`ollama` against the YAML `Ollama`.

- data-schemas: `getConfigEntryIdentity` folds a key by its override path;
  `getConfigEntryMatcher` backs upsertEntry, removeEntry, rename, written-path
  attribution and the stored-counterpart lookup; issue locations use the same
  identity. A rename of an entry stored in two spellings moves the one entry
  the runtime merge combines (`combineFoldedConfigEntries`).
- api: the YAML-entry rename guard and the per-batch duplicate check compare
  entries by the same identity.
- Tests: unit coverage for each op across spellings, and handler integration
  tests against MongoDB for upsert with secret preservation (single and
  two-spelling documents), removal, entry_exists, inherited_entry and
  duplicate changes in one batch.
2026-10-22 16:57:42 +02:00

4665 lines
159 KiB
JavaScript

const mongoose = require('mongoose');
const {
ResourceType,
PermissionBits,
PrincipalType,
PrincipalModel,
MAX_SUBAGENT_DEPTH,
MAX_SUBAGENT_GRAPH_NODES,
MAX_SUBAGENT_RUN_CONFIGS,
Constants,
ErrorTypes,
} = require('librechat-data-provider');
const { MongoMemoryServer } = require('mongodb-memory-server');
const mockInitializeAgent = jest.fn();
const mockValidateAgentModel = jest.fn();
const mockGetAppConfig = jest.fn();
jest.mock('~/server/services/Config', () => ({
...jest.requireActual('~/server/services/Config'),
getAppConfig: (...args) => mockGetAppConfig(...args),
}));
function deferred() {
let resolve;
const promise = new Promise((resolvePromise) => {
resolve = resolvePromise;
});
return { promise, resolve };
}
jest.mock('@librechat/agents', () => ({
...jest.requireActual('@librechat/agents'),
createContentAggregator: jest.fn(() => ({
contentParts: [],
aggregateContent: jest.fn(),
})),
}));
jest.mock('@librechat/api', () => ({
...jest.requireActual('@librechat/api'),
initializeAgent: (...args) => mockInitializeAgent(...args),
validateAgentModel: (...args) => mockValidateAgentModel(...args),
GenerationJobManager: { setCollectedUsage: jest.fn(), getJobStore: jest.fn() },
getCustomEndpointConfig: jest.fn(),
createSequentialChainEdges: jest.fn(),
}));
/** Captured by the `getDefaultHandlers` mock so tests can drive the
* `ON_TOOL_EXECUTE` pipeline with a real subagent id and observe whether
* the tool context (agent, tool_resources, skill ACLs) was preserved. */
let capturedToolExecuteOptions;
let capturedDefaultHandlerOptions;
const mockArtifactToolEndCallback = jest.fn();
jest.mock('~/server/controllers/agents/callbacks', () => ({
createToolEndCallback: jest.fn(() => mockArtifactToolEndCallback),
createAttachmentEmitter: jest.fn(() => jest.fn()),
createPtcProgressEmitter: jest.fn(() => jest.fn()),
createBackgroundCodeResultHandler: jest.fn(() => jest.fn()),
getDefaultHandlers: jest.fn((opts) => {
capturedDefaultHandlerOptions = opts;
capturedToolExecuteOptions = opts?.toolExecuteOptions;
return {};
}),
}));
const mockLoadToolsForExecution = jest.fn();
const mockGetAccessibleMcpServerNames = jest.fn();
jest.mock('~/server/services/ToolService', () => ({
loadAgentTools: jest.fn(),
loadToolsForExecution: (...args) => mockLoadToolsForExecution(...args),
getAccessibleMcpServerNames: (...args) => mockGetAccessibleMcpServerNames(...args),
isFatalAgentInitializationError:
jest.requireActual('@librechat/api').isFatalAgentInitializationError,
}));
jest.mock('~/server/controllers/ModelController', () => ({
getModelsConfig: jest.fn().mockResolvedValue({}),
}));
let agentClientArgs;
jest.mock('~/server/controllers/agents/client', () => {
return jest.fn().mockImplementation((args) => {
agentClientArgs = args;
return {};
});
});
jest.mock('./addedConvo', () => ({
processAddedConvo: jest.fn().mockResolvedValue({ userMCPAuthMap: undefined }),
}));
const mockResolveLinkedInstructions = jest.fn();
jest.mock('./linkedInstructions', () => ({
getLinkedInstructionsResolver: jest.fn(() => mockResolveLinkedInstructions),
}));
jest.mock('~/cache', () => ({
logViolation: jest.fn(),
}));
const { createInitializeClient, initializeClient } = require('./initialize');
const { processAddedConvo } = require('./addedConvo');
const { getSkillDbMethods, getSkillToolDeps } = require('./skillDeps');
const { loadAgentTools } = require('~/server/services/ToolService');
const { getModelsConfig } = require('~/server/controllers/ModelController');
const { logger } = require('@librechat/data-schemas');
const { User, AclEntry } = require('~/db/models');
const { createAgent, createSkill, updateAgent } = require('~/models');
const db = require('~/models');
jest.spyOn(logger, 'warn').mockImplementation(() => {});
const PRIMARY_ID = 'agent_primary';
const TARGET_ID = 'agent_target';
const AUTHORIZED_ID = 'agent_authorized';
describe('initializeClient — processAgent ACL gate', () => {
let mongoServer;
let testUser;
beforeAll(async () => {
mongoServer = await MongoMemoryServer.create();
await mongoose.connect(mongoServer.getUri());
});
afterAll(async () => {
await mongoose.disconnect();
await mongoServer.stop();
});
beforeEach(async () => {
await mongoose.connection.dropDatabase();
jest.clearAllMocks();
agentClientArgs = undefined;
capturedDefaultHandlerOptions = undefined;
testUser = await User.create({
email: 'test@example.com',
name: 'Test User',
username: 'testuser',
role: 'USER',
});
mockValidateAgentModel.mockResolvedValue({ isValid: true });
});
const makeReq = () => ({
user: { id: testUser._id.toString(), role: 'USER' },
body: { conversationId: 'conv_1', files: [] },
resolvedConversation: null,
config: { endpoints: {} },
_resumableStreamId: null,
});
const makeEndpointOption = () => ({
agent: Promise.resolve({
id: PRIMARY_ID,
name: 'Primary',
provider: 'openai',
model: 'gpt-4',
tools: [],
}),
model_parameters: { model: 'gpt-4' },
endpoint: 'agents',
});
const makePrimaryConfig = (edges) => ({
id: PRIMARY_ID,
endpoint: 'agents',
edges,
toolDefinitions: [],
toolRegistry: new Map(),
userMCPAuthMap: null,
tool_resources: {},
resendFiles: true,
maxContextTokens: 4096,
codeExecutionContext: {
baseUrl: 'https://code-default.example.com',
codeSessionKey: 'execute_code',
executionProfile: 'default',
statefulSessions: false,
},
});
it.each([false, true])('defers host credential resolution with restored=%s', async (restored) => {
const upstreamTokenProvider = jest.fn();
const resolveUpstreamTokenProvider = jest.fn().mockResolvedValue(upstreamTokenProvider);
const hostInitializeClient = createInitializeClient({ resolveUpstreamTokenProvider });
const req = makeReq();
req._isScheduledFire = true;
req._isAgentTrigger = !restored;
req.body.agent_id = PRIMARY_ID;
req.body.agentTrigger = {
version: 1,
event: {
type: 'schedule.occurrence',
occurredAt: 0,
source: { type: 'schedule', id: 'sched-1' },
},
};
await db.createSchedule({
id: 'sched-1',
user: testUser._id,
agent_id: PRIMARY_ID,
name: 'Legacy read',
prompt: 'Read',
cadence: { frequency: 'hourly', minute: 0, hour: 1 },
timezone: 'UTC',
enabled: true,
});
const signal = new AbortController().signal;
mockInitializeAgent.mockImplementationOnce(async ({ loadTools, agent }) => {
await loadTools({
tools: ['run_query_mcp_warehouse'],
model: agent.model,
agentId: agent.id,
provider: agent.provider,
});
return makePrimaryConfig([]);
});
await hostInitializeClient({
req,
res: {},
signal,
scheduledTokenContext: restored
? {
scheduleId: 'sched-1',
ownerId: req.user.id,
agentId: PRIMARY_ID,
invocationMode: 'delegated',
}
: undefined,
endpointOption: makeEndpointOption(),
});
expect(resolveUpstreamTokenProvider).not.toHaveBeenCalled();
const toolLoadParams = loadAgentTools.mock.calls[0][0];
expect(toolLoadParams.upstreamTokenProvider).toBeUndefined();
const resolver = toolLoadParams.upstreamTokenProviderResolver;
await expect(resolver({ signal })).resolves.toBe(upstreamTokenProvider);
expect(resolveUpstreamTokenProvider).toHaveBeenCalledWith(req.user, {
signal,
context: {
scheduleId: 'sched-1',
ownerId: req.user.id,
agentId: PRIMARY_ID,
invocationMode: 'delegated',
},
});
});
it.each([false, true])(
'binds the resource bearer host to the trusted root, restored=%s',
async (restored) => {
const {
getMCPRequestContext,
bindScheduledMCPBearerInvocation,
createScheduledMCPBearerHeaderResolver,
ScheduledMCPBearerError,
} = require('@librechat/api');
const receipts = jest
.spyOn(require('~/server/services/Schedules'), 'recordMCPToolAuthFailure')
.mockResolvedValue(true);
const boundaries = jest
.spyOn(require('~/server/services/Schedules'), 'registerMCPSettlement')
.mockImplementation(() => {});
const resolve = jest.fn(async (input) => input.config);
const bind = jest.fn((identity) => ({ identity, resolve, reject: jest.fn() }));
const host = createInitializeClient({ scheduledBearerHost: { bind } });
const req = makeReq();
req._resumableStreamId = 'notification-owner';
req._isScheduledFire = true;
req._isAgentTrigger = !restored;
req.body.agent_id = PRIMARY_ID;
req.body.agentTrigger = {
version: 1,
event: {
type: 'schedule.occurrence',
occurredAt: 0,
source: { type: 'schedule', id: 'sched-bearer' },
},
};
await db.createSchedule({
id: 'sched-bearer',
user: testUser._id,
agent_id: PRIMARY_ID,
name: 'Bearer',
prompt: 'Read',
cadence: { frequency: 'hourly', minute: 0, hour: 1 },
timezone: 'UTC',
enabled: true,
});
mockInitializeAgent.mockResolvedValue(makePrimaryConfig([]));
await host({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
jobCreatedAt: 42,
scheduledTokenContext: restored
? {
scheduleId: 'sched-bearer',
ownerId: req.user.id,
agentId: PRIMARY_ID,
invocationMode: 'delegated',
}
: undefined,
});
expect(bind).toHaveBeenCalledWith(
{
scheduleId: 'sched-bearer',
ownerId: req.user.id,
tenantId: null,
agentId: PRIMARY_ID,
invocationMode: 'delegated',
},
restored ? 'resume' : 'invoke',
expect.any(AbortSignal),
{ manual: false },
);
const invocation = bindScheduledMCPBearerInvocation(
getMCPRequestContext(req),
'child',
'read',
);
const config = { type: 'streamable-http', url: 'https://resource.test/mcp' };
await invocation.resolve({ user: req.user, serverName: 'Files', config });
expect(resolve).toHaveBeenCalledWith(
expect.objectContaining({ selection: { agentId: 'child', tools: ['read'] }, config }),
);
const headers = createScheduledMCPBearerHeaderResolver({
context: getMCPRequestContext(req),
user: req.user,
serverName: 'Files',
config: {
...config,
source: 'yaml',
headers: { Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}' },
},
});
req.body.agent_id = 'forged';
req._resumableStreamId = 'forged-stream';
const failure = new ScheduledMCPBearerError('consent_revoked', 'Files');
await headers.recordFailure(failure);
expect(receipts).toHaveBeenCalledWith({
error: failure,
streamId: 'notification-owner',
jobCreatedAt: 42,
userId: req.user.id,
serverName: 'Files',
identity: {
scheduleId: 'sched-bearer',
ownerId: req.user.id,
tenantId: null,
agentId: PRIMARY_ID,
invocationMode: 'delegated',
},
});
await headers.settle();
expect(boundaries).toHaveBeenCalledWith(
expect.objectContaining({
streamId: 'notification-owner',
jobCreatedAt: 42,
quiesce: expect.any(Function),
identity: expect.objectContaining({ agentId: PRIMARY_ID, ownerId: req.user.id }),
}),
);
boundaries.mockRestore();
receipts.mockRestore();
},
);
it('persists trusted completion lineage before initialization and rechecks it on authenticated resume', async () => {
const { InMemoryJobStore, GenerationJobManager } = require('@librechat/api');
const store = new InMemoryJobStore();
GenerationJobManager.getJobStore.mockReturnValue(store);
const req = makeReq();
req._isAgentTrigger = true;
req._resumableStreamId = 'completion-lineage';
req.body.conversationId = 'completion-lineage';
req.body.agentCompletion = {
version: 1,
sourceId: 'subagent-completion',
scheduleMCPIdentity: {
scheduleId: 'completion-schedule',
ownerId: req.user.id,
tenantId: null,
agentId: PRIMARY_ID,
invocationMode: 'delegated',
},
};
req.body.agent_id = PRIMARY_ID;
const identity = {
scheduleId: 'completion-schedule',
ownerId: req.user.id,
tenantId: null,
agentId: PRIMARY_ID,
invocationMode: 'delegated',
};
await db.createSchedule({
id: identity.scheduleId,
user: testUser._id,
agent_id: PRIMARY_ID,
name: 'Legacy',
prompt: 'Read',
cadence: { frequency: 'hourly', minute: 0, hour: 1 },
timezone: 'UTC',
enabled: true,
});
await db.insertScheduleRun({
scheduleId: identity.scheduleId,
user: testUser._id,
conversationId: req.body.conversationId,
scheduledFor: new Date(),
status: 'started',
});
const job = await store.createJob(req._resumableStreamId, req.user.id, req.body.conversationId);
try {
mockInitializeAgent.mockImplementationOnce(async () => {
expect((await store.getJob(job.streamId)).scheduleMCPCompletion).toEqual(identity);
return makePrimaryConfig([]);
});
await initializeClient({
req,
res: {},
endpointOption: makeEndpointOption(),
signal: new AbortController().signal,
jobCreatedAt: job.createdAt,
});
const retained = await store.getJob(job.streamId);
expect(retained.scheduleId).toBeUndefined();
await mongoose.models.Schedule.updateOne(
{ id: identity.scheduleId },
{ $set: { mcpConsent: { version: 999 } } },
);
mockInitializeAgent.mockClear();
await expect(
initializeClient({
req: { ...req, _isAgentTrigger: false },
res: {},
endpointOption: makeEndpointOption(),
signal: new AbortController().signal,
jobCreatedAt: job.createdAt,
scheduleJobIdentity: { scheduleMCPCompletion: retained.scheduleMCPCompletion },
}),
).rejects.toMatchObject({ failure: { reason: 'binding_mismatch' } });
expect(mockInitializeAgent).not.toHaveBeenCalled();
} finally {
await store.destroy();
}
});
it('preserves the owning cancellation before scheduled preparation begins', async () => {
const req = makeReq();
req._isScheduledFire = true;
const controller = new AbortController();
const stop = new Error('Owner stopped');
controller.abort(stop);
mockInitializeAgent.mockClear();
await expect(
initializeClient({
req,
res: {},
endpointOption: makeEndpointOption(),
signal: controller.signal,
}),
).rejects.toBe(stop);
expect(mockInitializeAgent).not.toHaveBeenCalled();
});
it('keeps interactive agent initialization independent of the host resolver', async () => {
const resolveUpstreamTokenProvider = jest.fn();
const hostInitializeClient = createInitializeClient({ resolveUpstreamTokenProvider });
mockInitializeAgent.mockResolvedValue(makePrimaryConfig([]));
await hostInitializeClient({
req: makeReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(resolveUpstreamTokenProvider).not.toHaveBeenCalled();
});
it('forwards the linked-instructions resolver and records usage by default', async () => {
mockInitializeAgent.mockResolvedValue(makePrimaryConfig([]));
await initializeClient({
req: makeReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(mockInitializeAgent).toHaveBeenCalledWith(
expect.objectContaining({
resolveLinkedInstructions: mockResolveLinkedInstructions,
recordLinkedPromptUsage: true,
}),
expect.anything(),
);
});
it('forwards recordLinkedPromptUsage: false for every agent initialized on the resume path', async () => {
mockInitializeAgent.mockResolvedValue(makePrimaryConfig([]));
await initializeClient({
req: makeReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
isResume: true,
});
expect(mockInitializeAgent).toHaveBeenCalledWith(
expect.objectContaining({
resolveLinkedInstructions: mockResolveLinkedInstructions,
recordLinkedPromptUsage: false,
}),
expect.anything(),
);
});
it('replaces untrusted artifact route metadata with the executing agent context', async () => {
mockInitializeAgent.mockResolvedValue(makePrimaryConfig([]));
await initializeClient({
req: makeReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
const data = { output: { name: 'execute_code', artifact: { files: [] } } };
await capturedDefaultHandlerOptions.toolEndCallback(data, {
langgraph_node: `tools=${PRIMARY_ID}`,
codeExecutionContext: {
baseUrl: 'https://attacker.invalid',
executionProfile: 'stateful',
},
});
expect(mockArtifactToolEndCallback).toHaveBeenLastCalledWith(
data,
expect.objectContaining({
codeExecutionContext: expect.objectContaining({
baseUrl: 'https://code-default.example.com',
executionProfile: 'default',
}),
}),
);
});
it('threads the owning job epoch into resumable event handlers', async () => {
const {
createAttachmentEmitter,
createPtcProgressEmitter,
createToolEndCallback,
} = require('~/server/controllers/agents/callbacks');
mockInitializeAgent.mockResolvedValue(makePrimaryConfig([]));
const req = makeReq();
req._resumableStreamId = 'conv_1';
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
jobCreatedAt: 1234,
});
expect(capturedDefaultHandlerOptions).toEqual(
expect.objectContaining({
streamId: 'conv_1',
jobCreatedAt: 1234,
}),
);
expect(
require('~/server/controllers/agents/callbacks').createBackgroundCodeResultHandler,
).toHaveBeenCalledWith(expect.objectContaining({ jobCreatedAt: 1234 }));
expect(createToolEndCallback).toHaveBeenCalledWith(
expect.objectContaining({
streamId: 'conv_1',
jobCreatedAt: 1234,
}),
);
expect(createAttachmentEmitter).toHaveBeenCalledWith({
res: {},
streamId: 'conv_1',
jobCreatedAt: 1234,
});
/** The PTC trace emitter is generation-fenced like every other resumable
* emitter; a stale epoch would leak one run's inner calls into the next. */
expect(createPtcProgressEmitter).toHaveBeenCalledWith({
res: {},
streamId: 'conv_1',
jobCreatedAt: 1234,
});
mockLoadToolsForExecution.mockResolvedValue({ loadedTools: [], configurable: {} });
await capturedToolExecuteOptions.loadTools([], PRIMARY_ID);
expect(mockLoadToolsForExecution).toHaveBeenCalledWith(
expect.objectContaining({
streamId: 'conv_1',
jobCreatedAt: 1234,
}),
);
});
it('publishes event-root activity through the owning child task stream', async () => {
const subagentThreadTaskStore = require('./subagentThreadStore');
const publishTaskActivity = jest
.spyOn(subagentThreadTaskStore, 'publishTaskActivity')
.mockResolvedValueOnce(undefined);
mockInitializeAgent.mockResolvedValue(makePrimaryConfig([]));
const req = makeReq();
req._resumableStreamId = 'child-conversation';
req.body.conversationId = 'child-conversation';
req._agentEventTaskId = 'event-task';
req._agentEventBindingParentConversationId = 'parent-conversation';
req._agentEventBindingParentAgentId = 'parent-agent';
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(capturedDefaultHandlerOptions.eventChildActivity).toEqual(
expect.objectContaining({
runId: 'child-conversation',
parentRunId: 'parent-conversation',
subagentRunId: 'event-task',
subagentType: PRIMARY_ID,
subagentAgentId: PRIMARY_ID,
parentAgentId: 'parent-agent',
}),
);
await capturedDefaultHandlerOptions.eventChildActivity.publish({
phase: 'writing',
label: 'Drafting response',
});
expect(publishTaskActivity).toHaveBeenCalledWith('child-conversation', 'event-task', {
phase: 'writing',
label: 'Drafting response',
});
});
it('binds foreground tool execution to the host-owned run signal', async () => {
mockInitializeAgent.mockResolvedValue(makePrimaryConfig([]));
const controller = new AbortController();
const req = makeReq();
req.body.messageId = 'user-message-1';
await initializeClient({
req,
res: {},
signal: controller.signal,
endpointOption: makeEndpointOption(),
foregroundRunId: 'response-1',
requestBody: { messageId: 'response-1', conversationId: 'conv_1' },
});
expect(capturedToolExecuteOptions.runSignal).toBe(controller.signal);
expect(capturedToolExecuteOptions.foregroundRunId).toBe('response-1');
});
it('threads the deployment ordinary-tool cancellation gate into execution', async () => {
mockInitializeAgent.mockResolvedValue(makePrimaryConfig([]));
const disabledReq = makeReq();
await initializeClient({
req: disabledReq,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(capturedToolExecuteOptions.ordinaryToolCancellation).toBe(false);
expect(capturedToolExecuteOptions.backgroundCompletionResultMaxChars).toBeUndefined();
const enabledReq = makeReq();
enabledReq.config.endpoints.agents = {
backgroundTasks: { ordinaryToolCancellation: true, completionResultMaxChars: 4096 },
};
await initializeClient({
req: enabledReq,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(capturedToolExecuteOptions.ordinaryToolCancellation).toBe(true);
expect(capturedToolExecuteOptions.backgroundCompletionResultMaxChars).toBe(4096);
});
it('propagates an expected-MCP-tools failure from the runtime tool loader', async () => {
const toolError = Object.assign(new Error('Expected MCP tools are unavailable'), {
code: 'AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE',
statusCode: 503,
});
loadAgentTools.mockRejectedValueOnce(toolError);
mockInitializeAgent.mockImplementationOnce(async ({ req, res, loadTools, agent }) => {
await loadTools({
req,
res,
tools: ['run_query_mcp_warehouse'],
model: agent.model,
agentId: agent.id,
provider: agent.provider,
});
return makePrimaryConfig([]);
});
await expect(
initializeClient({
req: makeReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
}),
).rejects.toBe(toolError);
});
it.each([
new (require('@librechat/api').OpenIDReauthRequiredError)('Please sign in again'),
new (require('@librechat/api').MCPAuthenticationRejectedError)('private-mcp', false),
new (require('@librechat/api').MCPAuthenticationRefreshError)(new Error('Retry later')),
])('preserves credential failure through the runtime agent loader: %s', async (toolError) => {
loadAgentTools.mockRejectedValueOnce(toolError);
mockInitializeAgent.mockImplementationOnce(async ({ req, res, loadTools, agent }) => {
await loadTools({
req,
res,
tools: ['run_query_mcp_warehouse'],
model: agent.model,
agentId: agent.id,
provider: agent.provider,
});
return makePrimaryConfig([]);
});
await expect(
initializeClient({
req: makeReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
}),
).rejects.toBe(toolError);
});
it('aborts the run when a handoff target resolves none of its expected MCP tools', async () => {
const target = await createAgent({
id: AUTHORIZED_ID,
name: 'Target Agent',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: ['run_query_mcp_warehouse'],
});
await AclEntry.create({
principalType: PrincipalType.USER,
principalId: testUser._id,
principalModel: PrincipalModel.USER,
resourceType: ResourceType.AGENT,
resourceId: target._id,
permBits: PermissionBits.VIEW,
grantedBy: testUser._id,
});
const toolError = Object.assign(new Error('Target Agent expected MCP tools are unavailable'), {
code: 'AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE',
statusCode: 503,
});
loadAgentTools.mockRejectedValueOnce(toolError);
mockInitializeAgent
.mockResolvedValueOnce(
makePrimaryConfig([{ from: PRIMARY_ID, to: AUTHORIZED_ID, edgeType: 'handoff' }]),
)
.mockImplementationOnce(async ({ req, res, loadTools, agent }) => {
await loadTools({
req,
res,
tools: agent.tools,
model: agent.model,
agentId: agent.id,
provider: agent.provider,
});
});
await expect(
initializeClient({
req: makeReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
}),
).rejects.toBe(toolError);
});
it('should skip handoff agent and filter its edge when user lacks VIEW access', async () => {
await createAgent({
id: TARGET_ID,
name: 'Target Agent',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: [],
});
const edges = [{ from: PRIMARY_ID, to: TARGET_ID, edgeType: 'handoff' }];
mockInitializeAgent.mockResolvedValue(makePrimaryConfig(edges));
await initializeClient({
req: makeReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
expect(agentClientArgs.agent.edges).toEqual([]);
});
it('should initialize handoff agent and keep its edge when user has VIEW access', async () => {
const authorizedAgent = await createAgent({
id: AUTHORIZED_ID,
name: 'Authorized Agent',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: [],
});
await AclEntry.create({
principalType: PrincipalType.USER,
principalId: testUser._id,
principalModel: PrincipalModel.USER,
resourceType: ResourceType.AGENT,
resourceId: authorizedAgent._id,
permBits: PermissionBits.VIEW,
grantedBy: testUser._id,
});
const edges = [{ from: PRIMARY_ID, to: AUTHORIZED_ID, edgeType: 'handoff' }];
const requestAttachment = { file_id: 'request_file', filename: 'request.txt' };
const primaryContextAttachment = { file_id: 'primary_context', filename: 'primary.txt' };
const handoffContextAttachment = { file_id: 'handoff_context', filename: 'handoff.txt' };
const primaryConfig = {
...makePrimaryConfig(edges),
attachments: [primaryContextAttachment, requestAttachment],
requestAttachments: [requestAttachment],
agentContextAttachments: [primaryContextAttachment],
};
const handoffConfig = {
id: AUTHORIZED_ID,
edges: [],
toolDefinitions: [],
toolRegistry: new Map(),
userMCPAuthMap: null,
tool_resources: {},
agentContextAttachments: [handoffContextAttachment],
};
let callCount = 0;
mockInitializeAgent.mockImplementation(() => {
callCount++;
return callCount === 1 ? Promise.resolve(primaryConfig) : Promise.resolve(handoffConfig);
});
await initializeClient({
req: makeReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(mockInitializeAgent).toHaveBeenCalledTimes(2);
expect(agentClientArgs.agent.edges).toHaveLength(1);
expect(agentClientArgs.agent.edges[0].to).toBe(AUTHORIZED_ID);
expect(agentClientArgs.attachments).toEqual([requestAttachment]);
expect(agentClientArgs.agentContextAttachmentsByAgentId.get(PRIMARY_ID)).toEqual([
primaryContextAttachment,
]);
expect(agentClientArgs.agentContextAttachmentsByAgentId.get(AUTHORIZED_ID)).toEqual([
handoffContextAttachment,
]);
});
it('does not enable skill authoring for VIEW-only shared skills', async () => {
const { skill } = await createSkill({
name: 'shared-view-only',
description: 'Use for read-only sharing.',
body: '# Shared view-only skill\n',
author: new mongoose.Types.ObjectId(),
authorName: 'Skill Owner',
});
await AclEntry.create({
principalType: PrincipalType.USER,
principalId: testUser._id,
principalModel: PrincipalModel.USER,
resourceType: ResourceType.SKILL,
resourceId: skill._id,
permBits: PermissionBits.VIEW,
grantedBy: testUser._id,
});
const endpointOption = makeEndpointOption();
endpointOption.agent = Promise.resolve({
id: PRIMARY_ID,
name: 'Primary',
provider: 'openai',
model: 'gpt-4',
tools: [],
skills_enabled: true,
});
mockInitializeAgent.mockResolvedValue(makePrimaryConfig([]));
const req = makeReq();
req.config.endpoints.agents = { capabilities: ['skills'] };
const canCreateSkillSpy = jest
.spyOn(getSkillToolDeps(), 'canCreateSkill')
.mockResolvedValue(false);
try {
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption,
});
} finally {
canCreateSkillSpy.mockRestore();
}
const initializeParams = mockInitializeAgent.mock.calls[0][0];
expect(initializeParams.accessibleSkillIds.map(String)).toContain(skill._id.toString());
expect(initializeParams.skillAuthoringAvailable).toBe(false);
});
it('enables skill authoring when model specs enable skills for an ephemeral agent', async () => {
const endpointOption = makeEndpointOption();
endpointOption.spec = 'spec-skills';
endpointOption.agent = Promise.resolve({
id: Constants.EPHEMERAL_AGENT_ID,
name: 'Ephemeral Primary',
provider: 'openai',
model: 'gpt-4',
tools: [],
});
mockInitializeAgent.mockResolvedValue(makePrimaryConfig([]));
const req = makeReq();
req.config.endpoints.agents = { capabilities: ['skills'] };
req.config.modelSpecs = {
list: [{ name: 'spec-skills', skills: true }],
};
const canCreateSkillSpy = jest
.spyOn(getSkillToolDeps(), 'canCreateSkill')
.mockResolvedValue(true);
try {
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption,
});
} finally {
canCreateSkillSpy.mockRestore();
}
const initializeParams = mockInitializeAgent.mock.calls[0][0];
expect(initializeParams.agent.skills_enabled).toBe(true);
expect(initializeParams.skillAuthoringAvailable).toBe(true);
});
it('enables standalone authoring without exposing the persisted agent skill catalog', async () => {
const endpointOption = makeEndpointOption();
endpointOption.agent = Promise.resolve({
id: PRIMARY_ID,
name: 'Primary',
provider: 'openai',
model: 'gpt-4',
tools: [],
skills: [],
skills_enabled: false,
skill_authoring_enabled: true,
});
mockInitializeAgent.mockResolvedValue(makePrimaryConfig([]));
const req = makeReq();
req.config.endpoints.agents = { capabilities: ['skills'] };
const canCreateSkillSpy = jest
.spyOn(getSkillToolDeps(), 'canCreateSkill')
.mockResolvedValue(true);
try {
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption,
});
} finally {
canCreateSkillSpy.mockRestore();
}
const initializeParams = mockInitializeAgent.mock.calls[0][0];
expect(initializeParams.accessibleSkillIds).toEqual([]);
expect(initializeParams.skillAuthoringAvailable).toBe(true);
});
it('loads model validation and skill permissions without serial waits', async () => {
const models = deferred();
const createPermission = deferred();
const req = makeReq();
req.config.endpoints.agents = { capabilities: ['skills'] };
mockInitializeAgent.mockResolvedValue(makePrimaryConfig([]));
getModelsConfig.mockReturnValueOnce(models.promise);
const canCreateSkillSpy = jest
.spyOn(getSkillToolDeps(), 'canCreateSkill')
.mockReturnValue(createPermission.promise);
try {
const initialization = initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(getModelsConfig).toHaveBeenCalledWith(req);
expect(canCreateSkillSpy).toHaveBeenCalledWith({ req });
models.resolve({});
await new Promise((resolve) => setImmediate(resolve));
expect(mockValidateAgentModel).toHaveBeenCalledTimes(1);
expect(mockInitializeAgent).not.toHaveBeenCalled();
createPermission.resolve(false);
await initialization;
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
} finally {
canCreateSkillSpy.mockRestore();
}
});
it('starts Project lookup as soon as the conversation snapshot resolves', async () => {
const models = deferred();
const conversation = deferred();
const project = deferred();
const req = makeReq();
delete req.resolvedConversation;
const getConvoSpy = jest.spyOn(db, 'getConvo').mockReturnValue(conversation.promise);
const getChatProjectSpy = jest.spyOn(db, 'getChatProject').mockReturnValue(project.promise);
getModelsConfig.mockReturnValueOnce(models.promise);
mockInitializeAgent.mockResolvedValue(makePrimaryConfig([]));
try {
const initialization = initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
conversation.resolve({
conversationId: 'conv_1',
chatProjectId: 'project-1',
user: req.user.id,
tenantId: null,
});
await new Promise((resolve) => setImmediate(resolve));
expect(getChatProjectSpy).toHaveBeenCalledWith(req.user.id, 'project-1');
models.resolve({});
project.resolve({
_id: 'project-1',
instructions: '',
contextRevision: 0,
file_ids: [],
tenantId: null,
});
await initialization;
} finally {
getConvoSpy.mockRestore();
getChatProjectSpy.mockRestore();
}
});
it('resolves model-spec skill names through deployment-aware skill methods', async () => {
const deploymentSkillId = new mongoose.Types.ObjectId();
await AclEntry.create({
principalType: PrincipalType.USER,
principalId: testUser._id,
principalModel: PrincipalModel.USER,
resourceType: ResourceType.SKILL,
resourceId: new mongoose.Types.ObjectId(),
permBits: PermissionBits.VIEW,
grantedBy: testUser._id,
});
const endpointOption = makeEndpointOption();
endpointOption.spec = 'spec-deployment-skill';
endpointOption.agent = Promise.resolve({
id: Constants.EPHEMERAL_AGENT_ID,
name: 'Ephemeral Primary',
provider: 'openai',
model: 'gpt-4',
tools: [],
});
mockInitializeAgent.mockResolvedValue(makePrimaryConfig([]));
const req = makeReq();
req.config.endpoints.agents = { capabilities: ['skills'] };
req.config.modelSpecs = {
list: [{ name: 'spec-deployment-skill', skills: ['deployment-skill'] }],
};
const getSkillByNameSpy = jest.spyOn(getSkillDbMethods(), 'getSkillByName').mockResolvedValue({
_id: deploymentSkillId,
name: 'deployment-skill',
source: 'deployment',
});
const canCreateSkillSpy = jest
.spyOn(getSkillToolDeps(), 'canCreateSkill')
.mockResolvedValue(false);
try {
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption,
});
expect(getSkillByNameSpy).toHaveBeenCalledWith(
'deployment-skill',
expect.any(Array),
expect.any(Object),
);
const initializeParams = mockInitializeAgent.mock.calls[0][0];
expect(initializeParams.agent.skills_enabled).toBe(true);
expect(initializeParams.agent.skills).toEqual([deploymentSkillId.toString()]);
} finally {
getSkillByNameSpy.mockRestore();
canCreateSkillSpy.mockRestore();
}
});
describe('an agent saved under another spelling of a served endpoint', () => {
const actualApi = jest.requireActual('@librechat/api');
/** The effective config as served: custom endpoint `Ollama` from librechat.yaml, its
* models under the served name `ollama`, and `allowedProviders` in served names. */
const runAgent = async (provider, catalog = { ollama: ['llama3.2'] }) => {
const req = makeReq();
req.config = {
endpoints: {
agents: { allowedProviders: ['ollama'] },
custom: [
{
name: 'Ollama',
apiKey: 'ollama',
baseURL: 'http://ollama.test:11434/v1',
models: { default: ['llama3.2'] },
},
],
},
};
getModelsConfig.mockResolvedValueOnce(catalog);
mockValidateAgentModel.mockImplementation(actualApi.validateAgentModel);
mockInitializeAgent.mockImplementation(actualApi.initializeAgent);
loadAgentTools.mockResolvedValue({ tools: [], toolContextMap: {}, toolDefinitions: [] });
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: {
...makeEndpointOption(),
agent: Promise.resolve({
id: PRIMARY_ID,
name: 'Primary',
provider,
model: 'llama3.2',
tools: [],
}),
model_parameters: { model: 'llama3.2' },
},
});
return agentClientArgs.agent;
};
afterEach(() => {
mockValidateAgentModel.mockReset();
mockInitializeAgent.mockReset();
loadAgentTools.mockReset();
});
it.each(['Ollama', 'OLLAMA'])(
'validates and runs an agent saved as %s on the served ollama endpoint',
async (provider) => {
const agent = await runAgent(provider);
expect(agent.endpoint).toBe('ollama');
expect(agent.model).toBe('llama3.2');
expect(mockValidateAgentModel).toHaveBeenCalledTimes(1);
},
);
it('still rejects a provider the served allowedProviders do not name', async () => {
await expect(runAgent('Probe', { Probe: ['llama3.2'] })).rejects.toThrow(
ErrorTypes.INVALID_AGENT_PROVIDER,
);
});
});
});
describe('initializeClient — subagent loading', () => {
const SUBAGENT_ID = 'agent_subagent_1';
const DUPLICATE_SUBAGENT_ID = 'agent_subagent_dup';
const HANDOFF_AND_SUB_ID = 'agent_handoff_and_sub';
let mongoServer;
let testUser;
beforeAll(async () => {
mongoServer = await MongoMemoryServer.create();
await mongoose.connect(mongoServer.getUri());
});
afterAll(async () => {
await mongoose.disconnect();
await mongoServer.stop();
});
beforeEach(async () => {
await mongoose.connection.dropDatabase();
jest.clearAllMocks();
agentClientArgs = undefined;
capturedToolExecuteOptions = undefined;
mockLoadToolsForExecution.mockReset();
mockLoadToolsForExecution.mockResolvedValue({ loadedTools: [], configurable: {} });
mockGetAccessibleMcpServerNames.mockReset();
mockGetAccessibleMcpServerNames.mockResolvedValue([]);
testUser = await User.create({
email: 'subagent@example.com',
name: 'Subagent User',
username: 'subuser',
role: 'USER',
});
mockValidateAgentModel.mockResolvedValue({ isValid: true });
});
/** Grant the test user VIEW on an agent so processAgent loads it. */
const grantView = async (agentDoc) => {
await AclEntry.create({
principalType: PrincipalType.USER,
principalId: testUser._id,
principalModel: PrincipalModel.USER,
resourceType: ResourceType.AGENT,
resourceId: agentDoc._id,
permBits: PermissionBits.VIEW,
grantedBy: testUser._id,
});
};
/** Build a request with the `subagents` capability enabled. */
const makeSubagentReq = () => ({
user: { id: testUser._id.toString(), role: 'USER' },
body: { conversationId: 'conv_sub', files: [] },
resolvedConversation: null,
config: {
endpoints: {
agents: {
capabilities: ['subagents'],
},
},
},
_resumableStreamId: null,
});
const makeEndpointOption = () => ({
agent: Promise.resolve({
id: PRIMARY_ID,
name: 'Primary',
provider: 'openai',
model: 'gpt-4',
tools: [],
}),
model_parameters: { model: 'gpt-4' },
endpoint: 'agents',
});
const makePrimaryConfig = ({ edges = [], subagents, agent_ids }) => ({
id: PRIMARY_ID,
endpoint: 'agents',
edges,
toolDefinitions: [],
toolRegistry: new Map(),
userMCPAuthMap: null,
tool_resources: {},
resendFiles: true,
maxContextTokens: 4096,
subagents,
agent_ids,
});
const makeSubagentConfig = (id) => ({
id,
endpoint: 'agents',
edges: [],
toolDefinitions: [{ name: 'web', description: 'web', parameters: {} }],
toolRegistry: new Map([['web', { name: 'web' }]]),
userMCPAuthMap: null,
tool_resources: { file_search: { file_ids: ['file_1'] } },
accessibleSkillIds: ['skill_1'],
actionsEnabled: true,
resendFiles: false,
maxContextTokens: 4096,
});
const makeNestedSubagentConfig = (id, childIds = []) => ({
...makeSubagentConfig(id),
subagents: { enabled: true, allowSelf: false, agent_ids: childIds },
});
const createViewableAgent = async (id, subagents) => {
const agent = await createAgent({
id,
name: id,
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: [],
subagents,
});
await grantView(agent);
return agent;
};
it('creates one trusted durable thread scope for detached subagents', async () => {
mockInitializeAgent.mockResolvedValue(
makePrimaryConfig({
subagents: { enabled: true, allowSelf: true, agent_ids: [] },
}),
);
const req = makeSubagentReq();
req.config.endpoints.agents.capabilities.push('run_in_background');
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(agentClientArgs.subagentTasks).toBe(capturedToolExecuteOptions.subagentTasks);
expect(agentClientArgs.subagentTasks.store.supportsThreadContinuation).toBe(true);
expect(JSON.parse(agentClientArgs.subagentTasks.scopeId)).toEqual({
version: 1,
userId: testUser._id.toString(),
parentConversationId: 'conv_sub',
});
});
it('uses one normalized MCP body for discovery, deferred execution, and AgentClient', async () => {
const requestBody = Object.freeze({
messageId: 'response-message',
conversationId: 'conv_sub',
parentMessageId: 'user-message',
});
mockInitializeAgent.mockResolvedValue(makePrimaryConfig({}));
mockLoadToolsForExecution.mockResolvedValue({ loadedTools: [], configurable: {} });
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
requestBody,
});
const normalizedRequestBody = mockInitializeAgent.mock.calls[0][0].requestBody;
expect(normalizedRequestBody).toEqual({
...requestBody,
codeEnvironmentMode: 'without_attached',
codeWorkspaces: undefined,
});
expect(agentClientArgs.mcpRequestBody).toBe(normalizedRequestBody);
await capturedToolExecuteOptions.loadTools([], PRIMARY_ID);
expect(mockLoadToolsForExecution).toHaveBeenCalledWith(
expect.objectContaining({ requestBody: normalizedRequestBody }),
);
});
it('retains only root-attributed model-invoked Skills for durable replay', async () => {
mockInitializeAgent.mockResolvedValue(makePrimaryConfig({}));
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
const rootSkill = {
id: 'root-skill',
name: 'root-skill',
version: 1,
contentDigest: 'root-digest',
};
const childSkill = {
id: 'child-skill',
name: 'child-skill',
version: 1,
contentDigest: 'child-digest',
};
capturedToolExecuteOptions.onSkillResolved(childSkill, { agentId: SUBAGENT_ID });
capturedToolExecuteOptions.onSkillResolved(rootSkill, { agentId: PRIMARY_ID });
expect([...agentClientArgs.invokedSkillIdentities.values()]).toEqual([rootSkill]);
});
it('keeps an existing detached task controllable after subagent config is disabled', async () => {
mockInitializeAgent.mockResolvedValue(
makePrimaryConfig({
subagents: { enabled: true, allowSelf: true, agent_ids: [] },
}),
);
const initialReq = makeSubagentReq();
initialReq.config.endpoints.agents.capabilities.push('run_in_background');
await initializeClient({
req: initialReq,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
const existingConfig = agentClientArgs.subagentTasks;
const subagentThreadTaskStore = require('./subagentThreadStore');
const hasTasksSpy = jest.spyOn(subagentThreadTaskStore, 'hasTasks').mockResolvedValueOnce(true);
mockInitializeAgent.mockResolvedValue(makePrimaryConfig({}));
const changedReq = makeSubagentReq();
changedReq.config.endpoints.agents.capabilities.push('run_in_background');
try {
await initializeClient({
req: changedReq,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
const currentConfig = agentClientArgs.subagentTasks;
expect(hasTasksSpy).toHaveBeenCalledWith(existingConfig.scopeId);
expect(currentConfig.scopeId).toBe(existingConfig.scopeId);
expect(currentConfig.completionDelivery).toBe(existingConfig.completionDelivery);
expect(currentConfig.store).not.toBe(existingConfig.store);
expect(capturedToolExecuteOptions.subagentTasks).toBe(currentConfig);
expect(agentClientArgs.agent.subagents).toBeUndefined();
} finally {
hasTasksSpy.mockRestore();
}
});
it('disables every nested subagent path at the durable child-thread depth limit', async () => {
const primaryConfig = makePrimaryConfig({
subagents: { enabled: true, allowSelf: true, agent_ids: [] },
});
mockInitializeAgent.mockResolvedValue(primaryConfig);
const req = makeSubagentReq();
req.config.endpoints.agents.capabilities.push('run_in_background');
req.resolvedConversation = {
conversationId: 'conv_sub',
subagentThread: { depth: 1 },
};
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(agentClientArgs.subagentTasks).toBeUndefined();
expect(capturedToolExecuteOptions.subagentTasks).toBeUndefined();
expect(agentClientArgs.agent.subagents).toBeUndefined();
});
it('keeps detached subagents disabled without the admin background capability', async () => {
mockInitializeAgent.mockResolvedValue(
makePrimaryConfig({
subagents: { enabled: true, allowSelf: true, agent_ids: [] },
}),
);
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(agentClientArgs.subagentTasks).toBeUndefined();
expect(capturedToolExecuteOptions.subagentTasks).toBeUndefined();
});
it('defers pure-subagent MCP initialization until the descriptor is selected', async () => {
const subAgent = await createAgent({
id: SUBAGENT_ID,
name: 'Data Subagent',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: [`${Constants.mcp_all}${Constants.mcp_delimiter}warehouse`],
});
await grantView(subAgent);
const toolError = Object.assign(new Error('Subagent expected MCP tools are unavailable'), {
code: 'AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE',
statusCode: 503,
});
loadAgentTools.mockRejectedValueOnce(toolError);
mockGetAccessibleMcpServerNames.mockResolvedValueOnce(['warehouse']);
mockInitializeAgent
.mockResolvedValueOnce(
makePrimaryConfig({
subagents: { enabled: true, allowSelf: true, agent_ids: [SUBAGENT_ID] },
}),
)
.mockImplementationOnce(async ({ req, res, loadTools, agent }) => {
await loadTools({
req,
res,
tools: agent.tools,
model: agent.model,
agentId: agent.id,
provider: agent.provider,
});
});
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
expect(mockGetAccessibleMcpServerNames).toHaveBeenCalledWith(testUser._id.toString(), 'USER');
expect(agentClientArgs.agent.lazySubagentConfigs[0].historicalToolNames).toEqual([
`${Constants.mcp_all}${Constants.mcp_delimiter}warehouse`,
]);
expect(agentClientArgs.agent.lazySubagentConfigs[0].historicalMcpServerNames).toEqual([
'warehouse',
]);
await expect(
agentClientArgs.agent.lazySubagentConfigs[0].resolve({
signal: new AbortController().signal,
}),
).rejects.toBe(toolError);
});
it('defers pure-subagent resource recovery until the descriptor is selected', async () => {
const subAgent = await createAgent({
id: SUBAGENT_ID,
name: 'Code Subagent',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: ['execute_code'],
});
await grantView(subAgent);
const resourceRecoveryError = Object.assign(new Error('resource recovery required'), {
code: ErrorTypes.RESOURCE_RECOVERY_REQUIRED,
status: 409,
statusCode: 409,
});
mockInitializeAgent
.mockResolvedValueOnce(
makePrimaryConfig({
subagents: { enabled: true, allowSelf: true, agent_ids: [SUBAGENT_ID] },
}),
)
.mockRejectedValueOnce(resourceRecoveryError);
const req = makeSubagentReq();
req.config.endpoints.agents.capabilities.push('execute_code');
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(agentClientArgs.agent.lazySubagentConfigs[0].historicalToolNames).toEqual([
'execute_code',
'bash_tool',
'read_file',
'create_file',
'edit_file',
'search_workspace',
'list_workspace_files',
]);
await expect(
agentClientArgs.agent.lazySubagentConfigs[0].resolve({
signal: new AbortController().signal,
}),
).rejects.toBe(resourceRecoveryError);
});
it('advertises a configured subagent without initializing it, then initializes it on selection', async () => {
const subAgent = await createAgent({
id: SUBAGENT_ID,
name: 'Explicit Subagent',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: ['web'],
stateful_code_environment: 'agent-user',
memory_scope: 'agent',
});
await grantView(subAgent);
const primaryConfig = makePrimaryConfig({
subagents: { enabled: true, allowSelf: true, agent_ids: [SUBAGENT_ID] },
});
const subagentConfig = makeSubagentConfig(SUBAGENT_ID);
let call = 0;
let subagentConvoFileIds;
mockInitializeAgent.mockImplementation(async (params, dbDeps) => {
call += 1;
if (call === 1) {
return primaryConfig;
}
subagentConvoFileIds = await dbDeps.getConvoFiles(params.conversationId);
return subagentConfig;
});
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
expect(agentClientArgs.agent.lazySubagentConfigs).toHaveLength(1);
expect(agentClientArgs.agent.lazySubagentConfigs[0]).toEqual(
expect.objectContaining({
id: SUBAGENT_ID,
configId: expect.any(String),
statefulCodeEnvironment: 'agent-user',
memory_scope: 'agent',
memoryToolsRegistered: false,
skillAuthoringAvailable: false,
historicalToolNames: ['web'],
}),
);
expect(agentClientArgs.agent.lazySubagentConfigs[0]).not.toHaveProperty('tools');
expect(agentClientArgs.agent.lazySubagentConfigs[0]).not.toHaveProperty('tool_resources');
expect(agentClientArgs.agent.lazySubagentConfigs[0]).not.toHaveProperty('_id');
await agentClientArgs.agent.lazySubagentConfigs[0].resolve({
signal: new AbortController().signal,
});
expect(mockInitializeAgent).toHaveBeenCalledTimes(2);
const subagentDbDeps = mockInitializeAgent.mock.calls[1][1];
expect(subagentDbDeps.getConvoFiles).toBeInstanceOf(Function);
expect(subagentDbDeps.db).toBeUndefined();
expect(subagentConvoFileIds).toEqual([]);
/** Subagent-only agents must NOT appear in `agentConfigs` — otherwise the
* graph would treat them as a parallel/handoff node. */
expect(agentClientArgs.agentConfigs).toBeDefined();
expect(agentClientArgs.agentConfigs.has(SUBAGENT_ID)).toBe(false);
});
it.each(['ask', 'chat', 'always', 'allow', undefined])(
'retains server-only lazy approval admission for %s without initializing the child',
async (mode) => {
const toolName = 'query_mcp_fixture';
const child = await createAgent({
id: SUBAGENT_ID,
name: 'Review-capable child',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: [toolName],
tool_options: {
[toolName]: {
approval_mode: mode,
approval_revision: 'c09e8bb4-00fa-41be-90ca-f53f1a0c1f05',
},
},
});
await grantView(child);
mockInitializeAgent.mockResolvedValue(
makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },
}),
);
const req = makeSubagentReq();
req.config.endpoints.agents.capabilities.push('tools');
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
const { canAgentGraphPause } = jest.requireActual('@librechat/api');
const policy = { enabled: true, mode: 'bypass' };
expect(canAgentGraphPause({ policy, agents: [agentClientArgs.agent] })).toBe(
mode != null && mode !== 'allow',
);
expect(
canAgentGraphPause({
policy: { ...policy, deny: [toolName] },
agents: [agentClientArgs.agent],
}),
).toBe(false);
expect(
canAgentGraphPause({
policy: { ...policy, enabled: false },
agents: [agentClientArgs.agent],
}),
).toBe(false);
const descriptor = agentClientArgs.agent.lazySubagentConfigs[0];
expect(descriptor).not.toHaveProperty('tool_options');
expect(descriptor).not.toHaveProperty('tools');
expect(JSON.stringify(descriptor)).not.toContain('approval_revision');
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
},
);
it.each([[[]], [['other_mcp_fixture']]])(
'does not let deselected lazy modes block admission with tools=%j',
async (tools) => {
const child = await createAgent({
id: SUBAGENT_ID,
name: 'Inactive review option',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools,
tool_options: { query_mcp_fixture: { approval_mode: 'ask' } },
});
await grantView(child);
mockInitializeAgent.mockResolvedValue(
makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },
}),
);
const req = makeSubagentReq();
req.config.endpoints.agents.capabilities.push('tools');
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(
jest.requireActual('@librechat/api').canAgentGraphPause({
policy: { enabled: true, mode: 'bypass' },
agents: [agentClientArgs.agent],
}),
).toBe(false);
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
},
);
it.each([
['query_mcp_db', 'db_query_mcp_db', ['db'], true],
['query_mcp_DB', 'db_query_mcp_DB', ['DB'], true],
['query_mcp_db ops', 'db_ops_query_mcp_db_ops', ['db ops'], true],
[`${Constants.mcp_all}${Constants.mcp_delimiter}db`, 'read_mcp_other', ['db', 'other'], false],
[
`${Constants.mcp_all}${Constants.mcp_delimiter}db`,
'read_mcp_other_mcp_db',
['db', 'other_mcp_db'],
false,
],
[
`${Constants.mcp_all}${Constants.mcp_delimiter}db ops`,
'read_mcp_db_ops',
['db ops', 'other'],
true,
],
[
`${Constants.mcp_all}${Constants.mcp_delimiter}Finance_mcp_EU`,
'get_mcp_version_mcp_Finance_mcp_EU',
['Finance_mcp_EU'],
true,
],
[
`${Constants.mcp_all}${Constants.mcp_delimiter}db_ops`,
'read_mcp_db ops',
['db_ops', 'db ops'],
false,
],
])(
'classifies real lazy spellings and wildcard scope before resolution: %s / %s',
async (selected, option, servers, expected) => {
const child = await createAgent({
id: SUBAGENT_ID,
name: 'Scoped review child',
provider: 'openai',
model: 'gpt-4',
author: testUser._id,
tools: [selected],
tool_options: { [option]: { approval_mode: 'ask' } },
});
await grantView(child);
mockGetAccessibleMcpServerNames.mockResolvedValue(servers);
mockInitializeAgent.mockResolvedValue(
makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },
}),
);
const req = makeSubagentReq();
req.config.endpoints.agents.capabilities.push('tools');
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
const descriptor = agentClientArgs.agent.lazySubagentConfigs[0];
const { canAgentGraphPause } = jest.requireActual('@librechat/api');
expect(
canAgentGraphPause({
policy: { enabled: true, mode: 'bypass' },
agents: [agentClientArgs.agent],
}),
).toBe(expected);
expect(descriptor).not.toHaveProperty('mcpToolAliases');
expect(descriptor).not.toHaveProperty('tool_options');
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
},
);
it.each(['ask', 'chat', 'always'])(
'disabled MCP capability excludes real saved lazy selections before delegation: %s',
async (mode) => {
const child = await createAgent({
id: SUBAGENT_ID,
name: 'Disabled MCP child',
provider: 'openai',
model: 'gpt-4',
author: testUser._id,
tools: ['query_mcp_fixture'],
tool_options: { query_mcp_fixture: { approval_mode: mode } },
});
await grantView(child);
mockInitializeAgent.mockResolvedValue(
makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },
}),
);
const { canAgentGraphPause } = jest.requireActual('@librechat/api');
for (const enabled of [false, true]) {
const req = makeSubagentReq();
if (enabled) req.config.endpoints.agents.capabilities.push('tools');
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(
canAgentGraphPause({
policy: { enabled: true, mode: 'bypass' },
agents: [agentClientArgs.agent],
}),
).toBe(enabled);
expect(agentClientArgs.agent.lazySubagentConfigs[0]).not.toHaveProperty('tool_options');
}
expect(mockInitializeAgent).toHaveBeenCalledTimes(2);
},
);
it('requires durable approval for a real unresolved lazy legacy selection', async () => {
const child = await createAgent({
id: SUBAGENT_ID,
name: 'Unresolved legacy selection',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: ['fixture_query_mcp_fixture'],
tool_options: { query_mcp_fixture: { approval_mode: 'chat' } },
});
await grantView(child);
mockInitializeAgent.mockResolvedValue(
makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },
}),
);
const req = makeSubagentReq();
req.config.endpoints.agents.capabilities.push('tools');
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(
jest.requireActual('@librechat/api').canAgentGraphPause({
policy: { enabled: true, mode: 'bypass' },
agents: [agentClientArgs.agent],
}),
).toBe(true);
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
expect(agentClientArgs.agent.lazySubagentConfigs[0]).not.toHaveProperty('mcpToolAliases');
});
it('retains review capability through nested lazy descriptors before delegation', async () => {
const leafId = 'approval-lazy-leaf';
await createViewableAgent(SUBAGENT_ID, {
enabled: true,
allowSelf: false,
agent_ids: [leafId],
});
const leaf = await createAgent({
id: leafId,
name: 'Approval leaf',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: ['query_mcp_fixture'],
tool_options: { query_mcp_fixture: { approval_mode: 'chat' } },
});
await grantView(leaf);
mockInitializeAgent.mockResolvedValue(
makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },
}),
);
const req = makeSubagentReq();
req.config.endpoints.agents.capabilities.push('tools');
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(
jest.requireActual('@librechat/api').canAgentGraphPause({
policy: { enabled: true, mode: 'bypass' },
agents: [agentClientArgs.agent],
}),
).toBe(true);
expect(agentClientArgs.agent.lazySubagentConfigs[0].lazySubagentConfigs[0]).not.toHaveProperty(
'tool_options',
);
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
});
it('classifies unresolved lazy graph-member review modes before selecting the parent', async () => {
const memberId = 'approval-lazy-graph-member';
await createViewableAgent(SUBAGENT_ID, {
enabled: true,
allowSelf: false,
graphs: [
{
type: 'review_team',
name: 'Review team',
agent_ids: [SUBAGENT_ID, memberId],
edges: [{ from: SUBAGENT_ID, to: memberId, edgeType: 'direct' }],
entry_agent_id: SUBAGENT_ID,
result_agent_id: memberId,
},
],
});
const member = await createAgent({
id: memberId,
name: 'Approval graph member',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: [`${Constants.mcp_all}${Constants.mcp_delimiter}fixture`],
tool_options: { query_mcp_fixture: { approval_mode: 'always' } },
});
await grantView(member);
mockInitializeAgent.mockResolvedValue(
makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },
}),
);
const req = makeSubagentReq();
req.config.endpoints.agents.capabilities.push('tools');
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
const metadata = agentClientArgs.agent.lazySubagentConfigs[0].subagentGraphMemberMetadata[0];
expect(metadata.id).toBe(memberId);
expect(metadata).not.toHaveProperty('tool_options');
expect(
jest.requireActual('@librechat/api').canAgentGraphPause({
policy: { enabled: true, mode: 'bypass' },
agents: [agentClientArgs.agent],
}),
).toBe(true);
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
});
it.each([
['db_query_mcp_DB', 'query_mcp_DB', 'DB'],
['db_ops_query_mcp_db ops', 'query_mcp_db_ops', 'db ops'],
['db_ops_query_mcp_db_ops', 'query_mcp_db ops', 'db ops'],
])(
'classifies a real normalized lazy selection before resolution: %s',
async (selected, current, raw) => {
const child = await createAgent({
id: SUBAGENT_ID,
name: 'Normalized review selection',
provider: 'openai',
model: 'gpt-4',
author: testUser._id,
tools: [selected],
tool_options: { [current]: { approval_mode: 'chat' } },
});
await grantView(child);
mockGetAccessibleMcpServerNames.mockResolvedValue([raw]);
mockInitializeAgent.mockResolvedValue(
makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },
}),
);
const req = makeSubagentReq();
req.config.endpoints.agents.capabilities.push('tools');
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(
jest.requireActual('@librechat/api').canAgentGraphPause({
policy: { enabled: true, mode: 'bypass' },
agents: [agentClientArgs.agent],
}),
).toBe(true);
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
expect(agentClientArgs.agent.lazySubagentConfigs[0]).not.toHaveProperty('mcpToolAliases');
expect(agentClientArgs.agent.lazySubagentConfigs[0]).not.toHaveProperty('tool_options');
},
);
it.each([
'active',
'disabled-skills',
'disabled-tools',
'agent-opt-out',
'inactive',
'out-of-scope',
'deselected',
'raw-key',
])('uses the real gated skill-only lazy surface for admission: %s', async (state) => {
const current = 'query_mcp_db_ops';
const { skill } = await createSkill({
name: 'approval-skill',
description: 'Adds a reviewed query.',
body: '# Approval query\n',
alwaysApply: true,
frontmatter: { 'allowed-tools': [state === 'raw-key' ? 'db_ops_query_mcp_db ops' : current] },
author: testUser._id,
authorName: testUser.name,
});
await AclEntry.create({
principalType: PrincipalType.USER,
principalId: testUser._id,
principalModel: PrincipalModel.USER,
resourceType: ResourceType.SKILL,
resourceId: skill._id,
permBits: PermissionBits.VIEW,
grantedBy: testUser._id,
});
const child = await createAgent({
id: SUBAGENT_ID,
name: 'Skill-only review selection',
provider: 'openai',
model: 'gpt-4',
author: testUser._id,
tools: [],
skills_enabled: state !== 'agent-opt-out',
skills: [
state === 'out-of-scope' ? new mongoose.Types.ObjectId().toString() : skill._id.toString(),
],
tool_options: {
[state === 'deselected' ? 'other_mcp_db_ops' : current]: { approval_mode: 'ask' },
},
});
await grantView(child);
if (state === 'inactive')
await User.updateOne(
{ _id: testUser._id },
{ $set: { skillStates: { [skill._id.toString()]: false } } },
);
mockGetAccessibleMcpServerNames.mockResolvedValue(['db ops']);
mockInitializeAgent.mockResolvedValue(
makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },
}),
);
const req = makeSubagentReq();
if (state !== 'disabled-skills') req.config.endpoints.agents.capabilities.push('skills');
if (state !== 'disabled-tools') req.config.endpoints.agents.capabilities.push('tools');
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(
jest.requireActual('@librechat/api').canAgentGraphPause({
policy: { enabled: true, mode: 'bypass' },
agents: [agentClientArgs.agent],
}),
).toBe(state === 'active' || state === 'raw-key');
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
expect(agentClientArgs.agent.lazySubagentConfigs[0]).not.toHaveProperty('tools');
expect(agentClientArgs.agent.lazySubagentConfigs[0]).not.toHaveProperty('tool_options');
});
it('includes current always-apply Skill revisions in lazy descriptor metadata', async () => {
const secondSubagentId = 'agent_subagent_skill_2';
const { skill } = await createSkill({
name: 'lazy-specialist',
description: 'Prime a lazy specialist.',
body: '# Lazy specialist v1\n',
alwaysApply: true,
author: testUser._id,
authorName: testUser.name,
});
await AclEntry.create({
principalType: PrincipalType.USER,
principalId: testUser._id,
principalModel: PrincipalModel.USER,
resourceType: ResourceType.SKILL,
resourceId: skill._id,
permBits: PermissionBits.VIEW,
grantedBy: testUser._id,
});
const subAgent = await createAgent({
id: SUBAGENT_ID,
name: 'Skill Subagent',
provider: 'openai',
model: 'gpt-4',
author: testUser._id,
tools: [],
skills_enabled: true,
skills: [skill._id.toString()],
});
await grantView(subAgent);
const secondSubAgent = await createAgent({
id: secondSubagentId,
name: 'Second Skill Subagent',
provider: 'openai',
model: 'gpt-4',
author: testUser._id,
tools: [],
skills_enabled: true,
skills: [skill._id.toString()],
});
await grantView(secondSubAgent);
mockInitializeAgent.mockResolvedValue(
makePrimaryConfig({
subagents: {
enabled: true,
allowSelf: true,
agent_ids: [SUBAGENT_ID, secondSubagentId],
},
}),
);
const req = makeSubagentReq();
req.config.endpoints.agents.capabilities.push('skills');
const listAlwaysApplySkillsSpy = jest.spyOn(getSkillDbMethods(), 'listAlwaysApplySkills');
try {
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
expect(listAlwaysApplySkillsSpy).toHaveBeenCalledTimes(1);
for (const descriptor of agentClientArgs.agent.lazySubagentConfigs) {
expect(descriptor.alwaysApplySkillPrimes).toEqual([
expect.objectContaining({
_id: skill._id,
name: 'lazy-specialist',
version: 1,
body: '# Lazy specialist v1\n',
}),
]);
expect(descriptor.historicalToolNames).toEqual(
expect.arrayContaining(['skill', 'read_file']),
);
}
const eventReq = makeSubagentReq();
eventReq.config.endpoints.agents.capabilities.push('skills');
eventReq._isAgentTrigger = true;
eventReq._agentEventBindingParentConversationId = 'parent-conversation';
await initializeClient({
req: eventReq,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(mockInitializeAgent).toHaveBeenCalledTimes(2);
expect(listAlwaysApplySkillsSpy).toHaveBeenCalledTimes(2);
expect(agentClientArgs.agent.lazySubagentConfigs).toHaveLength(2);
for (const descriptor of agentClientArgs.agent.lazySubagentConfigs) {
expect(descriptor.alwaysApplySkillPrimes).toEqual([
expect.objectContaining({
_id: skill._id,
name: 'lazy-specialist',
version: 1,
body: '# Lazy specialist v1\n',
}),
]);
expect(descriptor.historicalToolNames).toEqual(
expect.arrayContaining(['skill', 'read_file']),
);
}
} finally {
listAlwaysApplySkillsSpy.mockRestore();
}
});
it('loads independent lazy Skill scopes concurrently', async () => {
const secondSubagentId = 'agent_subagent_parallel_skill_2';
const skills = [];
for (const name of ['parallel-skill-one', 'parallel-skill-two']) {
const { skill } = await createSkill({
name,
description: `${name} description`,
body: `# ${name}\n`,
alwaysApply: true,
author: testUser._id,
authorName: testUser.name,
});
await AclEntry.create({
principalType: PrincipalType.USER,
principalId: testUser._id,
principalModel: PrincipalModel.USER,
resourceType: ResourceType.SKILL,
resourceId: skill._id,
permBits: PermissionBits.VIEW,
grantedBy: testUser._id,
});
skills.push(skill);
}
for (const [id, skill] of [
[SUBAGENT_ID, skills[0]],
[secondSubagentId, skills[1]],
]) {
const agent = await createAgent({
id,
name: id,
provider: 'openai',
model: 'gpt-4',
author: testUser._id,
tools: [],
skills_enabled: true,
skills: [skill._id.toString()],
});
await grantView(agent);
}
mockInitializeAgent.mockResolvedValue(
makePrimaryConfig({
subagents: {
enabled: true,
allowSelf: false,
agent_ids: [SUBAGENT_ID, secondSubagentId],
},
}),
);
const req = makeSubagentReq();
req.config.endpoints.agents.capabilities.push('skills');
const skillDbMethods = getSkillDbMethods();
const listAlwaysApplySkills = skillDbMethods.listAlwaysApplySkills.bind(skillDbMethods);
let activeQueries = 0;
let maxActiveQueries = 0;
const bothQueriesStarted = deferred();
const waitForBothQueries = async () => {
let timer;
await Promise.race([
bothQueriesStarted.promise,
new Promise((resolve) => {
timer = setTimeout(resolve, 1000);
}),
]);
clearTimeout(timer);
};
const listAlwaysApplySkillsSpy = jest
.spyOn(skillDbMethods, 'listAlwaysApplySkills')
.mockImplementation(async (...args) => {
activeQueries += 1;
maxActiveQueries = Math.max(maxActiveQueries, activeQueries);
if (activeQueries === 2) {
bothQueriesStarted.resolve();
}
await waitForBothQueries();
try {
return await listAlwaysApplySkills(...args);
} finally {
activeQueries -= 1;
}
});
try {
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(listAlwaysApplySkillsSpy).toHaveBeenCalledTimes(2);
expect(maxActiveQueries).toBe(2);
expect(agentClientArgs.agent.lazySubagentConfigs).toHaveLength(2);
} finally {
listAlwaysApplySkillsSpy.mockRestore();
}
});
it('bounds concurrent lazy metadata reads', async () => {
const subagentIds = Array.from({ length: 6 }, (_, index) => `agent_bounded_lazy_${index}`);
for (const id of subagentIds) {
await createViewableAgent(id);
}
mockInitializeAgent.mockResolvedValue(
makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: subagentIds },
}),
);
const originalGetAgent = db.getAgentWithVersionCount.bind(db);
const fourReadsStarted = deferred();
let activeReads = 0;
let maxActiveReads = 0;
const getAgentSpy = jest
.spyOn(db, 'getAgentWithVersionCount')
.mockImplementation(async (...args) => {
activeReads += 1;
maxActiveReads = Math.max(maxActiveReads, activeReads);
if (activeReads === 4) {
fourReadsStarted.resolve();
}
let timer;
await Promise.race([
fourReadsStarted.promise,
new Promise((resolve) => {
timer = setTimeout(resolve, 1000);
}),
]);
clearTimeout(timer);
try {
return await originalGetAgent(...args);
} finally {
activeReads -= 1;
}
});
try {
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(agentClientArgs.agent.lazySubagentConfigs).toHaveLength(subagentIds.length);
expect(maxActiveReads).toBe(4);
} finally {
getAgentSpy.mockRestore();
}
});
it('rejects a disallowed lazy subagent scope before exposing it for prewarm', async () => {
const subAgent = await createAgent({
id: SUBAGENT_ID,
name: 'Disallowed Stateful Subagent',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: ['execute_code'],
stateful_code_sessions: true,
stateful_code_environment: 'conversation',
});
await grantView(subAgent);
mockInitializeAgent.mockResolvedValue(
makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },
}),
);
const req = makeSubagentReq();
req.config.endpoints.agents.capabilities.push('execute_code', 'stateful_code_sessions');
req.config.endpoints.agents.statefulCodeSessions = { allowedEnvironments: ['user'] };
process.env.CODE_ENVIRONMENT_DECISION_VERSION = '1';
process.env.LIBRECHAT_CODE_BASEURL_STATEFUL = 'https://stateful-code.example.com/v1/';
try {
await expect(
initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
}),
).rejects.toMatchObject({
code: ErrorTypes.STATEFUL_CODE_ENVIRONMENT_NOT_ALLOWED,
});
expect(agentClientArgs).toBeUndefined();
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
} finally {
delete process.env.CODE_ENVIRONMENT_DECISION_VERSION;
delete process.env.LIBRECHAT_CODE_BASEURL_STATEFUL;
}
});
it('binds a versioned implicit stateful route into lazy subagent metadata', async () => {
const subAgent = await createAgent({
id: SUBAGENT_ID,
name: 'Implicit Stateful Subagent',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: ['execute_code'],
stateful_code_sessions: true,
stateful_code_environment: 'user',
});
await grantView(subAgent);
mockInitializeAgent.mockResolvedValue(
makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },
}),
);
const req = makeSubagentReq();
req.body.codeEnvironmentMode = 'without_attached';
req.config.endpoints.agents.capabilities.push('execute_code', 'stateful_code_sessions');
req.config.endpoints.agents.statefulCodeSessions = { allowedEnvironments: ['user'] };
process.env.CODE_ENVIRONMENT_DECISION_VERSION = '1';
process.env.LIBRECHAT_CODE_BASEURL_STATEFUL = 'https://stateful-code.example.com/v1/';
try {
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(agentClientArgs.agent.lazySubagentConfigs[0]).toEqual(
expect.objectContaining({
codeExecutionContext: expect.objectContaining({
baseUrl: 'https://stateful-code.example.com/v1',
executionProfile: 'stateful',
statefulSessions: true,
}),
}),
);
} finally {
delete process.env.CODE_ENVIRONMENT_DECISION_VERSION;
delete process.env.LIBRECHAT_CODE_BASEURL_STATEFUL;
}
});
it('forwards the initializer code opt-out through the tool loader', async () => {
const codeExecutionContext = {
baseUrl: 'https://api.librechat.ai/v1',
codeSessionKey: 'execute_code',
executionProfile: 'default',
statefulSessions: false,
};
mockInitializeAgent.mockImplementationOnce(async (params) => {
await params.loadTools({
agentId: PRIMARY_ID,
tools: ['execute_code'],
codeExecutionContext,
attachedEnvironmentOptOut: true,
});
return makePrimaryConfig({});
});
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(loadAgentTools).toHaveBeenCalledWith(
expect.objectContaining({ codeExecutionContext, attachedEnvironmentOptOut: true }),
);
});
it('keeps a lazy subagent off its attached machine in a conversation that chose no workspace', async () => {
const subAgent = await createAgent({
id: SUBAGENT_ID,
name: 'Attached Default Subagent',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: ['execute_code'],
stateful_code_sessions: true,
stateful_code_environment: 'agent-user',
code_environment_id: 'attached-vm',
code_environment_ids: ['other-vm'],
});
await grantView(subAgent);
mockInitializeAgent.mockResolvedValue(
makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },
}),
);
const attachedVm = (id) => ({
id,
name: id,
type: 'attached',
owner: 'deployment',
workerId: `${id}-worker`,
baseURL: 'https://bridge.example.com/v1/',
});
const req = makeSubagentReq();
req.body.codeEnvironmentMode = 'without_attached';
req.config.endpoints.agents.capabilities.push('execute_code', 'stateful_code_sessions');
req.config.endpoints.agents.statefulCodeSessions = {
allowedEnvironments: ['agent-user'],
allowEnvironmentSelection: true,
environments: [attachedVm('attached-vm'), attachedVm('other-vm')],
};
const fetchSpy = jest.spyOn(globalThis, 'fetch');
try {
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
const descriptor = agentClientArgs.agent.lazySubagentConfigs[0];
expect(descriptor).toEqual(
expect.objectContaining({
codeEnvAvailable: false,
statefulCodeSessions: false,
codeExecutionContext: undefined,
subagentHostArgs: undefined,
codeExecutionChoices: undefined,
}),
);
expect(descriptor.description ?? '').not.toContain('Unavailable in this conversation');
const initCalls = mockInitializeAgent.mock.calls.length;
await expect(
descriptor.resolve({
signal: new AbortController().signal,
hostArgs: { machine: 'other-vm' },
}),
).rejects.toThrow(/rejected/);
expect(mockInitializeAgent).toHaveBeenCalledTimes(initCalls);
mockInitializeAgent.mockResolvedValueOnce(makeSubagentConfig(SUBAGENT_ID));
await descriptor.resolve({ signal: new AbortController().signal });
const childInit = mockInitializeAgent.mock.calls.at(-1)[0];
expect(childInit.agent.code_environment_id).toBe('attached-vm');
expect(childInit.requestBody).toEqual(
expect.objectContaining({ codeEnvironmentMode: 'without_attached' }),
);
expect(
mockInitializeAgent.mock.calls.some(
([params]) => params.agent?.code_environment_id === 'other-vm',
),
).toBe(false);
expect(fetchSpy).not.toHaveBeenCalled();
} finally {
fetchSpy.mockRestore();
}
});
it.each([
[true, 'request', false],
[false, 'request', false],
[true, 'fallback', false],
[true, 'override', false],
[true, 'override-resolved', false],
[true, 'resolved', false],
[true, 'moved', true],
[true, 'inaccessible-choice', false],
[false, 'resolved-null', false],
[true, 'resolved-null', true],
[false, 'other-owner', false],
])(
'validates the lazy subagent workspace before exposure: registered=%s source=%s moves=%s',
async (registered, source, movesEnabled) => {
const subAgent = await createAgent({
id: SUBAGENT_ID,
name: 'Attached Stateful Subagent',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: ['execute_code'],
stateful_code_sessions: true,
stateful_code_environment: 'agent-user',
code_environment_id: 'attached-vm',
});
await grantView(subAgent);
mockInitializeAgent.mockResolvedValue(
makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },
}),
);
const req = makeSubagentReq();
req.config.endpoints.agents.capabilities.push('execute_code', 'stateful_code_sessions');
req.config.endpoints.agents.statefulCodeSessions = {
allowedEnvironments: ['agent-user'],
conversationMoves: { enabled: movesEnabled },
environments: [
{
id: 'attached-vm',
name: 'Attached VM',
type: 'attached',
owner: 'deployment',
pairing: { workerId: 'lazy-worker', tokenEnv: 'TEST_LAZY_WORKSPACE_TOKEN' },
baseURL: 'https://bridge.example.com/v1/',
default: true,
},
],
};
req.body.codeWorkspaces = [{ environmentId: 'attached-vm', workspaceId: 'project-b' }];
if (source === 'inaccessible-choice') {
req.config.endpoints.agents.statefulCodeSessions.allowEnvironmentSelection = true;
await db.updateAgent({ id: SUBAGENT_ID }, { code_environment_ids: ['unavailable-vm'] });
req.body.codeWorkspaces = [{ environmentId: 'unavailable-vm', workspaceId: 'project-b' }];
}
if (source === 'request' && !registered) {
req.body.codeWorkspaces[0].workspaceId = 'removed-project';
}
let requestBody;
if (source !== 'request') {
const conversation = await mongoose.model('Conversation').create({
conversationId: req.body.conversationId,
endpoint: 'agents',
user: source === 'other-owner' ? new mongoose.Types.ObjectId().toString() : req.user.id,
codeWorkspaces: req.body.codeWorkspaces,
});
delete req.body.codeWorkspaces;
if (source === 'moved') {
req.resolvedConversation = {
...conversation.toObject(),
codeWorkspaces: [{ environmentId: 'old-machine', workspaceId: 'old-project' }],
};
} else if (source === 'resolved') req.resolvedConversation = conversation.toObject();
else if (source !== 'resolved-null') delete req.resolvedConversation;
if (source.startsWith('override')) {
conversation.codeWorkspaces = [
{ environmentId: 'attached-vm', workspaceId: 'wrong-source' },
];
await conversation.save();
if (source === 'override-resolved') req.resolvedConversation = conversation.toObject();
requestBody = { ...req.body, conversationId: 'effective-target' };
await mongoose.model('Conversation').create({
conversationId: requestBody.conversationId,
endpoint: 'agents',
user: req.user.id,
codeWorkspaces: [{ environmentId: 'attached-vm', workspaceId: 'project-b' }],
});
}
}
mockGetAppConfig.mockResolvedValue(req.config);
process.env.TEST_LAZY_WORKSPACE_TOKEN = 'test-token';
const fetchSpy = jest.spyOn(globalThis, 'fetch').mockResolvedValue(
new Response(
JSON.stringify({
protocolVersion: 1,
workerId: 'lazy-worker',
online: true,
ready: true,
leaseExpiresInMs: 45000,
capabilities: {
statefulWorkspace: true,
sandboxProfile: 'native-srt',
runtimes: ['bash'],
workspaceTools: {
protocolVersion: 1,
operations: ['read_file'],
workspaces: [{ id: 'project-b' }],
},
},
}),
),
);
const readSpy = jest.spyOn(db, 'readAdmittedConvoCodeEnvironmentDecision');
try {
const initialization = initializeClient({
req,
requestBody,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
const defaultsWithoutAttached =
source === 'other-owner' || (source === 'resolved-null' && !movesEnabled);
if ((!registered && !defaultsWithoutAttached) || source === 'inaccessible-choice') {
/** The parent's turn proceeds; the subagent is advertised as unable to run instead. */
await initialization;
const descriptor = agentClientArgs.agent.lazySubagentConfigs[0];
const reason = source === 'inaccessible-choice' ? 'invalid' : 'missing';
expect(descriptor).toEqual(
expect.objectContaining({
codeEnvAvailable: false,
statefulCodeSessions: false,
codeExecutionContext: undefined,
description: expect.stringContaining('Unavailable in this conversation'),
}),
);
await expect(
descriptor.resolve({ signal: new AbortController().signal }),
).rejects.toMatchObject({ code: ErrorTypes.CODE_WORKSPACE_UNAVAILABLE, reason });
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
return;
}
await initialization;
if (movesEnabled)
expect(readSpy).toHaveBeenCalledWith(
req.user.id,
requestBody?.conversationId ?? req.body.conversationId,
);
else expect(readSpy).not.toHaveBeenCalled();
if (defaultsWithoutAttached) {
expect(fetchSpy).not.toHaveBeenCalled();
expect(agentClientArgs.mcpRequestBody).toEqual(
expect.objectContaining({ codeEnvironmentMode: 'without_attached' }),
);
return;
}
if (source === 'fallback' || source.startsWith('override')) {
mockInitializeAgent.mockImplementationOnce(async (params) => {
expect(params.req.resolvedConversation.codeWorkspaces).toEqual([
{ environmentId: 'attached-vm', workspaceId: 'project-b' },
]);
await params.loadTools({ ...subAgent, agentId: SUBAGENT_ID });
return makeSubagentConfig(SUBAGENT_ID);
});
await agentClientArgs.agent.lazySubagentConfigs[0].resolve({
signal: new AbortController().signal,
});
expect(loadAgentTools).toHaveBeenLastCalledWith(
expect.objectContaining({
req: expect.objectContaining({
resolvedConversation: expect.objectContaining({
codeWorkspaces: [{ environmentId: 'attached-vm', workspaceId: 'project-b' }],
}),
}),
}),
);
}
} finally {
fetchSpy.mockRestore();
readSpy.mockRestore();
delete process.env.TEST_LAZY_WORKSPACE_TOKEN;
}
expect(agentClientArgs.agent.lazySubagentConfigs[0]).toEqual(
expect.objectContaining({
codeSessionKey: expect.stringMatching(/^execute_code:stateful:[a-f0-9]{32}:v3:/),
codeExecutionContext: expect.objectContaining({
baseUrl: 'https://bridge.example.com/v1',
environmentId: 'attached-vm',
environmentType: 'attached',
codeWorkspace: {
environmentId: 'attached-vm',
workspaceId: 'project-b',
operations: ['read_file'],
},
executionProfile: 'stateful',
executionRouteKey: expect.stringMatching(/^stateful:[a-f0-9]{32}$/),
}),
}),
);
},
);
describe('subagent machine inheritance', () => {
const SKYNET = 'code-skynet';
const LIA_RAG = 'code-lia-rag';
const bridgeEnvironment = (id) => ({
id,
name: id,
type: 'attached',
owner: 'deployment',
pairing: { workerId: `${id}-worker`, tokenEnv: 'TEST_INHERIT_WORKSPACE_TOKEN' },
baseURL: 'https://bridge.example.com/v1/',
});
/** Both machines are registered; each advertises the checkout it holds on demo. */
const mockWorkerStatus = () =>
jest.spyOn(globalThis, 'fetch').mockImplementation(async (url) => {
const workerId = decodeURIComponent(String(url).match(/workers\/([^/]+)\/status/)[1]);
return new Response(
JSON.stringify({
protocolVersion: 1,
workerId,
online: true,
ready: true,
leaseExpiresInMs: 45000,
capabilities: {
statefulWorkspace: true,
sandboxProfile: 'native-srt',
runtimes: ['bash'],
workspaceTools: {
protocolVersion: 1,
operations: ['read_file'],
workspaces: [{ id: workerId.startsWith(SKYNET) ? 'code-api' : 'agents' }],
},
},
}),
);
});
const setup = async ({ reviewer = {}, environments = [SKYNET, LIA_RAG] } = {}) => {
const subAgent = await createAgent({
id: SUBAGENT_ID,
name: 'PR Reviewer',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: ['execute_code'],
stateful_code_sessions: true,
stateful_code_environment: 'user',
code_environment_id: SKYNET,
code_environment_ids: [LIA_RAG],
code_workspace_id: '',
...reviewer,
});
await grantView(subAgent);
mockInitializeAgent.mockResolvedValue({
...makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },
}),
statefulCodeSessions: true,
codeExecutionContext: { environmentId: LIA_RAG, environmentType: 'attached' },
});
const req = makeSubagentReq();
req.config.endpoints.agents.capabilities.push('execute_code', 'stateful_code_sessions');
req.config.endpoints.agents.statefulCodeSessions = {
allowedEnvironments: ['user'],
environments: environments.map(bridgeEnvironment),
};
/** An older client: Lia owns her machine, the reviewer is named nowhere. */
req.body.codeEnvironmentMode = 'attached';
req.body.codeWorkspaces = [
{ environmentId: LIA_RAG, workspaceId: 'agents', agentIds: [PRIMARY_ID] },
...(environments.includes(SKYNET)
? [{ environmentId: SKYNET, workspaceId: 'code-api' }]
: []),
];
mockGetAppConfig.mockResolvedValue(req.config);
process.env.TEST_INHERIT_WORKSPACE_TOKEN = 'test-token';
return req;
};
afterEach(() => {
delete process.env.TEST_INHERIT_WORKSPACE_TOKEN;
});
/** Selects a lazy child the way the run does: the whole resolution inside its settle hook. */
const select = (descriptor, context) =>
descriptor.settle(context, () => descriptor.resolve(context));
it("routes the reviewer to its parent's machine and workspace, not its own default", async () => {
const req = await setup();
const fetchSpy = mockWorkerStatus();
try {
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
} finally {
fetchSpy.mockRestore();
}
expect(req.codeWorkspaceInheritance).toEqual(new Map([[SUBAGENT_ID, LIA_RAG]]));
expect(req.body.codeWorkspaces).toEqual([
{ environmentId: LIA_RAG, workspaceId: 'agents', agentIds: [PRIMARY_ID] },
{ environmentId: SKYNET, workspaceId: 'code-api' },
]);
expect(agentClientArgs.agent.lazySubagentConfigs[0].codeExecutionContext).toEqual(
expect.objectContaining({
environmentId: LIA_RAG,
codeWorkspace: expect.objectContaining({ environmentId: LIA_RAG, workspaceId: 'agents' }),
}),
);
mockInitializeAgent.mockImplementationOnce(async (params) => {
expect(params.req.codeWorkspaceInheritance).toBe(req.codeWorkspaceInheritance);
return makeSubagentConfig(SUBAGENT_ID);
});
await agentClientArgs.agent.lazySubagentConfigs[0].resolve({
signal: new AbortController().signal,
});
});
it('routes a reviewer to the machine its parent names and keeps it there this turn', async () => {
const req = await setup();
const fetchSpy = mockWorkerStatus();
try {
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
const descriptor = agentClientArgs.agent.lazySubagentConfigs[0];
const routedAgents = [];
mockInitializeAgent.mockImplementation(async (params) => {
routedAgents.push(params.agent);
return {
...makeSubagentConfig(SUBAGENT_ID),
codeExecutionContext: {
environmentId: params.agent.code_environment_id,
environmentType: 'attached',
},
};
});
await descriptor.resolve({
signal: new AbortController().signal,
executionId: 'run-routed',
hostArgs: { machine: SKYNET },
});
await descriptor.resolve({
signal: new AbortController().signal,
executionId: 'run-later',
});
await expect(
descriptor.resolve({
signal: new AbortController().signal,
executionId: 'run-unadmitted',
hostArgs: { machine: 'code-unadmitted' },
}),
).rejects.toThrow();
expect(routedAgents).toHaveLength(2);
expect(routedAgents[0]).toMatchObject({
id: SUBAGENT_ID,
code_environment_id: SKYNET,
code_environment_ids: [SKYNET],
});
expect(routedAgents[1]).toMatchObject({
code_environment_id: SKYNET,
code_environment_ids: [SKYNET],
});
} finally {
fetchSpy.mockRestore();
}
});
it("routes a routed reviewer's graph members to its machine when they may use it", async () => {
const req = await setup();
const member = await createAgent({
id: 'agent_graph_member',
name: 'Graph member',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: ['execute_code'],
stateful_code_sessions: true,
stateful_code_environment: 'user',
code_environment_id: LIA_RAG,
code_environment_ids: [SKYNET],
});
await grantView(member);
const fetchSpy = mockWorkerStatus();
try {
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
const descriptor = agentClientArgs.agent.lazySubagentConfigs[0];
const initialized = [];
mockInitializeAgent.mockImplementation(async (params) => {
initialized.push(params.agent);
return {
...makeSubagentConfig(params.agent.id),
...(params.agent.id === SUBAGENT_ID
? {
subagents: {
enabled: true,
allowSelf: false,
agent_ids: [],
graphs: [
{
type: 'review_team',
name: 'Review team',
description: 'Reviews together.',
agent_ids: [member.id],
edges: [],
entryAgentId: member.id,
resultAgentId: member.id,
},
],
},
}
: {}),
codeExecutionContext: {
environmentId: params.agent.code_environment_id,
environmentType: 'attached',
},
};
});
const config = await descriptor.resolve({
signal: new AbortController().signal,
executionId: 'run-routed-graph',
hostArgs: { machine: SKYNET },
});
expect(initialized.map((agent) => [agent.id, agent.code_environment_id])).toEqual([
[SUBAGENT_ID, SKYNET],
[member.id, SKYNET],
]);
expect(initialized[1].code_environment_ids).toEqual([SKYNET]);
expect(config.subagentGraphConfigs?.[0]?.memberConfigs?.[0]?.id).toBe(member.id);
} finally {
fetchSpy.mockRestore();
}
});
it('gives back the machine of a failed initialization so a retry may name another', async () => {
const req = await setup();
const fetchSpy = mockWorkerStatus();
try {
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
const descriptor = agentClientArgs.agent.lazySubagentConfigs[0];
mockInitializeAgent.mockRejectedValueOnce(new Error('tools failed to load'));
mockInitializeAgent.mockImplementation(async (params) => ({
...makeSubagentConfig(SUBAGENT_ID),
codeExecutionContext: {
environmentId: params.agent.code_environment_id,
environmentType: 'attached',
},
}));
await expect(
descriptor.resolve({ signal: new AbortController().signal, executionId: 'run-failed' }),
).rejects.toThrow('tools failed to load');
const config = await descriptor.resolve({
signal: new AbortController().signal,
executionId: 'run-retry',
hostArgs: { machine: SKYNET },
});
expect(config.codeExecutionContext.environmentId).toBe(SKYNET);
} finally {
fetchSpy.mockRestore();
}
});
it('gives back a routed reviewer\u2019s machine when its graph resolution is canceled', async () => {
const req = await setup();
const member = await createAgent({
id: 'agent_graph_member',
name: 'Graph member',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: ['execute_code'],
stateful_code_sessions: true,
stateful_code_environment: 'user',
code_environment_id: LIA_RAG,
code_environment_ids: [SKYNET],
});
await grantView(member);
const fetchSpy = mockWorkerStatus();
try {
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
const descriptor = agentClientArgs.agent.lazySubagentConfigs[0];
let memberStarted;
const started = new Promise((resolve) => {
memberStarted = resolve;
});
let memberLoads = 0;
mockInitializeAgent.mockImplementation(async (params) => {
if (params.agent.id === member.id && memberLoads++ === 0) {
memberStarted();
await new Promise(() => {});
}
return {
...makeSubagentConfig(params.agent.id),
...(params.agent.id === SUBAGENT_ID
? {
subagents: {
enabled: true,
allowSelf: false,
agent_ids: [],
graphs: [
{
type: 'review_team',
name: 'Review team',
description: 'Reviews together.',
agent_ids: [member.id],
edges: [],
entryAgentId: member.id,
resultAgentId: member.id,
},
],
},
}
: {}),
codeExecutionContext: {
environmentId: params.agent.code_environment_id,
environmentType: 'attached',
},
};
});
const controller = new AbortController();
const canceled = select(descriptor, {
signal: controller.signal,
executionId: 'run-canceled',
hostArgs: { machine: SKYNET },
});
await started;
controller.abort();
await expect(canceled).rejects.toBeDefined();
const config = await select(descriptor, {
signal: new AbortController().signal,
executionId: 'run-retry',
hostArgs: { machine: LIA_RAG },
});
expect(config.codeExecutionContext.environmentId).toBe(LIA_RAG);
} finally {
fetchSpy.mockRestore();
}
});
it('does not reuse the config of a resolution whose graph failed', async () => {
const req = await setup();
const member = await createAgent({
id: 'agent_graph_member',
name: 'Graph member',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: ['execute_code'],
stateful_code_sessions: true,
stateful_code_environment: 'user',
code_environment_id: LIA_RAG,
code_environment_ids: [SKYNET],
});
await grantView(member);
const fetchSpy = mockWorkerStatus();
try {
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
const descriptor = agentClientArgs.agent.lazySubagentConfigs[0];
let memberStarted;
const started = new Promise((resolve) => {
memberStarted = resolve;
});
let memberLoads = 0;
mockInitializeAgent.mockImplementation(async (params) => {
if (params.agent.id === member.id && memberLoads++ === 0) {
memberStarted();
await new Promise(() => {});
}
return {
...makeSubagentConfig(params.agent.id),
...(params.agent.id === SUBAGENT_ID
? {
subagents: {
enabled: true,
allowSelf: false,
agent_ids: [],
graphs: [
{
type: 'review_team',
name: 'Review team',
description: 'Reviews together.',
agent_ids: [SUBAGENT_ID, member.id],
edges: [],
entryAgentId: SUBAGENT_ID,
resultAgentId: member.id,
},
],
},
}
: {}),
codeExecutionContext: {
environmentId: params.agent.code_environment_id,
environmentType: 'attached',
},
};
});
const controller = new AbortController();
const canceled = select(descriptor, {
signal: controller.signal,
executionId: 'run-canceled',
});
await started;
controller.abort();
await expect(canceled).rejects.toBeDefined();
const config = await select(descriptor, {
signal: new AbortController().signal,
executionId: 'run-retry',
hostArgs: { machine: LIA_RAG },
});
const graphReviewer = config.subagentGraphConfigs?.[0]?.memberConfigs?.find(
(memberConfig) => memberConfig.id === SUBAGENT_ID,
);
expect(config.codeExecutionContext.environmentId).toBe(LIA_RAG);
expect(graphReviewer?.codeExecutionContext.environmentId).toBe(LIA_RAG);
} finally {
fetchSpy.mockRestore();
}
});
it('shares a lazy child config with later graphs only once its selection commits', async () => {
const req = await setup();
const member = await createAgent({
id: 'agent_graph_member',
name: 'Graph member',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: ['execute_code'],
stateful_code_sessions: true,
stateful_code_environment: 'user',
code_environment_id: LIA_RAG,
code_environment_ids: [],
});
await grantView(member);
mockInitializeAgent.mockResolvedValue({
...makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID, member.id] },
}),
statefulCodeSessions: true,
codeExecutionContext: { environmentId: LIA_RAG, environmentType: 'attached' },
});
const fetchSpy = mockWorkerStatus();
try {
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
const descriptorFor = (id) =>
agentClientArgs.agent.lazySubagentConfigs.find((descriptor) => descriptor.id === id);
mockInitializeAgent.mockImplementation(async (params) => ({
...makeSubagentConfig(params.agent.id),
...(params.agent.id === SUBAGENT_ID
? {
subagents: {
enabled: true,
allowSelf: false,
agent_ids: [],
graphs: [
{
type: 'review_team',
name: 'Review team',
description: 'Reviews together.',
agent_ids: [member.id],
edges: [],
entryAgentId: member.id,
resultAgentId: member.id,
},
],
},
}
: {}),
codeExecutionContext: {
environmentId: params.agent.code_environment_id,
environmentType: 'attached',
},
}));
const reviewWith = async (executionId) => {
const config = await select(descriptorFor(SUBAGENT_ID), {
signal: new AbortController().signal,
executionId,
hostArgs: { machine: SKYNET },
});
return config.subagentGraphConfigs?.[0]?.memberConfigs?.[0];
};
const unsettled = await descriptorFor(member.id).resolve({
signal: new AbortController().signal,
executionId: 'run-member-unsettled',
});
expect(await reviewWith('run-review-a')).not.toBe(unsettled);
const settled = await select(descriptorFor(member.id), {
signal: new AbortController().signal,
executionId: 'run-member-settled',
});
expect(await reviewWith('run-review-b')).toBe(settled);
} finally {
fetchSpy.mockRestore();
}
});
it("holds a graph member's default machine while it initializes", async () => {
const req = await setup();
const member = await createAgent({
id: 'agent_graph_member',
name: 'Graph member',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: ['execute_code'],
stateful_code_sessions: true,
stateful_code_environment: 'user',
code_environment_id: LIA_RAG,
code_environment_ids: [SKYNET],
});
await grantView(member);
mockInitializeAgent.mockResolvedValue({
...makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID, member.id] },
}),
statefulCodeSessions: true,
codeExecutionContext: { environmentId: LIA_RAG, environmentType: 'attached' },
});
const fetchSpy = mockWorkerStatus();
try {
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
const descriptorFor = (id) =>
agentClientArgs.agent.lazySubagentConfigs.find((descriptor) => descriptor.id === id);
let memberStarted;
const started = new Promise((resolve) => {
memberStarted = resolve;
});
let releaseMember;
const memberGate = new Promise((resolve) => {
releaseMember = resolve;
});
let memberLoads = 0;
mockInitializeAgent.mockImplementation(async (params) => {
if (params.agent.id === member.id && memberLoads++ === 0) {
memberStarted();
await memberGate;
}
return {
...makeSubagentConfig(params.agent.id),
...(params.agent.id === SUBAGENT_ID
? {
subagents: {
enabled: true,
allowSelf: false,
agent_ids: [],
graphs: [
{
type: 'review_team',
name: 'Review team',
description: 'Reviews together.',
agent_ids: [member.id],
edges: [],
entryAgentId: member.id,
resultAgentId: member.id,
},
],
},
}
: {}),
codeExecutionContext: {
environmentId: params.agent.code_environment_id,
environmentType: 'attached',
},
};
});
const reviewing = descriptorFor(SUBAGENT_ID).resolve({
signal: new AbortController().signal,
executionId: 'run-reviewer',
});
await started;
const moved = descriptorFor(member.id)
.resolve({
signal: new AbortController().signal,
executionId: 'run-member',
hostArgs: { machine: SKYNET },
})
.then(
() => 'routed',
() => 'refused',
);
const outcome = await moved;
releaseMember();
await reviewing;
expect(outcome).toBe('refused');
} finally {
fetchSpy.mockRestore();
}
});
it('keeps a reviewer that may not use the parent machine on its own default', async () => {
const req = await setup({ reviewer: { code_environment_ids: [] } });
const fetchSpy = mockWorkerStatus();
try {
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
} finally {
fetchSpy.mockRestore();
}
expect(req.codeWorkspaceInheritance.size).toBe(0);
expect(agentClientArgs.agent.lazySubagentConfigs[0].codeExecutionContext).toEqual(
expect.objectContaining({
environmentId: SKYNET,
codeWorkspace: expect.objectContaining({ workspaceId: 'code-api' }),
}),
);
});
it("never inherits a machine outside the principal's environments", async () => {
const req = await setup({ environments: [SKYNET] });
req.body.codeWorkspaces = [{ environmentId: SKYNET, workspaceId: 'code-api' }];
mockInitializeAgent.mockResolvedValue({
...makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },
}),
statefulCodeSessions: true,
codeExecutionContext: { environmentId: LIA_RAG, environmentType: 'attached' },
});
const fetchSpy = mockWorkerStatus();
try {
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
} finally {
fetchSpy.mockRestore();
}
expect(req.codeWorkspaceInheritance.size).toBe(0);
expect(agentClientArgs.agent.lazySubagentConfigs[0].codeExecutionContext.environmentId).toBe(
SKYNET,
);
});
it("keeps the parent's turn when a reviewer has no selection it may use", async () => {
const req = await setup({ reviewer: { code_environment_ids: [] } });
req.body.codeWorkspaces = [req.body.codeWorkspaces[0]];
const fetchSpy = mockWorkerStatus();
try {
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
} finally {
fetchSpy.mockRestore();
}
const descriptor = agentClientArgs.agent.lazySubagentConfigs[0];
expect(descriptor.codeExecutionContext).toBeUndefined();
expect(descriptor.description).toContain('Unavailable in this conversation');
await expect(
descriptor.resolve({ signal: new AbortController().signal }),
).rejects.toMatchObject({ code: ErrorTypes.CODE_WORKSPACE_UNAVAILABLE, reason: 'required' });
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
});
});
it('omits a descriptor when its metadata lookup fails without aborting the primary run', async () => {
jest.spyOn(logger, 'error').mockImplementation(() => {});
const primaryConfig = makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },
});
mockInitializeAgent.mockResolvedValue(primaryConfig);
jest.spyOn(db, 'getAgentWithVersionCount').mockRejectedValueOnce(new Error('transient read'));
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(agentClientArgs.agent.lazySubagentConfigs).toEqual([]);
expect(logger.error).toHaveBeenCalledWith(
expect.stringContaining(`Error loading subagent metadata ${SUBAGENT_ID}`),
expect.any(Error),
);
});
it('uses exact custom-endpoint identity for descriptor reasoning history', async () => {
const subAgent = await createAgent({
id: SUBAGENT_ID,
name: 'Custom Subagent',
provider: 'caseprovider',
model: 'custom-model',
author: new mongoose.Types.ObjectId(),
tools: [],
});
await grantView(subAgent);
mockInitializeAgent.mockResolvedValue(
makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },
}),
);
const req = makeSubagentReq();
req.config.endpoints.custom = [
{ name: 'CaseProvider', customParams: { includeReasoningHistory: true } },
{ name: 'caseprovider', customParams: { includeReasoningHistory: false } },
];
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(agentClientArgs.agent.lazySubagentConfigs[0].includeReasoningHistory).toBe(false);
});
it('fails closed when a selected subagent configuration changes after advertisement', async () => {
await createViewableAgent(SUBAGENT_ID);
const primaryConfig = makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },
});
mockInitializeAgent.mockResolvedValue(primaryConfig);
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
await updateAgent({ id: SUBAGENT_ID }, { instructions: 'Changed after descriptor creation.' });
await expect(
agentClientArgs.agent.lazySubagentConfigs[0].resolve({
signal: new AbortController().signal,
}),
).rejects.toThrow(`Subagent ${SUBAGENT_ID} changed`);
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
});
it('rechecks VIEW permission when a descriptor is selected', async () => {
const subAgent = await createViewableAgent(SUBAGENT_ID);
const primaryConfig = makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },
});
mockInitializeAgent.mockResolvedValue(primaryConfig);
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
await AclEntry.deleteMany({ resourceId: subAgent._id });
await expect(
agentClientArgs.agent.lazySubagentConfigs[0].resolve({
signal: new AbortController().signal,
}),
).rejects.toThrow(`no longer have access to subagent ${SUBAGENT_ID}`);
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
});
it('preserves subagent tool context for ON_TOOL_EXECUTE (Codex P1 regression guard)', async () => {
/** Verifies the Codex P1 fix: `agentToolContexts.delete(subagentId)` is
* NOT called for subagent-only agents, so when the child dispatches
* `ON_TOOL_EXECUTE` the parent can still resolve its tool context
* (agent, tool_resources, skill ACLs, actionsEnabled) to run tools
* with the right scope. We drive the real `loadTools` closure that
* `initializeClient` wires into `toolExecuteOptions`. */
const subAgent = await createAgent({
id: SUBAGENT_ID,
name: 'Explicit Subagent',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: ['web'],
});
await grantView(subAgent);
const primaryConfig = makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },
});
const subagentConfig = makeSubagentConfig(SUBAGENT_ID);
let call = 0;
mockInitializeAgent.mockImplementation(() =>
Promise.resolve(++call === 1 ? primaryConfig : subagentConfig),
);
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
await agentClientArgs.agent.lazySubagentConfigs[0].resolve({
signal: new AbortController().signal,
});
expect(capturedToolExecuteOptions?.loadTools).toBeInstanceOf(Function);
/** Invoke the real closure with the subagent's id. If `agentToolContexts`
* had been deleted (as in the pre-fix code), this would call
* `loadToolsForExecution` with `agent: undefined` — actions/resource-
* scoped tools would silently drop. */
await capturedToolExecuteOptions.loadTools(['web'], SUBAGENT_ID);
expect(mockLoadToolsForExecution).toHaveBeenCalledTimes(1);
const arg = mockLoadToolsForExecution.mock.calls[0][0];
expect(arg.agent).toBeDefined();
expect(arg.agent.id).toBe(SUBAGENT_ID);
expect(arg.toolRegistry).toBeInstanceOf(Map);
expect(arg.tool_resources).toEqual({ file_search: { file_ids: ['file_1'] } });
expect(arg.actionsEnabled).toBe(true);
});
it('threads run-scoped MCP tool definitions into ON_TOOL_EXECUTE loading', async () => {
/** Regression guard for the request-scoped MCP/PTC handoff: the
* `mcpAvailableTools` discovered at run start must survive
* `buildAgentToolContext` and reach `loadToolsForExecution`, otherwise
* request-scoped servers reinitialize on every programmatic tool call
* and can trip the MCP circuit breaker under parallel calls. */
const mcpTool = 'list_tables_mcp_ClickHouse';
const mcpAvailableTools = {
ClickHouse: {
[mcpTool]: {
type: 'function',
function: {
name: mcpTool,
description: 'List tables',
parameters: { type: 'object', properties: {} },
},
},
},
};
const primaryConfig = {
...makePrimaryConfig({}),
toolRegistry: new Map([[mcpTool, { name: mcpTool }]]),
mcpAvailableTools,
};
mockInitializeAgent.mockResolvedValue(primaryConfig);
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(capturedToolExecuteOptions?.loadTools).toBeInstanceOf(Function);
await capturedToolExecuteOptions.loadTools([mcpTool], PRIMARY_ID);
expect(mockLoadToolsForExecution).toHaveBeenCalledTimes(1);
expect(mockLoadToolsForExecution).toHaveBeenCalledWith(
expect.objectContaining({ mcpAvailableTools }),
);
});
it('deduplicates repeated ids in subagents.agent_ids', async () => {
const subAgent = await createAgent({
id: DUPLICATE_SUBAGENT_ID,
name: 'Dup Subagent',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: [],
});
await grantView(subAgent);
const primaryConfig = makePrimaryConfig({
subagents: {
enabled: true,
allowSelf: false,
/** Same id three times — the backend must not load the agent
* repeatedly and must not emit three SubagentConfig entries. */
agent_ids: [DUPLICATE_SUBAGENT_ID, DUPLICATE_SUBAGENT_ID, DUPLICATE_SUBAGENT_ID],
},
});
mockInitializeAgent.mockResolvedValue(primaryConfig);
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
/** Repeated ids produce one lightweight descriptor and no eager child initialization. */
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
expect(agentClientArgs.agent.lazySubagentConfigs).toHaveLength(1);
});
it('does not initialize a descriptor after its SDK cancellation signal aborts', async () => {
await createViewableAgent(SUBAGENT_ID);
const primaryConfig = makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },
});
mockInitializeAgent.mockResolvedValue(primaryConfig);
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
const controller = new AbortController();
controller.abort(new Error('cancelled'));
await expect(
agentClientArgs.agent.lazySubagentConfigs[0].resolve({ signal: controller.signal }),
).rejects.toThrow('cancelled');
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
});
it('rejects promptly when cancellation occurs during lazy initialization', async () => {
await createViewableAgent(SUBAGENT_ID);
const primaryConfig = makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },
});
const initialization = deferred();
const initializationStarted = deferred();
mockInitializeAgent.mockResolvedValueOnce(primaryConfig).mockImplementationOnce((params) => {
initializationStarted.resolve(params);
return initialization.promise;
});
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
const controller = new AbortController();
const resolution = agentClientArgs.agent.lazySubagentConfigs[0].resolve({
signal: controller.signal,
});
const selectedInitParams = await initializationStarted.promise;
controller.abort(new Error('cancelled in flight'));
await expect(resolution).rejects.toThrow('cancelled in flight');
expect(selectedInitParams.loadTools).not.toBe(mockInitializeAgent.mock.calls[0][0].loadTools);
initialization.resolve(makeSubagentConfig(SUBAGENT_ID));
});
it('resolves a graph subagent as an isolated all-member team', async () => {
const memberIds = ['agent_graph_researcher', 'agent_graph_writer'];
for (const memberId of memberIds) {
await createViewableAgent(memberId);
}
const definition = {
type: 'research_team',
name: 'Research team',
description: 'Researches and writes a final answer',
agent_ids: memberIds,
edges: [{ from: memberIds[0], to: memberIds[1], edgeType: 'direct' }],
entry_agent_id: memberIds[0],
result_agent_id: memberIds[1],
};
const primaryConfig = makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, graphs: [definition] },
});
const memberConfigs = new Map(
memberIds.map((id, index) => [
id,
{
...makeSubagentConfig(id),
userMCPAuthMap: { [`server_${index}`]: { token: `token_${index}` } },
},
]),
);
mockInitializeAgent.mockImplementation(({ agent }) =>
Promise.resolve(agent.id === PRIMARY_ID ? primaryConfig : memberConfigs.get(agent.id)),
);
const req = makeSubagentReq();
req.config.endpoints.agents.capabilities.push('run_in_background');
const { userMCPAuthMap } = await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(agentClientArgs.agent.subagentGraphConfigs).toEqual([
{
definition,
memberConfigs: memberIds.map((id) => memberConfigs.get(id)),
},
]);
expect(memberIds.every((id) => !agentClientArgs.agentConfigs.has(id))).toBe(true);
expect(agentClientArgs.subagentTasks).toBe(capturedToolExecuteOptions.subagentTasks);
expect(userMCPAuthMap).toEqual({
server_0: { token: 'token_0' },
server_1: { token: 'token_1' },
});
});
it('resolves graph teams only after their lazy parent is selected', async () => {
const childId = 'agent_lazy_graph_parent';
const memberId = 'agent_lazy_graph_member';
const definition = {
type: 'lazy_team',
name: 'Lazy team',
description: 'Loads with its selected parent',
agent_ids: [childId, memberId],
edges: [{ from: childId, to: memberId, edgeType: 'direct' }],
entry_agent_id: childId,
result_agent_id: memberId,
};
await createViewableAgent(childId, {
enabled: true,
allowSelf: false,
graphs: [definition],
});
const memberAgent = await createAgent({
id: memberId,
name: memberId,
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: ['execute_code'],
stateful_code_sessions: true,
});
await grantView(memberAgent);
const primaryConfig = makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [childId] },
});
const memberMCPAuthMap = { late_server: { token: 'late_token' } };
mockInitializeAgent.mockImplementation(({ agent }) =>
Promise.resolve(
agent.id === PRIMARY_ID
? primaryConfig
: {
...makeSubagentConfig(agent.id),
subagents: agent.subagents,
...(agent.id === memberId ? { userMCPAuthMap: memberMCPAuthMap } : {}),
},
),
);
const req = makeSubagentReq();
req.config.endpoints.agents.capabilities.push(
'execute_code',
'run_in_background',
'tool_intents',
'stateful_code_sessions',
);
req.config.endpoints.agents.statefulCodeSessions = {
allowedEnvironments: ['user'],
environments: [
{
id: 'managed-code',
name: 'Managed code',
type: 'managed',
baseURL: 'https://stateful-code.example.com/v1',
default: true,
},
],
};
mockGetAppConfig.mockResolvedValue(req.config);
const { userMCPAuthMap } = await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
const descriptor = agentClientArgs.agent.lazySubagentConfigs[0];
expect(descriptor.subagentGraphMemberMetadata).toEqual([
expect.objectContaining({
id: memberId,
codeEnvAvailable: true,
statefulCodeSessions: true,
}),
]);
expect(userMCPAuthMap).toEqual({});
const resolvedChild = await descriptor.resolve({
signal: new AbortController().signal,
});
expect(mockInitializeAgent).toHaveBeenCalledTimes(3);
expect(mockInitializeAgent).toHaveBeenCalledWith(
expect.objectContaining({
agent: expect.objectContaining({ id: memberId }),
backgroundToolsAvailable: true,
toolIntentsAvailable: true,
}),
expect.anything(),
);
expect(resolvedChild.subagentGraphConfigs).toEqual([
{
definition,
memberConfigs: [resolvedChild, expect.objectContaining({ id: memberId })],
},
]);
expect(userMCPAuthMap).toEqual(memberMCPAuthMap);
});
it('aborts lazy graph member initialization with the descriptor signal', async () => {
const childId = 'agent_lazy_cancel_parent';
const memberId = 'agent_lazy_cancel_member';
const definition = {
type: 'lazy_cancel_team',
name: 'Lazy cancel team',
description: 'Stops member initialization with its selected parent',
agent_ids: [memberId],
edges: [],
entry_agent_id: memberId,
result_agent_id: memberId,
};
await createViewableAgent(childId, {
enabled: true,
allowSelf: false,
graphs: [definition],
});
await createViewableAgent(memberId);
const primaryConfig = makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [childId] },
});
const memberInitialization = deferred();
const memberStarted = deferred();
mockInitializeAgent.mockImplementation(({ agent }) => {
if (agent.id === PRIMARY_ID) return Promise.resolve(primaryConfig);
if (agent.id === childId) {
return Promise.resolve({ ...makeSubagentConfig(childId), subagents: agent.subagents });
}
memberStarted.resolve();
return memberInitialization.promise;
});
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
const controller = new AbortController();
const resolution = agentClientArgs.agent.lazySubagentConfigs[0].resolve({
signal: controller.signal,
});
await memberStarted.promise;
controller.abort(new Error('cancelled graph resolution'));
await expect(resolution).rejects.toThrow('cancelled graph resolution');
memberInitialization.resolve(makeSubagentConfig(memberId));
});
it('coalesces shared graph member initialization across parallel lazy resolutions', async () => {
const childIds = ['agent_lazy_shared_parent_a', 'agent_lazy_shared_parent_b'];
const memberId = 'agent_lazy_shared_member';
for (const childId of childIds) {
await createViewableAgent(childId, {
enabled: true,
allowSelf: false,
graphs: [
{
type: `shared_team_${childId}`,
name: `Shared team ${childId}`,
description: 'Loads one shared member',
agent_ids: [memberId],
edges: [],
entry_agent_id: memberId,
result_agent_id: memberId,
},
],
});
}
await createViewableAgent(memberId);
const primaryConfig = makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: childIds },
});
const memberStarted = deferred();
const memberRelease = deferred();
mockInitializeAgent.mockImplementation(async ({ agent }) => {
if (agent.id === PRIMARY_ID) return primaryConfig;
if (childIds.includes(agent.id)) {
return { ...makeSubagentConfig(agent.id), subagents: agent.subagents };
}
memberStarted.resolve();
await memberRelease.promise;
return makeSubagentConfig(memberId);
});
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
const resolutions = agentClientArgs.agent.lazySubagentConfigs.map((descriptor) =>
descriptor.resolve({ signal: new AbortController().signal }),
);
await memberStarted.promise;
memberRelease.resolve();
const resolvedChildren = await Promise.all(resolutions);
expect(
mockInitializeAgent.mock.calls.filter(([{ agent }]) => agent.id === memberId),
).toHaveLength(1);
expect(resolvedChildren).toHaveLength(2);
expect(
resolvedChildren.every(
(child) => child.subagentGraphConfigs[0].memberConfigs[0].id === memberId,
),
).toBe(true);
});
it('loads independent graph members concurrently', async () => {
const memberIds = ['agent_graph_parallel_a', 'agent_graph_parallel_b'];
for (const memberId of memberIds) {
await createViewableAgent(memberId);
}
const definition = {
type: 'parallel_team',
name: 'Parallel team',
description: 'Loads independent members concurrently',
agent_ids: memberIds,
edges: [{ from: memberIds[0], to: memberIds[1], edgeType: 'direct' }],
entry_agent_id: memberIds[0],
result_agent_id: memberIds[1],
};
const primaryConfig = makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, graphs: [definition] },
});
const memberStarts = new Map(memberIds.map((id) => [id, deferred()]));
const memberReleases = new Map(memberIds.map((id) => [id, deferred()]));
mockInitializeAgent.mockImplementation(async ({ agent }) => {
if (agent.id === PRIMARY_ID) {
return primaryConfig;
}
memberStarts.get(agent.id)?.resolve();
await memberReleases.get(agent.id)?.promise;
return makeSubagentConfig(agent.id);
});
const getAgentWithVersionCount = jest.spyOn(db, 'getAgentWithVersionCount');
const initialization = initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
await Promise.all(memberIds.map((id) => memberStarts.get(id)?.promise));
for (const release of memberReleases.values()) {
release.resolve();
}
await initialization;
expect(agentClientArgs.agent.subagentGraphConfigs[0].memberConfigs).toHaveLength(2);
for (const memberId of memberIds) {
expect(
getAgentWithVersionCount.mock.calls.filter(([query]) => query.id === memberId),
).toHaveLength(1);
}
});
it('reuses the primary config when the parent is a graph member', async () => {
const memberId = 'agent_graph_self_worker';
await createViewableAgent(memberId);
const definition = {
type: 'self_team',
name: 'Self team',
description: 'Uses the parent as the entry member',
agent_ids: [PRIMARY_ID, memberId],
edges: [{ from: PRIMARY_ID, to: memberId, edgeType: 'direct' }],
entry_agent_id: PRIMARY_ID,
result_agent_id: memberId,
};
const primaryConfig = makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, graphs: [definition] },
});
const memberConfig = makeSubagentConfig(memberId);
mockInitializeAgent.mockImplementation(({ agent }) =>
Promise.resolve(agent.id === PRIMARY_ID ? primaryConfig : memberConfig),
);
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(mockInitializeAgent).toHaveBeenCalledTimes(2);
expect(agentClientArgs.agent.subagentGraphConfigs).toEqual([
{ definition, memberConfigs: [primaryConfig, memberConfig] },
]);
expect(agentClientArgs.agentConfigs.has(PRIMARY_ID)).toBe(false);
});
it('keeps an added-conversation agent that is also a graph member', async () => {
const addedAgentId = 'agent_added_graph_member';
const definition = {
type: 'added_member_team',
name: 'Added member team',
description: 'Runs the selected parallel agent as a graph member',
agent_ids: [addedAgentId],
edges: [],
entry_agent_id: addedAgentId,
result_agent_id: addedAgentId,
};
const primaryConfig = makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, graphs: [definition] },
});
const addedConfig = makeSubagentConfig(addedAgentId);
mockInitializeAgent.mockResolvedValue(primaryConfig);
processAddedConvo.mockImplementationOnce(async ({ agentConfigs }) => {
agentConfigs.set(addedAgentId, addedConfig);
return { userMCPAuthMap: undefined };
});
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(agentClientArgs.agentConfigs.get(addedAgentId)).toBe(addedConfig);
expect(agentClientArgs.agent.subagentGraphConfigs).toEqual([
{ definition, memberConfigs: [addedConfig] },
]);
});
it('skips the whole graph subagent when one persisted member is missing', async () => {
const existingId = 'agent_graph_existing';
const missingId = 'agent_graph_missing';
await createViewableAgent(existingId);
const definition = {
type: 'incomplete_team',
name: 'Incomplete team',
description: 'Legacy graph with a deleted member',
agent_ids: [existingId, missingId],
edges: [{ from: existingId, to: missingId, edgeType: 'direct' }],
entry_agent_id: existingId,
result_agent_id: missingId,
};
const primaryConfig = makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, graphs: [definition] },
});
mockInitializeAgent.mockImplementation(({ agent }) =>
Promise.resolve(agent.id === PRIMARY_ID ? primaryConfig : makeSubagentConfig(agent.id)),
);
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(agentClientArgs.agent.subagentGraphConfigs).toEqual([]);
expect(agentClientArgs.agentConfigs.has(existingId)).toBe(false);
expect(logger.warn).toHaveBeenCalledWith(
'[initializeClient] Skipping incomplete graph subagent',
expect.objectContaining({ graphType: 'incomplete_team', resolvedMemberCount: 1 }),
);
});
it('counts initialized members from incomplete graph teams against the global node limit', async () => {
const retainedMemberIds = Array.from(
{ length: 31 },
(_, index) => `agent_incomplete_retained_${index}`,
);
const overflowMemberIds = Array.from(
{ length: 20 },
(_, index) => `agent_incomplete_overflow_${index}`,
);
await Promise.all(
[...retainedMemberIds, ...overflowMemberIds].map((id) => createViewableAgent(id)),
);
const definitions = [
{
type: 'incomplete_retained_team',
name: 'Incomplete retained team',
description: 'Loads members before discovering a missing result',
agent_ids: [...retainedMemberIds, 'agent_incomplete_missing_result'],
edges: [],
entry_agent_id: retainedMemberIds[0],
result_agent_id: 'agent_incomplete_missing_result',
},
{
type: 'incomplete_overflow_team',
name: 'Incomplete overflow team',
description: 'Must be rejected before loading any more members',
agent_ids: [...overflowMemberIds, 'agent_incomplete_missing_overflow'],
edges: [],
entry_agent_id: overflowMemberIds[0],
result_agent_id: 'agent_incomplete_missing_overflow',
},
];
const primaryConfig = makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, graphs: definitions },
});
mockInitializeAgent.mockImplementation(({ agent }) =>
Promise.resolve(agent.id === PRIMARY_ID ? primaryConfig : makeSubagentConfig(agent.id)),
);
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(mockInitializeAgent).toHaveBeenCalledTimes(1 + retainedMemberIds.length);
expect(logger.warn).toHaveBeenCalledWith(
'[initializeClient] Subagent graph node limit exceeded',
expect.objectContaining({
loadedSubagentCount: retainedMemberIds.length + 1,
stagedSubagentCount: overflowMemberIds.length + 1,
maxSubagentGraphNodes: MAX_SUBAGENT_GRAPH_NODES,
}),
);
});
it('rejects nested subagent chains deeper than MAX_SUBAGENT_DEPTH', async () => {
const ids = Array.from(
{ length: MAX_SUBAGENT_DEPTH + 1 },
(_, index) => `agent_depth_${index}`,
);
for (const [index, id] of ids.entries()) {
await createViewableAgent(id, {
enabled: true,
allowSelf: false,
agent_ids: index < ids.length - 1 ? [ids[index + 1]] : [],
});
}
const primaryConfig = makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [ids[0]] },
});
mockInitializeAgent.mockResolvedValue(primaryConfig);
await expect(
initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
}),
).rejects.toThrow(`maximum depth of ${MAX_SUBAGENT_DEPTH}`);
expect(logger.warn).toHaveBeenCalledWith(
'[initializeClient] Subagent graph depth limit exceeded',
expect.objectContaining({
agentId: ids[MAX_SUBAGENT_DEPTH - 1],
primaryAgentId: PRIMARY_ID,
depth: MAX_SUBAGENT_DEPTH,
maxSubagentDepth: MAX_SUBAGENT_DEPTH,
}),
);
expect(agentClientArgs).toBeUndefined();
});
it('preserves deeper path depth when a handoff root is also a nested subagent', async () => {
const chainIds = Array.from(
{ length: MAX_SUBAGENT_DEPTH },
(_, index) => `agent_overlap_depth_${index}`,
);
await createViewableAgent(HANDOFF_AND_SUB_ID, {
enabled: true,
allowSelf: false,
agent_ids: [chainIds[0]],
});
for (const [index, id] of chainIds.entries()) {
await createViewableAgent(id, {
enabled: true,
allowSelf: false,
agent_ids: index < chainIds.length - 1 ? [chainIds[index + 1]] : [],
});
}
const edges = [{ from: PRIMARY_ID, to: HANDOFF_AND_SUB_ID, edgeType: 'handoff' }];
const primaryConfig = makePrimaryConfig({
edges,
subagents: { enabled: true, allowSelf: false, agent_ids: [HANDOFF_AND_SUB_ID] },
});
const sharedConfig = makeNestedSubagentConfig(HANDOFF_AND_SUB_ID, [chainIds[0]]);
mockInitializeAgent.mockImplementation(({ agent }) =>
Promise.resolve(agent.id === PRIMARY_ID ? primaryConfig : sharedConfig),
);
await expect(
initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
}),
).rejects.toThrow(`maximum depth of ${MAX_SUBAGENT_DEPTH}`);
expect(agentClientArgs).toBeUndefined();
});
it('rejects subagent graphs that exceed MAX_SUBAGENT_GRAPH_NODES unique agents', async () => {
const firstLevelIds = Array.from({ length: 10 }, (_, index) => `agent_graph_${index}`);
const secondLevelIdsByParent = new Map(
firstLevelIds.map((id) => [
id,
Array.from({ length: 5 }, (_, index) => `${id}_child_${index}`),
]),
);
for (const id of firstLevelIds) {
await createViewableAgent(id, {
enabled: true,
allowSelf: false,
agent_ids: secondLevelIdsByParent.get(id),
});
}
for (const id of Array.from(secondLevelIdsByParent.values()).flat()) {
await createViewableAgent(id, { enabled: true, allowSelf: false, agent_ids: [] });
}
const primaryConfig = makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: firstLevelIds },
});
mockInitializeAgent.mockResolvedValue(primaryConfig);
await expect(
initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
}),
).rejects.toThrow(`maximum of ${MAX_SUBAGENT_GRAPH_NODES} unique agents`);
expect(logger.warn).toHaveBeenCalledWith(
'[initializeClient] Subagent graph node limit exceeded',
expect.objectContaining({
primaryAgentId: PRIMARY_ID,
loadedSubagentCount: MAX_SUBAGENT_GRAPH_NODES,
maxSubagentGraphNodes: MAX_SUBAGENT_GRAPH_NODES,
}),
);
expect(agentClientArgs).toBeUndefined();
});
it('bounds capability metadata reads across lazy graph teams', async () => {
const firstChildId = 'agent_lazy_graph_cap_first';
const secondChildId = 'agent_lazy_graph_cap_second';
const firstMemberIds = Array.from({ length: 32 }, (_, index) => `agent_cap_first_${index}`);
const secondMemberIds = Array.from({ length: 17 }, (_, index) => `agent_cap_second_${index}`);
const makeGraph = (type, memberIds) => ({
type,
name: type,
description: type,
agent_ids: memberIds,
edges: memberIds.slice(0, -1).map((memberId, index) => ({
from: memberId,
to: memberIds[index + 1],
edgeType: 'direct',
})),
entry_agent_id: memberIds[0],
result_agent_id: memberIds.at(-1),
});
await createViewableAgent(firstChildId, {
enabled: true,
allowSelf: false,
graphs: [makeGraph('first_capability_team', firstMemberIds)],
});
await createViewableAgent(secondChildId, {
enabled: true,
allowSelf: false,
graphs: [makeGraph('second_capability_team', secondMemberIds)],
});
await Promise.all(
[...firstMemberIds, ...secondMemberIds].map((memberId) => createViewableAgent(memberId)),
);
const primaryConfig = makePrimaryConfig({
subagents: {
enabled: true,
allowSelf: false,
agent_ids: [firstChildId, secondChildId],
},
});
mockInitializeAgent.mockResolvedValue(primaryConfig);
await expect(
initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
}),
).rejects.toThrow(`maximum of ${MAX_SUBAGENT_GRAPH_NODES} unique agents`);
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
const stagedLimitWarning = logger.warn.mock.calls.find(
([message, metadata]) =>
message === '[initializeClient] Subagent graph node limit exceeded' &&
Number.isInteger(metadata?.stagedSubagentCount),
);
expect(stagedLimitWarning).toBeDefined();
expect(stagedLimitWarning[1]).toEqual(
expect.objectContaining({ maxSubagentGraphNodes: MAX_SUBAGENT_GRAPH_NODES }),
);
expect(
stagedLimitWarning[1].loadedSubagentCount + stagedLimitWarning[1].stagedSubagentCount,
).toBeGreaterThan(MAX_SUBAGENT_GRAPH_NODES);
});
it('rejects a branching DAG that exceeds expanded descriptor capacity', async () => {
const width = 3;
const layers = Array.from({ length: MAX_SUBAGENT_DEPTH }, (_, level) =>
Array.from({ length: width }, (_, index) => `agent_descriptor_${level}_${index}`),
);
for (let level = 0; level < layers.length; level++) {
const childIds = level < layers.length - 1 ? layers[level + 1] : [];
for (const id of layers[level]) {
await createViewableAgent(id, { enabled: true, allowSelf: false, agent_ids: childIds });
}
}
const primaryConfig = makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: layers[0] },
});
mockInitializeAgent.mockResolvedValue(primaryConfig);
await expect(
initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
}),
).rejects.toThrow(`maximum of ${MAX_SUBAGENT_RUN_CONFIGS} expanded entries`);
expect(logger.warn).toHaveBeenCalledWith(
'[initializeClient] Subagent run configuration limit exceeded',
expect.objectContaining({
expandedConfigCount: MAX_SUBAGENT_RUN_CONFIGS + 1,
maxSubagentRunConfigs: MAX_SUBAGENT_RUN_CONFIGS,
rootAgentIds: [PRIMARY_ID],
}),
);
expect(agentClientArgs).toBeUndefined();
});
it('keeps an agent in `agentConfigs` when it is BOTH a handoff target and a subagent', async () => {
/** Overlap case: the same child is used both via handoff edges (needs to
* be in agentConfigs) and as a subagent (needs to be in
* subagentAgentConfigs, and its tool context preserved). The pipeline
* shouldn't silently drop it from the handoff map. */
const shared = await createAgent({
id: HANDOFF_AND_SUB_ID,
name: 'Shared Agent',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: [],
});
await grantView(shared);
const edges = [{ from: PRIMARY_ID, to: HANDOFF_AND_SUB_ID, edgeType: 'handoff' }];
const primaryConfig = makePrimaryConfig({
edges,
subagents: {
enabled: true,
allowSelf: false,
agent_ids: [HANDOFF_AND_SUB_ID],
},
});
const sharedConfig = makeSubagentConfig(HANDOFF_AND_SUB_ID);
let call = 0;
mockInitializeAgent.mockImplementation(() =>
Promise.resolve(++call === 1 ? primaryConfig : sharedConfig),
);
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(agentClientArgs.agent.subagentAgentConfigs).toHaveLength(1);
/** Shared agent must stay in agentConfigs — it's still the handoff target. */
expect(agentClientArgs.agentConfigs.has(HANDOFF_AND_SUB_ID)).toBe(true);
});
it('preserves shared initialized agent children across parallel walkers', async () => {
const leftId = 'agent_parallel_left';
const rightId = 'agent_parallel_right';
const sharedId = 'agent_parallel_shared';
const primaryConfig = makePrimaryConfig({
subagents: { enabled: true, allowSelf: false, agent_ids: [leftId, rightId] },
});
const leftConfig = makeNestedSubagentConfig(leftId, [sharedId]);
const rightConfig = makeNestedSubagentConfig(rightId, [sharedId]);
const sharedConfig = makeNestedSubagentConfig(sharedId, [leftId]);
mockInitializeAgent.mockResolvedValue(primaryConfig);
processAddedConvo.mockImplementationOnce(async ({ agentConfigs }) => {
agentConfigs.set(leftId, leftConfig);
agentConfigs.set(rightId, rightConfig);
agentConfigs.set(sharedId, sharedConfig);
return { userMCPAuthMap: undefined };
});
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
const subagentsById = new Map(
agentClientArgs.agent.subagentAgentConfigs.map((config) => [config.id, config]),
);
const left = subagentsById.get(leftId);
const right = subagentsById.get(rightId);
const leftShared = left.subagentAgentConfigs[0];
const rightShared = right.subagentAgentConfigs[0];
expect(leftShared).toBe(sharedConfig);
expect(rightShared).toBe(sharedConfig);
expect(leftShared.subagentAgentConfigs.map((child) => child.id)).toEqual([leftId]);
expect(rightShared.subagentAgentConfigs.map((child) => child.id)).toEqual([leftId]);
expect(agentClientArgs.agentConfigs.get(sharedId)).toBe(sharedConfig);
});
it('clears subagents config on primary when the capability is disabled', async () => {
/** Admin can turn subagents off at the endpoint level even if an agent was
* configured for them. The primary's `subagents` field should be
* suppressed so run.ts never builds a SubagentConfig. */
const primaryConfig = makePrimaryConfig({
subagents: { enabled: true, allowSelf: true, agent_ids: [] },
});
mockInitializeAgent.mockResolvedValue(primaryConfig);
const req = makeSubagentReq();
/** Remove the capability from the admin config. */
req.config.endpoints.agents.capabilities = [];
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(agentClientArgs.agent.subagents).toBeUndefined();
expect(agentClientArgs.agent.subagentAgentConfigs).toEqual([]);
});
it('clears subagents on handoff agents too when capability is disabled (Codex P2 regression)', async () => {
/** Codex P2: the capability gate must suppress `subagents` on EVERY
* loaded config, not just the primary. `run.ts` iterates all agents
* and calls `buildSubagentConfigs` per agent, so a handoff target
* with `subagents.enabled: true` persisted on its document would
* otherwise still expose self-spawn even when the admin has disabled
* the capability globally. */
const authorized = await createAgent({
id: AUTHORIZED_ID,
name: 'Handoff Agent',
provider: 'openai',
model: 'gpt-4',
author: new mongoose.Types.ObjectId(),
tools: [],
});
await grantView(authorized);
const edges = [{ from: PRIMARY_ID, to: AUTHORIZED_ID, edgeType: 'handoff' }];
const primaryConfig = makePrimaryConfig({
edges,
subagents: { enabled: true, allowSelf: true, agent_ids: [] },
});
const handoffConfig = {
id: AUTHORIZED_ID,
endpoint: 'agents',
edges: [],
toolDefinitions: [],
toolRegistry: new Map(),
userMCPAuthMap: null,
tool_resources: {},
/** Handoff agent document has subagents enabled of its own accord. */
subagents: { enabled: true, allowSelf: true, agent_ids: [] },
};
let callCount = 0;
mockInitializeAgent.mockImplementation(() =>
Promise.resolve(++callCount === 1 ? primaryConfig : handoffConfig),
);
const req = makeSubagentReq();
/** Capability OFF at endpoint level. */
req.config.endpoints.agents.capabilities = [];
await initializeClient({
req,
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
/** Primary cleared. */
expect(agentClientArgs.agent.subagents).toBeUndefined();
/** Handoff target must ALSO be cleared — otherwise its self-spawn
* would still fire when run.ts iterates agentConfigs. */
const handoffLoaded = agentClientArgs.agentConfigs.get(AUTHORIZED_ID);
expect(handoffLoaded).toBeDefined();
expect(handoffLoaded.subagents).toBeUndefined();
expect(handoffLoaded.subagentAgentConfigs).toBeUndefined();
});
it('skips subagent loading entirely when the feature is disabled on the agent', async () => {
const primaryConfig = makePrimaryConfig({
subagents: { enabled: false, allowSelf: true, agent_ids: [SUBAGENT_ID] },
});
mockInitializeAgent.mockResolvedValue(primaryConfig);
await initializeClient({
req: makeSubagentReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
/** Only one initializeAgent call — for the primary. No subagent loaded. */
expect(mockInitializeAgent).toHaveBeenCalledTimes(1);
expect(agentClientArgs.agent.subagentAgentConfigs).toEqual([]);
});
});