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

17.7 KB
Raw Blame
import { Types } from 'mongoose';
import {
  enqueueAgentQueuedTurnSchema,
  isAgentsEndpoint,
  isEphemeralAgentId,
} from 'librechat-data-provider';
import {
  logger,
  AgentQueuedTurnCapacityError,
  AgentQueuedTurnConflictError,
  AgentQueuedTurnLaneRetiredError,
} from '@librechat/data-schemas';
import type {
  CodeApprovalMode,
  TAgentQueuedTurnFileRef,
  TAgentQueuedTurnReceipt,
  TFile,
  TReasoningOverride,
} from 'librechat-data-provider';
import type {
  AgentQueuedTurnActiveRecord,
  AgentQueuedTurnMethods,
  AgentQueuedTurnRecord,
  IMongoFile,
} from '@librechat/data-schemas';
import type { Request, RequestHandler } from 'express';
import type { AgentQueuedTurnLifecycle } from './queuedTurns';
import type { SteerFileFetcher } from './steering/request';
import type { SteerRequestUser } from './steering/refs';
import { buildOwnerFilter, collectFileIds, toSteerFileRef } from './steering/refs';
import { createQueuedTurnDeliveryReservation } from './queuedTurns';
import { getReferencedQuotes } from '~/utils';

const MAX_QUEUED_TURN_LENGTH = 16_000;
const MAX_QUEUED_TURN_FILES = 10;
const CAPABILITY = { supported: true, durability: 'durable', protocolVersion: 2 } as const;

interface QueuedTurnConversation {
  agent_id?: string;
  endpoint?: string;
  tenantId?: string;
}

interface QueuedTurnHttpMethods extends AgentQueuedTurnMethods {
  getConvo: (userId: string, conversationId: string) => Promise<QueuedTurnConversation | null>;
}

export interface AgentQueuedTurnHttpDeps {
  protocolVersion?: 2;
  methods: QueuedTurnHttpMethods;
  lifecycle: Pick<AgentQueuedTurnLifecycle, 'schedule' | 'cancel'>;
  getFiles?: SteerFileFetcher;
  updateFilesUsage?: (
    files: Array<{ file_id: string }>,
    fileIds?: string[],
    options?: { user?: string; tenantId?: string | null },
  ) => Promise<unknown[]>;
  checkAgentAccess?: (run: { agentId?: string; endpoint?: string }) => Promise<boolean>;
  isPrincipalActive?: (userId: string) => boolean | Promise<boolean>;
}

export interface AgentQueuedTurnHttpResult {
  status: number;
  body: Record<string, unknown>;
}

function owner(user: SteerRequestUser): { user: Types.ObjectId; tenantId?: string } | null {
  if (typeof user.id !== 'string' || !Types.ObjectId.isValid(user.id)) {
    return null;
  }
  return {
    user: new Types.ObjectId(user.id),
    ...(user.tenantId != null && { tenantId: user.tenantId }),
  };
}

function sameTenant(actual: unknown, expected: string | undefined): boolean {
  return expected == null ? actual == null : actual === expected;
}

function receipt(
  turn: AgentQueuedTurnRecord | AgentQueuedTurnActiveRecord,
  position?: number,
): TAgentQueuedTurnReceipt {
  const updatedAt = turn.updatedAt ?? turn.createdAt;
  return {
    queuedTurnId: turn.queuedTurnId,
    conversationId: turn.conversationId,
    parentMessageId: turn.parentMessageId,
    clientRequestId: turn.clientRequestId,
    text: turn.text,
    ...(turn.files != null && { files: turn.files }),
    ...(turn.quotes != null && { quotes: turn.quotes }),
    ...(turn.manualSkills != null && { manualSkills: turn.manualSkills }),
    ...(turn.codeApprovalMode != null && { codeApprovalMode: turn.codeApprovalMode }),
    ...(turn.reasoningOverride != null && { reasoningOverride: turn.reasoningOverride }),
    priority: turn.priority,
    ...(turn.expectedPredecessorCreatedAt != null && {
      expectedPredecessorCreatedAt: turn.expectedPredecessorCreatedAt,
    }),
    ...(turn.terminalReceipt?.outcome === 'admitted' &&
      turn.terminalReceipt.effectivePredecessorCreatedAt != null && {
        effectivePredecessorCreatedAt: turn.terminalReceipt.effectivePredecessorCreatedAt,
      }),
    ...(turn.terminalReceipt?.outcome === 'admitted' &&
      turn.terminalReceipt.rootPredecessor === true && { rootPredecessor: true as const }),
    status: turn.status,
    ...(position != null && { position }),
    revision: turn.sequence,
    createdAt: turn.createdAt.toISOString(),
    updatedAt: updatedAt.toISOString(),
    ...(turn.terminalReceipt?.failure != null && {
      failure: {
        code: turn.terminalReceipt.failure.code,
        message: turn.terminalReceipt.failure.message,
      },
    }),
  };
}

