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

🚄 perf: Linearize Conversation Import Lineage (#15881)

Danny Avilae43fed2ed400
diff --git a/api/server/utils/import/fork.js b/api/server/utils/import/fork.js
index 467aabc0de..b777eed80d 100644
--- a/api/server/utils/import/fork.js
+++ b/api/server/utils/import/fork.js
@@ -1,5 +1,5 @@
const { v4: uuidv4 } = require('uuid');
-const { withoutTraceRefs } = require('@librechat/api');
+const { cloneLineage, withoutTraceRefs, getAllMessagesUpToParent } = require('@librechat/api');
const { logger, tenantStorage } = require('@librechat/data-schemas');
const { EModelEndpoint, Constants, ForkOptions } = require('librechat-data-provider');
const { getConvo, getMessages, getSharedMessages } = require('~/models');
@@ -21,53 +21,12 @@ function cloneMessagesWithTimestamps(
importBatchBuilder,
{ detachSubagentRuntime = false } = {},
) {
- const idMapping = new Map();
-
- // First pass: create ID mapping and sort messages by parentMessageId
- const sortedMessages = [...messagesToClone].sort((a, b) => {
- if (a.parentMessageId === Constants.NO_PARENT) {
- return -1;
- }
- if (b.parentMessageId === Constants.NO_PARENT) {
- return 1;
- }
- return 0;
- });
-
- // Helper function to ensure date object
- const ensureDate = (dateValue) => {
- if (!dateValue) {
- return new Date();
- }
- return dateValue instanceof Date ? dateValue : new Date(dateValue);
- };
-
- // Second pass: clone messages while maintaining proper timestamps
- for (const message of sortedMessages) {
- const newMessageId = uuidv4();
- idMapping.set(message.messageId, newMessageId);
-
- const parentId =
- message.parentMessageId && message.parentMessageId !== Constants.NO_PARENT
- ? idMapping.get(message.parentMessageId)
- : Constants.NO_PARENT;
-
- // If this message has a parent, ensure its timestamp is after the parent's
- let createdAt = ensureDate(message.createdAt);
- if (parentId !== Constants.NO_PARENT) {
- const parentMessage = importBatchBuilder.messages.find((msg) => msg.messageId === parentId);
- if (parentMessage) {
- const parentDate = ensureDate(parentMessage.createdAt);
- if (createdAt <= parentDate) {
- createdAt = new Date(parentDate.getTime() + 1);
- }
- }
- }
-
+ const { entries, idMapping } = cloneLineage(messagesToClone, uuidv4);
+ for (const { source, messageId, parentMessageId, createdAt } of entries) {
const clonedMessage = {
- ...withoutTraceRefs(message),
- messageId: newMessageId,
- parentMessageId: parentId,
+ ...withoutTraceRefs(source),
+ messageId,
+ parentMessageId,
createdAt,
};
if (detachSubagentRuntime) {
@@ -189,48 +148,6 @@ async function forkConversation({
}
}
-/**
- * Retrieves all messages up to the root from the target message.
- * @param {TMessage[]} messages - The list of messages to search.
- * @param {string} targetMessageId - The ID of the target message.
- * @returns {TMessage[]} The list of messages up to the root from the target message.
- */
-function getAllMessagesUpToParent(messages, targetMessageId) {
- const targetMessage = messages.find((msg) => msg.messageId === targetMessageId);
- if (!targetMessage) {
- return [];
- }
-
- const pathToRoot = new Set();
- const visited = new Set();
- let current = targetMessage;
-
- while (current) {
- if (visited.has(current.messageId)) {
- break;
- }
-
- visited.add(current.messageId);
- pathToRoot.add(current.messageId);
-
- const currentParentId = current.parentMessageId ?? Constants.NO_PARENT;
- if (currentParentId === Constants.NO_PARENT) {
- break;
- }
-
- current = messages.find((msg) => msg.messageId === currentParentId);
- }
-
- // Include all messages that are in the path or whose parent is in the path
- // Exclude children of the target message
- return messages.filter(
- (msg) =>
- (pathToRoot.has(msg.messageId) && msg.messageId !== targetMessageId) ||
- (pathToRoot.has(msg.parentMessageId) && msg.parentMessageId !== targetMessageId) ||
- msg.messageId === targetMessageId,
- );
-}
-
/**
* Retrieves all messages up to the root from the target message and its neighbors.
* @param {TMessage[]} messages - The list of messages to search.
diff --git a/api/server/utils/import/importers-timestamp.spec.js b/api/server/utils/import/importers-timestamp.spec.js
index 268cc74c0d..90572edd2c 100644
--- a/api/server/utils/import/importers-timestamp.spec.js
+++ b/api/server/utils/import/importers-timestamp.spec.js
@@ -530,4 +530,119 @@ describe('Import Timestamp Ordering', () => {
);
});
});
+
+ describe('Large exports', () => {
+ const baseTime = 1700000000;
+ const chatGptNode = (parent, role) => ({
+ parent,
+ children: [],
+ message: {
+ author: { role },
+ create_time: baseTime,
+ content: { content_type: 'text', parts: [role] },
+ metadata: {},
+ },
+ });
+
+ /** These sizes import in a few hundred milliseconds; a per-message scan takes ten seconds or more. */
+ const importBudgetMs = 3000;
+
+ const importJson = async (jsonData) => {
+ const importBatchBuilder = new ImportBatchBuilder('user-123');
+ const startedAt = performance.now();
+ await getImporter(jsonData)(jsonData, 'user-123', () => importBatchBuilder);
+ return { messages: importBatchBuilder.messages, elapsedMs: performance.now() - startedAt };
+ };
+
+ test('imports a flat LibreChat export whose messages all name an absent parent', async () => {
+ const count = 60000;
+ const { messages, elapsedMs } = await importJson({
+ conversationId: 'large-flat',
+ title: 'Large flat export',
+ messages: Array.from({ length: count }, (_, index) => ({
+ messageId: `m${index}`,
+ parentMessageId: 'absent-root',
+ text: 'x',
+ sender: 'user',
+ isCreatedByUser: true,
+ })),
+ });
+
+ expect(elapsedMs).toBeLessThan(importBudgetMs);
+ expect(messages).toHaveLength(count);
+ });
+
+ test('orders a long LibreChat chain whose timestamps all collide', async () => {
+ const count = 60000;
+ const createdAt = '2024-01-01T00:00:00.000Z';
+ const { messages, elapsedMs } = await importJson({
+ conversationId: 'large-chain',
+ title: 'Large chain export',
+ messages: Array.from({ length: count }, (_, index) => ({
+ messageId: `m${index}`,
+ parentMessageId: index === 0 ? Constants.NO_PARENT : `m${index - 1}`,
+ text: 'x',
+ sender: 'user',
+ isCreatedByUser: true,
+ createdAt,
+ })),
+ });
+
+ expect(elapsedMs).toBeLessThan(importBudgetMs);
+ expect(messages).toHaveLength(count);
+ expect(messages[count - 1].parentMessageId).toBe(messages[count - 2].messageId);
+ expect(messages[count - 1].createdAt.getTime()).toBe(
+ new Date(createdAt).getTime() + count - 1,
+ );
+ });
+
+ test('orders a long ChatGPT branch listed deepest-first', async () => {
+ const count = 10000;
+ const mapping = {};
+ for (let depth = count - 1; depth >= 0; depth--) {
+ mapping[`n${depth}`] = chatGptNode(
+ depth === 0 ? null : `n${depth - 1}`,
+ depth % 2 ? 'assistant' : 'user',
+ );
+ }
+
+ const { messages, elapsedMs } = await importJson([
+ { title: 'Deep branch', create_time: baseTime, mapping },
+ ]);
+
+ const byId = new Map(messages.map((message) => [message.messageId, message]));
+ const root = messages.find((message) => message.parentMessageId === Constants.NO_PARENT);
+ const leaf = messages[0];
+ expect(elapsedMs).toBeLessThan(importBudgetMs);
+ expect(messages).toHaveLength(count);
+ expect(root.createdAt.getTime()).toBe(baseTime * 1000);
+ expect(leaf.createdAt.getTime()).toBe(baseTime * 1000 + count - 1);
+ expect(leaf.createdAt.getTime()).toBeGreaterThan(
+ byId.get(leaf.parentMessageId).createdAt.getTime(),
+ );
+ });
+
+ test('attaches many ChatGPT replies behind one long run of system messages', async () => {
+ const systemCount = 10000;
+ const replyCount = 10000;
+ const mapping = { root: chatGptNode(null, 'user') };
+ for (let index = 0; index < systemCount; index++) {
+ mapping[`s${index}`] = chatGptNode(index === 0 ? 'root' : `s${index - 1}`, 'system');
+ }
+ for (let index = 0; index < replyCount; index++) {
+ mapping[`r${index}`] = chatGptNode(`s${systemCount - 1}`, 'assistant');
+ }
+
+ const { messages, elapsedMs } = await importJson([
+ { title: 'System run', create_time: baseTime, mapping },
+ ]);
+
+ const root = messages.find((message) => message.parentMessageId === Constants.NO_PARENT);
+ expect(elapsedMs).toBeLessThan(importBudgetMs);
+ expect(messages).toHaveLength(replyCount + 1);
+ expect(messages.filter((message) => message.parentMessageId === root.messageId)).toHaveLength(
+ replyCount,
+ );
+ });
+ });
});
diff --git a/api/server/utils/import/importers.js b/api/server/utils/import/importers.js
index d1d2edd29d..d496749e5c 100644
--- a/api/server/utils/import/importers.js
+++ b/api/server/utils/import/importers.js
@@ -7,7 +7,12 @@ const {
stripMessageUIResourceMarkers,
} = require('@librechat/data-schemas');
const { EModelEndpoint, Constants, Tools, openAISettings } = require('librechat-data-provider');
-const { withoutTraceRefs } = require('@librechat/api');
+const {
+ withoutTraceRefs,
+ orderMessageLineage,
+ createChatGptLineage,
+ linkChatGptCitations,
+} = require('@librechat/api');
const { getEndpointsConfig } = require('~/server/services/Config');
const { createImportBatchBuilder } = require('./importBatchBuilder');
const { resolveImportDefaultModel } = require('./defaults');
@@ -445,86 +450,7 @@ function processConversation(conv, importBatchBuilder, requestUserId, defaultMod
}
}
- /**
- * Finds the nearest valid parent by traversing up through skippable messages
- * (system, reasoning_recap, thoughts). Uses iterative traversal to avoid
- * stack overflow on deep chains of skippable messages.
- *
- * @param {string} startId - The ID of the starting parent message.
- * @returns {string} The ID of the nearest valid parent message.
- */
- const findValidParent = (startId) => {
- const visited = new Set();
- let parentId = startId;
-
- while (parentId) {
- if (!messageMap.has(parentId) || visited.has(parentId)) {
- return Constants.NO_PARENT;
- }
- visited.add(parentId);
-
- const parentMapping = conv.mapping[parentId];
- if (!parentMapping?.message) {
- return Constants.NO_PARENT;
- }
-
- const contentType = parentMapping.message.content?.content_type;
- const shouldSkip =
- parentMapping.message.author?.role === 'system' ||
- contentType === 'reasoning_recap' ||
- contentType === 'thoughts';
-
- if (!shouldSkip) {
- return messageMap.get(parentId);
- }
-
- parentId = parentMapping.parent;
- }
-
- return Constants.NO_PARENT;
- };
-
- /**
- * Helper function to find thinking content from parent chain (thoughts messages)
- * @param {string} parentId - The ID of the parent message.
- * @param {Set} visited - Set of already-visited IDs to prevent cycles.
- * @returns {Array} The thinking content array (empty if not found).
- */
- const findThinkingContent = (parentId, visited = new Set()) => {
- // Guard against circular references in malformed imports
- if (!parentId || visited.has(parentId)) {
- return [];
- }
- visited.add(parentId);
-
- const parentMapping = conv.mapping[parentId];
- if (!parentMapping?.message) {
- return [];
- }
-
- const contentType = parentMapping.message.content?.content_type;
-
- // If this is a thoughts message, extract the thinking content
- if (contentType === 'thoughts') {
- const thoughts = parentMapping.message.content.thoughts || [];
- const thinkingText = thoughts
- .map((t) => t.content || t.summary || '')
- .filter(Boolean)
- .join('\n\n');
-
- if (thinkingText) {
- return [{ type: 'think', think: thinkingText }];
- }
- return [];
- }
-
- // If this is reasoning_recap, look at its parent for thoughts
- if (contentType === 'reasoning_recap') {
- return findThinkingContent(parentMapping.parent, visited);
- }
-
- return [];
- };
+ const lineage = createChatGptLineage(conv.mapping, messageMap);
// Create and save messages using the mapped IDs
const messages = [];
@@ -554,7 +480,7 @@ function processConversation(conv, importBatchBuilder, requestUserId, defaultMod
if (!newMessageId) {
continue;
}
- const parentMessageId = findValidParent(mapping.parent);
+ const parentMessageId = lineage.findValidParent(mapping.parent);
const messageText = formatMessageText(mapping.message);
@@ -593,7 +519,7 @@ function processConversation(conv, importBatchBuilder, requestUserId, defaultMod
// For assistant messages, check if there's thinking content in the parent chain
if (!isCreatedByUser) {
- const thinkingContent = findThinkingContent(mapping.parent);
+ const thinkingContent = lineage.findThinkingContent(mapping.parent);
if (thinkingContent.length > 0) {
// Combine thinking content with the text response
message.content = [...thinkingContent, { type: 'text', text: messageText }];
@@ -603,10 +529,7 @@ function processConversation(conv, importBatchBuilder, requestUserId, defaultMod
messages.push(message);
}
- const cycleDetected = adjustTimestampsForOrdering(messages);
- if (cycleDetected) {
- breakParentCycles(messages);
- }
+ orderMessageLineage(messages);
for (const message of messages) {
importBatchBuilder.saveMessage(message);
@@ -633,28 +556,7 @@ function processAssistantMessage(messageData, messageText) {
return messageText;
}
- const citations = messageData.metadata?.citations ?? [];
-
- const sortedCitations = [...citations].sort((a, b) => b.start_ix - a.start_ix);
-
- let result = messageText;
- for (const citation of sortedCitations) {
- if (
- !citation.metadata?.type ||
- citation.metadata.type !== 'webpage' ||
- typeof citation.start_ix !== 'number' ||
- typeof citation.end_ix !== 'number' ||
- citation.start_ix >= citation.end_ix
- ) {
- continue;
- }
-
- const replacement = ` ([${citation.metadata.title}](${citation.metadata.url}))`;
-
- result = result.slice(0, citation.start_ix) + replacement + result.slice(citation.end_ix);
- }
-
- return result;
+ return linkChatGptCitations(messageText, messageData.metadata?.citations);
}
/**
@@ -693,85 +595,4 @@ function formatMessageText(messageData) {
return messageText;
}
-/**
- * Adjusts message timestamps to ensure children always come after parents.
- * Messages are sorted by createdAt and buildTree expects parents to appear before children.
- * ChatGPT exports can have slight timestamp inversions (e.g., tool call results
- * arriving a few ms before their parent). Uses multiple passes to handle cascading adjustments.
- * Capped at N passes (where N = message count) to guarantee termination on cyclic graphs.
- *
- * @param {Array} messages - Array of message objects with messageId, parentMessageId, and createdAt.
- * @returns {boolean} True if cyclic parent relationships were detected.
- */
-function adjustTimestampsForOrdering(messages) {
- if (messages.length === 0) {
- return false;
- }
-
- const timestampMap = new Map();
- for (const msg of messages) {
- timestampMap.set(msg.messageId, msg.createdAt);
- }
-
- let hasChanges = true;
- let remainingPasses = messages.length;
- while (hasChanges && remainingPasses > 0) {
- hasChanges = false;
- remainingPasses--;
- for (const message of messages) {
- if (message.parentMessageId && message.parentMessageId !== Constants.NO_PARENT) {
- const parentTimestamp = timestampMap.get(message.parentMessageId);
- if (parentTimestamp && message.createdAt <= parentTimestamp) {
- message.createdAt = new Date(parentTimestamp.getTime() + 1);
- timestampMap.set(message.messageId, message.createdAt);
- hasChanges = true;
- }
- }
- }
- }
-
- const cycleDetected = remainingPasses === 0 && hasChanges;
- if (cycleDetected) {
- logger.warn(
- '[importers] Detected cyclic parent relationships while adjusting import timestamps',
- );
- }
- return cycleDetected;
-}
-
-/**
- * Severs cyclic parentMessageId back-edges so saved messages form a valid tree.
- * Walks each message's parent chain; if a message is visited twice, its parentMessageId
- * is set to NO_PARENT to break the cycle.
- *
- * @param {Array} messages - Array of message objects with messageId and parentMessageId.
- */
-function breakParentCycles(messages) {
- const parentLookup = new Map();
- for (const msg of messages) {
- parentLookup.set(msg.messageId, msg);
- }
-
- const settled = new Set();
- for (const message of messages) {
- const chain = new Set();
- let current = message;
- while (current && !settled.has(current.messageId)) {
- if (chain.has(current.messageId)) {
- current.parentMessageId = Constants.NO_PARENT;
- break;
- }
- chain.add(current.messageId);
- const parentId = current.parentMessageId;
- if (!parentId || parentId === Constants.NO_PARENT) {
- break;
- }
- current = parentLookup.get(parentId);
- }
- for (const id of chain) {
- settled.add(id);
- }
- }
-}
-
module.exports = { getImporter, processAssistantMessage };
diff --git a/api/server/utils/import/importers.spec.js b/api/server/utils/import/importers.spec.js
index aa71772de5..b9d945af94 100644
--- a/api/server/utils/import/importers.spec.js
+++ b/api/server/utils/import/importers.spec.js
@@ -1594,6 +1594,26 @@ describe('processAssistantMessage', () => {
});
});
+ test('should link tens of thousands of citations in one message', () => {
+ const count = 40000;
+ const marker = '【†】';
+ const span = `${'word '.repeat(19)}${marker}`;
+ const citations = Array.from({ length: count }, (_, index) => ({
+ start_ix: (index + 1) * span.length - marker.length,
+ end_ix: (index + 1) * span.length,
+ metadata: { type: 'webpage', title: 'Source', url: 'https://example.com' },
+ }));
+
+ const text = span.repeat(count);
+ const startedAt = performance.now();
+ const result = processAssistantMessage({ metadata: { citations } }, text);
+ const elapsedMs = performance.now() - startedAt;
+
+ expect(elapsedMs).toBeLessThan(1000);
+ expect(result).not.toContain(marker);
+ expect(result.split(' ([Source](https://example.com))')).toHaveLength(count + 1);
+ });
+
test('should handle potential ReDoS attack payloads', () => {
// Test with increasing input sizes to check for exponential behavior
const sizes = [32, 33, 34]; // Adding more sizes would increase test time
diff --git a/packages/api/src/conversations/chatgpt.spec.ts b/packages/api/src/conversations/chatgpt.spec.ts
new file mode 100644
index 0000000000..b6b6df9436
--- /dev/null
+++ b/packages/api/src/conversations/chatgpt.spec.ts
@@ -0,0 +1,219 @@
+import { Constants, ContentTypes } from 'librechat-data-provider';
+
+import type {
+ ChatGptMapping,
+ ChatGptCitation,
+ ChatGptMappingNode,
+ ChatGptExportContent,
+} from './chatgpt';
+import { createChatGptLineage, linkChatGptCitations } from './chatgpt';
+
+const node = (
+ parent: string | null,
+ role: string,
+ contentType: string,
+ extra: ChatGptExportContent = {},
+): ChatGptMappingNode => ({
+ parent,
+ message: { author: { role }, content: { content_type: contentType, ...extra } },
+});
+
+/** Export ids map to imported ids with an `imported-` prefix. */
+const importedIds = (mapping: ChatGptMapping): Map<string, string> =>
+ new Map(
+ Object.entries(mapping)
+ .filter(([, entry]) => entry?.message?.content?.content_type)
+ .map(([id]) => [id, `imported-${id}`]),
+ );
+
+const webpage = (start_ix: number, end_ix: number, title: string): ChatGptCitation => ({
+ start_ix,
+ end_ix,
+ metadata: { type: 'webpage', title, url: `https://example.com/${title}` },
+});
+
+describe('createChatGptLineage', () => {
+ describe('findValidParent', () => {
+ it('passes over system, reasoning-recap and thoughts ancestors', () => {
+ const mapping: ChatGptMapping = {
+ user: node(null, 'user', 'text'),
+ system: node('user', 'system', 'text'),
+ thoughts: node('system', 'assistant', 'thoughts'),
+ recap: node('thoughts', 'assistant', 'reasoning_recap'),
+ };
+ const lineage = createChatGptLineage(mapping, importedIds(mapping));
+
+ expect(lineage.findValidParent('recap')).toBe('imported-user');
+ expect(lineage.findValidParent('system')).toBe('imported-user');
+ expect(lineage.findValidParent('user')).toBe('imported-user');
+ });
+
+ it('roots a message whose ancestry is missing, empty or unmapped', () => {
+ const mapping: ChatGptMapping = {
+ empty: { parent: null, message: null },
+ system: node('empty', 'system', 'text'),
+ untyped: { parent: null, message: { author: { role: 'user' }, content: {} } },
+ };
+ const lineage = createChatGptLineage(mapping, importedIds(mapping));
+
+ expect(lineage.findValidParent(undefined)).toBe(Constants.NO_PARENT);
+ expect(lineage.findValidParent('absent')).toBe(Constants.NO_PARENT);
+ expect(lineage.findValidParent('system')).toBe(Constants.NO_PARENT);
+ expect(lineage.findValidParent('untyped')).toBe(Constants.NO_PARENT);
+ });
+
+ it('roots a message whose passed-over ancestors form a cycle, from any entry point', () => {
+ const mapping: ChatGptMapping = {
+ a: node('b', 'system', 'text'),
+ b: node('a', 'system', 'text'),
+ };
+ const lineage = createChatGptLineage(mapping, importedIds(mapping));
+
+ expect(lineage.findValidParent('a')).toBe(Constants.NO_PARENT);
+ expect(lineage.findValidParent('b')).toBe(Constants.NO_PARENT);
+ });
+
+ it('resolves many descendants of one long run of system messages', () => {
+ const depth = 20_000;
+ const mapping: Record<string, ChatGptMappingNode> = { root: node(null, 'user', 'text') };
+ for (let i = 0; i < depth; i++) {
+ mapping[`s${i}`] = node(i === 0 ? 'root' : `s${i - 1}`, 'system', 'text');
+ }
+ const lineage = createChatGptLineage(mapping, importedIds(mapping));
+
+ const parents = new Set<string>();
+ const startedAt = performance.now();
+ for (let i = 0; i < depth; i++) {
+ parents.add(lineage.findValidParent(`s${depth - 1}`));
+ }
+ const elapsedMs = performance.now() - startedAt;
+
+ expect(elapsedMs).toBeLessThan(1000);
+ expect([...parents]).toEqual(['imported-root']);
+ });
+ });
+
+ describe('findThinkingContent', () => {
+ it('reads thoughts through reasoning recaps', () => {
+ const mapping: ChatGptMapping = {
+ thoughts: node(null, 'assistant', 'thoughts', {
+ thoughts: [{ content: 'first' }, { summary: 'second' }, { content: '' }],
+ }),
+ recap: node('thoughts', 'assistant', 'reasoning_recap'),
+ };
+ const lineage = createChatGptLineage(mapping, importedIds(mapping));
+
+ expect(lineage.findThinkingContent('recap')).toEqual([
+ { type: ContentTypes.THINK, think: 'first\n\nsecond' },
+ ]);
+ });
+
+ it('returns a separate part for each response sharing the same thoughts', () => {
+ const mapping: ChatGptMapping = {
+ thoughts: node(null, 'assistant', 'thoughts', { thoughts: [{ content: 'shared' }] }),
+ };
+ const lineage = createChatGptLineage(mapping, importedIds(mapping));
+
+ const first = lineage.findThinkingContent('thoughts');
+ const second = lineage.findThinkingContent('thoughts');
+ expect(second).toEqual(first);
+ expect(second[0]).not.toBe(first[0]);
+ });
+
+ it('returns nothing for other ancestors, malformed thoughts and recap cycles', () => {
+ const mapping: ChatGptMapping = {
+ text: node(null, 'user', 'text'),
+ malformed: node(null, 'assistant', 'thoughts', { thoughts: null }),
+ a: node('b', 'assistant', 'reasoning_recap'),
+ b: node('a', 'assistant', 'reasoning_recap'),
+ };
+ const lineage = createChatGptLineage(mapping, importedIds(mapping));
+
+ expect(lineage.findThinkingContent('text')).toEqual([]);
+ expect(lineage.findThinkingContent('malformed')).toEqual([]);
+ expect(lineage.findThinkingContent('a')).toEqual([]);
+ expect(lineage.findThinkingContent(null)).toEqual([]);
+ });
+
+ it('follows a recap run deeper than the call stack', () => {
+ const depth = 100_000;
+ const mapping: Record<string, ChatGptMappingNode> = {
+ thoughts: node(null, 'assistant', 'thoughts', { thoughts: [{ content: 'deep' }] }),
+ };
+ for (let i = 0; i < depth; i++) {
+ mapping[`r${i}`] = node(i === 0 ? 'thoughts' : `r${i - 1}`, 'assistant', 'reasoning_recap');
+ }
+ const lineage = createChatGptLineage(mapping, importedIds(mapping));
+
+ expect(lineage.findThinkingContent(`r${depth - 1}`)).toEqual([
+ { type: ContentTypes.THINK, think: 'deep' },
+ ]);
+ const startedAt = performance.now();
+ for (let i = 0; i < 1000; i++) {
+ lineage.findThinkingContent(`r${depth - 1}`);
+ }
+ expect(performance.now() - startedAt).toBeLessThan(1000);
+ });
+ });
+});
+
+describe('linkChatGptCitations', () => {
+ const text = 'Intro 【1†a】 middle 【2†b】 end';
+ const first = text.indexOf('【1');
+ const second = text.indexOf('【2');
+
+ it('replaces adjacent and separated markers in any listed order', () => {
+ const citations = [webpage(second, second + 5, 'b'), webpage(first, first + 5, 'a')];
+
+ expect(linkChatGptCitations(text, citations)).toBe(
+ 'Intro ([a](https://example.com/a)) middle ([b](https://example.com/b)) end',
+ );
+ });
+
+ it('clamps an end index past the text as slice would', () => {
+ const tail = 'Tail 【9†z】';
+ expect(linkChatGptCitations(tail, [webpage(5, tail.length + 1, 'z')])).toBe(
+ 'Tail ([z](https://example.com/z))',
+ );
+ });
+
+ it('leaves out non-webpage, inverted, fractional, negative and overlapping citations', () => {
+ const citations: Array<ChatGptCitation | null> = [
+ null,
+ { start_ix: first, end_ix: first + 5, metadata: { type: 'file', title: 'f', url: 'u' } },
+ webpage(second + 5, second, 'inverted'),
+ webpage(first + 0.5, first + 5, 'fractional'),
+ webpage(-3, 2, 'negative'),
+ webpage(second, second + 5, 'b'),
+ webpage(second - 2, second + 1, 'overlap'),
+ ];
+
+ expect(linkChatGptCitations(text, citations)).toBe(
+ 'Intro 【1†a】 middle ([b](https://example.com/b)) end',
+ );
+ });
+
+ it('returns the text unchanged when there is nothing to link', () => {
+ expect(linkChatGptCitations(text, undefined)).toBe(text);
+ expect(linkChatGptCitations(text, [])).toBe(text);
+ expect(linkChatGptCitations('', [webpage(0, 1, 'a')])).toBe('');
+ });
+
+ it('links tens of thousands of citations in one message', () => {
+ const count = 20_000;
+ const marker = '【†】';
+ const body = `${'word '.repeat(19)}${marker}`.repeat(count);
+ const span = body.length / count;
+ const citations = Array.from({ length: count }, (_, index) =>
+ webpage((index + 1) * span - marker.length, (index + 1) * span, 's'),
+ );
+
+ const startedAt = performance.now();
+ const linked = linkChatGptCitations(body, citations);
+ const elapsedMs = performance.now() - startedAt;
+
+ expect(elapsedMs).toBeLessThan(1000);
+ expect(linked).not.toContain(marker);
+ expect(linked.split(' ([s](https://example.com/s))')).toHaveLength(count + 1);
+ });
+});
diff --git a/packages/api/src/conversations/chatgpt.ts b/packages/api/src/conversations/chatgpt.ts
new file mode 100644
index 0000000000..b46602d9d0
--- /dev/null
+++ b/packages/api/src/conversations/chatgpt.ts
@@ -0,0 +1,196 @@
+import { Constants, ContentTypes } from 'librechat-data-provider';
+import type { Agents } from 'librechat-data-provider';
+
+export interface ChatGptThought {
+ content?: string | null;
+ summary?: string | null;
+}
+
+export interface ChatGptExportContent {
+ content_type?: string | null;
+ thoughts?: ChatGptThought[] | null;
+}
+
+export interface ChatGptExportMessage {
+ author?: { role?: string | null } | null;
+ content?: ChatGptExportContent | null;
+}
+
+export interface ChatGptMappingNode {
+ message?: ChatGptExportMessage | null;
+ parent?: string | null;
+}
+
+export type ChatGptMapping = Readonly<Record<string, ChatGptMappingNode | undefined>>;
+
+export interface ChatGptCitationMetadata {
+ type?: string;
+ title?: string;
+ url?: string;
+}
+
+export interface ChatGptCitation {
+ start_ix?: number;
+ end_ix?: number;
+ metadata?: ChatGptCitationMetadata | null;
+}
+
+type LinkableCitation = ChatGptCitation & {
+ start_ix: number;
+ end_ix: number;
+ metadata: ChatGptCitationMetadata;
+};
+
+export interface ChatGptLineage {
+ /** Nearest imported ancestor, passing over system, reasoning-recap and thoughts nodes. */
+ findValidParent: (startId: string | null | undefined) => string;
+ /** Reasoning from the thoughts node behind a response, reached through any reasoning recaps. */
+ findThinkingContent: (parentId: string | null | undefined) => Agents.ReasoningContentText[];
+}
+
+const THOUGHTS = 'thoughts';
+const REASONING_RECAP = 'reasoning_recap';
+
+function isPassedOver(message: ChatGptExportMessage): boolean {
+ const contentType = message.content?.content_type;
+ return (
+ message.author?.role === 'system' || contentType === REASONING_RECAP || contentType === THOUGHTS
+ );
+}
+
+function joinThoughts(thoughts: ChatGptThought[] | null | undefined): string {
+ if (!Array.isArray(thoughts)) {
+ return '';
+ }
+ return thoughts
+ .map((thought) => thought?.content || thought?.summary || '')
+ .filter(Boolean)
+ .join('\n\n');
+}
+
+/**
+ * Resolves parent and reasoning ancestry for one exported ChatGPT conversation.
+ * Every node's answer is memoized when its walk finishes, so a long run of passed-over
+ * ancestors is traversed once for the whole conversation rather than once per descendant.
+ * `messageIds` maps export node ids to imported message ids and must not change afterward.
+ */
+export function createChatGptLineage(
+ mapping: ChatGptMapping,
+ messageIds: ReadonlyMap<string, string>,
+): ChatGptLineage {
+ const validParents = new Map<string, string>();
+ const thinkingTexts = new Map<string, string>();
+
+ const findValidParent = (startId: string | null | undefined): string => {
+ const walked = new Set<string>();
+ let resolved: string = Constants.NO_PARENT;
+ let nodeId = startId;
+ while (nodeId) {
+ const known = validParents.get(nodeId);
+ if (known !== undefined) {
+ resolved = known;
+ break;
+ }
+ const node = mapping[nodeId];
+ if (!messageIds.has(nodeId) || walked.has(nodeId) || !node?.message) {
+ break;
+ }
+ walked.add(nodeId);
+ if (!isPassedOver(node.message)) {
+ resolved = messageIds.get(nodeId) ?? Constants.NO_PARENT;
+ break;
+ }
+ nodeId = node.parent;
+ }
+ for (const id of walked) {
+ validParents.set(id, resolved);
+ }
+ return resolved;
+ };
+
+ const findThinkingText = (startId: string | null | undefined): string => {
+ const walked = new Set<string>();
+ let text = '';
+ let nodeId = startId;
+ while (nodeId) {
+ const known = thinkingTexts.get(nodeId);
+ if (known !== undefined) {
+ text = known;
+ break;
+ }
+ const node = mapping[nodeId];
+ if (walked.has(nodeId) || !node?.message) {
+ break;
+ }
+ walked.add(nodeId);
+ const content = node.message.content;
+ if (content?.content_type === THOUGHTS) {
+ text = joinThoughts(content.thoughts);
+ break;
+ }
+ if (content?.content_type !== REASONING_RECAP) {
+ break;
+ }
+ nodeId = node.parent;
+ }
+ for (const id of walked) {
+ thinkingTexts.set(id, text);
+ }
+ return text;
+ };
+
+ return {
+ findValidParent,
+ findThinkingContent: (parentId) => {
+ const think = findThinkingText(parentId);
+ return think ? [{ type: ContentTypes.THINK, think }] : [];
+ },
+ };
+}
+
+const isIndex = (value: number | undefined): value is number => Number.isInteger(value);
+
+function isLinkableCitation(
+ citation: ChatGptCitation | null | undefined,
+): citation is LinkableCitation {
+ if (citation?.metadata?.type !== 'webpage') {
+ return false;
+ }
+ const { start_ix: start, end_ix: end } = citation;
+ return isIndex(start) && isIndex(end) && start >= 0 && start < end;
+}
+
+/**
+ * Replaces webpage citation markers with Markdown links in a single pass over the text.
+ * Citations apply from the end of the text backward, with indices past the end clamped to it
+ * as `String.prototype.slice` would; a citation overlapping one already applied is left out.
+ */
+export function linkChatGptCitations(
+ text: string,
+ citations: readonly (ChatGptCitation | null | undefined)[] | null | undefined,
+): string {
+ if (!text || !Array.isArray(citations)) {
+ return text;
+ }
+
+ const linkable = citations.filter(isLinkableCitation).sort((a, b) => b.start_ix - a.start_ix);
+ const pieces: string[] = [];
+ let boundary = text.length;
+ for (const citation of linkable) {
+ const end = Math.min(citation.end_ix, text.length);
+ if (end > boundary) {
+ continue;
+ }
+ pieces.push(
+ text.slice(end, boundary),
+ ` ([${citation.metadata.title}](${citation.metadata.url}))`,
+ );
+ boundary = Math.min(citation.start_ix, text.length);
+ }
+
+ if (pieces.length === 0) {
+ return text;
+ }
+ pieces.push(text.slice(0, boundary));
+ return pieces.reverse().join('');
+}
diff --git a/packages/api/src/conversations/index.ts b/packages/api/src/conversations/index.ts
index 0795f87e5d..80329340be 100644
--- a/packages/api/src/conversations/index.ts
+++ b/packages/api/src/conversations/index.ts
@@ -1,2 +1,4 @@
export * from './archive';
+export * from './chatgpt';
export * from './import';
+export * from './lineage';
diff --git a/packages/api/src/conversations/lineage.spec.ts b/packages/api/src/conversations/lineage.spec.ts
new file mode 100644
index 0000000000..612570acbc
--- /dev/null
+++ b/packages/api/src/conversations/lineage.spec.ts
@@ -0,0 +1,282 @@
+import { logger } from '@librechat/data-schemas';
+import { Constants } from 'librechat-data-provider';
+
+import type { LineageMessage } from './lineage';
+import {
+ cloneLineage,
+ breakParentCycles,
+ orderMessageLineage,
+ orderParentTimestamps,
+ getAllMessagesUpToParent,
+} from './lineage';
+
+const BASE = Date.UTC(2024, 0, 1);
+const ROOT: string = Constants.NO_PARENT;
+
+const at = (offset: number): Date => new Date(BASE + offset);
+
+const message = (messageId: string, parentMessageId: string, offset = 0): LineageMessage => ({
+ messageId,
+ parentMessageId,
+ createdAt: at(offset),
+});
+
+const timeOf = (messages: LineageMessage[], messageId: string): number =>
+ messages.find((entry) => entry.messageId === messageId)?.createdAt.getTime() ?? Number.NaN;
+
+/** Lists a chain deepest-first, the order that forces one pass per level on a naive fixed point. */
+const reverseChain = (length: number): LineageMessage[] =>
+ Array.from({ length }, (_, index) => {
+ const depth = length - 1 - index;
+ return message(`m${depth}`, depth === 0 ? Constants.NO_PARENT : `m${depth - 1}`);
+ });
+
+describe('breakParentCycles', () => {
+ it('leaves a forest untouched', () => {
+ const messages = [
+ message('a', Constants.NO_PARENT),
+ message('b', 'a'),
+ message('c', 'a'),
+ message('d', 'missing'),
+ ];
+
+ expect(breakParentCycles(messages)).toBe(false);
+ expect(messages.map((entry) => entry.parentMessageId)).toEqual([
+ Constants.NO_PARENT,
+ 'a',
+ 'a',
+ 'missing',
+ ]);
+ });
+
+ it('severs the link that closes a two-message cycle', () => {
+ const messages = [message('a', 'b'), message('b', 'a')];
+
+ expect(breakParentCycles(messages)).toBe(true);
+ expect(messages[0].parentMessageId).toBe(Constants.NO_PARENT);
+ expect(messages[1].parentMessageId).toBe('a');
+ });
+
+ it('severs a self-parented message', () => {
+ const messages = [message('a', 'a')];
+
+ expect(breakParentCycles(messages)).toBe(true);
+ expect(messages[0].parentMessageId).toBe(Constants.NO_PARENT);
+ });
+
+ it('keeps the tail that leads into a cycle attached to it', () => {
+ const messages = [message('tail', 'a'), message('a', 'b'), message('b', 'a')];
+
+ expect(breakParentCycles(messages)).toBe(true);
+ expect(messages.map((entry) => entry.parentMessageId)).toEqual(['a', Constants.NO_PARENT, 'a']);
+ });
+});
+
+describe('orderParentTimestamps', () => {
+ it('moves a child that sorts at or before its parent to one millisecond after it', () => {
+ const messages = [message('parent', Constants.NO_PARENT, 100), message('child', 'parent', 50)];
+
+ orderParentTimestamps(messages);
+
+ expect(timeOf(messages, 'child')).toBe(BASE + 101);
+ expect(timeOf(messages, 'parent')).toBe(BASE + 100);
+ });
+
+ it('keeps a child that already sorts after its parent', () => {
+ const messages = [message('parent', Constants.NO_PARENT, 100), message('child', 'parent', 500)];
+
+ orderParentTimestamps(messages);
+
+ expect(timeOf(messages, 'child')).toBe(BASE + 500);
+ });
+
+ it('cascades through descendants regardless of listing order', () => {
+ const messages = [
+ message('grandchild', 'child', 0),
+ message('child', 'parent', 0),
+ message('sibling', 'parent', 300),
+ message('parent', Constants.NO_PARENT, 200),
+ ];
+
+ orderParentTimestamps(messages);
+
+ expect(timeOf(messages, 'parent')).toBe(BASE + 200);
+ expect(timeOf(messages, 'child')).toBe(BASE + 201);
+ expect(timeOf(messages, 'grandchild')).toBe(BASE + 202);
+ expect(timeOf(messages, 'sibling')).toBe(BASE + 300);
+ });
+
+ it('does not adjust a message whose parent is not in the set', () => {
+ const messages = [message('orphan', 'missing', 0)];
+
+ orderParentTimestamps(messages);
+
+ expect(timeOf(messages, 'orphan')).toBe(BASE);
+ });
+
+ it('does not propagate from an invalid parent timestamp', () => {
+ const parent = message('parent', Constants.NO_PARENT);
+ parent.createdAt = new Date(Number.NaN);
+ const messages = [parent, message('child', 'parent', 0)];
+
+ orderParentTimestamps(messages);
+
+ expect(timeOf(messages, 'child')).toBe(BASE);
+ });
+
+ it('orders a deep chain listed deepest-first in a single pass', () => {
+ const length = 20_000;
+ const messages = reverseChain(length);
+
+ const startedAt = performance.now();
+ orderParentTimestamps(messages);
+ const elapsedMs = performance.now() - startedAt;
+
+ expect(elapsedMs).toBeLessThan(1000);
+ expect(timeOf(messages, 'm0')).toBe(BASE);
+ expect(timeOf(messages, `m${length - 1}`)).toBe(BASE + length - 1);
+ });
+});
+
+describe('orderMessageLineage', () => {
+ it('breaks cycles before ordering and reports them once', () => {
+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
+ const messages = [message('a', 'b', 10), message('b', 'a', 10), message('c', 'b', 0)];
+
+ orderMessageLineage(messages);
+
+ expect(warn).toHaveBeenCalledTimes(1);
+ expect(warn).toHaveBeenCalledWith(expect.stringContaining('cyclic parent relationships'));
+ expect(messages.map((entry) => entry.parentMessageId)).toEqual([Constants.NO_PARENT, 'a', 'b']);
+ expect(timeOf(messages, 'a')).toBe(BASE + 10);
+ expect(timeOf(messages, 'b')).toBe(BASE + 11);
+ expect(timeOf(messages, 'c')).toBe(BASE + 12);
+ warn.mockRestore();
+ });
+
+ it('stays silent for an acyclic lineage', () => {
+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
+
+ orderMessageLineage(reverseChain(3));
+
+ expect(warn).not.toHaveBeenCalled();
+ warn.mockRestore();
+ });
+});
+
+describe('cloneLineage', () => {
+ const sequentialIds = () => {
+ let next = 0;
+ return () => `clone-${++next}`;
+ };
+
+ it('clones roots first and re-links each child to its parent clone', () => {
+ const { entries, idMapping } = cloneLineage(
+ [
+ { messageId: 'child', parentMessageId: 'root', createdAt: '2024-01-01T00:00:05.000Z' },
+ { messageId: 'root', parentMessageId: ROOT, createdAt: new Date(BASE) },
+ ],
+ sequentialIds(),
+ );
+
+ expect(entries.map((entry) => entry.source.messageId)).toEqual(['root', 'child']);
+ expect(idMapping).toEqual(
+ new Map([
+ ['root', 'clone-1'],
+ ['child', 'clone-2'],
+ ]),
+ );
+ expect(entries[0].parentMessageId).toBe(Constants.NO_PARENT);
+ expect(entries[1].parentMessageId).toBe('clone-1');
+ expect(entries[1].createdAt.getTime()).toBe(BASE + 5000);
+ });
+
+ it('moves a clone that sorts at or before its parent clone to one millisecond after it', () => {
+ const { entries } = cloneLineage(
+ [
+ { messageId: 'root', parentMessageId: ROOT, createdAt: at(100) },
+ { messageId: 'child', parentMessageId: 'root', createdAt: at(100) },
+ { messageId: 'grandchild', parentMessageId: 'child', createdAt: at(0) },
+ ],
+ sequentialIds(),
+ );
+
+ expect(entries.map((entry) => entry.createdAt.getTime())).toEqual([
+ BASE + 100,
+ BASE + 101,
+ BASE + 102,
+ ]);
+ });
+
+ it('leaves the parent link undefined when the parent is cloned later or absent', () => {
+ const { entries } = cloneLineage(
+ [
+ { messageId: 'early', parentMessageId: 'late', createdAt: at(0) },
+ { messageId: 'late', parentMessageId: 'missing', createdAt: at(10) },
+ ],
+ sequentialIds(),
+ );
+
+ expect(entries.map((entry) => entry.parentMessageId)).toEqual([undefined, undefined]);
+ expect(entries.map((entry) => entry.createdAt.getTime())).toEqual([BASE, BASE + 10]);
+ });
+
+ it('stamps a missing timestamp with the current time', () => {
+ const before = Date.now();
+ const { entries } = cloneLineage(
+ [{ messageId: 'root', parentMessageId: ROOT }],
+ sequentialIds(),
+ );
+
+ expect(entries[0].createdAt.getTime()).toBeGreaterThanOrEqual(before);
+ });
+});
+
+describe('getAllMessagesUpToParent', () => {
+ const tree = [
+ { messageId: 'root', parentMessageId: ROOT },
+ { messageId: 'a', parentMessageId: 'root' },
+ { messageId: 'b', parentMessageId: 'root' },
+ { messageId: 'a1', parentMessageId: 'a' },
+ { messageId: 'a2', parentMessageId: 'a' },
+ { messageId: 'a1x', parentMessageId: 'a1' },
+ { messageId: 'b1', parentMessageId: 'b' },
+ ];
+
+ it('returns the path to the root with every sibling along it, but not the target children', () => {
+ expect(getAllMessagesUpToParent(tree, 'a1').map((entry) => entry.messageId)).toEqual([
+ 'root',
+ 'a',
+ 'b',
+ 'a1',
+ 'a2',
+ ]);
+ });
+
+ it('returns nothing for an unknown target and stops on a parent cycle', () => {
+ expect(getAllMessagesUpToParent(tree, 'unknown')).toEqual([]);
+ const cyclic = [
+ { messageId: 'x', parentMessageId: 'y' },
+ { messageId: 'y', parentMessageId: 'x' },
+ ];
+ expect(getAllMessagesUpToParent(cyclic, 'x').map((entry) => entry.messageId)).toEqual([
+ 'x',
+ 'y',
+ ]);
+ });
+
+ it('walks a deep chain from its leaf in one pass', () => {
+ const length = 100_000;
+ const chain = Array.from({ length }, (_, index) => ({
+ messageId: `m${index}`,
+ parentMessageId: index === 0 ? ROOT : `m${index - 1}`,
+ }));
+
+ const startedAt = performance.now();
+ const branch = getAllMessagesUpToParent(chain, `m${length - 1}`);
+ const elapsedMs = performance.now() - startedAt;
+
+ expect(elapsedMs).toBeLessThan(1000);
+ expect(branch).toHaveLength(length);
+ });
+});
diff --git a/packages/api/src/conversations/lineage.ts b/packages/api/src/conversations/lineage.ts
new file mode 100644
index 0000000000..65d2b2500c
--- /dev/null
+++ b/packages/api/src/conversations/lineage.ts
@@ -0,0 +1,214 @@
+import { logger } from '@librechat/data-schemas';
+import { Constants } from 'librechat-data-provider';
+
+/** The identity, parent link and timestamp of a message whose lineage is being ordered. */
+export interface LineageMessage {
+ messageId: string;
+ parentMessageId?: string | null;
+ createdAt: Date;
+}
+
+/** A message as it is read before cloning, with the timestamp still in its stored form. */
+export interface LineageSource {
+ messageId: string;
+ parentMessageId?: string | null;
+ createdAt?: Date | string | number | null;
+}
+
+/** A source message's clone identity: its new id, re-linked parent and ordered timestamp. */
+export interface ClonedLineageEntry<T extends LineageSource> {
+ source: T;
+ messageId: string;
+ /** Undefined when the source's parent had not been cloned yet in clone order. */
+ parentMessageId: string | undefined;
+ createdAt: Date;
+}
+
+export interface ClonedLineage<T extends LineageSource> {
+ entries: ClonedLineageEntry<T>[];
+ /** Source message id to cloned message id. */
+ idMapping: Map<string, string>;
+}
+
+function indexById<T extends LineageMessage>(messages: readonly T[]): Map<string, T> {
+ const byId = new Map<string, T>();
+ for (const message of messages) {
+ byId.set(message.messageId, message);
+ }
+ return byId;
+}
+
+function parentOf<T extends LineageMessage>(message: T, byId: Map<string, T>): T | undefined {
+ const { parentMessageId } = message;
+ if (!parentMessageId || parentMessageId === Constants.NO_PARENT) {
+ return undefined;
+ }
+ return byId.get(parentMessageId);
+}
+
+/**
+ * Severs the parent link that closes each cycle so the messages form a forest.
+ * Every message joins at most one walk, so the pass is linear in the message count.
+ * @returns Whether any cycle was found.
+ */
+export function breakParentCycles<T extends LineageMessage>(messages: readonly T[]): boolean {
+ const byId = indexById(messages);
+ const settled = new Set<T>();
+ let cycleFound = false;
+
+ for (const message of messages) {
+ const chain = new Set<T>();
+ let current: T | undefined = message;
+ while (current != null && !settled.has(current)) {
+ if (chain.has(current)) {
+ current.parentMessageId = Constants.NO_PARENT;
+ cycleFound = true;
+ break;
+ }
+ chain.add(current);
+ current = parentOf(current, byId);
+ }
+ for (const member of chain) {
+ settled.add(member);
+ }
+ }
+
+ return cycleFound;
+}
+
+/**
+ * Moves each child's `createdAt` to one millisecond after its parent's whenever the child
+ * would otherwise sort at or before it. Each chain is resolved once, downward from its
+ * nearest settled ancestor, so the pass is linear in the message count. A cycle that
+ * remains is treated as rooted where the walk re-entered it.
+ */
+export function orderParentTimestamps<T extends LineageMessage>(messages: readonly T[]): void {
+ const byId = indexById(messages);
+ const settled = new Set<T>();
+
+ for (const message of messages) {
+ const chain: T[] = [];
+ const pending = new Set<T>();
+ let current: T | undefined = message;
+ while (current != null && !settled.has(current) && !pending.has(current)) {
+ chain.push(current);
+ pending.add(current);
+ current = parentOf(current, byId);
+ }
+
+ let parentCreatedAt = current != null && settled.has(current) ? current.createdAt : undefined;
+ for (let i = chain.length - 1; i >= 0; i--) {
+ const member = chain[i];
+ if (parentCreatedAt != null && member.createdAt <= parentCreatedAt) {
+ member.createdAt = new Date(parentCreatedAt.getTime() + 1);
+ }
+ parentCreatedAt = member.createdAt;
+ settled.add(member);
+ }
+ }
+}
+
+/**
+ * Makes imported messages a forest whose children sort after their parents:
+ * cyclic parent links are severed first, then timestamps are ordered in one pass.
+ */
+export function orderMessageLineage<T extends LineageMessage>(messages: readonly T[]): void {
+ if (breakParentCycles(messages)) {
+ logger.warn(
+ '[importers] Detected cyclic parent relationships while adjusting import timestamps',
+ );
+ }
+ orderParentTimestamps(messages);
+}
+
+const toDate = (value: LineageSource['createdAt']): Date => {
+ if (!value) {
+ return new Date();
+ }
+ return value instanceof Date ? value : new Date(value);
+};
+
+/**
+ * Assigns each message a new id, re-links it to its parent's clone and moves its timestamp
+ * after that clone's. Root messages are cloned first; a message whose parent is cloned later
+ * keeps an undefined parent link, as the caller's persistence decides where it attaches.
+ */
+export function cloneLineage<T extends LineageSource>(
+ messages: readonly T[],
+ createId: () => string,
+): ClonedLineage<T> {
+ const idMapping = new Map<string, string>();
+ const clonedCreatedAt = new Map<string, Date>();
+ const ordered = [...messages].sort((a, b) => {
+ if (a.parentMessageId === Constants.NO_PARENT) {
+ return -1;
+ }
+ if (b.parentMessageId === Constants.NO_PARENT) {
+ return 1;
+ }
+ return 0;
+ });
+
+ const entries = ordered.map((source): ClonedLineageEntry<T> => {
+ const messageId = createId();
+ idMapping.set(source.messageId, messageId);
+
+ const parentMessageId =
+ source.parentMessageId && source.parentMessageId !== Constants.NO_PARENT
+ ? idMapping.get(source.parentMessageId)
+ : Constants.NO_PARENT;
+
+ let createdAt = toDate(source.createdAt);
+ const parentCreatedAt =
+ parentMessageId == null ? undefined : clonedCreatedAt.get(parentMessageId);
+ if (parentCreatedAt != null && createdAt <= parentCreatedAt) {
+ createdAt = new Date(parentCreatedAt.getTime() + 1);
+ }
+ clonedCreatedAt.set(messageId, createdAt);
+
+ return { source, messageId, parentMessageId, createdAt };
+ });
+
+ return { entries, idMapping };
+}
+
+/**
+ * Retrieves the target message, its ancestors up to the root, and every sibling along that
+ * path, excluding the target's own children. The first message listed under an id wins.
+ */
+export function getAllMessagesUpToParent<T extends Omit<LineageSource, 'createdAt'>>(
+ messages: readonly T[],
+ targetMessageId: string,
+): T[] {
+ const messagesById = new Map<string, T>();
+ for (const message of messages) {
+ if (!messagesById.has(message.messageId)) {
+ messagesById.set(message.messageId, message);
+ }
+ }
+
+ const targetMessage = messagesById.get(targetMessageId);
+ if (!targetMessage) {
+ return [];
+ }
+
+ const pathToRoot = new Set<string>();
+ let current: T | undefined = targetMessage;
+ while (current != null && !pathToRoot.has(current.messageId)) {
+ pathToRoot.add(current.messageId);
+ const parentId: string = current.parentMessageId ?? Constants.NO_PARENT;
+ if (parentId === Constants.NO_PARENT) {
+ break;
+ }
+ current = messagesById.get(parentId);
+ }
+
+ return messages.filter(
+ (message) =>
+ message.messageId === targetMessageId ||
+ (pathToRoot.has(message.messageId) && message.messageId !== targetMessageId) ||
+ (message.parentMessageId != null &&
+ pathToRoot.has(message.parentMessageId) &&
+ message.parentMessageId !== targetMessageId),
+ );
+}