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

24.4 KB
Raw Blame
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { pipeline } from 'node:stream/promises';
import { logger } from '@librechat/data-schemas';
import { getCodeBaseURL } from '@librechat/agents';
import { createHash, randomUUID } from 'node:crypto';
import {
  FileSources,
  getCodeEnvRefs,
  mergeCodeEnvRef,
  resolveSandboxFilename,
} from 'librechat-data-provider';
import type { CodeEnvRef, CodeEnvRefMap, TFile } from 'librechat-data-provider';
import type { Readable } from 'node:stream';
import type { FileStorageUploadObserver } from '../operations';
import type { CodeExecutionContext } from '~/agents/execution';
import type { CodeEnvIdentity } from '~/files/code/identity';
import type { CodeApiRateLimitBudget } from '~/utils';
import type { ServerRequest } from '~/types';
import {
  logAxiosError,
  createAxiosInstance,
  createCodeApiRateLimitBudget,
  codeServerHttpAgent,
  codeServerHttpsAgent,
  getCodeApiUploadOptions,
  withCodeApiUploadRecovery,
} from '~/utils';
import { getCodeEnvUploadFilename, getUploadedCodeEnvFilename } from '../code/form';
import { buildCodeEnvIdentityParams } from '~/files/code/identity';
import { codeExecutionHeaders } from '~/agents/execution';
import { getCodeApiAuthHeaders } from '~/auth/codeapi';
import { resolveDownloadPath } from '~/storage/path';

/** Storage strategy lookup, injected so this module stays free of the api workspace. */
export interface ProvisionDeps {
  getStrategyFunctions: (source: string) => {
    getDownloadStream?: (
      req: ServerRequest,
      filepath: string,
      options?: { signal?: AbortSignal },
    ) => Promise<Readable>;
    handleFileUpload?: (params: Record<string, unknown>) => Promise<{
      storage_session_id: string;
      file_id: string;
      filename?: string;
    }>;
  };
  uploadVectors: (params: {
    req: ServerRequest;
    file: { path: string; originalname: string; mimetype?: string; size?: number };
    file_id: string;
    entity_id?: string;
    signal?: AbortSignal;
    onUploadStart?: FileStorageUploadObserver;
  }) => Promise<{ embedded?: boolean } | undefined>;
  loadAuthValues: (params: {
    userId: string;
    authFields: string[];
    throwError?: boolean;
  }) => Promise<Record<string, string | undefined>>;
}

/** The Code API deployment an agent resolved for this turn. */
export interface CodeExecutionRoute {
  baseUrl?: string;
  executionProfile?: 'default' | 'stateful';
  executionRouteKey?: string;
}

/** Deferred database write produced by a successful provisioning call. */
export interface ProvisionFileUpdate {
  file_id: string;
  metadata?: Record<string, unknown>;
  embedded?: boolean;
}

/** One route pointer, written on its own so concurrent routes do not overwrite each other. */
export interface CodeEnvRefUpdate {
  file_id: string;
  routeKey: string;
  ref: CodeEnvRef;
  legacyRef?: CodeEnvRef;
}

/** Merged code-environment pointers written after a successful sandbox upload. */
export interface CodeEnvReferenceSetResult {
  codeEnvRef?: CodeEnvRef;
  codeEnvRefs?: CodeEnvRefMap;
}

export interface StoredFileDigest {
  sha256: string;
  bytes: number;
}