function parseClientRequestIds(raw: unknown): string[] | null {
  if (raw == null) {
    return [];
  }
  const values = Array.isArray(raw) ? raw : [raw];
  if (values.length > 100 || values.some((value) => typeof value !== 'string')) {
    return null;
  }
  const normalized = [...new Set((values as string[]).map((value) => value.trim()))];
  return normalized.some((value) => value.length === 0 || value.length > 128) ? null : normalized;
}

function sameStrings(left: readonly string[] | undefined, right: readonly string[] | undefined) {
  const a = left ?? [];
  const b = right ?? [];
  return a.length === b.length && a.every((value, index) => value === b[index]);
}

function uniqueStrings(values: readonly string[] | undefined): string[] | undefined {
  return values == null ? undefined : [...new Set(values)];
}

function sameReasoningOverride(
  left: TReasoningOverride | undefined,
  right: TReasoningOverride | undefined,
): boolean {
  return left?.key === right?.key && left?.value === right?.value;
}

function matchesReplayIntent(
  turn: AgentQueuedTurnRecord,
  input: {
    parentMessageId: string;
    clientRequestId: string;
    files?: readonly TAgentQueuedTurnFileRef[];
    manualSkills?: readonly string[];
    codeApprovalMode?: CodeApprovalMode;
    reasoningOverride?: TReasoningOverride;
    expectedPredecessorCreatedAt?: number;
  },
  text: string,
  quotes: readonly string[] | undefined,
): boolean {
  return (
    turn.parentMessageId === input.parentMessageId &&
    turn.clientRequestId === input.clientRequestId &&
    turn.text === text &&
    sameStrings(
      turn.files?.map((file) => file.file_id),
      uniqueStrings(input.files?.map((file) => file.file_id)),
    ) &&
    sameStrings(turn.quotes, quotes) &&
    sameStrings(turn.manualSkills, uniqueStrings(input.manualSkills)) &&
    turn.codeApprovalMode === input.codeApprovalMode &&
    sameReasoningOverride(turn.reasoningOverride, input.reasoningOverride) &&
    turn.expectedPredecessorCreatedAt === input.expectedPredecessorCreatedAt
  );
}

async function authorizeConversation(
  user: SteerRequestUser,
  conversationId: string,
  deps: AgentQueuedTurnHttpDeps,
): Promise<
  | { status: 200; conversation: QueuedTurnConversation & { agent_id: string } }
  | AgentQueuedTurnHttpResult
> {
  if (user.id == null) {
    return { status: 401, body: { code: 'UNAUTHORIZED' } };
  }
  const conversation = await deps.methods.getConvo(user.id, conversationId);
  if (conversation == null || !sameTenant(conversation.tenantId, user.tenantId)) {
    return { status: 404, body: { code: 'CONVERSATION_NOT_FOUND' } };
  }
  const agentId = conversation.agent_id;
  if (
    !isAgentsEndpoint(conversation.endpoint) ||
    typeof agentId !== 'string' ||
    isEphemeralAgentId(agentId)
  ) {
    return { status: 501, body: { code: 'QUEUED_TURNS_UNSUPPORTED' } };
  }
  if (
    deps.checkAgentAccess != null &&
    !(await deps.checkAgentAccess({ agentId, endpoint: conversation.endpoint }))
  ) {
    return { status: 403, body: { code: 'FORBIDDEN' } };
  }
  return { status: 200, conversation: { ...conversation, agent_id: agentId } };
}

