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

12.3 KB
Raw Blame
import { logger } from '@librechat/data-schemas';
import { excludedKeys, isAgentsEndpoint, isEphemeralAgentId } from 'librechat-data-provider';
import type { AppConfig, ConversationMethods, IConversation } from '@librechat/data-schemas';
import type { TConversation } from 'librechat-data-provider';
import type { PersistedReply } from './announce';
import { isAnnounceableReply } from './announce';

type SaveConvo = ConversationMethods['saveConvo'];
type SaveConvoOptions = NonNullable<Parameters<SaveConvo>[2]>;
type SavedMessageId = NonNullable<SaveConvoOptions['appendMessageIds']>[number];
type ConversationStore = Pick<ConversationMethods, 'getConvo' | 'saveConvo'>;

/** Retention context a message or conversation write runs under. */
export type ConversationWriteContext = Parameters<SaveConvo>[0];

/** The request state a turn's conversation writes read and update. */
export interface TurnConversationRequest {
  user?: { id?: string };
  body?: { isTemporary?: boolean };
  config?: { interfaceConfig?: AppConfig['interfaceConfig'] };
  /** Server-captured creation time, stamped only when a write inserts the row. */
  conversationCreatedAt?: string;
  /** `null` once looked up and absent; unset until something has read it. */
  resolvedConversation?: Partial<IConversation> | null;
  _agentEventBindingRetention?: { isTemporary?: boolean; expiredAt?: Date };
  /** Set for subagent threads, whose rows only their parent run may create. */
  _agentEventBindingParentConversationId?: string;
}

/** The conversation fields a turn writes, shared by its seed and its message saves. */
export interface TurnConversationFields {
  req?: TurnConversationRequest;
  conversationId: string;
  endpoint?: string | null;
  endpointType?: string | null;
  endpointOptions?: Partial<TConversation>;
  /** The agent running the turn, recorded as the conversation's initial agent when persisted. */
  agentId?: string;
  /** Stored fields this write leaves as they are when `endpointOptions` omits them, instead of
   *  unsetting them: the turn made no decision about them. */
  preservedFields?: ReadonlyArray<keyof TConversation>;
  /** Logged by `saveConvo` to name the write. */
  context: string;
}

export interface TurnConversationWrite extends TurnConversationFields {
  ctx: ConversationWriteContext;
  /** Whether an earlier write in this request already initialized the conversation. */
  initialized?: boolean;
  /** The message this write just saved, appended to the conversation's message list. */
  savedMessageId?: SavedMessageId;
  /**
   * The assistant reply this write persisted, if any. Absent for the user's own turn and for a
   * reply whose message write resolved empty; whether it may raise an indicator is decided by
   * `isAnnounceableReply`, the same predicate every other persistence path asks.
   */
  reply?: PersistedReply;
}

export interface TurnConversationResult {
  conversation: Awaited<ReturnType<SaveConvo>>;
  /** Whether the conversation was already stored, so later writes in the turn skip that work. */
  initialized: boolean;
}

function hasResolvedConversation(req?: TurnConversationRequest): boolean {
  return req != null && Object.prototype.hasOwnProperty.call(req, 'resolvedConversation');
}

/** Whether `retentionMode: all` still needs the stored conversation to stamp a write. */
export function needsRetentionConversation(req?: TurnConversationRequest): boolean {
  const interfaceConfig = req?.config?.interfaceConfig;
  return (
    interfaceConfig?.retentionMode === 'all' &&
    interfaceConfig.generalChatRetention !== undefined &&
    !hasResolvedConversation(req)
  );
}

/** Builds the retention context a message or conversation write runs under. */
export function getConversationWriteContext(
  req?: TurnConversationRequest,
): ConversationWriteContext {
  const resolved = hasResolvedConversation(req) ? req?.resolvedConversation : null;
  return {
    userId: req?.user?.id ?? '',
    isTemporary:
      req?._agentEventBindingRetention?.isTemporary ??
      resolved?.isTemporary ??
      req?.body?.isTemporary,
    expiredAt: req?._agentEventBindingRetention?.expiredAt ?? resolved?.expiredAt ?? undefined,
    interfaceConfig: req?.config?.interfaceConfig,
  };
}

