LibreChat/packages/api/src/agents/execution.ts
Marco Beretta ecd6943194
✂️ refactor: Remove Dead Helpers, Classes and Dependencies From packages/api (#17118)
* refactor: Remove Unused Agent Helpers and Superseded Wrappers

* refactor: Remove Dead Auth, Middleware, Protection and Prompt Helpers

* refactor: Remove Dead MCP, File, Skill and Endpoint Code

* refactor: Remove Dead Stream, Telemetry, Utility and Type Exports

* chore: Drop Unused packages/api Dependencies From bun.lock

* refactor: Keep Published Compatibility and Deprecated packages/api Exports
2026-10-16 15:43:12 +02:00

524 lines
20 KiB
TypeScript

import { createHash } from 'node:crypto';
import { logger } from '@librechat/data-schemas';
import { Constants, getCodeBaseURL } from '@librechat/agents';
import { stripAgentIdSuffix, 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;
/** The worker advertises the native SRT sandbox: read-only filesystem outside the workspace and `$TMPDIR`. */
nativeSandbox?: 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'];
};
}
type CodeExecutionApprovalAgent = {
id?: string | null;
codeExecutionContext?: CodeExecutionContext | null;
/** Alternate machines a parent may route this subagent to per call. */
codeExecutionChoices?: readonly CodeExecutionContext[] | null;
};
function hashCodeExecutionTarget(agentId: string | null, context: CodeExecutionContext): string {
return createHash('sha256')
.update(
JSON.stringify([
agentId,
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 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>();
const addTarget = (target: Agents.CodeExecutionApprovalTargetBinding): void => {
targetsByIdentity.set(`${target.agentId ?? ''}\u0000${target.targetHash}`, target);
};
for (const agent of agents) {
const agentId = agent?.id ?? null;
const routeHashes = [agent?.codeExecutionContext, ...(agent?.codeExecutionChoices ?? [])]
.filter((context): context is CodeExecutionContext => context?.statefulSessions === true)
.map((context) => hashCodeExecutionTarget(agentId, context));
if (routeHashes.length === 0) {
continue;
}
/** An agent with per-call choices folds its default and every choice into one
* target, so each agent contributes at most one entry to the bounded binding. */
addTarget({
agentId,
targetHash:
(agent?.codeExecutionChoices?.length ?? 0) === 0
? routeHashes[0]
: createHash('sha256')
.update(JSON.stringify(['choices', [...new Set(routeHashes)].sort()]))
.digest('hex'),
});
}
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);
}
/** Machine an agent runs on without a conversation choice, and whether a choice applies to it. */
export function resolveAgentCodeEnvironmentRouting(params: {
environmentId?: string | null;
environmentIds?: readonly string[];
environments?: readonly CodeEnvironmentConfig[];
/** Deployment ceiling (on unless `false` or the decision protocol is off). */
allowEnvironmentSelection?: boolean;
}): { defaultEnvironment?: CodeEnvironmentConfig; allowSelection: boolean } {
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)));
return { defaultEnvironment, allowSelection };
}
/** Whether the principal-scoped environment list admits running on this attached machine. */
export function isExecutableAttachedEnvironment(
environmentId: string,
environments?: readonly CodeEnvironmentConfig[],
): boolean {
return (
environments?.some(
(candidate) =>
candidate.id === environmentId &&
candidate.type === 'attached' &&
isExecutableEnvironment(candidate),
) === 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;
/** Request-scoped subagent inheritance, keyed by saved agent ID. An inherited machine the
* principal can no longer use is ignored, leaving the agent on its own route. */
inheritedEnvironments?: ReadonlyMap<string, string>;
}): CodeExecutionContext {
if (!params.statefulSessions) {
return {
baseUrl: getCodeExecutionBaseUrl('default'),
codeSessionKey: Constants.EXECUTE_CODE,
executionProfile: 'default',
statefulSessions: false,
};
}
const environment = normalizeStatefulCodeEnvironment(params.environment);
const { defaultEnvironment, allowSelection } = resolveAgentCodeEnvironmentRouting(params);
const inheritedEnvironmentId =
params.agentId == null
? undefined
: params.inheritedEnvironments?.get(stripAgentIdSuffix(params.agentId));
const selection = resolveCodeEnvironmentSelection({
agentId: params.agentId,
environmentId: params.environmentId ?? defaultEnvironment?.id,
environmentIds: params.environmentIds,
allowSelection,
selections: params.workspaceSelections,
inheritedEnvironmentId:
inheritedEnvironmentId != null &&
isExecutableAttachedEnvironment(inheritedEnvironmentId, params.environments)
? inheritedEnvironmentId
: undefined,
});
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;
}
}