async function resolveFiles(
  raw: unknown,
  user: SteerRequestUser,
  deps: AgentQueuedTurnHttpDeps,
): Promise<{ files?: TAgentQueuedTurnFileRef[]; error?: AgentQueuedTurnHttpResult }> {
  if (raw == null) {
    return {};
  }
  if (!Array.isArray(raw) || raw.length > MAX_QUEUED_TURN_FILES) {
    return { error: { status: 400, body: { code: 'INVALID_FILES' } } };
  }
  const requested = raw.map(toSteerFileRef);
  if (requested.some((file) => file == null)) {
    return { error: { status: 400, body: { code: 'INVALID_FILES' } } };
  }
  const files = requested as Partial<TFile>[];
  if (files.length === 0) {
    return {};
  }
  if (deps.getFiles == null || deps.updateFilesUsage == null) {
    return {
      error: { status: 503, body: { code: 'FILE_STORAGE_UNAVAILABLE' } },
    };
  }
  const ids = collectFileIds(files);
  const filter = buildOwnerFilter(ids, user);
  if (filter == null) {
    return { error: { status: 400, body: { code: 'INVALID_FILES' } } };
  }
  const docs = (await deps.getFiles(filter, {}, {})) ?? [];
  const byId = new Map(docs.map((doc: IMongoFile) => [doc.file_id, doc]));
  const resolved = ids.flatMap((id): TAgentQueuedTurnFileRef[] => {
    const ref = toSteerFileRef(byId.get(id));
    return ref == null ? [] : [{ ...ref, file_id: id }];
  });
  if (resolved.length !== ids.length) {
    return { error: { status: 400, body: { code: 'INVALID_FILES' } } };
  }
  const retained = await deps.updateFilesUsage(
    ids.map((file_id) => ({ file_id })),
    undefined,
    { user: user.id, tenantId: user.tenantId },
  );
  const retainedIds = new Set<string>();
  for (const file of retained) {
    if (
      file != null &&
      typeof file === 'object' &&
      'file_id' in file &&
      typeof file.file_id === 'string'
    ) {
      retainedIds.add(file.file_id);
    }
  }
  if (!ids.every((id) => retainedIds.has(id))) {
    return { error: { status: 503, body: { code: 'FILE_RETENTION_FAILED' } } };
  }
  return { files: resolved };
}

