🚛 fix: Move Sealed Chats to New Code Environments (#15902)

* 🧭 fix: Let a Sealed Chat Follow Its Agent to a New Machine

A conversation's code-environment decision is sealed on its first turn, but the
environment an agent uses stays editable. Pointing an agent at a different
attached machine left every chat sealed to the old one with no valid move: the
client showed an unusable workspace chooser, and any other selection was
rejected by the server as locked. Forking copied the stale seal.

The owner can now move such a chat explicitly. The composer names the machine
the chat used and the one its agent uses now, and moving it goes through an
owner-scoped endpoint that compare-and-swaps the persisted decision after
validating the new workspace against the live worker. A move never switches the
workspace of an environment the decision already covers, never upgrades a chat
that continues without an attached environment, and is refused while a
generation is in flight.

A saved chat also no longer auto-selects a sole workspace for an environment its
decision never covered, which submitted a selection the server always rejected.

* fix: Hold Moves Through Terminal Saves and Move Every Target at Once

A terminal claim marks a generation complete before its response save lands,
and that save still writes the decision the run started with, so a move is now
refused until terminalPersistencePending clears.

The API advertises codeEnvironmentMoveVersion, and the client offers a move only
when it is present, so a new client never exposes an endpoint an older API lacks.

The move menu picks one workspace per new environment, with a sole workspace
preselected, and a single confirm sends the complete target set in one request,
so a partial move can no longer leave a half-migrated decision. A new machine
that advertises no workspace shows its unavailable state instead of an empty
section, and the confirm stays disabled.

* fix: Keep Runs From Rewriting Moved Decisions and Gate Moves by Policy

Every agent turn used to persist the decision it started with, so a run from any
ingress that settled after a move could write the old decision back: the chat
controller reads the conversation before its generation job exists, and
Responses API runs never enroll one. Runs now persist a decision only for a
conversation that does not store one yet, and a legacy row records only the mode
it inferred, so no admission or persistence order can revert a move.

Moves are now an operator setting, statefulCodeSessions.conversationMoves.enabled,
off by default. The API advertises codeEnvironmentMoveVersion and accepts moves
only where the effective policy enables them.

A saved chat carrying attached selections no longer auto-selects a sole workspace
even when selection-less decisions are not advertised, because the server seals
those selections either way.

* fix: Fence Moves Across Remote Runs and Let Moves Drop Unused Machines

A Responses API run is keyed by its response id, so the conversation stream
alone could not show it still working on a chat. A move is now refused while any
generation that can still act for the conversation exists, using the same
conversation-scoped enumeration conversation deletion drains.

A move now validates every workspace it persists, not only the added ones, so a
successful move never hands back a decision whose kept workspace is gone.

A chat sealed to machines its agents no longer all use could not be sent or
moved: the client trimmed the unused selection and the server rejected the
trimmed set as locked. A saved chat now treats that seal as unresolvable, offers
a move that drops the unused machine, and the server accepts drop-only moves.

* fix: Own the Decision Fallback in TypeScript and Settle Move Caches

The fields a run may persist when it never resolved a decision were chosen by a
branch in AgentClient; resolvePersistableCodeEnvironmentDecision now owns that
fallback too, under the same never-overwrite rule, and the CJS method only wires
the request into it.

Workspace choices made in the move menu belong to the chat they were made in, so
another relocatable chat targeting the same machine starts undecided.

A successful move cancels conversation, pinned, and list reads already in flight
before writing the moved decision, so a response from before the move cannot
restore the replaced decision in the cache.
This commit is contained in:
Danny Avila 2026-09-14 00:58:08 -04:00 • committed by GitHub
parent 7fe9a45894
commit 4216de41c2
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
33 changed files with 2345 additions and 218 deletions

View file

@ -4,6 +4,7 @@ import {
isImplicitStatefulCodeRouteAvailable,
mergeAccessibleCodeEnvironments,
resolveCodeEnvironmentDecisionVersion,
resolveCodeEnvironmentMoveVersion,
} from './config';
describe('resolveCodeEnvironmentDecisionVersion', () => {
@ -19,6 +20,33 @@ describe('resolveCodeEnvironmentDecisionVersion', () => {
);
});
describe('resolveCodeEnvironmentMoveVersion', () => {
const withMoves = (conversationMoves?: { enabled?: boolean }) =>
({
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: { allowedEnvironments: ['user'], conversationMoves },
},
},
}) as unknown as AppConfig;
it('advertises moves only where the effective policy enables them', () => {
expect(resolveCodeEnvironmentMoveVersion(withMoves({ enabled: true }))).toBe(1);
});
it.each([undefined, {}, { enabled: false }])(
'keeps sealed decisions immovable by default: %j',
(conversationMoves) => {
expect(resolveCodeEnvironmentMoveVersion(withMoves(conversationMoves))).toBeUndefined();
},
);
it('keeps moves off without any stateful code configuration', () => {
expect(resolveCodeEnvironmentMoveVersion({} as AppConfig)).toBeUndefined();
expect(resolveCodeEnvironmentMoveVersion(undefined)).toBeUndefined();
});
});
describe('isImplicitStatefulCodeRouteAvailable', () => {
it('requires both the deployed protocol version and a non-empty managed base URL', () => {
expect(isImplicitStatefulCodeRouteAvailable('1', 'https://code.example/v1')).toBe(true);

View file

@ -1,5 +1,9 @@
import { logger } from '@librechat/data-schemas';
import { CODE_ENVIRONMENT_DECISION_VERSION, EModelEndpoint } from 'librechat-data-provider';
import {
CODE_ENVIRONMENT_DECISION_VERSION,
CODE_ENVIRONMENT_MOVE_VERSION,
EModelEndpoint,
} from 'librechat-data-provider';
import type { AppConfig } from '@librechat/data-schemas';
import type {
AccessibleCodeEnvironmentConfiguration,
@ -30,6 +34,16 @@ export function resolveCodeEnvironmentDecisionVersion(
: undefined;
}
/** Advertises owner moves of a sealed decision only where the effective policy enables them. */
export function resolveCodeEnvironmentMoveVersion(
appConfig?: Pick<AppConfig, 'endpoints'> | null,
): typeof CODE_ENVIRONMENT_MOVE_VERSION | undefined {
return appConfig?.endpoints?.[EModelEndpoint.agents]?.statefulCodeSessions?.conversationMoves
?.enabled === true
? CODE_ENVIRONMENT_MOVE_VERSION
: undefined;
}
/** Enables the implicit managed route only after the versioned rollout is complete. */
export function isImplicitStatefulCodeRouteAvailable(
configuredVersion?: string,

View file

@ -1,4 +1,8 @@
import { resolveConversationCodeEnvironmentDecision } from './decision';
import {
resolveConversationCodeEnvironmentDecision,
resolveConversationCodeEnvironmentMove,
resolvePersistableCodeEnvironmentDecision,
} from './decision';
import { CodeWorkspaceSelectionError } from './capabilities';
const selection = { environmentId: 'personal-vm', workspaceId: 'project-a' };
@ -121,3 +125,208 @@ describe('resolveConversationCodeEnvironmentDecision', () => {
).toThrow(expect.objectContaining<Partial<CodeWorkspaceSelectionError>>({ reason: 'invalid' }));
});
});
describe('resolveConversationCodeEnvironmentMove', () => {
const mac = { environmentId: 'mac', workspaceId: 'primary' };
const vm = { environmentId: 'vm', workspaceId: 'projects' };
const locked = expect.objectContaining<Partial<CodeWorkspaceSelectionError>>({
reason: 'locked',
});
const sealedOn = (...codeWorkspaces: (typeof mac)[]) => ({
conversationId: 'conversation-1',
codeEnvironmentMode: 'attached' as const,
codeWorkspaces,
});
it('replaces an environment the agents stopped using with the one they use now', () => {
expect(
resolveConversationCodeEnvironmentMove({
conversation: sealedOn(mac),
from: [mac],
to: [vm],
}),
).toEqual({ codeWorkspaces: [vm] });
});
it('carries a covered environment over unchanged while adding a new one', () => {
const team = { environmentId: 'team', workspaceId: 'shared' };
expect(
resolveConversationCodeEnvironmentMove({
conversation: sealedOn(team),
from: [team],
to: [vm, team],
}),
).toEqual({ codeWorkspaces: [team, vm] });
});
it('moves a legacy decision inferred from its selections', () => {
expect(
resolveConversationCodeEnvironmentMove({
conversation: { conversationId: 'conversation-1', codeWorkspaces: [mac] },
from: [mac],
to: [vm],
}),
).toEqual({ codeWorkspaces: [vm] });
});
it('never switches the workspace of an environment the decision already covers', () => {
expect(() =>
resolveConversationCodeEnvironmentMove({
conversation: sealedOn(mac),
from: [mac],
to: [{ environmentId: 'mac', workspaceId: 'canary' }],
}),
).toThrow(locked);
expect(() =>
resolveConversationCodeEnvironmentMove({
conversation: sealedOn(mac),
from: [mac],
to: [{ environmentId: 'mac', workspaceId: 'canary' }, vm],
}),
).toThrow(locked);
});
it('drops an environment the agents stopped using without adding one', () => {
const team = { environmentId: 'team', workspaceId: 'shared' };
expect(
resolveConversationCodeEnvironmentMove({
conversation: sealedOn(mac, team),
from: [mac, team],
to: [team],
}),
).toEqual({ codeWorkspaces: [team] });
});
it('rejects a move that changes nothing', () => {
expect(() =>
resolveConversationCodeEnvironmentMove({
conversation: sealedOn(mac),
from: [mac],
to: [mac],
}),
).toThrow(locked);
});
it.each([
{ conversationId: 'conversation-1', codeEnvironmentMode: 'without_attached' as const },
{ conversationId: 'conversation-1' },
])('never upgrades a conversation that continues without an attached environment', (stored) => {
expect(() =>
resolveConversationCodeEnvironmentMove({ conversation: stored, from: [], to: [vm] }),
).toThrow(locked);
});
it('rejects a client acting on a decision it has not seen', () => {
expect(() =>
resolveConversationCodeEnvironmentMove({ conversation: sealedOn(vm), from: [mac], to: [vm] }),
).toThrow(locked);
});
it.each([[], undefined, [vm, { ...vm, workspaceId: 'other' }], [{ environmentId: 'vm' }]])(
'rejects a malformed target: %j',
(to) => {
expect(() =>
resolveConversationCodeEnvironmentMove({ conversation: sealedOn(mac), from: [mac], to }),
).toThrow(
expect.objectContaining<Partial<CodeWorkspaceSelectionError>>({ reason: 'invalid' }),
);
},
);
});
describe('resolvePersistableCodeEnvironmentDecision', () => {
const mac = { environmentId: 'mac', workspaceId: 'primary' };
const vm = { environmentId: 'vm', workspaceId: 'projects' };
it('persists the decision a new conversation establishes', () => {
expect(
resolvePersistableCodeEnvironmentDecision({
conversationId: 'conversation-1',
decision: { mode: 'attached', codeWorkspaces: [mac] },
}),
).toEqual({ codeEnvironmentMode: 'attached', codeWorkspaces: [mac] });
expect(
resolvePersistableCodeEnvironmentDecision({
conversationId: 'conversation-1',
decision: { mode: 'without_attached' },
}),
).toEqual({ codeEnvironmentMode: 'without_attached' });
});
it('never writes a run-start decision over a stored one that a move replaced', () => {
expect(
resolvePersistableCodeEnvironmentDecision({
conversationId: 'conversation-1',
decision: { mode: 'attached', codeWorkspaces: [mac] },
conversation: {
conversationId: 'conversation-1',
codeEnvironmentMode: 'attached',
codeWorkspaces: [vm],
},
}),
).toEqual({});
});
it('records the mode a legacy row inferred without rewriting its selections', () => {
expect(
resolvePersistableCodeEnvironmentDecision({
conversationId: 'conversation-1',
decision: { mode: 'attached', codeWorkspaces: [mac] },
conversation: { conversationId: 'conversation-1', codeWorkspaces: [vm] },
}),
).toEqual({ codeEnvironmentMode: 'attached' });
});
it('treats a resolved conversation for another id as a new conversation', () => {
expect(
resolvePersistableCodeEnvironmentDecision({
conversationId: 'conversation-1',
decision: { mode: 'attached', codeWorkspaces: [mac] },
conversation: {
conversationId: 'another-conversation',
codeEnvironmentMode: 'attached',
codeWorkspaces: [vm],
},
}),
).toEqual({ codeEnvironmentMode: 'attached', codeWorkspaces: [mac] });
});
it('falls back to request fields for a caller that never resolved a decision', () => {
expect(
resolvePersistableCodeEnvironmentDecision({
conversationId: 'conversation-1',
requested: { codeEnvironmentMode: 'attached', codeWorkspaces: [mac] },
}),
).toEqual({ codeEnvironmentMode: 'attached', codeWorkspaces: [mac] });
});
it('never writes a request fallback over a stored decision', () => {
expect(
resolvePersistableCodeEnvironmentDecision({
conversationId: 'conversation-1',
requested: { codeEnvironmentMode: 'attached', codeWorkspaces: [mac] },
conversation: {
conversationId: 'conversation-1',
codeEnvironmentMode: 'attached',
codeWorkspaces: [vm],
},
}),
).toEqual({});
});
it('prefers the validated decision over request fields', () => {
expect(
resolvePersistableCodeEnvironmentDecision({
conversationId: 'conversation-1',
decision: { mode: 'without_attached' },
requested: { codeEnvironmentMode: 'attached', codeWorkspaces: [mac] },
}),
).toEqual({ codeEnvironmentMode: 'without_attached' });
});
it('persists nothing without a validated decision', () => {
expect(resolvePersistableCodeEnvironmentDecision({ conversationId: 'conversation-1' })).toEqual(
{},
);
});
});

View file

@ -11,7 +11,7 @@ export interface ConversationCodeEnvironmentDecision {
codeWorkspaces?: CodeWorkspaceSelection[];
}
type StoredConversationDecision = Pick<
export type StoredConversationDecision = Pick<
TConversation,
'conversationId' | 'codeEnvironmentMode' | 'codeWorkspaces'
>;
@ -49,6 +49,16 @@ function validateDecision(mode: unknown, selections: unknown): ConversationCodeE
return { mode, codeWorkspaces: canonicalSelections(selections) };
}
/** A stored conversation always carries a decision; legacy rows infer it from their selections. */
function readPersistedDecision(
conversation: StoredConversationDecision,
): ConversationCodeEnvironmentDecision {
const mode =
conversation.codeEnvironmentMode ??
(conversation.codeWorkspaces?.length ? 'attached' : 'without_attached');
return validateDecision(mode, conversation.codeWorkspaces);
}
/** Resolves one immutable conversation choice before attached tools are registered. */
export function resolveConversationCodeEnvironmentDecision({
conversationId,
@ -61,16 +71,8 @@ export function resolveConversationCodeEnvironmentDecision({
requestedSelections?: unknown;
conversation?: StoredConversationDecision | null;
}): ConversationCodeEnvironmentDecision {
const ownsConversation = conversation != null && conversation.conversationId === conversationId;
const persistedMode = ownsConversation ? conversation.codeEnvironmentMode : undefined;
const persistedSelections = ownsConversation ? conversation.codeWorkspaces : undefined;
let inferredPersistedMode: unknown = persistedMode;
if (inferredPersistedMode == null && ownsConversation) {
inferredPersistedMode = persistedSelections?.length ? 'attached' : 'without_attached';
}
if (inferredPersistedMode != null) {
const persisted = validateDecision(inferredPersistedMode, persistedSelections);
if (conversation != null && conversation.conversationId === conversationId) {
const persisted = readPersistedDecision(conversation);
if (requestedMode !== undefined && requestedMode !== persisted.mode) {
throw new CodeWorkspaceSelectionError('locked');
}
@ -102,3 +104,95 @@ export function resolveConversationCodeEnvironmentDecision({
: 'without_attached');
return validateDecision(mode, requestedSelections);
}
export interface ConversationCodeEnvironmentMove {
codeWorkspaces: CodeWorkspaceSelection[];
}
/**
* Validates an owner's explicit move of a sealed attached decision onto the environments its
* agents now use. A move may drop environments the agents stopped using and add ones they now use,
* but never changes the workspace of an environment the decision already covers and never upgrades
* a conversation that continues without an attached environment. `from` must repeat the persisted selections, so a client acting
* on a stale view of the conversation cannot replace a decision it has not seen.
*/
export function resolveConversationCodeEnvironmentMove({
conversation,
from,
to,
}: {
conversation: StoredConversationDecision;
from: unknown;
to: unknown;
}): ConversationCodeEnvironmentMove {
const persisted = readPersistedDecision(conversation);
if (persisted.mode !== 'attached' || persisted.codeWorkspaces == null) {
throw new CodeWorkspaceSelectionError('locked');
}
if (!isCodeWorkspaceSelections(from) || !sameSelections(from, persisted.codeWorkspaces)) {
throw new CodeWorkspaceSelectionError('locked');
}
if (!isCodeWorkspaceSelections(to) || to.length === 0) {
throw new CodeWorkspaceSelectionError('invalid');
}
const sealed = new Map(
persisted.codeWorkspaces.map(({ environmentId, workspaceId }) => [environmentId, workspaceId]),
);
let adds = false;
for (const selection of to) {
const sealedWorkspaceId = sealed.get(selection.environmentId);
if (sealedWorkspaceId == null) {
adds = true;
} else if (sealedWorkspaceId !== selection.workspaceId) {
throw new CodeWorkspaceSelectionError('locked');
}
}
if (!adds && to.length === sealed.size) {
throw new CodeWorkspaceSelectionError('locked');
}
return { codeWorkspaces: canonicalSelections(to) };
}
type PersistableDecisionFields = Pick<
StoredConversationDecision,
'codeEnvironmentMode' | 'codeWorkspaces'
>;
/**
* Returns the decision fields a run may persist. A stored conversation keeps the decision it
* already holds, because only its owner's explicit move replaces one: a run from any ingress that
* settles after a move would otherwise write its run-start decision back over it. A legacy row
* records the mode it inferred without touching the selections it already stores. A caller that
* never resolved a decision falls back to the fields its request carried, under the same rule.
*/
export function resolvePersistableCodeEnvironmentDecision({
conversationId,
decision,
conversation,
requested,
}: {
conversationId: string;
decision?: ConversationCodeEnvironmentDecision | null;
conversation?: StoredConversationDecision | null;
requested?: PersistableDecisionFields | null;
}): PersistableDecisionFields {
const candidate: PersistableDecisionFields =
decision != null
? {
codeEnvironmentMode: decision.mode,
...(decision.codeWorkspaces != null && { codeWorkspaces: decision.codeWorkspaces }),
}
: {
...(requested?.codeEnvironmentMode != null && {
codeEnvironmentMode: requested.codeEnvironmentMode,
}),
...(requested?.codeWorkspaces != null && { codeWorkspaces: requested.codeWorkspaces }),
};
if (conversation == null || conversation.conversationId !== conversationId) {
return candidate;
}
if (conversation.codeEnvironmentMode != null || candidate.codeEnvironmentMode == null) {
return {};
}
return { codeEnvironmentMode: candidate.codeEnvironmentMode };
}

View file

@ -1,5 +1,6 @@
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';
@ -1501,3 +1502,362 @@ describe('code environment HTTP handlers', () => {
expect(res.body).toEqual(body);
});
});
describe('moving a sealed conversation code-environment decision', () => {
type Selection = { environmentId: string; workspaceId: string };
type StoredDecision = {
conversationId: string;
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,
stored = {
conversationId: 'conversation-1',
codeEnvironmentMode: 'attached',
codeWorkspaces: [mac],
},
job,
conversationRunIds = [],
fetchImpl = jest.fn().mockImplementation(async () => workerStatusResponse()),
}: {
movesEnabled?: 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,
codeWorkspaces,
}: {
conversationId: string;
expected: Pick<StoredDecision, 'codeEnvironmentMode' | 'codeWorkspaces'>;
codeWorkspaces: Selection[];
}) => {
const current = conversations.get(conversationId);
const decisionOf = (decision: Partial<StoredDecision> | undefined) =>
JSON.stringify([decision?.codeEnvironmentMode ?? null, decision?.codeWorkspaces ?? null]);
if (current == null || decisionOf(current) !== decisionOf(expected)) {
return null;
}
const moved: StoredDecision = {
...current,
codeEnvironmentMode: 'attached',
codeWorkspaces,
};
conversations.set(conversationId, moved);
return moved;
},
);
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn().mockResolvedValue({
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
environments: [controlPlane],
conversationMoves: { enabled: movesEnabled },
},
},
},
} 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;
};
return {
move,
conversations,
getConversation,
listConversationRuns,
replaceDecision,
fetchImpl,
};
}
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('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('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 workspace switch inside a sealed environment',
body: { from: [mac], to: [{ environmentId: 'mac', workspaceId: 'canary' }] },
reason: 'locked',
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();
});
});

