Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
import { trace } from '@opentelemetry/api';
import { logger } from '@librechat/data-schemas';
import {
codeEnvironmentAdmissionSchema,
CODE_ENVIRONMENT_ADMISSION_MAX_MS,
CODE_ENVIRONMENT_COMMAND_TIMEOUT_DEFAULT_MS,
CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES,
CODE_ENVIRONMENT_READ_FILE_HARD_MAX_LINES,
CODE_ENVIRONMENT_COMMAND_ADMISSION_DEFAULT_MS,
CODE_ENVIRONMENT_QUEUE_WAIT_DEFAULT_MS,
CODE_ENVIRONMENT_REQUEST_TIMEOUT_HARD_MAX_MS,
} from 'librechat-data-provider';
import type { CodeEnvironmentUserConfigSchema } from 'librechat-data-provider';
import type { WorkspaceEditMatch, WorkspaceEditMatching } from './edits';
import type { CodeBridgeFetch } from './bridge';
import { executeDurableWorkspaceRequest, WorkspaceResponseTransportError } from './requests';
import { CODE_API_RATE_LIMIT_WAIT_DEFAULT_MS } from './limits';
import { WORKSPACE_EDIT_MATCH_STRATEGIES } from './edits';
const WORKSPACE_TOOL_TIMEOUT_MS = 30_000;
const MAX_PATH_LENGTH = 4096;
const MAX_QUERY_LENGTH = 4096;
const MAX_READ_BYTES = 1024 * 1024;
const MAX_READ_LINES = CODE_ENVIRONMENT_READ_FILE_HARD_MAX_LINES;
const MAX_SEARCH_RESULTS = 200;
const MAX_SEARCH_TEXT_LENGTH = 2000;
const MAX_LIST_RESULTS = 500;
export const WORKSPACE_WRITE_MAX_BYTES: number = 1024 * 1024;
export const WORKSPACE_EDIT_MAX_COUNT: number = 100;
const MAX_COMMAND_BYTES = 32 * 1024;
/** Keep aligned with data-provider's deployment schema defaults and hard cap. */
export const WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS: number =
CODE_ENVIRONMENT_COMMAND_TIMEOUT_DEFAULT_MS;
export const WORKSPACE_COMMAND_MAX_TIMEOUT_MS: number = 5 * 60_000;
const DEFAULT_COMMAND_OUTPUT_BYTES = 256 * 1024;
const MAX_COMMAND_OUTPUT_BYTES = 1024 * 1024;
const MAX_COMMAND_SIGNAL_LENGTH = 32;
const MAX_LANE_BRANCH_LENGTH = 256;
const WORKSPACE_COMMAND_TRANSPORT_GRACE_MS = 5_000;
/** Legacy per-request admission window, independent of the retry horizon. */
const WORKSPACE_QUEUE_TIMEOUT_MS = 30_000;
const WORKSPACE_QUEUE_WAIT_HEADER = 'X-LibreChat-Workspace-Queue-Wait-Ms';
/** Compatibility export; the deployment schema owns the default and hard cap. */
export const WORKSPACE_QUEUE_MAX_WAIT_MS: number = CODE_ENVIRONMENT_QUEUE_WAIT_DEFAULT_MS;
const WORKSPACE_COMMAND_SETTLEMENT_GRACE_MS = 5_000;
/**
* Longest command timeout a total HTTP budget can carry: the budget minus settlement and delivery
* grace and a minimum admission allowance. A command whose reserve reaches the budget is refused
* before dispatch, so a larger ceiling would only advertise timeouts that can never start.
*/
export function fitWorkspaceCommandTimeoutToBudget(
maxRequestTimeoutMs: number,
minCommandAdmissionMs: number = CODE_ENVIRONMENT_COMMAND_ADMISSION_DEFAULT_MS,
): number {
return Math.max(
1,
maxRequestTimeoutMs -
WORKSPACE_COMMAND_SETTLEMENT_GRACE_MS -
WORKSPACE_COMMAND_TRANSPORT_GRACE_MS -
minCommandAdmissionMs,
);
}
const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
const MAX_ERROR_BODY_BYTES = 4096;
const ERROR_BODY_TIMEOUT_MS = 1000;
const READ_RESULT_KEYS = new Set([
'protocolVersion',
'operation',
'workspaceId',
'path',
'content',
'startLine',
'endLine',
'truncated',
'nextStartLine',
]);
const SEARCH_RESULT_KEYS = new Set([
'protocolVersion',
'operation',
'workspaceId',
'matches',
'truncated',
]);
const SEARCH_MATCH_KEYS = new Set(['path', 'line', 'column', 'text']);
const LIST_RESULT_KEYS = new Set([
'protocolVersion',
'operation',
'workspaceId',
'paths',
'truncated',
'nextAfterPath',
]);
const COMMAND_RESULT_KEYS = new Set([
'protocolVersion',
'operation',
'workspaceId',
'exitCode',
'signal',
'stdout',
'stderr',
'truncated',
'timedOut',
'laneGit',
]);
const LANE_GIT_KEYS = new Set(['branch', 'head']);
const WRITE_RESULT_KEYS = new Set([
'protocolVersion',
'operation',
'workspaceId',
'path',
'created',
'bytesWritten',
]);
const EDIT_RESULT_KEYS = new Set([
'protocolVersion',
'operation',
'workspaceId',
'path',
'replacements',
'bytesWritten',
'matches',
]);
const PREVIEW_EDIT_RESULT_KEYS = new Set([
'protocolVersion',
'operation',
'workspaceId',
'path',
'content',
'hasUtf8Bom',
'baseSha256',
'replacements',
'bytesWritten',
'matches',
]);
const IMPORT_RESULT_KEYS = new Set([
'protocolVersion',
'operation',
'workspaceId',
'path',
'created',
'unchanged',
'bytesWritten',
'sha256',
]);
/** Raw Code API storage identifiers are URL-safe nanoids. */
const STORAGE_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
const SHA256_PATTERN = /^[a-f0-9]{64}$/;
const TEXT_EDIT_KEYS = new Set(['oldText', 'newText', 'replaceAll']);
const EDIT_MATCH_KEYS = new Set(['strategy', 'occurrences']);
export interface WorkspaceReadRequest {
protocolVersion: 1;
operation: 'read_file';
workspaceId: string;
workspaceInstanceId?: string;
path: string;
startLine?: number;
maxLines?: number;
instructionSha256?: string;
}
export interface WorkspaceSearchRequest {
protocolVersion: 1;
operation: 'search_text';
workspaceId: string;
workspaceInstanceId?: string;
query: string;
path?: string;
maxResults?: number;
}
export interface WorkspaceListRequest {
protocolVersion: 1;
operation: 'list_files';
workspaceId: string;
workspaceInstanceId?: string;
path?: string;
maxResults?: number;
afterPath?: string;
}
export interface WorkspaceExecuteCommandRequest {
protocolVersion: 1;
operation: 'execute_command';
workspaceId: string;
workspaceInstanceId?: string;
command: string;
cwd?: string;
timeoutMs?: number;
maxOutputBytes?: number;
environmentAction?: { name: string; fingerprint: string };
}
export interface WorkspaceWriteRequest {
protocolVersion: 1;
operation: 'write_file';
workspaceId: string;
workspaceInstanceId?: string;
path: string;
content: string;
overwrite?: boolean;
}
/**
* Copies an object the Code API already stores for this user into the workspace. Additive to
* protocol v1: sent only to workspaces that advertise `import_file`. The Code API mints the
* read grant and checks ownership; LibreChat names only refs it already holds.
*/
export interface WorkspaceImportRequest {
protocolVersion: 1;
operation: 'import_file';
workspaceId: string;
workspaceInstanceId?: string;
/** Linked worktree (`.worktrees/<name>`) the path is relative to. */
worktree?: string;
path: string;
source: { storage_session_id: string; id: string };
bytes: number;
/** Lowercase hex digest of the object; an existing file with the same digest is left as is. */
sha256: string;
overwrite?: boolean;
}
export interface WorkspaceTextEdit {
oldText: string;
newText: string;
/** Requires the worker's `replace_all` edit feature. */
replaceAll?: boolean;
}
export interface WorkspaceEditRequest {
protocolVersion: 1;
operation: 'edit_file';
workspaceId: string;
workspaceInstanceId?: string;
path: string;
edits: WorkspaceTextEdit[];
expectedBaseSha256?: string;
/** Requires the worker's `tolerant_match` edit feature. */
matching?: WorkspaceEditMatching;
}
export interface WorkspacePreviewEditRequest {
protocolVersion: 1;
operation: 'preview_edit';
workspaceId: string;
workspaceInstanceId?: string;
path: string;
edits: WorkspaceTextEdit[];
/** Requires the worker's `tolerant_match` edit feature. */
matching?: WorkspaceEditMatching;
}
export type WorkspaceToolRequest =
| WorkspaceReadRequest
| WorkspaceSearchRequest
| WorkspaceListRequest
| WorkspaceWriteRequest
| WorkspacePreviewEditRequest
| WorkspaceEditRequest
| WorkspaceExecuteCommandRequest
| WorkspaceImportRequest;
export interface WorkspaceReadResult {
protocolVersion: 1;
operation: 'read_file';
workspaceId: string;
path: string;
content: string;
startLine: number;
endLine: number;
truncated: boolean;
nextStartLine?: number;
}
export interface WorkspaceSearchResult {
protocolVersion: 1;
operation: 'search_text';
workspaceId: string;
matches: Array<{ path: string; line: number; column: number; text: string }>;
truncated: boolean;
}
export interface WorkspaceListResult {
protocolVersion: 1;
operation: 'list_files';
workspaceId: string;
paths: string[];
truncated: boolean;
nextAfterPath?: string;
}
export interface WorkspaceExecuteCommandResult {
protocolVersion: 1;
operation: 'execute_command';
workspaceId: string;
exitCode: number | null;
signal?: string;
stdout: string;
stderr: string;
truncated: boolean;
timedOut: boolean;
/** Branch and head of the lane the command ran in. Absent means unknown, null means the lane
* has no branch (detached) or no commit yet. */
laneGit?: WorkspaceLaneGit;
}
export interface WorkspaceLaneGit {
branch: string | null;
head: string | null;
}
export interface WorkspaceWriteResult {
protocolVersion: 1;
operation: 'write_file';
workspaceId: string;
path: string;
created: boolean;
bytesWritten: number;
}
export interface WorkspaceImportResult {
protocolVersion: 1;
operation: 'import_file';
workspaceId: string;
path: string;
created: boolean;
/** The file already held these exact bytes, so nothing was written. */
unchanged?: boolean;
bytesWritten: number;
sha256: string;
}
export interface WorkspaceEditResult {
protocolVersion: 1;
operation: 'edit_file';
workspaceId: string;
path: string;
replacements: number;
bytesWritten: number;
matches?: WorkspaceEditMatch[];
}
export interface WorkspacePreviewEditResult {
protocolVersion: 1;
operation: 'preview_edit';
workspaceId: string;
path: string;
content: string;
hasUtf8Bom: boolean;
baseSha256: string;
replacements: number;
bytesWritten: number;
matches?: WorkspaceEditMatch[];
}
export type WorkspaceToolResult =
| WorkspaceReadResult
| WorkspaceSearchResult
| WorkspaceListResult
| WorkspaceWriteResult
| WorkspacePreviewEditResult
| WorkspaceEditResult
| WorkspaceExecuteCommandResult
| WorkspaceImportResult;
export class WorkspaceToolHttpError extends Error {
/**
* The worker's own explanation of a rejected edit (`EDIT_CONFLICT`), which current workers
* phrase for the model: which edits failed, why, and where. Absent for other failures.
*/
public readonly editConflict?: string;
/** The `code` of a complete JSON error body, such as `EDIT_CONFLICT` or `WORKSPACE_QUARANTINED`. */
public readonly upstreamCode?: string;
constructor(
public readonly reason: 'rejected' | 'invalid' | 'timeout' | 'failed' | 'insufficient_time',
public readonly upstreamStatus?: number,
public readonly upstreamBody?: string,
public readonly upstreamBodyTruncated = false,
) {
const parsed = upstreamBodyTruncated ? undefined : parseErrorBody(upstreamBody);
let message = `Workspace tool request ${reason}`;
const admissionRejection =
reason === 'rejected'
? getWorkspaceAdmissionRejection(upstreamStatus, upstreamBody, upstreamBodyTruncated)
: undefined;
if (admissionRejection === 'queue_timeout') {
message =
'Workspace capacity was unavailable before the queue deadline. The operation was not started. Wait for active work to finish or select an independent workspace on a machine with available capacity.';
}
if (admissionRejection === 'rate_limited') {
message =
'The Code API request rate limit was reached. The operation was not started. Wait a few seconds before retrying, or make fewer concurrent workspace calls.';
}
if (reason === 'insufficient_time') {
message =
'Workspace execution cannot fit within the remaining HTTP budget. The operation was not started.';
}
super(
message +
(upstreamStatus == null ? '' : ` (upstreamStatus: ${upstreamStatus})`) +
(parsed?.code == null ? '' : ` (upstreamCode: ${parsed.code})`),
);
this.name = 'WorkspaceToolHttpError';
this.upstreamCode = parsed?.code;
this.editConflict =
reason === 'rejected' && upstreamStatus === 409 && parsed?.code === 'EDIT_CONFLICT'
? parsed.error
: undefined;
}
}
const DURABLE_ERROR_STATUS: Readonly<Record<string, number>> = {
WORKER_OFFLINE: 503,
WORKER_BUSY: 503,
WORKSPACE_QUEUE_TIMEOUT: 503,
WORKER_QUEUE_FULL: 429,
WORKER_UNAUTHORIZED: 403,
ASSIGNMENT_INVALID: 400,
RESULT_INVALID: 502,
ASSIGNMENT_EXPIRED: 504,
WORKER_FENCED: 409,
WORKER_MISMATCH: 409,
WORKER_QUARANTINED: 409,
WORKSPACE_QUARANTINED: 409,
ASSIGNMENT_FENCED: 409,
ASSIGNMENT_NOT_FOUND: 409,
REQUEST_CONFLICT: 409,
FILE_EXISTS: 409,
EDIT_CONFLICT: 409,
SEARCH_TIMEOUT: 504,
LIST_TIMEOUT: 504,
COMMAND_TIMEOUT: 504,
SEARCH_UNAVAILABLE: 503,
LIST_UNAVAILABLE: 503,
COMMAND_UNAVAILABLE: 503,
WRITE_DISABLED: 403,
COMMAND_DISABLED: 403,
WRITE_LIMIT_EXCEEDED: 413,
WRITE_UNAVAILABLE: 503,
INVALID_PATH: 422,
NOT_FOUND: 422,
INVALID_REQUEST: 422,
READ_LIMIT_EXCEEDED: 422,
REGISTRATION_INVALID: 422,
EXECUTION_ABORTED: 422,
WORKSPACE_TOOL_REJECTED: 422,
};
function durableWorkspaceFailure(code?: string): WorkspaceToolHttpError {
const approved =
code !== undefined && Object.prototype.hasOwnProperty.call(DURABLE_ERROR_STATUS, code)
? code
: 'WORKSPACE_TOOL_REJECTED';
return new WorkspaceToolHttpError(
'rejected',
DURABLE_ERROR_STATUS[approved] ?? 422,
JSON.stringify({ code: approved }),
);
}
const ERROR_CODE = /^[A-Z][A-Z0-9_]{0,63}$/;
function parseErrorBody(body?: string): { code?: string; error?: string } | undefined {
if (!body) {
return undefined;
}
try {
const parsed: { code?: unknown; error?: unknown } | null = JSON.parse(body);
return {
...(typeof parsed?.code === 'string' && ERROR_CODE.test(parsed.code)
? { code: parsed.code }
: {}),
...(typeof parsed?.error === 'string' ? { error: parsed.error } : {}),
};
} catch {
return undefined;
}
}
type WorkspaceAdmissionRejection = 'queue_timeout' | 'rate_limited';
/**
* Rejections the Code API issues before an operation is assigned, so retrying cannot repeat a
* mutation: a queue deadline that expired before admission, or its rate limiter, which runs as
* middleware ahead of the workspace router. Anything else, including an unparsable body under
* either status, keeps an unknown outcome and is never retried.
*/
function getWorkspaceAdmissionRejection(
status?: number,
body?: string,
truncated = false,
): WorkspaceAdmissionRejection | undefined {
if (
(status !== 503 && status !== 429) ||
!body ||
truncated ||
body.length > MAX_ERROR_BODY_BYTES
) {
return undefined;
}
try {
const parsed: { code?: string; error?: string } | null = JSON.parse(body);
if (status === 503 && parsed?.code === 'WORKSPACE_QUEUE_TIMEOUT') {
return 'queue_timeout';
}
if (status === 429 && parsed?.error === 'rate_limited') {
return 'rate_limited';
}
return undefined;
} catch {
return undefined;
}
}
function waitForWorkspaceAdmission(delayMs: number, signal?: AbortSignal): Promise<void> {
signal?.throwIfAborted();
return new Promise((resolve, reject) => {
const cleanup = () => signal?.removeEventListener('abort', abort);
const finish = () => {
cleanup();
resolve();
};
const abort = () => {
clearTimeout(timer);
cleanup();
reject(signal?.reason);
};
const timer = setTimeout(finish, delayMs);
signal?.addEventListener('abort', abort, { once: true });
if (signal?.aborted === true) abort();
});
}
const DEFAULT_ADMISSION_POLICY = codeEnvironmentAdmissionSchema.parse({});
export interface WorkspaceAdmissionOptions {
maxRunTimeoutMs?: number;
admission?: CodeEnvironmentUserConfigSchema['admission'];
}
/** Keep omitted policy absent so existing adapters and total-budget semantics remain unchanged. */
export function resolveAttachedWorkspaceAdmissionOptions(
config?: CodeEnvironmentUserConfigSchema,
): WorkspaceAdmissionOptions {
return {
...(config?.limits?.maxRunTimeoutMs == null
? {}
: { maxRunTimeoutMs: config.limits.maxRunTimeoutMs }),
...(config?.admission == null ? {} : { admission: config.admission }),
};
}
function workspaceAdmissionRetryDelay(
value: string | null,
body: string | undefined,
attempt: number,
policy: NonNullable<WorkspaceAdmissionOptions['admission']>,
): number {
let hintMs: number | undefined;
if (value != null && /^\d+$/.test(value)) {
hintMs = Number(value) * 1_000;
} else if (value != null) {
const date = Date.parse(value);
if (Number.isFinite(date)) hintMs = Math.max(0, date - Date.now());
}
if (hintMs != null && !Number.isFinite(hintMs)) hintMs = undefined;
if (hintMs == null && body) {
try {
const parsed: { retry_after_seconds?: number } | null = JSON.parse(body);
const seconds = parsed?.retry_after_seconds;
if (typeof seconds === 'number' && Number.isFinite(seconds) && seconds >= 0) {
hintMs = seconds * 1_000;
}
} catch {
// The rejection whitelist already requires complete JSON.
}
}
const delayMs =
hintMs == null
? Math.min(policy.maxDelayMs, policy.initialDelayMs * policy.multiplier ** (attempt - 1))
: Math.max(100, hintMs);
const jitteredMs = Math.ceil(delayMs + delayMs * policy.jitterRatio * Math.random());
return hintMs == null ? Math.min(policy.maxDelayMs, jitteredMs) : jitteredMs;
}
/** Keep a received HTTP status even if reading its diagnostic body fails or stalls. */
async function readErrorBody(
response: Response,
signal: AbortSignal,
): Promise<{
body: string;
truncated: boolean;
}> {
if (!response.body) return { body: '', truncated: false };
const reader = response.body.getReader();
const decoder = new TextDecoder();
let body = '';
let bytes = 0;
let complete = false;
let interrupted = false;
const cancel = () => {
interrupted = true;
void reader.cancel().catch(() => undefined);
};
const timer = setTimeout(cancel, ERROR_BODY_TIMEOUT_MS);
signal.addEventListener('abort', cancel, { once: true });
try {
if (signal.aborted) return { body, truncated: true };
while (bytes <= MAX_ERROR_BODY_BYTES) {
const { done, value } = await reader.read();
if (done) {
complete = !interrupted;
body += decoder.decode();
break;
}
const remaining = MAX_ERROR_BODY_BYTES - bytes;
body += decoder.decode(value.subarray(0, remaining), { stream: true });
bytes += value.byteLength;
}
} catch {
complete = false;
} finally {
clearTimeout(timer);
signal.removeEventListener('abort', cancel);
cancel();
reader.releaseLock();
}
return { body, truncated: !complete || signal.aborted };
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value != null;
}
function isSafePath(value: unknown): value is string {
return (
typeof value === 'string' &&
value.length > 0 &&
value.length <= MAX_PATH_LENGTH &&
!value.includes('\0') &&
!value.includes('\r') &&
!value.includes('\n') &&
!value.includes('\\') &&
!value.startsWith('/') &&
!/^[A-Za-z]:/.test(value) &&
value.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..')
);
}
function isPositiveInteger(value: unknown, maximum: number): boolean {
return Number.isSafeInteger(value) && Number(value) >= 1 && Number(value) <= maximum;
}
function isUtf8StringWithinBytes(value: unknown, maximum: number): value is string {
return (
typeof value === 'string' &&
Buffer.from(value).toString('utf8') === value &&
new TextEncoder().encode(value).byteLength <= maximum
);
}
function areValidWorkspaceEdits(edits: unknown): edits is WorkspaceTextEdit[] {
if (!Array.isArray(edits)) return false;
if (edits.length < 1 || edits.length > WORKSPACE_EDIT_MAX_COUNT) return false;
let bytes = 0;
for (const edit of edits) {
if (
!isRecord(edit) ||
!hasOnlyKeys(edit, TEXT_EDIT_KEYS) ||
!isUtf8StringWithinBytes(edit.oldText, WORKSPACE_WRITE_MAX_BYTES) ||
edit.oldText.length === 0 ||
!isUtf8StringWithinBytes(edit.newText, WORKSPACE_WRITE_MAX_BYTES) ||
(edit.replaceAll !== undefined && typeof edit.replaceAll !== 'boolean')
) {
return false;
}
bytes +=
new TextEncoder().encode(edit.oldText).byteLength +
new TextEncoder().encode(edit.newText).byteLength;
if (bytes > WORKSPACE_WRITE_MAX_BYTES) return false;
}
return true;
}
function isValidEditMatching(matching: unknown): boolean {
return matching === undefined || matching === 'exact' || matching === 'tolerant';
}
/** Whether an edit request opted into per-edit match reporting (and so must receive it). */
function reportsEditMatches(request: WorkspaceEditRequest | WorkspacePreviewEditRequest): boolean {
return (
request.matching !== undefined || request.edits.some((edit) => edit.replaceAll !== undefined)
);
}
function areValidEditMatches(
request: WorkspaceEditRequest | WorkspacePreviewEditRequest,
matches: unknown,
): boolean {
if (!reportsEditMatches(request)) {
return matches === undefined;
}
return (
Array.isArray(matches) &&
matches.length === request.edits.length &&
matches.every(
(match, index) =>
isRecord(match) &&
hasOnlyKeys(match, EDIT_MATCH_KEYS) &&
typeof match.strategy === 'string' &&
WORKSPACE_EDIT_MATCH_STRATEGIES.has(match.strategy) &&
(request.matching === 'tolerant' || match.strategy === 'exact') &&
isPositiveInteger(match.occurrences, Number.MAX_SAFE_INTEGER) &&
(request.edits[index]?.replaceAll === true || match.occurrences === 1),
)
);
}
function hasControlCharacter(value: string): boolean {
for (let index = 0; index < value.length; index++) {
const code = value.charCodeAt(index);
if (code <= 0x1f || code === 0x7f) return true;
}
return false;
}
function isLaneGit(value: unknown): value is WorkspaceLaneGit {
if (!isRecord(value) || !hasOnlyKeys(value, LANE_GIT_KEYS)) return false;
const { branch, head } = value;
return (
(branch === null ||
(typeof branch === 'string' &&
branch.length >= 1 &&
branch.length <= MAX_LANE_BRANCH_LENGTH &&
!hasControlCharacter(branch))) &&
(head === null || (typeof head === 'string' && /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(head)))
);
}
function hasOnlyKeys(value: Record<string, unknown>, allowed: ReadonlySet<string>): boolean {
return Object.keys(value).every((key) => allowed.has(key));
}
function normalizeRelativePath(value: string): string {
return value
.split('/')
.filter((segment) => segment !== '' && segment !== '.')
.join('/');
}
function isWithinRequestedPath(candidate: string, requestedPath: string | undefined): boolean {
const prefix = requestedPath == null ? '' : normalizeRelativePath(requestedPath);
if (prefix === '') return true;
const normalizedCandidate = normalizeRelativePath(candidate);
return normalizedCandidate === prefix || normalizedCandidate.startsWith(`${prefix}/`);
}
function comparePortablePaths(left: string, right: string): number {
const encoder = new TextEncoder();
const leftBytes = encoder.encode(left);
const rightBytes = encoder.encode(right);
const sharedLength = Math.min(leftBytes.length, rightBytes.length);
for (let index = 0; index < sharedLength; index += 1) {
const difference = leftBytes[index] - rightBytes[index];
if (difference !== 0) return difference;
}
return leftBytes.length - rightBytes.length;
}
async function readBoundedJson(
response: Response,
signal?: AbortSignal,
recoverTransport = false,
): Promise<unknown> {
const declaredLength = Number(response.headers.get('content-length'));
if (Number.isFinite(declaredLength) && declaredLength > MAX_RESPONSE_BYTES) {
await response.body?.cancel().catch(() => undefined);
throw new WorkspaceToolHttpError('invalid');
}
if (!response.body) {
throw new WorkspaceToolHttpError('invalid');
}
const reader = response.body.getReader();
const decoder = new TextDecoder();
let byteLength = 0;
let body = '';
try {
while (true) {
const { done, value } = await reader.read().catch((error: unknown) => {
if (recoverTransport) {
if (signal?.aborted === true) throw signal.reason ?? error;
throw new WorkspaceResponseTransportError();
}
throw error;
});
if (done) break;
byteLength += value.byteLength;
if (byteLength > MAX_RESPONSE_BYTES) {
await reader.cancel();
throw new WorkspaceToolHttpError('invalid');
}
body += decoder.decode(value, { stream: true });
}
body += decoder.decode();
return JSON.parse(body) as unknown;
} catch (error) {
if (error instanceof WorkspaceToolHttpError || error instanceof WorkspaceResponseTransportError)
throw error;
if (
signal?.aborted === true &&
(error === signal.reason ||
(isRecord(error) && (error.name === 'AbortError' || error.name === 'TimeoutError')))
) {
throw signal.reason ?? error;
}
if (isRecord(error) && (error.name === 'AbortError' || error.name === 'TimeoutError')) {
throw error;
}
throw new WorkspaceToolHttpError('invalid');
} finally {
reader.releaseLock();
}
}
function isValidRequest(request: WorkspaceToolRequest): boolean {
if (
request.protocolVersion !== 1 ||
!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(request.workspaceId) ||
(request.workspaceInstanceId !== undefined &&
!/^[a-f0-9]{64}$/.test(request.workspaceInstanceId))
) {
return false;
}
if (request.operation === 'read_file') {
if (request.instructionSha256 !== undefined) {
return (
/^[a-f0-9]{64}$/.test(request.instructionSha256) &&
(request.path === 'AGENTS.md' || request.path === 'CLAUDE.md') &&
request.startLine === undefined &&
request.maxLines === undefined
);
}
return (
isSafePath(request.path) &&
(request.startLine == null ||
isPositiveInteger(request.startLine, Number.MAX_SAFE_INTEGER)) &&
(request.maxLines == null || isPositiveInteger(request.maxLines, MAX_READ_LINES))
);
}
if (request.operation === 'list_files') {
return (
(request.path == null || isSafePath(request.path)) &&
(request.afterPath == null ||
(isSafePath(request.afterPath) &&
isWithinRequestedPath(request.afterPath, request.path))) &&
(request.maxResults == null || isPositiveInteger(request.maxResults, MAX_LIST_RESULTS))
);
}
if (request.operation === 'execute_command') {
return (
isUtf8StringWithinBytes(request.command, MAX_COMMAND_BYTES) &&
request.command.trim().length > 0 &&
!request.command.includes('\0') &&
(request.cwd == null || isSafePath(request.cwd)) &&
(request.timeoutMs == null ||
isPositiveInteger(request.timeoutMs, WORKSPACE_COMMAND_MAX_TIMEOUT_MS)) &&
(request.maxOutputBytes == null ||
isPositiveInteger(request.maxOutputBytes, MAX_COMMAND_OUTPUT_BYTES))
);
}
if (request.operation === 'write_file') {
return (
isSafePath(request.path) &&
isUtf8StringWithinBytes(request.content, WORKSPACE_WRITE_MAX_BYTES) &&
(request.overwrite === undefined || typeof request.overwrite === 'boolean')
);
}
if (request.operation === 'import_file') {
return (
isSafePath(request.path) &&
(request.worktree === undefined ||
(LINKED_WORKTREE_NAME_PATTERN.test(request.worktree) &&
!request.worktree.endsWith('.lock'))) &&
isRecord(request.source) &&
Object.keys(request.source).length === 2 &&
typeof request.source.storage_session_id === 'string' &&
STORAGE_ID_PATTERN.test(request.source.storage_session_id) &&
typeof request.source.id === 'string' &&
STORAGE_ID_PATTERN.test(request.source.id) &&
Number.isSafeInteger(request.bytes) &&
request.bytes >= 0 &&
SHA256_PATTERN.test(request.sha256) &&
(request.overwrite === undefined || typeof request.overwrite === 'boolean')
);
}
if (request.operation === 'preview_edit') {
return (
isSafePath(request.path) &&
areValidWorkspaceEdits(request.edits) &&
isValidEditMatching(request.matching)
);
}
if (request.operation === 'edit_file') {
return (
isSafePath(request.path) &&
areValidWorkspaceEdits(request.edits) &&
isValidEditMatching(request.matching) &&
(request.expectedBaseSha256 == null || /^[a-f0-9]{64}$/.test(request.expectedBaseSha256))
);
}
if (request.operation !== 'search_text') {
return false;
}
return (
typeof request.query === 'string' &&
request.query.length > 0 &&
request.query.length <= MAX_QUERY_LENGTH &&
!request.query.includes('\0') &&
(request.path == null || isSafePath(request.path)) &&
(request.maxResults == null || isPositiveInteger(request.maxResults, MAX_SEARCH_RESULTS))
);
}
function isValidResult(
request: WorkspaceToolRequest,
value: unknown,
): value is WorkspaceToolResult {
if (
!isRecord(value) ||
value.protocolVersion !== 1 ||
value.operation !== request.operation ||
value.workspaceId !== request.workspaceId
) {
return false;
}
if (request.operation === 'read_file') {
if (request.instructionSha256 !== undefined) {
return (
hasOnlyKeys(value, READ_RESULT_KEYS) &&
value.path === request.path &&
typeof value.content === 'string' &&
Buffer.byteLength(value.content) <= 32768 &&
value.startLine === 1 &&
value.endLine === value.content.split('\n').length &&
typeof value.truncated === 'boolean' &&
value.nextStartLine === undefined
);
}
const startLine = request.startLine ?? 1;
const maxLines = request.maxLines ?? 200;
const content = typeof value.content === 'string' ? value.content : null;
const reportedLineCount =
Number.isSafeInteger(value.endLine) && Number(value.endLine) >= startLine - 1
? Number(value.endLine) - startLine + 1
: -1;
let actualLineCount = -1;
if (content != null) {
actualLineCount = content.length === 0 ? reportedLineCount : content.split('\n').length;
}
return (
hasOnlyKeys(value, READ_RESULT_KEYS) &&
value.path === request.path &&
isSafePath(value.path) &&
content != null &&
typeof value.truncated === 'boolean' &&
new TextEncoder().encode(content).byteLength <= MAX_READ_BYTES &&
value.startLine === startLine &&
Number.isSafeInteger(value.endLine) &&
Number(value.endLine) >= startLine - 1 &&
Number(value.endLine) < startLine + maxLines &&
reportedLineCount >= 0 &&
reportedLineCount <= maxLines &&
(content.length !== 0 || reportedLineCount <= 1) &&
actualLineCount === reportedLineCount &&
(value.truncated === true
? Number.isSafeInteger(value.nextStartLine) &&
Number(value.nextStartLine) === Number(value.endLine) + 1
: value.nextStartLine == null)
);
}
if (request.operation === 'list_files') {
const maxResults = request.maxResults ?? 100;
if (
!hasOnlyKeys(value, LIST_RESULT_KEYS) ||
typeof value.truncated !== 'boolean' ||
!Array.isArray(value.paths) ||
value.paths.length > maxResults
) {
return false;
}
let previousPath = request.afterPath;
for (const path of value.paths) {
if (
!isSafePath(path) ||
!isWithinRequestedPath(path, request.path) ||
(previousPath != null && comparePortablePaths(path, previousPath) <= 0)
) {
return false;
}
previousPath = path;
}
return value.truncated === true
? value.paths.length > 0 && value.nextAfterPath === value.paths[value.paths.length - 1]
: value.nextAfterPath == null;
}
if (request.operation === 'execute_command') {
const stdout = typeof value.stdout === 'string' ? value.stdout : null;
const stderr = typeof value.stderr === 'string' ? value.stderr : null;
const outputLimit = request.maxOutputBytes ?? DEFAULT_COMMAND_OUTPUT_BYTES;
return (
hasOnlyKeys(value, COMMAND_RESULT_KEYS) &&
(!('laneGit' in value) || isLaneGit(value.laneGit)) &&
typeof value.truncated === 'boolean' &&
stdout != null &&
stderr != null &&
Buffer.from(stdout).toString('utf8') === stdout &&
Buffer.from(stderr).toString('utf8') === stderr &&
new TextEncoder().encode(stdout).byteLength + new TextEncoder().encode(stderr).byteLength <=
outputLimit &&
(value.exitCode === null ||
(Number.isSafeInteger(value.exitCode) &&
Number(value.exitCode) >= 0 &&
Number(value.exitCode) <= 255)) &&
(value.signal == null ||
(typeof value.signal === 'string' &&
value.signal.length <= MAX_COMMAND_SIGNAL_LENGTH &&
/^SIG[A-Z0-9]+$/.test(value.signal))) &&
typeof value.timedOut === 'boolean' &&
(value.exitCode === null
? value.timedOut === true || value.signal != null
: value.timedOut === false && value.signal == null)
);
}
if (request.operation === 'write_file') {
return (
hasOnlyKeys(value, WRITE_RESULT_KEYS) &&
value.path === request.path &&
typeof value.created === 'boolean' &&
(request.overwrite !== false || value.created === true) &&
Number.isSafeInteger(value.bytesWritten) &&
Number(value.bytesWritten) === new TextEncoder().encode(request.content).byteLength
);
}
if (request.operation === 'import_file') {
return (
hasOnlyKeys(value, IMPORT_RESULT_KEYS) &&
value.path === request.path &&
typeof value.created === 'boolean' &&
(value.unchanged === undefined || typeof value.unchanged === 'boolean') &&
!(value.created === true && value.unchanged === true) &&
value.sha256 === request.sha256 &&
Number.isSafeInteger(value.bytesWritten) &&
(Number(value.bytesWritten) === request.bytes ||
(value.unchanged === true && Number(value.bytesWritten) === 0))
);
}
if (request.operation === 'edit_file') {
return (
hasOnlyKeys(value, EDIT_RESULT_KEYS) &&
value.path === request.path &&
value.replacements === request.edits.length &&
Number.isSafeInteger(value.bytesWritten) &&
Number(value.bytesWritten) >= 0 &&
Number(value.bytesWritten) <= WORKSPACE_WRITE_MAX_BYTES &&
areValidEditMatches(request, value.matches)
);
}
if (request.operation === 'preview_edit') {
const content = typeof value.content === 'string' ? value.content : null;
return (
hasOnlyKeys(value, PREVIEW_EDIT_RESULT_KEYS) &&
value.path === request.path &&
content != null &&
Buffer.from(content).toString('utf8') === content &&
typeof value.hasUtf8Bom === 'boolean' &&
/^[a-f0-9]{64}$/.test(typeof value.baseSha256 === 'string' ? value.baseSha256 : '') &&
value.replacements === request.edits.length &&
Number.isSafeInteger(value.bytesWritten) &&
Number(value.bytesWritten) ===
new TextEncoder().encode(content).byteLength + (value.hasUtf8Bom ? 3 : 0) &&
Number(value.bytesWritten) <= WORKSPACE_WRITE_MAX_BYTES &&
areValidEditMatches(request, value.matches)
);
}
const maxResults = request.maxResults ?? 50;
return (
hasOnlyKeys(value, SEARCH_RESULT_KEYS) &&
typeof value.truncated === 'boolean' &&
Array.isArray(value.matches) &&
value.matches.length <= maxResults &&
value.matches.every(
(match) =>
isRecord(match) &&
hasOnlyKeys(match, SEARCH_MATCH_KEYS) &&
isSafePath(match.path) &&
isWithinRequestedPath(match.path, request.path) &&
isPositiveInteger(match.line, Number.MAX_SAFE_INTEGER) &&
isPositiveInteger(match.column, Number.MAX_SAFE_INTEGER) &&
typeof match.text === 'string' &&
match.text.length <= MAX_SEARCH_TEXT_LENGTH,
)
);
}
function getWorkspaceExecutionBudgetMs(request: WorkspaceToolRequest): number {
return request.operation === 'execute_command'
? (request.timeoutMs ?? WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS) +
WORKSPACE_COMMAND_SETTLEMENT_GRACE_MS
: WORKSPACE_TOOL_TIMEOUT_MS;
}
function getWorkspaceToolTimeoutMs(request: WorkspaceToolRequest): number {
return (
WORKSPACE_QUEUE_TIMEOUT_MS +
getWorkspaceExecutionBudgetMs(request) +
WORKSPACE_COMMAND_TRANSPORT_GRACE_MS
);
}
/**
* Credentials for one admission attempt. A supplier is minted per attempt, so a
* call that stays queued past the Code API token TTL presents a fresh token
* instead of failing permanently with 401 while capacity is still pending.
*/
export type WorkspaceToolAuthHeaders =
| Record<string, string>
| (() => Promise<Record<string, string>> | Record<string, string>);
function getWorkspaceAuthHeaders(
supplier: () => Promise<Record<string, string>> | Record<string, string>,
signal: AbortSignal,
): Promise<Record<string, string>> {
signal.throwIfAborted();
return new Promise((resolve, reject) => {
const abort = () => reject(signal.reason);
signal.addEventListener('abort', abort, { once: true });
if (signal.aborted) {
abort();
return;
}
try {
void Promise.resolve(supplier())
.then(resolve, reject)
.finally(() => {
signal.removeEventListener('abort', abort);
});
} catch (error) {
signal.removeEventListener('abort', abort);
reject(error);
}
});
}
/** Linked worktrees live at `.worktrees/<name>` beneath a registered checkout. */
const LINKED_WORKTREE_DIRECTORY = '.worktrees/';
/** Mirrors Code API's single-segment worktree name rule. */
const LINKED_WORKTREE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
export type LinkedWorktreeRequest = WorkspaceToolRequest & { worktree: string };
interface LinkedWorktreePath {
worktree: string;
/** Path relative to the worktree root; empty for the worktree root itself. */
rest: string;
}
function splitLinkedWorktreePath(path: string | undefined): LinkedWorktreePath | undefined {
if (path == null || !path.startsWith(LINKED_WORKTREE_DIRECTORY)) return undefined;
const remainder = path.slice(LINKED_WORKTREE_DIRECTORY.length);
const slash = remainder.indexOf('/');
const worktree = slash === -1 ? remainder : remainder.slice(0, slash);
if (!LINKED_WORKTREE_NAME_PATTERN.test(worktree) || worktree.endsWith('.lock')) {
return undefined;
}
return { worktree, rest: slash === -1 ? '' : remainder.slice(slash + 1) };
}
function prefixed(worktree: string, path: string): string {
return `${LINKED_WORKTREE_DIRECTORY}${worktree}/${path}`;
}
/**
* Route a request that targets `.worktrees/<name>/…` into that worktree's own
* scheduling lane, so work in sibling worktrees runs concurrently. Only
* structural targets are routed: a file path, a search or listing scope, or a
* command `cwd`. Anything else, including a command that `cd`s into a worktree
* from the root, stays root-scoped because its reach cannot be bounded.
*/
export function toLinkedWorktreeRequest(
request: WorkspaceToolRequest,
): { request: LinkedWorktreeRequest; worktree: string } | undefined {
if (request.workspaceInstanceId != null) return undefined;
switch (request.operation) {
case 'read_file':
case 'write_file':
case 'edit_file':
case 'preview_edit': {
if (request.operation === 'read_file' && request.instructionSha256 != null) return undefined;
const target = splitLinkedWorktreePath(request.path);
if (target == null || target.rest === '') return undefined;
return {
worktree: target.worktree,
request: { ...request, path: target.rest, worktree: target.worktree },
};
}
case 'search_text': {
const target = splitLinkedWorktreePath(request.path);
if (target == null) return undefined;
const { path: _path, ...rest } = request;
return {
worktree: target.worktree,
request: {
...rest,
...(target.rest === '' ? {} : { path: target.rest }),
worktree: target.worktree,
},
};
}
case 'list_files': {
const target = splitLinkedWorktreePath(request.path);
if (target == null) return undefined;
const after =
request.afterPath == null ? undefined : splitLinkedWorktreePath(request.afterPath);
if (
request.afterPath != null &&
(after == null || after.worktree !== target.worktree || after.rest === '')
) {
return undefined;
}
const { path: _path, afterPath: _afterPath, ...rest } = request;
return {
worktree: target.worktree,
request: {
...rest,
...(target.rest === '' ? {} : { path: target.rest }),
...(after == null ? {} : { afterPath: after.rest }),
worktree: target.worktree,
},
};
}
case 'import_file':
return undefined;
case 'execute_command': {
if (request.environmentAction != null) return undefined;
const target = splitLinkedWorktreePath(request.cwd);
if (target == null) return undefined;
const { cwd: _cwd, ...rest } = request;
return {
worktree: target.worktree,
request: {
...rest,
...(target.rest === '' ? {} : { cwd: target.rest }),
worktree: target.worktree,
},
};
}
}
}
/** Restore the `.worktrees/<name>/` prefix on every path a lane result reports. */
export function fromLinkedWorktreeResult(
result: WorkspaceToolResult,
worktree: string,
): WorkspaceToolResult {
switch (result.operation) {
case 'read_file':
case 'write_file':
case 'edit_file':
case 'preview_edit':
case 'import_file':
return { ...result, path: prefixed(worktree, result.path) };
case 'search_text':
return {
...result,
matches: result.matches.map((match) => ({
...match,
path: prefixed(worktree, match.path),
})),
};
case 'list_files':
return {
...result,
paths: result.paths.map((path) => prefixed(worktree, path)),
...(result.nextAfterPath == null
? {}
: { nextAfterPath: prefixed(worktree, result.nextAfterPath) }),
};
case 'execute_command':
return result;
}
}
/** Resolves a bounded read window without changing the protocol-v1 byte or line ceilings. */
export function resolveAttachedWorkspaceReadFileLines(
configSchema?: CodeEnvironmentUserConfigSchema,
): number {
const configured = configSchema?.limits?.defaultReadFileLines;
return configured != null &&
Number.isSafeInteger(configured) &&
configured >= 1 &&
configured <= MAX_READ_LINES
? configured
: CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES;
}
export async function executeWorkspaceTool({
baseURL,
authHeaders,
request,
signal,
fetchImpl = fetch,
maxQueueWaitMs = WORKSPACE_QUEUE_MAX_WAIT_MS,
codeApiMaxRetryWaitMs = CODE_API_RATE_LIMIT_WAIT_DEFAULT_MS,
maxRequestTimeoutMs,
maxRunTimeoutMs,
admission,
deadlineAtMs,
linkedWorktrees = false,
requestId,
resumeRequestId,
synchronousCommandFallback,
}: {
baseURL: string;
/** Fresh idempotency key. Use resumeRequestId for a previously accepted invocation. */
requestId?: string;
resumeRequestId?: string;
/** Host-selected fallback for omitted command timeouts, applied only on unsupported discovery. */
synchronousCommandFallback?: {
timeoutMs: number;
minAdmissionMs?: number;
onSelected: (timeoutMs: number) => void;
};
authHeaders: WorkspaceToolAuthHeaders;
request: WorkspaceToolRequest;
signal?: AbortSignal;
fetchImpl?: CodeBridgeFetch;
maxQueueWaitMs?: number;
/** Maximum time waiting for Code API rate-limit admission, independent of queue retries. */
codeApiMaxRetryWaitMs?: number;
/** Per-attempt transport ceiling; also the total budget unless maxRunTimeoutMs is set. */
maxRequestTimeoutMs?: number;
/** Optional earlier caller deadline; a signal alone has no remaining-time value. */
deadlineAtMs?: number;
/** The worker runs each `.worktrees/<name>` in its own lane; route matching requests there. */
linkedWorktrees?: boolean;
} & WorkspaceAdmissionOptions): Promise<WorkspaceToolResult> {
const parsedPolicy = codeEnvironmentAdmissionSchema.safeParse(
admission ?? DEFAULT_ADMISSION_POLICY,
);
if (
!parsedPolicy.success ||
(resumeRequestId !== undefined &&
(requestId !== undefined || parsedPolicy.data.durableRequests !== true)) ||
!isValidRequest(request) ||
(synchronousCommandFallback !== undefined &&
(request.operation !== 'execute_command' ||
!isPositiveInteger(
synchronousCommandFallback.timeoutMs,
request.timeoutMs ?? WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS,
) ||
(synchronousCommandFallback.minAdmissionMs !== undefined &&
!isPositiveInteger(
synchronousCommandFallback.minAdmissionMs,
CODE_ENVIRONMENT_ADMISSION_MAX_MS,
)))) ||
!Number.isSafeInteger(maxQueueWaitMs) ||
maxQueueWaitMs < 0 ||
maxQueueWaitMs > WORKSPACE_QUEUE_MAX_WAIT_MS ||
!Number.isSafeInteger(codeApiMaxRetryWaitMs) ||
codeApiMaxRetryWaitMs < 0 ||
codeApiMaxRetryWaitMs > 300_000 ||
(maxRequestTimeoutMs !== undefined &&
(!Number.isSafeInteger(maxRequestTimeoutMs) ||
maxRequestTimeoutMs < 1 ||
maxRequestTimeoutMs > CODE_ENVIRONMENT_REQUEST_TIMEOUT_HARD_MAX_MS)) ||
(maxRunTimeoutMs !== undefined &&
(!Number.isSafeInteger(maxRunTimeoutMs) ||
maxRunTimeoutMs < 1 ||
maxRunTimeoutMs > CODE_ENVIRONMENT_REQUEST_TIMEOUT_HARD_MAX_MS)) ||
(deadlineAtMs !== undefined && (!Number.isSafeInteger(deadlineAtMs) || deadlineAtMs < 1))
) {
throw new WorkspaceToolHttpError('invalid');
}
const policy = parsedPolicy.data;
const lane = linkedWorktrees === true ? toLinkedWorktreeRequest(request) : undefined;
let wireRequest: WorkspaceToolRequest = lane?.request ?? request;
let executionBudgetMs = getWorkspaceExecutionBudgetMs(wireRequest);
let completionReserveMs = executionBudgetMs + WORKSPACE_COMMAND_TRANSPORT_GRACE_MS;
const perAttemptTimeoutMs = maxRequestTimeoutMs ?? getWorkspaceToolTimeoutMs(wireRequest);
const startedAt = Date.now();
const runTimeoutMs = maxRunTimeoutMs ?? maxRequestTimeoutMs;
const callerDeadlineAt = Math.min(
deadlineAtMs ?? Infinity,
runTimeoutMs == null ? Infinity : startedAt + runTimeoutMs,
);
const queueDeadlineAt = startedAt + maxQueueWaitMs;
let callerRetryDeadlineAt = callerDeadlineAt - completionReserveMs;
let body = JSON.stringify(wireRequest);
let fallback: typeof synchronousCommandFallback;
let lastAdmissionRejection: WorkspaceToolHttpError | undefined;
let lastRetryDeadlineAt = Infinity;
let rateLimitWaitedMs = 0;
let retryWaitMs = 0;
let attempts = 0;
let queueRejections = 0;
let rateLimitRejections = 0;
let outcome = 'failed';
let transport = policy.durableRequests === true ? 'durable' : 'synchronous';
let httpRequests = 0;
let durableReads = 0;
const span = trace.getTracer('librechat.workspace').startSpan('workspace.tool', {
attributes: {
'workspace.operation': wireRequest.operation,
'workspace.id': wireRequest.workspaceId,
...(lane == null ? {} : { 'workspace.lane': lane.worktree }),
'workspace.execution_budget_ms': executionBudgetMs,
'workspace.transport_budget_ms': perAttemptTimeoutMs,
},
});
try {
if (policy.durableRequests === true) {
const durableDeadlineAt = Math.min(
deadlineAtMs ?? Infinity,
maxRunTimeoutMs == null ? Infinity : startedAt + maxRunTimeoutMs,
startedAt +
Math.max(maxQueueWaitMs, policy.queueWaitMs ?? WORKSPACE_QUEUE_TIMEOUT_MS) +
completionReserveMs,
);
if (resumeRequestId === undefined && durableDeadlineAt - Date.now() <= completionReserveMs) {
throw new WorkspaceToolHttpError('insufficient_time');
}
const durable = await executeDurableWorkspaceRequest({
baseURL,
request: wireRequest,
requestId,
resumeRequestId,
fetchImpl,
signal,
authHeaders: async (requestSignal) =>
typeof authHeaders === 'function'
? await getWorkspaceAuthHeaders(authHeaders, requestSignal)
: authHeaders,
deadlineAtMs: durableDeadlineAt,
completionReserveMs,
transportTimeoutMs: Math.min(perAttemptTimeoutMs, policy.transportTimeoutMs ?? 10000),
queueWaitMs: Math.max(
1,
policy.queueWaitMs ?? Math.max(maxQueueWaitMs, WORKSPACE_QUEUE_TIMEOUT_MS),
),
pollIntervalMs: policy.pollIntervalMs ?? 500,
rateLimitWaitMs: codeApiMaxRetryWaitMs,
readJson: (response, requestSignal) => readBoundedJson(response, requestSignal, true),
validateResult: isValidResult,
rejected: async (response, requestSignal, attempt) => {
const error = await readErrorBody(response, requestSignal);
return {
error: new WorkspaceToolHttpError(
'rejected',
response.status,
error.body,
error.truncated,
),
...(attempt !== undefined &&
getWorkspaceAdmissionRejection(response.status, error.body, error.truncated) ===
'rate_limited'
? {
rateLimitDelayMs: workspaceAdmissionRetryDelay(
response.headers.get('Retry-After'),
error.body,
attempt,
policy,
),
}
: {}),
};
},
terminalFailure: durableWorkspaceFailure,
insufficient: () => new WorkspaceToolHttpError('insufficient_time'),
invalid: () => new WorkspaceToolHttpError('invalid'),
timeout: () => new WorkspaceToolHttpError('timeout'),
wait: waitForWorkspaceAdmission,
onRateLimitRejection: () => {
rateLimitRejections++;
if (rateLimitRejections === 1)
span.addEvent('workspace.admission.rejected', { kind: 'rate_limited' });
},
onRateLimitWait: (waitMs) => {
rateLimitWaitedMs += waitMs;
retryWaitMs += waitMs;
},
onRequest: (method) => {
httpRequests++;
if (method === 'POST') attempts++;
if (method === 'GET') durableReads++;
},
});
if (durable.supported) {
transport = 'durable';
outcome = 'completed';
return lane ? fromLinkedWorktreeResult(durable.result, lane.worktree) : durable.result;
}
transport = 'synchronous';
fallback = synchronousCommandFallback;
}
while (true) {
signal?.throwIfAborted();
/** Admission and retries cannot consume the reserved execution or delivery time. */
const attemptTimeoutMs = Math.floor(
Math.min(perAttemptTimeoutMs, callerDeadlineAt - Date.now()),
);
if (fallback == null && attemptTimeoutMs <= completionReserveMs) {
throw lastAdmissionRejection ?? new WorkspaceToolHttpError('insufficient_time');
}
const attemptStartedAt = Date.now();
const timeoutSignal = AbortSignal.timeout(attemptTimeoutMs);
const requestSignal =
signal != null && typeof AbortSignal.any === 'function'
? AbortSignal.any([signal, timeoutSignal])
: timeoutSignal;
let attemptHeaders: Record<string, string>;
try {
attemptHeaders =
typeof authHeaders === 'function'
? await getWorkspaceAuthHeaders(authHeaders, requestSignal)
: authHeaders;
} catch (error) {
if (timeoutSignal.aborted && signal?.aborted !== true) {
throw lastAdmissionRejection ?? new WorkspaceToolHttpError('insufficient_time');
}
throw error;
}
signal?.throwIfAborted();
if (timeoutSignal.aborted) {
throw lastAdmissionRejection ?? new WorkspaceToolHttpError('insufficient_time');
}
if (lastAdmissionRejection && Date.now() >= lastRetryDeadlineAt) {
throw lastAdmissionRejection;
}
const remainingMs = Math.min(
attemptTimeoutMs - (Date.now() - attemptStartedAt),
callerDeadlineAt - Date.now(),
);
if (fallback != null && wireRequest.operation === 'execute_command') {
const minAdmissionMs =
fallback.minAdmissionMs ?? CODE_ENVIRONMENT_COMMAND_ADMISSION_DEFAULT_MS;
const timeoutMs = Math.min(
fallback.timeoutMs,
wireRequest.timeoutMs ?? WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS,
fitWorkspaceCommandTimeoutToBudget(remainingMs, minAdmissionMs),
);
executionBudgetMs = getWorkspaceExecutionBudgetMs({ ...wireRequest, timeoutMs });
completionReserveMs = executionBudgetMs + WORKSPACE_COMMAND_TRANSPORT_GRACE_MS;
if (remainingMs - completionReserveMs < minAdmissionMs) {
throw lastAdmissionRejection ?? new WorkspaceToolHttpError('insufficient_time');
}
wireRequest = { ...wireRequest, timeoutMs };
callerRetryDeadlineAt = callerDeadlineAt - completionReserveMs;
body = JSON.stringify(wireRequest);
span.setAttribute('workspace.execution_budget_ms', executionBudgetMs);
fallback.onSelected(timeoutMs);
}
const queueAllowanceMs = Math.min(
policy.queueWaitMs ?? CODE_ENVIRONMENT_ADMISSION_MAX_MS,
Math.floor(remainingMs - completionReserveMs),
);
if (queueAllowanceMs < 1) {
throw lastAdmissionRejection ?? new WorkspaceToolHttpError('insufficient_time');
}
attempts++;
httpRequests++;
const response = await fetchImpl(
`${baseURL.trim().replace(/\/+$/, '')}/workspace-tools/execute`,
{
method: 'POST',
headers: {
...attemptHeaders,
'Content-Type': 'application/json',
[WORKSPACE_QUEUE_WAIT_HEADER]: String(queueAllowanceMs),
},
body,
redirect: 'error',
signal: requestSignal,
},
);
if (!response.ok) {
const { body, truncated } = await readErrorBody(response, requestSignal);
signal?.throwIfAborted();
const rejection = new WorkspaceToolHttpError('rejected', response.status, body, truncated);
const admission = getWorkspaceAdmissionRejection(response.status, body, truncated);
if (admission == null) throw rejection;
if (admission === 'queue_timeout') queueRejections++;
else rateLimitRejections++;
const rejectionCount =
admission === 'queue_timeout' ? queueRejections : rateLimitRejections;
if (rejectionCount === 1) {
span.addEvent('workspace.admission.rejected', { kind: admission });
}
const retryDeadlineAt = Math.min(
admission === 'queue_timeout' ? queueDeadlineAt : Infinity,
callerRetryDeadlineAt,
);
if (Date.now() >= retryDeadlineAt) throw rejection;
const retryAfterMs = workspaceAdmissionRetryDelay(
response.headers.get('Retry-After'),
admission === 'rate_limited' ? body : undefined,
rejectionCount,
policy,
);
if (
admission === 'rate_limited' &&
retryAfterMs > codeApiMaxRetryWaitMs - rateLimitWaitedMs
) {
throw rejection;
}
// Never truncate a server hint into an early retry.
if (!Number.isFinite(retryAfterMs) || retryAfterMs >= retryDeadlineAt - Date.now()) {
throw rejection;
}
const delayMs = retryAfterMs;
lastAdmissionRejection = rejection;
lastRetryDeadlineAt = retryDeadlineAt;
if (delayMs <= 0) throw rejection;
const waitStartedAt = Date.now();
await waitForWorkspaceAdmission(delayMs, signal);
retryWaitMs += Math.max(delayMs, Date.now() - waitStartedAt);
if (admission === 'rate_limited') {
/** A timer may run late. Charge the actual wait, but honor the retry that
* was authorized before waiting; another 429 cannot exceed the balance. */
rateLimitWaitedMs += Math.max(retryAfterMs, Date.now() - waitStartedAt);
}
/** Timer oversleep cannot consume the execution reserve. */
if (Date.now() >= retryDeadlineAt) {
throw rejection;
}
continue;
}
const result = await readBoundedJson(response, requestSignal);
if (!isValidResult(wireRequest, result)) {
throw new WorkspaceToolHttpError('invalid');
}
outcome = 'completed';
return lane ? fromLinkedWorktreeResult(result, lane.worktree) : result;
}
} catch (error) {
outcome = error instanceof WorkspaceToolHttpError ? error.reason : 'failed';
if (
signal?.aborted === true ||
(transport === 'durable' && isRecord(error) && error.name === 'AbortError')
)
outcome = 'cancelled';
if (error instanceof WorkspaceToolHttpError) throw error;
if (
(signal?.aborted === true &&
(error === signal.reason || (isRecord(error) && error.name === 'AbortError'))) ||
(transport === 'durable' && isRecord(error) && error.name === 'AbortError')
) {
throw error;
}
if (isRecord(error) && error.name === 'TimeoutError') {
outcome = 'timeout';
throw new WorkspaceToolHttpError('timeout');
}
throw new WorkspaceToolHttpError('failed');
} finally {
const diagnostics = {
operation: wireRequest.operation,
workspaceId: wireRequest.workspaceId,
...(lane == null ? {} : { lane: lane.worktree }),
outcome,
attempts,
transport,
httpRequests,
durableReads,
queueRejections,
rateLimitRejections,
retryWaitMs,
rateLimitWaitedMs,
elapsedMs: Math.max(0, Date.now() - startedAt),
};
span.setAttributes({
'workspace.outcome': outcome,
'workspace.attempts': attempts,
'workspace.transport': transport,
'workspace.http_requests': httpRequests,
'workspace.durable_reads': durableReads,
'workspace.queue_rejections': queueRejections,
'workspace.rate_limit_rejections': rateLimitRejections,
'workspace.client_retry_wait_ms': retryWaitMs,
'workspace.rate_limit_wait_ms': rateLimitWaitedMs,
});
span.end();
logger.debug('[WorkspaceAdmission] outcome', diagnostics);
}
}