export interface ProvisionService {
  loadCodeApiKey: (userId: string) => Promise<string | undefined>;
  provisionToCodeEnv: (params: {
    req: ServerRequest;
    file: TFile;
    entity_id?: string;
    route?: CodeExecutionRoute;
    sandboxFilename?: string;
    signal?: AbortSignal;
    rateLimitBudget?: CodeApiRateLimitBudget;
    onUploadStart?: FileStorageUploadObserver;
  }) => Promise<{
    referenceSet: CodeEnvReferenceSetResult;
    refUpdate: CodeEnvRefUpdate;
    /** The name the sandbox stored it under, which a converted image renames. */
    sandboxFilename: string;
  }>;
  provisionToVectorDB: (params: {
    req: ServerRequest;
    file: TFile;
    entity_id?: string;
    existingStream?: Readable;
    signal?: AbortSignal;
    onUploadStart?: FileStorageUploadObserver;
  }) => Promise<{ embedded: boolean; fileUpdate: ProvisionFileUpdate | null }>;
  /** SHA-256 and length of the stored bytes, the same bytes a code-environment upload sends;
   *  null when the file's storage cannot be streamed. */
  digestFile: (params: {
    req: ServerRequest;
    file: TFile;
    signal?: AbortSignal;
  }) => Promise<StoredFileDigest | null>;
  checkSessionsAlive: (params: {
    files: TFile[];
    apiKey?: string;
    req?: ServerRequest;
    staleSafeWindowMs?: number;
    /** Deployment this turn runs on. Refs are deployment-local, so a ref is probed
     *  against the Code API that issued it, not against the default one. */
    baseURL?: string;
    routeKey?: string;
    /** Wire profile and worker of that deployment. A worker-bound route authorizes
     *  only a bearer minted for its worker, exactly as its uploads and reads do. */
    executionProfile?: CodeExecutionContext['executionProfile'];
    bridgeWorkerId?: string;
  }) => Promise<Set<string>>;
}

/**
 * Provisioning service for the code environment and vector store.
 *
 * Storage strategies, vector upload, and credential lookup live in the api workspace,
 * so they are injected rather than imported: that keeps the logic here, where it is
 * type checked, and leaves only wiring on the other side.
 */
/** The reference a given deployment issued, across both the per-route map and the
 *  legacy single pointer. A ref from another deployment answers for another Code API. */
const codeEnvRefForRoute = (file: TFile, routeKey: string): CodeEnvRef | undefined =>
  getCodeEnvRefs(file.metadata).find(([key]) => key === routeKey)?.[1];