function isAgentOwned(write: TurnConversationFields): boolean {
  const agentId = write.endpointOptions?.agent_id;
  return (
    isAgentsEndpoint(write.endpoint) &&
    agentId != null &&
    agentId !== '' &&
    !isEphemeralAgentId(agentId)
  );
}

/** Keys the stored row carries that this turn's options no longer set. */
function getUnsetFields(
  existing: Partial<IConversation>,
  endpointOptions: Partial<TConversation>,
  agentOwned: boolean,
  preservedFields: ReadonlyArray<keyof TConversation> = [],
): Record<string, number> {
  const kept = new Set(['spec', 'iconURL']);
  if (agentOwned) {
    kept.add('model');
  }
  const preserved = new Set<string>(preservedFields);
  const unsetFields: Record<string, number> = {};
  for (const key of Object.keys(existing)) {
    if ((excludedKeys.has(key) && !kept.has(key)) || preserved.has(key)) {
      continue;
    }
    if (endpointOptions[key as keyof TConversation] === undefined) {
      unsetFields[key] = 1;
    }
  }
  return unsetFields;
}

function getCreatedAtOnInsert(req?: TurnConversationRequest): Date | undefined {
  if (req?.conversationCreatedAt == null) {
    return undefined;
  }
  const createdAt = new Date(req.conversationCreatedAt);
  return Number.isNaN(createdAt.getTime()) ? undefined : createdAt;
}

async function loadExistingConversation(
  deps: ConversationStore,
  write: TurnConversationWrite,
): Promise<Partial<IConversation> | null> {
  if (write.initialized === true) {
    return null;
  }
  if (hasResolvedConversation(write.req)) {
    return write.req?.resolvedConversation ?? null;
  }
  return deps.getConvo(write.ctx.userId, write.conversationId);
}

/**
 * The reply stamp a write carries, and nothing when it carries none.
 *
 * `saveConvo` assigns the timestamp itself, past its own awaited reads and against the write, so
 * a catch-up recorded by `/seen` while one of those reads is in flight cannot outrank this reply
 * and leave it reading as already seen. A temporary chat is never announced: it has no row in the
 * lists the indicator is read from, and a row with nothing a reader can open is not either.
 */
function getReplyStamp(
  write: TurnConversationWrite,
): { stampReply: true; replyMessageId: string } | Record<string, never> {
  const { reply } = write;
  if (reply == null || !isAnnounceableReply({ ...reply, isTemporary: write.ctx.isTemporary })) {
    return {};
  }
  return { stampReply: true, replyMessageId: reply.messageId as string };
}

async function writeConversation(
  deps: ConversationStore,
  write: TurnConversationWrite,
  existing: Partial<IConversation> | null,
  appendMessageIds: SavedMessageId[] | undefined,
): Promise<TurnConversationResult> {
  const { req, ctx, conversationId, endpoint, endpointType, endpointOptions = {} } = write;
  const agentOwned = isAgentOwned(write);
  const inserting = write.initialized !== true && existing == null;
  const { chatProjectId, ...storedOptions } = endpointOptions;
  const conversation = await deps.saveConvo(
    ctx,
    {
      endpoint,
      endpointType,
      ...storedOptions,
      ...(inserting && chatProjectId !== undefined ? { chatProjectId } : {}),
      conversationId: endpointOptions.conversationId ?? conversationId,
    },
    {
      context: write.context,
      unsetFields:
        existing != null
          ? getUnsetFields(existing, endpointOptions, agentOwned, write.preservedFields)
          : {},
      noUpsert: req?._agentEventBindingParentConversationId != null,
      initialAgentId: agentOwned ? (write.agentId ?? null) : null,
      createdAtOnInsert: inserting ? getCreatedAtOnInsert(req) : undefined,
      ...(appendMessageIds != null ? { appendMessageIds } : {}),
      ...getReplyStamp(write),
    },
  );
  if (req != null && conversation != null && 'conversationId' in conversation) {
    req.resolvedConversation = conversation;
  }
  return { conversation, initialized: existing != null };
}