export async function handleAgentQueuedTurnEnqueue(
  user: SteerRequestUser,
  body: unknown,
  deps: AgentQueuedTurnHttpDeps,
): Promise<AgentQueuedTurnHttpResult> {
  const parsed = enqueueAgentQueuedTurnSchema.safeParse(body);
  if (!parsed.success) {
    return { status: 400, body: { code: 'INVALID_QUEUED_TURN' } };
  }
  const input = parsed.data;
  if (input.codeApprovalMode != null && deps.protocolVersion !== 2) {
    return { status: 409, body: { code: 'QUEUED_TURN_PROTOCOL_REQUIRED' } };
  }
  const text = input.text.replace(/\0/g, '').trim();
  if (text.length === 0) {
    return { status: 400, body: { code: 'EMPTY_TEXT' } };
  }
  if (text.length > MAX_QUEUED_TURN_LENGTH) {
    return {
      status: 413,
      body: { code: 'QUEUED_TURN_TOO_LONG', maxLength: MAX_QUEUED_TURN_LENGTH },
    };
  }
  /** Interrupt-and-send remains the existing warm steer path; a future lane
   * arbiter can add durable front insertion without weakening FIFO here. */
  if (input.priority === true) {
    return { status: 501, body: { code: 'QUEUED_TURN_PRIORITY_UNSUPPORTED' } };
  }
  const scope = owner(user);
  if (scope == null) {
    return { status: 401, body: { code: 'UNAUTHORIZED' } };
  }
  if (deps.isPrincipalActive != null && !(await deps.isPrincipalActive(user.id!))) {
    return { status: 409, body: { code: 'USER_DELETION_IN_PROGRESS' } };
  }
  const quotes = getReferencedQuotes(input.quotes) ?? undefined;
  /** Request identity is the durable receipt address. Resolve it before
   * mutable conversation/agent/file preconditions so an accepted turn remains
   * observable even if those resources change before a lost-response replay. */
  const existing = await deps.methods.getAgentQueuedTurnByClientRequestId({
    ...scope,
    conversationId: input.conversationId,
    clientRequestId: input.clientRequestId,
  });
  if (existing != null) {
    if (!matchesReplayIntent(existing, input, text, quotes)) {
      return { status: 409, body: { code: 'QUEUED_TURN_IDEMPOTENCY_CONFLICT' } };
    }
    if (existing.status !== 'queued' && existing.status !== 'claimed') {
      return {
        status: 200,
        body: { receipt: receipt(existing), capability: CAPABILITY },
      };
    }
    try {
      await deps.lifecycle.schedule(existing);
    } catch {
      return { status: 503, body: { code: 'QUEUED_TURN_SCHEDULING_PENDING' } };
    }
    const active = await deps.methods.listActiveAgentQueuedTurns({
      ...scope,
      conversationId: input.conversationId,
    });
    const position = active.findIndex((turn) => turn.queuedTurnId === existing.queuedTurnId);
    return {
      status: 202,
      body: {
        receipt: receipt(existing, position >= 0 ? position + 1 : undefined),
        capability: CAPABILITY,
      },
    };
  }
  const authorized = await authorizeConversation(user, input.conversationId, deps);
  if ('body' in authorized) {
    return authorized;
  }
  const resolvedFiles = await resolveFiles(input.files, user, deps);
  if (resolvedFiles.error != null) {
    return resolvedFiles.error;
  }
  try {
    const enqueueInput = {
      ...scope,
      conversationId: input.conversationId,
      agentId: authorized.conversation.agent_id,
      parentMessageId: input.parentMessageId,
      clientRequestId: input.clientRequestId,
      text,
      ...(resolvedFiles.files != null && { files: resolvedFiles.files }),
      ...(quotes != null && { quotes }),
      ...(input.manualSkills != null && { manualSkills: input.manualSkills }),
      ...(input.codeApprovalMode != null && { codeApprovalMode: input.codeApprovalMode }),
      ...(input.reasoningOverride != null && { reasoningOverride: input.reasoningOverride }),
      priority: false,
      ...(input.expectedPredecessorCreatedAt != null && {
        expectedPredecessorCreatedAt: input.expectedPredecessorCreatedAt,
      }),
    };
    const queued = await deps.methods.enqueueAgentQueuedTurn({
      ...enqueueInput,
      ...(input.codeApprovalMode != null && {
        deliveryReservation: createQueuedTurnDeliveryReservation(enqueueInput),
      }),
    });
    /** A same-body replay is the transport-independent receipt lookup. It can
     * arrive after the original row already settled, in which case no new
     * scheduling side effect is valid or necessary. */
    if (queued.replayed && queued.turn.status !== 'queued' && queued.turn.status !== 'claimed') {
      return {
        status: 200,
        body: { receipt: receipt(queued.turn), capability: CAPABILITY },
      };
    }
    try {
      await deps.lifecycle.schedule(queued.turn);
    } catch {
      /** The row is the outbox source of truth; periodic recovery repairs the
       * record-to-delivery seam. A retry with the same clientRequestId replays. */
      return { status: 503, body: { code: 'QUEUED_TURN_SCHEDULING_PENDING' } };
    }
    const active = await deps.methods.listActiveAgentQueuedTurns({
      ...scope,
      conversationId: input.conversationId,
    });
    const position = active.findIndex((turn) => turn.queuedTurnId === queued.turn.queuedTurnId);
    return {
      status: 202,
      body: {
        receipt: receipt(queued.turn, position >= 0 ? position + 1 : undefined),
        capability: CAPABILITY,
      },
    };
  } catch (error) {
    if (error instanceof AgentQueuedTurnCapacityError) {
      return { status: 429, body: { code: 'QUEUED_TURN_QUEUE_FULL' } };
    }
    if (error instanceof AgentQueuedTurnConflictError) {
      return {
        status: 409,
        body: { code: 'QUEUED_TURN_IDEMPOTENCY_CONFLICT' },
      };
    }
    if (error instanceof AgentQueuedTurnLaneRetiredError) {
      return { status: 409, body: { code: 'QUEUED_TURN_CONVERSATION_DELETING' } };
    }
    throw error;
  }
}