View file

@ -1,6 +1,7 @@
import { nanoid } from 'nanoid';
import { EModelEndpoint } from 'librechat-data-provider';
import { logger, type AppConfig } from '@librechat/data-schemas';
import type { CodeWorkspaceSelection } from 'librechat-data-provider';
import type { Response } from 'express';
import type {
CodeEnvironmentLifecycleTarget,
@ -10,9 +11,11 @@ import type {
AccessibleCodeEnvironmentDetails,
AccessibleCodeEnvironmentConfiguration,
} from './environments';
import type { ConversationCodeEnvironmentMove, StoredConversationDecision } from './decision';
import type { CodeBridgeFetch, CodeBridgeWorkerStatus } from './bridge';
import type { JobStatus } from '~/stream/interfaces/IJobStore';
import type { GetAppConfigOptions } from '~/app/service';
import type { ServerRequest } from '~/types/http';
import type { CodeBridgeFetch } from './bridge';
import {
CodeBridgeLifecycleError,
CodeBridgePairingError,
@ -37,7 +40,10 @@ import {
CodeEnvironmentSettingsValidationError,
validateCodeEnvironmentUserSettings,
} from './settings';
import { resolveConversationCodeEnvironmentMove } from './decision';
import { resolveCodeWorkerEnrollmentLimit } from './enrollment';
import { resolveCodeEnvironmentMoveVersion } from './config';
import { CodeWorkspaceSelectionError } from './capabilities';
import { getAppConfigOptionsFromUser } from '~/app/service';
type Registry = {
@ -76,9 +82,40 @@ type ConfiguredCodeEnvironment = NonNullable<
NonNullable<StatefulCodeConfig>['environments']
>[number];
/** Owner-scoped conversation access for moving a sealed code-environment decision. */
export interface CodeEnvironmentConversationDeps {
get: (userId: string, conversationId: string) => Promise<StoredConversationDecision | null>;
replaceDecision: (params: {
user: string;
conversationId: string;
expected: Pick<StoredConversationDecision, 'codeEnvironmentMode' | 'codeWorkspaces'>;
codeWorkspaces: CodeWorkspaceSelection[];
}) => Promise<StoredConversationDecision | null>;
}
/** Generation lookups a move needs to tell whether any run can still act for a conversation. */
export interface CodeEnvironmentGenerationDeps {
getJob: (streamId: string) => Promise<CodeEnvironmentGenerationJob | null | undefined>;
/** Remote API runs use response IDs as stream identities, so the conversation's own stream
* is not the only generation that can still act in its environment. */
getCleanupBlockingJobIdsForConversations: (
userId: string,
conversationIds: readonly string[],
tenantId?: string,
) => Promise<string[]>;
}
/** The generation state a move reads to tell whether a run can still save its own decision. */
export type CodeEnvironmentGenerationJob = {
status: JobStatus;
metadata?: { terminalPersistencePending?: boolean };
};
export interface CodeEnvironmentHttpDeps {
getAppConfig: (options: GetAppConfigOptions) => Promise<AppConfig>;
registry: Registry;
conversations?: CodeEnvironmentConversationDeps;
generations?: CodeEnvironmentGenerationDeps;
createEnvironmentId?: () => string;
readSecret?: (name: string) => string | undefined;
resolveTenantId?: (req: ServerRequest) => string;
@ -153,6 +190,60 @@ function configuredAttachedControlPlane(
);
}
type WorkerPolicy = {
configurations: AccessibleCodeEnvironmentConfiguration[];
effectiveConfig: AppConfig;
deploymentConfig: AppConfig;
};
type WorkerTarget = { controlPlane: ConfiguredCodeEnvironment; workerId: string };
/** Resolves the deployment control plane and worker a principal may poll for one environment. */
function selectWorkerTarget(policy: WorkerPolicy, environmentId: string): WorkerTarget | undefined {
const { configurations, effectiveConfig, deploymentConfig } = policy;
const configuration = configurations.find(({ id }) => id === environmentId);
if (configuration == null) {
const effectiveEnvironment = configuredControlPlane(effectiveConfig, environmentId);
const deploymentEnvironment = configuredControlPlane(deploymentConfig, environmentId);
const workerId = deploymentEnvironment?.pairing?.workerId;
if (
effectiveEnvironment == null ||
deploymentEnvironment == null ||
workerId == null ||
effectiveEnvironment.pairing?.workerId !== workerId
) {
return undefined;
}
return { controlPlane: deploymentEnvironment, workerId };
}
const { controlPlaneId, workerId } = configuration;
if (
controlPlaneId == null ||
workerId == null ||
configuredAttachedControlPlane(effectiveConfig, controlPlaneId) == null
) {
return undefined;
}
const controlPlane = configuredAttachedControlPlane(deploymentConfig, controlPlaneId);
return controlPlane == null ? undefined : { controlPlane, workerId };
}
/** A terminal claim marks the job settled before its response save lands, so that save still
* writes the decision the run started with until `terminalPersistencePending` clears. */
function isGenerationActive(job: CodeEnvironmentGenerationJob | null | undefined): boolean {
return (
job?.status === 'running' ||
job?.status === 'requires_action' ||
job?.metadata?.terminalPersistencePending === true
);
}
function selectionErrorResponse(error: CodeWorkspaceSelectionError, res: Response): Response {
return res
.status(error.status)
.json({ error: error.message, code: error.code, reason: error.reason });
}
class CodeEnvironmentLifecycleHttpError extends Error {
constructor(
public readonly status: number,
@ -196,6 +287,7 @@ export function createCodeEnvironmentHttpHandlers(deps: CodeEnvironmentHttpDeps)
status: (req: ServerRequest, res: Response) => Promise<Response>;
updateSettings: (req: ServerRequest, res: Response) => Promise<Response>;
remove: (req: ServerRequest, res: Response) => Promise<Response>;
moveConversationDecision: (req: ServerRequest, res: Response) => Promise<Response>;
} {
const createEnvironmentId = deps.createEnvironmentId ?? (() => `code-${nanoid(20)}`);
const readSecret = deps.readSecret ?? readCodeBridgeSecret;
@ -205,6 +297,158 @@ export function createCodeEnvironmentHttpHandlers(deps: CodeEnvironmentHttpDeps)
const principalIsActive = deps.principalIsActive ?? (async () => true);
const workerStatus = createCodeBridgeStatusPoller({ fetchImpl: deps.fetchImpl });
async function loadWorkerPolicy(
req: ServerRequest,
principal: CodeEnvironmentPrincipalContext,
): Promise<WorkerPolicy> {
const principals = await deps.registry.resolvePrincipals?.(principal);
const resolvedPrincipal = principals == null ? principal : { ...principal, principals };
const [configurations, effectiveConfig, deploymentConfig] = await Promise.all([
deps.registry.listAccessibleConfigurations?.(resolvedPrincipal) ?? Promise.resolve([]),
deps.getAppConfig({
...getAppConfigOptionsFromUser(req.user),
...(principals == null ? {} : { resolvedPrincipals: principals }),
failClosed: true,
skipRuntimeAugmentation: true,
}),
deps.getAppConfig({ baseOnly: true }),
]);
return { configurations, effectiveConfig, deploymentConfig };
}
function readControlPlaneToken(controlPlane: ConfiguredCodeEnvironment): string | undefined {
const tokenEnv = controlPlane.pairing?.tokenEnv;
return tokenEnv == null ? undefined : readSecret(tokenEnv)?.trim();
}
/** Applies the run path's live workspace checks to a selection before it is persisted. */
async function assertWorkspaceRegistered(
policy: WorkerPolicy,
selection: CodeWorkspaceSelection,
): Promise<void> {
const target = selectWorkerTarget(policy, selection.environmentId);
if (target == null) {
throw new CodeWorkspaceSelectionError('invalid');
}
const token = readControlPlaneToken(target.controlPlane);
if (!token) {
throw new CodeWorkspaceSelectionError('worker_unavailable');
}
let current: CodeBridgeWorkerStatus;
try {
current = await workerStatus({
baseURL: target.controlPlane.baseURL,
token,
workerId: target.workerId,
});
} catch (error) {
if (error instanceof CodeBridgeStatusError) {
throw new CodeWorkspaceSelectionError('worker_unavailable');
}
throw error;
}
if (current.status !== 'ready') {
throw new CodeWorkspaceSelectionError('worker_unavailable');
}
if (!current.workspaces || !current.operations) {
throw new CodeWorkspaceSelectionError('unsupported');
}
if (!current.workspaces.some(({ id }) => id === selection.workspaceId)) {
throw new CodeWorkspaceSelectionError('missing');
}
}
/**
* Moves a sealed attached decision onto the environments a conversation's agents now use, when
* the effective policy enables moves. Runs never rewrite a stored decision, so no run from any
* ingress can write its run-start decision back over a move. A move is still refused while a
* generation is running, awaiting approval, or saving its response, so that generation does not
* keep working in the previous environment after the conversation has left it.
*/
async function moveConversationDecision(req: ServerRequest, res: Response): Promise<Response> {
const principal = actor(req);
if (principal == null) {
return res.status(401).json({ error: 'Authentication required' });
}
const { conversations, generations } = deps;
if (conversations == null || generations == null) {
return res.status(503).json({ error: 'Conversation code environments are not configured' });
}
const conversationId = (
req.params as { conversationId?: string } | undefined
)?.conversationId?.trim();
if (!conversationId) {
return res.status(400).json({ error: 'Conversation id is required' });
}
let policy: WorkerPolicy;
try {
policy = await loadWorkerPolicy(req, principal);
} catch (error) {
logger.error('[codeEnvironments] move policy resolution failed:', error);
return res.status(503).json({ error: 'Code environment policy is unavailable' });
}
if (resolveCodeEnvironmentMoveVersion(policy.effectiveConfig) == null) {
return res.status(403).json({ error: 'Conversation code environment moves are disabled' });
}
const { from, to } = (req.body ?? {}) as { from?: unknown; to?: unknown };
const userId = principal.userId.toString();
const tenantId =
typeof req.user?.tenantId === 'string' && req.user.tenantId !== ''
? req.user.tenantId
: undefined;
const [conversation, job, conversationRunIds] = await Promise.all([
conversations.get(userId, conversationId),
generations.getJob(conversationId),
generations.getCleanupBlockingJobIdsForConversations(userId, [conversationId], tenantId),
]);
if (conversation == null) {
return res.status(404).json({ error: 'Conversation was not found' });
}
if (isGenerationActive(job) || conversationRunIds.length > 0) {
return res
.status(409)
.json({ error: 'Wait for the current response to finish before moving this conversation' });
}
let move: ConversationCodeEnvironmentMove;
try {
move = resolveConversationCodeEnvironmentMove({ conversation, from, to });
} catch (error) {
if (error instanceof CodeWorkspaceSelectionError) {
return selectionErrorResponse(error, res);
}
throw error;
}
try {
await Promise.all(
move.codeWorkspaces.map((selection) => assertWorkspaceRegistered(policy, selection)),
);
} catch (error) {
if (error instanceof CodeWorkspaceSelectionError) {
return selectionErrorResponse(error, res);
}
throw error;
}
const moved = await conversations.replaceDecision({
user: userId,
conversationId,
expected: {
codeEnvironmentMode: conversation.codeEnvironmentMode,
codeWorkspaces: conversation.codeWorkspaces,
},
codeWorkspaces: move.codeWorkspaces,
});
if (moved == null) {
return selectionErrorResponse(new CodeWorkspaceSelectionError('locked'), res);
}
return res.status(200).json({
conversationId,
codeEnvironmentMode: 'attached',
codeWorkspaces: move.codeWorkspaces,
});
}
async function list(req: ServerRequest, res: Response): Promise<Response> {
const principal = actor(req);
if (principal == null) {
@ -659,62 +903,25 @@ export function createCodeEnvironmentHttpHandlers(deps: CodeEnvironmentHttpDeps)
return res.status(400).json({ error: 'Code environment id is required' });
}
let configuration: AccessibleCodeEnvironmentConfiguration | undefined;
let controlPlane: ConfiguredCodeEnvironment | undefined;
let workerId: string | undefined;
let target: WorkerTarget | undefined;
try {
const principals = await deps.registry.resolvePrincipals?.(principal);
const resolvedPrincipal = principals == null ? principal : { ...principal, principals };
const [configurations, effectiveConfig, deploymentConfig] = await Promise.all([
deps.registry.listAccessibleConfigurations?.(resolvedPrincipal) ?? Promise.resolve([]),
deps.getAppConfig({
...getAppConfigOptionsFromUser(req.user),
...(principals == null ? {} : { resolvedPrincipals: principals }),
failClosed: true,
skipRuntimeAugmentation: true,
}),
deps.getAppConfig({ baseOnly: true }),
]);
configuration = configurations.find(({ id }) => id === environmentId);
const controlPlaneId = configuration?.controlPlaneId;
const effectiveControlPlane =
controlPlaneId == null
? undefined
: configuredAttachedControlPlane(effectiveConfig, controlPlaneId);
controlPlane =
effectiveControlPlane == null || controlPlaneId == null
? undefined
: configuredAttachedControlPlane(deploymentConfig, controlPlaneId);
workerId = configuration?.workerId;
if (configuration == null) {
const effectiveEnvironment = configuredControlPlane(effectiveConfig, environmentId);
const deploymentEnvironment = configuredControlPlane(deploymentConfig, environmentId);
if (
effectiveEnvironment != null &&
deploymentEnvironment != null &&
effectiveEnvironment.pairing?.workerId === deploymentEnvironment.pairing?.workerId
) {
controlPlane = deploymentEnvironment;
workerId = deploymentEnvironment.pairing?.workerId;
}
}
target = selectWorkerTarget(await loadWorkerPolicy(req, principal), environmentId);
} catch (error) {
logger.error('[codeEnvironments] status policy resolution failed:', error);
return res.status(503).json({ error: 'Code environment policy is unavailable' });
}
if (workerId == null || controlPlane == null) {
if (target == null) {
return res.status(404).json({ error: 'Code environment was not found' });
}
const tokenEnv = controlPlane.pairing?.tokenEnv;
const token = tokenEnv == null ? undefined : readSecret(tokenEnv)?.trim();
const token = readControlPlaneToken(target.controlPlane);
if (!token) {
return res.status(503).json({ error: 'Code environment status is not configured' });
}
try {
const currentStatus = await workerStatus({
baseURL: controlPlane.baseURL,
baseURL: target.controlPlane.baseURL,
token,
workerId,
workerId: target.workerId,
});
return res.status(200).json({ environmentId, ...currentStatus });
} catch (error) {
@ -781,5 +988,5 @@ export function createCodeEnvironmentHttpHandlers(deps: CodeEnvironmentHttpDeps)
}
}
return { list, register, pair, status, updateSettings, remove };
return { list, register, pair, status, updateSettings, remove, moveConversationDecision };
}