/** Writes the conversation row for a turn's message save. */
export async function saveTurnConversation(
  deps: ConversationStore,
  write: TurnConversationWrite,
): Promise<TurnConversationResult> {
  const existing = await loadExistingConversation(deps, write);
  const appendMessageIds = write.savedMessageId != null ? [write.savedMessageId] : undefined;
  return writeConversation(deps, write, existing, appendMessageIds);
}

/**
 * Adds one message's id to its conversation. Declared structurally, and by plain id, so this
 * operation's callers never name the storage engine's own id type.
 */
export interface MessageReferenceAppender {
  appendConvoMessageReference(
    user: string,
    conversationId: string,
    messageId: string,
  ): Promise<unknown>;
}

/** What a turn knows about a message row whose conversation reference may be missing. */
export interface TurnMessageReferenceRecovery {
  userId: string;
  conversationId: string;
  /** The row a retry restored. Absent means there is nothing to reference. */
  messageId?: string;
  /** Whether the write that should have appended this reference already did. */
  alreadyRecorded: boolean;
  /** False for a turn whose conversation row another run owns, which holds no messages. */
  managesConversation: boolean;
  /** Names the caller in the repair log. */
  context: string;
}

/**
 * Appends a recovered message's reference when nothing else recorded it.
 *
 * A message write can fail and be swallowed, or resolve falsy on a duplicate key it cannot
 * re-read; either way its conversation is written with nothing appended. The turn then retries
 * the row with a bare `saveMessage`, which never touches the conversation, so that row would
 * stay absent from `messages` for good — every other write appends only its own id.
 *
 * Skipped whenever the reference is already recorded, which is every ordinary turn, so the happy
 * path costs no write. Returns whether it wrote.
 */
export async function recoverTurnMessageReference(
  deps: MessageReferenceAppender,
  recovery: TurnMessageReferenceRecovery,
): Promise<boolean> {
  const { userId, conversationId, messageId, alreadyRecorded, managesConversation } = recovery;
  if (alreadyRecorded || !managesConversation || messageId == null || messageId === '') {
    return false;
  }
  try {
    await deps.appendConvoMessageReference(userId, conversationId, messageId);
    return true;
  } catch (error) {
    /** Bookkeeping beside the row it points at: the message itself is already durable, and
     *  failing a turn over its reference would trade a wrong field for a lost response. The
     *  next write that appends to this conversation carries it. */
    logger.error(`[recoverTurnMessageReference] ${recovery.context}`, error);
    return false;
  }
}

/**
 * Creates a new conversation's row ahead of a deferred first message, without the message, so
 * the conversation lists return a running chat. An existing row is left to the message save.
 * Settles once the write has finished and never rejects.
 */
export async function seedTurnConversation(
  deps: ConversationStore,
  fields: TurnConversationFields,
): Promise<void> {
  const { req } = fields;
  const userId = req?.user?.id;
  if (req == null || userId == null || userId === '') {
    return;
  }
  try {
    if (!hasResolvedConversation(req)) {
      req.resolvedConversation = await deps.getConvo(userId, fields.conversationId);
    }
    const write: TurnConversationWrite = { ...fields, ctx: getConversationWriteContext(req) };
    const existing = await loadExistingConversation(deps, write);
    if (existing != null) {
      return;
    }
    /** An empty append set tells `saveConvo` the row holds no messages yet, sparing the read. */
    await writeConversation(deps, write, null, []);
  } catch (error) {
    logger.error('[seedTurnConversation] Failed to seed the conversation', error);
  }
}

/**
 * Orders a deferred write behind a seed of the same row. While the seed is in flight the write
 * waits for it; once the seed has landed the write starts synchronously, which a Stop relies on.
 * `seed` must not reject.
 */
export function runAfterSeed<T>(seed: Promise<void>, write: () => Promise<T>): () => Promise<T> {
  let seeding = true;
  void seed.finally(() => {
    seeding = false;
  });
  return () => (seeding ? seed.then(write) : write());
}