export async function handleAgentQueuedTurnList(
  user: SteerRequestUser,
  conversationId: unknown,
  deps: AgentQueuedTurnHttpDeps,
  rawClientRequestIds?: unknown,
): Promise<AgentQueuedTurnHttpResult> {
  if (typeof conversationId !== 'string' || conversationId.length === 0) {
    return { status: 400, body: { code: 'INVALID_CONVERSATION' } };
  }
  const scope = owner(user);
  if (scope == null) {
    return { status: 401, body: { code: 'UNAUTHORIZED' } };
  }
  const clientRequestIds = parseClientRequestIds(rawClientRequestIds);
  if (clientRequestIds == null) {
    return { status: 400, body: { code: 'INVALID_CLIENT_REQUEST_IDS' } };
  }
  const authorized = await authorizeConversation(user, conversationId, deps);
  if ('body' in authorized) {
    return authorized;
  }
  const turns = await deps.methods.listAgentQueuedTurnReceipts({
    ...scope,
    conversationId,
    clientRequestIds,
  });
  let activePosition = 0;
  return {
    status: 200,
    body: {
      queuedTurns: turns.map((turn) => {
        if (turn.status !== 'queued' && turn.status !== 'claimed') {
          return receipt(turn);
        }
        activePosition += 1;
        return receipt(turn, activePosition);
      }),
      capability: CAPABILITY,
      revision: turns.reduce((latest, turn) => Math.max(latest, turn.sequence), 0),
    },
  };
}

export async function handleAgentQueuedTurnCancel(
  user: SteerRequestUser,
  queuedTurnId: unknown,
  deps: AgentQueuedTurnHttpDeps,
): Promise<AgentQueuedTurnHttpResult> {
  if (typeof queuedTurnId !== 'string' || queuedTurnId.length === 0) {
    return { status: 400, body: { code: 'INVALID_QUEUED_TURN' } };
  }
  const scope = owner(user);
  if (scope == null) {
    return { status: 401, body: { code: 'UNAUTHORIZED' } };
  }
  const cancelled = await deps.lifecycle.cancel({
    ...scope,
    queuedTurnId,
    settledAt: new Date(),
  });
  if (cancelled.outcome === 'not_found') {
    return { status: 404, body: { code: 'QUEUED_TURN_NOT_FOUND' } };
  }
  if (cancelled.outcome === 'not_cancellable') {
    return { status: 409, body: { code: 'QUEUED_TURN_ALREADY_ADMITTING' } };
  }
  return { status: 200, body: { receipt: receipt(cancelled.turn) } };
}

/** Keep protocol selection and error handling in the TypeScript backend. */
export function createAgentQueuedTurnEnqueueHandlers(
  getDependencies: (req: Request) => AgentQueuedTurnHttpDeps,
): { enqueue: RequestHandler; enqueueV2: RequestHandler } {
  const create =
    (protocolVersion?: 2): RequestHandler =>
    async (req, res) => {
      try {
        const result = await handleAgentQueuedTurnEnqueue(req.user ?? {}, req.body ?? {}, {
          ...getDependencies(req),
          protocolVersion,
        });
        res.status(result.status).json(result.body);
      } catch (error) {
        logger.error('[AgentQueuedTurns] Failed to enqueue turn', error);
        res.status(500).json({ code: 'QUEUED_TURN_ENQUEUE_FAILED' });
      }
    };
  return { enqueue: create(), enqueueV2: create(2) };
}