LibreChat/packages/api/src/code/http.spec.ts
Danny Avila 35a2bee409
Some checks are pending
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 (full suite) (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/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
Sync Locize Translations & Create Translation PR / Sync Translation Keys with Locize (push) Waiting to run
Sync Locize Translations & Create Translation PR / Create Translation PR on Version Published (push) Blocked by required conditions
🗂️ feat: Choose Conversation Checkout Mode (#16679)
* feat: Choose the conversation checkout mode

* fix: Preserve checkout choices across submission and recovery

* test: Match checkout policy defaults and share mode enum

* fix: Offer shared checkout and require deliberate transition modes

* fix: Retain explicit mode when changing repository selection

* test: Match repository menu accessible labels
2026-10-02 14:41:35 -04:00

2178 lines
73 KiB
TypeScript

import { EModelEndpoint } from 'librechat-data-provider';
import type { AppConfig } from '@librechat/data-schemas';
import type { CodeEnvironmentGenerationJob } from './http';
import { CodeEnvironmentLimitError, CodeEnvironmentValidationError } from './environments';
import { createCodeEnvironmentHttpHandlers } from './http';
function response() {
const res = {
statusCode: 200,
body: undefined as unknown,
status(code: number) {
this.statusCode = code;
return this;
},
json(body: unknown) {
this.body = body;
return this;
},
};
return res;
}
describe('code environment HTTP handlers', () => {
test.each(['allowed', 'denied', 'unpaired', 'changed-worker'])(
'resolves deployment worker status only through effective authorization: %s',
async (policy) => {
const deploymentEnvironment = {
id: 'deployment-vm',
name: 'Deployment VM',
type: 'attached' as const,
owner: 'deployment' as const,
baseURL: 'https://code.example.com/v1',
pairing: { workerId: 'configured-worker', tokenEnv: 'CODE_ADMIN_TOKEN' },
};
let effectiveWorkerId: string | undefined = 'configured-worker';
if (policy === 'unpaired') effectiveWorkerId = undefined;
if (policy === 'changed-worker') effectiveWorkerId = 'replacement';
const effectiveEnvironment = {
...deploymentEnvironment,
pairing: {
...deploymentEnvironment.pairing,
workerId: effectiveWorkerId,
},
};
const fetchImpl = jest.fn().mockResolvedValue(
new Response(
JSON.stringify({
protocolVersion: 1,
workerId: 'configured-worker',
online: true,
ready: true,
leaseExpiresInMs: 50_000,
capabilities: {
statefulWorkspace: true,
sandboxProfile: 'native-srt',
runtimes: ['bash'],
},
}),
),
);
const effectiveEnvironments = policy === 'denied' ? [] : [effectiveEnvironment];
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn().mockImplementation(async ({ baseOnly }) => ({
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
environments: baseOnly ? [deploymentEnvironment] : effectiveEnvironments,
},
},
},
})),
registry: {
register: jest.fn(),
listAccessible: jest.fn(),
remove: jest.fn(),
listAccessibleConfigurations: jest.fn().mockResolvedValue([]),
},
readSecret: () => 'administrator-token',
fetchImpl,
});
const res = response();
await handlers.status(
{
user: { id: 'user-1', role: 'USER' },
params: { environmentId: 'deployment-vm' },
} as never,
res as never,
);
expect(res.statusCode).toBe(policy === 'allowed' ? 200 : 404);
if (policy !== 'allowed') {
expect(fetchImpl).not.toHaveBeenCalled();
return;
}
expect(res.body).toEqual(
expect.objectContaining({ environmentId: 'deployment-vm', statefulWorkspace: true }),
);
expect(fetchImpl).toHaveBeenCalledWith(
'https://code.example.com/v1/bridge/workers/configured-worker/status',
expect.any(Object),
);
},
);
test('reports status only for an accessible worker through its current control plane', async () => {
const fetchImpl = jest.fn().mockResolvedValue(
new Response(
JSON.stringify({
protocolVersion: 1,
workerId: 'personal-vm',
online: true,
ready: true,
leaseExpiresInMs: 50_000,
capabilities: {
sandboxProfile: 'native-srt',
runtimes: ['bash'],
workspaceTools: {
protocolVersion: 1,
operations: ['read_file', 'execute_command'],
workspaces: [
{
id: 'project-a',
name: 'Project A',
operations: ['read_file', 'execute_command'],
},
],
},
},
}),
),
);
const controlPlane = {
id: 'self-service',
name: 'Self service',
type: 'attached' as const,
baseURL: 'https://code.example.com/v1',
owner: 'deployment' as const,
pairing: { allowPrincipalWorkers: true, tokenEnv: 'CODE_ADMIN_TOKEN' },
};
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn().mockResolvedValue({
endpoints: {
[EModelEndpoint.agents]: { statefulCodeSessions: { environments: [controlPlane] } },
},
} as unknown as AppConfig),
registry: {
register: jest.fn(),
listAccessible: jest.fn(),
listAccessibleConfigurations: jest.fn().mockResolvedValue([
{
id: 'personal-vm',
name: 'Personal VM',
type: 'attached',
baseURL: 'https://stale.example.com/v1',
controlPlaneId: 'self-service',
owner: 'principal',
workerId: 'personal-vm',
},
]),
remove: jest.fn(),
},
readSecret: jest.fn(() => 'administrator-token'),
fetchImpl,
});
const res = response();
const coalescedRes = response();
await Promise.all([
handlers.status(
{
user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' },
params: { environmentId: 'personal-vm' },
} as never,
res as never,
),
handlers.status(
{
user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' },
params: { environmentId: 'personal-vm' },
} as never,
coalescedRes as never,
),
]);
expect(res.statusCode).toBe(200);
expect(res.body).toEqual({
environmentId: 'personal-vm',
status: 'ready',
leaseExpiresInMs: 50_000,
sandboxProfile: 'native-srt',
runtimes: ['bash'],
operations: ['read_file', 'execute_command'],
workspaces: [
{
id: 'project-a',
name: 'Project A',
operations: ['read_file', 'execute_command'],
},
],
});
expect(coalescedRes.body).toEqual(res.body);
expect(fetchImpl).toHaveBeenCalledTimes(1);
expect(fetchImpl).toHaveBeenCalledWith(
'https://code.example.com/v1/bridge/workers/personal-vm/status',
expect.objectContaining({ headers: { Authorization: 'Bearer administrator-token' } }),
);
});
test('does not query status for an inaccessible environment', async () => {
const fetchImpl = jest.fn();
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn().mockResolvedValue({
endpoints: { [EModelEndpoint.agents]: { statefulCodeSessions: { environments: [] } } },
} as unknown as AppConfig),
registry: {
register: jest.fn(),
listAccessible: jest.fn(),
listAccessibleConfigurations: jest.fn().mockResolvedValue([]),
remove: jest.fn(),
},
fetchImpl,
});
const res = response();
await handlers.status(
{
user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' },
params: { environmentId: 'another-users-vm' },
} as never,
res as never,
);
expect(res.statusCode).toBe(404);
expect(fetchImpl).not.toHaveBeenCalled();
});
test('does not advertise principal pairing when Code API principal auth is disabled', async () => {
const listAccessible = jest.fn();
const listAccessibleConfigurations = jest.fn();
const listAccessibleDetails = jest.fn().mockResolvedValue({
summaries: [],
configurations: [],
});
const resolvedPrincipals = [
{ principalType: 'role', principalId: 'USER' },
{ principalType: 'user', principalId: '68b2f0c498f24c1e78fa0001' },
];
const resolvePrincipals = jest.fn().mockResolvedValue(resolvedPrincipals);
const getAppConfig = jest.fn().mockResolvedValue({
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
environments: [
{
id: 'principal-workers',
name: 'Principal workers',
type: 'attached',
baseURL: 'https://code.example.com/v1',
owner: 'deployment',
pairing: { allowPrincipalWorkers: true },
},
],
},
},
},
} as AppConfig);
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig,
registry: {
register: jest.fn(),
listAccessible,
listAccessibleConfigurations,
listAccessibleDetails,
resolvePrincipals,
remove: jest.fn(),
},
principalAuthEnabled: () => false,
});
const res = response();
await handlers.list(
{ user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' } } as never,
res as never,
);
expect(res.statusCode).toBe(200);
expect(res.body).toEqual({ environments: [], controlPlanes: [] });
expect(listAccessibleDetails).toHaveBeenCalledTimes(1);
expect(resolvePrincipals).toHaveBeenCalledTimes(1);
expect(listAccessibleDetails).toHaveBeenCalledWith(
expect.objectContaining({ principals: resolvedPrincipals }),
);
expect(getAppConfig).toHaveBeenCalledWith(
expect.objectContaining({
resolvedPrincipals,
skipRuntimeAugmentation: true,
}),
);
expect(listAccessible).not.toHaveBeenCalled();
expect(listAccessibleConfigurations).not.toHaveBeenCalled();
});
test('lists only principal control planes present in the caller effective policy', async () => {
const getAppConfig = jest.fn().mockResolvedValue({
endpoints: { [EModelEndpoint.agents]: { statefulCodeSessions: { environments: [] } } },
} as unknown as AppConfig);
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig,
registry: {
register: jest.fn(),
listAccessible: jest.fn().mockResolvedValue([]),
remove: jest.fn(),
},
principalAuthEnabled: () => true,
});
const res = response();
await handlers.list(
{
user: {
id: '68b2f0c498f24c1e78fa0001',
role: 'USER',
tenantId: 'tenant-1',
},
} as never,
res as never,
);
expect(res.body).toEqual({ environments: [], controlPlanes: [] });
expect(getAppConfig).toHaveBeenCalledWith({
role: 'USER',
userId: '68b2f0c498f24c1e78fa0001',
idOnTheSource: undefined,
tenantId: 'tenant-1',
failClosed: true,
skipRuntimeAugmentation: true,
});
});
test('returns 400 when registration has no request body', async () => {
const register = jest.fn();
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn(),
registry: { register, listAccessible: jest.fn(), remove: jest.fn() },
});
const res = response();
await handlers.register(
{ user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' }, body: null } as never,
res as never,
);
expect(res.statusCode).toBe(400);
expect(register).not.toHaveBeenCalled();
});
test('updates settings only through the selected control plane config schema', async () => {
const updateSettings = jest.fn().mockResolvedValue({
resourceId: '68b2f0c498f24c1e78fa0111',
id: 'personal-vm',
name: 'Personal VM',
type: 'attached',
canDelete: true,
});
const configSchema = {
permissions: {
fileWrite: { allowed: ['allow', 'ask', 'deny'] as const, default: 'ask' as const },
},
};
const resolvedPrincipals = [
{ principalType: 'role', principalId: 'USER' },
{ principalType: 'user', principalId: '68b2f0c498f24c1e78fa0001' },
];
const resolvePrincipals = jest.fn().mockResolvedValue(resolvedPrincipals);
const listAccessibleConfigurations = jest.fn().mockResolvedValue([
{
id: 'personal-vm',
name: 'Personal VM',
type: 'attached',
baseURL: 'https://code.example.com/v1',
controlPlaneId: 'self-service',
owner: 'principal',
},
]);
const getAppConfig = jest.fn().mockResolvedValue({
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
environments: [
{
id: 'self-service',
name: 'Self service',
type: 'attached',
baseURL: 'https://code.example.com/v1',
owner: 'deployment',
configSchema,
},
],
},
},
},
} as unknown as AppConfig);
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig,
registry: {
register: jest.fn(),
listAccessible: jest.fn(),
listAccessibleConfigurations,
resolvePrincipals,
updateSettings,
remove: jest.fn(),
},
});
const res = response();
await handlers.updateSettings(
{
user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' },
params: { environmentId: 'personal-vm' },
body: { settings: { permissions: { fileWrite: 'allow' } } },
} as never,
res as never,
);
expect(res.statusCode).toBe(200);
expect(resolvePrincipals).toHaveBeenCalledTimes(1);
expect(listAccessibleConfigurations).toHaveBeenCalledWith(
expect.objectContaining({ principals: resolvedPrincipals }),
);
expect(getAppConfig).toHaveBeenCalledWith(
expect.objectContaining({ resolvedPrincipals, skipRuntimeAugmentation: true }),
);
expect(updateSettings).toHaveBeenCalledWith({
actor: expect.objectContaining({
userId: '68b2f0c498f24c1e78fa0001',
principals: resolvedPrincipals,
}),
environmentId: 'personal-vm',
settings: { permissions: { fileWrite: 'allow' } },
});
expect(res.body).toEqual({
environment: expect.objectContaining({
id: 'personal-vm',
configSchema,
settings: { permissions: { fileWrite: 'allow' } },
}),
});
});
test.each([
[undefined, undefined, 5],
[{ maxPerUser: 100 }, { maxPerUser: 100 }, 100],
[{ maxPerUser: 100 }, { maxPerUser: 20 }, 20],
[{ maxPerUser: 10 }, { maxPerUser: 100 }, 10],
[{ enabled: false }, { enabled: true }, 0],
[{ maxPerUser: 10 }, { maxPerUser: 0 }, 0],
])(
'pairs with deployment %j and effective policy %j (limit %i)',
async (deployment, effective, limit) => {
const register = jest.fn().mockResolvedValue({
resourceId: '68b2f0c498f24c1e78fa0111',
id: 'code-generated',
name: 'Personal VM',
type: 'attached',
});
const fetchImpl = jest.fn().mockResolvedValue({
ok: true,
json: jest.fn().mockResolvedValue({
protocolVersion: 1,
workerId: 'code-generated',
code: 'a'.repeat(32),
expiresAt: new Date(Date.now() + 60_000).toISOString(),
}),
});
const appConfig = {
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
allowedEnvironments: ['user'],
environments: [
{
id: 'shared-code-api',
name: 'Shared Code API',
type: 'attached',
baseURL: 'https://code.librechat.example/v1',
owner: 'deployment',
pairing: {
allowPrincipalWorkers: true,
tokenEnv: 'CODE_ADMIN_TOKEN',
},
},
],
},
},
},
} as AppConfig;
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn(
async (options) =>
({
...appConfig,
endpoints: {
...appConfig.endpoints,
agents: {
...appConfig.endpoints?.agents,
statefulCodeSessions: {
...appConfig.endpoints?.agents?.statefulCodeSessions,
principalWorkers: options?.baseOnly ? deployment : effective,
},
},
},
}) as AppConfig,
),
registry: {
register,
listAccessible: jest.fn().mockResolvedValue([{ id: 'existing-machine' }]),
remove: jest.fn(),
},
createEnvironmentId: () => 'code-generated',
readSecret: jest.fn(() => 'administrator-token'),
resolveTenantId: jest.fn(() => 'tenant-1'),
principalAuthEnabled: jest.fn(() => true),
principalAuthReady: jest.fn(),
fetchImpl,
});
const req = {
user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' },
body: {
name: 'Personal VM',
controlPlaneId: 'shared-code-api',
workerId: 'attacker-worker',
baseURL: 'https://attacker.example',
},
};
const res = response();
await handlers.pair(req as never, res as never);
if (limit === 0) {
expect(res.statusCode).toBe(403);
expect(fetchImpl).not.toHaveBeenCalled();
expect(register).not.toHaveBeenCalled();
const discovery = response();
await handlers.list(req as never, discovery as never);
expect(discovery.statusCode).toBe(200);
expect(discovery.body).toEqual({
environments: [{ id: 'existing-machine' }],
controlPlanes: [],
});
return;
}
expect(res.statusCode).toBe(201);
expect(fetchImpl).toHaveBeenCalledWith(
'https://code.librechat.example/v1/bridge/pairings',
expect.objectContaining({
method: 'POST',
headers: expect.objectContaining({ Authorization: 'Bearer administrator-token' }),
body: JSON.stringify({
workerId: 'code-generated',
binding: {
tenantId: 'tenant-1',
principal: { type: 'user', id: '68b2f0c498f24c1e78fa0001' },
},
}),
}),
);
expect(register).toHaveBeenCalledWith({
actor: {
userId: '68b2f0c498f24c1e78fa0001',
role: 'USER',
idOnTheSource: null,
},
maxOwned: limit,
environment: {
id: 'code-generated',
name: 'Personal VM',
type: 'attached' as const,
baseURL: 'https://code.librechat.example/v1',
workerId: 'code-generated',
controlPlaneId: 'shared-code-api',
revocationTokenEnv: 'CODE_ADMIN_TOKEN',
workerPrincipal: { type: 'user', id: '68b2f0c498f24c1e78fa0001' },
},
});
expect(res.body).toEqual({
environment: expect.objectContaining({ id: 'code-generated' }),
pairing: expect.objectContaining({
workerId: 'code-generated',
code: 'a'.repeat(32),
endpoint: 'https://code.librechat.example/v1',
}),
});
},
);
test('revokes an upstream pairing when the atomic owner quota is exhausted', async () => {
const fetchImpl = jest.fn(
async (input: string | URL | Request) =>
({
ok: true,
json: async () =>
String(input).endsWith('/bridge/pairings')
? {
protocolVersion: 1,
workerId: 'code-generated',
code: 'a'.repeat(32),
expiresAt: new Date(Date.now() + 60_000).toISOString(),
}
: { protocolVersion: 1, revoked: true },
}) as Response,
);
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn().mockResolvedValue({
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
allowedEnvironments: ['user'],
environments: [
{
id: 'shared-code-api',
name: 'Shared Code API',
type: 'attached',
baseURL: 'https://code.librechat.example/v1',
owner: 'deployment',
pairing: {
allowPrincipalWorkers: true,
tokenEnv: 'CODE_ADMIN_TOKEN',
},
},
],
},
},
},
} as AppConfig),
registry: {
register: jest.fn().mockRejectedValue(new CodeEnvironmentLimitError()),
listAccessible: jest.fn(),
remove: jest.fn(),
},
createEnvironmentId: () => 'code-generated',
readSecret: () => 'administrator-token',
principalAuthEnabled: () => true,
principalAuthReady: jest.fn().mockResolvedValue(undefined),
fetchImpl,
});
const res = response();
await handlers.pair(
{
user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' },
body: { name: 'Personal VM', controlPlaneId: 'shared-code-api' },
} as never,
res as never,
);
expect(res.statusCode).toBe(409);
expect(res.body).toEqual({ error: 'Personal code environment limit reached' });
expect(fetchImpl).toHaveBeenCalledWith(
'https://code.librechat.example/v1/bridge/workers/code-generated/revoke',
expect.objectContaining({ method: 'POST' }),
);
});
test('returns 503 without issuing a pairing when the initial principal check is unavailable', async () => {
const fetchImpl = jest.fn();
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn().mockResolvedValue({
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
allowedEnvironments: ['user'],
environments: [
{
id: 'shared-code-api',
name: 'Shared Code API',
type: 'attached',
baseURL: 'https://code.librechat.example/v1',
owner: 'deployment',
pairing: { allowPrincipalWorkers: true, tokenEnv: 'CODE_ADMIN_TOKEN' },
},
],
},
},
},
} as AppConfig),
registry: { register: jest.fn(), listAccessible: jest.fn(), remove: jest.fn() },
createEnvironmentId: () => 'code-generated',
readSecret: () => 'administrator-token',
principalAuthEnabled: () => true,
principalAuthReady: jest.fn(),
principalIsActive: jest.fn().mockRejectedValue(new Error('user store unavailable')),
fetchImpl,
});
const res = response();
await handlers.pair(
{
user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' },
body: { name: 'Personal VM', controlPlaneId: 'shared-code-api' },
} as never,
res as never,
);
expect(res.statusCode).toBe(503);
expect(res.body).toEqual({ error: 'Account status could not be confirmed' });
expect(fetchImpl).not.toHaveBeenCalled();
});
test('revokes through the registry fence when the principal becomes inactive after registration', async () => {
const remove = jest.fn(
async ({ beforeDelete }: { beforeDelete?: (target: never) => Promise<void> }) => {
await beforeDelete?.({} as never);
return { id: 'code-generated' } as never;
},
);
const principalIsActive = jest
.fn()
.mockResolvedValueOnce(true)
.mockResolvedValueOnce(true)
.mockResolvedValueOnce(false);
const fetchImpl = jest.fn(
async (input: string | URL | Request) =>
({
ok: true,
json: async () =>
String(input).endsWith('/bridge/pairings')
? {
protocolVersion: 1,
workerId: 'code-generated',
code: 'a'.repeat(32),
expiresAt: new Date(Date.now() + 60_000).toISOString(),
}
: { protocolVersion: 1, revoked: true },
}) as Response,
);
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn().mockResolvedValue({
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
allowedEnvironments: ['user'],
environments: [
{
id: 'shared-code-api',
name: 'Shared Code API',
type: 'attached',
baseURL: 'https://code.librechat.example/v1',
owner: 'deployment',
pairing: { allowPrincipalWorkers: true, tokenEnv: 'CODE_ADMIN_TOKEN' },
},
],
},
},
},
} as AppConfig),
registry: {
register: jest.fn().mockResolvedValue({ id: 'code-generated' }),
listAccessible: jest.fn(),
remove,
},
createEnvironmentId: () => 'code-generated',
readSecret: () => 'administrator-token',
principalAuthEnabled: () => true,
principalAuthReady: jest.fn(),
principalIsActive,
fetchImpl,
});
const res = response();
await handlers.pair(
{
user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' },
body: { name: 'Personal VM', controlPlaneId: 'shared-code-api' },
} as never,
res as never,
);
expect(res.statusCode).toBe(409);
expect(remove).toHaveBeenCalledWith(
expect.objectContaining({
environmentId: 'code-generated',
beforeDelete: expect.any(Function),
}),
);
expect(fetchImpl).toHaveBeenLastCalledWith(
'https://code.librechat.example/v1/bridge/workers/code-generated/revoke',
expect.objectContaining({ method: 'POST' }),
);
});
test('persists cleanup intent before compensating a registered pairing after removal fails', async () => {
const markRevocationPending = jest.fn().mockResolvedValue(undefined);
const remove = jest.fn().mockRejectedValue(new Error('registry removal failed'));
const principalIsActive = jest
.fn()
.mockResolvedValueOnce(true)
.mockResolvedValueOnce(true)
.mockResolvedValueOnce(false);
const fetchImpl = jest.fn(
async (input: string | URL | Request) =>
({
ok: true,
json: async () =>
String(input).endsWith('/bridge/pairings')
? {
protocolVersion: 1,
workerId: 'code-generated',
code: 'a'.repeat(32),
expiresAt: new Date(Date.now() + 60_000).toISOString(),
}
: { protocolVersion: 1, revoked: true },
}) as Response,
);
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn().mockResolvedValue({
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
allowedEnvironments: ['user'],
environments: [
{
id: 'shared-code-api',
name: 'Shared Code API',
type: 'attached',
baseURL: 'https://code.librechat.example/v1',
owner: 'deployment',
pairing: { allowPrincipalWorkers: true, tokenEnv: 'CODE_ADMIN_TOKEN' },
},
],
},
},
},
} as AppConfig),
registry: {
register: jest.fn().mockResolvedValue({ id: 'code-generated' }),
listAccessible: jest.fn(),
remove,
markRevocationPending,
},
createEnvironmentId: () => 'code-generated',
readSecret: () => 'administrator-token',
principalAuthEnabled: () => true,
principalAuthReady: jest.fn(),
principalIsActive,
fetchImpl,
});
const res = response();
await handlers.pair(
{
user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' },
body: { name: 'Personal VM', controlPlaneId: 'shared-code-api' },
} as never,
res as never,
);
expect(res.statusCode).toBe(500);
expect(markRevocationPending).toHaveBeenCalledWith('code-generated');
expect(markRevocationPending.mock.invocationCallOrder[0]).toBeLessThan(
fetchImpl.mock.invocationCallOrder[fetchImpl.mock.invocationCallOrder.length - 1] ?? 0,
);
});
test('revokes an issued pairing when the post-issue principal check is unavailable', async () => {
const register = jest.fn();
const principalIsActive = jest
.fn()
.mockResolvedValueOnce(true)
.mockRejectedValueOnce(new Error('user store unavailable'));
const fetchImpl = jest.fn(
async (input: string | URL | Request) =>
({
ok: true,
json: async () =>
String(input).endsWith('/bridge/pairings')
? {
protocolVersion: 1,
workerId: 'code-generated',
code: 'a'.repeat(32),
expiresAt: new Date(Date.now() + 60_000).toISOString(),
}
: { protocolVersion: 1, revoked: true },
}) as Response,
);
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn().mockResolvedValue({
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
allowedEnvironments: ['user'],
environments: [
{
id: 'shared-code-api',
name: 'Shared Code API',
type: 'attached',
baseURL: 'https://code.librechat.example/v1',
owner: 'deployment',
pairing: { allowPrincipalWorkers: true, tokenEnv: 'CODE_ADMIN_TOKEN' },
},
],
},
},
},
} as AppConfig),
registry: { register, listAccessible: jest.fn(), remove: jest.fn() },
createEnvironmentId: () => 'code-generated',
readSecret: () => 'administrator-token',
principalAuthEnabled: () => true,
principalAuthReady: jest.fn(),
principalIsActive,
fetchImpl,
});
const res = response();
await handlers.pair(
{
user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' },
body: { name: 'Personal VM', controlPlaneId: 'shared-code-api' },
} as never,
res as never,
);
expect(res.statusCode).toBe(503);
expect(register).not.toHaveBeenCalled();
expect(fetchImpl).toHaveBeenLastCalledWith(
'https://code.librechat.example/v1/bridge/workers/code-generated/revoke',
expect.objectContaining({ method: 'POST' }),
);
});
test('rejects self-service pairing without principal-aware Code API auth', async () => {
const fetchImpl = jest.fn();
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn(),
registry: { register: jest.fn(), listAccessible: jest.fn(), remove: jest.fn() },
principalAuthEnabled: jest.fn(() => false),
fetchImpl,
});
const res = response();
await handlers.pair(
{
user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' },
body: { name: 'Personal VM', controlPlaneId: 'self-service' },
} as never,
res as never,
);
expect(res.statusCode).toBe(409);
expect(fetchImpl).not.toHaveBeenCalled();
});
test('does not pair through a control plane removed from the caller effective config', async () => {
const fetchImpl = jest.fn();
const baseConfig = {
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
environments: [
{
id: 'self-service',
name: 'Self-service',
type: 'attached',
baseURL: 'https://code.librechat.example',
owner: 'deployment',
pairing: { allowPrincipalWorkers: true, tokenEnv: 'CODE_ADMIN_TOKEN' },
},
],
},
},
},
} as AppConfig;
const effectiveConfig = {
endpoints: { [EModelEndpoint.agents]: { statefulCodeSessions: { environments: [] } } },
} as unknown as AppConfig;
const getAppConfig = jest.fn(async (options) =>
options.baseOnly === true ? baseConfig : effectiveConfig,
);
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig,
registry: { register: jest.fn(), listAccessible: jest.fn(), remove: jest.fn() },
readSecret: jest.fn(() => 'administrator-token'),
principalAuthEnabled: jest.fn(() => true),
principalAuthReady: jest.fn(),
fetchImpl,
});
const res = response();
await handlers.pair(
{
user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER', tenantId: 'tenant-1' },
body: { name: 'Personal VM', controlPlaneId: 'self-service' },
} as never,
res as never,
);
expect(res.statusCode).toBe(404);
expect(getAppConfig).toHaveBeenCalledWith({
role: 'USER',
userId: '68b2f0c498f24c1e78fa0001',
idOnTheSource: undefined,
tenantId: 'tenant-1',
failClosed: true,
});
expect(fetchImpl).not.toHaveBeenCalled();
});
test('fails closed when effective pairing policy cannot be loaded', async () => {
const fetchImpl = jest.fn();
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn(async (options) => {
if (options.baseOnly === true) return {} as AppConfig;
throw new Error('authorization unavailable');
}),
registry: { register: jest.fn(), listAccessible: jest.fn(), remove: jest.fn() },
principalAuthEnabled: jest.fn(() => true),
principalAuthReady: jest.fn(),
fetchImpl,
});
const res = response();
await handlers.pair(
{
user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' },
body: { name: 'Personal VM', controlPlaneId: 'self-service' },
} as never,
res as never,
);
expect(res.statusCode).toBe(503);
expect(fetchImpl).not.toHaveBeenCalled();
});
test('authorizes pairing effectively but resolves destinations and secrets from deployment config', async () => {
const fetchImpl = jest.fn().mockResolvedValue({
ok: true,
json: jest.fn().mockResolvedValue({
protocolVersion: 1,
workerId: 'code-generated',
code: 'a'.repeat(32),
expiresAt: new Date(Date.now() + 60_000).toISOString(),
}),
});
const deploymentConfig = {
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
environments: [
{
id: 'self-service',
name: 'Self-service',
type: 'attached',
baseURL: 'https://code.librechat.example',
owner: 'deployment',
pairing: { allowPrincipalWorkers: true, tokenEnv: 'CODE_ADMIN_TOKEN' },
},
],
},
},
},
} as AppConfig;
const effectiveConfig = {
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
environments: [
{
id: 'self-service',
name: 'Override attempt',
type: 'attached',
baseURL: 'https://attacker.example',
owner: 'deployment',
pairing: { allowPrincipalWorkers: true, tokenEnv: 'DATABASE_URL' },
},
],
},
},
},
} as AppConfig;
const readSecret = jest.fn((name) =>
name === 'CODE_ADMIN_TOKEN' ? 'administrator-token' : 'database-secret',
);
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn(async (options) =>
options.baseOnly === true ? deploymentConfig : effectiveConfig,
),
registry: {
register: jest.fn().mockResolvedValue({ id: 'code-generated' }),
listAccessible: jest.fn(),
remove: jest.fn(),
},
createEnvironmentId: () => 'code-generated',
readSecret,
resolveTenantId: jest.fn(() => 'tenant-1'),
principalAuthEnabled: jest.fn(() => true),
principalAuthReady: jest.fn(),
fetchImpl,
});
const res = response();
await handlers.pair(
{
user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' },
body: { name: 'Personal VM', controlPlaneId: 'self-service' },
} as never,
res as never,
);
expect(res.statusCode).toBe(201);
expect(readSecret).toHaveBeenCalledWith('CODE_ADMIN_TOKEN');
expect(readSecret).not.toHaveBeenCalledWith('DATABASE_URL');
expect(fetchImpl).toHaveBeenCalledWith(
'https://code.librechat.example/bridge/pairings',
expect.any(Object),
);
});
test('validates JWT signing before creating upstream pairing state', async () => {
const fetchImpl = jest.fn();
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn(),
registry: { register: jest.fn(), listAccessible: jest.fn(), remove: jest.fn() },
principalAuthEnabled: jest.fn(() => true),
principalAuthReady: jest.fn(() => {
throw new Error('invalid signing key');
}),
fetchImpl,
});
const res = response();
await handlers.pair(
{
user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' },
body: { name: 'Personal VM', controlPlaneId: 'self-service' },
} as never,
res as never,
);
expect(res.statusCode).toBe(503);
expect(fetchImpl).not.toHaveBeenCalled();
});
test('registers against an operator-configured control plane and ignores client URLs', async () => {
const register = jest.fn().mockResolvedValue({
resourceId: '68b2f0c498f24c1e78fa0111',
id: 'personal-vm',
name: 'Personal VM',
type: 'attached',
});
const appConfig = {
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
allowedEnvironments: ['user'],
environments: [
{
id: 'shared-code-api',
name: 'Shared Code API',
type: 'attached',
baseURL: 'https://code.librechat.example',
owner: 'deployment',
pairing: { workerId: 'deployment-worker', tokenEnv: 'CODE_ADMIN_TOKEN' },
},
],
},
},
},
} as AppConfig;
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn().mockResolvedValue(appConfig),
registry: { register, listAccessible: jest.fn(), remove: jest.fn() },
createEnvironmentId: () => 'personal-vm',
});
const req = {
user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' },
body: {
name: 'Personal VM',
controlPlaneId: 'shared-code-api',
workerId: 'attacker-worker',
baseURL: 'https://attacker.example',
},
};
const res = response();
await handlers.register(req as never, res as never);
expect(res.statusCode).toBe(201);
expect(register).toHaveBeenCalledWith({
actor: {
userId: '68b2f0c498f24c1e78fa0001',
role: 'USER',
idOnTheSource: null,
},
environment: {
id: 'personal-vm',
name: 'Personal VM',
type: 'attached',
baseURL: 'https://code.librechat.example',
controlPlaneId: 'shared-code-api',
workerId: 'deployment-worker',
workerPrincipal: { type: 'deployment', id: 'shared-code-api' },
},
});
});
test('removes a fixed environment when its principal becomes inactive after registration', async () => {
const register = jest.fn().mockResolvedValue({
resourceId: '68b2f0c498f24c1e78fa0111',
id: 'personal-vm',
name: 'Personal VM',
type: 'attached',
});
const remove = jest.fn().mockResolvedValue({ id: 'personal-vm' });
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn().mockResolvedValue({
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
environments: [
{
id: 'shared-code-api',
name: 'Shared Code API',
type: 'attached',
baseURL: 'https://code.librechat.example',
owner: 'deployment',
pairing: { workerId: 'deployment-worker' },
},
],
},
},
},
} as AppConfig),
registry: { register, listAccessible: jest.fn(), remove },
createEnvironmentId: () => 'personal-vm',
principalIsActive: jest.fn().mockResolvedValueOnce(true).mockResolvedValueOnce(false),
});
const res = response();
await handlers.register(
{
user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' },
body: { name: 'Personal VM', controlPlaneId: 'shared-code-api' },
} as never,
res as never,
);
expect(res.statusCode).toBe(409);
expect(remove).toHaveBeenCalledWith({
actor: {
userId: '68b2f0c498f24c1e78fa0001',
role: 'USER',
idOnTheSource: null,
},
environmentId: 'personal-vm',
});
});
test('returns 503 without fixed registration when the principal check is unavailable', async () => {
const register = jest.fn();
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn().mockResolvedValue({
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
environments: [
{
id: 'shared-code-api',
name: 'Shared Code API',
type: 'attached',
baseURL: 'https://code.librechat.example',
owner: 'deployment',
pairing: { workerId: 'deployment-worker' },
},
],
},
},
},
} as AppConfig),
registry: { register, listAccessible: jest.fn(), remove: jest.fn() },
principalIsActive: jest.fn().mockRejectedValue(new Error('user store unavailable')),
});
const res = response();
await handlers.register(
{
user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' },
body: { name: 'Personal VM', controlPlaneId: 'shared-code-api' },
} as never,
res as never,
);
expect(res.statusCode).toBe(503);
expect(register).not.toHaveBeenCalled();
});
test('does not register a fixed environment on a self-service-only control plane', async () => {
const register = jest.fn();
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn().mockResolvedValue({
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
allowedEnvironments: ['user'],
environments: [
{
id: 'self-service',
name: 'Self-service',
type: 'attached',
baseURL: 'https://code.librechat.example',
owner: 'deployment',
pairing: {
allowPrincipalWorkers: true,
tokenEnv: 'CODE_ADMIN_TOKEN',
},
},
],
},
},
},
} as AppConfig),
registry: { register, listAccessible: jest.fn(), remove: jest.fn() },
});
const res = response();
await handlers.register(
{
user: { id: '68b2f0c498f24c1e78fa0001', role: 'ADMIN' },
body: { name: 'Invalid fixed route', controlPlaneId: 'self-service' },
} as never,
res as never,
);
expect(res.statusCode).toBe(404);
expect(register).not.toHaveBeenCalled();
});
test('validates a pairing name before creating upstream state', async () => {
const fetchImpl = jest.fn();
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn().mockResolvedValue({
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
allowedEnvironments: ['user'],
environments: [
{
id: 'self-service',
name: 'Self-service',
type: 'attached',
baseURL: 'https://code.librechat.example',
owner: 'deployment',
pairing: {
allowPrincipalWorkers: true,
tokenEnv: 'CODE_ADMIN_TOKEN',
},
},
],
},
},
},
} as AppConfig),
registry: { register: jest.fn(), listAccessible: jest.fn(), remove: jest.fn() },
readSecret: jest.fn(() => 'administrator-token'),
principalAuthEnabled: jest.fn(() => true),
principalAuthReady: jest.fn(),
fetchImpl,
});
const res = response();
await handlers.pair(
{
user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' },
body: { name: 'x'.repeat(101), controlPlaneId: 'self-service' },
} as never,
res as never,
);
expect(res.statusCode).toBe(400);
expect(fetchImpl).not.toHaveBeenCalled();
});
test('revokes a user-bound worker before deleting its registry entry', async () => {
const remove = jest.fn(async ({ beforeDelete }) => {
await beforeDelete({
resourceId: '68b2f0c498f24c1e78fa0111',
id: 'code-generated',
name: 'Personal VM',
type: 'attached',
baseURL: 'https://code.librechat.example/v1',
workerId: 'code-generated',
controlPlaneId: 'self-service',
revocationTokenEnv: 'CODE_ADMIN_TOKEN',
workerPrincipal: { type: 'user', id: '68b2f0c498f24c1e78fa0001' },
});
return {
resourceId: '68b2f0c498f24c1e78fa0111',
id: 'code-generated',
name: 'Personal VM',
type: 'attached' as const,
canDelete: true,
};
});
const fetchImpl = jest.fn().mockResolvedValue({
ok: true,
json: async () => ({ protocolVersion: 1, revoked: true }),
});
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn().mockResolvedValue({
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
allowedEnvironments: ['user'],
environments: [
{
id: 'self-service',
name: 'Self-service',
type: 'attached',
baseURL: 'https://code.librechat.example/v1',
owner: 'deployment',
pairing: {
allowPrincipalWorkers: true,
tokenEnv: 'CODE_ADMIN_TOKEN',
},
},
],
},
},
},
} as AppConfig),
registry: { register: jest.fn(), listAccessible: jest.fn(), remove },
readSecret: jest.fn(() => 'administrator-token'),
fetchImpl,
});
const res = response();
await handlers.remove(
{
user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' },
params: { environmentId: 'code-generated' },
} as never,
res as never,
);
expect(res.statusCode).toBe(200);
expect(fetchImpl).toHaveBeenCalledWith(
'https://code.librechat.example/v1/bridge/workers/code-generated/revoke',
expect.objectContaining({
method: 'POST',
headers: { Authorization: 'Bearer administrator-token' },
}),
);
expect(remove).toHaveBeenCalled();
});
test.each([
{
error: new Error('mongo connection details'),
status: 500,
body: { error: 'Code environment registration failed' },
},
{
error: new CodeEnvironmentValidationError('Code environment id is invalid'),
status: 400,
body: { error: 'Code environment id is invalid' },
},
])('classifies registration failure with status $status', async ({ error, status, body }) => {
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn().mockResolvedValue({
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
environments: [
{
id: 'shared-code-api',
name: 'Shared Code API',
type: 'attached',
baseURL: 'https://code.librechat.example',
owner: 'deployment',
pairing: { workerId: 'deployment-worker' },
},
],
},
},
},
} as AppConfig),
registry: {
register: jest.fn().mockRejectedValue(error),
listAccessible: jest.fn(),
remove: jest.fn(),
},
});
const res = response();
await handlers.register(
{
user: { id: '68b2f0c498f24c1e78fa0001' },
body: { name: 'Personal VM', controlPlaneId: 'shared-code-api' },
} as never,
res as never,
);
expect(res.statusCode).toBe(status);
expect(res.body).toEqual(body);
});
});
describe('moving a sealed conversation code-environment decision', () => {
type Selection = { environmentId: string; workspaceId: string };
type StoredDecision = {
conversationId: string;
codeEnvironmentRevision?: number;
codeEnvironmentMode?: 'attached' | 'without_attached';
codeWorkspaces?: Selection[];
};
const userId = '68b2f0c498f24c1e78fa0001';
const mac: Selection = { environmentId: 'mac', workspaceId: 'primary' };
const vm: Selection = { environmentId: 'personal-vm', workspaceId: 'project-a' };
const controlPlane = {
id: 'self-service',
name: 'Self service',
type: 'attached' as const,
baseURL: 'https://code.example.com/v1',
owner: 'deployment' as const,
pairing: { allowPrincipalWorkers: true, tokenEnv: 'CODE_ADMIN_TOKEN' },
};
function workerStatusResponse({
ready = true,
workspaces = [{ id: 'project-a', name: 'Project A' }],
}: { ready?: boolean; workspaces?: Array<{ id: string; name?: string }> } = {}) {
return new Response(
JSON.stringify({
protocolVersion: 1,
workerId: 'personal-vm',
online: true,
ready,
leaseExpiresInMs: 50_000,
capabilities: {
sandboxProfile: 'native-srt',
runtimes: ['bash'],
workspaceTools: { protocolVersion: 1, operations: ['read_file'], workspaces },
},
}),
);
}
function setup({
movesEnabled = true,
checkoutEnabled = false,
allowAttachDetach = true,
stored = {
conversationId: 'conversation-1',
codeEnvironmentMode: 'attached',
codeWorkspaces: [mac],
},
job,
conversationRunIds = [],
fetchImpl = jest.fn().mockImplementation(async () => workerStatusResponse()),
}: {
movesEnabled?: boolean;
checkoutEnabled?: boolean;
allowAttachDetach?: boolean;
stored?: StoredDecision;
job?: CodeEnvironmentGenerationJob;
conversationRunIds?: string[];
fetchImpl?: jest.Mock;
} = {}) {
const conversations = new Map<string, StoredDecision>([[stored.conversationId, stored]]);
const listConversationRuns = jest.fn(async () => conversationRunIds);
const getConversation = jest.fn(async (user: string, conversationId: string) =>
user === userId ? (conversations.get(conversationId) ?? null) : null,
);
/** Mirrors the data-schemas compare-and-swap: the write lands only on the decision it read. */
const replaceDecision = jest.fn(
async ({
conversationId,
expected,
codeEnvironmentMode,
codeWorkspaces,
}: {
conversationId: string;
expected: Pick<StoredDecision, 'codeEnvironmentMode' | 'codeWorkspaces'> & {
codeEnvironmentRevision?: number;
};
codeEnvironmentMode: StoredDecision['codeEnvironmentMode'];
codeWorkspaces?: Selection[];
}) => {
const current = conversations.get(conversationId);
const decisionOf = (decision: Partial<StoredDecision> | undefined) =>
JSON.stringify([
decision?.codeEnvironmentMode ?? null,
decision?.codeWorkspaces ?? null,
(decision as { codeEnvironmentRevision?: number })?.codeEnvironmentRevision ?? null,
]);
if (current == null || decisionOf(current) !== decisionOf(expected)) {
return null;
}
/** Mirrors the stored shape: leaving attached execution clears the selections. */
const moved: StoredDecision =
codeEnvironmentMode === 'attached'
? { ...current, codeEnvironmentMode, codeWorkspaces }
: { conversationId: current.conversationId, codeEnvironmentMode };
conversations.set(conversationId, moved);
return moved;
},
);
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn().mockResolvedValue({
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
environments: [
{
...controlPlane,
configSchema: { workspaces: { allowCheckoutSelection: checkoutEnabled } },
},
],
conversationMoves: { enabled: movesEnabled, allowAttachDetach },
},
},
},
} as unknown as AppConfig),
registry: {
register: jest.fn(),
listAccessible: jest.fn(),
listAccessibleConfigurations: jest.fn().mockResolvedValue([
{
id: 'personal-vm',
name: 'Personal VM',
type: 'attached',
baseURL: 'https://stale.example.com/v1',
controlPlaneId: 'self-service',
owner: 'principal',
workerId: 'personal-vm',
},
]),
remove: jest.fn(),
},
readSecret: jest.fn(() => 'administrator-token'),
fetchImpl,
conversations: {
get: getConversation,
replaceDecision,
},
generations: {
getJob: async () => job ?? null,
getCleanupBlockingJobIdsForConversations: listConversationRuns,
},
});
const move = async (
body: { from?: unknown; to?: unknown },
conversationId = 'conversation-1',
) => {
const res = response();
await handlers.moveConversationDecision(
{ user: { id: userId, role: 'USER' }, params: { conversationId }, body } as never,
res as never,
);
return res;
};
const status = async () => {
const res = response();
await handlers.status(
{
user: { id: userId, role: 'USER' },
params: { environmentId: vm.environmentId },
} as never,
res as never,
);
return res;
};
return {
move,
status,
conversations,
getConversation,
listConversationRuns,
replaceDecision,
fetchImpl,
};
}
test.each([
{ checkout: 'source', enabled: false, capable: true, accepted: false },
{ checkout: 'isolated', enabled: true, capable: false, accepted: false },
{ checkout: 'isolated', enabled: false, capable: true, accepted: false },
{ checkout: 'source', enabled: true, capable: false, accepted: true },
{ checkout: 'isolated', enabled: true, capable: true, accepted: true },
] as const)(
'validates checkout before persisting a move: %j',
async ({ checkout, enabled, capable, accepted }) => {
const { move, replaceDecision } = setup({
checkoutEnabled: enabled,
fetchImpl: jest.fn(async () =>
workerStatusResponse({
workspaces: [
{ id: vm.workspaceId, ...(capable ? { workspaceInstances: ['git_worktree'] } : {}) },
],
}),
),
});
const to = [{ ...vm, checkout }];
const res = await move({ from: [mac], to });
expect(res.statusCode).toBe(accepted ? 200 : 409);
if (accepted) {
expect(replaceDecision).toHaveBeenCalledWith(
expect.objectContaining({ codeWorkspaces: to }),
);
} else {
expect(res.body).toEqual(expect.objectContaining({ reason: 'unsupported' }));
expect(replaceDecision).not.toHaveBeenCalled();
}
},
);
test('moves a sealed decision onto a workspace the new machine registers', async () => {
const { move, conversations, fetchImpl } = setup();
const res = await move({ from: [mac], to: [vm] });
expect(res.statusCode).toBe(200);
expect(res.body).toEqual({
conversationId: 'conversation-1',
codeEnvironmentMode: 'attached',
codeWorkspaces: [vm],
});
expect(conversations.get('conversation-1')?.codeWorkspaces).toEqual([vm]);
expect(fetchImpl).toHaveBeenCalledTimes(1);
expect(fetchImpl).toHaveBeenCalledWith(
'https://code.example.com/v1/bridge/workers/personal-vm/status',
expect.objectContaining({ headers: { Authorization: 'Bearer administrator-token' } }),
);
});
test.each(['attached', undefined] as const)(
'recovers a missing workspace on the same machine with mode %s and keeps the new decision sealed',
async (codeEnvironmentMode) => {
const missing = { ...vm, workspaceId: 'deleted-project' };
const { move, conversations, fetchImpl } = setup({
stored: {
conversationId: 'conversation-1',
codeEnvironmentMode,
codeWorkspaces: [missing],
},
});
const res = await move({ from: [missing], to: [vm] });
expect(res.statusCode).toBe(200);
expect(conversations.get('conversation-1')).toEqual({
conversationId: 'conversation-1',
codeEnvironmentMode: 'attached',
codeWorkspaces: [vm],
});
expect(fetchImpl).toHaveBeenCalledTimes(1);
expect((await move({ from: [missing], to: [vm] })).statusCode).toBe(409);
expect(fetchImpl).toHaveBeenCalledTimes(1);
},
);
test.each([
{
name: 'old workspace restored',
workspaces: ['deleted-project', 'project-a'],
ready: true,
reason: 'locked',
},
{ name: 'replacement removed', workspaces: ['unrelated'], ready: true, reason: 'missing' },
{
name: 'worker unavailable',
workspaces: ['project-a'],
ready: false,
reason: 'worker_unavailable',
},
{ name: 'workspace still missing', workspaces: ['project-a'], ready: true, reason: undefined },
])(
'revalidates recovery after a cached status poll: $name',
async ({ workspaces, ready, reason }) => {
jest.spyOn(Date, 'now').mockReturnValue(1_000);
const old = { ...vm, workspaceId: 'deleted-project' };
const fetchImpl = jest
.fn()
.mockImplementationOnce(async () => workerStatusResponse())
.mockImplementation(async () =>
workerStatusResponse({ workspaces: workspaces.map((id) => ({ id })), ready }),
);
const { move, status, conversations, replaceDecision } = setup({
stored: { conversationId: 'conversation-1', codeWorkspaces: [old] },
fetchImpl,
});
expect((await status()).statusCode).toBe(200);
expect((await status()).statusCode).toBe(200);
expect(fetchImpl).toHaveBeenCalledTimes(1);
const res = await move({ from: [old], to: [vm] });
expect(fetchImpl).toHaveBeenCalledTimes(2);
expect(res.statusCode).toBe(reason == null ? 200 : 409);
if (reason != null) {
expect(res.body).toEqual(expect.objectContaining({ reason }));
expect(replaceDecision).not.toHaveBeenCalled();
}
expect(conversations.get('conversation-1')?.codeWorkspaces).toEqual(
reason == null ? [vm] : [old],
);
},
);
test('refuses replacement if the old workspace is still registered or was restored', async () => {
const old = { ...vm, workspaceId: 'old-project' };
const { move, conversations, replaceDecision, fetchImpl } = setup({
stored: { conversationId: 'conversation-1', codeWorkspaces: [old] },
fetchImpl: jest.fn(async () =>
workerStatusResponse({ workspaces: [{ id: old.workspaceId }, { id: vm.workspaceId }] }),
),
});
const res = await move({ from: [old], to: [vm] });
expect(res.statusCode).toBe(409);
expect(res.body).toEqual(expect.objectContaining({ reason: 'locked' }));
expect(fetchImpl).toHaveBeenCalledTimes(1);
expect(replaceDecision).not.toHaveBeenCalled();
expect(conversations.get('conversation-1')?.codeWorkspaces).toEqual([old]);
});
test.each([
{ ready: false, workspaces: [{ id: vm.workspaceId }], reason: 'worker_unavailable' },
{ ready: true, workspaces: [{ id: 'unrelated' }], reason: 'missing' },
{ ready: true, workspaces: [], reason: 'worker_unavailable' },
])(
'leaves a missing decision untouched when recovery fails: $reason',
async ({ reason, ...status }) => {
const old = { ...vm, workspaceId: 'deleted-project' };
const { move, conversations, replaceDecision } = setup({
stored: { conversationId: 'conversation-1', codeWorkspaces: [old] },
fetchImpl: jest.fn(async () => workerStatusResponse(status)),
});
const res = await move({ from: [old], to: [vm] });
expect(res.statusCode).toBe(409);
expect(res.body).toEqual(expect.objectContaining({ reason }));
expect(replaceDecision).not.toHaveBeenCalled();
expect(conversations.get('conversation-1')?.codeWorkspaces).toEqual([old]);
},
);
test('moves a legacy decision that only stored its selections', async () => {
const { move, conversations } = setup({
stored: { conversationId: 'conversation-1', codeWorkspaces: [mac] },
});
const res = await move({ from: [mac], to: [vm] });
expect(res.statusCode).toBe(200);
expect(conversations.get('conversation-1')).toEqual({
conversationId: 'conversation-1',
codeEnvironmentMode: 'attached',
codeWorkspaces: [vm],
});
});
test.each([
{ name: 'running', job: { status: 'running' as const } },
{ name: 'awaiting approval', job: { status: 'requires_action' as const } },
{
name: 'settled but still saving its response',
job: { status: 'complete' as const, metadata: { terminalPersistencePending: true } },
},
])(
'refuses while a generation is $name, since it saves the decision it started with',
async ({ job }) => {
const { move, replaceDecision, fetchImpl } = setup({ job });
const res = await move({ from: [mac], to: [vm] });
expect(res.statusCode).toBe(409);
expect(fetchImpl).not.toHaveBeenCalled();
expect(replaceDecision).not.toHaveBeenCalled();
},
);
test('refuses while a remote run keyed by its response id still works on the conversation', async () => {
const { move, listConversationRuns, replaceDecision, fetchImpl } = setup({
conversationRunIds: ['resp_remote-run'],
});
const res = await move({ from: [mac], to: [vm] });
expect(res.statusCode).toBe(409);
expect(listConversationRuns).toHaveBeenCalledWith(userId, ['conversation-1'], undefined);
expect(fetchImpl).not.toHaveBeenCalled();
expect(replaceDecision).not.toHaveBeenCalled();
});
test('drops an environment the agents stopped using after revalidating the one it keeps', async () => {
const gone = { environmentId: 'gone-vm', workspaceId: 'root' };
const { move, conversations, fetchImpl } = setup({
stored: {
conversationId: 'conversation-1',
codeEnvironmentMode: 'attached',
codeWorkspaces: [gone, vm],
},
});
const res = await move({ from: [gone, vm], to: [vm] });
expect(res.statusCode).toBe(200);
expect(conversations.get('conversation-1')?.codeWorkspaces).toEqual([vm]);
expect(fetchImpl).toHaveBeenCalledTimes(1);
});
test('rejects a move whose kept workspace is no longer registered', async () => {
const gone = { environmentId: 'gone-vm', workspaceId: 'root' };
const { move, conversations, replaceDecision } = setup({
stored: {
conversationId: 'conversation-1',
codeEnvironmentMode: 'attached',
codeWorkspaces: [gone, vm],
},
fetchImpl: jest
.fn()
.mockImplementation(async () =>
workerStatusResponse({ workspaces: [{ id: 'another-project' }] }),
),
});
const res = await move({ from: [gone, vm], to: [vm] });
expect(res.statusCode).toBe(409);
expect(res.body).toEqual(expect.objectContaining({ reason: 'missing' }));
expect(replaceDecision).not.toHaveBeenCalled();
expect(conversations.get('conversation-1')?.codeWorkspaces).toEqual([gone, vm]);
});
test('attaches a workspace to a chat that recorded running without one', async () => {
const { move, conversations, fetchImpl } = setup({
stored: { conversationId: 'conversation-1', codeEnvironmentMode: 'without_attached' },
});
const res = await move({ from: [], to: [vm] });
expect(res.statusCode).toBe(200);
expect(res.body).toEqual({
conversationId: 'conversation-1',
codeEnvironmentMode: 'attached',
codeWorkspaces: [vm],
});
expect(conversations.get('conversation-1')).toEqual({
conversationId: 'conversation-1',
codeEnvironmentMode: 'attached',
codeWorkspaces: [vm],
});
/** The attached workspace is revalidated exactly like a move's target. */
expect(fetchImpl).toHaveBeenCalledTimes(1);
});
test('rejects attaching a workspace the machine does not register', async () => {
const { move, conversations, replaceDecision } = setup({
stored: { conversationId: 'conversation-1', codeEnvironmentMode: 'without_attached' },
fetchImpl: jest
.fn()
.mockImplementation(async () =>
workerStatusResponse({ workspaces: [{ id: 'another-project' }] }),
),
});
const res = await move({ from: [], to: [vm] });
expect(res.statusCode).toBe(409);
expect(res.body).toEqual(expect.objectContaining({ reason: 'missing' }));
expect(replaceDecision).not.toHaveBeenCalled();
expect(conversations.get('conversation-1')).toEqual({
conversationId: 'conversation-1',
codeEnvironmentMode: 'without_attached',
});
});
test('leaves an attached machine without polling it and clears the selections', async () => {
const { move, conversations, fetchImpl } = setup();
const res = await move({ from: [mac], to: [] });
expect(res.statusCode).toBe(200);
expect(res.body).toEqual({
conversationId: 'conversation-1',
codeEnvironmentMode: 'without_attached',
});
/** The machine a chat is leaving is usually the unreachable one; checking it would refuse the
* one transition that works while it is down. */
expect(fetchImpl).not.toHaveBeenCalled();
expect(conversations.get('conversation-1')).toEqual({
conversationId: 'conversation-1',
codeEnvironmentMode: 'without_attached',
});
});
test('refuses to leave while a generation is still running', async () => {
const { move, replaceDecision } = setup({ job: { status: 'running' } });
expect((await move({ from: [mac], to: [] })).statusCode).toBe(409);
expect(replaceDecision).not.toHaveBeenCalled();
});
/* Revalidating the target is a round trip to the worker, so the earlier checks are stale when it
* returns. A turn that starts in that window would run in the previous environment while the
* conversation reports the new one, and the swap would still succeed: the stored decision it
* expects is unchanged, because a run never rewrites one the conversation already holds. */
test('refuses when a generation starts while the target worker is being checked', async () => {
const job: CodeEnvironmentGenerationJob = {
status: 'complete',
metadata: { terminalPersistencePending: false },
};
const fetchImpl = jest.fn().mockImplementation(async () => {
job.status = 'running';
return workerStatusResponse();
});
const { move, conversations, replaceDecision } = setup({ job, fetchImpl });
const res = await move({ from: [mac], to: [vm] });
expect(res.statusCode).toBe(409);
expect(fetchImpl).toHaveBeenCalledTimes(1);
expect(replaceDecision).not.toHaveBeenCalled();
expect(conversations.get('conversation-1')?.codeWorkspaces).toEqual([mac]);
});
test('refuses when a remote run claims the conversation during that check', async () => {
const runIds: string[] = [];
const fetchImpl = jest.fn().mockImplementation(async () => {
runIds.push('resp_remote-run');
return workerStatusResponse();
});
const { move, replaceDecision } = setup({ conversationRunIds: runIds, fetchImpl });
expect((await move({ from: [mac], to: [vm] })).statusCode).toBe(409);
expect(replaceDecision).not.toHaveBeenCalled();
});
test('preserves moves but rejects attach and detach in a move-only deployment', async () => {
const context = setup({ allowAttachDetach: false });
expect((await context.move({ from: [mac], to: [] })).statusCode).toBe(403);
expect(context.replaceDecision).not.toHaveBeenCalled();
expect((await context.move({ from: [mac], to: [vm] })).statusCode).toBe(200);
const unattached = setup({
allowAttachDetach: false,
stored: {
conversationId: 'conversation-1',
codeEnvironmentMode: 'without_attached',
},
});
expect((await unattached.move({ from: [], to: [vm] })).statusCode).toBe(403);
expect(unattached.fetchImpl).not.toHaveBeenCalled();
expect(unattached.replaceDecision).not.toHaveBeenCalled();
});
test('rejects when an admitted read advances the revision after the final idle check', async () => {
const context = setup();
const swap = context.replaceDecision.getMockImplementation()!;
context.replaceDecision.mockImplementationOnce(async (args) => {
// The real readAdmittedConvoCodeEnvironmentDecision advances this in Mongo atomically.
context.conversations.set('conversation-1', {
...context.conversations.get('conversation-1')!,
codeEnvironmentRevision: 1,
} as StoredDecision);
return swap(args);
});
const res = await context.move({ from: [mac], to: [vm] });
expect(res.statusCode).toBe(409);
expect(res.body).toEqual(expect.objectContaining({ reason: 'locked' }));
expect(context.conversations.get('conversation-1')?.codeWorkspaces).toEqual([mac]);
});
test('moves once the previous generation has settled and saved', async () => {
const { move } = setup({
job: { status: 'complete', metadata: { terminalPersistencePending: false } },
});
expect((await move({ from: [mac], to: [vm] })).statusCode).toBe(200);
});
test.each([
{
name: 'a workspace the machine does not register',
fetchImpl: jest
.fn()
.mockImplementation(async () =>
workerStatusResponse({ workspaces: [{ id: 'another-project' }] }),
),
reason: 'missing',
},
{
name: 'a machine that is not ready',
fetchImpl: jest.fn().mockImplementation(async () => workerStatusResponse({ ready: false })),
reason: 'worker_unavailable',
},
])('rejects $name without persisting', async ({ fetchImpl, reason }) => {
const { move, conversations, replaceDecision } = setup({ fetchImpl });
const res = await move({ from: [mac], to: [vm] });
expect(res.statusCode).toBe(409);
expect(res.body).toEqual(expect.objectContaining({ reason }));
expect(replaceDecision).not.toHaveBeenCalled();
expect(conversations.get('conversation-1')?.codeWorkspaces).toEqual([mac]);
});
test.each([
{
name: 'an environment the caller cannot access',
body: { from: [mac], to: [{ environmentId: 'another-users-vm', workspaceId: 'root' }] },
reason: 'invalid',
polls: 0,
},
{
name: 'a stale view of the decision',
body: { from: [{ environmentId: 'old-vm', workspaceId: 'primary' }], to: [vm] },
reason: 'locked',
polls: 0,
},
{
name: 'a replacement on an environment the caller cannot access',
body: { from: [mac], to: [{ environmentId: 'mac', workspaceId: 'canary' }] },
reason: 'invalid',
polls: 0,
},
])('rejects $name without polling any worker', async ({ body, reason, polls }) => {
const { move, replaceDecision, fetchImpl } = setup();
const res = await move(body);
expect(res.statusCode).toBe(409);
expect(res.body).toEqual(expect.objectContaining({ reason }));
expect(fetchImpl).toHaveBeenCalledTimes(polls);
expect(replaceDecision).not.toHaveBeenCalled();
});
test('keeps a decision another writer replaced while the worker was checked', async () => {
const concurrent: StoredDecision = {
conversationId: 'conversation-1',
codeEnvironmentMode: 'without_attached',
};
const holder: { conversations?: Map<string, StoredDecision> } = {};
const fetchImpl = jest.fn().mockImplementation(async () => {
holder.conversations?.set('conversation-1', concurrent);
return workerStatusResponse();
});
const context = setup({ fetchImpl });
holder.conversations = context.conversations;
const res = await context.move({ from: [mac], to: [vm] });
expect(res.statusCode).toBe(409);
expect(res.body).toEqual(expect.objectContaining({ reason: 'locked' }));
expect(context.conversations.get('conversation-1')).toEqual(concurrent);
});
test('refuses every move when the effective policy does not enable them', async () => {
const { move, getConversation, replaceDecision, fetchImpl } = setup({ movesEnabled: false });
const res = await move({ from: [mac], to: [vm] });
expect(res.statusCode).toBe(403);
expect(getConversation).not.toHaveBeenCalled();
expect(fetchImpl).not.toHaveBeenCalled();
expect(replaceDecision).not.toHaveBeenCalled();
});
test('reports a conversation the caller does not own as not found', async () => {
const { move, fetchImpl } = setup();
const res = await move({ from: [mac], to: [vm] }, 'someone-elses-conversation');
expect(res.statusCode).toBe(404);
expect(fetchImpl).not.toHaveBeenCalled();
});
});