mirror of
https://github.com/danny-avila/LibreChat.git
synced 2026-11-16 13:00:55 +00:00
* ✅ 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>
493 lines
18 KiB
TypeScript
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;
|
|
}
|
|
}
|