LibreChat/packages/api/src/agents/execution.ts
Danny Avila 1a8d23e1ed
✅ feat: Default Machine Selection and Linked-Worktree Lanes On (#16678)
* ✅ feat: Default Machine Selection and Linked-Worktree Lanes On

Per-chat machine choice from an agent's saved allowlist and linked-worktree
lane routing were both opt-in, so neither worked until a deployment found and
set its flag. Both are now on unless set to false: machine choice still only
applies to agents with a saved allowlist, and lanes still require a worker
that advertises git_linked_worktree. One helper per flag in data-provider
decides the default for every server reader and the advertised client config.

* feat: Advertise the Code Environment Decision Protocol by Default

Per-chat machine choice needs the conversation decision protocol, which the
client requires before offering allowlisted machines, but the protocol was
only advertised when CODE_ENVIRONMENT_DECISION_VERSION=1. With selection on
by default, authors could save an allowlist the composer never offered.
An unset or blank value now advertises protocol v1; any other value, such as
0, keeps the legacy-safe path.

* fix: Turn Machine Choice Off With the Decision Protocol Opt-Out

CODE_ENVIRONMENT_DECISION_VERSION=0 stopped advertising the protocol but
routing still accepted a non-default machine, so a cached tab or a direct
client could persist a choice during a mixed-version rollout. Machine choice
is recorded through that protocol, so isCodeEnvironmentSelectionEnabled now
requires both, for routing and for the advertised endpoints config. The
protocol resolver moves to code/protocol.ts (re-exported from code/config)
so execution and endpoints can use it without an import cycle.

* style: Format checkout routing regression cases

---------

Co-authored-by: Lia <lia@librechat.ai>
2026-10-02 20:08:35 -04:00

493 lines
18 KiB
TypeScript

import { createHash } from 'node:crypto';
import { logger } from '@librechat/data-schemas';
import { Constants, getCodeBaseURL } from '@librechat/agents';
import { resolveCodeEnvironmentSelection } from 'librechat-data-provider';
import type {
Agents,
CodeWorkspaceOperation,
CodeWorkspaceDescriptor,
CodeWorkspaceSelection,
CodeEnvironmentUserConfigSchema,
CodeEnvironmentUserSettings,
StatefulCodeEnvironment,
TAgentsEndpoint,
} from 'librechat-data-provider';
import type { WorkspaceEditFileFeature } from '~/code/edits';
import { isCodeEnvironmentSelectionEnabled } from '~/code/protocol';
import { CodeWorkspaceSelectionError } from '~/code/errors';
export const CODE_API_EXPECTED_PROFILE_HEADER = 'X-CodeAPI-Expected-Profile';
export const CODE_API_BRIDGE_WORKER_HEADER = 'X-LibreChat-Code-Worker-ID';
/** Persisted choices are authoritative, including an empty set. All execution ingresses share
* this precedence so a request cannot replace an admitted conversation's machine selection. */
export function resolveCodeExecutionWorkspaceSelections({
conversation,
request,
}: {
conversation?: { codeWorkspaces?: unknown } | null;
request?: { codeWorkspaces?: unknown } | null;
}): unknown {
return conversation?.codeWorkspaces ?? request?.codeWorkspaces;
}
export type CodeExecutionProfile = 'default' | 'stateful';
export type CodeEnvironmentConfig = NonNullable<
NonNullable<TAgentsEndpoint['statefulCodeSessions']>['environments']
>[number] & {
/** Server-resolved control plane for a principal-owned attached environment. */
controlPlaneId?: string;
};
export interface CodeExecutionContext {
baseUrl: string;
codeSessionKey: string;
executionProfile: CodeExecutionProfile;
/** Stable server-side namespace for deployment-local file references and
* priming work. Unlike `executionProfile`, this distinguishes configured
* Code API deployments that all use the `stateful` wire profile. */
executionRouteKey?: string;
runtimeSessionHint?: string;
statefulSessions: boolean;
environmentId?: string;
environmentType?: CodeEnvironmentConfig['type'];
bridgeWorkerId?: string;
codeEnvironmentConfigSchema?: CodeEnvironmentUserConfigSchema;
codeEnvironmentSettings?: CodeEnvironmentUserSettings;
/** Server-derived conversation identity, activated only after worker capability negotiation. */
conversationWorkspaceInstanceId?: string;
/** Live, server-validated directory selection. Never derive session reuse from this field. */
codeWorkspace?: CodeWorkspaceSelection & {
operations: CodeWorkspaceOperation[];
workspaceInstanceId?: string;
/** The worker schedules each `.worktrees/<name>` of this root as its own lane. */
linkedWorktrees?: boolean;
/** Live Code API execution ceiling. Omitted by older deployments. */
maxCommandTimeoutMs?: number;
/** Edit features the worker negotiated with the Code API. Omitted by older workers. */
editFileFeatures?: WorkspaceEditFileFeature[];
instructions?: CodeWorkspaceDescriptor['instructions'];
environment?: CodeWorkspaceDescriptor['environment'];
};
}
/** Removes live capability data before a workspace binding is persisted. */
export function getCodeWorkspaceSelections(
contexts: Array<
| Pick<CodeExecutionContext, 'environmentId' | 'environmentType' | 'codeWorkspace'>
| null
| undefined
>,
): CodeWorkspaceSelection[] | undefined {
const selections = new Map<string, CodeWorkspaceSelection>();
for (const context of contexts) {
const workspace = context?.codeWorkspace;
if (
context?.environmentType !== 'attached' ||
context.environmentId == null ||
workspace == null ||
workspace.environmentId !== context.environmentId
) {
continue;
}
selections.set(workspace.environmentId, {
environmentId: workspace.environmentId,
workspaceId: workspace.workspaceId,
...(workspace.checkout == null ? {} : { checkout: workspace.checkout }),
...(workspace.agentIds == null ? {} : { agentIds: [...workspace.agentIds] }),
});
}
if (selections.size === 0) return undefined;
return [...selections.values()].sort((a, b) => a.environmentId.localeCompare(b.environmentId));
}
type CodeExecutionApprovalAgent = {
id?: string | null;
codeExecutionContext?: CodeExecutionContext | null;
};
const CODE_EXECUTION_TARGET_HASH = /^[a-f0-9]{64}$/;
const MAX_CODE_EXECUTION_APPROVAL_TARGETS = 128;
/**
* Captures an opaque identity for every stateful code target reachable by a
* paused run. Raw base URLs, worker IDs and session hints never enter the
* pending-action client projection.
*/
export function captureCodeExecutionApprovalBinding(
agents: readonly (CodeExecutionApprovalAgent | null | undefined)[],
): Agents.CodeExecutionApprovalBinding | undefined {
const targetsByIdentity = new Map<string, Agents.CodeExecutionApprovalTargetBinding>();
for (const agent of agents) {
const context = agent?.codeExecutionContext;
if (context?.statefulSessions !== true) {
continue;
}
const targetHash = createHash('sha256')
.update(
JSON.stringify([
agent?.id ?? null,
context.executionProfile,
context.baseUrl,
context.codeSessionKey,
context.executionRouteKey ?? null,
context.runtimeSessionHint ?? null,
context.environmentId ?? null,
context.environmentType ?? null,
context.bridgeWorkerId ?? null,
context.codeWorkspace == null
? null
: {
environmentId: context.codeWorkspace.environmentId,
workspaceId: context.codeWorkspace.workspaceId,
workspaceInstanceId: context.codeWorkspace.workspaceInstanceId ?? null,
operations: [...new Set(context.codeWorkspace.operations)].sort(),
...(context.codeWorkspace.environment
? { definitionFingerprint: context.codeWorkspace.environment.fingerprint }
: {}),
},
]),
)
.digest('hex');
const target = { agentId: agent?.id ?? null, targetHash };
targetsByIdentity.set(`${target.agentId ?? ''}\u0000${target.targetHash}`, target);
}
const targets = [...targetsByIdentity.values()];
if (targets.length === 0) {
return undefined;
}
/** Relational string comparison is defined over UTF-16 code units. Unlike
* localeCompare, this produces the same canonical order on every replica
* regardless of its ICU build or process locale. */
targets.sort((left, right) => {
const leftAgentId = left.agentId ?? '';
const rightAgentId = right.agentId ?? '';
if (leftAgentId !== rightAgentId) {
return leftAgentId < rightAgentId ? -1 : 1;
}
if (left.targetHash === right.targetHash) {
return 0;
}
return left.targetHash < right.targetHash ? -1 : 1;
});
return { version: 1, targets };
}
function isCodeExecutionApprovalBinding(
value: unknown,
): value is Agents.CodeExecutionApprovalBinding {
if (value == null || typeof value !== 'object' || Array.isArray(value)) {
return false;
}
const binding = value as Partial<Agents.CodeExecutionApprovalBinding>;
if (
binding.version !== 1 ||
!Array.isArray(binding.targets) ||
binding.targets.length === 0 ||
binding.targets.length > MAX_CODE_EXECUTION_APPROVAL_TARGETS
) {
return false;
}
const identities = new Set<string>();
for (const target of binding.targets) {
if (
target == null ||
typeof target !== 'object' ||
Array.isArray(target) ||
!(
target.agentId === null ||
(typeof target.agentId === 'string' && target.agentId.length <= 256)
) ||
typeof target.targetHash !== 'string' ||
!CODE_EXECUTION_TARGET_HASH.test(target.targetHash)
) {
return false;
}
const identity = `${target.agentId ?? ''}\u0000${target.targetHash}`;
if (identities.has(identity)) {
return false;
}
identities.add(identity);
}
return true;
}
export class CodeExecutionApprovalTargetChangedError extends Error {
readonly code = 'CODE_EXECUTION_APPROVAL_TARGET_CHANGED';
constructor() {
super(
'The attached code environment changed while this action awaited approval. Retry the request and review the action again before running it.',
);
this.name = 'CodeExecutionApprovalTargetChangedError';
}
}
/** Backward-compatible for old pauses; present bindings always fail closed. */
export function assertCodeExecutionApprovalBinding(
expected: unknown,
agents: readonly (CodeExecutionApprovalAgent | null | undefined)[],
): void {
if (expected == null) {
return;
}
const current = captureCodeExecutionApprovalBinding(agents);
if (
!isCodeExecutionApprovalBinding(expected) ||
current == null ||
JSON.stringify(expected.targets) !== JSON.stringify(current.targets)
) {
throw new CodeExecutionApprovalTargetChangedError();
}
}
export function createCodeExecutionRouteKey(
profile: CodeExecutionProfile,
environment?: Pick<CodeEnvironmentConfig, 'id' | 'baseURL' | 'workerId' | 'pairing'>,
): string {
if (profile === 'default' || environment == null) {
return profile;
}
const identity = JSON.stringify([
environment.id,
environment.baseURL.trim().replace(/\/+$/, ''),
environment.workerId ?? environment.pairing?.workerId ?? '',
]);
return `stateful:${createHash('sha256').update(identity).digest('hex').slice(0, 32)}`;
}
export function getCodeExecutionRouteKey(
context: Pick<CodeExecutionContext, 'executionProfile' | 'executionRouteKey'>,
): string {
return context.executionRouteKey ?? context.executionProfile;
}
export function normalizeStatefulCodeEnvironment(
environment?: StatefulCodeEnvironment | string | null,
): StatefulCodeEnvironment {
if (environment === 'agent-user') {
return 'agent-user';
}
if (environment === 'conversation') {
return 'conversation';
}
return 'user';
}
export function getCodeExecutionBaseUrl(
profile: CodeExecutionProfile,
environment?: CodeEnvironmentConfig,
): string {
if (profile === 'default') {
return getCodeBaseURL().replace(/\/+$/, '');
}
if (environment) {
return environment.baseURL.trim().replace(/\/+$/, '');
}
const baseUrl = process.env.LIBRECHAT_CODE_BASEURL_STATEFUL?.trim().replace(/\/+$/, '');
if (baseUrl) {
return baseUrl;
}
throw new Error(
'Stateful code execution is enabled for this agent, but LIBRECHAT_CODE_BASEURL_STATEFUL is not configured.',
);
}
function resolveRuntimeSessionHint(params: {
environment: StatefulCodeEnvironment;
environmentId?: string;
userId: string;
agentId?: string | null;
conversationId?: string | null;
}): string {
const { environment, environmentId, userId, agentId, conversationId } = params;
const scopeFingerprint = (...parts: string[]): string =>
createHash('sha256').update(JSON.stringify(parts)).digest('hex').slice(0, 32);
const prefix = environmentId ? `v3:${scopeFingerprint(environmentId).slice(0, 12)}` : 'v2';
if (environment === 'agent-user') {
if (!agentId) {
throw new Error('Agent-user code environments require an agent ID.');
}
return `${prefix}:agent-user:${scopeFingerprint(userId, agentId)}`;
}
if (environment === 'conversation') {
if (!conversationId) {
throw new Error('Conversation code environments require a conversation ID.');
}
return `${prefix}:conversation:${scopeFingerprint(userId, conversationId)}`;
}
return `${prefix}:user:${scopeFingerprint(userId)}`;
}
function isExecutableEnvironment(environment: CodeEnvironmentConfig): boolean {
return !(
environment.pairing?.allowPrincipalWorkers === true &&
environment.pairing.workerId == null &&
environment.workerId == null
);
}
function resolveConfiguredEnvironment(params: {
environmentId?: string | null;
environments?: readonly CodeEnvironmentConfig[];
}): CodeEnvironmentConfig | undefined {
const { environmentId, environments } = params;
const executableEnvironments = environments?.filter(isExecutableEnvironment);
if (environmentId) {
const configured = executableEnvironments?.find(
(environment) => environment.id === environmentId,
);
if (!configured) {
throw new Error(`Stateful code environment "${environmentId}" is not configured.`);
}
return configured;
}
return executableEnvironments?.find((environment) => environment.default === true);
}
export function resolveCodeExecutionContext(params: {
statefulSessions: boolean;
environment?: StatefulCodeEnvironment | string | null;
environmentId?: string | null;
environments?: readonly CodeEnvironmentConfig[];
userId?: string | null;
agentId?: string | null;
conversationId?: string | null;
/** Deployment ceiling (on unless `false` or the decision protocol is off) and a persisted
* agent machine allowlist are both required. */
allowEnvironmentSelection?: boolean;
environmentIds?: readonly string[];
workspaceSelections?: unknown;
}): CodeExecutionContext {
if (!params.statefulSessions) {
return {
baseUrl: getCodeExecutionBaseUrl('default'),
codeSessionKey: Constants.EXECUTE_CODE,
executionProfile: 'default',
statefulSessions: false,
};
}
const environment = normalizeStatefulCodeEnvironment(params.environment);
const defaultEnvironment = params.environments?.find(
(candidate) =>
isExecutableEnvironment(candidate) &&
(params.environmentId ? candidate.id === params.environmentId : candidate.default === true),
);
const allowSelection =
isCodeEnvironmentSelectionEnabled(params.allowEnvironmentSelection) &&
(params.environmentIds?.length ?? 0) > 0 &&
(defaultEnvironment?.type === 'attached' ||
(defaultEnvironment == null && Boolean(params.environmentId)));
const selection = resolveCodeEnvironmentSelection({
agentId: params.agentId,
environmentId: params.environmentId ?? defaultEnvironment?.id,
environmentIds: params.environmentIds,
allowSelection,
selections: params.workspaceSelections,
});
if (!selection.valid) throw new CodeWorkspaceSelectionError('invalid');
if (
allowSelection &&
!params.environments?.some(
(candidate) => candidate.id === selection.environmentId && isExecutableEnvironment(candidate),
)
) {
throw new CodeWorkspaceSelectionError('invalid');
}
const configuredEnvironment = resolveConfiguredEnvironment({
...params,
environmentId: selection.environmentId,
});
if (allowSelection && configuredEnvironment?.type !== 'attached') {
throw new CodeWorkspaceSelectionError('unsupported');
}
if (!params.userId) {
throw new Error('Stateful code environments require an authenticated user ID.');
}
const runtimeSessionHint = resolveRuntimeSessionHint({
environment,
environmentId: configuredEnvironment?.id,
userId: params.userId,
agentId: params.agentId,
conversationId: params.conversationId,
});
const executionRouteKey = createCodeExecutionRouteKey('stateful', configuredEnvironment);
const conversationWorkspaceInstanceId =
configuredEnvironment?.type === 'attached' && params.conversationId
? createHash('sha256')
.update('librechat-conversation-workspace-v1\0')
.update(JSON.stringify([params.userId, params.conversationId, configuredEnvironment.id]))
.digest('hex')
: undefined;
return {
baseUrl: getCodeExecutionBaseUrl('stateful', configuredEnvironment),
codeSessionKey: `${Constants.EXECUTE_CODE}:${executionRouteKey}:${runtimeSessionHint}`,
executionProfile: 'stateful',
...(configuredEnvironment ? { executionRouteKey } : {}),
runtimeSessionHint,
statefulSessions: true,
environmentId: configuredEnvironment?.id,
environmentType: configuredEnvironment?.type,
bridgeWorkerId: configuredEnvironment?.workerId ?? configuredEnvironment?.pairing?.workerId,
codeEnvironmentConfigSchema: configuredEnvironment?.configSchema,
codeEnvironmentSettings: configuredEnvironment?.settings,
...(conversationWorkspaceInstanceId ? { conversationWorkspaceInstanceId } : {}),
};
}
export function codeExecutionHeaders(
context: Pick<CodeExecutionContext, 'executionProfile' | 'bridgeWorkerId'>,
): Record<string, string> {
return {
[CODE_API_EXPECTED_PROFILE_HEADER]: context.executionProfile,
...(context.bridgeWorkerId != null
? { [CODE_API_BRIDGE_WORKER_HEADER]: context.bridgeWorkerId }
: {}),
};
}
/**
* The cause belongs in the message rather than in winston metadata. A caught
* value passed as metadata is merged onto the log record, so a rejection
* carrying `tenantId`, `userId` or `event_name` would overwrite the request
* identity this log exists to provide; and any metadata makes `format.splat()`
* treat a `%s` in the cause as a substitution token. Every read is guarded:
* `String()` throws on a null-prototype object and a proxy can throw from a
* `name` or `message` accessor, either of which would otherwise replace the
* rejection with a formatting error and log nothing.
*/
function describeAuthFailure(error: unknown): string {
try {
return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
} catch {
return 'undescribable rejection';
}
}
/**
* `@librechat/agents` replaces any throw from this callback with a fixed
* "not authorized" string before the model or the operator sees it, and its own
* console diagnostic carries no request or user id. This log is the only
* request-correlated record of why the headers could not be resolved.
*/
export async function codeExecutionAuthHeaders(
authHeaders: (
bridgeWorkerId?: string,
) => Promise<Record<string, string>> | Record<string, string>,
context: Pick<CodeExecutionContext, 'executionProfile' | 'bridgeWorkerId'>,
): Promise<Record<string, string>> {
try {
return {
...(await authHeaders(context.bridgeWorkerId)),
...codeExecutionHeaders(context),
};
} catch (error) {
logger.error(
`[codeExecutionAuthHeaders] Failed to resolve Code API auth headers | Profile: ${context.executionProfile}` +
(context.bridgeWorkerId != null ? ` | Worker: ${context.bridgeWorkerId}` : '') +
` | Cause: ${describeAuthFailure(error)}`,
);
throw error;
}
}