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>
283 lines
12 KiB
TypeScript
283 lines
12 KiB
TypeScript
import { stripAgentIdSuffix } from '../agents/identity';
|
|
|
|
export const CODE_WORKSPACE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
|
|
/** Protocol-v1 ceiling enforced by the worker and Code API. */
|
|
export const CODE_WORKSPACE_MAX_COUNT = 32;
|
|
/** Wire/storage safety ceiling; deployments may set a lower per-agent choice limit. */
|
|
export const MAX_AGENT_CODE_ENVIRONMENT_CHOICES = 128;
|
|
export const DEFAULT_AGENT_CODE_ENVIRONMENT_CHOICES = 32;
|
|
|
|
/**
|
|
* Per-chat machine choice is on unless a deployment sets `allowEnvironmentSelection: false`.
|
|
* It only ever applies to agents whose author saved a machine allowlist; every other agent
|
|
* keeps its fixed machine either way.
|
|
*/
|
|
export function isCodeEnvironmentSelectionAllowed(
|
|
allowEnvironmentSelection?: boolean | null,
|
|
): boolean {
|
|
return allowEnvironmentSelection !== false;
|
|
}
|
|
|
|
/**
|
|
* Linked-worktree lanes are on unless an environment sets `workspaces.linkedWorktrees: false`.
|
|
* They only apply where the worker advertises the `git_linked_worktree` scope.
|
|
*/
|
|
export function isLinkedWorktreeRoutingAllowed(linkedWorktrees?: boolean | null): boolean {
|
|
return linkedWorktrees !== false;
|
|
}
|
|
/** API/client protocol for immutable conversation-owned environment decisions. */
|
|
export const CODE_ENVIRONMENT_DECISION_VERSION = 1 as const;
|
|
/** API/client protocol for an owner's explicit move of a sealed environment decision. */
|
|
export const CODE_ENVIRONMENT_MOVE_VERSION = 1 as const;
|
|
/**
|
|
* API/client protocol for the other two replacements of a sealed decision: attaching an
|
|
* environment to a chat that recorded running without one, and leaving attached execution behind.
|
|
* Advertised beside the move version rather than replacing it, so a client that predates this
|
|
* capability keeps the move it already had while a deployment rolls out, and a client that has it
|
|
* never offers an attach a replica would refuse as `locked` or a detach it would call `invalid`.
|
|
*/
|
|
export const CODE_ENVIRONMENT_TRANSITION_VERSION = 2 as const;
|
|
/** Additive capability for replacing a missing workspace without disabling moves in V1 clients. */
|
|
export const CODE_WORKSPACE_RECOVERY_VERSION = 1 as const;
|
|
export const CODE_WORKSPACE_OPERATIONS = [
|
|
'read_file',
|
|
'search_text',
|
|
'list_files',
|
|
'write_file',
|
|
'preview_edit',
|
|
'edit_file',
|
|
'execute_command',
|
|
] as const;
|
|
export const CODE_WORKSPACE_INSTANCE_TYPES = ['git_worktree'] as const;
|
|
export const CODE_WORKSPACE_CHECKOUT_MODES = ['source', 'isolated'] as const;
|
|
/** Scheduling scopes a worker can admit beneath one registered root. */
|
|
export const CODE_WORKSPACE_SCOPES = ['git_linked_worktree'] as const;
|
|
export const CODE_WORKSPACE_SELECTION_ERROR_REASONS = [
|
|
'required',
|
|
'invalid',
|
|
'worker_unavailable',
|
|
'unsupported',
|
|
'missing',
|
|
'locked',
|
|
] as const;
|
|
export const CODE_ENVIRONMENT_MODES = ['attached', 'without_attached'] as const;
|
|
|
|
export type CodeWorkspaceOperation = (typeof CODE_WORKSPACE_OPERATIONS)[number];
|
|
export type CodeWorkspaceInstanceType = (typeof CODE_WORKSPACE_INSTANCE_TYPES)[number];
|
|
export type CodeWorkspaceScope = (typeof CODE_WORKSPACE_SCOPES)[number];
|
|
export type CodeWorkspaceSelectionErrorReason =
|
|
(typeof CODE_WORKSPACE_SELECTION_ERROR_REASONS)[number];
|
|
export type CodeEnvironmentMode = (typeof CODE_ENVIRONMENT_MODES)[number];
|
|
|
|
/** Public, path-free description of one root registered by an attached worker. */
|
|
export interface CodeWorkspaceDescriptor {
|
|
id: string;
|
|
name?: string;
|
|
instructions?: RepositoryInstructionDescriptor[];
|
|
/** Omitted when every worker-level operation applies to this workspace. */
|
|
operations?: CodeWorkspaceOperation[];
|
|
/** Optional worker-managed isolation modes available beneath this root. */
|
|
workspaceInstances?: CodeWorkspaceInstanceType[];
|
|
/** `git_linked_worktree`: each `.worktrees/<name>` runs in its own scheduling lane. */
|
|
workspaceScopes?: CodeWorkspaceScope[];
|
|
environment?: {
|
|
fingerprint: string;
|
|
repo?: string;
|
|
ref?: string;
|
|
actions: string[];
|
|
};
|
|
}
|
|
|
|
export type RepositoryInstructionMode = 'prefer' | 'defer' | 'off';
|
|
export interface RepositoryInstructionDescriptor {
|
|
path: 'AGENTS.md' | 'CLAUDE.md';
|
|
bytes: number;
|
|
sha256: string;
|
|
truncated: boolean;
|
|
}
|
|
export function isRepositoryInstructionDescriptor(
|
|
value: unknown,
|
|
): value is RepositoryInstructionDescriptor {
|
|
if (value == null || typeof value !== 'object') return false;
|
|
const descriptor = value as Record<string, unknown>;
|
|
return (
|
|
Object.keys(descriptor).every((key) =>
|
|
['path', 'bytes', 'sha256', 'truncated'].includes(key),
|
|
) &&
|
|
(descriptor.path === 'AGENTS.md' || descriptor.path === 'CLAUDE.md') &&
|
|
Number.isSafeInteger(descriptor.bytes) &&
|
|
Number(descriptor.bytes) >= 0 &&
|
|
Number(descriptor.bytes) <= 32768 &&
|
|
typeof descriptor.sha256 === 'string' &&
|
|
/^[a-f0-9]{64}$/.test(descriptor.sha256) &&
|
|
typeof descriptor.truncated === 'boolean'
|
|
);
|
|
}
|
|
|
|
export function isCodeWorkspaceEnvironment(
|
|
value: unknown,
|
|
): value is NonNullable<CodeWorkspaceDescriptor['environment']> {
|
|
if (value == null || typeof value !== 'object' || Array.isArray(value)) return false;
|
|
const environment = value as Record<string, unknown>;
|
|
return (
|
|
Object.keys(environment).every((key) =>
|
|
['fingerprint', 'repo', 'ref', 'actions'].includes(key),
|
|
) &&
|
|
typeof environment.fingerprint === 'string' &&
|
|
/^[a-f0-9]{64}$/.test(environment.fingerprint) &&
|
|
(environment.repo === undefined ||
|
|
(typeof environment.repo === 'string' &&
|
|
environment.repo.length <= 256 &&
|
|
/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(environment.repo))) &&
|
|
(environment.ref === undefined ||
|
|
(typeof environment.ref === 'string' &&
|
|
environment.ref.trim().length > 0 &&
|
|
environment.ref.length <= 256 &&
|
|
!/[\0\r\n]/.test(environment.ref))) &&
|
|
Array.isArray(environment.actions) &&
|
|
environment.actions.length <= 32 &&
|
|
environment.actions.every(
|
|
(name) => typeof name === 'string' && /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(name),
|
|
) &&
|
|
new Set(environment.actions).size === environment.actions.length
|
|
);
|
|
}
|
|
|
|
/** Conversation-owned selection, bound to the environment that advertised it. */
|
|
export interface CodeWorkspaceSelection {
|
|
environmentId: string;
|
|
workspaceId: string;
|
|
/** Omitted preserves the worker's legacy automatic isolation policy. */
|
|
checkout?: (typeof CODE_WORKSPACE_CHECKOUT_MODES)[number];
|
|
/** Explicit graph-agent ownership of a chat machine choice; absent on legacy selections. */
|
|
agentIds?: string[];
|
|
}
|
|
|
|
/** Explicit isolation never falls back to shared files when a capability or policy disappears. */
|
|
export function isCodeWorkspaceCheckoutAvailable(
|
|
selection: Pick<CodeWorkspaceSelection, 'checkout'>,
|
|
workspace: Pick<CodeWorkspaceDescriptor, 'workspaceInstances'> | undefined,
|
|
allowSelection: boolean,
|
|
): boolean {
|
|
return (
|
|
selection.checkout == null ||
|
|
(allowSelection &&
|
|
workspace != null &&
|
|
(selection.checkout === 'source' ||
|
|
workspace.workspaceInstances?.includes('git_worktree') === true))
|
|
);
|
|
}
|
|
|
|
export function isCodeEnvironmentMode(value: unknown): value is CodeEnvironmentMode {
|
|
return CODE_ENVIRONMENT_MODES.some((mode) => mode === value);
|
|
}
|
|
|
|
export function isCodeWorkspaceSelectionErrorReason(
|
|
value: unknown,
|
|
): value is CodeWorkspaceSelectionErrorReason {
|
|
return CODE_WORKSPACE_SELECTION_ERROR_REASONS.some((reason) => reason === value);
|
|
}
|
|
|
|
export function isCodeWorkspaceSelection(value: unknown): value is CodeWorkspaceSelection {
|
|
if (value == null || typeof value !== 'object' || Array.isArray(value)) {
|
|
return false;
|
|
}
|
|
const selection = value as Record<string, unknown>;
|
|
return (
|
|
Object.keys(selection).every((key) =>
|
|
['environmentId', 'workspaceId', 'agentIds', 'checkout'].includes(key),
|
|
) &&
|
|
typeof selection.environmentId === 'string' &&
|
|
CODE_WORKSPACE_ID_PATTERN.test(selection.environmentId) &&
|
|
typeof selection.workspaceId === 'string' &&
|
|
CODE_WORKSPACE_ID_PATTERN.test(selection.workspaceId) &&
|
|
(selection.checkout === undefined ||
|
|
selection.checkout === 'source' ||
|
|
selection.checkout === 'isolated') &&
|
|
(selection.agentIds === undefined ||
|
|
(Array.isArray(selection.agentIds) &&
|
|
selection.agentIds.length > 0 &&
|
|
selection.agentIds.length <= MAX_AGENT_CODE_ENVIRONMENT_CHOICES &&
|
|
selection.agentIds.every(
|
|
(id) => typeof id === 'string' && CODE_WORKSPACE_ID_PATTERN.test(id),
|
|
) &&
|
|
new Set(selection.agentIds).size === selection.agentIds.length))
|
|
);
|
|
}
|
|
|
|
/** One exact workspace per attached environment used by a conversation. */
|
|
export function isCodeWorkspaceSelections(value: unknown): value is CodeWorkspaceSelection[] {
|
|
if (!Array.isArray(value)) return false;
|
|
const environmentIds = new Set<string>();
|
|
const agentIds = new Set<string>();
|
|
return value.every((selection) => {
|
|
if (!isCodeWorkspaceSelection(selection) || environmentIds.has(selection.environmentId)) {
|
|
return false;
|
|
}
|
|
environmentIds.add(selection.environmentId);
|
|
for (const id of selection.agentIds ?? []) {
|
|
if (agentIds.has(id)) return false;
|
|
agentIds.add(id);
|
|
if (agentIds.size > MAX_AGENT_CODE_ENVIRONMENT_CHOICES) return false;
|
|
}
|
|
return true;
|
|
});
|
|
}
|
|
|
|
/** Stable decision serialization includes ownership so replay cannot change an agent's route. */
|
|
export function canonicalizeCodeWorkspaceSelections(
|
|
selections: CodeWorkspaceSelection[],
|
|
): CodeWorkspaceSelection[] {
|
|
return selections
|
|
.map(({ environmentId, workspaceId, agentIds, checkout }) => ({
|
|
environmentId,
|
|
workspaceId,
|
|
...(checkout == null ? {} : { checkout }),
|
|
...(agentIds == null ? {} : { agentIds: [...agentIds].sort() }),
|
|
}))
|
|
.sort((left, right) => left.environmentId.localeCompare(right.environmentId));
|
|
}
|
|
|
|
/** Resolves an agent's default or its chat-owned machine choice. Callers still authorize the
|
|
* resolved ID against their principal-scoped environment list and verify live capabilities. */
|
|
export function resolveCodeEnvironmentSelection({
|
|
environmentId,
|
|
environmentIds,
|
|
agentId,
|
|
allowSelection,
|
|
selections,
|
|
}: {
|
|
environmentId?: string | null;
|
|
environmentIds?: readonly string[];
|
|
agentId?: string | null;
|
|
allowSelection?: boolean;
|
|
selections?: unknown;
|
|
}): { valid: true; environmentId?: string | null } | { valid: false } {
|
|
if (selections == null) return { valid: true, environmentId };
|
|
if (!isCodeWorkspaceSelections(selections)) return { valid: false };
|
|
if (selections.length === 0) return { valid: true, environmentId };
|
|
/** Ownership is persisted under the saved agent ID, not the parallel actor's runtime ID.
|
|
* Check it before feature gates so revoked routes cannot silently revert to the default. */
|
|
const stableAgentId = agentId == null ? undefined : stripAgentIdSuffix(agentId);
|
|
const owned =
|
|
stableAgentId == null
|
|
? undefined
|
|
: selections.find((selection) => selection.agentIds?.includes(stableAgentId));
|
|
if (owned != null) {
|
|
if (owned.environmentId === environmentId) return { valid: true, environmentId };
|
|
return allowSelection === true && environmentIds?.includes(owned.environmentId)
|
|
? { valid: true, environmentId: owned.environmentId }
|
|
: { valid: false };
|
|
}
|
|
if (!allowSelection) return { valid: true, environmentId };
|
|
const allowed = new Set(environmentIds ?? []);
|
|
if (environmentId) allowed.add(environmentId);
|
|
const matches = selections.filter((selection) => allowed.has(selection.environmentId));
|
|
/** A graph may need an alternative for a different agent. Preserve this agent's explicit
|
|
* default when present; without it, require exactly one allowed target rather than guessing. */
|
|
const selectedDefault = matches.find((selection) => selection.environmentId === environmentId);
|
|
if (selectedDefault != null) return { valid: true, environmentId };
|
|
const legacy = matches.filter((selection) => selection.agentIds == null);
|
|
if (legacy.length !== 1) return { valid: false };
|
|
return { valid: true, environmentId: legacy[0].environmentId };
|
|
}
|