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: Index Hot Lookups and Fix the Message Cursor (#17464)

Marco Berettac81e244afdba
diff --git a/api/server/routes/__tests__/messages-get.spec.js b/api/server/routes/__tests__/messages-get.spec.js
index 24069625e2..daec00efe8 100644
--- a/api/server/routes/__tests__/messages-get.spec.js
+++ b/api/server/routes/__tests__/messages-get.spec.js
@@ -59,6 +59,12 @@ jest.mock('@librechat/api', () => {
/** The real helper, without loading the rest of the package this suite mocks around. */
withoutTraceRefs: jest.requireActual('../../../../packages/api/src/langfuse/trace.ts')
.withoutTraceRefs,
+ /** Mirrors the real parse (default 25, ceiling 1000) without loading the config service. */
+ awaitPageSize: jest.fn((pageSize) => pageSize),
+ resolveMessagesPageSize: jest.fn(async (_user, raw) => {
+ const parsed = parseInt(String(raw), 10);
+ return Number.isFinite(parsed) && parsed > 0 ? Math.min(parsed, 1000) : 25;
+ }),
createPrivateTextView: jest.fn(() => (_req, _res, next) => next()),
stripPrivateMessageFields: jest.requireActual(
'../../../../packages/api/src/protection/private/view',
@@ -613,7 +619,7 @@ describe('message route conversation ownership filters', () => {
name: 'capped',
query: `search=needle&pageSize=${MEILI_SEARCH_LIMIT + 1}`,
searchLimit: MEILI_SEARCH_LIMIT,
- conversationLimit: MEILI_SEARCH_LIMIT + 1,
+ conversationLimit: MEILI_SEARCH_LIMIT,
},
{
name: 'invalid',
diff --git a/api/server/routes/messages.js b/api/server/routes/messages.js
index 851f8b8dae..24430c390e 100644
--- a/api/server/routes/messages.js
+++ b/api/server/routes/messages.js
@@ -34,6 +34,8 @@ const {
createToolCallPartHandler,
createSubagentAttachmentCallsHandler,
rejectToolCallPreviewWrites,
+ resolveMessagesPageSize,
+ awaitPageSize,
withMessageToolCallPreviews,
} = require('@librechat/api');
const subagentThreadTaskStore = require('~/server/services/Endpoints/agents/subagentThreadStore');
@@ -132,8 +134,8 @@ router.get('/', async (req, res) => {
messageId,
search,
} = req.query;
- const parsedPageSize = parseInt(pageSizeRaw, 10);
- const pageSize = Number.isFinite(parsedPageSize) && parsedPageSize > 0 ? parsedPageSize : 25;
+ /** Starts beside the ownership read; it never rejects and falls back to the default ceiling. */
+ const pageSizeRead = resolveMessagesPageSize(req.user, pageSizeRaw, toolCallPreviewDeps);
let response;
const sortField = ['endpoint', 'createdAt', 'updatedAt'].includes(sortBy)
@@ -145,6 +147,7 @@ router.get('/', async (req, res) => {
const previewToolCalls = prepareToolCallPreviews(req, toolCallPreviewDeps);
if (typeof conversationId === 'string') {
const ownershipRead = db.getConvoOwnership(user, conversationId);
+ const pageSize = await awaitPageSize(pageSizeRead, ownershipRead);
/** Client-facing reads never expose server-private fields such as `contextMeta`. */
const messageRead = messageId
? db.getMessages({ conversationId, messageId, user }, CLIENT_MESSAGE_SELECT)
@@ -189,6 +192,7 @@ router.get('/', async (req, res) => {
messages: await previewToolCalls(messageResult.value.messages),
};
} else if (search) {
+ const pageSize = await pageSizeRead;
const searchResults = await db.searchMessages(
search,
{
diff --git a/e2e/specs/mock/scenarios/message-cursor.spec.ts b/e2e/specs/mock/scenarios/message-cursor.spec.ts
new file mode 100644
index 0000000000..a76e7f54c7
--- /dev/null
+++ b/e2e/specs/mock/scenarios/message-cursor.spec.ts
@@ -0,0 +1,89 @@
+import { randomUUID } from 'node:crypto';
+import { expect, test } from '@playwright/test';
+import { getE2EUser } from '../../../setup/user';
+import {
+ deleteConversations,
+ deleteMessagesByConversation,
+ seedConversations,
+ withMongo,
+} from '../db';
+import { NEW_CHAT_PATH, getAccessToken, requestJson } from '../helpers';
+
+type Page = { messages: { messageId: string; _id?: string }[]; nextCursor: string | null };
+
+async function seedTied(conversationId: string, count: number): Promise<string[]> {
+ const at = new Date('2026-01-01T00:00:00.123Z');
+ await seedConversations(getE2EUser().email, [{ conversationId, title: 'cursor', updatedAt: at }]);
+ return withMongo(async (db) => {
+ const user = await db.collection('users').findOne({ email: getE2EUser().email });
+ const rows = Array.from({ length: count }, (_, index) => ({
+ messageId: `cursor-${index}-${randomUUID()}`,
+ conversationId,
+ user: String(user?._id),
+ text: `message ${index}`,
+ sender: 'User',
+ isCreatedByUser: false,
+ createdAt: at,
+ updatedAt: at,
+ __v: 0,
+ }));
+ await db.collection('messages').insertMany(rows);
+ return rows.map((row) => row.messageId);
+ });
+}
+
+test.describe('message cursor and page size', () => {
+ const conversationIds: string[] = [];
+ test.afterEach(async () => {
+ await deleteMessagesByConversation(conversationIds);
+ await deleteConversations(conversationIds);
+ conversationIds.length = 0;
+ });
+
+ test('@scenario:message-pages-share-timestamp-without-skips messages sharing one timestamp are all returned across pages', async ({
+ page,
+ }) => {
+ const conversationId = randomUUID();
+ conversationIds.push(conversationId);
+ const seeded = await seedTied(conversationId, 7);
+ await page.goto(NEW_CHAT_PATH);
+ const token = await getAccessToken(page);
+
+ const seen: string[] = [];
+ let cursor: string | null = null;
+ for (let index = 0; index < 10; index++) {
+ const query = new URLSearchParams({ conversationId, pageSize: '3' });
+ if (cursor) {
+ query.set('cursor', cursor);
+ }
+ const result: Page = await requestJson<Page>(page, {
+ path: `/api/messages?${query.toString()}`,
+ token,
+ });
+ expect(result.messages.every((message) => message._id === undefined)).toBe(true);
+ seen.push(...result.messages.map((message) => message.messageId));
+ cursor = result.nextCursor;
+ if (!cursor) {
+ break;
+ }
+ }
+ expect(seen).toHaveLength(7);
+ expect(new Set(seen)).toEqual(new Set(seeded));
+ });
+
+ test('@scenario:message-page-size-capped an oversized pageSize returns a bounded page', async ({
+ page,
+ }) => {
+ const conversationId = randomUUID();
+ conversationIds.push(conversationId);
+ await seedTied(conversationId, 4);
+ await page.goto(NEW_CHAT_PATH);
+ const token = await getAccessToken(page);
+ const result = await requestJson<Page>(page, {
+ path: `/api/messages?conversationId=${conversationId}&pageSize=999999999`,
+ token,
+ });
+ expect(result.messages).toHaveLength(4);
+ expect(result.nextCursor).toBeNull();
+ });
+});
diff --git a/librechat.example.yaml b/librechat.example.yaml
index 801d1d96d6..874483cd0d 100644
--- a/librechat.example.yaml
+++ b/librechat.example.yaml
@@ -571,6 +571,10 @@ registration:
# violationLog:
# maxEntries: 100
+# Largest pageSize accepted when reading a conversation's messages.
+# messages:
+# maxPageSize: 1000 # default: 1000
+
# rateLimits:
# # Per-user MCP App browser-route limits. Each limit uses a fixed one-minute window.
# mcpApps:
diff --git a/packages/api/src/cache/keyvMongo.spec.ts b/packages/api/src/cache/keyvMongo.spec.ts
new file mode 100644
index 0000000000..e83b5a88bb
--- /dev/null
+++ b/packages/api/src/cache/keyvMongo.spec.ts
@@ -0,0 +1,49 @@
+import mongoose from 'mongoose';
+import { MongoMemoryServer } from 'mongodb-memory-server';
+import keyvMongo from './keyvMongo';
+
+jest.mock('@librechat/data-schemas', () => ({
+ ...jest.requireActual('@librechat/data-schemas'),
+ logger: { error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn() },
+}));
+
+let server: MongoMemoryServer;
+
+beforeAll(async () => {
+ server = await MongoMemoryServer.create();
+ await mongoose.connect(server.getUri());
+});
+afterAll(async () => {
+ await mongoose.disconnect();
+ await server?.stop();
+});
+
+async function waitForIndex(name: string): Promise<Record<string, unknown> | undefined> {
+ const logs = mongoose.connection.db!.collection('logs');
+ for (let attempt = 0; attempt < 50; attempt++) {
+ const found = (await logs.indexes()).find((index) => index.name === name);
+ if (found) {
+ return found as Record<string, unknown>;
+ }
+ await new Promise((resolve) => setTimeout(resolve, 100));
+ }
+ return undefined;
+}
+
+describe('KeyvMongo logs collection', () => {
+ it('indexes lookups by key and expires entries through a TTL index', async () => {
+ await keyvMongo.set('ban:1', 'value', 60_000);
+ expect(await keyvMongo.get('ban:1')).toBe('value');
+ expect(await waitForIndex('key_1')).toBeDefined();
+ const expiry = await waitForIndex('expiresAt_1');
+ expect(expiry?.expireAfterSeconds).toBe(0);
+ });
+
+ it('stores a null expiresAt for entries without a ttl, which the TTL index ignores', async () => {
+ const logs = mongoose.connection.db!.collection('logs');
+ await keyvMongo.set('no-ttl', 'kept');
+ expect(await logs.countDocuments({ key: 'no-ttl' })).toBe(1);
+ const stored = await logs.findOne({ key: 'no-ttl' });
+ expect(stored?.expiresAt).toBeNull();
+ });
+});
diff --git a/packages/api/src/cache/keyvMongo.ts b/packages/api/src/cache/keyvMongo.ts
index 34189800ca..24ae00b384 100644
--- a/packages/api/src/cache/keyvMongo.ts
+++ b/packages/api/src/cache/keyvMongo.ts
@@ -85,6 +85,14 @@ class KeyvMongoCustom extends EventEmitter {
).catch((error: unknown) => {
logger.warn(`[KeyvMongo] Could not index "${collection}" by key`, error);
});
+ /** `set` stamps `expiresAt` from the ttl (null when there is none, which a TTL index
+ * ignores), so entries Keyv already treats as expired are also removed from disk. */
+ buildIndexWithRetry(
+ () => store.createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 }),
+ `KeyvMongo "${collection}" expiry index`,
+ ).catch((error: unknown) => {
+ logger.warn(`[KeyvMongo] Could not add expiry index to "${collection}"`, error);
+ });
}
}
diff --git a/packages/api/src/messages/index.ts b/packages/api/src/messages/index.ts
index 4d62fa23e7..ad8154f7b3 100644
--- a/packages/api/src/messages/index.ts
+++ b/packages/api/src/messages/index.ts
@@ -1,2 +1,3 @@
export * from './parts';
export * from './previews';
+export * from './page';
diff --git a/packages/api/src/messages/page.spec.ts b/packages/api/src/messages/page.spec.ts
new file mode 100644
index 0000000000..47629f040f
--- /dev/null
+++ b/packages/api/src/messages/page.spec.ts
@@ -0,0 +1,68 @@
+import {
+ DEFAULT_MESSAGES_PAGE_SIZE,
+ MAX_MESSAGES_PAGE_SIZE,
+ parseMessagesPageSize,
+ resolveMessagesPageSize,
+ awaitPageSize,
+} from './page';
+
+describe('parseMessagesPageSize', () => {
+ it('falls back to the default for missing, zero, negative, or non-numeric values', () => {
+ for (const raw of [undefined, '', '0', '-5', 'abc', null, {}, ['10']]) {
+ expect(parseMessagesPageSize(raw)).toBe(DEFAULT_MESSAGES_PAGE_SIZE);
+ }
+ });
+
+ it('keeps values within the cap unchanged', () => {
+ expect(parseMessagesPageSize('10')).toBe(10);
+ expect(parseMessagesPageSize(String(MAX_MESSAGES_PAGE_SIZE))).toBe(MAX_MESSAGES_PAGE_SIZE);
+ });
+
+ it('clamps oversized values to the cap', () => {
+ expect(parseMessagesPageSize('1000000')).toBe(MAX_MESSAGES_PAGE_SIZE);
+ });
+
+ it('honors a configured ceiling', () => {
+ expect(parseMessagesPageSize('5000', 2000)).toBe(2000);
+ expect(parseMessagesPageSize('50', 2000)).toBe(50);
+ expect(parseMessagesPageSize(undefined, 10)).toBe(10);
+ });
+});
+
+describe('resolveMessagesPageSize', () => {
+ const user = { id: 'u1', role: 'USER' };
+
+ it('applies the configured ceiling', async () => {
+ const getAppConfig = jest.fn().mockResolvedValue({ messages: { maxPageSize: 40 } });
+ await expect(resolveMessagesPageSize(user, '500', { getAppConfig })).resolves.toBe(40);
+ expect(getAppConfig).toHaveBeenCalledWith(
+ expect.objectContaining({ skipRuntimeAugmentation: true }),
+ );
+ });
+
+ it('keeps the default ceiling when no limit is configured', async () => {
+ const getAppConfig = jest.fn().mockResolvedValue({});
+ await expect(resolveMessagesPageSize(user, '5000', { getAppConfig })).resolves.toBe(
+ MAX_MESSAGES_PAGE_SIZE,
+ );
+ });
+
+ it('falls back to the default ceiling when config is unavailable', async () => {
+ const getAppConfig = jest.fn().mockRejectedValue(new Error('down'));
+ await expect(resolveMessagesPageSize(user, '5000', { getAppConfig })).resolves.toBe(
+ MAX_MESSAGES_PAGE_SIZE,
+ );
+ });
+});
+
+describe('awaitPageSize', () => {
+ it('returns the page size and leaves a rejecting sibling read awaitable', async () => {
+ const failing = Promise.reject(new Error('db down'));
+ const size = await awaitPageSize(
+ new Promise<number>((resolve) => setTimeout(() => resolve(40), 5)),
+ failing,
+ );
+ expect(size).toBe(40);
+ await expect(failing).rejects.toThrow('db down');
+ });
+});
diff --git a/packages/api/src/messages/page.ts b/packages/api/src/messages/page.ts
new file mode 100644
index 0000000000..96ebd78686
--- /dev/null
+++ b/packages/api/src/messages/page.ts
@@ -0,0 +1,57 @@
+import { logger } from '@librechat/data-schemas';
+import type { AppConfigUserLike } from '~/app/service';
+import type { ToolCallPreviewDeps } from './previews';
+import { getAppConfigOptionsFromUser } from '~/app/service';
+
+export const DEFAULT_MESSAGES_PAGE_SIZE = 25;
+/** Default ceiling, matching the search page ceiling; `messages.maxPageSize` overrides it. */
+export const MAX_MESSAGES_PAGE_SIZE = 1000;
+
+/** Parses the client `pageSize` query value, falling back to the default and never exceeding the cap. */
+export function parseMessagesPageSize(
+ raw: unknown,
+ maxPageSize: number = MAX_MESSAGES_PAGE_SIZE,
+): number {
+ const parsed =
+ typeof raw === 'string' || typeof raw === 'number' ? parseInt(String(raw), 10) : NaN;
+ if (!Number.isFinite(parsed) || parsed <= 0) {
+ return Math.min(DEFAULT_MESSAGES_PAGE_SIZE, maxPageSize);
+ }
+ return Math.min(parsed, maxPageSize);
+}
+
+/**
+ * Parses the client `pageSize` against the deployment's `messages.maxPageSize`. The config read skips
+ * runtime augmentation and is meant to start beside the message reads; an unavailable config keeps
+ * the default ceiling instead of failing the load.
+ */
+export async function resolveMessagesPageSize(
+ user: AppConfigUserLike | undefined,
+ raw: unknown,
+ deps: ToolCallPreviewDeps,
+): Promise<number> {
+ try {
+ const config = await deps.getAppConfig({
+ ...getAppConfigOptionsFromUser(user),
+ skipRuntimeAugmentation: true,
+ });
+ return parseMessagesPageSize(raw, config?.messages?.maxPageSize ?? MAX_MESSAGES_PAGE_SIZE);
+ } catch (error) {
+ logger.warn('[messages] Config unavailable; using the default page size ceiling', error);
+ return parseMessagesPageSize(raw);
+ }
+}
+
+/**
+ * Waits for the resolved page size while `pending` reads run beside it. They are observed so one
+ * that rejects first is not an unhandled rejection; each stays awaitable by the caller.
+ */
+export async function awaitPageSize(
+ pageSize: Promise<number>,
+ ...pending: Promise<unknown>[]
+): Promise<number> {
+ for (const read of pending) {
+ read.catch(() => undefined);
+ }
+ return pageSize;
+}
diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts
index 3b0545b281..dc1df759ae 100644
--- a/packages/data-provider/src/config.ts
+++ b/packages/data-provider/src/config.ts
@@ -4662,6 +4662,12 @@ export const configSchema = z.object({
.optional(),
timeouts: outboundTimeoutsSchema.optional(),
violationLog: violationLogSchema.optional(),
+ messages: z
+ .object({
+ /** Largest `pageSize` accepted by `GET /api/messages`. Defaults to 1000. */
+ maxPageSize: z.number().int().min(1).max(10000).optional(),
+ })
+ .optional(),
fileConfig: fileConfigSchema.optional(),
modelSpecs: specsConfigSchema.optional(),
filters: filtersConfigSchema.optional(),
diff --git a/packages/data-schemas/src/app/service.ts b/packages/data-schemas/src/app/service.ts
index 67eb9d0191..b9cbae7f9b 100644
--- a/packages/data-schemas/src/app/service.ts
+++ b/packages/data-schemas/src/app/service.ts
@@ -223,6 +223,7 @@ export const AppService = async (params?: {
githubCompare: config.githubCompare,
timeouts: config.timeouts,
violationLog: config.violationLog,
+ messages: config.messages,
mcpSettings,
mcpAppSandbox,
fileStrategy,
diff --git a/packages/data-schemas/src/methods/message.cursor.spec.ts b/packages/data-schemas/src/methods/message.cursor.spec.ts
new file mode 100644
index 0000000000..54d5876d32
--- /dev/null
+++ b/packages/data-schemas/src/methods/message.cursor.spec.ts
@@ -0,0 +1,275 @@
+import mongoose from 'mongoose';
+import { v4 as uuid } from 'uuid';
+import { MongoMemoryServer } from 'mongodb-memory-server';
+import { createMessageMethods, CLIENT_MESSAGE_SELECT } from './message';
+import { createModels } from '../models';
+
+jest.mock('~/config/winston', () => ({
+ error: jest.fn(),
+ warn: jest.fn(),
+ info: jest.fn(),
+ debug: jest.fn(),
+}));
+
+let server: MongoMemoryServer;
+const methods = createMessageMethods(mongoose);
+
+beforeAll(async () => {
+ server = await MongoMemoryServer.create();
+ Object.assign(mongoose.models, createModels(mongoose));
+ await mongoose.connect(server.getUri());
+ await mongoose.models.Message.createIndexes();
+});
+afterAll(async () => {
+ await mongoose.disconnect();
+ await server?.stop();
+});
+afterEach(async () => {
+ await mongoose.models.Message.deleteMany({});
+});
+
+async function seedTied(conversationId: string, count: number, at: Date): Promise<string[]> {
+ const rows = Array.from({ length: count }, (_, index) => ({
+ messageId: `m-${index}-${uuid()}`,
+ conversationId,
+ user: 'user-1',
+ text: `message ${index}`,
+ isCreatedByUser: false,
+ createdAt: at,
+ updatedAt: at,
+ }));
+ await mongoose.models.Message.collection.insertMany(rows);
+ return rows.map((row) => row.messageId);
+}
+
+async function readAll(options: {
+ sortField: string;
+ sortOrder: 1 | -1;
+ conversationId: string;
+ limit: number;
+}): Promise<string[]> {
+ const ids: string[] = [];
+ let cursor: string | null = null;
+ for (let page = 0; page < 20; page++) {
+ const result = await methods.getMessagesByCursor(
+ { conversationId: options.conversationId, user: 'user-1' },
+ { sortField: options.sortField, sortOrder: options.sortOrder, limit: options.limit, cursor },
+ );
+ ids.push(...result.messages.map((message) => message.messageId));
+ if (result.nextCursor == null) {
+ return ids;
+ }
+ cursor = result.nextCursor;
+ }
+ throw new Error('cursor did not terminate');
+}
+
+describe('getMessagesByCursor', () => {
+ it.each([
+ ['createdAt', -1],
+ ['createdAt', 1],
+ ['updatedAt', -1],
+ ['updatedAt', 1],
+ ] as const)(
+ 'pages through rows sharing one %s value without skips or repeats (order %i)',
+ async (sortField, sortOrder) => {
+ const conversationId = uuid();
+ const seeded = await seedTied(conversationId, 7, new Date('2026-01-01T00:00:00.123Z'));
+ const seen = await readAll({ sortField, sortOrder, conversationId, limit: 3 });
+ expect(seen).toHaveLength(7);
+ expect(new Set(seen)).toEqual(new Set(seeded));
+ },
+ );
+
+ it('keeps millisecond precision in the cursor', async () => {
+ const conversationId = uuid();
+ await seedTied(conversationId, 3, new Date('2026-01-01T00:00:00.456Z'));
+ const first = await methods.getMessagesByCursor(
+ { conversationId, user: 'user-1' },
+ { limit: 1 },
+ );
+ expect(first.nextCursor).toContain('2026-01-01T00:00:00.456Z|');
+ });
+
+ it('pages ties without skips under the client projection that omits _id', async () => {
+ const conversationId = uuid();
+ const seeded = await seedTied(conversationId, 7, new Date('2026-01-01T00:00:00.123Z'));
+ const seen: string[] = [];
+ let cursor: string | null = null;
+ for (let page = 0; page < 20; page++) {
+ const result = await methods.getMessagesByCursor(
+ { conversationId, user: 'user-1' },
+ { limit: 3, cursor, select: CLIENT_MESSAGE_SELECT },
+ );
+ expect(result.messages.every((message) => message._id === undefined)).toBe(true);
+ seen.push(...result.messages.map((message) => message.messageId));
+ if (result.nextCursor == null) {
+ break;
+ }
+ cursor = result.nextCursor;
+ }
+ expect(seen).toHaveLength(7);
+ expect(new Set(seen)).toEqual(new Set(seeded));
+ });
+
+ it('pages past rows with a missing sort value without skips', async () => {
+ const conversationId = uuid();
+ const at = new Date('2026-01-01T00:00:00.000Z');
+ const rows = Array.from({ length: 5 }, (_, index) => ({
+ messageId: `blank-${index}-${uuid()}`,
+ conversationId,
+ user: 'user-1',
+ text: 'x',
+ isCreatedByUser: false,
+ createdAt: at,
+ updatedAt: at,
+ }));
+ await mongoose.models.Message.collection.insertMany(rows);
+ const seen: string[] = [];
+ let cursor: string | null = null;
+ for (let page = 0; page < 10; page++) {
+ const result = await methods.getMessagesByCursor(
+ { conversationId, user: 'user-1' },
+ { sortField: 'endpoint', sortOrder: 1, limit: 2, cursor },
+ );
+ seen.push(...result.messages.map((message) => message.messageId));
+ if (result.nextCursor == null) {
+ break;
+ }
+ cursor = result.nextCursor;
+ }
+ expect(seen).toHaveLength(5);
+ expect(new Set(seen)).toEqual(new Set(rows.map((row) => row.messageId)));
+ });
+
+ it('descending past populated values still returns rows with a missing sort value', async () => {
+ const conversationId = uuid();
+ const at = new Date('2026-01-01T00:00:00.000Z');
+ const rows = ['a', 'a', 'b', undefined, undefined].map((endpoint, index) => ({
+ messageId: `mixed-${index}-${uuid()}`,
+ conversationId,
+ user: 'user-1',
+ text: 'x',
+ isCreatedByUser: false,
+ createdAt: at,
+ updatedAt: at,
+ ...(endpoint ? { endpoint } : {}),
+ }));
+ await mongoose.models.Message.collection.insertMany(rows);
+ const seen: string[] = [];
+ let cursor: string | null = null;
+ for (let page = 0; page < 10; page++) {
+ const result = await methods.getMessagesByCursor(
+ { conversationId, user: 'user-1' },
+ { sortField: 'endpoint', sortOrder: -1, limit: 2, cursor },
+ );
+ seen.push(...result.messages.map((message) => message.messageId));
+ if (result.nextCursor == null) {
+ break;
+ }
+ cursor = result.nextCursor;
+ }
+ expect(seen).toHaveLength(5);
+ expect(new Set(seen)).toEqual(new Set(rows.map((row) => row.messageId)));
+ });
+
+ it.each([
+ [1, 1],
+ [1, 2],
+ [-1, 1],
+ [-1, 2],
+ ] as const)(
+ 'keeps missing, empty and populated sort values distinct (order %i, page size %i)',
+ async (sortOrder, limit) => {
+ const conversationId = uuid();
+ const at = new Date('2026-01-01T00:00:00.000Z');
+ const rows = [undefined, '', undefined, '', 'a', 'a', 'b', null].map((endpoint, index) => ({
+ messageId: `mix-${index}-${uuid()}`,
+ conversationId,
+ user: 'user-1',
+ text: 'x',
+ isCreatedByUser: false,
+ createdAt: at,
+ updatedAt: at,
+ ...(endpoint === undefined ? {} : { endpoint }),
+ }));
+ await mongoose.models.Message.collection.insertMany(rows);
+ const seen: string[] = [];
+ let cursor: string | null = null;
+ for (let page = 0; page < 20; page++) {
+ const result = await methods.getMessagesByCursor(
+ { conversationId, user: 'user-1' },
+ { sortField: 'endpoint', sortOrder, limit, cursor },
+ );
+ seen.push(...result.messages.map((message) => message.messageId));
+ if (result.nextCursor == null) {
+ break;
+ }
+ cursor = result.nextCursor;
+ }
+ expect(seen).toHaveLength(rows.length);
+ expect(new Set(seen)).toEqual(new Set(rows.map((row) => row.messageId)));
+ },
+ );
+
+ it.each([1, -1] as const)(
+ 'pages past messages with a missing timestamp (order %i)',
+ async (sortOrder) => {
+ const conversationId = uuid();
+ const at = new Date('2026-01-01T00:00:00.000Z');
+ const rows = [at, undefined, at, undefined].map((updatedAt, index) => ({
+ messageId: `ts-${index}-${uuid()}`,
+ conversationId,
+ user: 'user-1',
+ text: 'x',
+ isCreatedByUser: false,
+ createdAt: at,
+ ...(updatedAt ? { updatedAt } : {}),
+ }));
+ await mongoose.models.Message.collection.insertMany(rows);
+ const seen: string[] = [];
+ let cursor: string | null = null;
+ for (let page = 0; page < 10; page++) {
+ const result = await methods.getMessagesByCursor(
+ { conversationId, user: 'user-1' },
+ { sortField: 'updatedAt', sortOrder, limit: 1, cursor },
+ );
+ seen.push(...result.messages.map((message) => message.messageId));
+ if (result.nextCursor == null) {
+ break;
+ }
+ cursor = result.nextCursor;
+ }
+ expect(new Set(seen)).toEqual(new Set(rows.map((row) => row.messageId)));
+ expect(seen).toHaveLength(rows.length);
+ },
+ );
+
+ it('still honors a legacy bare timestamp cursor', async () => {
+ const conversationId = uuid();
+ const newer = new Date('2026-02-01T00:00:00.000Z');
+ const older = new Date('2026-01-01T00:00:00.000Z');
+ await seedTied(conversationId, 1, newer);
+ const [olderId] = await seedTied(conversationId, 1, older);
+ const result = await methods.getMessagesByCursor(
+ { conversationId, user: 'user-1' },
+ { cursor: newer.toISOString(), limit: 10 },
+ );
+ expect(result.messages.map((message) => message.messageId)).toEqual([olderId]);
+ });
+
+ it('serves the default and updatedAt sorts from an index', async () => {
+ const Message = mongoose.models.Message;
+ const conversationId = uuid();
+ await seedTied(conversationId, 3, new Date());
+ for (const sortField of ['createdAt', 'updatedAt']) {
+ const plan = (await Message.find({ conversationId, user: 'user-1' })
+ .sort({ [sortField]: -1, _id: -1 })
+ .explain('queryPlanner')) as unknown as { queryPlanner: { winningPlan: unknown } };
+ const winning = JSON.stringify(plan.queryPlanner.winningPlan);
+ expect(winning.includes('"stage":"IXSCAN"')).toBe(true);
+ expect(winning.includes('"stage":"SORT"')).toBe(false);
+ expect(winning.includes('COLLSCAN')).toBe(false);
+ }
+ });
+});
diff --git a/packages/data-schemas/src/methods/message.ts b/packages/data-schemas/src/methods/message.ts
index dcc062e3c2..cc6403e189 100644
--- a/packages/data-schemas/src/methods/message.ts
+++ b/packages/data-schemas/src/methods/message.ts
@@ -950,6 +950,7 @@ export interface MessageMethods {
sortOrder?: 1 | -1;
limit?: number;
cursor?: string | null;
+ select?: string;
},
): Promise<{ messages: IMessage[]; nextCursor: string | null }>;
searchMessages(
@@ -960,6 +961,58 @@ export interface MessageMethods {
deleteMessages(filter: FilterQuery<IMessage>): Promise<DeleteResult>;
}
+const DATE_SORT_FIELDS = new Set(['createdAt', 'updatedAt']);
+/** Cursor marker for a null or missing sort value, which MongoDB orders before every string, '' included. */
+const NULL_SORT_VALUE = '\u0000';
+const OBJECT_ID_PATTERN = /^[0-9a-f]{24}$/i;
+
+/** Encodes the last row of a page as `<sortValue>|<_id>`; dates use ISO strings so milliseconds survive. */
+function formatMessageCursor(value: unknown, id: unknown): string {
+ if (value == null) {
+ return id == null ? NULL_SORT_VALUE : `${NULL_SORT_VALUE}|${String(id)}`;
+ }
+ const sortValue = value instanceof Date ? value.toISOString() : String(value);
+ return id == null ? sortValue : `${sortValue}|${String(id)}`;
+}
+
+/** Accepts both the compound cursor and the legacy bare sort value from older clients. */
+function parseMessageCursor(cursor: string): { value: string; id?: string } {
+ const split = cursor.lastIndexOf('|');
+ if (split >= 0 && OBJECT_ID_PATTERN.test(cursor.slice(split + 1))) {
+ return { value: cursor.slice(0, split), id: cursor.slice(split + 1) };
+ }
+ return { value: cursor };
+}
+
+/** The rows after a cursor, following MongoDB's order: null/missing, then '' (strings only), then values. */
+function buildCursorFilter(
+ sortField: string,
+ op: '$gt' | '$lt',
+ value: string | Date,
+ position: { value: string; id?: Types.ObjectId },
+): FilterQuery<IMessage> {
+ if (position.id == null) {
+ return { [sortField]: { [op]: value } };
+ }
+ const tieId = { _id: { [op]: position.id } };
+ const ascending = op === '$gt';
+ if (position.value === NULL_SORT_VALUE) {
+ return {
+ $or: [
+ { [sortField]: null, ...tieId },
+ ...(ascending ? [{ [sortField]: { $ne: null } }] : []),
+ ],
+ };
+ }
+ return {
+ $or: [
+ { [sortField]: { [op]: value } },
+ { [sortField]: value, ...tieId },
+ ...(ascending ? [] : [{ [sortField]: null }]),
+ ],
+ };
+}
+
/** The agent-ownership rule shared by background-tool settling and claiming:
* `agentId` on the part wins, then `tool_call.agentId`, and a part without
* agent identity belongs to any caller (single-agent runs). `field: null`
@@ -4247,16 +4300,28 @@ export function createMessageMethods(
) {
const Message = mongoose.models.Message as Model<IMessage>;
const { sortField = 'createdAt', sortOrder = -1, limit = 25, cursor, select } = options;
- const queryFilter = { ...filter };
- if (cursor) {
- queryFilter[sortField] = sortOrder === 1 ? { $gt: cursor } : { $lt: cursor };
+ const queryFilter: FilterQuery<IMessage> = { ...filter };
+ const position = cursor ? parseMessageCursor(cursor) : null;
+ if (position != null) {
+ const op = sortOrder === 1 ? '$gt' : '$lt';
+ const value =
+ DATE_SORT_FIELDS.has(sortField) && position.value !== NULL_SORT_VALUE
+ ? new Date(position.value)
+ : position.value;
+ const id = position.id == null ? undefined : new mongoose.Types.ObjectId(position.id);
+ const after = buildCursorFilter(sortField, op, value, { value: position.value, id });
+ queryFilter.$and = [...(queryFilter.$and ?? []), after];
}
const query = Message.find(queryFilter);
- if (select) {
- query.select(select);
+ /** The cursor needs `_id`, so an `-_id` projection is applied after it is read. */
+ const tokens = select ? select.split(/\s+/).filter(Boolean) : [];
+ const omitId = tokens.includes('-_id');
+ if (tokens.length > 0) {
+ query.select(tokens.filter((token) => token !== '-_id').join(' '));
}
+ /** `_id` makes the order total, so a page boundary inside a run of equal sort values is stable. */
const messages = await query
- .sort({ [sortField]: sortOrder })
+ .sort({ [sortField]: sortOrder, _id: sortOrder })
.limit(limit + 1)
.lean<IMessage[]>();
@@ -4264,9 +4329,12 @@ export function createMessageMethods(
if (messages.length > limit) {
messages.pop();
const last = messages[messages.length - 1];
- const cursorValue =
- sortField === 'createdAt' ? last.createdAt : last[sortField as keyof IMessage];
- nextCursor = String(cursorValue ?? '');
+ nextCursor = formatMessageCursor(last[sortField as keyof IMessage], last._id);
+ }
+ if (omitId) {
+ for (const message of messages) {
+ delete (message as { _id?: unknown })._id;
+ }
}
return { messages, nextCursor };
}
diff --git a/packages/data-schemas/src/schema/agent.ts b/packages/data-schemas/src/schema/agent.ts
index 762d5f3471..c959980aea 100644
--- a/packages/data-schemas/src/schema/agent.ts
+++ b/packages/data-schemas/src/schema/agent.ts
@@ -201,5 +201,20 @@ agentSchema.index({ tenantId: 1, updatedAt: -1, _id: 1 });
agentSchema.index({ createdAt: -1, _id: 1 });
agentSchema.index({ tenantId: 1, createdAt: -1, _id: 1 });
agentSchema.index({ 'edges.to': 1 });
+/** Reference checks before code environment removal match either field; each `$or` branch needs its own index. */
+agentSchema.index(
+ { code_environment_id: 1 },
+ {
+ name: 'agent_code_environment_id',
+ partialFilterExpression: { code_environment_id: { $exists: true } },
+ },
+);
+agentSchema.index(
+ { code_environment_ids: 1 },
+ {
+ name: 'agent_code_environment_ids',
+ partialFilterExpression: { code_environment_ids: { $exists: true } },
+ },
+);
export default agentSchema;
diff --git a/packages/data-schemas/src/schema/lookupIndexes.spec.ts b/packages/data-schemas/src/schema/lookupIndexes.spec.ts
new file mode 100644
index 0000000000..6785e9e22c
--- /dev/null
+++ b/packages/data-schemas/src/schema/lookupIndexes.spec.ts
@@ -0,0 +1,91 @@
+import mongoose from 'mongoose';
+import { MongoMemoryServer } from 'mongodb-memory-server';
+import type { FilterQuery, Model } from 'mongoose';
+import { createModels } from '../models';
+
+let server: MongoMemoryServer;
+
+beforeAll(async () => {
+ server = await MongoMemoryServer.create();
+ Object.assign(mongoose.models, createModels(mongoose));
+ await mongoose.connect(server.getUri());
+ await Promise.all(
+ ['Session', 'ToolCall', 'AgentQueuedTurn', 'Agent'].map((name) =>
+ mongoose.models[name].createIndexes(),
+ ),
+ );
+});
+afterAll(async () => {
+ await mongoose.disconnect();
+ await server?.stop();
+});
+
+/** Names the index the winning plan scans, or `COLLSCAN` when it reads the whole collection. */
+async function winningScan(
+ modelName: string,
+ filter: FilterQuery<unknown>,
+ seed: Record<string, unknown>[],
+): Promise<string> {
+ const model = mongoose.models[modelName] as Model<unknown>;
+ await model.collection.deleteMany({});
+ /** Filler rows without the indexed field keep the planner from preferring a scan on a tiny collection. */
+ await model.collection.insertMany(seed);
+ const plan = (await model.find(filter).explain('queryPlanner')) as unknown as {
+ queryPlanner: { winningPlan: unknown };
+ };
+ const text = JSON.stringify(plan.queryPlanner.winningPlan);
+ const match = /"stage":"IXSCAN".*?"indexName":"([^"]+)"/.exec(text);
+ return match?.[1] ?? (text.includes('COLLSCAN') ? 'COLLSCAN' : text);
+}
+
+/** Builds rows that satisfy each collection's unique indexes via `make(index)`. */
+const filler = (count: number, make: (index: number) => Record<string, unknown>) =>
+ Array.from({ length: count }, (_, index) => ({ filler: index, ...make(index) }));
+
+describe('single-field lookups use an index', () => {
+ it('session by refreshTokenHash without a user', async () => {
+ const scan = await winningScan('Session', { refreshTokenHash: 'abc' }, [
+ ...filler(50, (i) => ({
+ user: new mongoose.Types.ObjectId(),
+ refreshTokenHash: `other-${i}`,
+ })),
+ { user: new mongoose.Types.ObjectId(), refreshTokenHash: 'abc' },
+ ]);
+ expect(scan).toBe('refreshTokenHash_1');
+ });
+
+ it('tool calls by user alone', async () => {
+ const user = new mongoose.Types.ObjectId();
+ const scan = await winningScan('ToolCall', { user }, [
+ ...filler(50, () => ({ user: new mongoose.Types.ObjectId() })),
+ { user },
+ ]);
+ expect(scan).toBe('user_1');
+ });
+
+ it.each([
+ ['deliveryKey', { deliveryKey: 'key-1' }, 'agent_queued_turn_delivery_key'],
+ [
+ 'reconciliationClaimId',
+ { reconciliationClaimId: 'claim-1', reconciliationClaimBy: 'worker' },
+ 'agent_queued_turn_reconciliation_claim',
+ ],
+ ])('queued turns by %s', async (_name, filter, indexName) => {
+ const scan = await winningScan('AgentQueuedTurn', filter, [
+ ...filler(50, (i) => ({ clientRequestId: `filler-${i}` })),
+ { ...filter, clientRequestId: 'target', filler: -1 },
+ ]);
+ expect(scan).toBe(indexName);
+ });
+
+ it.each([
+ ['code_environment_id', 'agent_code_environment_id', 'env-1'],
+ ['code_environment_ids', 'agent_code_environment_ids', 'env-1'],
+ ])('agents by %s', async (field, indexName, value) => {
+ const scan = await winningScan('Agent', { [field]: value }, [
+ ...filler(50, (i) => ({ id: `filler-${i}` })),
+ { id: 'target', [field]: field.endsWith('s') ? [value] : value, filler: -1 },
+ ]);
+ expect(scan).toBe(indexName);
+ });
+});
diff --git a/packages/data-schemas/src/schema/message.ts b/packages/data-schemas/src/schema/message.ts
index 45484f270e..fe6c19de07 100644
--- a/packages/data-schemas/src/schema/message.ts
+++ b/packages/data-schemas/src/schema/message.ts
@@ -365,6 +365,12 @@ messageSchema.index({
*/
messageSchema.index({ conversationId: 1, user: 1, createdAt: 1, _id: 1 });
+/**
+ * Serves the cursor-paginated message read when sorted by `updatedAt`, the
+ * default of `GET /api/messages`; the `createdAt` sort uses the index above.
+ */
+messageSchema.index({ conversationId: 1, user: 1, updatedAt: 1, _id: 1 });
+
/**
* Serves the batched newest-task read for child threads. `user` is an equality
* prefix and `conversationId` is the partition key, so Mongo/DocumentDB can
diff --git a/packages/data-schemas/src/schema/queuedTurn.ts b/packages/data-schemas/src/schema/queuedTurn.ts
index 9040720a73..314d51398d 100644
--- a/packages/data-schemas/src/schema/queuedTurn.ts
+++ b/packages/data-schemas/src/schema/queuedTurn.ts
@@ -191,6 +191,22 @@ queuedTurnSchema.index(
},
{ name: 'agent_queued_turn_active' },
);
+/** Delivery retirement looks turns up by `deliveryKey` alone; most turns never carry one. */
+queuedTurnSchema.index(
+ { deliveryKey: 1 },
+ {
+ name: 'agent_queued_turn_delivery_key',
+ partialFilterExpression: { deliveryKey: { $exists: true } },
+ },
+);
+/** Re-fetches the rows a reconciliation sweep just claimed. */
+queuedTurnSchema.index(
+ { reconciliationClaimId: 1 },
+ {
+ name: 'agent_queued_turn_reconciliation_claim',
+ partialFilterExpression: { reconciliationClaimId: { $exists: true } },
+ },
+);
queuedTurnSchema.index({ tenantId: 1, user: 1, status: 1, claimUntil: 1 });
queuedTurnSchema.index({ status: 1, createdAt: 1, _id: 1 });
queuedTurnSchema.index({
diff --git a/packages/data-schemas/src/schema/session.ts b/packages/data-schemas/src/schema/session.ts
index 298180f0ab..ef7139082c 100644
--- a/packages/data-schemas/src/schema/session.ts
+++ b/packages/data-schemas/src/schema/session.ts
@@ -23,5 +23,7 @@ const sessionSchema: Schema<ISession> = new Schema({
});
sessionSchema.index({ user: 1, refreshTokenHash: 1 }, { unique: true });
+/** `deleteSession({ refreshToken })` has no user in its filter, so the compound index above cannot serve it. */
+sessionSchema.index({ refreshTokenHash: 1 });
export default sessionSchema;
diff --git a/packages/data-schemas/src/schema/toolCall.ts b/packages/data-schemas/src/schema/toolCall.ts
index cde2163ca3..a8aab33bbc 100644
--- a/packages/data-schemas/src/schema/toolCall.ts
+++ b/packages/data-schemas/src/schema/toolCall.ts
@@ -59,6 +59,8 @@ const toolCallSchema: Schema<IToolCallData> = new Schema(
);
toolCallSchema.index({ expiredAt: 1 }, { expireAfterSeconds: 0 });
+/** Serves the user-only `deleteToolCalls` (account and bulk cleanup) without a collection scan. */
+toolCallSchema.index({ user: 1 });
toolCallSchema.index({ messageId: 1, user: 1, tenantId: 1 });
toolCallSchema.index({ conversationId: 1, user: 1, tenantId: 1 });
diff --git a/packages/data-schemas/src/types/app.ts b/packages/data-schemas/src/types/app.ts
index 5b890c6bba..7208395767 100644
--- a/packages/data-schemas/src/types/app.ts
+++ b/packages/data-schemas/src/types/app.ts
@@ -73,6 +73,7 @@ export interface AppConfig {
timeouts?: TCustomConfig['timeouts'];
/** Violation log retention; unset keeps the server default */
violationLog?: TCustomConfig['violationLog'];
+ messages?: TCustomConfig['messages'];
skillDeletion?: {
finalizationEnabled?: boolean;
sweepIntervalMs?: number;