Skip to content

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

57.7 KB
Raw Blame
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);
  }
}