export function createProvisionService({
  getStrategyFunctions,
  uploadVectors,
  loadAuthValues,
}: ProvisionDeps): ProvisionService {
  /* Created on first use rather than at module load: this module is pulled into the
   * OpenAI-compatible controllers, whose tests partially mock @librechat/api, and a
   * load-time call would throw before any provisioning is even requested. */
  let axiosInstance;
  const getAxios = () => (axiosInstance ??= createAxiosInstance());

  /* Sources whose `getDownloadStream` takes `(req, filepath)` and returns a readable.
   * Others diverge: `openai` takes `(file_id, client)` and `execute_code` takes
   * `(fileIdentifier, identity, req)` returning an Axios response, so calling them
   * through this contract fails. An allowlist keeps an unfamiliar source skipped
   * rather than mis-invoked. */
  const STORAGE_STREAM_SOURCES = new Set([
    FileSources.local,
    FileSources.s3,
    FileSources.cloudfront,
    FileSources.azure_blob,
    FileSources.firebase,
  ]);

  /** Resolves a storage download stream, or null when the source uses a different contract. */
  async function getStorageStream(
    file: TFile,
    req: ServerRequest,
    signal?: AbortSignal,
  ): Promise<Readable | null> {
    if (file.source == null || !STORAGE_STREAM_SOURCES.has(file.source)) {
      logger.warn(
        `[provision] Cannot stream "${file.filename}" (${file.file_id}) from source "${file.source}": unsupported download contract`,
      );
      return null;
    }
    const { getDownloadStream } = getStrategyFunctions(file.source as string);
    if (!getDownloadStream) {
      return null;
    }
    signal?.throwIfAborted();
    const stream = await getDownloadStream(req, resolveDownloadPath(file), { signal });
    if (signal?.aborted) {
      stream.destroy(signal.reason instanceof Error ? signal.reason : undefined);
      signal.throwIfAborted();
    }
    return stream;
  }

  /**
   * Auth for a liveness probe against the route that issued the refs, matching what that
   * route's uploads, reads and executions send. The legacy key belongs to the default
   * Code API alone: an attached or stateful route never receives it, and a worker-bound
   * route gets a bearer minted for its worker plus the route headers. Returns null when
   * there is nothing to authenticate with, neither a request to mint from nor a key this
   * route accepts, since the probe could only be rejected.
   */
  async function buildSessionProbeHeaders({
    apiKey,
    req,
    routeKey,
    executionProfile,
    bridgeWorkerId,
  }: {
    apiKey?: string;
    req?: ServerRequest;
    routeKey?: string;
    executionProfile?: CodeExecutionContext['executionProfile'];
    bridgeWorkerId?: string;
  }): Promise<Record<string, string> | null> {
    const isDefaultRoute = (routeKey ?? 'default') === 'default';
    const authHeaders = await getCodeApiAuthHeaders(req, bridgeWorkerId);
    const legacyKey = isDefaultRoute && authHeaders.Authorization == null ? apiKey : undefined;
    if (req == null && authHeaders.Authorization == null && !legacyKey) {
      return null;
    }
    return {
      'User-Agent': 'LibreChat/1.0',
      ...(legacyKey ? { 'X-API-Key': legacyKey } : {}),
      ...authHeaders,
      ...(executionProfile ? codeExecutionHeaders({ executionProfile, bridgeWorkerId }) : {}),
    };
  }

  /** Env var holding the code-execution API key (symmetric with LIBRECHAT_CODE_BASEURL). */
  const CODE_API_KEY_FIELD = 'LIBRECHAT_CODE_API_KEY';

  /**
   * Loads the code-execution API key for a user. Call once per request and pass the
   * result to checkSessionsAlive to avoid redundant lookups. Returns undefined when
   * no key is configured; JWT-mode code auth can still authorize provisioning.
   *
   * @param {string} userId
   * @returns {Promise<string | undefined>} The code-execution API key, if configured
   */
  async function loadCodeApiKey(userId: string): Promise<string | undefined> {
    const result = await loadAuthValues({
      userId,
      authFields: [CODE_API_KEY_FIELD],
      throwError: false,
    });
    return result[CODE_API_KEY_FIELD];
  }

  /**
   * Provisions a file to the code execution environment.
   * Gets a read stream from our storage and uploads to the code env, persisting
   * the resulting `codeEnvRef` so downstream readers (primeFiles, code env
   * categorization) can locate the sandbox copy on subsequent turns.
   *
   * @param {object} params
   * @param {object} params.req - Express request object (needs req.user.id)
   * @param {import('librechat-data-provider').TFile} params.file - The file record from DB
   * @param {string} [params.entity_id] - Optional entity ID (agent_id); when present the ref
   *   is scoped to `kind: 'agent'`, otherwise it falls back to `kind: 'user'`.
   * @returns {Promise<{ referenceSet: { codeEnvRef: object, codeEnvRefs: object }, fileUpdate: object }>}
   *   Merged pointers plus the deferred DB update
   */
  async function provisionToCodeEnv({
    req,
    file,
    entity_id,
    route,
    sandboxFilename: requestedSandboxFilename,
    signal,
    rateLimitBudget,
    onUploadStart,
  }: {
    req: ServerRequest;
    file: TFile;
    entity_id?: string;
    route?: CodeExecutionRoute;
    sandboxFilename?: string;
    signal?: AbortSignal;
    rateLimitBudget?: CodeApiRateLimitBudget;
    onUploadStart?: FileStorageUploadObserver;
  }) {
    signal?.throwIfAborted();
    const { handleFileUpload: uploadCodeEnvFile } = getStrategyFunctions(FileSources.execute_code);
    if (!uploadCodeEnvFile) {
      throw new Error('Code environment upload strategy is unavailable');
    }
    const kind: 'agent' | 'user' = entity_id ? 'agent' : 'user';
    const id = entity_id ?? (req.user?.id as string);

    /* Upload to the deployment this agent actually resolved. Hard-coding the default
     * meant a stateful agent's file was uploaded to the wrong Code API and then had to
     * be re-uploaded by priming, and a deployment whose only healthy Code API is the
     * configured stateful one could not provision at all. */
    const executionProfile = route?.executionProfile ?? 'default';
    const sandboxFilename = getCodeEnvUploadFilename(
      resolveSandboxFilename(requestedSandboxFilename ?? file.filename, file.type),
    );
    const uploadOptions = getCodeApiUploadOptions(
      req,
      route?.executionRouteKey ?? route?.baseUrl ?? executionProfile,
    );
    const uploaded = await withCodeApiUploadRecovery({
      registry: req.app.locals.codeApiUploadRegistry,
      scope: uploadOptions.scope,
      concurrency: uploadOptions.concurrency,
      label: `uploading "${file.filename}" to the code environment`,
      budget: rateLimitBudget ?? createCodeApiRateLimitBudget(uploadOptions.retryWaitMs),
      signal,
      onWait: (waitMs) =>
        logger.warn(
          `[provisionToCodeEnv] Rate-limited uploading file ${file.file_id}; retrying in ${waitMs}ms`,
        ),
      openSource: async () => {
        const stream = await getStorageStream(file, req, signal);
        signal?.throwIfAborted();
        if (!stream) {
          throw new Error(
            `Cannot provision file "${file.filename}" to code env: storage source "${file.source}" does not support download streams`,
          );
        }
        return stream;
      },
      upload: (stream) =>
        uploadCodeEnvFile({
          req,
          stream,
          filename: sandboxFilename,
          kind,
          id,
          ...(route?.baseUrl ? { codeApiBaseUrl: route.baseUrl } : {}),
          executionProfile,
          signal,
          onUploadStart,
        }),
    });

    /* A successful upload must reach pointer persistence even if cancellation just arrived. */
    /* Merge rather than overwrite: the eager upload path persists the same shape via
     * mergeCodeEnvRef, so both the legacy pointer and the route-keyed map stay in sync
     * and pointers for other Code API routes survive re-provisioning. */
    const storedSandboxFilename = getUploadedCodeEnvFilename(uploaded, sandboxFilename);
    const ref: CodeEnvRef = {
      kind,
      id,
      storage_session_id: uploaded.storage_session_id,
      file_id: uploaded.file_id,
      executionProfile,
      ...(route?.executionRouteKey ? { executionRouteKey: route.executionRouteKey } : {}),
      provisionedAt: Date.now(),
      sandboxFilename: storedSandboxFilename,
    };
    const referenceSet = mergeCodeEnvRef(file.metadata, ref);
    const routeKey = route?.executionRouteKey ?? executionProfile;

    logger.debug(
      `[provisionToCodeEnv] Provisioned file "${file.filename}" (${file.file_id}) to code env`,
    );

    return {
      referenceSet,
      sandboxFilename: storedSandboxFilename,
      refUpdate: {
        file_id: file.file_id,
        routeKey,
        ref,
        ...(referenceSet.codeEnvRef ? { legacyRef: referenceSet.codeEnvRef } : {}),
      },
    };
  }

  /**
   * Provisions a file to the vector DB for file_search/RAG.
   * Gets the file from our storage and uploads vectors/embeddings.
   *
   * @param {object} params
   * @param {object} params.req - Express request object
   * @param {import('librechat-data-provider').TFile} params.file - The file record from DB
   * @param {string} [params.entity_id] - Optional entity ID (agent_id)
   * @param {import('stream').Readable} [params.existingStream] - Pre-fetched download stream (avoids duplicate storage fetch)
   * @returns {Promise<{ embedded: boolean, fileUpdate: object | null }>} Result with deferred DB update
   */
  async function provisionToVectorDB({
    req,
    file,
    entity_id,
    existingStream,
    onUploadStart,
    signal,
  }: {
    req: ServerRequest;
    file: TFile;
    entity_id?: string;
    existingStream?: Readable;
    signal?: AbortSignal;
    onUploadStart?: FileStorageUploadObserver;
  }): Promise<{ embedded: boolean; fileUpdate: { file_id: string; embedded?: boolean } | null }> {
    /* Unique per attempt: two concurrent requests provisioning the same file_id would
     * otherwise share one path, and the first to finish unlinks it while the second is
     * still streaming into uploadVectors. */
    const tmpPath = path.join(
      os.tmpdir(),
      `provision-${file.file_id}-${randomUUID()}${path.extname(file.filename)}`,
    );

    try {
      signal?.throwIfAborted();
      let stream: Readable | undefined = existingStream;
      if (!stream) {
        stream = (await getStorageStream(file, req, signal)) ?? undefined;
        if (!stream) {
          throw new Error(
            `Cannot provision file "${file.filename}" to vector DB: storage source "${file.source}" does not support download streams`,
          );
        }
      }

      // uploadVectors expects a file-like object with a `path` property for fs.createReadStream.
      // Since we're provisioning from storage (not a multer upload), we stream to a temp file first.
      await pipeline(stream, fs.createWriteStream(tmpPath), { signal });

      const tempFile = {
        path: tmpPath,
        originalname: file.filename,
        mimetype: file.type,
        size: file.bytes,
      };

      const embeddingResult = await uploadVectors({
        req,
        file: tempFile,
        file_id: file.file_id,
        entity_id,
        signal,
        onUploadStart,
      });

      const embedded = embeddingResult?.embedded ?? false;

      logger.debug(
        `[provisionToVectorDB] Provisioned file "${file.filename}" (${file.file_id}) to vector DB, embedded=${embedded}`,
      );

      return {
        embedded,
        fileUpdate: embedded ? { file_id: file.file_id, embedded } : null,
      };
    } finally {
      try {
        fs.unlinkSync(tmpPath);
      } catch {
        // Ignore cleanup errors
      }
    }
  }

  /**
   * Batch-check code env file liveness by `storage_session_id`.
   * Groups files by session, makes one API call per session.
   *
   * @param {object} params
   * @param {import('librechat-data-provider').TFile[]} params.files - Files with metadata.codeEnvRef
   * @param {string} [params.apiKey] - Pre-loaded legacy CODE_API_KEY, when configured
   * @param {object} [params.req] - Request used to mint JWT code auth, when enabled
   * @param {number} [params.staleSafeWindowMs=21600000] - Skip the live check if the file was provisioned to the code env within this window (default 6h)
   * @returns {Promise<Set<string>>} file_ids that are not known to be expired: confirmed
   *   alive, within the safe window, or unverifiable because the probe itself failed
   */
  /** A definitive not-found from the Code API, as opposed to a transient probe failure. */
  function isSessionNotFound(error: unknown): boolean {
    const { response, status } = (error ?? {}) as {
      response?: { status?: number };
      status?: number;
    };
    return (response?.status ?? status) === 404;
  }

  async function checkSessionsAlive({
    files,
    apiKey,
    req,
    staleSafeWindowMs = 6 * 60 * 60 * 1000,
    baseURL: routeBaseURL,
    routeKey,
    executionProfile,
    bridgeWorkerId,
  }: {
    files: TFile[];
    apiKey?: string;
    req?: ServerRequest;
    staleSafeWindowMs?: number;
    baseURL?: string;
    routeKey?: string;
    executionProfile?: CodeExecutionContext['executionProfile'];
    bridgeWorkerId?: string;
  }): Promise<Set<string>> {
    const aliveFileIds = new Set<string>();
    const now = Date.now();

    /* Group by session AND resource identity, skipping recently-updated files. Codeapi
     * reconstructs the session key from kind and id for shared kinds, so a probe that
     * omits them asks about the requester's own bucket and 404s on a live agent
     * session, which reads here as expiry and forces a needless re-upload. */
    const sessionGroups = new Map<
      string,
      {
        session_id: string;
        identity: CodeEnvIdentity;
        entries: Array<{ file_id: string; remoteFileId: string }>;
      }
    >();

    for (const file of files) {
      const ref = routeKey != null ? codeEnvRefForRoute(file, routeKey) : file.metadata?.codeEnvRef;
      if (!ref?.storage_session_id || !ref?.file_id) {
        continue;
      }

      // Trust only the code-env upload timestamp, not `updatedAt` (bumped by usage,
      // e.g. updateFilesUsage on resend); a usage-touched file may still have an
      // expired sandbox session. Refs without a marker fall through to a live check.
      const provisionedAt = ref.provisionedAt ?? 0;
      if (provisionedAt && now - provisionedAt < staleSafeWindowMs) {
        aliveFileIds.add(file.file_id);
        continue;
      }

      const identity: CodeEnvIdentity = {
        kind: ref.kind,
        id: ref.id,
        ...(ref.kind === 'skill' ? { version: ref.version } : {}),
      };
      const groupKey = `${ref.storage_session_id}\0${identity.kind}\0${identity.id}\0${
        identity.version ?? ''
      }`;
      let group = sessionGroups.get(groupKey);
      if (!group) {
        group = { session_id: ref.storage_session_id, identity, entries: [] };
        sessionGroups.set(groupKey, group);
      }
      group.entries.push({ file_id: file.file_id, remoteFileId: ref.file_id });
    }

    if (sessionGroups.size === 0) {
      return aliveFileIds;
    }
    const keepUnverified = () => {
      for (const file of files) {
        if (file?.file_id) {
          aliveFileIds.add(file.file_id);
        }
      }
      return aliveFileIds;
    };

    /* Minting can fail on its own, for example when the request carries no tenant
     * context. That is an unverifiable probe, not an expired file, so it is handled
     * like any other probe failure: every ref stays alive rather than the rejection
     * propagating out and aborting initialization for the whole turn. */
    let headers: Record<string, string> | null;
    try {
      headers = await buildSessionProbeHeaders({
        apiKey,
        req,
        routeKey,
        executionProfile,
        bridgeWorkerId,
      });
    } catch (error) {
      logger.warn(
        `[checkSessionsAlive] Could not build Code API auth headers; treating ${files.length} reference(s) as unverified: ${(error as Error).message}`,
      );
      return keepUnverified();
    }
    /* Sending a credential the route does not accept only earns a 401, so a route with
     * no usable credential this turn is left unverified without a request. */
    if (headers == null) {
      logger.debug(
        `[checkSessionsAlive] No credential this route accepts is available; treating ${files.length} reference(s) as unverified`,
      );
      return keepUnverified();
    }

    // One API call per session (in parallel)
    const baseURL = routeBaseURL ?? getCodeBaseURL();
    const sessionChecks = Array.from(sessionGroups.values()).map(
      async ({ session_id, identity, entries: fileEntries }) => {
        try {
          const response = await getAxios()({
            method: 'get',
            url: `${baseURL}/files/${session_id}`,
            params: { detail: 'summary', ...buildCodeEnvIdentityParams(identity) },
            headers,
            httpAgent: codeServerHttpAgent,
            httpsAgent: codeServerHttpsAgent,
            timeout: 5000,
          });

          const remoteFiles = response.data ?? [];
          for (const { file_id, remoteFileId } of fileEntries) {
            if (
              (remoteFiles as Array<{ fileId?: string }>).some((f) => f.fileId === remoteFileId)
            ) {
              aliveFileIds.add(file_id);
            }
          }
        } catch (error) {
          logAxiosError({
            message: `[checkSessionsAlive] Error checking session "${session_id}": ${(error as Error).message}`,
            error,
          });
          /* A 404 is the Code API answering that the session is gone, so its files are
           * expired and a replacement upload should be queued. Every other failure means
           * unknown: a timeout or 5xx would otherwise clear a live ref and force a
           * re-upload that the same outage will likely fail too. */
          if (isSessionNotFound(error)) {
            return;
          }
          for (const { file_id } of fileEntries) {
            aliveFileIds.add(file_id);
          }
        }
      },
    );

    await Promise.allSettled(sessionChecks);
    return aliveFileIds;
  }
  async function digestFile({
    req,
    file,
    signal,
  }: {
    req: ServerRequest;
    file: TFile;
    signal?: AbortSignal;
  }): Promise<StoredFileDigest | null> {
    const stream = await getStorageStream(file, req, signal);
    if (stream == null) {
      return null;
    }
    const hash = createHash('sha256');
    let bytes = 0;
    const abort = () => stream.destroy(signal?.reason instanceof Error ? signal.reason : undefined);
    signal?.addEventListener('abort', abort, { once: true });
    try {
      for await (const chunk of stream) {
        const buffer: Buffer = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
        hash.update(buffer);
        bytes += buffer.byteLength;
      }
    } finally {
      signal?.removeEventListener('abort', abort);
    }
    signal?.throwIfAborted();
    return { sha256: hash.digest('hex'), bytes };
  }

  return {
    loadCodeApiKey,
    provisionToCodeEnv,
    provisionToVectorDB,
    digestFile,
    checkSessionsAlive,
  };
}