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
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
import { v4 as uuidv4 } from 'uuid';
import mongoose, { type FilterQuery } from 'mongoose';
import { MongoMemoryServer } from 'mongodb-memory-server';
import { EModelEndpoint, RetentionMode, UNSEEN_REPLY_WATERMARK } from 'librechat-data-provider';
import type {
Document,
Filter,
FindOneAndUpdateOptions,
UpdateFilter,
UpdateResult,
} from 'mongodb';
import type {
IAgentEventActorReconciliation,
IAgentEventActorSuspensionEvidence,
IChatProject,
IConversation,
IMessage,
AppConfig,
} from '../types';
import { ConversationMethods, createConversationMethods } from './conversation';
import { tenantStorage, runAsSystem } from '~/config/tenantContext';
import { createChatProjectMethods } from './chatProject';
import { createModels } from '../models';
jest.mock('~/config/winston', () => ({
error: jest.fn(),
warn: jest.fn(),
info: jest.fn(),
debug: jest.fn(),
}));
const MEILI_SEARCH_LIMIT = 1000;
let mongoServer: InstanceType<typeof MongoMemoryServer>;
let Conversation: mongoose.Model<IConversation>;
let ChatProject: mongoose.Model<IChatProject>;
let ConversationTag: mongoose.Model<{
user: string;
tag: string;
count: number;
position: number;
}>;
let modelsToCleanup: string[] = [];
// Mock message methods (same as original test mocking ./Message)
const getMessages = jest.fn().mockResolvedValue([]);
const deleteMessages = jest.fn().mockResolvedValue({ deletedCount: 0 });
const searchMessages = jest.fn().mockResolvedValue({ hits: [] });
let methods: ConversationMethods;
beforeAll(async () => {
mongoServer = await MongoMemoryServer.create();
const mongoUri = mongoServer.getUri();
const models = createModels(mongoose);
modelsToCleanup = Object.keys(models);
Object.assign(mongoose.models, models);
Conversation = mongoose.models.Conversation as mongoose.Model<IConversation>;
ChatProject = mongoose.models.ChatProject as mongoose.Model<IChatProject>;
ConversationTag = mongoose.models.ConversationTag as mongoose.Model<{
user: string;
tag: string;
count: number;
position: number;
}>;
methods = createConversationMethods(mongoose, { getMessages, deleteMessages, searchMessages });
await mongoose.connect(mongoUri);
});
afterAll(async () => {
const collections = mongoose.connection.collections;
for (const key in collections) {
await collections[key].deleteMany({});
}
for (const modelName of modelsToCleanup) {
if (mongoose.models[modelName]) {
delete mongoose.models[modelName];
}
}
await mongoose.disconnect();
await mongoServer.stop();
});
const saveConvo = (...args: Parameters<ConversationMethods['saveConvo']>) =>
methods.saveConvo(...args) as Promise<IConversation | null>;
const setConvoPinned = (...args: Parameters<ConversationMethods['setConvoPinned']>) =>
methods.setConvoPinned(...args);
const getConvo = (...args: Parameters<ConversationMethods['getConvo']>) =>
methods.getConvo(...args);
const getConvoRetention = (...args: Parameters<ConversationMethods['getConvoRetention']>) =>
methods.getConvoRetention(...args);
const getConvoTitle = (...args: Parameters<ConversationMethods['getConvoTitle']>) =>
methods.getConvoTitle(...args);
const getConvoFiles = (...args: Parameters<ConversationMethods['getConvoFiles']>) =>
methods.getConvoFiles(...args);
const deleteConvos = (...args: Parameters<ConversationMethods['deleteConvos']>) =>
methods.deleteConvos(...args);
const archiveAllConvos = (...args: Parameters<ConversationMethods['archiveAllConvos']>) =>
methods.archiveAllConvos(...args);
const getConvosByCursor = (...args: Parameters<ConversationMethods['getConvosByCursor']>) =>
methods.getConvosByCursor(...args);
const getConvosQueried = (...args: Parameters<ConversationMethods['getConvosQueried']>) =>
methods.getConvosQueried(...args);
const searchConversation = (...args: Parameters<ConversationMethods['searchConversation']>) =>
methods.searchConversation(...args);
/** The archive sweep discovers projects either by a bounded id list or by its own
* `archivedAt` marker, and the tests below assert which of the two a call used. */
type ArchiveDistinctFilter = {
_id?: { $in?: unknown[] };
user?: string;
isArchived?: boolean;
archivedAt?: Date;
};
describe('Conversation Operations', () => {
let mockCtx: {
userId: string;
isTemporary?: boolean;
expiredAt?: Date;
interfaceConfig?: AppConfig['interfaceConfig'];
};
let mockConversationData: {
conversationId: string;
title: string;
endpoint: string;
};
beforeEach(async () => {
// Clear database
await Conversation.deleteMany({});
await ChatProject.deleteMany({});
await ConversationTag.deleteMany({});
// Reset mocks
jest.clearAllMocks();
getMessages.mockResolvedValue([]);
deleteMessages.mockResolvedValue({ deletedCount: 0 });
searchMessages.mockResolvedValue({ hits: [] });
mockCtx = {
userId: 'user123',
interfaceConfig: {
temporaryChatRetention: 24, // Default 24 hours
},
};
mockConversationData = {
conversationId: uuidv4(),
title: 'Test Conversation',
endpoint: EModelEndpoint.openAI,
};
});
describe('saveConvo', () => {
it('should save a conversation for an authenticated user', async () => {
const result = await saveConvo(mockCtx, mockConversationData);
expect(result?.conversationId).toBe(mockConversationData.conversationId);
expect(result?.user).toBe('user123');
expect(result?.title).toBe('Test Conversation');
expect(result?.endpoint).toBe(EModelEndpoint.openAI);
// Verify the conversation was actually saved to the database
const savedConvo = await Conversation.findOne<IConversation>({
conversationId: mockConversationData.conversationId,
user: 'user123',
});
expect(savedConvo).toBeTruthy();
expect(savedConvo?.title).toBe('Test Conversation');
});
it('rejects actor checkpoint ownership evidence through ordinary saves and imports', async () => {
const forged = {
agentEventActor: {
generation: 1,
checkpoint: {
threadId: 'other',
checkpointNs: 'event-actor/other',
checkpointId: 'other',
},
},
agentEventActorCleanup: [
{ threadId: 'other', checkpointNs: 'event-actor/other', checkpointId: 'other' },
],
agentEventActorReconciliations: [
{
checkpoint: {
threadId: 'other',
checkpointNs: 'event-actor/other',
checkpointId: 'other',
},
},
],
agentEventActorSuspension: { status: 'closed' },
'agentEventActor.checkpoint': {
threadId: 'other',
checkpointNs: 'event-actor/other',
checkpointId: 'other',
},
'agentEventActorCleanup.0': {
threadId: 'other',
checkpointNs: 'event-actor/other',
checkpointId: 'other',
},
lastResponseAt: new Date('2026-08-16T10:00:00.000Z'),
lastResponseMessageId: 'forged-reply',
lastResponseIsManual: true,
};
await saveConvo(mockCtx, { ...mockConversationData, ...forged });
await methods.bulkSaveConvos([{ ...mockConversationData, user: mockCtx.userId, ...forged }]);
const saved = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
user: mockCtx.userId,
})
.select(
'+agentEventActor +agentEventActorCleanup +agentEventActorReconciliations +agentEventActorSuspension',
)
.lean();
for (const field of Object.keys(forged)) {
expect(saved).not.toHaveProperty(field);
}
});
it('sets immutable agent attribution from server metadata only on insert', async () => {
await saveConvo(
mockCtx,
{
...mockConversationData,
agent_id: 'agent-a',
initial_agent_id: 'forged-agent',
},
{ initialAgentId: 'agent-a' },
);
await saveConvo(
mockCtx,
{
conversationId: mockConversationData.conversationId,
agent_id: 'agent-b',
initial_agent_id: 'forged-agent-b',
},
{ initialAgentId: 'agent-b' },
);
const saved = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
user: mockCtx.userId,
})
.select('+initial_agent_id')
.lean();
expect(saved?.initial_agent_id).toBe('agent-a');
expect(saved?.agent_id).toBe('agent-b');
});
it('does not undo explicit Project moves or removal when a stale turn completes', async () => {
const firstProject = await ChatProject.create({
user: mockCtx.userId,
name: 'Insert Project A',
conversationCount: 0,
lastConversationAt: null,
lastConversationId: null,
});
const secondProject = await ChatProject.create({
user: mockCtx.userId,
name: 'Insert Project B',
conversationCount: 0,
lastConversationAt: null,
lastConversationId: null,
});
const conversationId = uuidv4();
await saveConvo(mockCtx, {
conversationId,
title: 'Project turn',
chatProjectId: firstProject._id!.toString(),
});
const projects = createChatProjectMethods(mongoose);
await projects.assignConversationToProject(
mockCtx.userId,
conversationId,
secondProject._id!.toString(),
);
await saveConvo(mockCtx, {
conversationId,
title: 'Stale turn',
chatProjectId: firstProject._id!.toString(),
});
expect((await Conversation.findOne({ conversationId }).lean())?.chatProjectId).toBe(
secondProject._id!.toString(),
);
await projects.assignConversationToProject(mockCtx.userId, conversationId, null);
await saveConvo(mockCtx, {
conversationId,
title: 'Another stale turn',
chatProjectId: firstProject._id!.toString(),
});
const saved = await Conversation.findOne({ conversationId }).lean();
expect(saved?.chatProjectId == null).toBe(true);
});
it('stores explicit null attribution for a new non-agent conversation', async () => {
await saveConvo(mockCtx, mockConversationData);
const saved = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
user: mockCtx.userId,
})
.select('+initial_agent_id')
.lean();
expect(saved).toHaveProperty('initial_agent_id', null);
});
it('should query messages when saving a conversation', async () => {
// Mock messages as ObjectIds
const mockMessages = [new mongoose.Types.ObjectId(), new mongoose.Types.ObjectId()];
getMessages.mockResolvedValue(mockMessages);
await saveConvo(mockCtx, mockConversationData);
// Verify that getMessages was called with correct parameters
expect(getMessages).toHaveBeenCalledWith(
{ conversationId: mockConversationData.conversationId, user: mockCtx.userId },
'_id',
);
});
it('does not let metadata forge a reply timestamp or identity', async () => {
const replyAt = new Date('2026-08-16T10:05:00.000Z');
await saveConvo(
mockCtx,
{ ...mockConversationData },
{ stampReply: true, replyMessageId: 'reply-newer' },
);
await saveConvo(mockCtx, {
...mockConversationData,
lastResponseAt: new Date('2026-08-16T11:00:00.000Z'),
lastResponseMessageId: 'forged',
});
const convo = await Conversation.findOne<IConversation>({
conversationId: mockConversationData.conversationId,
});
expect(convo?.lastResponseAt?.getTime()).toBeGreaterThanOrEqual(replyAt.getTime());
expect(convo?.lastResponseMessageId).toBe('reply-newer');
});
it('stamps a first reply through the monotonic path', async () => {
await saveConvo(
mockCtx,
{ ...mockConversationData },
{ stampReply: true, replyMessageId: 'reply-first' },
);
const convo = await Conversation.findOne<IConversation>({
conversationId: mockConversationData.conversationId,
});
expect(convo?.lastResponseAt).toBeInstanceOf(Date);
expect(convo?.lastResponseMessageId).toBe('reply-first');
});
it('stamps the reply at write time and clears the catch-up it outranks', async () => {
/* `/seen` can match the previous reply while this save is in flight and record a
catch-up later than any timestamp the caller could hold. The stamp and the clear are
one conditional write, so the reply this save persists is never born seen. */
const before = new Date();
await saveConvo(mockCtx, { ...mockConversationData });
await Conversation.updateOne(
{ conversationId: mockConversationData.conversationId },
{ $set: { lastSeenAt: new Date(Date.now() + 5_000) } },
);
await saveConvo(
mockCtx,
{ ...mockConversationData },
{ stampReply: true, replyMessageId: 'reply-write-time' },
);
const convo = await Conversation.findOne<IConversation>({
conversationId: mockConversationData.conversationId,
});
expect(convo?.lastResponseAt).toBeInstanceOf(Date);
expect(convo?.lastResponseAt?.getTime()).toBeGreaterThanOrEqual(before.getTime());
expect(convo?.lastSeenAt?.toISOString()).toBe(UNSEEN_REPLY_WATERMARK);
});
it('returns the durable conversation when the optional reply stamp fails', async () => {
const find = jest.spyOn(Conversation, 'findOne').mockImplementationOnce(() => {
throw new Error('reply stamp read unavailable');
});
let result;
try {
result = await saveConvo(mockCtx, mockConversationData, {
stampReply: true,
replyMessageId: 'reply-failed-read',
});
} finally {
find.mockRestore();
}
expect(result).toMatchObject({
conversationId: mockConversationData.conversationId,
title: mockConversationData.title,
});
const saved = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>();
expect(saved?.title).toBe(mockConversationData.title);
expect(saved?.lastResponseAt).toBeUndefined();
});
it('advances past a future stamp when a save host clock is behind', async () => {
await saveConvo(
mockCtx,
{ ...mockConversationData },
{ stampReply: true, replyMessageId: 'reply-before-future' },
);
const newer = new Date(Date.now() + 60_000);
const seenAt = new Date(Date.now() + 90_000);
await Conversation.updateOne(
{ conversationId: mockConversationData.conversationId },
{ $set: { lastResponseAt: newer, lastSeenAt: seenAt } },
);
await saveConvo(
mockCtx,
{ ...mockConversationData },
{ stampReply: true, replyMessageId: 'reply-after-future' },
);
const convo = await Conversation.findOne<IConversation>({
conversationId: mockConversationData.conversationId,
});
expect(convo?.lastResponseAt?.getTime()).toBeGreaterThan(newer.getTime());
expect(convo?.lastSeenAt?.toISOString()).toBe(UNSEEN_REPLY_WATERMARK);
});
it('leaves the reply stamp alone for a save that does not carry one', async () => {
await saveConvo(mockCtx, { ...mockConversationData });
const convo = await Conversation.findOne<IConversation>({
conversationId: mockConversationData.conversationId,
});
expect(convo?.lastResponseAt).toBeUndefined();
});
it('should handle newConversationId when provided', async () => {
const newConversationId = uuidv4();
const result = await saveConvo(mockCtx, {
...mockConversationData,
newConversationId,
});
expect(result?.conversationId).toBe(newConversationId);
});
it('refreshes project stats when archiving a project conversation', async () => {
const project = await ChatProject.create({
user: mockCtx.userId,
name: 'Project Stats',
conversationCount: 0,
lastConversationAt: null,
lastConversationId: null,
});
const firstConversationId = uuidv4();
const secondConversationId = uuidv4();
const chatProjectId = project._id!.toString();
await saveConvo(mockCtx, {
conversationId: firstConversationId,
title: 'First',
endpoint: EModelEndpoint.openAI,
chatProjectId,
});
await saveConvo(mockCtx, {
conversationId: secondConversationId,
title: 'Second',
endpoint: EModelEndpoint.openAI,
chatProjectId,
});
await saveConvo(mockCtx, {
conversationId: secondConversationId,
isArchived: true,
});
const refreshedProject = await ChatProject.findById(project._id).lean<IChatProject>();
expect(refreshedProject?.conversationCount).toBe(1);
expect(refreshedProject?.lastConversationId).toBe(firstConversationId);
});
it('bulkSaveConvos keeps owned project ids and strips orphan ones', async () => {
const project = await ChatProject.create({
user: mockCtx.userId,
name: 'Bulk Project',
conversationCount: 0,
lastConversationAt: null,
lastConversationId: null,
});
const ownedId = project._id!.toString();
const orphanId = new mongoose.Types.ObjectId().toString();
const ownedConvoId = uuidv4();
const orphanConvoId = uuidv4();
await methods.bulkSaveConvos([
{
conversationId: ownedConvoId,
user: mockCtx.userId,
endpoint: EModelEndpoint.openAI,
chatProjectId: ownedId,
},
{
conversationId: orphanConvoId,
user: mockCtx.userId,
endpoint: EModelEndpoint.openAI,
chatProjectId: orphanId,
},
]);
const ownedConvo = await Conversation.findOne({
conversationId: ownedConvoId,
}).lean<IConversation>();
const orphanConvo = await Conversation.findOne({
conversationId: orphanConvoId,
}).lean<IConversation>();
expect(ownedConvo?.chatProjectId).toBe(ownedId);
expect(orphanConvo?.chatProjectId == null).toBe(true);
const refreshedProject = await ChatProject.findById(project._id).lean<IChatProject>();
expect(refreshedProject?.conversationCount).toBe(1);
});
it('bulkSaveConvos strips supplied attribution and stores explicit null on insert', async () => {
const conversationId = uuidv4();
await methods.bulkSaveConvos([
{
conversationId,
user: mockCtx.userId,
endpoint: EModelEndpoint.openAI,
initial_agent_id: 'forged-agent',
},
]);
const saved = await Conversation.findOne({ conversationId, user: mockCtx.userId })
.select('+initial_agent_id')
.lean();
expect(saved).toHaveProperty('initial_agent_id', null);
});
it('does not reassign membership or Project counts from a stale save payload', async () => {
const projectA = await ChatProject.create({
user: mockCtx.userId,
name: 'Project A',
conversationCount: 0,
});
const projectB = await ChatProject.create({
user: mockCtx.userId,
name: 'Project B',
conversationCount: 0,
});
const conversationId = uuidv4();
const projectAId = projectA._id!.toString();
const projectBId = projectB._id!.toString();
await saveConvo(mockCtx, {
conversationId,
title: 'Moving',
endpoint: EModelEndpoint.openAI,
chatProjectId: projectAId,
});
// Only explicit Project assignment may move this existing conversation.
await saveConvo(mockCtx, {
conversationId,
endpoint: EModelEndpoint.openAI,
chatProjectId: projectBId,
});
const refreshedA = await ChatProject.findById(projectA._id).lean<IChatProject>();
const refreshedB = await ChatProject.findById(projectB._id).lean<IChatProject>();
expect(refreshedA?.conversationCount).toBe(1);
expect(refreshedA?.lastConversationId).toBe(conversationId);
expect(refreshedB?.conversationCount).toBe(0);
expect(refreshedB?.lastConversationId == null).toBe(true);
});
it('bulkSaveConvos refreshes the project a conversation leaves', async () => {
const projectA = await ChatProject.create({
user: mockCtx.userId,
name: 'Bulk Project A',
conversationCount: 0,
});
const projectB = await ChatProject.create({
user: mockCtx.userId,
name: 'Bulk Project B',
conversationCount: 0,
});
const conversationId = uuidv4();
const projectAId = projectA._id!.toString();
const projectBId = projectB._id!.toString();
await saveConvo(mockCtx, {
conversationId,
title: 'Bulk Moving',
endpoint: EModelEndpoint.openAI,
chatProjectId: projectAId,
});
await methods.bulkSaveConvos([
{
conversationId,
user: mockCtx.userId,
endpoint: EModelEndpoint.openAI,
chatProjectId: projectBId,
},
]);
const refreshedA = await ChatProject.findById(projectA._id).lean<IChatProject>();
const refreshedB = await ChatProject.findById(projectB._id).lean<IChatProject>();
expect(refreshedA?.conversationCount).toBe(0);
expect(refreshedB?.conversationCount).toBe(1);
});
it('should not create a conversation when noUpsert is true and conversation does not exist', async () => {
const nonExistentId = uuidv4();
const result = await saveConvo(
mockCtx,
{ conversationId: nonExistentId, title: 'Ghost Title' },
{ noUpsert: true },
);
expect(result).toBeNull();
const dbConvo = await Conversation.findOne({ conversationId: nonExistentId });
expect(dbConvo).toBeNull();
});
it('should update an existing conversation when noUpsert is true', async () => {
await saveConvo(mockCtx, mockConversationData);
const result = await saveConvo(
mockCtx,
{ conversationId: mockConversationData.conversationId, title: 'Updated Title' },
{ noUpsert: true },
);
expect(result).not.toBeNull();
expect(result?.title).toBe('Updated Title');
expect(result?.conversationId).toBe(mockConversationData.conversationId);
});
describe('generated title ownership', () => {
const generated = { titleSource: 'generated' as const, appendMessageIds: [] };
const manual = { titleSource: 'manual' as const, appendMessageIds: [] };
it('does not upsert a missing conversation', async () => {
const conversationId = uuidv4();
expect(
await saveConvo(mockCtx, { conversationId, title: 'Generated' }, generated),
).toBeNull();
expect(await Conversation.countDocuments({ conversationId })).toBe(0);
});
it.each(['Renamed', 'New Chat', ''])('preserves an explicit rename to %s', async (title) => {
const conversationId = uuidv4();
await saveConvo(mockCtx, { conversationId });
await saveConvo(mockCtx, { conversationId, title }, manual);
expect(
await saveConvo(mockCtx, { conversationId, title: 'Generated' }, generated),
).toBeNull();
expect((await getConvo(mockCtx.userId, conversationId))?.title).toBe(title);
await saveConvo(mockCtx, { conversationId, titleSetByUser: false });
expect(await saveConvo(mockCtx, { conversationId, title: 'Later' }, generated)).toBeNull();
});
it('projects manual title authority and unread intent while ordering repeated renames', async () => {
const conversationId = uuidv4();
await saveConvo(mockCtx, { conversationId });
await methods.markConvoUnread(mockCtx.userId, conversationId);
await Promise.all([
saveConvo(mockCtx, { conversationId, title: 'First' }, manual),
saveConvo(mockCtx, { conversationId, title: 'New Chat' }, manual),
]);
const current = await getConvo(mockCtx.userId, conversationId);
expect(current?.titleRevision).toBe(2);
expect(await methods.getConvoTitleState(mockCtx.userId, conversationId)).toEqual({
title: current?.title,
titleSetByUser: true,
titleRevision: 2,
});
expect(await methods.getConvoTitleState('another-owner', conversationId)).toBeNull();
const page = await getConvosByCursor(mockCtx.userId);
expect(page.conversations.find((row) => row.conversationId === conversationId)).toEqual(
expect.objectContaining({ titleSetByUser: true, titleRevision: 2, isMarkedUnread: true }),
);
await saveConvo(
mockCtx,
{ conversationId, titleRevision: 99, titleSetByUser: false },
{
unsetFields: { titleRevision: 1, titleSetByUser: 1 },
appendMessageIds: [],
},
);
expect(await getConvo(mockCtx.userId, conversationId)).toEqual(
expect.objectContaining({
titleSetByUser: true,
titleRevision: 2,
}),
);
});
it('preserves remembered approvals while claiming manual title ownership', async () => {
const conversationId = uuidv4();
await saveConvo(mockCtx, { conversationId });
await methods.addConvoToolApprovalAllows({
user: mockCtx.userId,
conversationId,
toolNames: ['kept'],
max: 64,
});
const stale = {
conversationId,
toolApprovalAllows: ['*'],
titleSetByUser: false,
titleRevision: 99,
};
const unsetFields = { toolApprovalAllows: 1, titleSetByUser: 1, titleRevision: 1 };
const saved = await saveConvo(
mockCtx,
{ ...stale, title: 'Renamed' },
{ ...manual, unsetFields },
);
expect(saved).toEqual(
expect.objectContaining({
title: 'Renamed',
titleSetByUser: true,
titleRevision: 1,
toolApprovalAllows: ['kept'],
}),
);
expect(
await saveConvo(mockCtx, { ...stale, title: 'Generated' }, { ...generated, unsetFields }),
).toBeNull();
expect(await getConvo(mockCtx.userId, conversationId)).toEqual(
expect.objectContaining({
title: 'Renamed',
titleSetByUser: true,
titleRevision: 1,
toolApprovalAllows: ['kept'],
}),
);
});
it('preserves renamed legacy rows without an ownership flag', async () => {
await saveConvo(mockCtx, mockConversationData);
expect(
await saveConvo(mockCtx, { ...mockConversationData, title: 'Generated' }, generated),
).toBeNull();
});
it('atomically preserves a rename that races generation', async () => {
const conversationId = uuidv4();
await saveConvo(mockCtx, { conversationId });
await Promise.all([
saveConvo(mockCtx, { conversationId, title: 'Generated' }, generated),
saveConvo(mockCtx, { conversationId, title: 'Renamed' }, manual),
]);
expect((await getConvo(mockCtx.userId, conversationId))?.title).toBe('Renamed');
});
it('publishes a generated title without moving activity or messages', async () => {
const conversationId = uuidv4();
const initial = await saveConvo(mockCtx, { conversationId });
const saved = await saveConvo(
mockCtx,
{ conversationId, title: 'Generated' },
{
...generated,
preserveUpdatedAt: true,
},
);
expect(saved?.title).toBe('Generated');
expect(saved?.updatedAt).toEqual(initial?.updatedAt);
expect(saved?.messages).toEqual(initial?.messages);
});
});
it('should still upsert by default when noUpsert is not provided', async () => {
const newId = uuidv4();
const result = await saveConvo(mockCtx, {
conversationId: newId,
title: 'New Conversation',
endpoint: EModelEndpoint.openAI,
});
expect(result).not.toBeNull();
expect(result?.conversationId).toBe(newId);
expect(result?.title).toBe('New Conversation');
});
it('should handle unsetFields metadata', async () => {
const metadata = {
unsetFields: { someField: 1 },
};
await saveConvo(mockCtx, mockConversationData, metadata);
const savedConvo = await Conversation.findOne<IConversation & { someField?: string }>({
conversationId: mockConversationData.conversationId,
});
expect(savedConvo?.someField).toBeUndefined();
});
it('should set createdAt from metadata only on insert', async () => {
const firstAnchor = new Date('2024-02-03T04:05:06.000Z');
const secondAnchor = new Date('2025-02-03T04:05:06.000Z');
const firstSave = await saveConvo(mockCtx, mockConversationData, {
createdAtOnInsert: firstAnchor,
});
const secondSave = await saveConvo(
mockCtx,
{ ...mockConversationData, title: 'Updated title' },
{ createdAtOnInsert: secondAnchor },
);
expect(new Date(firstSave?.createdAt ?? 0).toISOString()).toBe(firstAnchor.toISOString());
expect(new Date(secondSave?.createdAt ?? 0).toISOString()).toBe(firstAnchor.toISOString());
expect(secondSave?.title).toBe('Updated title');
});
it('preserves insert defaults and suppressed timestamps for an archive pipeline upsert', async () => {
const conversationId = uuidv4();
const firstAnchor = new Date('2024-02-03T04:05:06.000Z');
const secondAnchor = new Date('2025-02-03T04:05:06.000Z');
const firstSave = await saveConvo(
{ userId: 'user123' },
{ conversationId, isArchived: true },
{ createdAtOnInsert: firstAnchor, preserveUpdatedAt: true },
);
const secondSave = await saveConvo(
{ userId: 'user123' },
{ conversationId, isArchived: true },
{ createdAtOnInsert: secondAnchor, preserveUpdatedAt: true },
);
expect(firstSave?.title).toBe('New Chat');
expect(firstSave?.isTemporary).toBe(false);
expect(firstSave?.updatedAt ?? null).toBeNull();
expect(new Date(firstSave?.createdAt ?? 0).toISOString()).toBe(firstAnchor.toISOString());
expect(secondSave?.updatedAt ?? null).toBeNull();
expect(new Date(secondSave?.createdAt ?? 0).toISOString()).toBe(firstAnchor.toISOString());
expect(secondSave?.archivedAt).toEqual(firstSave?.archivedAt);
});
describe('preserveUpdatedAt', () => {
const anchor = new Date('2026-02-11T15:28:18.561Z');
const seedAgedConvo = async () => {
const conversationId = uuidv4();
await Conversation.collection.insertOne({
conversationId,
user: 'user123',
title: 'Date And Time Test',
endpoint: EModelEndpoint.openAI,
expiredAt: null,
isArchived: false,
createdAt: anchor,
updatedAt: anchor,
});
return conversationId;
};
/** Archiving files a chat away rather than touching it, and unarchiving has to
* restore it to its real place in the date groups. */
it('leaves updatedAt untouched across an archive and unarchive round trip', async () => {
const conversationId = await seedAgedConvo();
const archived = await saveConvo(
{ userId: 'user123' },
{ conversationId, isArchived: true },
{ preserveUpdatedAt: true, noUpsert: true },
);
const unarchived = await saveConvo(
{ userId: 'user123' },
{ conversationId, isArchived: false },
{ preserveUpdatedAt: true, noUpsert: true },
);
expect(archived?.isArchived).toBe(true);
expect(unarchived?.isArchived).toBe(false);
expect(new Date(archived?.updatedAt ?? 0).toISOString()).toBe(anchor.toISOString());
expect(new Date(unarchived?.updatedAt ?? 0).toISOString()).toBe(anchor.toISOString());
});
/** Opening an archived chat and hitting the archive shortcut (or a retried
* POST) sends isArchived: true again. That must not move Date Archived. */
it('keeps the original archivedAt when the chat is already archived', async () => {
const conversationId = uuidv4();
const original = new Date('2026-03-01T12:00:00.000Z');
await Conversation.collection.insertOne({
conversationId,
user: 'user123',
title: 'Already filed away',
endpoint: EModelEndpoint.openAI,
expiredAt: null,
isArchived: true,
archivedAt: original,
createdAt: original,
updatedAt: original,
});
const again = await saveConvo(
{ userId: 'user123' },
{
conversationId,
isArchived: true,
archivedAt: new Date('2026-08-15T21:00:00.000Z'),
},
{ preserveUpdatedAt: true, noUpsert: true },
);
expect(new Date(again?.archivedAt ?? 0).toISOString()).toBe(original.toISOString());
});
/** DocumentDB documents no support for pipeline-form updates on any engine
* version (`misc/documentdb/documentdb-compat.md`), so both archive transitions
* have to stay on plain update operators. */
it('archives with plain update operators rather than an aggregation pipeline', async () => {
const conversationId = uuidv4();
const original = new Date('2026-03-01T12:00:00.000Z');
await Conversation.collection.insertOne({
conversationId,
user: 'user123',
title: 'Plain operators only',
endpoint: EModelEndpoint.openAI,
expiredAt: null,
isArchived: false,
createdAt: original,
updatedAt: original,
});
const findOneAndUpdate = Conversation.collection.findOneAndUpdate.bind(
Conversation.collection,
);
const updates: Array<UpdateFilter<Document> | Document[]> = [];
const writeSpy = jest
.spyOn(Conversation.collection, 'findOneAndUpdate')
.mockImplementation(
async (
filter: Filter<Document>,
update: UpdateFilter<Document> | Document[],
options?: FindOneAndUpdateOptions,
) => {
updates.push(update);
return findOneAndUpdate(filter, update, options ?? {});
},
);
try {
const archived = await saveConvo(
{ userId: 'user123' },
{ conversationId, isArchived: true },
{ preserveUpdatedAt: true, noUpsert: true },
);
const unarchived = await saveConvo(
{ userId: 'user123' },
{ conversationId, isArchived: false },
{ preserveUpdatedAt: true, noUpsert: true },
);
expect(archived?.archivedAt).toBeInstanceOf(Date);
expect(unarchived?.archivedAt ?? null).toBeNull();
expect(updates.length).toBeGreaterThan(0);
for (const update of updates) {
expect(Array.isArray(update)).toBe(false);
}
} finally {
writeSpy.mockRestore();
}
});
/** Both conditional writes of the compare-and-set miss when an unarchive lands
* between them. The conversation still exists, so the route must not 404. */
it('does not report a missing chat when an unarchive splits the archive writes', async () => {
const conversationId = uuidv4();
const original = new Date('2026-03-01T12:00:00.000Z');
await Conversation.collection.insertOne({
conversationId,
user: 'user123',
title: 'Split archive',
endpoint: EModelEndpoint.openAI,
expiredAt: null,
isArchived: true,
archivedAt: original,
createdAt: original,
updatedAt: original,
});
const findOneAndUpdate = Conversation.collection.findOneAndUpdate.bind(
Conversation.collection,
);
let writeCount = 0;
const writeSpy = jest
.spyOn(Conversation.collection, 'findOneAndUpdate')
.mockImplementation(
async (
filter: Filter<Document>,
update: UpdateFilter<Document> | Document[],
options?: FindOneAndUpdateOptions,
) => {
writeCount += 1;
const result = await findOneAndUpdate(filter, update, options ?? {});
/** The transition write has just missed on an already archived chat.
* Unarchive it now so the already-archived write misses too. */
if (writeCount === 1) {
await Conversation.collection.updateOne(
{ conversationId },
{ $set: { isArchived: false, archivedAt: null } },
);
}
return result;
},
);
try {
const archived = await saveConvo(
{ userId: 'user123' },
{ conversationId, isArchived: true },
{ preserveUpdatedAt: true, noUpsert: true },
);
expect(archived).not.toBeNull();
expect(archived?.isArchived).toBe(true);
expect(archived?.archivedAt).toBeInstanceOf(Date);
} finally {
writeSpy.mockRestore();
}
});
/** Alternating requests can split every retry, and exhausting them still proves
* nothing about whether the chat exists, so it must not become a 404 either. */
it('does not report a missing chat when every archive retry is split', async () => {
const conversationId = uuidv4();
const original = new Date('2026-03-01T12:00:00.000Z');
await Conversation.collection.insertOne({
conversationId,
user: 'user123',
title: 'Perpetually split',
endpoint: EModelEndpoint.openAI,
expiredAt: null,
isArchived: true,
archivedAt: original,
createdAt: original,
updatedAt: original,
});
const findOneAndUpdate = Conversation.collection.findOneAndUpdate.bind(
Conversation.collection,
);
const writeSpy = jest
.spyOn(Conversation.collection, 'findOneAndUpdate')
.mockImplementation(
async (
filter: Filter<Document>,
update: UpdateFilter<Document> | Document[],
options?: FindOneAndUpdateOptions,
) => {
const result = await findOneAndUpdate(filter, update, options ?? {});
/** Flip the flag after every write so no transition write and no
* already-archived write can ever match. */
const archived = await Conversation.collection.findOne({ conversationId });
await Conversation.collection.updateOne(
{ conversationId },
{ $set: { isArchived: archived?.isArchived !== true } },
);
return result;
},
);
try {
const archived = await saveConvo(
{ userId: 'user123' },
{ conversationId, isArchived: true },
{ preserveUpdatedAt: true, noUpsert: true },
);
expect(archived).not.toBeNull();
expect(archived?.conversationId).toBe(conversationId);
} finally {
writeSpy.mockRestore();
}
});
it('stamps again when unarchive lands before a pending repeated archive write', async () => {
const conversationId = uuidv4();
const original = new Date('2026-03-01T12:00:00.000Z');
await Conversation.collection.insertOne({
conversationId,
user: 'user123',
title: 'Archive race',
endpoint: EModelEndpoint.openAI,
expiredAt: null,
isArchived: true,
archivedAt: original,
createdAt: original,
updatedAt: original,
});
let markArchiveWriteReached = () => {};
const archiveWriteReached = new Promise<void>((resolve) => {
markArchiveWriteReached = resolve;
});
let releaseArchiveWrite = () => {};
const archiveWriteBlocked = new Promise<void>((resolve) => {
releaseArchiveWrite = resolve;
});
const findOneAndUpdate = Conversation.collection.findOneAndUpdate.bind(
Conversation.collection,
);
let writeCount = 0;
const writeSpy = jest
.spyOn(Conversation.collection, 'findOneAndUpdate')
.mockImplementation(
async (
filter: Filter<Document>,
update: UpdateFilter<Document> | Document[],
options?: FindOneAndUpdateOptions,
) => {
writeCount += 1;
if (writeCount === 1) {
markArchiveWriteReached();
await archiveWriteBlocked;
}
return findOneAndUpdate(filter, update, options ?? {});
},
);
try {
const archive = saveConvo(
{ userId: 'user123' },
{ conversationId, isArchived: true },
{ preserveUpdatedAt: true, noUpsert: true },
);
await archiveWriteReached;
const unarchived = await saveConvo(
{ userId: 'user123' },
{ conversationId, isArchived: false },
{ preserveUpdatedAt: true, noUpsert: true },
);
releaseArchiveWrite();
const archived = await archive;
expect(unarchived?.isArchived).toBe(false);
expect(archived?.isArchived).toBe(true);
expect(archived?.archivedAt).toBeInstanceOf(Date);
expect(new Date(archived?.archivedAt ?? 0).toISOString()).not.toBe(
original.toISOString(),
);
} finally {
releaseArchiveWrite();
writeSpy.mockRestore();
}
});
it('stamps archivedAt on the first archive when the caller omits it', async () => {
const conversationId = await seedAgedConvo();
const before = Date.now();
const archived = await saveConvo(
{ userId: 'user123' },
{ conversationId, isArchived: true },
{ preserveUpdatedAt: true, noUpsert: true },
);
expect(archived?.archivedAt).toBeInstanceOf(Date);
expect(new Date(archived?.archivedAt ?? 0).getTime()).toBeGreaterThanOrEqual(before);
});
it('clears archivedAt on unarchive when the caller omits it', async () => {
const conversationId = uuidv4();
const original = new Date('2026-03-01T12:00:00.000Z');
await Conversation.collection.insertOne({
conversationId,
user: 'user123',
title: 'To restore',
endpoint: EModelEndpoint.openAI,
expiredAt: null,
isArchived: true,
archivedAt: original,
createdAt: original,
updatedAt: original,
});
const unarchived = await saveConvo(
{ userId: 'user123' },
{ conversationId, isArchived: false },
{ preserveUpdatedAt: true, noUpsert: true },
);
expect(unarchived?.archivedAt ?? null).toBeNull();
});
/** A pin carries a preserved older timestamp, so the project it belongs to must
* not be dragged back to it while the project holds newer conversations. */
it('does not drag a project pointer back when only metadata changes', async () => {
const project = await ChatProject.create({
user: 'user123',
name: 'Pinned project',
conversationCount: 0,
lastConversationAt: null,
lastConversationId: null,
});
const newer = uuidv4();
const older = uuidv4();
const newerAt = new Date('2026-08-01T00:00:00.000Z');
for (const [id, when] of [
[newer, newerAt],
[older, anchor],
] as Array<[string, Date]>) {
await Conversation.collection.insertOne({
conversationId: id,
user: 'user123',
title: id,
endpoint: EModelEndpoint.openAI,
expiredAt: null,
isArchived: false,
chatProjectId: String(project._id),
createdAt: when,
updatedAt: when,
});
}
await ChatProject.updateOne(
{ _id: project._id },
{
$set: {
conversationCount: 2,
lastConversationAt: newerAt,
lastConversationId: newer,
},
},
);
await saveConvo(
{ userId: 'user123' },
{ conversationId: older, pinned: true },
{ preserveUpdatedAt: true, noUpsert: true },
);
const after = await ChatProject.findById(project._id).lean<{
lastConversationAt: Date;
lastConversationId: string;
}>();
expect(new Date(after?.lastConversationAt ?? 0).toISOString()).toBe(newerAt.toISOString());
expect(after?.lastConversationId).toBe(newer);
});
/** Under RetentionMode.ALL a legacy chat also gets an isTemporary backfill after
* the main write; that second update has to stay silent too. */
it('keeps updatedAt through the retention backfill', async () => {
const conversationId = uuidv4();
await Conversation.collection.insertOne({
conversationId,
user: 'user123',
title: 'legacy chat with no isTemporary',
endpoint: EModelEndpoint.openAI,
expiredAt: null,
isArchived: false,
createdAt: anchor,
updatedAt: anchor,
});
const result = await saveConvo(
{
userId: 'user123',
interfaceConfig: { retentionMode: RetentionMode.ALL, temporaryChatRetention: 24 },
},
{ conversationId, isArchived: true },
{ preserveUpdatedAt: true, noUpsert: true },
);
expect(result?.isArchived).toBe(true);
const stored = await Conversation.findOne({ conversationId }).lean<IConversation>();
expect(new Date(stored?.updatedAt ?? 0).toISOString()).toBe(anchor.toISOString());
});
it('still bumps updatedAt for an ordinary save', async () => {
const conversationId = await seedAgedConvo();
const result = await saveConvo({ userId: 'user123' }, { conversationId, title: 'Renamed' });
expect(new Date(result?.updatedAt ?? 0).getTime()).toBeGreaterThan(anchor.getTime());
});
it('does not insert a timestampless conversation for an unknown id', async () => {
const result = await saveConvo(
{ userId: 'user123' },
{ conversationId: uuidv4(), isArchived: true },
{ preserveUpdatedAt: true, noUpsert: true },
);
expect(result).toBeNull();
});
});
describe('setConvoPinned', () => {
const anchor = new Date('2026-03-05T22:17:14.997Z');
const seedAgedConvo = async (user = 'user123') => {
const conversationId = uuidv4();
await Conversation.collection.insertOne({
conversationId,
user,
title: 'Living Room Light And Temperature',
endpoint: EModelEndpoint.openAI,
expiredAt: null,
isArchived: false,
messages: [],
createdAt: anchor,
updatedAt: anchor,
});
return conversationId;
};
it('pins a conversation without disturbing its timestamps', async () => {
const conversationId = await seedAgedConvo();
const result = await setConvoPinned('user123', conversationId, true);
expect(result?.pinned).toBe(true);
expect(result?.title).toBe('Living Room Light And Temperature');
expect(new Date(result?.updatedAt ?? 0).toISOString()).toBe(anchor.toISOString());
expect(new Date(result?.createdAt ?? 0).toISOString()).toBe(anchor.toISOString());
});
it('unpins a conversation without disturbing its timestamps', async () => {
const conversationId = await seedAgedConvo();
await setConvoPinned('user123', conversationId, true);
const result = await setConvoPinned('user123', conversationId, false);
expect(result?.pinned).toBe(false);
expect(new Date(result?.updatedAt ?? 0).toISOString()).toBe(anchor.toISOString());
});
/** The whole point of the dedicated method: a one-field toggle should not pay for
* `saveConvo`'s message-id read, nor rewrite the array it returns. */
it('does not read the conversation messages', async () => {
const conversationId = await seedAgedConvo();
await setConvoPinned('user123', conversationId, true);
expect(getMessages).not.toHaveBeenCalled();
});
it('leaves the stored message list alone', async () => {
const conversationId = await seedAgedConvo();
await Conversation.collection.updateOne(
{ conversationId },
{ $set: { messages: ['message-a', 'message-b'] } },
);
await setConvoPinned('user123', conversationId, true);
const stored = await Conversation.findOne({ conversationId }).lean<IConversation>();
expect(stored?.messages).toEqual(['message-a', 'message-b']);
});
it('returns null for an unknown id rather than inserting one', async () => {
const conversationId = uuidv4();
const result = await setConvoPinned('user123', conversationId, true);
expect(result).toBeNull();
expect(await Conversation.countDocuments({ conversationId })).toBe(0);
});
it('cannot pin another user’s conversation', async () => {
const conversationId = await seedAgedConvo('other-user');
const result = await setConvoPinned('user123', conversationId, true);
expect(result).toBeNull();
const stored = await Conversation.findOne({ conversationId }).lean<IConversation>();
expect(stored?.pinned).toBeUndefined();
});
});
});
describe('code approval persistence', () => {
it.each(['ask', 'acceptEdits', 'fullAccess', null, undefined] as const)(
'bulkSaveConvos ignores imported approval mode %s on insert',
async (codeApprovalMode) => {
const imported = {
...mockConversationData,
user: mockCtx.userId,
endpoint: EModelEndpoint.agents,
agent_id: 'imported-agent',
codeApprovalMode,
};
await methods.bulkSaveConvos([imported]);
const stored = await getConvo(mockCtx.userId, imported.conversationId);
expect(stored).not.toBeNull();
expect(stored).not.toHaveProperty('codeApprovalMode');
expect(stored).toMatchObject({
title: imported.title,
endpoint: EModelEndpoint.agents,
agent_id: imported.agent_id,
});
expect(imported.codeApprovalMode).toBe(codeApprovalMode);
},
);
it.each(['ask', 'acceptEdits', 'fullAccess', undefined] as const)(
'bulkSaveConvos preserves existing approval mode %s on update',
async (codeApprovalMode) => {
const conversationId = uuidv4();
await saveConvo(mockCtx, {
conversationId,
endpoint: EModelEndpoint.agents,
...(codeApprovalMode != null && { codeApprovalMode }),
});
await methods.bulkSaveConvos([
{
conversationId,
user: mockCtx.userId,
title: 'Imported update',
codeApprovalMode: 'fullAccess',
},
]);
const stored = await getConvo(mockCtx.userId, conversationId);
expect(stored).not.toBeNull();
expect(stored?.codeApprovalMode).toBe(codeApprovalMode);
expect(stored?.title).toBe('Imported update');
},
);
it('persists explicit user choices through ordinary saves after an import', async () => {
const conversationId = uuidv4();
await methods.bulkSaveConvos([
{
conversationId,
user: mockCtx.userId,
endpoint: EModelEndpoint.agents,
codeApprovalMode: 'fullAccess',
},
]);
for (const codeApprovalMode of ['ask', 'acceptEdits', 'fullAccess'] as const) {
await saveConvo(mockCtx, { conversationId, codeApprovalMode });
await saveConvo(mockCtx, { conversationId, title: 'Ordinary save' });
expect((await getConvo(mockCtx.userId, conversationId))?.codeApprovalMode).toBe(
codeApprovalMode,
);
}
});
});
describe('code environment persistence during ordinary saves', () => {
const mac = { environmentId: 'code-mac', workspaceId: 'primary' };
const vm = { environmentId: 'code-vm', workspaceId: 'primary' };
const userId = 'user123';
const unsetFields = { codeEnvironmentMode: 1, codeWorkspaces: 1 };
it.each(['source', 'isolated'] as const)(
'preserves the %s checkout through save, reload and a stale save',
async (checkout) => {
const conversationId = uuidv4();
const codeWorkspaces = [{ ...mac, checkout }];
await saveConvo(
{ userId },
{ conversationId, codeEnvironmentMode: 'attached', codeWorkspaces },
);
expect((await getConvo(userId, conversationId))?.codeWorkspaces).toEqual(codeWorkspaces);
await saveConvo({ userId }, { conversationId, codeWorkspaces: [mac], title: 'Later save' });
expect(
(await methods.readAdmittedConvoCodeEnvironmentDecision(userId, conversationId))
?.codeWorkspaces,
).toEqual(codeWorkspaces);
},
);
it('lists the code decision, so a row can tell a code conversation from an ordinary one', async () => {
const conversationId = uuidv4();
const plainId = uuidv4();
const codeWorkspaces = [mac];
await saveConvo(
{ userId },
{ conversationId, codeEnvironmentMode: 'attached', codeWorkspaces },
);
await saveConvo({ userId }, { conversationId: plainId });
const { conversations } = await getConvosByCursor(userId);
expect(conversations.find((row) => row.conversationId === conversationId)).toEqual(
expect.objectContaining({ codeEnvironmentMode: 'attached', codeWorkspaces }),
);
expect(conversations.find((row) => row.conversationId === plainId)).not.toHaveProperty(
'codeEnvironmentMode',
);
expect(conversations.every((row) => row.codeDecisionListed === true)).toBe(true);
});
it('preserves explicit agent ownership through save, reload and a stale ordinary save', async () => {
const conversationId = uuidv4();
const codeWorkspaces = [{ ...mac, agentIds: ['primary', 'reviewer'] }];
await saveConvo(
{ userId },
{ conversationId, codeEnvironmentMode: 'attached', codeWorkspaces },
);
expect((await getConvo(userId, conversationId))?.codeWorkspaces).toEqual(codeWorkspaces);
await saveConvo(
{ userId },
{ conversationId, codeEnvironmentMode: 'attached', codeWorkspaces: [vm] },
);
expect(
(await methods.readAdmittedConvoCodeEnvironmentDecision(userId, conversationId))
?.codeWorkspaces,
).toEqual(codeWorkspaces);
});
it.each([
{ codeEnvironmentMode: 'attached', codeWorkspaces: [mac] },
{ codeEnvironmentMode: 'without_attached' },
])(
'preserves $codeEnvironmentMode through an approval pause and later saves',
async (decision) => {
const conversationId = uuidv4();
await saveConvo({ userId }, { conversationId, ...decision });
for (const title of ['Approval required', 'Resumed', 'Completed']) {
await saveConvo({ userId }, { conversationId, title }, { unsetFields });
const stored = await getConvo(userId, conversationId);
expect(stored?.codeEnvironmentMode).toBe(decision.codeEnvironmentMode);
expect(stored?.codeWorkspaces).toEqual(decision.codeWorkspaces);
expect(stored?.title).toBe(title);
}
},
);
it('cannot overwrite an explicit move with a stale turn-start snapshot', async () => {
const conversationId = uuidv4();
const decision = { codeEnvironmentMode: 'attached' as const, codeWorkspaces: [mac] };
await saveConvo({ userId }, { conversationId, ...decision });
await methods.replaceConvoCodeEnvironmentDecision({
user: userId,
conversationId,
expected: decision,
codeEnvironmentMode: 'attached',
codeWorkspaces: [vm],
});
await saveConvo({ userId }, { conversationId, ...decision });
expect((await getConvo(userId, conversationId))?.codeWorkspaces).toEqual([vm]);
await saveConvo(
{ userId },
{ conversationId, codeEnvironmentMode: null, codeWorkspaces: [] },
);
const stored = await getConvo(userId, conversationId);
expect(stored?.codeEnvironmentMode).toBe('attached');
expect(stored?.codeWorkspaces).toEqual([vm]);
});
it('seeds imported decisions without letting repeated imports undo a move', async () => {
const conversationId = uuidv4();
const decision = { codeEnvironmentMode: 'attached' as const, codeWorkspaces: [mac] };
const imported = { conversationId, user: userId, ...decision };
await methods.bulkSaveConvos([imported]);
expect((await getConvo(userId, conversationId))?.codeWorkspaces).toEqual([mac]);
await methods.replaceConvoCodeEnvironmentDecision({
user: userId,
conversationId,
expected: decision,
codeEnvironmentMode: 'attached',
codeWorkspaces: [vm],
});
await methods.bulkSaveConvos([imported]);
const stored = await getConvo(userId, conversationId);
expect(stored?.codeEnvironmentMode).toBe('attached');
expect(stored?.codeWorkspaces).toEqual([vm]);
});
it('preserves a legacy decision', async () => {
const conversationId = uuidv4();
await Conversation.collection.insertOne({
conversationId,
user: userId,
codeWorkspaces: [mac],
});
await saveConvo(
{ userId },
{ conversationId, codeEnvironmentMode: 'attached', codeWorkspaces: [vm] },
{ unsetFields },
);
const stored = await getConvo(userId, conversationId);
expect(stored?.codeEnvironmentMode).toBeUndefined();
expect(stored?.codeWorkspaces).toEqual([mac]);
});
it('records the first decision of a saved chat that holds none', async () => {
const conversationId = uuidv4();
await Conversation.collection.insertOne({ conversationId, user: userId, title: 'Saved' });
const saved = await saveConvo(
{ userId },
{ conversationId, codeEnvironmentMode: 'attached', codeWorkspaces: [mac] },
{ unsetFields },
);
expect(saved?.codeEnvironmentMode).toBe('attached');
expect(saved?.codeWorkspaces).toEqual([mac]);
const stored = await getConvo(userId, conversationId);
expect(stored?.codeEnvironmentMode).toBe('attached');
expect(stored?.codeWorkspaces).toEqual([mac]);
});
it('keeps the decision it recorded when a later turn resolves another', async () => {
const conversationId = uuidv4();
await Conversation.collection.insertOne({ conversationId, user: userId, title: 'Saved' });
await saveConvo(
{ userId },
{ conversationId, codeEnvironmentMode: 'attached', codeWorkspaces: [mac] },
{ unsetFields },
);
await saveConvo(
{ userId },
{ conversationId, codeEnvironmentMode: 'without_attached', codeWorkspaces: [vm] },
{ unsetFields },
);
const stored = await getConvo(userId, conversationId);
expect(stored?.codeEnvironmentMode).toBe('attached');
expect(stored?.codeWorkspaces).toEqual([mac]);
});
it('leaves a chat undecided when a save carries selections without a mode', async () => {
const conversationId = uuidv4();
await Conversation.collection.insertOne({ conversationId, user: userId, title: 'Saved' });
await saveConvo({ userId }, { conversationId, codeWorkspaces: [vm] }, { unsetFields });
const stored = await getConvo(userId, conversationId);
expect(stored?.codeEnvironmentMode).toBeUndefined();
expect(stored?.codeWorkspaces).toBeUndefined();
});
});
describe('replaceConvoCodeEnvironmentDecision', () => {
const anchor = new Date('2026-09-12T11:22:22.976Z');
const mac = { environmentId: 'code-mac', workspaceId: 'primary' };
const team = { environmentId: 'code-team', workspaceId: 'shared' };
const vm = { environmentId: 'code-vm', workspaceId: 'projects' };
/** Raw inserts bypass Mongoose casting, the way legacy rows and operator repairs are stored. */
const seedDecision = async (decision: Record<string, unknown>, user = 'user123') => {
const conversationId = uuidv4();
await Conversation.collection.insertOne({
conversationId,
user,
title: 'Mortgage analysis',
endpoint: EModelEndpoint.agents,
messages: [],
createdAt: anchor,
updatedAt: anchor,
...decision,
});
return conversationId;
};
const moveFromStored = async (
conversationId: string,
codeWorkspaces: NonNullable<IConversation['codeWorkspaces']>,
user = 'user123',
) => {
const stored = await methods.getConvoCodeEnvironmentDecision('user123', conversationId);
return methods.replaceConvoCodeEnvironmentDecision({
user,
conversationId,
expected: {
codeEnvironmentMode: stored?.codeEnvironmentMode,
codeWorkspaces: stored?.codeWorkspaces,
codeEnvironmentRevision: stored?.codeEnvironmentRevision,
},
codeEnvironmentMode: 'attached',
codeWorkspaces,
});
};
describe('stale lane state', () => {
const lane = { branch: 'feat/old', head: 'a'.repeat(40), repo: 'o/old' };
const stored = (conversationId: string) =>
methods.getConvoCodeEnvironmentDecision('user123', conversationId);
it('is cleared when the chat moves to another workspace', async () => {
const conversationId = await seedDecision({
codeEnvironmentMode: 'attached',
codeWorkspaces: [mac],
laneGit: lane,
});
await expect(methods.getConvoLaneGit('user123', conversationId)).resolves.toEqual(lane);
await moveFromStored(conversationId, [team]);
await expect(methods.getConvoLaneGit('user123', conversationId)).resolves.toBeNull();
});
it('is cleared when the chat leaves attached execution', async () => {
const conversationId = await seedDecision({
codeEnvironmentMode: 'attached',
codeWorkspaces: [mac],
laneGit: lane,
});
const decision = await stored(conversationId);
await methods.replaceConvoCodeEnvironmentDecision({
user: 'user123',
conversationId,
expected: {
codeEnvironmentMode: decision?.codeEnvironmentMode,
codeWorkspaces: decision?.codeWorkspaces,
codeEnvironmentRevision: decision?.codeEnvironmentRevision,
},
codeEnvironmentMode: 'without_attached',
});
await expect(methods.getConvoLaneGit('user123', conversationId)).resolves.toBeNull();
});
it('is kept when the move is refused', async () => {
const conversationId = await seedDecision({
codeEnvironmentMode: 'attached',
codeWorkspaces: [mac],
laneGit: lane,
});
await methods.replaceConvoCodeEnvironmentDecision({
user: 'user123',
conversationId,
expected: {
codeEnvironmentMode: 'attached',
codeWorkspaces: [team],
codeEnvironmentRevision: 99,
},
codeEnvironmentMode: 'attached',
codeWorkspaces: [vm],
});
await expect(methods.getConvoLaneGit('user123', conversationId)).resolves.toEqual(lane);
});
});
it('replaces the decision it read without disturbing timestamps', async () => {
const conversationId = await seedDecision({
codeEnvironmentMode: 'attached',
codeWorkspaces: [mac, team],
});
const result = await moveFromStored(conversationId, [team, vm]);
expect(result?.codeEnvironmentMode).toBe('attached');
expect(result?.codeWorkspaces).toEqual([team, vm]);
expect(new Date(result?.updatedAt ?? 0).toISOString()).toBe(anchor.toISOString());
});
it('replaces a legacy decision stored without a mode', async () => {
const conversationId = await seedDecision({ codeWorkspaces: [mac] });
const result = await moveFromStored(conversationId, [vm]);
expect(result?.codeEnvironmentMode).toBe('attached');
expect(result?.codeWorkspaces).toEqual([vm]);
});
it('replaces a decision that saveConvo persisted', async () => {
const conversationId = uuidv4();
await saveConvo(
{ userId: 'user123' },
{
conversationId,
endpoint: EModelEndpoint.agents,
codeEnvironmentMode: 'attached',
codeWorkspaces: [mac, team],
},
);
expect((await getConvo('user123', conversationId))?.codeWorkspaces).toEqual([mac, team]);
const result = await moveFromStored(conversationId, [vm]);
expect(result?.codeWorkspaces).toEqual([vm]);
});
it('advances the revision and returns the snapshot in one database round trip', async () => {
const conversationId = await seedDecision({
codeEnvironmentMode: 'attached',
codeWorkspaces: [mac],
});
const update = jest.spyOn(Conversation.collection, 'findOneAndUpdate');
const read = jest.spyOn(Conversation.collection, 'findOne');
try {
const result = await methods.readAdmittedConvoCodeEnvironmentDecision(
'user123',
conversationId,
);
expect(result?.codeWorkspaces).toEqual([mac]);
expect(update).toHaveBeenCalledTimes(1);
expect(read).not.toHaveBeenCalled();
} finally {
update.mockRestore();
read.mockRestore();
}
});
it('rejects a transition when an admitted run reads after the idle check', async () => {
const conversationId = await seedDecision({
codeEnvironmentMode: 'attached',
codeWorkspaces: [mac],
});
const snapshot = await methods.getConvoCodeEnvironmentDecision('user123', conversationId);
const admitted = await methods.readAdmittedConvoCodeEnvironmentDecision(
'user123',
conversationId,
);
expect(admitted?.codeWorkspaces).toEqual([mac]);
expect(
await methods.replaceConvoCodeEnvironmentDecision({
user: 'user123',
conversationId,
expected: snapshot!,
codeEnvironmentMode: 'attached',
codeWorkspaces: [vm],
}),
).toBeNull();
expect((await getConvo('user123', conversationId))?.codeWorkspaces).toEqual([mac]);
});
it('gives an admitted run the new decision when the transition wins first', async () => {
const conversationId = await seedDecision({
codeEnvironmentMode: 'attached',
codeWorkspaces: [mac],
});
const snapshot = await methods.getConvoCodeEnvironmentDecision('user123', conversationId);
expect(
await methods.replaceConvoCodeEnvironmentDecision({
user: 'user123',
conversationId,
expected: snapshot!,
codeEnvironmentMode: 'attached',
codeWorkspaces: [vm],
}),
).not.toBeNull();
const admitted = await methods.readAdmittedConvoCodeEnvironmentDecision(
'user123',
conversationId,
);
expect(admitted?.codeWorkspaces).toEqual([vm]);
expect(admitted).not.toHaveProperty('codeEnvironmentRevision');
const current = await getConvo('user123', conversationId);
expect(current).not.toHaveProperty('codeEnvironmentRevision');
expect(new Date(current?.updatedAt ?? 0).toISOString()).toBe(anchor.toISOString());
});
it("does not advance another tenant's decision revision", async () => {
const conversationId = await seedDecision({
codeEnvironmentMode: 'attached',
codeWorkspaces: [mac],
tenantId: 'tenant-a',
});
const other = await tenantStorage.run({ tenantId: 'tenant-b' }, () =>
methods.readAdmittedConvoCodeEnvironmentDecision('user123', conversationId),
);
expect(other).toBeNull();
const own = await tenantStorage.run({ tenantId: 'tenant-a' }, () =>
methods.readAdmittedConvoCodeEnvironmentDecision('user123', conversationId),
);
expect(own?.codeWorkspaces).toEqual([mac]);
const raw = await Conversation.collection.findOne({ conversationId });
expect(raw?.codeEnvironmentRevision).toBe(1);
});
it('protects the revision from ordinary saves, imports and other users', async () => {
const conversationId = await seedDecision({
codeEnvironmentMode: 'attached',
codeWorkspaces: [mac],
});
await methods.readAdmittedConvoCodeEnvironmentDecision('user123', conversationId);
const before = await methods.getConvoCodeEnvironmentDecision('user123', conversationId);
await saveConvo(
{ userId: 'user123' },
{ conversationId, codeEnvironmentRevision: 999 },
{ unsetFields: { codeEnvironmentRevision: 1 } },
);
await methods.bulkSaveConvos([
{ conversationId, user: 'user123', codeEnvironmentRevision: 0 },
]);
expect(
(await methods.getConvoCodeEnvironmentDecision('user123', conversationId))
?.codeEnvironmentRevision,
).toBe(before?.codeEnvironmentRevision);
expect(
await methods.readAdmittedConvoCodeEnvironmentDecision('someone-else', conversationId),
).toBeNull();
});
it('attaches an environment to a chat stored without one', async () => {
const conversationId = await seedDecision({ codeEnvironmentMode: 'without_attached' });
const result = await methods.replaceConvoCodeEnvironmentDecision({
user: 'user123',
conversationId,
expected: { codeEnvironmentMode: 'without_attached' },
codeEnvironmentMode: 'attached',
codeWorkspaces: [vm],
});
expect(result?.codeEnvironmentMode).toBe('attached');
expect(result?.codeWorkspaces).toEqual([vm]);
});
it('clears the selections when a chat leaves attached execution', async () => {
const conversationId = await seedDecision({
codeEnvironmentMode: 'attached',
codeWorkspaces: [mac, team],
});
const result = await methods.replaceConvoCodeEnvironmentDecision({
user: 'user123',
conversationId,
expected: { codeEnvironmentMode: 'attached', codeWorkspaces: [mac, team] },
codeEnvironmentMode: 'without_attached',
});
expect(result?.codeEnvironmentMode).toBe('without_attached');
/** Keeping them would read as an attached decision again on the next turn. */
expect(result?.codeWorkspaces).toBeUndefined();
const stored = await getConvo('user123', conversationId);
expect(stored?.codeWorkspaces).toBeUndefined();
expect(new Date(stored?.updatedAt ?? 0).toISOString()).toBe(anchor.toISOString());
});
it('leaves a decision that changed after it was read untouched', async () => {
const conversationId = await seedDecision({
codeEnvironmentMode: 'attached',
codeWorkspaces: [mac],
});
const stored = await getConvo('user123', conversationId);
await Conversation.collection.updateOne(
{ conversationId },
{ $set: { codeWorkspaces: [team] } },
);
const result = await methods.replaceConvoCodeEnvironmentDecision({
user: 'user123',
conversationId,
expected: {
codeEnvironmentMode: stored?.codeEnvironmentMode,
codeWorkspaces: stored?.codeWorkspaces,
codeEnvironmentRevision: stored?.codeEnvironmentRevision,
},
codeEnvironmentMode: 'attached',
codeWorkspaces: [vm],
});
expect(result).toBeNull();
const current = await getConvo('user123', conversationId);
expect(current?.codeWorkspaces).toEqual([team]);
});
it('does not treat a reordered selection list as the decision it read', async () => {
const conversationId = await seedDecision({
codeEnvironmentMode: 'attached',
codeWorkspaces: [mac, team],
});
const result = await methods.replaceConvoCodeEnvironmentDecision({
user: 'user123',
conversationId,
expected: { codeEnvironmentMode: 'attached', codeWorkspaces: [team, mac] },
codeEnvironmentMode: 'attached',
codeWorkspaces: [vm],
});
expect(result).toBeNull();
});
it('cannot move another user’s conversation', async () => {
const conversationId = await seedDecision(
{ codeEnvironmentMode: 'attached', codeWorkspaces: [mac] },
'other-user',
);
const result = await methods.replaceConvoCodeEnvironmentDecision({
user: 'user123',
conversationId,
expected: { codeEnvironmentMode: 'attached', codeWorkspaces: [mac] },
codeEnvironmentMode: 'attached',
codeWorkspaces: [vm],
});
expect(result).toBeNull();
const stored = await Conversation.findOne({ conversationId }).lean<IConversation>();
expect(stored?.codeWorkspaces).toEqual([mac]);
});
});
describe('saveConvo appendMessageIds', () => {
const ctx = { userId: 'append-user' };
const conversationId = 'append-conversation';
beforeEach(async () => {
await Conversation.deleteMany({ user: ctx.userId });
getMessages.mockClear();
});
it('appends the provided ids without reading the messages collection', async () => {
const seeded = [new mongoose.Types.ObjectId(), new mongoose.Types.ObjectId()];
getMessages.mockResolvedValueOnce(seeded.map((_id) => ({ _id })));
await saveConvo(ctx, { conversationId, title: 'seeded' });
expect(getMessages).toHaveBeenCalledTimes(1);
const appended = new mongoose.Types.ObjectId();
const result = await saveConvo(
ctx,
{ conversationId, title: 'appended' },
{ appendMessageIds: [appended] },
);
expect(getMessages).toHaveBeenCalledTimes(1);
expect(result?.title).toBe('appended');
const stored = await Conversation.findOne({ conversationId }).lean();
expect(stored?.messages?.map(String)).toEqual([...seeded, appended].map(String));
});
it('keeps response references when an explicit rename lands concurrently', async () => {
const userMessage = new mongoose.Types.ObjectId();
const responseMessage = new mongoose.Types.ObjectId();
await saveConvo(ctx, { conversationId }, { appendMessageIds: [userMessage] });
await Promise.all([
saveConvo(
ctx,
{ conversationId, title: 'Renamed while running' },
{
titleSource: 'manual',
appendMessageIds: [],
},
),
saveConvo(ctx, { conversationId }, { appendMessageIds: [responseMessage] }),
]);
const stored = await getConvo(ctx.userId, conversationId);
expect(stored?.messages?.map(String)).toEqual([userMessage, responseMessage].map(String));
expect(stored?.title).toBe('Renamed while running');
expect(getMessages).not.toHaveBeenCalled();
});
it('does not duplicate an id that is already recorded', async () => {
const id = new mongoose.Types.ObjectId();
await saveConvo(ctx, { conversationId }, { appendMessageIds: [id] });
await saveConvo(ctx, { conversationId }, { appendMessageIds: [id] });
const stored = await Conversation.findOne({ conversationId }).lean();
expect(stored?.messages?.map(String)).toEqual([String(id)]);
expect(getMessages).not.toHaveBeenCalled();
});
it('creates the conversation with the appended id when it does not exist yet', async () => {
const id = new mongoose.Types.ObjectId();
const result = await saveConvo(
ctx,
{ conversationId, title: 'first turn' },
{ appendMessageIds: [id] },
);
expect(result?.conversationId).toBe(conversationId);
const stored = await Conversation.findOne({ conversationId }).lean();
expect(stored?.messages?.map(String)).toEqual([String(id)]);
expect(getMessages).not.toHaveBeenCalled();
});
it('ignores a caller-supplied messages field so $set cannot conflict with the append', async () => {
const kept = new mongoose.Types.ObjectId();
await saveConvo(ctx, { conversationId }, { appendMessageIds: [kept] });
const appended = new mongoose.Types.ObjectId();
await saveConvo(
ctx,
{ conversationId, messages: [new mongoose.Types.ObjectId()] },
{ appendMessageIds: [appended] },
);
const stored = await Conversation.findOne({ conversationId }).lean();
expect(stored?.messages?.map(String)).toEqual([kept, appended].map(String));
});
it('still rebuilds the array from the database when the option is absent', async () => {
const rebuilt = [new mongoose.Types.ObjectId()];
getMessages.mockResolvedValueOnce(rebuilt.map((_id) => ({ _id })));
await saveConvo(ctx, { conversationId, title: 'rebuild' });
expect(getMessages).toHaveBeenCalledWith({ conversationId, user: ctx.userId }, '_id');
const stored = await Conversation.findOne({ conversationId }).lean();
expect(stored?.messages?.map(String)).toEqual(rebuilt.map(String));
});
/** An empty append is how a metadata-only write asks for the title (or any other
* field) to land without the array being rebuilt underneath it. */
it('leaves the array untouched when the append is empty', async () => {
const existing = new mongoose.Types.ObjectId();
await saveConvo(ctx, { conversationId }, { appendMessageIds: [existing] });
getMessages.mockClear();
await saveConvo(ctx, { conversationId, title: 'metadata only' }, { appendMessageIds: [] });
expect(getMessages).not.toHaveBeenCalled();
const stored = await Conversation.findOne({ conversationId }).lean();
expect(stored?.title).toBe('metadata only');
expect(stored?.messages?.map(String)).toEqual([String(existing)]);
});
/** The concurrency an immediate-mode title introduced: it saves while the turn is
* still running, so its write and the response's own append overlap. A title that
* rebuilt the array from a snapshot taken before the response existed erased the
* response's id permanently — nothing later re-adds it. Asking for no messages at
* all is what makes the interleaving irrelevant. */
it('keeps a concurrently appended id when a metadata-only write overlaps it', async () => {
const userMessage = new mongoose.Types.ObjectId();
await saveConvo(ctx, { conversationId }, { appendMessageIds: [userMessage] });
/** What a rebuilding write would have read: the turn before the response. The
* outer `beforeEach` restores the default, so this cannot leak. */
getMessages.mockResolvedValue([{ _id: userMessage }]);
getMessages.mockClear();
const responseMessage = new mongoose.Types.ObjectId();
await Promise.all([
saveConvo(ctx, { conversationId, title: 'generated mid-turn' }, { appendMessageIds: [] }),
saveConvo(ctx, { conversationId }, { appendMessageIds: [responseMessage] }),
]);
const stored = await Conversation.findOne({ conversationId }).lean();
expect(stored?.title).toBe('generated mid-turn');
expect(stored?.messages?.map(String)).toEqual([userMessage, responseMessage].map(String));
/** No snapshot was taken, so there was no window to lose the append in. */
expect(getMessages).not.toHaveBeenCalled();
});
});
describe('appendConvoMessageReference', () => {
const ctx = { userId: 'append-ref-user' };
const conversationId = 'append-ref-conversation';
const appendConvoMessageReference = (
...args: Parameters<ConversationMethods['appendConvoMessageReference']>
) => methods.appendConvoMessageReference(...args);
beforeEach(async () => {
await Conversation.deleteMany({});
getMessages.mockClear();
});
it('appends the id without reading or rewriting the message array', async () => {
const existing = new mongoose.Types.ObjectId();
await saveConvo(ctx, { conversationId, title: 'seeded' }, { appendMessageIds: [existing] });
getMessages.mockClear();
const recovered = new mongoose.Types.ObjectId();
const row = await appendConvoMessageReference(ctx.userId, conversationId, String(recovered));
expect(row?.messages?.map(String)).toEqual([existing, recovered].map(String));
expect(getMessages).not.toHaveBeenCalled();
});
it('does not duplicate an id the conversation already references', async () => {
const id = new mongoose.Types.ObjectId();
await saveConvo(ctx, { conversationId }, { appendMessageIds: [id] });
await appendConvoMessageReference(ctx.userId, conversationId, String(id));
await appendConvoMessageReference(ctx.userId, conversationId, String(id));
const stored = await Conversation.findOne({ conversationId }).lean();
expect(stored?.messages?.map(String)).toEqual([String(id)]);
});
/** Repairing a reference is not activity: the sidebar orders by `updatedAt`, and
* hoisting an untouched chat to Today would be a visible lie. */
it('leaves updatedAt alone', async () => {
await saveConvo(ctx, { conversationId }, { appendMessageIds: [] });
const before = await Conversation.findOne({ conversationId }).lean();
await appendConvoMessageReference(
ctx.userId,
conversationId,
String(new mongoose.Types.ObjectId()),
);
const after = await Conversation.findOne({ conversationId }).lean();
expect(after?.updatedAt?.getTime()).toBe(before?.updatedAt?.getTime());
});
it('never inserts a conversation that does not exist', async () => {
const row = await appendConvoMessageReference(
ctx.userId,
'no-such-conversation',
String(new mongoose.Types.ObjectId()),
);
expect(row).toBeNull();
expect(
await Conversation.findOne({ conversationId: 'no-such-conversation' }).lean(),
).toBeNull();
});
/** The repair runs on a turn's own behalf, so it must never reach another owner's row. */
it("cannot touch another owner's conversation", async () => {
const owner = new mongoose.Types.ObjectId();
await saveConvo(ctx, { conversationId }, { appendMessageIds: [owner] });
const row = await appendConvoMessageReference(
'someone-else',
conversationId,
String(new mongoose.Types.ObjectId()),
);
expect(row).toBeNull();
const stored = await Conversation.findOne({ conversationId }).lean();
expect(stored?.messages?.map(String)).toEqual([String(owner)]);
});
it('ignores an id the store could never hold', async () => {
await saveConvo(ctx, { conversationId }, { appendMessageIds: [] });
const row = await appendConvoMessageReference(ctx.userId, conversationId, 'not-an-id');
expect(row).toBeNull();
const stored = await Conversation.findOne({ conversationId }).lean();
expect(stored?.messages ?? []).toEqual([]);
});
});
describe('isTemporary conversation handling', () => {
it('should save a conversation with expiredAt when isTemporary is true', async () => {
mockCtx.interfaceConfig = { temporaryChatRetention: 24 };
mockCtx.isTemporary = true;
const beforeSave = new Date();
const result = await saveConvo(mockCtx, mockConversationData);
const afterSave = new Date();
expect(result?.conversationId).toBe(mockConversationData.conversationId);
expect(result?.expiredAt).toBeDefined();
expect(result?.expiredAt).toBeInstanceOf(Date);
const expectedExpirationTime = new Date(beforeSave.getTime() + 24 * 60 * 60 * 1000);
const actualExpirationTime = new Date(result?.expiredAt ?? 0);
expect(actualExpirationTime.getTime()).toBeGreaterThanOrEqual(
expectedExpirationTime.getTime() - 1000,
);
expect(actualExpirationTime.getTime()).toBeLessThanOrEqual(
new Date(afterSave.getTime() + 24 * 60 * 60 * 1000 + 1000).getTime(),
);
});
it('preserves an exact inherited expiration instead of recomputing retention', async () => {
const inheritedExpiration = new Date('2026-08-22T03:04:05.000Z');
mockCtx.isTemporary = true;
mockCtx.expiredAt = inheritedExpiration;
mockCtx.interfaceConfig = { temporaryChatRetention: 48 };
const result = await saveConvo(mockCtx, mockConversationData);
expect(result?.isTemporary).toBe(true);
expect(result?.expiredAt).toEqual(inheritedExpiration);
});
it('should save a conversation without expiredAt when isTemporary is false', async () => {
mockCtx.isTemporary = false;
const result = await saveConvo(mockCtx, mockConversationData);
expect(result?.conversationId).toBe(mockConversationData.conversationId);
expect(result?.expiredAt).toBeNull();
});
it('should save a conversation without expiredAt when isTemporary is not provided', async () => {
mockCtx.isTemporary = undefined;
const result = await saveConvo(mockCtx, mockConversationData);
expect(result?.conversationId).toBe(mockConversationData.conversationId);
expect(result?.expiredAt).toBeUndefined();
});
it('should use custom retention period from config', async () => {
mockCtx.interfaceConfig = { temporaryChatRetention: 48 };
mockCtx.isTemporary = true;
const beforeSave = new Date();
const result = await saveConvo(mockCtx, mockConversationData);
expect(result?.expiredAt).toBeDefined();
// Verify expiredAt is approximately 48 hours in the future
const expectedExpirationTime = new Date(beforeSave.getTime() + 48 * 60 * 60 * 1000);
const actualExpirationTime = new Date(result?.expiredAt ?? 0);
expect(actualExpirationTime.getTime()).toBeGreaterThanOrEqual(
expectedExpirationTime.getTime() - 1000,
);
expect(actualExpirationTime.getTime()).toBeLessThanOrEqual(
expectedExpirationTime.getTime() + 1000,
);
});
it('should handle minimum retention period (1 hour)', async () => {
// Mock app config with less than minimum retention
mockCtx.interfaceConfig = { temporaryChatRetention: 0.5 }; // Half hour - should be clamped to 1 hour
mockCtx.isTemporary = true;
const beforeSave = new Date();
const result = await saveConvo(mockCtx, mockConversationData);
expect(result?.expiredAt).toBeDefined();
// Verify expiredAt is approximately 1 hour in the future (minimum)
const expectedExpirationTime = new Date(beforeSave.getTime() + 1 * 60 * 60 * 1000);
const actualExpirationTime = new Date(result?.expiredAt ?? 0);
expect(actualExpirationTime.getTime()).toBeGreaterThanOrEqual(
expectedExpirationTime.getTime() - 1000,
);
expect(actualExpirationTime.getTime()).toBeLessThanOrEqual(
expectedExpirationTime.getTime() + 1000,
);
});
it('should handle maximum retention period (8760 hours)', async () => {
// Mock app config with more than maximum retention
mockCtx.interfaceConfig = { temporaryChatRetention: 10000 }; // Should be clamped to 8760 hours
mockCtx.isTemporary = true;
const beforeSave = new Date();
const result = await saveConvo(mockCtx, mockConversationData);
expect(result?.expiredAt).toBeDefined();
// Verify expiredAt is approximately 8760 hours (1 year) in the future
const expectedExpirationTime = new Date(beforeSave.getTime() + 8760 * 60 * 60 * 1000);
const actualExpirationTime = new Date(result?.expiredAt ?? 0);
expect(actualExpirationTime.getTime()).toBeGreaterThanOrEqual(
expectedExpirationTime.getTime() - 1000,
);
expect(actualExpirationTime.getTime()).toBeLessThanOrEqual(
expectedExpirationTime.getTime() + 1000,
);
});
it('should handle missing config gracefully', async () => {
// Simulate missing config - should use default retention period
mockCtx.interfaceConfig = undefined;
mockCtx.isTemporary = true;
const beforeSave = new Date();
const result = await saveConvo(mockCtx, mockConversationData);
const afterSave = new Date();
// Should still save the conversation with default retention period (30 days)
expect(result?.conversationId).toBe(mockConversationData.conversationId);
expect(result?.expiredAt).toBeDefined();
expect(result?.expiredAt).toBeInstanceOf(Date);
// Verify expiredAt is approximately 30 days in the future (720 hours)
const expectedExpirationTime = new Date(beforeSave.getTime() + 720 * 60 * 60 * 1000);
const actualExpirationTime = new Date(result?.expiredAt ?? 0);
expect(actualExpirationTime.getTime()).toBeGreaterThanOrEqual(
expectedExpirationTime.getTime() - 1000,
);
expect(actualExpirationTime.getTime()).toBeLessThanOrEqual(
new Date(afterSave.getTime() + 720 * 60 * 60 * 1000 + 1000).getTime(),
);
});
it('should use default retention when config is not provided', async () => {
// Mock getAppConfig to return empty config
mockCtx.interfaceConfig = undefined; // Empty config
mockCtx.isTemporary = true;
const beforeSave = new Date();
const result = await saveConvo(mockCtx, mockConversationData);
expect(result?.expiredAt).toBeDefined();
// Default retention is 30 days (720 hours)
const expectedExpirationTime = new Date(beforeSave.getTime() + 30 * 24 * 60 * 60 * 1000);
const actualExpirationTime = new Date(result?.expiredAt ?? 0);
expect(actualExpirationTime.getTime()).toBeGreaterThanOrEqual(
expectedExpirationTime.getTime() - 1000,
);
expect(actualExpirationTime.getTime()).toBeLessThanOrEqual(
expectedExpirationTime.getTime() + 1000,
);
});
it('should update expiredAt when saving existing temporary conversation', async () => {
// First save a temporary conversation
mockCtx.interfaceConfig = { temporaryChatRetention: 24 };
mockCtx.isTemporary = true;
const firstSave = await saveConvo(mockCtx, mockConversationData);
const originalExpiredAt = firstSave?.expiredAt ?? new Date(0);
// Wait a bit to ensure time difference
await new Promise((resolve) => setTimeout(resolve, 100));
// Save again with same conversationId but different title
const updatedData = { ...mockConversationData, title: 'Updated Title' };
const secondSave = await saveConvo(mockCtx, updatedData);
// Should update title and create new expiredAt
expect(secondSave?.title).toBe('Updated Title');
expect(secondSave?.expiredAt).toBeDefined();
expect(new Date(secondSave?.expiredAt ?? 0).getTime()).toBeGreaterThan(
new Date(originalExpiredAt).getTime(),
);
});
it('should preserve temporary retention when saving without isTemporary', async () => {
mockCtx.interfaceConfig = { temporaryChatRetention: 24 };
mockCtx.isTemporary = true;
const firstSave = await saveConvo(mockCtx, mockConversationData);
const originalExpiredAt = firstSave?.expiredAt;
mockCtx.isTemporary = undefined;
const updatedData = { ...mockConversationData, title: 'Updated Title' };
const secondSave = await saveConvo(mockCtx, updatedData);
expect(secondSave?.title).toBe('Updated Title');
expect(secondSave?.isTemporary).toBe(true);
expect(secondSave?.expiredAt).toEqual(originalExpiredAt);
});
it('should not set expiredAt when updating non-temporary conversation', async () => {
// First save a non-temporary conversation
mockCtx.isTemporary = false;
const firstSave = await saveConvo(mockCtx, mockConversationData);
expect(firstSave?.expiredAt).toBeNull();
// Update without isTemporary flag
mockCtx.isTemporary = undefined;
const updatedData = { ...mockConversationData, title: 'Updated Title' };
const secondSave = await saveConvo(mockCtx, updatedData);
expect(secondSave?.title).toBe('Updated Title');
expect(secondSave?.expiredAt).toBeNull();
});
it.each([true, false, undefined])(
'uses the independent retention period for isTemporary=%s',
async (isTemporary) => {
mockCtx.isTemporary = isTemporary;
mockCtx.interfaceConfig = {
temporaryChatRetention: 1,
generalChatRetention: 2160,
retentionMode: RetentionMode.ALL,
};
const now = Date.now();
const result = await saveConvo(mockCtx, mockConversationData);
const expectedHours = isTemporary === true ? 1 : 2160;
expect(result?.isTemporary).toBe(isTemporary === true);
expect(result?.expiredAt?.getTime()).toBeGreaterThanOrEqual(now + expectedHours * 3600000);
expect(result?.expiredAt?.getTime()).toBeLessThan(now + expectedHours * 3600000 + 5000);
},
);
it('ignores caller-supplied retention fields', async () => {
mockCtx.isTemporary = undefined;
mockCtx.interfaceConfig = {
temporaryChatRetention: 1,
generalChatRetention: 2160,
retentionMode: RetentionMode.ALL,
};
const suppliedExpiration = new Date('2099-01-01T00:00:00.000Z');
const result = await saveConvo(mockCtx, {
...mockConversationData,
isTemporary: true,
expiredAt: suppliedExpiration,
});
expect(result?.isTemporary).toBe(false);
expect(result?.expiredAt).not.toEqual(suppliedExpiration);
});
it.each([true, false])(
'preserves the stored deadline when chat type %s is omitted',
async (isTemporary) => {
mockCtx.isTemporary = isTemporary;
mockCtx.interfaceConfig = {
temporaryChatRetention: 1,
generalChatRetention: 2160,
retentionMode: RetentionMode.ALL,
};
const first = await saveConvo(mockCtx, mockConversationData);
mockCtx.isTemporary = undefined;
const second = await saveConvo(mockCtx, { ...mockConversationData });
expect(second?.isTemporary).toBe(isTemporary);
expect(second?.expiredAt).toEqual(first?.expiredAt);
},
);
it('preserves an explicitly inherited deadline with separate retention periods', async () => {
mockCtx.isTemporary = false;
mockCtx.expiredAt = new Date(Date.now() + 60000);
mockCtx.interfaceConfig = {
temporaryChatRetention: 1,
generalChatRetention: 2160,
retentionMode: RetentionMode.ALL,
};
const result = await saveConvo(mockCtx, mockConversationData);
expect(result?.expiredAt).toEqual(mockCtx.expiredAt);
});
it('should set expiredAt for non-temporary conversation when retentionMode is ALL', async () => {
mockCtx.isTemporary = false;
mockCtx.interfaceConfig = {
temporaryChatRetention: 24,
retentionMode: RetentionMode.ALL,
};
const result = await saveConvo(mockCtx, mockConversationData);
expect(result?.expiredAt).toBeDefined();
expect(result?.isTemporary).toBe(false);
});
it('should mark retained conversation non-temporary when retentionMode is ALL and isTemporary is omitted', async () => {
mockCtx.isTemporary = undefined;
mockCtx.interfaceConfig = {
temporaryChatRetention: 24,
retentionMode: RetentionMode.ALL,
};
const result = await saveConvo(mockCtx, mockConversationData);
expect(result?.expiredAt).toBeDefined();
expect(result?.isTemporary).toBe(false);
});
it('should preserve existing temporary flag when retentionMode is ALL and isTemporary is omitted', async () => {
mockCtx.isTemporary = true;
mockCtx.interfaceConfig = {
temporaryChatRetention: 24,
retentionMode: RetentionMode.ALL,
};
const firstSave = await saveConvo(mockCtx, mockConversationData);
mockCtx.isTemporary = undefined;
const secondSave = await saveConvo(mockCtx, {
...mockConversationData,
title: 'Updated Title',
});
expect(firstSave?.isTemporary).toBe(true);
expect(secondSave?.title).toBe('Updated Title');
expect(secondSave?.isTemporary).toBe(true);
expect(secondSave?.expiredAt).toBeDefined();
});
it('should not set expiredAt when retentionMode is temporary and not isTemporary', async () => {
mockCtx.isTemporary = false;
mockCtx.interfaceConfig = {
temporaryChatRetention: 24,
retentionMode: RetentionMode.TEMPORARY,
};
const result = await saveConvo(mockCtx, mockConversationData);
expect(result?.expiredAt).toBeNull();
expect(result?.isTemporary).toBe(false);
});
it('should force temporary conversation and set expiredAt when retentionMode is EPHEMERAL even if isTemporary is false', async () => {
mockCtx.isTemporary = false;
mockCtx.interfaceConfig = {
temporaryChatRetention: 24,
retentionMode: RetentionMode.EPHEMERAL,
};
const result = await saveConvo(mockCtx, mockConversationData);
expect(result?.isTemporary).toBe(true);
expect(result?.expiredAt).toBeDefined();
expect(result?.expiredAt).not.toBeNull();
});
it('should force temporary conversation when retentionMode is EPHEMERAL and isTemporary is omitted', async () => {
mockCtx.isTemporary = undefined;
mockCtx.interfaceConfig = {
temporaryChatRetention: 24,
retentionMode: RetentionMode.EPHEMERAL,
};
const result = await saveConvo(mockCtx, mockConversationData);
expect(result?.isTemporary).toBe(true);
expect(result?.expiredAt).toBeDefined();
expect(result?.expiredAt).not.toBeNull();
});
it('should filter out temporary conversations in getConvosByCursor', async () => {
// Create some test conversations
const newNonTemporaryConvo = await Conversation.create({
conversationId: uuidv4(),
user: 'user123',
title: 'New Non-temporary Conversation',
endpoint: EModelEndpoint.openAI,
isTemporary: false,
expiredAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
updatedAt: new Date(),
});
const oldNonTemporaryConvo = await Conversation.create({
conversationId: uuidv4(),
user: 'user123',
title: 'Old Non-Temporary Conversation',
endpoint: EModelEndpoint.openAI,
isTemporary: undefined,
expiredAt: null,
updatedAt: new Date(),
});
const legacyNullNonTemporaryConvoId = uuidv4();
await Conversation.collection.insertOne({
conversationId: legacyNullNonTemporaryConvoId,
user: 'user123',
title: 'Legacy Null Non-Temporary Conversation',
endpoint: EModelEndpoint.openAI,
isTemporary: null,
expiredAt: null,
updatedAt: new Date(),
createdAt: new Date(),
});
const legacyTemporaryConvoId = uuidv4();
await Conversation.collection.insertOne({
conversationId: legacyTemporaryConvoId,
user: 'user123',
title: 'Legacy Temporary Conversation',
endpoint: EModelEndpoint.openAI,
expiredAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
updatedAt: new Date(),
createdAt: new Date(),
});
const expiredRetainedConvo = await Conversation.create({
conversationId: uuidv4(),
user: 'user123',
title: 'Expired Retained Conversation',
endpoint: EModelEndpoint.openAI,
isTemporary: false,
expiredAt: new Date(Date.now() - 60 * 60 * 1000),
updatedAt: new Date(),
});
await Conversation.create({
conversationId: uuidv4(),
user: 'user123',
title: 'Temporary conversation',
endpoint: EModelEndpoint.openAI,
isTemporary: true,
expiredAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
updatedAt: new Date(),
});
// Mock Meili search
Object.assign(Conversation, { meiliSearch: jest.fn().mockResolvedValue({ hits: [] }) });
const result = await getConvosByCursor('user123');
// Should return both non-temporary conversations, not the temporary one
expect(result?.conversations).toHaveLength(3);
const convoIds = result?.conversations.map((c) => c.conversationId);
expect(convoIds).toContain(newNonTemporaryConvo.conversationId);
expect(convoIds).toContain(oldNonTemporaryConvo.conversationId);
expect(convoIds).toContain(legacyNullNonTemporaryConvoId);
expect(convoIds).not.toContain(legacyTemporaryConvoId);
expect(convoIds).not.toContain(expiredRetainedConvo.conversationId);
});
it('should filter out temporary conversations in getConvosQueried', async () => {
const newNonTemporaryConvo = await Conversation.create({
conversationId: uuidv4(),
user: 'user123',
title: 'New Non-temporary Conversation',
endpoint: EModelEndpoint.openAI,
isTemporary: false,
expiredAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
updatedAt: new Date(),
});
const oldNonTemporaryConvo = await Conversation.create({
conversationId: uuidv4(),
user: 'user123',
title: 'Old Non-Temporary Conversation',
endpoint: EModelEndpoint.openAI,
isTemporary: undefined,
expiredAt: null,
updatedAt: new Date(),
});
const legacyNullNonTemporaryConvoId = uuidv4();
await Conversation.collection.insertOne({
conversationId: legacyNullNonTemporaryConvoId,
user: 'user123',
title: 'Legacy Null Non-Temporary Conversation',
endpoint: EModelEndpoint.openAI,
isTemporary: null,
expiredAt: null,
updatedAt: new Date(),
createdAt: new Date(),
});
const legacyTemporaryConvoId = uuidv4();
await Conversation.collection.insertOne({
conversationId: legacyTemporaryConvoId,
user: 'user123',
title: 'Legacy Temporary Conversation',
endpoint: EModelEndpoint.openAI,
expiredAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
updatedAt: new Date(),
createdAt: new Date(),
});
const expiredRetainedConvo = await Conversation.create({
conversationId: uuidv4(),
user: 'user123',
title: 'Expired Retained Conversation',
endpoint: EModelEndpoint.openAI,
isTemporary: false,
expiredAt: new Date(Date.now() - 60 * 60 * 1000),
updatedAt: new Date(),
});
const tempConvo = await Conversation.create({
conversationId: uuidv4(),
user: 'user123',
title: 'Temporary conversation',
endpoint: EModelEndpoint.openAI,
isTemporary: true,
expiredAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
updatedAt: new Date(),
});
const convoIds = [
{ conversationId: newNonTemporaryConvo.conversationId },
{ conversationId: oldNonTemporaryConvo.conversationId },
{ conversationId: legacyNullNonTemporaryConvoId },
{ conversationId: legacyTemporaryConvoId },
{ conversationId: expiredRetainedConvo.conversationId },
{ conversationId: tempConvo.conversationId },
];
const result = await getConvosQueried('user123', convoIds);
// Should only return the non-temporary conversations
expect(result?.conversations).toHaveLength(3);
const resultIds = result?.conversations.map((c) => c.conversationId);
expect(resultIds).toContain(newNonTemporaryConvo.conversationId);
expect(resultIds).toContain(oldNonTemporaryConvo.conversationId);
expect(resultIds).toContain(legacyNullNonTemporaryConvoId);
expect(result?.convoMap[newNonTemporaryConvo.conversationId]).toBeDefined();
expect(result?.convoMap[oldNonTemporaryConvo.conversationId]).toBeDefined();
expect(result?.convoMap[legacyNullNonTemporaryConvoId]).toBeDefined();
expect(result?.convoMap[legacyTemporaryConvoId]).toBeUndefined();
expect(result?.convoMap[expiredRetainedConvo.conversationId]).toBeUndefined();
expect(result?.convoMap[tempConvo.conversationId]).toBeUndefined();
});
it('hides durable subagent threads from conversation lists and search results', async () => {
const parentId = uuidv4();
const childId = uuidv4();
const messageId = 'message-1';
const normalConversation = await Conversation.create({
conversationId: parentId,
user: 'user123',
endpoint: EModelEndpoint.agents,
title: 'Parent conversation',
});
await Conversation.create({
conversationId: childId,
user: 'user123',
endpoint: EModelEndpoint.agents,
title: 'Subagent: implementation',
subagentThread: {
rootConversationId: parentId,
parentConversationId: parentId,
parentMessageId: messageId,
parentToolCallId: 'tool-1',
subagentType: 'agent-child',
subagentKind: 'agent',
depth: 1,
},
});
Object.assign(Conversation, {
meiliSearch: jest.fn().mockResolvedValue({
hits: [{ conversationId: parentId }, { conversationId: childId }],
}),
});
const listed = await getConvosByCursor('user123', { search: 'implementation' });
const queried = await getConvosQueried('user123', [
{ conversationId: parentId },
{ conversationId: childId },
]);
expect(listed.conversations.map((convo) => convo.conversationId)).toEqual([
normalConversation.conversationId,
]);
expect(queried.conversations.map((convo) => convo.conversationId)).toEqual([
normalConversation.conversationId,
]);
expect(queried.convoMap[childId]).toBeUndefined();
});
});
describe('searchConversation', () => {
it('should find a conversation by conversationId', async () => {
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
title: 'Test',
endpoint: EModelEndpoint.openAI,
});
const result = await searchConversation(mockConversationData.conversationId);
expect(result).toBeTruthy();
expect(result!.conversationId).toBe(mockConversationData.conversationId);
expect(result!.user).toBe('user123');
expect((result as unknown as { title?: string }).title).toBeUndefined(); // Only returns conversationId and user
});
it('should return null if conversation not found', async () => {
const result = await searchConversation('non-existent-id');
expect(result).toBeNull();
});
});
describe('getConvo', () => {
it('should retrieve a conversation for a user', async () => {
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
title: 'Test Conversation',
endpoint: EModelEndpoint.openAI,
});
const result = await getConvo('user123', mockConversationData.conversationId);
expect(result!.conversationId).toBe(mockConversationData.conversationId);
expect(result!.user).toBe('user123');
expect(result!.title).toBe('Test Conversation');
});
it('should return null if conversation not found', async () => {
const result = await getConvo('user123', 'non-existent-id');
expect(result).toBeNull();
});
});
describe('getConvoOwnership', () => {
it('resolves only the owning user id, without the preset or message list', async () => {
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
tenantId: 'tenant-a',
title: 'Test Conversation',
endpoint: EModelEndpoint.openAI,
});
const result = await methods.getConvoOwnership(
'user123',
mockConversationData.conversationId,
);
expect(result?.user).toBe('user123');
expect(result?.tenantId).toBe('tenant-a');
expect(result).not.toHaveProperty('title');
expect(result).not.toHaveProperty('messages');
expect(result).not.toHaveProperty('endpoint');
});
it('returns null for another user or a missing conversation', async () => {
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
title: 'Test Conversation',
endpoint: EModelEndpoint.openAI,
});
expect(
await methods.getConvoOwnership('someone-else', mockConversationData.conversationId),
).toBeNull();
expect(await methods.getConvoOwnership('user123', 'non-existent-id')).toBeNull();
});
it('hides retention-expired conversations before TTL cleanup', async () => {
await Conversation.create({
conversationId: 'expired-owner',
user: 'user123',
endpoint: EModelEndpoint.agents,
expiredAt: new Date(Date.now() - 60_000),
});
await expect(methods.getConvoOwnership('user123', 'expired-owner')).resolves.toBeNull();
});
it('includes child-thread identity without materializing conversation content', async () => {
await Conversation.create({
conversationId: 'child-conversation',
user: 'user123',
title: 'Internal child',
endpoint: EModelEndpoint.agents,
subagentThread: {
rootConversationId: 'root-conversation',
parentConversationId: 'parent-conversation',
parentMessageId: 'parent-message',
parentToolCallId: 'parent-tool-call',
subagentType: 'child-agent',
subagentKind: 'agent',
depth: 1,
},
});
const result = await methods.getConvoOwnership('user123', 'child-conversation');
expect(result).toMatchObject({
user: 'user123',
subagentThread: { parentConversationId: 'parent-conversation' },
});
expect(result).not.toHaveProperty('title');
});
it('selects the exact tenant when conversation identifiers collide', async () => {
await runAsSystem(async () => {
await Conversation.create([
{
conversationId: 'shared-conversation-id',
user: 'user123',
title: 'Tenantless parent',
endpoint: EModelEndpoint.agents,
},
{
conversationId: 'shared-conversation-id',
user: 'user123',
tenantId: 'tenant-a',
title: 'Tenant parent',
endpoint: EModelEndpoint.agents,
},
]);
});
const tenantless = await methods.getConvoOwnership('user123', 'shared-conversation-id', null);
const tenant = await methods.getConvoOwnership(
'user123',
'shared-conversation-id',
'tenant-a',
);
expect(tenantless?.tenantId).toBeUndefined();
expect(tenant?.tenantId).toBe('tenant-a');
});
});
describe('getConvoRetention', () => {
it('should retrieve only retention fields for a user conversation', async () => {
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
title: 'Test Conversation',
endpoint: EModelEndpoint.openAI,
expiredAt: new Date('2030-01-01T00:00:00.000Z'),
});
const result = await getConvoRetention('user123', mockConversationData.conversationId);
expect(result?.expiredAt).toEqual(new Date('2030-01-01T00:00:00.000Z'));
expect(result).not.toHaveProperty('title');
expect(result).not.toHaveProperty('messages');
});
});
describe('getConvoTitle', () => {
it('should return the conversation title', async () => {
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
title: 'Test Title',
endpoint: EModelEndpoint.openAI,
});
const result = await getConvoTitle('user123', mockConversationData.conversationId);
expect(result).toBe('Test Title');
});
it('should return null if conversation has no title', async () => {
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
title: null,
endpoint: EModelEndpoint.openAI,
});
const result = await getConvoTitle('user123', mockConversationData.conversationId);
expect(result).toBeNull();
});
it('should return "New Chat" if conversation not found', async () => {
const result = await getConvoTitle('user123', 'non-existent-id');
expect(result).toBe('New Chat');
});
});
describe('markConvoSeen', () => {
const markConvoSeen = (...args: Parameters<ConversationMethods['markConvoSeen']>) =>
methods.markConvoSeen(...args);
it('records lastSeenAt for the owning user', async () => {
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
lastResponseAt: new Date(),
});
const result = await markConvoSeen('user123', mockConversationData.conversationId);
expect(result.modified).toBe(true);
const convo = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>();
expect(convo?.lastSeenAt).toBeInstanceOf(Date);
});
it('acknowledges only the reply the client observed', async () => {
/* Another device persists a newer reply while the seen write is in flight; stamping
"now" would clear an indicator for a message nobody has read. */
const observed = new Date('2026-08-16T10:00:00.000Z');
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
lastResponseAt: new Date('2026-08-16T10:05:00.000Z'),
});
const result = await markConvoSeen('user123', mockConversationData.conversationId, observed);
expect(result.modified).toBe(false);
const convo = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>();
expect(convo?.lastSeenAt).toBeUndefined();
});
it('never writes a catch-up older than the reply it acknowledges', async () => {
/* Across replicas the node handling this can be behind the one that stamped the reply;
a catch-up earlier than that reply would read as unseen again on the next refetch. */
const observed = new Date(Date.now() + 60_000);
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
lastResponseAt: observed,
});
const result = await markConvoSeen('user123', mockConversationData.conversationId, observed);
expect(result.modified).toBe(true);
const convo = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>();
expect(convo?.lastSeenAt?.getTime()).toBeGreaterThanOrEqual(observed.getTime());
});
it('records the catch-up when the observed reply is still the newest', async () => {
const observed = new Date('2026-08-16T10:00:00.000Z');
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
lastResponseAt: observed,
});
const result = await markConvoSeen('user123', mockConversationData.conversationId, observed);
expect(result.modified).toBe(true);
const convo = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>();
expect(convo?.lastSeenAt).toBeInstanceOf(Date);
});
it('reports success when a retried acknowledgement changes nothing', async () => {
/* A future-dated observed reply is stored verbatim, so a retry after a lost response
writes the identical value: zero documents modified, but the database is already
caught up. Reporting failure would make the client roll back to unseen. */
const observed = new Date(Date.now() + 60_000);
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
lastResponseAt: observed,
});
const first = await markConvoSeen('user123', mockConversationData.conversationId, observed);
expect(first.modified).toBe(true);
const retry = await markConvoSeen('user123', mockConversationData.conversationId, observed);
expect(retry.modified).toBe(true);
const convo = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>();
expect(convo?.lastSeenAt?.getTime()).toBe(observed.getTime());
});
it('leaves updatedAt alone so reading a conversation does not reorder the sidebar', async () => {
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
lastResponseAt: new Date(),
});
const before = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>();
await markConvoSeen('user123', mockConversationData.conversationId);
const after = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>();
expect(after?.updatedAt?.toISOString()).toBe(before?.updatedAt?.toISOString());
});
it('does not touch another user’s conversation', async () => {
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
});
const result = await markConvoSeen('someone-else', mockConversationData.conversationId);
expect(result.modified).toBe(false);
const convo = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>();
expect(convo?.lastSeenAt).toBeUndefined();
});
});
describe('stampConvoLastResponse', () => {
const stampConvoLastResponse = (
...args: Parameters<ConversationMethods['stampConvoLastResponse']>
) => methods.stampConvoLastResponse(...args);
it('carries the project activity forward with the conversation', async () => {
/* The workspace sorts on `ChatProject.lastConversationAt`, so lifting the conversation
without it would leave the project sitting at its old position. */
const ChatProject = mongoose.models.ChatProject;
const project = await ChatProject.create({
name: 'Stamped',
user: 'user123',
lastConversationAt: new Date('2026-08-16T09:00:00.000Z'),
});
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
chatProjectId: project._id.toString(),
createdAt: new Date('2026-08-16T09:00:00.000Z'),
updatedAt: new Date('2026-08-16T09:00:00.000Z'),
});
await stampConvoLastResponse('user123', mockConversationData.conversationId, 'reply-project');
const refreshed = await ChatProject.findById(project._id).lean<{
lastConversationAt?: Date;
}>();
expect(refreshed?.lastConversationAt).toBeDefined();
expect(new Date(refreshed?.lastConversationAt as Date).getTime()).toBeGreaterThan(
new Date('2026-08-16T09:00:00.000Z').getTime(),
);
});
it('returns the durable reply stamp when project maintenance fails', async () => {
const project = await ChatProject.create({
name: 'Unavailable project update',
user: 'user123',
});
await Conversation.create({
...mockConversationData,
user: 'user123',
chatProjectId: project._id.toString(),
});
const update = jest.spyOn(ChatProject, 'updateOne').mockImplementationOnce(() => {
throw new Error('project update unavailable');
});
try {
const settled = await stampConvoLastResponse(
'user123',
mockConversationData.conversationId,
'reply-project-failure',
);
const saved = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>();
expect(settled?.lastResponseAt).toBeInstanceOf(Date);
expect(settled?.lastResponseAt).toEqual(saved?.lastResponseAt);
expect(settled?.updatedAt).toEqual(saved?.updatedAt);
} finally {
update.mockRestore();
}
});
it('keeps a saved reply stamp when project maintenance fails', async () => {
/* The caller hands this document to the client as the turn's conversation. Answering a
durable save with an error would drop the stamp from the terminal event, and the next
list refresh would present a reply the user watched arrive as unread. */
const project = await ChatProject.create({
name: 'Unavailable project stats',
user: 'user123',
});
await Conversation.create({
...mockConversationData,
user: 'user123',
chatProjectId: project._id.toString(),
});
const update = jest.spyOn(ChatProject, 'updateOne').mockImplementation(() => {
throw new Error('project update unavailable');
});
try {
const saved = await saveConvo(
mockCtx,
{ ...mockConversationData, chatProjectId: project._id.toString() },
{ stampReply: true, replyMessageId: 'reply-project-tail' },
);
expect(saved).not.toMatchObject({ message: 'Error saving conversation' });
expect((saved as IConversation).lastResponseMessageId).toBe('reply-project-tail');
const stored = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>();
expect(stored?.lastResponseMessageId).toBe('reply-project-tail');
} finally {
update.mockRestore();
}
});
it('stamps lastResponseAt and lifts the conversation like any other reply', async () => {
/* The away poll pages by `updatedAt`, so a reply that left the order alone would be
invisible on any conversation that had fallen past the first page. BaseClient's own
reply path moves it too. */
const createdAt = new Date('2026-08-16T09:00:00.000Z');
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
createdAt,
updatedAt: createdAt,
});
const settled = await stampConvoLastResponse(
'user123',
mockConversationData.conversationId,
'reply-latest',
);
const convo = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>();
expect(settled?.lastResponseAt).toBeInstanceOf(Date);
expect(settled?.lastResponseMessageId).toBe('reply-latest');
expect(settled?.updatedAt).toBeInstanceOf(Date);
expect(settled?.lastResponseAt?.getTime()).toBe(convo?.lastResponseAt?.getTime());
expect(settled?.updatedAt?.getTime()).toBe(convo?.updatedAt?.getTime());
expect(convo?.lastResponseAt).toBeInstanceOf(Date);
expect(convo?.lastResponseAt?.getTime()).toBeGreaterThanOrEqual(createdAt.getTime());
expect(convo?.updatedAt?.getTime()).toBeGreaterThan(createdAt.getTime());
});
it('makes a new reply the latest activity even after a future-dated metadata update', async () => {
const metadataAt = new Date(Date.now() + 60_000);
await Conversation.create({
...mockConversationData,
user: 'user123',
});
await Conversation.updateOne(
{ conversationId: mockConversationData.conversationId },
{ $set: { updatedAt: metadataAt } },
{ timestamps: false },
);
const settled = await stampConvoLastResponse(
'user123',
mockConversationData.conversationId,
'reply-future',
);
expect(settled?.lastResponseAt?.getTime()).toBeGreaterThan(metadataAt.getTime());
expect(settled?.updatedAt).toEqual(settled?.lastResponseAt);
});
it('clears a catch-up and manual marker when the real reply advances the stamp', async () => {
/* `/seen` can accept the previous reply while this one is being persisted, and a
replica's clock can date that catch-up ahead: the stamp and the clear are one write. */
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
lastResponseAt: new Date('2026-08-16T09:00:00.000Z'),
lastResponseIsManual: true,
lastSeenAt: new Date(Date.now() + 5_000),
});
await stampConvoLastResponse(
'user123',
mockConversationData.conversationId,
'reply-manual-clear',
);
const convo = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>();
expect(convo?.lastResponseAt).toBeInstanceOf(Date);
expect(convo?.lastResponseIsManual).toBeUndefined();
expect(convo?.lastSeenAt?.toISOString()).toBe(UNSEEN_REPLY_WATERMARK);
});
it('advances past a future reply stamp when this host clock is behind', async () => {
const newer = new Date(Date.now() + 60_000);
const seenAt = new Date(Date.now() + 90_000);
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
lastResponseAt: newer,
lastSeenAt: seenAt,
});
await stampConvoLastResponse('user123', mockConversationData.conversationId, 'reply-future');
const convo = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>();
expect(convo?.lastResponseAt?.getTime()).toBeGreaterThan(newer.getTime());
expect(convo?.lastSeenAt?.toISOString()).toBe(UNSEEN_REPLY_WATERMARK);
});
it('does not stamp another user’s conversation', async () => {
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
});
const settled = await stampConvoLastResponse(
'someone-else',
mockConversationData.conversationId,
'reply-other-user',
);
const convo = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>();
expect(settled).toBeNull();
expect(convo?.lastResponseAt).toBeUndefined();
});
it('does not expose a reply stamp for a stored temporary conversation', async () => {
const original = await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
isTemporary: true,
});
const settled = await stampConvoLastResponse(
'user123',
original.conversationId,
'reply-temporary',
);
const current = await Conversation.findById(original._id).lean<IConversation>();
expect(settled).toBeNull();
expect(current?.lastResponseAt).toBeUndefined();
expect(current?.updatedAt).toEqual(original.updatedAt);
});
});
describe('markConvoUnread', () => {
const markConvoUnread = (...args: Parameters<ConversationMethods['markConvoUnread']>) =>
methods.markConvoUnread(...args);
it('clears the catch-up on a read conversation, restoring the unread state', async () => {
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
lastResponseAt: new Date('2026-08-16T10:00:00.000Z'),
lastSeenAt: new Date('2026-08-16T11:00:00.000Z'),
});
const result = await markConvoUnread('user123', mockConversationData.conversationId);
expect(result.modified).toBe(true);
expect(result.isMarkedUnread).toBe(true);
const convo = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>();
expect(convo?.lastSeenAt).toBeUndefined();
expect(convo?.lastResponseAt?.toISOString()).toBe('2026-08-16T10:00:00.000Z');
expect(convo?.lastResponseIsManual).toBeUndefined();
expect(convo?.isMarkedUnread).toBe(true);
});
it('returns the stamp it settled on so the client never invents one', async () => {
/* The optimistic marker the client guesses is necessarily earlier than the server's;
sending that guess to /seen would miss the observed-reply filter. */
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
});
const result = await markConvoUnread('user123', mockConversationData.conversationId);
const convo = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>();
expect(result.lastResponseAt?.toISOString()).toBe(convo?.lastResponseAt?.toISOString());
expect(result.lastResponseMessageId).toBeUndefined();
expect(result.lastResponseIsManual).toBe(true);
});
it('reports nothing modified for a conversation the user does not own', async () => {
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'someone-else',
endpoint: EModelEndpoint.openAI,
lastResponseAt: new Date('2026-08-16T10:00:00.000Z'),
});
const result = await markConvoUnread('user123', mockConversationData.conversationId);
expect(result.modified).toBe(false);
});
it('keeps the existing reply stamp rather than restamping it', async () => {
const responded = new Date('2026-08-16T10:00:00.000Z');
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
lastResponseAt: responded,
lastResponseMessageId: 'reply-existing',
});
const result = await markConvoUnread('user123', mockConversationData.conversationId);
expect(result.lastResponseAt?.toISOString()).toBe(responded.toISOString());
expect(result.lastResponseMessageId).toBe('reply-existing');
expect(result.lastResponseIsManual).toBe(false);
});
it('marks a never-replied conversation with a monotonic manual marker so the dot lights', async () => {
const created = await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
});
await markConvoUnread('user123', mockConversationData.conversationId);
const convo = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>();
expect(convo?.lastResponseAt?.getTime()).toBeGreaterThanOrEqual(
created.updatedAt?.getTime() ?? 0,
);
expect(convo?.lastResponseIsManual).toBe(true);
expect(convo?.lastSeenAt).toBeUndefined();
});
it('leaves updatedAt alone so flagging does not reorder the sidebar', async () => {
const createdAt = new Date('2026-08-16T09:00:00.000Z');
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
lastResponseAt: new Date('2026-08-16T10:00:00.000Z'),
lastSeenAt: new Date('2026-08-16T11:00:00.000Z'),
createdAt,
updatedAt: createdAt,
});
await markConvoUnread('user123', mockConversationData.conversationId);
const convo = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>();
expect(convo?.updatedAt?.toISOString()).toBe(createdAt.toISOString());
});
it('does not touch another user’s conversation', async () => {
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
lastResponseAt: new Date('2026-08-16T10:00:00.000Z'),
lastSeenAt: new Date('2026-08-16T11:00:00.000Z'),
});
const result = await markConvoUnread('someone-else', mockConversationData.conversationId);
expect(result.modified).toBe(false);
const convo = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>();
expect(convo?.lastSeenAt).toBeInstanceOf(Date);
});
});
describe('manual unread reminders', () => {
it('survives reload and is cleared by a persisted real reply', async () => {
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
lastResponseAt: new Date('2026-08-16T10:00:00.000Z'),
lastResponseMessageId: 'original-reply',
});
await methods.markConvoUnread('user123', mockConversationData.conversationId);
const unread = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>();
expect(unread?.isMarkedUnread).toBe(true);
expect(unread?.lastResponseMessageId).toBe('original-reply');
await methods.stampConvoLastResponse(
'user123',
mockConversationData.conversationId,
'new-reply',
);
const replied = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>();
expect(replied?.isMarkedUnread).toBe(false);
expect(replied?.lastResponseMessageId).toBe('new-reply');
});
it('leaves legacy intent unknown through listing and metadata saves, until a real reply', async () => {
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
lastResponseAt: new Date('2026-08-16T10:00:00.000Z'),
lastResponseMessageId: 'legacy-reply',
});
await saveConvo(mockCtx, {
conversationId: mockConversationData.conversationId,
title: 'Reminder',
});
const { conversations } = await getConvosByCursor('user123');
expect(conversations[0].isMarkedUnread).toBeUndefined();
expect(conversations[0].lastResponseMessageId).toBe('legacy-reply');
expect(conversations[0].lastSeenAt).toBeUndefined();
await methods.stampConvoLastResponse(
'user123',
mockConversationData.conversationId,
'confirmed-reply',
);
const reloaded = await getConvo('user123', mockConversationData.conversationId);
expect(reloaded?.isMarkedUnread).toBe(false);
expect(reloaded?.lastResponseMessageId).toBe('confirmed-reply');
});
it('keeps legacy replica seen/unread writes distinguishable after an upgraded reply', async () => {
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
});
await methods.stampConvoLastResponse(
'user123',
mockConversationData.conversationId,
'upgraded-reply',
);
let stored = await getConvo('user123', mockConversationData.conversationId);
expect(stored?.lastSeenAt?.toISOString()).toBe(UNSEEN_REPLY_WATERMARK);
expect(stored?.isMarkedUnread).toBe(false);
/* Exact operators used by the pre-upgrade backend. */
await Conversation.updateOne(
{ conversationId: mockConversationData.conversationId, user: 'user123' },
{ $set: { lastSeenAt: new Date() } },
{ timestamps: false },
);
await Conversation.findOneAndUpdate(
{ conversationId: mockConversationData.conversationId, user: 'user123' },
{ $unset: { lastSeenAt: '' } },
{ timestamps: false, new: true },
);
const { conversations } = await getConvosByCursor('user123');
expect(conversations[0].isMarkedUnread).toBe(false);
expect(conversations[0].lastSeenAt).toBeUndefined();
await methods.stampConvoLastResponse(
'user123',
mockConversationData.conversationId,
'next-upgraded-reply',
);
stored = await getConvo('user123', mockConversationData.conversationId);
expect(stored?.lastSeenAt?.toISOString()).toBe(UNSEEN_REPLY_WATERMARK);
expect(stored?.lastResponseMessageId).toBe('next-upgraded-reply');
});
it('is cleared only by an acknowledgement of the current reply', async () => {
const responseAt = new Date('2026-08-16T10:00:00.000Z');
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
lastResponseAt: responseAt,
isMarkedUnread: true,
});
await methods.markConvoSeen(
'user123',
mockConversationData.conversationId,
new Date(responseAt.getTime() - 1),
);
expect(
(
await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>()
)?.isMarkedUnread,
).toBe(true);
await methods.markConvoSeen('user123', mockConversationData.conversationId, responseAt);
expect(
(
await Conversation.findOne({
conversationId: mockConversationData.conversationId,
}).lean<IConversation>()
)?.isMarkedUnread,
).toBeUndefined();
});
});
describe('unseen-reply fields', () => {
it('returns lastResponseAt, manual marker, and lastSeenAt from the cursor listing', async () => {
const lastResponseAt = new Date('2026-08-16T10:00:00.000Z');
const lastSeenAt = new Date('2026-08-16T09:00:00.000Z');
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
lastResponseAt,
lastResponseMessageId: 'reply-listed',
lastResponseIsManual: true,
isMarkedUnread: true,
lastSeenAt,
});
const { conversations } = await getConvosByCursor('user123');
expect(conversations).toHaveLength(1);
expect(conversations[0].lastResponseAt?.toISOString()).toBe(lastResponseAt.toISOString());
expect(conversations[0].lastResponseMessageId).toBe('reply-listed');
expect(conversations[0].lastResponseIsManual).toBe(true);
expect(conversations[0].isMarkedUnread).toBe(true);
expect(conversations[0].lastSeenAt?.toISOString()).toBe(lastSeenAt.toISOString());
});
it('keeps them through a title-only saveConvo, whose partial $set leaves absent fields alone', async () => {
/* saveConvo never $unsets fields it is not given; the wipe threat lives in BaseClient's
unsetFields loop, which excludedKeys guards (covered in the api BaseClient spec). */
const lastResponseAt = new Date('2026-08-16T10:00:00.000Z');
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
lastResponseAt,
});
await saveConvo(mockCtx, {
conversationId: mockConversationData.conversationId,
title: 'Generated title',
});
const convo = await getConvo('user123', mockConversationData.conversationId);
expect(convo?.title).toBe('Generated title');
expect(convo?.lastResponseAt?.toISOString()).toBe(lastResponseAt.toISOString());
});
});
describe('getConvoFiles', () => {
it('should return conversation files', async () => {
const files = ['file1', 'file2'];
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
files,
});
const result = await getConvoFiles(mockConversationData.conversationId);
expect(result).toEqual(files);
});
it('should return empty array if no files', async () => {
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
});
const result = await getConvoFiles(mockConversationData.conversationId);
expect(result).toEqual([]);
});
it('should return empty array if conversation not found', async () => {
const result = await getConvoFiles('non-existent-id');
expect(result).toEqual([]);
});
});
describe('deleteConvos', () => {
it('retires queued-turn work before each conversation deletion wave', async () => {
const conversationId = uuidv4();
await Conversation.create({
conversationId,
user: 'user123',
tenantId: 'tenant-1',
endpoint: EModelEndpoint.agents,
});
const transitions: string[] = [];
const deleteAgentQueuedTurns = jest.fn(async () => {
transitions.push('queue-retired');
});
const eraseAgentTriggerDeliveryConversationResults = jest.fn(async () => {
transitions.push('trigger-results-erased');
});
const scopedMethods = createConversationMethods(mongoose, {
getMessages,
deleteMessages,
deleteAgentQueuedTurns,
eraseAgentTriggerDeliveryConversationResults,
});
await scopedMethods.deleteConvos(
'user123',
{ conversationId },
{
beforeDelete: async () => {
transitions.push('generation-drained');
},
},
);
expect(deleteAgentQueuedTurns).toHaveBeenCalledWith('user123', [
{ conversationId, tenantId: 'tenant-1' },
]);
expect(eraseAgentTriggerDeliveryConversationResults).toHaveBeenCalledWith('user123', [
conversationId,
]);
expect(transitions).toEqual([
'queue-retired',
'generation-drained',
'trigger-results-erased',
]);
});
it('preserves background receipts when a pre-delete drain fails', async () => {
const conversationId = uuidv4();
await Conversation.create({
conversationId,
user: 'user123',
endpoint: EModelEndpoint.agents,
});
const eraseAgentTriggerDeliveryConversationResults = jest.fn(async () => undefined);
const scopedMethods = createConversationMethods(mongoose, {
getMessages,
deleteMessages,
eraseAgentTriggerDeliveryConversationResults,
});
await expect(
scopedMethods.deleteConvos(
'user123',
{ conversationId },
{ beforeDelete: async () => Promise.reject(new Error('drain unavailable')) },
),
).rejects.toThrow('drain unavailable');
expect(await Conversation.findOne({ conversationId })).not.toBeNull();
expect(eraseAgentTriggerDeliveryConversationResults).not.toHaveBeenCalled();
});
it('finishes descendant bookkeeping and message cleanup when receipt erasure fails', async () => {
const parentId = uuidv4();
const childId = uuidv4();
const grandchildId = uuidv4();
const ids = [parentId, childId, grandchildId];
const project = await ChatProject.create({ user: 'user123', name: 'Receipt cleanup' });
await ConversationTag.create({ user: 'user123', tag: 'work', count: 3, position: 0 });
await Conversation.create(
ids.map((conversationId, depth) => ({
conversationId,
user: 'user123',
endpoint: EModelEndpoint.agents,
tags: ['work'],
chatProjectId: project._id.toString(),
...(depth === 0
? {}
: {
subagentThread: {
rootConversationId: parentId,
parentConversationId: ids[depth - 1],
parentMessageId: `message-${depth}`,
parentToolCallId: `call-${depth}`,
subagentType: 'agent-child',
subagentKind: 'agent',
depth,
},
}),
})),
);
const prepare = jest.fn(async () => undefined);
const erase = jest.fn(async () => {
throw new Error('receipt storage unavailable');
});
const scopedMethods = createConversationMethods(mongoose, {
getMessages,
deleteMessages,
prepareAgentTriggerConversationResultErasure: prepare,
eraseAgentTriggerDeliveryConversationResults: erase,
});
const result = await scopedMethods.deleteConvos('user123', { conversationId: parentId });
expect(result).toMatchObject({ deletedCount: 3, conversationIds: ids });
expect(prepare.mock.calls).toHaveLength(3);
expect(erase.mock.calls).toHaveLength(3);
expect(await Conversation.countDocuments({ user: 'user123' })).toBe(0);
expect((await ConversationTag.findOne({ user: 'user123', tag: 'work' }).lean())?.count).toBe(
0,
);
expect((await ChatProject.findById(project._id).lean())?.conversationCount).toBe(0);
expect(deleteMessages).toHaveBeenCalledWith({
user: 'user123',
conversationId: { $in: ids },
});
await expect(
scopedMethods.deleteConvos('user123', { conversationId: parentId }, { allowEmpty: true }),
).resolves.toMatchObject({ deletedCount: 0, conversationIds: [parentId] });
});
it('fails closed before deleting a conversation when queued-turn retirement fails', async () => {
const conversationId = uuidv4();
await Conversation.create({
conversationId,
user: 'user123',
endpoint: EModelEndpoint.agents,
});
const scopedMethods = createConversationMethods(mongoose, {
getMessages,
deleteMessages,
deleteAgentQueuedTurns: async () => Promise.reject(new Error('retirement unavailable')),
});
await expect(scopedMethods.deleteConvos('user123', { conversationId })).rejects.toThrow(
'retirement unavailable',
);
expect(await Conversation.findOne({ conversationId })).not.toBeNull();
});
it('should delete conversations and associated messages', async () => {
await Conversation.create({
conversationId: mockConversationData.conversationId,
user: 'user123',
title: 'To Delete',
endpoint: EModelEndpoint.openAI,
});
deleteMessages.mockResolvedValue({ deletedCount: 5 });
const result = await deleteConvos('user123', {
conversationId: mockConversationData.conversationId,
});
expect(result?.deletedCount).toBe(1);
expect(result?.messages.deletedCount).toBe(5);
expect(deleteMessages).toHaveBeenCalledWith({
conversationId: { $in: [mockConversationData.conversationId] },
user: 'user123',
});
// Verify conversation was deleted
const deletedConvo = await Conversation.findOne({
conversationId: mockConversationData.conversationId,
});
expect(deletedConvo).toBeNull();
});
it('cascades parent deletion through owner-scoped child-thread lineage', async () => {
const parentId = uuidv4();
const childId = uuidv4();
const grandchildId = uuidv4();
const otherUsersChildId = uuidv4();
const lineage = (
parentConversationId: string,
rootConversationId: string,
depth: number,
) => ({
rootConversationId,
parentConversationId,
parentMessageId: `message-${depth}`,
parentToolCallId: `tool-${depth}`,
subagentType: 'agent-child',
subagentKind: 'agent',
depth,
});
await Conversation.create([
{ conversationId: parentId, user: 'user123', endpoint: EModelEndpoint.agents },
{
conversationId: childId,
user: 'user123',
endpoint: EModelEndpoint.agents,
subagentThread: lineage(parentId, parentId, 1),
},
{
conversationId: grandchildId,
user: 'user123',
endpoint: EModelEndpoint.agents,
subagentThread: lineage(childId, parentId, 2),
},
{
conversationId: otherUsersChildId,
user: 'other-user',
endpoint: EModelEndpoint.agents,
subagentThread: lineage(parentId, parentId, 1),
},
]);
deleteMessages.mockResolvedValue({ acknowledged: true, deletedCount: 3 });
const beforeDelete = jest.fn(async (conversationIds: string[]) => {
expect(
await Conversation.countDocuments({ conversationId: { $in: conversationIds } }),
).toBe(conversationIds.length);
});
const result = await deleteConvos('user123', { conversationId: parentId }, { beforeDelete });
expect(result.deletedCount).toBe(3);
expect(result.conversationIds).toEqual([parentId, childId, grandchildId]);
expect(beforeDelete.mock.calls).toEqual([[[parentId]], [[childId]], [[grandchildId]]]);
expect(deleteMessages).toHaveBeenCalledWith({
conversationId: { $in: [parentId, childId, grandchildId] },
user: 'user123',
});
expect(await Conversation.find({ user: 'user123' })).toHaveLength(0);
expect(await Conversation.findOne({ conversationId: otherUsersChildId })).not.toBeNull();
});
it('reports a partial cascade failure instead of silently succeeding', async () => {
const parentId = uuidv4();
const childId = uuidv4();
const project = await ChatProject.create({
user: 'user123',
name: 'Partial Cascade',
conversationCount: 1,
lastConversationId: parentId,
});
await ConversationTag.create({ user: 'user123', tag: 'work', count: 1, position: 1 });
await Conversation.create([
{
conversationId: parentId,
user: 'user123',
endpoint: EModelEndpoint.agents,
chatProjectId: project._id!.toString(),
tags: ['work'],
},
{
conversationId: childId,
user: 'user123',
endpoint: EModelEndpoint.agents,
subagentThread: {
rootConversationId: parentId,
parentConversationId: parentId,
parentMessageId: 'message-1',
parentToolCallId: 'tool-1',
subagentType: 'agent-child',
subagentKind: 'agent',
depth: 1,
},
},
]);
const realFind = Conversation.find.bind(Conversation);
const findSpy = jest.spyOn(Conversation, 'find').mockImplementation(((filter) => {
if (
filter != null &&
Object.prototype.hasOwnProperty.call(filter, 'subagentThread.parentConversationId')
) {
return {
select: () => ({ lean: () => Promise.reject(new Error('stepdown')) }),
};
}
return realFind(filter as FilterQuery<IConversation>);
}) as typeof Conversation.find);
await expect(deleteConvos('user123', { conversationId: parentId })).rejects.toThrow(
'stepdown',
);
expect(findSpy).toHaveBeenCalledTimes(4);
expect(await Conversation.findOne({ conversationId: parentId })).toBeNull();
expect(await Conversation.findOne({ conversationId: childId })).not.toBeNull();
expect(deleteMessages).not.toHaveBeenCalled();
expect((await ConversationTag.findOne({ user: 'user123', tag: 'work' }).lean())?.count).toBe(
0,
);
expect(
(await ChatProject.findById(project._id).lean<IChatProject>())?.conversationCount,
).toBe(0);
findSpy.mockRestore();
deleteMessages.mockResolvedValue({ acknowledged: true, deletedCount: 2 });
const recovered = await deleteConvos('user123', { conversationId: parentId });
expect(recovered.conversationIds).toEqual([parentId, childId]);
expect(await Conversation.findOne({ conversationId: childId })).toBeNull();
expect(deleteMessages).toHaveBeenCalledWith({
conversationId: { $in: [parentId, childId] },
user: 'user123',
});
expect((await ConversationTag.findOne({ user: 'user123', tag: 'work' }).lean())?.count).toBe(
0,
);
findSpy.mockRestore();
});
it('does not delete a parent when deleting one child thread', async () => {
const parentId = uuidv4();
const childId = uuidv4();
await Conversation.create([
{ conversationId: parentId, user: 'user123', endpoint: EModelEndpoint.agents },
{
conversationId: childId,
user: 'user123',
endpoint: EModelEndpoint.agents,
subagentThread: {
rootConversationId: parentId,
parentConversationId: parentId,
parentMessageId: 'message-1',
parentToolCallId: 'tool-1',
subagentType: 'agent-child',
subagentKind: 'agent',
depth: 1,
},
},
]);
const result = await deleteConvos('user123', { conversationId: childId });
expect(result.conversationIds).toEqual([childId]);
expect(await Conversation.findOne({ conversationId: parentId })).not.toBeNull();
});
it('should throw error if no conversations found', async () => {
await expect(deleteConvos('user123', { conversationId: 'non-existent' })).rejects.toThrow(
'Conversation not found or already deleted.',
);
});
it('allows a single-conversation cleanup retry after topology and messages are gone', async () => {
const eraseAgentTriggerDeliveryConversationResults = jest.fn(async () => undefined);
const scopedMethods = createConversationMethods(mongoose, {
getMessages,
deleteMessages,
eraseAgentTriggerDeliveryConversationResults,
});
const result = await scopedMethods.deleteConvos(
'user123',
{ conversationId: 'already-absent' },
{ allowEmpty: true },
);
expect(result.deletedCount).toBe(0);
expect(result.conversationIds).toEqual(['already-absent']);
expect(eraseAgentTriggerDeliveryConversationResults).toHaveBeenCalledWith('user123', [
'already-absent',
]);
});
it('supports an idempotent empty recovery sweep without hiding storage failures', async () => {
await expect(
deleteConvos(
'user123',
{ conversationId: { $in: ['already-absent'] } },
{ allowEmpty: true },
),
).resolves.toEqual({
acknowledged: true,
deletedCount: 0,
messages: { acknowledged: true, deletedCount: 0 },
conversationIds: [],
});
const find = jest.spyOn(Conversation, 'find').mockImplementationOnce(() => {
throw new Error('database unavailable');
});
await expect(deleteConvos('user123', {}, { allowEmpty: true })).rejects.toThrow(
'database unavailable',
);
find.mockRestore();
});
it('should decrement tag counts for a deleted bookmarked conversation', async () => {
await ConversationTag.create({ user: 'user123', tag: 'work', count: 2, position: 1 });
const convoId = uuidv4();
await Conversation.create({
conversationId: convoId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
tags: ['work'],
});
await deleteConvos('user123', { conversationId: convoId });
const tag = await ConversationTag.findOne({ user: 'user123', tag: 'work' }).lean();
expect(tag?.count).toBe(1);
});
it('should decrement counts for every tag on the deleted conversation', async () => {
await ConversationTag.create({ user: 'user123', tag: 'work', count: 3, position: 1 });
await ConversationTag.create({ user: 'user123', tag: 'personal', count: 1, position: 2 });
const convoId = uuidv4();
await Conversation.create({
conversationId: convoId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
tags: ['work', 'personal'],
});
await deleteConvos('user123', { conversationId: convoId });
const work = await ConversationTag.findOne({ user: 'user123', tag: 'work' }).lean();
const personal = await ConversationTag.findOne({ user: 'user123', tag: 'personal' }).lean();
expect(work?.count).toBe(2);
expect(personal?.count).toBe(0);
});
it('should decrement a shared tag once per deleted conversation when clearing all', async () => {
await ConversationTag.create({ user: 'user123', tag: 'work', count: 2, position: 1 });
await Conversation.create({
conversationId: uuidv4(),
user: 'user123',
endpoint: EModelEndpoint.openAI,
tags: ['work'],
});
await Conversation.create({
conversationId: uuidv4(),
user: 'user123',
endpoint: EModelEndpoint.openAI,
tags: ['work'],
});
await deleteConvos('user123', {});
const tag = await ConversationTag.findOne({ user: 'user123', tag: 'work' }).lean();
expect(tag?.count).toBe(0);
});
it('should not double-decrement duplicate tag entries within one conversation', async () => {
await ConversationTag.create({ user: 'user123', tag: 'work', count: 2, position: 1 });
const convoId = uuidv4();
await Conversation.create({
conversationId: convoId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
tags: ['work', 'work'],
});
await deleteConvos('user123', { conversationId: convoId });
const tag = await ConversationTag.findOne({ user: 'user123', tag: 'work' }).lean();
expect(tag?.count).toBe(1);
});
it('should clamp tag counts at zero and never go negative', async () => {
await ConversationTag.create({ user: 'user123', tag: 'work', count: 0, position: 1 });
const convoId = uuidv4();
await Conversation.create({
conversationId: convoId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
tags: ['work'],
});
await deleteConvos('user123', { conversationId: convoId });
const tag = await ConversationTag.findOne({ user: 'user123', tag: 'work' }).lean();
expect(tag?.count).toBe(0);
});
it('should not touch tags belonging to another user', async () => {
await ConversationTag.create({ user: 'other', tag: 'work', count: 5, position: 1 });
const convoId = uuidv4();
await Conversation.create({
conversationId: convoId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
tags: ['work'],
});
await deleteConvos('user123', { conversationId: convoId });
const tag = await ConversationTag.findOne({ user: 'other', tag: 'work' }).lean();
expect(tag?.count).toBe(5);
});
it('should not decrement tag counts when the delete removed nothing (lost race)', async () => {
await ConversationTag.create({ user: 'user123', tag: 'work', count: 2, position: 1 });
const convoId = uuidv4();
await Conversation.create({
conversationId: convoId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
tags: ['work'],
});
const deleteSpy = jest
.spyOn(Conversation, 'deleteMany')
.mockResolvedValueOnce({ acknowledged: true, deletedCount: 0 } as never);
await deleteConvos('user123', { conversationId: convoId });
deleteSpy.mockRestore();
const tag = await ConversationTag.findOne({ user: 'user123', tag: 'work' }).lean();
expect(tag?.count).toBe(2);
});
it('still decrements tag counts AND returns the deleted ids when message deletion fails', async () => {
await ConversationTag.create({ user: 'user123', tag: 'work', count: 2, position: 1 });
const convoId = uuidv4();
await Conversation.create({
conversationId: convoId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
tags: ['work'],
});
deleteMessages.mockRejectedValueOnce(new Error('message cleanup failed'));
// Post-delete cleanup is best-effort: the conversations are already gone, so the
// caller must still receive the deleted ids (downstream cleanup — e.g. agent
// checkpoint pruning — depends on them, and a retry would find nothing).
const result = await deleteConvos('user123', { conversationId: convoId });
expect(result.deletedCount).toBe(1);
expect(result.conversationIds).toEqual([convoId]);
expect(result.messages.deletedCount).toBe(0);
const tag = await ConversationTag.findOne({ user: 'user123', tag: 'work' }).lean();
expect(tag?.count).toBe(1);
const convo = await Conversation.findOne({ conversationId: convoId });
expect(convo).toBeNull();
});
});
describe('archiveAllConvos', () => {
it('defines an index for the user-scoped ObjectId batch scan', () => {
const indexFields = Conversation.schema.indexes().map(([fields]) => fields);
expect(indexFields).toContainEqual({ user: 1, _id: 1 });
});
it('archives every unarchived conversation for the user only', async () => {
const first = uuidv4();
const second = uuidv4();
const otherUsers = uuidv4();
const childThread = uuidv4();
await Conversation.create([
{ conversationId: first, user: 'user123', endpoint: EModelEndpoint.openAI },
{ conversationId: second, user: 'user123', endpoint: EModelEndpoint.openAI },
{ conversationId: otherUsers, user: 'user456', endpoint: EModelEndpoint.openAI },
{
conversationId: childThread,
user: 'user123',
endpoint: EModelEndpoint.agents,
subagentThread: {
rootConversationId: first,
parentConversationId: first,
parentMessageId: 'parent-message',
parentToolCallId: 'parent-tool-call',
subagentType: 'agent-child',
subagentKind: 'agent',
depth: 1,
},
},
]);
const result = await archiveAllConvos('user123');
expect(result.archivedCount).toBe(2);
const archived = await Conversation.find({
user: 'user123',
conversationId: { $in: [first, second] },
}).lean<IConversation[]>();
expect(archived.every((convo) => convo.isArchived === true)).toBe(true);
const untouched = await Conversation.findOne({
conversationId: otherUsers,
}).lean<IConversation>();
expect(untouched?.isArchived).not.toBe(true);
const child = await Conversation.findOne({
conversationId: childThread,
}).lean<IConversation>();
expect(child?.isArchived).not.toBe(true);
});
it('archives large snapshots in bounded batches', async () => {
const conversations = Array.from({ length: 501 }, (_, index) => ({
conversationId: `archive-batch-${index}`,
user: 'user123',
endpoint: EModelEndpoint.openAI,
}));
await Conversation.insertMany(conversations);
const updateManySpy = jest.spyOn(Conversation, 'updateMany');
try {
const result = await archiveAllConvos('user123');
expect(result.archivedCount).toBe(conversations.length);
expect(updateManySpy).toHaveBeenCalledTimes(2);
} finally {
updateManySpy.mockRestore();
}
const unarchivedCount = await Conversation.countDocuments({
user: 'user123',
isArchived: { $ne: true },
});
expect(unarchivedCount).toBe(0);
});
it('recovers destination projects from the sweep marker, not a per-conversation id list', async () => {
const conversations = Array.from({ length: 501 }, (_, index) => ({
conversationId: `archive-recovery-batch-${index}`,
user: 'user123',
endpoint: EModelEndpoint.openAI,
}));
await Conversation.insertMany(conversations);
const distinct = Conversation.distinct.bind(Conversation);
const distinctFilters: ArchiveDistinctFilter[] = [];
const distinctSpy = jest.spyOn(Conversation, 'distinct').mockImplementation(((
field,
filter,
) => {
distinctFilters.push((filter ?? {}) as ArchiveDistinctFilter);
return distinct(field, filter);
}) as typeof Conversation.distinct);
try {
const result = await archiveAllConvos('user123');
expect(result.archivedCount).toBe(conversations.length);
} finally {
distinctSpy.mockRestore();
}
/** Every id list stays within one batch, so nothing accumulates across the sweep. */
const idListSizes = distinctFilters
.map((filter) => filter._id?.$in?.length)
.filter((size): size is number => size !== undefined);
expect(idListSizes.length).toBeGreaterThan(0);
expect(Math.max(...idListSizes)).toBeLessThanOrEqual(500);
const recoveryFilters = distinctFilters.filter((filter) => filter.archivedAt instanceof Date);
expect(recoveryFilters).toHaveLength(1);
expect(recoveryFilters[0]._id).toBeUndefined();
expect(recoveryFilters[0]).toMatchObject({ user: 'user123', isArchived: true });
});
it('recovers a batch-sized destination move from the marker alone', async () => {
const destinationProject = await ChatProject.create({ user: 'user123', name: 'Destination' });
const conversations = Array.from({ length: 501 }, (_, index) => ({
conversationId: `archive-recovery-scale-${index}`,
user: 'user123',
endpoint: EModelEndpoint.openAI,
}));
await Conversation.insertMany(conversations);
/** The chats carry no project when the sweep captures them, so the destination is
* reachable only through the marker: nothing in the loop ever saw it. */
const updateMany = Conversation.updateMany.bind(Conversation);
const updateManySpy = jest.spyOn(Conversation, 'updateMany').mockImplementationOnce((async (
filter,
update,
options,
) => {
const result = await updateMany(filter, update, options);
await Conversation.updateMany(
{ user: 'user123' },
{ $set: { chatProjectId: destinationProject._id!.toString() } },
{ timestamps: false },
);
await ChatProject.findByIdAndUpdate(destinationProject._id, {
conversationCount: conversations.length,
lastConversationId: conversations[conversations.length - 1].conversationId,
});
return result;
}) as typeof Conversation.updateMany);
const distinct = Conversation.distinct.bind(Conversation);
const distinctSpy = jest
.spyOn(Conversation, 'distinct')
.mockRejectedValueOnce(new Error('project discovery failed'))
.mockRejectedValueOnce(new Error('project discovery failed'))
.mockRejectedValueOnce(new Error('project discovery failed'))
.mockImplementation(((...args) => distinct(...args)) as typeof Conversation.distinct);
try {
await expect(archiveAllConvos('user123')).rejects.toThrow('project discovery failed');
} finally {
updateManySpy.mockRestore();
distinctSpy.mockRestore();
}
const archived = await Conversation.countDocuments({ user: 'user123', isArchived: true });
expect(archived).toBe(500);
const refreshed = await ChatProject.findById(destinationProject._id).lean<IChatProject>();
expect(refreshed?.conversationCount).toBe(1);
});
it('replays a failed project refresh without abandoning the rest of the run', async () => {
const projects = await ChatProject.insertMany(
Array.from({ length: 11 }, (_, index) => ({
user: 'user123',
name: `Project ${index}`,
conversationCount: 1,
lastConversationId: `project-conversation-${index}`,
})),
);
await Conversation.insertMany(
projects.map((project, index) => ({
conversationId: `project-conversation-${index}`,
user: 'user123',
endpoint: EModelEndpoint.openAI,
chatProjectId: project._id!.toString(),
})),
);
const countDocumentsSpy = jest
.spyOn(Conversation, 'countDocuments')
.mockRejectedValueOnce(new Error('transient project refresh failure'));
try {
const result = await archiveAllConvos('user123');
expect(result.archivedCount).toBe(projects.length);
/** Ten in the first batch and one in the second, then a replay of the one that
* failed: nothing else in the run is still competing with it by then. */
expect(countDocumentsSpy).toHaveBeenCalledTimes(projects.length + 1);
} finally {
countDocumentsSpy.mockRestore();
}
const refreshed = await ChatProject.find({ user: 'user123' }).lean<IChatProject[]>();
expect(refreshed).toHaveLength(projects.length);
for (const project of refreshed) {
expect(project.conversationCount).toBe(0);
expect(project.lastConversationId).toBeNull();
}
});
it('leaves already-archived conversations untouched', async () => {
const alreadyArchived = uuidv4();
await Conversation.create({
conversationId: alreadyArchived,
user: 'user123',
endpoint: EModelEndpoint.openAI,
isArchived: true,
});
const result = await archiveAllConvos('user123');
expect(result.archivedCount).toBe(0);
});
it('skips temporary and retention-expired conversations', async () => {
const temporary = uuidv4();
const expired = uuidv4();
const visible = uuidv4();
await Conversation.create([
{
conversationId: temporary,
user: 'user123',
endpoint: EModelEndpoint.openAI,
isTemporary: true,
expiredAt: new Date(Date.now() + 60 * 60 * 1000),
},
{
conversationId: expired,
user: 'user123',
endpoint: EModelEndpoint.openAI,
expiredAt: new Date(Date.now() - 60 * 60 * 1000),
},
{ conversationId: visible, user: 'user123', endpoint: EModelEndpoint.openAI },
]);
const result = await archiveAllConvos('user123');
expect(result.archivedCount).toBe(1);
const temporaryConvo = await Conversation.findOne({
conversationId: temporary,
}).lean<IConversation>();
const expiredConvo = await Conversation.findOne({
conversationId: expired,
}).lean<IConversation>();
expect(temporaryConvo?.isArchived).not.toBe(true);
expect(expiredConvo?.isArchived).not.toBe(true);
});
it('preserves each conversation updatedAt so the archived view keeps its order', async () => {
const convoId = uuidv4();
const updatedAt = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
await Conversation.create({
conversationId: convoId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
createdAt: updatedAt,
updatedAt,
});
await archiveAllConvos('user123');
const archived = await Conversation.findOne({
conversationId: convoId,
}).lean<IConversation>();
expect(archived?.updatedAt?.toISOString()).toBe(updatedAt.toISOString());
});
it('stamps archivedAt so the sweep is dated and sorted as archived now', async () => {
const before = Date.now();
const convoIds = [uuidv4(), uuidv4()];
await Conversation.insertMany(
convoIds.map((conversationId) => ({
conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
createdAt: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
})),
);
await archiveAllConvos('user123');
const archived = await Conversation.find({ conversationId: { $in: convoIds } }).lean<
IConversation[]
>();
expect(archived).toHaveLength(2);
for (const conversation of archived) {
expect(conversation.archivedAt).toBeInstanceOf(Date);
expect(new Date(conversation.archivedAt ?? 0).getTime()).toBeGreaterThanOrEqual(before);
}
expect(new Date(archived[0].archivedAt ?? 0).toISOString()).toBe(
new Date(archived[1].archivedAt ?? 0).toISOString(),
);
});
it('leaves the archivedAt of an already-archived chat alone', async () => {
const original = new Date('2026-01-01T00:00:00.000Z');
const archivedId = uuidv4();
await Conversation.create({
conversationId: archivedId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
isArchived: true,
archivedAt: original,
});
await archiveAllConvos('user123');
const untouched = await Conversation.findOne({
conversationId: archivedId,
}).lean<IConversation>();
expect(new Date(untouched?.archivedAt ?? 0).toISOString()).toBe(original.toISOString());
});
it('refreshes stats for every project the archived conversations belonged to', async () => {
const project = await ChatProject.create({ user: 'user123', name: 'Project' });
const projectId = project._id!.toString();
const convoId = uuidv4();
await Conversation.create({
conversationId: convoId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
chatProjectId: projectId,
});
await ChatProject.findByIdAndUpdate(project._id, {
conversationCount: 1,
lastConversationId: convoId,
});
await archiveAllConvos('user123');
const refreshed = await ChatProject.findById(project._id).lean<IChatProject>();
expect(refreshed?.conversationCount).toBe(0);
expect(refreshed?.lastConversationId).toBeNull();
});
it('does not archive a project conversation created after the initial snapshot', async () => {
const project = await ChatProject.create({ user: 'user123', name: 'Project' });
const projectId = project._id!.toString();
const initialConversationId = uuidv4();
const concurrentConversationId = uuidv4();
await Conversation.create({
conversationId: initialConversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
});
const updateMany = Conversation.updateMany.bind(Conversation);
const updateManySpy = jest.spyOn(Conversation, 'updateMany').mockImplementationOnce((async (
filter,
update,
options,
) => {
await Conversation.create({
conversationId: concurrentConversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
chatProjectId: projectId,
});
await ChatProject.findByIdAndUpdate(project._id, {
conversationCount: 1,
lastConversationId: concurrentConversationId,
});
return await updateMany(filter, update, options);
}) as typeof Conversation.updateMany);
try {
const result = await archiveAllConvos('user123');
expect(result.archivedCount).toBe(1);
} finally {
updateManySpy.mockRestore();
}
const concurrentConversation = await Conversation.findOne({
conversationId: concurrentConversationId,
}).lean<IConversation>();
const refreshed = await ChatProject.findById(project._id).lean<IChatProject>();
expect(concurrentConversation?.isArchived).not.toBe(true);
expect(refreshed?.conversationCount).toBe(1);
expect(refreshed?.lastConversationId).toBe(concurrentConversationId);
});
it('retries destination-project discovery after a transient distinct failure', async () => {
const sourceProject = await ChatProject.create({ user: 'user123', name: 'Source' });
const destinationProject = await ChatProject.create({ user: 'user123', name: 'Destination' });
const conversationId = uuidv4();
await Conversation.create({
conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
chatProjectId: sourceProject._id!.toString(),
});
await ChatProject.findByIdAndUpdate(sourceProject._id, {
conversationCount: 1,
lastConversationId: conversationId,
});
const updateMany = Conversation.updateMany.bind(Conversation);
const updateManySpy = jest.spyOn(Conversation, 'updateMany').mockImplementationOnce((async (
filter,
update,
options,
) => {
await Conversation.updateOne(
{ conversationId },
{ $set: { chatProjectId: destinationProject._id!.toString() } },
);
await ChatProject.findByIdAndUpdate(sourceProject._id, {
conversationCount: 0,
lastConversationId: null,
});
await ChatProject.findByIdAndUpdate(destinationProject._id, {
conversationCount: 1,
lastConversationId: conversationId,
});
return await updateMany(filter, update, options);
}) as typeof Conversation.updateMany);
const distinct = Conversation.distinct.bind(Conversation);
const distinctSpy = jest
.spyOn(Conversation, 'distinct')
.mockRejectedValueOnce(new Error('transient project discovery failure'))
.mockImplementation(((...args) => distinct(...args)) as typeof Conversation.distinct);
try {
const result = await archiveAllConvos('user123');
expect(result.archivedCount).toBe(1);
} finally {
updateManySpy.mockRestore();
distinctSpy.mockRestore();
}
const refreshed = await ChatProject.findById(destinationProject._id).lean<IChatProject>();
expect(refreshed?.conversationCount).toBe(0);
expect(refreshed?.lastConversationId).toBeNull();
});
it('reconciles the destination project when discovery retries exhaust after a move', async () => {
const sourceProject = await ChatProject.create({ user: 'user123', name: 'Source' });
const destinationProject = await ChatProject.create({ user: 'user123', name: 'Destination' });
const conversationId = uuidv4();
await Conversation.create({
conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
chatProjectId: sourceProject._id!.toString(),
});
await ChatProject.findByIdAndUpdate(sourceProject._id, {
conversationCount: 1,
lastConversationId: conversationId,
});
const updateMany = Conversation.updateMany.bind(Conversation);
const updateManySpy = jest.spyOn(Conversation, 'updateMany').mockImplementationOnce((async (
filter,
update,
options,
) => {
await Conversation.updateOne(
{ conversationId },
{ $set: { chatProjectId: destinationProject._id!.toString() } },
);
await ChatProject.findByIdAndUpdate(sourceProject._id, {
conversationCount: 0,
lastConversationId: null,
});
await ChatProject.findByIdAndUpdate(destinationProject._id, {
conversationCount: 1,
lastConversationId: conversationId,
});
return await updateMany(filter, update, options);
}) as typeof Conversation.updateMany);
const distinct = Conversation.distinct.bind(Conversation);
const distinctSpy = jest
.spyOn(Conversation, 'distinct')
.mockRejectedValueOnce(new Error('project discovery failed'))
.mockRejectedValueOnce(new Error('project discovery failed'))
.mockRejectedValueOnce(new Error('project discovery failed'))
.mockImplementation(((...args) => distinct(...args)) as typeof Conversation.distinct);
try {
await expect(archiveAllConvos('user123')).rejects.toThrow('project discovery failed');
} finally {
updateManySpy.mockRestore();
distinctSpy.mockRestore();
}
const archived = await Conversation.findOne({ conversationId }).lean<IConversation>();
const refreshed = await ChatProject.findById(destinationProject._id).lean<IChatProject>();
expect(archived?.isArchived).toBe(true);
expect(refreshed?.conversationCount).toBe(0);
expect(refreshed?.lastConversationId).toBeNull();
});
it('refreshes the destination project when a captured conversation moves before archiving', async () => {
const sourceProject = await ChatProject.create({ user: 'user123', name: 'Source' });
const destinationProject = await ChatProject.create({ user: 'user123', name: 'Destination' });
const conversationId = uuidv4();
await Conversation.create({
conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
chatProjectId: sourceProject._id!.toString(),
});
await ChatProject.findByIdAndUpdate(sourceProject._id, {
conversationCount: 1,
lastConversationId: conversationId,
});
const updateMany = Conversation.updateMany.bind(Conversation);
const updateManySpy = jest.spyOn(Conversation, 'updateMany').mockImplementationOnce((async (
filter,
update,
options,
) => {
await Conversation.updateOne(
{ conversationId },
{ $set: { chatProjectId: destinationProject._id!.toString() } },
);
await ChatProject.findByIdAndUpdate(sourceProject._id, {
conversationCount: 0,
lastConversationId: null,
});
await ChatProject.findByIdAndUpdate(destinationProject._id, {
conversationCount: 1,
lastConversationId: conversationId,
});
return await updateMany(filter, update, options);
}) as typeof Conversation.updateMany);
try {
const result = await archiveAllConvos('user123');
expect(result.archivedCount).toBe(1);
} finally {
updateManySpy.mockRestore();
}
const refreshed = await ChatProject.findById(destinationProject._id).lean<IChatProject>();
expect(refreshed?.conversationCount).toBe(0);
expect(refreshed?.lastConversationId).toBeNull();
});
it('refreshes project stats for committed batches when a later batch fails', async () => {
const project = await ChatProject.create({ user: 'user123', name: 'Project' });
const projectId = project._id!.toString();
const conversations = Array.from({ length: 501 }, (_, index) => ({
conversationId: `archive-partial-fail-${index}`,
user: 'user123',
endpoint: EModelEndpoint.openAI,
chatProjectId: projectId,
}));
await Conversation.insertMany(conversations);
await ChatProject.findByIdAndUpdate(project._id, {
conversationCount: conversations.length,
lastConversationId: conversations[conversations.length - 1].conversationId,
});
const updateMany = Conversation.updateMany.bind(Conversation);
const updateManySpy = jest
.spyOn(Conversation, 'updateMany')
.mockImplementationOnce(((...args) =>
updateMany(...args)) as typeof Conversation.updateMany)
.mockImplementationOnce(() => {
throw new Error('later batch update failed');
});
try {
await expect(archiveAllConvos('user123')).rejects.toThrow('later batch update failed');
} finally {
updateManySpy.mockRestore();
}
const archivedCount = await Conversation.countDocuments({
user: 'user123',
isArchived: true,
});
expect(archivedCount).toBe(500);
const remaining = await Conversation.findOne({
user: 'user123',
isArchived: { $ne: true },
}).lean<IConversation>();
const refreshed = await ChatProject.findById(project._id).lean<IChatProject>();
expect(refreshed?.conversationCount).toBe(1);
expect(refreshed?.lastConversationId).toBe(remaining?.conversationId);
});
it('reconciles projects when an archive write commits but its result is lost', async () => {
const destinationProject = await ChatProject.create({ user: 'user123', name: 'Destination' });
const conversationId = uuidv4();
await Conversation.create({
conversationId,
user: 'user123',
endpoint: EModelEndpoint.openAI,
});
/** The chat carries no project when the sweep captures it and the write never
* reports a modified count, so the marker is the only thing left that knows the
* archive happened at all. */
const updateMany = Conversation.updateMany.bind(Conversation);
const updateManySpy = jest.spyOn(Conversation, 'updateMany').mockImplementationOnce((async (
filter,
update,
options,
/** Annotated because a mock that only ever throws infers `Promise<never>`, which
* the cast back to the real signature rejects. */
): Promise<UpdateResult> => {
await updateMany(filter, update, options);
await Conversation.updateOne(
{ conversationId },
{ $set: { chatProjectId: destinationProject._id!.toString() } },
);
await ChatProject.findByIdAndUpdate(destinationProject._id, {
conversationCount: 1,
lastConversationId: conversationId,
});
throw new Error('connection reset before the write acknowledged');
}) as typeof Conversation.updateMany);
try {
await expect(archiveAllConvos('user123')).rejects.toThrow(
'connection reset before the write acknowledged',
);
} finally {
updateManySpy.mockRestore();
}
const archived = await Conversation.findOne({ conversationId }).lean<IConversation>();
expect(archived?.isArchived).toBe(true);
const refreshed = await ChatProject.findById(destinationProject._id).lean<IChatProject>();
expect(refreshed?.conversationCount).toBe(0);
expect(refreshed?.lastConversationId).toBeNull();
});
it('does not let a save in flight restore the project pointer it just cleared', async () => {
const project = await ChatProject.create({ user: 'user123', name: 'Project' });
const projectId = project._id!.toString();
const conversationId = uuidv4();
const anchor = new Date('2026-01-01T00:00:00.000Z');
await Conversation.collection.insertOne({
conversationId,
user: 'user123',
title: 'legacy chat with no isTemporary',
endpoint: EModelEndpoint.openAI,
chatProjectId: projectId,
expiredAt: null,
isArchived: false,
createdAt: anchor,
updatedAt: anchor,
});
await ChatProject.findByIdAndUpdate(project._id, {
conversationCount: 1,
lastConversationAt: anchor,
lastConversationId: conversationId,
});
/** The sweep lands after the save's own write has returned, so the save carries a
* document that still says the chat is visible. Re-sending the unchanged
* `chatProjectId`, as a client saving into an open project chat does, is what puts
* the tail on the pointer branch instead of the recompute one. */
const findOneAndUpdate = Conversation.findOneAndUpdate.bind(Conversation);
const findOneAndUpdateSpy = jest
.spyOn(Conversation, 'findOneAndUpdate')
.mockImplementationOnce((async (filter, update, options) => {
const result = await findOneAndUpdate(filter, update, options);
await archiveAllConvos('user123');
return result;
}) as typeof Conversation.findOneAndUpdate);
try {
await saveConvo(
{ userId: 'user123' },
{ conversationId, chatProjectId: projectId, title: 'Renamed while the sweep ran' },
{ noUpsert: true },
);
} finally {
findOneAndUpdateSpy.mockRestore();
}
const archived = await Conversation.findOne({ conversationId }).lean<IConversation>();
expect(archived?.isArchived).toBe(true);
const refreshed = await ChatProject.findById(project._id).lean<IChatProject>();
expect(refreshed?.lastConversationId).toBeNull();
expect(refreshed?.lastConversationAt).toBeNull();
expect(refreshed?.conversationCount).toBe(0);
});
it('repairs the project when the sweep lands while the pointer write is in flight', async () => {
const project = await ChatProject.create({ user: 'user123', name: 'Project' });
const projectId = project._id!.toString();
const conversationId = uuidv4();
const anchor = new Date('2026-01-01T00:00:00.000Z');
await Conversation.collection.insertOne({
conversationId,
user: 'user123',
title: 'chat being saved',
endpoint: EModelEndpoint.openAI,
chatProjectId: projectId,
expiredAt: null,
isArchived: false,
createdAt: anchor,
updatedAt: anchor,
});
await ChatProject.findByIdAndUpdate(project._id, {
conversationCount: 1,
lastConversationAt: anchor,
lastConversationId: conversationId,
});
/** The sweep runs after the save has decided the chat is visible and immediately
* before its pointer write commits, which is the one window a check taken before
* that write cannot cover. */
const updateOne = ChatProject.updateOne.bind(ChatProject);
const updateOneSpy = jest.spyOn(ChatProject, 'updateOne').mockImplementationOnce((async (
filter,
update,
options,
) => {
await archiveAllConvos('user123');
return await updateOne(filter, update, options);
}) as typeof ChatProject.updateOne);
try {
await saveConvo(
{ userId: 'user123' },
{ conversationId, chatProjectId: projectId, title: 'Renamed while the sweep ran' },
{ noUpsert: true },
);
} finally {
updateOneSpy.mockRestore();
}
const archived = await Conversation.findOne({ conversationId }).lean<IConversation>();
expect(archived?.isArchived).toBe(true);
const refreshed = await ChatProject.findById(project._id).lean<IChatProject>();
expect(refreshed?.lastConversationId).toBeNull();
expect(refreshed?.lastConversationAt).toBeNull();
expect(refreshed?.conversationCount).toBe(0);
});
it('returns zero when the user has no conversations', async () => {
const result = await archiveAllConvos('user123');
expect(result.archivedCount).toBe(0);
});
});
describe('Error Handling', () => {
it('should handle database errors in saveConvo', async () => {
// Force a database error by disconnecting
await mongoose.disconnect();
const result = await saveConvo(mockCtx, mockConversationData);
expect(result).toEqual({ message: 'Error saving conversation' });
// Reconnect for other tests
await mongoose.connect(mongoServer.getUri());
});
});
describe('getConvosByCursor pagination', () => {
/**
* Helper to create conversations with specific timestamps
* Uses collection.insertOne to bypass Mongoose timestamps entirely
*/
const createConvoWithTimestamps = async (index: number, createdAt: Date, updatedAt: Date) => {
const conversationId = uuidv4();
// Use collection-level insert to bypass Mongoose timestamps
await Conversation.collection.insertOne({
conversationId,
user: 'user123',
title: `Conversation ${index}`,
endpoint: EModelEndpoint.openAI,
expiredAt: null,
isArchived: false,
createdAt,
updatedAt,
});
return Conversation.findOne({ conversationId }).lean<IConversation>();
};
it('should flag conversations that have an active shared link', async () => {
const SharedLink = mongoose.models.SharedLink as mongoose.Model<{
conversationId: string;
user: string;
shareId: string;
expiredAt?: Date | null;
}>;
const baseTime = new Date('2026-03-01T00:00:00.000Z');
const shared = await createConvoWithTimestamps(1, baseTime, baseTime);
const unshared = await createConvoWithTimestamps(2, baseTime, baseTime);
const expiredShare = await createConvoWithTimestamps(3, baseTime, baseTime);
await SharedLink.create([
{
conversationId: shared!.conversationId,
user: 'user123',
shareId: `share-${uuidv4()}`,
},
{
conversationId: expiredShare!.conversationId,
user: 'user123',
shareId: `share-${uuidv4()}`,
expiredAt: new Date('2020-01-01T00:00:00.000Z'),
},
]);
const result = await methods.getConvosByCursor('user123', { limit: 25 });
const byId = new Map(result.conversations.map((convo) => [convo.conversationId, convo]));
expect(byId.get(shared!.conversationId)?.isShared).toBe(true);
expect(byId.get(unshared!.conversationId)?.isShared).toBe(false);
expect(byId.get(expiredShare!.conversationId)?.isShared).toBe(false);
await SharedLink.deleteMany({ user: 'user123' });
await Conversation.deleteMany({ user: 'user123' });
});
it('should skip the shared lookup when shared links are disabled', async () => {
const SharedLink = mongoose.models.SharedLink as mongoose.Model<{
conversationId: string;
user: string;
shareId: string;
}>;
const baseTime = new Date('2026-03-02T00:00:00.000Z');
const shared = await createConvoWithTimestamps(1, baseTime, baseTime);
await SharedLink.create({
conversationId: shared!.conversationId,
user: 'user123',
shareId: `share-${uuidv4()}`,
});
process.env.ALLOW_SHARED_LINKS = 'false';
try {
const result = await methods.getConvosByCursor('user123', { limit: 25 });
expect(result.conversations[0].isShared).toBeUndefined();
} finally {
delete process.env.ALLOW_SHARED_LINKS;
}
await SharedLink.deleteMany({ user: 'user123' });
await Conversation.deleteMany({ user: 'user123' });
});
it('should page through titles that share a timestamp', async () => {
// Imports land with identical titles and timestamps, so (title, updatedAt)
// alone cannot mark where the previous page stopped.
const sameTime = new Date('2026-04-01T00:00:00.000Z');
for (let index = 0; index < 6; index++) {
await Conversation.collection.insertOne({
conversationId: uuidv4(),
user: 'user123',
title: 'Imported chat',
endpoint: EModelEndpoint.openAI,
expiredAt: null,
isArchived: false,
createdAt: sameTime,
updatedAt: sameTime,
});
}
const seen = new Set<string>();
let cursor: string | null = null;
for (let page = 0; page < 6; page++) {
const result = await methods.getConvosByCursor('user123', {
limit: 2,
sortBy: 'title',
sortDirection: 'asc',
cursor,
});
result.conversations.forEach((convo) => seen.add(convo.conversationId));
cursor = result.nextCursor;
if (!cursor) {
break;
}
}
expect(seen.size).toBe(6);
await Conversation.deleteMany({ user: 'user123' });
});
it('should page past conversations that have no title', async () => {
const sameTime = new Date('2026-04-15T00:00:00.000Z');
for (let index = 0; index < 3; index++) {
await Conversation.collection.insertOne({
conversationId: uuidv4(),
user: 'user123',
endpoint: EModelEndpoint.openAI,
expiredAt: null,
isArchived: false,
createdAt: sameTime,
updatedAt: sameTime,
});
await Conversation.collection.insertOne({
conversationId: uuidv4(),
user: 'user123',
title: `Named ${index}`,
endpoint: EModelEndpoint.openAI,
expiredAt: null,
isArchived: false,
createdAt: sameTime,
updatedAt: sameTime,
});
}
// Missing titles sort before every string, and comparison operators never cross
// that type boundary, so the group needs cursor clauses of its own.
for (const sortDirection of ['asc', 'desc']) {
const seen = new Set<string>();
let cursor: string | null = null;
for (let page = 0; page < 6; page++) {
const result = await methods.getConvosByCursor('user123', {
limit: 2,
sortBy: 'title',
sortDirection,
cursor,
});
result.conversations.forEach((convo) => seen.add(convo.conversationId));
cursor = result.nextCursor;
if (!cursor) {
break;
}
}
expect(seen.size).toBe(6);
}
await Conversation.deleteMany({ user: 'user123' });
});
it('should not skip conversations at page boundaries', async () => {
// Create 30 conversations to ensure pagination (limit is 25)
const baseTime = new Date('2026-01-01T00:00:00.000Z');
const convos: unknown[] = [];
for (let i = 0; i < 30; i++) {
const updatedAt = new Date(baseTime.getTime() - i * 60000); // Each 1 minute apart
const convo = await createConvoWithTimestamps(i, updatedAt, updatedAt);
convos.push(convo);
}
// Fetch first page
const page1 = await getConvosByCursor('user123', { limit: 25 });
expect(page1.conversations).toHaveLength(25);
expect(page1.nextCursor).toBeTruthy();
// Fetch second page using cursor
const page2 = await getConvosByCursor('user123', {
limit: 25,
cursor: page1.nextCursor,
});
// Should get remaining 5 conversations
expect(page2.conversations).toHaveLength(5);
expect(page2.nextCursor).toBeNull();
// Verify no duplicates and no gaps
const allIds = [
...page1.conversations.map((c: IConversation) => c.conversationId),
...page2.conversations.map((c: IConversation) => c.conversationId),
];
const uniqueIds = new Set(allIds);
expect(uniqueIds.size).toBe(30); // All 30 conversations accounted for
expect(allIds.length).toBe(30); // No duplicates
});
it('should include conversation at exact page boundary (item 26 bug fix)', async () => {
// This test specifically verifies the fix for the bug where item 26
// (the first item that should appear on page 2) was being skipped
const baseTime = new Date('2026-01-01T12:00:00.000Z');
// Create exactly 26 conversations
const convos: (IConversation | null)[] = [];
for (let i = 0; i < 26; i++) {
const updatedAt = new Date(baseTime.getTime() - i * 60000);
const convo = await createConvoWithTimestamps(i, updatedAt, updatedAt);
convos.push(convo);
}
// The 26th conversation (index 25) should be on page 2
const item26 = convos[25];
// Fetch first page with limit 25
const page1 = await getConvosByCursor('user123', { limit: 25 });
expect(page1.conversations).toHaveLength(25);
expect(page1.nextCursor).toBeTruthy();
// Item 26 should NOT be in page 1
const page1Ids = page1.conversations.map((c: IConversation) => c.conversationId);
expect(page1Ids).not.toContain(item26!.conversationId);
// Fetch second page
const page2 = await getConvosByCursor('user123', {
limit: 25,
cursor: page1.nextCursor,
});
// Item 26 MUST be in page 2 (this was the bug - it was being skipped)
expect(page2.conversations).toHaveLength(1);
expect(page2.conversations[0].conversationId).toBe(item26!.conversationId);
});
it('should sort by updatedAt DESC by default', async () => {
// Create conversations with different updatedAt times
// Note: createdAt is older but updatedAt varies
const convo1 = await createConvoWithTimestamps(
1,
new Date('2026-01-01T00:00:00.000Z'), // oldest created
new Date('2026-01-03T00:00:00.000Z'), // most recently updated
);
const convo2 = await createConvoWithTimestamps(
2,
new Date('2026-01-02T00:00:00.000Z'), // middle created
new Date('2026-01-02T00:00:00.000Z'), // middle updated
);
const convo3 = await createConvoWithTimestamps(
3,
new Date('2026-01-03T00:00:00.000Z'), // newest created
new Date('2026-01-01T00:00:00.000Z'), // oldest updated
);
const result = await getConvosByCursor('user123');
// Should be sorted by updatedAt DESC (most recent first)
expect(result?.conversations).toHaveLength(3);
expect(result?.conversations[0].conversationId).toBe(convo1!.conversationId); // Jan 3 updatedAt
expect(result?.conversations[1].conversationId).toBe(convo2!.conversationId); // Jan 2 updatedAt
expect(result?.conversations[2].conversationId).toBe(convo3!.conversationId); // Jan 1 updatedAt
});
it('should handle conversations with same updatedAt (tie-breaker)', async () => {
const sameTime = new Date('2026-01-01T12:00:00.000Z');
// Create 3 conversations with exact same updatedAt
const convo1 = await createConvoWithTimestamps(1, sameTime, sameTime);
const convo2 = await createConvoWithTimestamps(2, sameTime, sameTime);
const convo3 = await createConvoWithTimestamps(3, sameTime, sameTime);
const result = await getConvosByCursor('user123');
// All 3 should be returned (no skipping due to same timestamps)
expect(result?.conversations).toHaveLength(3);
const returnedIds = result?.conversations.map((c: IConversation) => c.conversationId);
expect(returnedIds).toContain(convo1!.conversationId);
expect(returnedIds).toContain(convo2!.conversationId);
expect(returnedIds).toContain(convo3!.conversationId);
});
it('should handle cursor pagination with conversations updated during pagination', async () => {
// Simulate the scenario where a conversation is updated between page fetches
const baseTime = new Date('2026-01-01T00:00:00.000Z');
// Create 30 conversations
for (let i = 0; i < 30; i++) {
const updatedAt = new Date(baseTime.getTime() - i * 60000);
await createConvoWithTimestamps(i, updatedAt, updatedAt);
}
// Fetch first page
const page1 = await getConvosByCursor('user123', { limit: 25 });
expect(page1.conversations).toHaveLength(25);
// Now update one of the conversations that should be on page 2
// to have a newer updatedAt (simulating user activity during pagination)
const convosOnPage2 = await Conversation.find({ user: 'user123' })
.sort({ updatedAt: -1 })
.skip(25)
.limit(5);
if (convosOnPage2.length > 0) {
const updatedConvo = convosOnPage2[0];
await Conversation.updateOne(
{ _id: updatedConvo._id },
{ updatedAt: new Date('2026-01-02T00:00:00.000Z') }, // Much newer
);
}
// Fetch second page with original cursor
const page2 = await getConvosByCursor('user123', {
limit: 25,
cursor: page1.nextCursor,
});
// The updated conversation might not be in page 2 anymore
// (it moved to the front), but we should still get remaining items
// without errors and without infinite loops
expect(page2.conversations.length).toBeGreaterThanOrEqual(0);
});
it('should correctly decode and use cursor for pagination', async () => {
const baseTime = new Date('2026-01-01T00:00:00.000Z');
// Create 30 conversations
for (let i = 0; i < 30; i++) {
const updatedAt = new Date(baseTime.getTime() - i * 60000);
await createConvoWithTimestamps(i, updatedAt, updatedAt);
}
// Fetch first page
const page1 = await getConvosByCursor('user123', { limit: 25 });
// Decode the cursor to verify it's based on the last RETURNED item
const decodedCursor = JSON.parse(
Buffer.from(page1.nextCursor as string, 'base64').toString(),
);
// The cursor should match the last item in page1 (item at index 24)
const lastReturnedItem = page1.conversations[24] as IConversation;
expect(new Date(decodedCursor.primary).getTime()).toBe(
new Date(lastReturnedItem.updatedAt ?? 0).getTime(),
);
});
it('should support sortBy createdAt when explicitly requested', async () => {
// Create conversations with different timestamps
const convo1 = await createConvoWithTimestamps(
1,
new Date('2026-01-03T00:00:00.000Z'), // newest created
new Date('2026-01-01T00:00:00.000Z'), // oldest updated
);
const convo2 = await createConvoWithTimestamps(
2,
new Date('2026-01-01T00:00:00.000Z'), // oldest created
new Date('2026-01-03T00:00:00.000Z'), // newest updated
);
// Verify timestamps were set correctly
expect(new Date(convo1!.createdAt ?? 0).getTime()).toBe(
new Date('2026-01-03T00:00:00.000Z').getTime(),
);
expect(new Date(convo2!.createdAt ?? 0).getTime()).toBe(
new Date('2026-01-01T00:00:00.000Z').getTime(),
);
const result = await getConvosByCursor('user123', { sortBy: 'createdAt' });
// Should be sorted by createdAt DESC
expect(result?.conversations).toHaveLength(2);
expect(result?.conversations[0].conversationId).toBe(convo1!.conversationId); // Jan 3 createdAt
expect(result?.conversations[1].conversationId).toBe(convo2!.conversationId); // Jan 1 createdAt
});
it('should handle empty result set gracefully', async () => {
const result = await getConvosByCursor('user123');
expect(result?.conversations).toHaveLength(0);
expect(result?.nextCursor).toBeNull();
});
it('should handle exactly limit number of conversations (no next page)', async () => {
const baseTime = new Date('2026-01-01T00:00:00.000Z');
// Create exactly 25 conversations (equal to default limit)
for (let i = 0; i < 25; i++) {
const updatedAt = new Date(baseTime.getTime() - i * 60000);
await createConvoWithTimestamps(i, updatedAt, updatedAt);
}
const result = await getConvosByCursor('user123', { limit: 25 });
expect(result?.conversations).toHaveLength(25);
expect(result?.nextCursor).toBeNull(); // No next page
});
});
describe('getConvosByCursor archivedAt sorting', () => {
const insertArchived = async (title: string, archivedAt: Date | null, updatedAt: Date) => {
const conversationId = uuidv4();
await Conversation.collection.insertOne({
conversationId,
user: 'user123',
title,
endpoint: EModelEndpoint.openAI,
expiredAt: null,
isArchived: true,
createdAt: updatedAt,
updatedAt,
...(archivedAt === null ? {} : { archivedAt }),
});
return conversationId;
};
it('accepts archivedAt as a sort field', async () => {
const base = new Date('2026-06-01T00:00:00.000Z');
const older = await insertArchived('older', new Date(base.getTime() - 60000), base);
const newer = await insertArchived('newer', new Date(base.getTime() + 60000), base);
const result = await getConvosByCursor('user123', {
isArchived: true,
sortBy: 'archivedAt',
sortDirection: 'desc',
});
expect(result.conversations.map((convo) => convo.conversationId)).toEqual([newer, older]);
});
/* Everything archived before the field existed has no stamp, so the missing-value
group is the common case here, not an edge case. A cursor that collapsed a null
stamp to the epoch would restart paging from 1970 and replay the whole archive. */
it('pages across stamped and unstamped chats without repeating or dropping any', async () => {
const base = new Date('2026-06-01T00:00:00.000Z');
const expected = new Set<string>();
for (let index = 0; index < 4; index++) {
expected.add(
await insertArchived(`stamped ${index}`, new Date(base.getTime() + index * 60000), base),
);
}
for (let index = 0; index < 4; index++) {
expected.add(
await insertArchived(`legacy ${index}`, null, new Date(base.getTime() + index * 60000)),
);
}
const seen: string[] = [];
let cursor: string | null = null;
for (let page = 0; page < 10; page++) {
const result = await getConvosByCursor('user123', {
isArchived: true,
sortBy: 'archivedAt',
sortDirection: 'desc',
limit: 3,
cursor,
});
seen.push(...result.conversations.map((convo) => convo.conversationId));
cursor = result.nextCursor;
if (!cursor) {
break;
}
}
expect(new Set(seen)).toEqual(expected);
expect(seen.length).toBe(expected.size);
});
it('orders unstamped chats last when sorting newest first', async () => {
const base = new Date('2026-06-01T00:00:00.000Z');
const stamped = await insertArchived('stamped', base, base);
const legacy = await insertArchived('legacy', null, base);
const result = await getConvosByCursor('user123', {
isArchived: true,
sortBy: 'archivedAt',
sortDirection: 'desc',
});
expect(result.conversations.map((convo) => convo.conversationId)).toEqual([stamped, legacy]);
});
/** Ascending takes the other null branch: the unstamped group comes first and the
* page that leaves it has to pick up every stamped chat behind it. */
it('pages across stamped and unstamped chats when sorting oldest first', async () => {
const base = new Date('2026-06-01T00:00:00.000Z');
const expected = new Set<string>();
for (let index = 0; index < 3; index++) {
expected.add(
await insertArchived(`stamped ${index}`, new Date(base.getTime() + index * 60000), base),
);
}
for (let index = 0; index < 3; index++) {
expected.add(
await insertArchived(`legacy ${index}`, null, new Date(base.getTime() + index * 60000)),
);
}
const seen: string[] = [];
let cursor: string | null = null;
for (let page = 0; page < 10; page++) {
const result = await getConvosByCursor('user123', {
isArchived: true,
sortBy: 'archivedAt',
sortDirection: 'asc',
limit: 2,
cursor,
});
seen.push(...result.conversations.map((convo) => convo.conversationId));
cursor = result.nextCursor;
if (!cursor) {
break;
}
}
expect(new Set(seen)).toEqual(expected);
expect(seen.length).toBe(expected.size);
});
/** The cell renders `archivedAt ?? createdAt`, so the legacy group has to come back
* in that same createdAt order; ordering it by last activity read out of order. */
it('orders the legacy group by the createdAt it displays, not last activity', async () => {
const base = new Date('2026-06-01T00:00:00.000Z');
const olderCreated = uuidv4();
const newerCreated = uuidv4();
/* createdAt and updatedAt deliberately disagree: ordering by activity would
invert these two relative to the dates the dialog shows. */
await Conversation.collection.insertOne({
conversationId: olderCreated,
user: 'user123',
title: 'created first, touched last',
endpoint: EModelEndpoint.openAI,
expiredAt: null,
isArchived: true,
createdAt: new Date(base.getTime() - 60000),
updatedAt: new Date(base.getTime() + 60000),
});
await Conversation.collection.insertOne({
conversationId: newerCreated,
user: 'user123',
title: 'created last, touched first',
endpoint: EModelEndpoint.openAI,
expiredAt: null,
isArchived: true,
createdAt: new Date(base.getTime() + 60000),
updatedAt: new Date(base.getTime() - 60000),
});
const result = await getConvosByCursor('user123', {
isArchived: true,
sortBy: 'archivedAt',
sortDirection: 'desc',
});
expect(result.conversations.map((convo) => convo.conversationId)).toEqual([
newerCreated,
olderCreated,
]);
});
it('still rejects a sort field that is not allowed', async () => {
await expect(getConvosByCursor('user123', { sortBy: 'pinned' })).rejects.toThrow(
/Invalid sortBy field/,
);
});
});
describe('getConvosByCursor pinned filter', () => {
const insertConvo = async ({
user = 'user123',
title,
updatedAt,
pinned,
isArchived = false,
}: {
user?: string;
title: string;
updatedAt: Date;
pinned?: boolean;
isArchived?: boolean;
}) => {
const conversationId = uuidv4();
await Conversation.collection.insertOne({
conversationId,
user,
title,
endpoint: EModelEndpoint.openAI,
expiredAt: null,
isArchived,
createdAt: updatedAt,
updatedAt,
...(pinned === undefined ? {} : { pinned }),
});
return conversationId;
};
it('returns only pinned conversations when pinned is requested', async () => {
const baseTime = new Date('2026-05-01T00:00:00.000Z');
const pinnedId = await insertConvo({
title: 'Pinned chat',
updatedAt: baseTime,
pinned: true,
});
await insertConvo({ title: 'Unpinned chat', updatedAt: baseTime, pinned: false });
await insertConvo({ title: 'Never pinned chat', updatedAt: baseTime });
const result = await getConvosByCursor('user123', { pinned: true });
expect(result.conversations.map((convo) => convo.conversationId)).toEqual([pinnedId]);
});
/** The sidebar's pinned section used to filter the paginated chats list, so a pin
* older than the first page stayed hidden until that list scrolled far enough. */
it('returns a pin that falls outside the first page of the unfiltered list', async () => {
const baseTime = new Date('2026-05-01T00:00:00.000Z');
const pinnedId = await insertConvo({
title: 'Initial Greeting',
updatedAt: baseTime,
pinned: true,
});
for (let index = 0; index < 30; index++) {
await insertConvo({
title: `Newer chat ${index}`,
updatedAt: new Date(baseTime.getTime() + (index + 1) * 60000),
});
}
const firstPage = await getConvosByCursor('user123', { limit: 25 });
expect(firstPage.conversations.map((convo) => convo.conversationId)).not.toContain(pinnedId);
const pinnedResult = await getConvosByCursor('user123', { pinned: true });
expect(pinnedResult.conversations.map((convo) => convo.conversationId)).toEqual([pinnedId]);
});
it('excludes archived pins and other users’ pins', async () => {
const baseTime = new Date('2026-05-01T00:00:00.000Z');
const visibleId = await insertConvo({
title: 'Visible pin',
updatedAt: baseTime,
pinned: true,
});
await insertConvo({
title: 'Archived pin',
updatedAt: baseTime,
pinned: true,
isArchived: true,
});
await insertConvo({
user: 'other-user',
title: 'Someone else’s pin',
updatedAt: baseTime,
pinned: true,
});
const result = await getConvosByCursor('user123', { pinned: true });
expect(result.conversations.map((convo) => convo.conversationId)).toEqual([visibleId]);
});
it('leaves the list unfiltered when pinned is not requested', async () => {
const baseTime = new Date('2026-05-01T00:00:00.000Z');
await insertConvo({ title: 'Pinned chat', updatedAt: baseTime, pinned: true });
await insertConvo({ title: 'Unpinned chat', updatedAt: baseTime });
const result = await getConvosByCursor('user123', {});
expect(result.conversations).toHaveLength(2);
});
});
describe('getConvosByCursor page size bounds', () => {
const TOTAL = 105;
const user = 'page-size-user';
beforeEach(async () => {
const baseTime = new Date('2026-06-01T00:00:00.000Z').getTime();
await Conversation.collection.insertMany(
Array.from({ length: TOTAL }, (_, index) => ({
conversationId: uuidv4(),
user,
title: `Conversation ${index}`,
endpoint: EModelEndpoint.openAI,
expiredAt: null,
isArchived: false,
createdAt: new Date(baseTime + index * 1000),
updatedAt: new Date(baseTime + index * 1000),
})),
);
});
afterEach(async () => {
await Conversation.deleteMany({ user });
});
/** `.limit(limit + 1)` turned a -1 page size into `.limit(0)`, which MongoDB reads as
* "no limit" — the query returned the caller's entire collection in one response. */
it.each([
['negative', -1],
['zero', 0],
['oversized', 999999999],
])('bounds a %s page size', async (_label, limit) => {
const result = await getConvosByCursor(user, { limit });
expect(result.conversations.length).toBeLessThanOrEqual(100);
expect(result.conversations.length).toBeGreaterThan(0);
expect(result.nextCursor).not.toBeNull();
});
it('caps an oversized page size at the ceiling and still pages the remainder', async () => {
const first = await getConvosByCursor(user, { limit: Number.MAX_SAFE_INTEGER });
expect(first.conversations).toHaveLength(100);
expect(first.nextCursor).not.toBeNull();
const second = await getConvosByCursor(user, {
limit: Number.MAX_SAFE_INTEGER,
cursor: first.nextCursor,
});
expect(second.conversations).toHaveLength(TOTAL - 100);
expect(second.nextCursor).toBeNull();
const ids = new Set(
[...first.conversations, ...second.conversations].map((convo) => convo.conversationId),
);
expect(ids.size).toBe(TOTAL);
});
it('serves a page size inside the range unchanged', async () => {
const result = await getConvosByCursor(user, { limit: 10 });
expect(result.conversations).toHaveLength(10);
expect(result.nextCursor).not.toBeNull();
});
});
describe('subagent thread leases', () => {
it('reserves child lineage once without overwriting a concurrent winner', async () => {
await Conversation.init();
const conversationId = uuidv4();
const lineage = {
rootConversationId: 'root',
parentConversationId: 'parent',
parentMessageId: 'parent-message',
parentToolCallId: 'parent-tool',
parentAgentId: 'parent-agent',
subagentType: 'researcher',
subagentKind: 'agent' as const,
depth: 1,
};
const reservations = await Promise.all(
['First title', 'Second title'].map((title) =>
methods.reserveSubagentThread({
user: 'reservation-user',
conversationId,
conversation: { endpoint: EModelEndpoint.agents, title, subagentThread: lineage },
}),
),
);
expect(reservations.filter((reservation) => reservation.created)).toHaveLength(1);
const saved = await methods.getConvo('reservation-user', conversationId);
expect(saved?.title).toBe(
reservations.find((reservation) => reservation.created)?.conversation.title,
);
expect(saved?.subagentThread).toEqual(lineage);
});
it('reads a child only through its exact parent and tenant with the private lease', async () => {
const parentConversationId = uuidv4();
const conversationId = uuidv4();
await Conversation.create([
{
conversationId: parentConversationId,
user: 'view-user',
tenantId: 'tenant-a',
endpoint: EModelEndpoint.agents,
},
{
conversationId,
user: 'view-user',
tenantId: 'tenant-a',
endpoint: EModelEndpoint.agents,
subagentThread: {
rootConversationId: parentConversationId,
parentConversationId,
parentMessageId: 'parent-message',
parentToolCallId: 'parent-tool',
subagentType: 'researcher',
subagentKind: 'agent',
depth: 1,
},
subagentThreadLease: {
token: 'private-token',
taskId: 'task-1',
expiresAt: new Date('2099-08-21T12:00:00.000Z'),
},
},
]);
await expect(
methods.getSubagentThreadForParent({
user: 'view-user',
parentConversationId,
conversationId,
tenantId: 'tenant-a',
}),
).resolves.toEqual(
expect.objectContaining({
conversationId,
subagentThreadLease: expect.objectContaining({ taskId: 'task-1' }),
}),
);
await expect(
methods.getSubagentThreadForParent({
user: 'view-user',
parentConversationId: 'another-parent',
conversationId,
tenantId: 'tenant-a',
}),
).resolves.toBeNull();
await expect(
methods.getSubagentThreadForParent({
user: 'view-user',
parentConversationId,
conversationId,
tenantId: 'tenant-b',
}),
).resolves.toBeNull();
expect(await methods.getConvo('view-user', conversationId)).not.toHaveProperty(
'subagentThreadLease',
);
});
it('lists bounded child metadata while collapsing private event bindings to actor identity', async () => {
const parentConversationId = uuidv4();
const eventThreadId = uuidv4();
const toolThreadId = uuidv4();
const lineage = (parentToolCallId: string) => ({
rootConversationId: parentConversationId,
parentConversationId,
parentMessageId: 'parent-message',
parentToolCallId,
subagentType: 'researcher',
subagentKind: 'agent' as const,
depth: 1,
});
await Conversation.create([
{
conversationId: eventThreadId,
user: 'index-user',
tenantId: 'tenant-a',
endpoint: EModelEndpoint.agents,
agent_id: 'agent-event',
subagentThread: lineage('event-binding:private'),
subagentThreadLease: {
token: 'private-token',
taskId: 'task-live',
expiresAt: new Date('2099-08-21T12:00:00.000Z'),
},
agentEventBinding: {
bindingId: `evtbind_${'b'.repeat(48)}`,
sourceKeyId: 'private-key',
actorId: 'actor-a',
},
},
{
conversationId: toolThreadId,
user: 'index-user',
tenantId: 'tenant-a',
endpoint: EModelEndpoint.agents,
subagentThread: lineage('tool-call-a'),
},
{
conversationId: uuidv4(),
user: 'index-user',
tenantId: 'tenant-b',
endpoint: EModelEndpoint.agents,
subagentThread: lineage('wrong-tenant'),
},
{
conversationId: uuidv4(),
user: 'different-user',
tenantId: 'tenant-a',
endpoint: EModelEndpoint.agents,
subagentThread: lineage('wrong-user'),
},
{
conversationId: uuidv4(),
user: 'index-user',
tenantId: 'tenant-a',
endpoint: EModelEndpoint.agents,
subagentThread: {
...lineage('wrong-parent'),
parentConversationId: uuidv4(),
},
},
]);
const records = await methods.listSubagentThreadsForParent({
user: 'index-user',
tenantId: 'tenant-a',
parentConversationId,
limit: 10,
});
expect(records.map((record) => record.conversationId).sort()).toEqual(
[eventThreadId, toolThreadId].sort(),
);
expect(records.find((record) => record.conversationId === eventThreadId)).toEqual(
expect.objectContaining({
actorId: 'actor-a',
subagentThreadLease: expect.objectContaining({ taskId: 'task-live' }),
}),
);
expect(records).not.toEqual(
expect.arrayContaining([expect.objectContaining({ agentEventBinding: expect.anything() })]),
);
expect(JSON.stringify(records)).not.toContain('private-key');
expect(JSON.stringify(records)).not.toContain(`evtbind_${'b'.repeat(48)}`);
});
it('hides retention-expired children before TTL cleanup', async () => {
const parentConversationId = uuidv4();
const expiredThreadId = uuidv4();
await Conversation.create({
conversationId: expiredThreadId,
user: 'expired-child-user',
endpoint: EModelEndpoint.agents,
expiredAt: new Date(Date.now() - 60_000),
subagentThread: {
rootConversationId: parentConversationId,
parentConversationId,
parentMessageId: 'parent-message',
parentToolCallId: 'parent-tool',
subagentType: 'researcher',
subagentKind: 'agent',
depth: 1,
},
});
await expect(
methods.getSubagentThreadForParent({
user: 'expired-child-user',
parentConversationId,
conversationId: expiredThreadId,
}),
).resolves.toBeNull();
await expect(
methods.listSubagentThreadsForParent({
user: 'expired-child-user',
parentConversationId,
limit: 10,
}),
).resolves.toEqual([]);
});
it('keeps an older child with a live lease inside the bounded parent index', async () => {
const parentConversationId = uuidv4();
const activeThreadId = uuidv4();
const recentThreadId = uuidv4();
const lineage = (parentToolCallId: string) => ({
rootConversationId: parentConversationId,
parentConversationId,
parentMessageId: 'parent-message',
parentToolCallId,
subagentType: 'researcher',
subagentKind: 'agent' as const,
depth: 1,
});
await Conversation.create([
{
conversationId: activeThreadId,
user: 'active-index-user',
endpoint: EModelEndpoint.agents,
subagentThread: lineage('active-tool'),
},
{
conversationId: recentThreadId,
user: 'active-index-user',
endpoint: EModelEndpoint.agents,
subagentThread: lineage('recent-tool'),
},
]);
await Conversation.updateOne(
{ conversationId: activeThreadId },
{ $set: { updatedAt: new Date('2026-08-20T10:00:00.000Z') } },
{ timestamps: false },
);
await Conversation.updateOne(
{ conversationId: recentThreadId },
{ $set: { updatedAt: new Date('2026-08-21T10:00:00.000Z') } },
{ timestamps: false },
);
await methods.acquireSubagentThreadLease({
user: 'active-index-user',
conversationId: activeThreadId,
token: 'private-token',
taskId: 'active-task',
now: new Date('2026-08-22T10:00:00.000Z'),
expiresAt: new Date('2026-08-22T10:00:30.000Z'),
});
const records = await methods.listSubagentThreadsForParent({
user: 'active-index-user',
parentConversationId,
limit: 1,
});
expect(records).toEqual([
expect.objectContaining({
conversationId: activeThreadId,
subagentThreadLease: expect.objectContaining({ taskId: 'active-task' }),
}),
]);
});
it('resolves an event binding only through its owner, tenant, and API key', async () => {
const conversationId = uuidv4();
const bindingId = `evtbind_${'a'.repeat(48)}`;
await Conversation.create({
conversationId,
user: 'binding-user',
tenantId: 'tenant-a',
endpoint: EModelEndpoint.agents,
agent_id: 'agent-player',
agentEventBinding: { bindingId, sourceKeyId: 'key-a', actorId: 'player-a' },
subagentThread: {
rootConversationId: 'parent',
parentConversationId: 'parent',
parentMessageId: 'parent-message',
parentToolCallId: 'event-binding',
parentAgentId: 'agent-director',
subagentType: 'agent-player',
subagentKind: 'agent',
depth: 1,
},
});
await expect(
methods.getAgentEventBinding({
user: 'binding-user',
tenantId: 'tenant-a',
bindingId,
sourceKeyId: 'key-a',
}),
).resolves.toMatchObject({
conversationId,
agentId: 'agent-player',
binding: { bindingId, sourceKeyId: 'key-a', actorId: 'player-a' },
});
await expect(
methods.getAgentEventBinding({
user: 'binding-user',
tenantId: 'tenant-a',
bindingId,
sourceKeyId: 'key-b',
}),
).resolves.toBeNull();
await expect(
methods.getAgentEventBinding({
user: 'binding-user',
tenantId: 'tenant-b',
bindingId,
sourceKeyId: 'key-a',
}),
).resolves.toBeNull();
await Conversation.updateOne({ conversationId }, { expiredAt: new Date(0) });
await expect(
methods.getAgentEventBinding({
user: 'binding-user',
tenantId: 'tenant-a',
bindingId,
sourceKeyId: 'key-a',
}),
).resolves.toBeNull();
expect(await methods.getConvo('binding-user', conversationId)).not.toHaveProperty(
'agentEventBinding',
);
});
it.each(['owned', 'legacy'])(
'serializes %s suspension ownership through claim, re-pause, and resumed commit',
async (storage) => {
const conversationId = uuidv4();
const owner = {
user: 'suspended-actor-user',
tenantId: 'tenant-a',
conversationId,
};
await Conversation.create({
conversationId,
user: owner.user,
tenantId: owner.tenantId,
endpoint: EModelEndpoint.agents,
agent_id: 'agent-player',
agentEventBinding: {
bindingId: `evtbind_${'s'.repeat(48)}`,
sourceKeyId: 'key-a',
actorId: 'player-a',
},
subagentThread: {
rootConversationId: 'parent',
parentConversationId: 'parent',
parentMessageId: 'parent-message',
parentToolCallId: 'event-binding',
parentAgentId: 'agent-director',
subagentType: 'agent-player',
subagentKind: 'agent',
depth: 1,
},
});
const checkpoint = (suffix: string) => ({
threadId: conversationId,
checkpointId: `checkpoint-${suffix}`,
checkpointNs: `event-actor/${suffix}`,
});
const suspension = (
suffix: string,
attempt: number,
): IAgentEventActorSuspensionEvidence => ({
version: 1,
suspensionId: `suspension-${suffix}`,
attempt,
issuedAt: 1_000 + attempt,
expiresAt: 100_000 + attempt,
invocation: {
actorThreadId: conversationId,
invocationId: 'event-pause',
depth: 1,
continuation: 'cold',
base: { actorThreadId: conversationId, generation: 0 },
fork: { ...checkpoint('fork'), invocationId: 'event-pause' },
},
checkpoint: {
...checkpoint('fork'),
checkpointId: `checkpoint-${suffix}`,
invocationId: 'event-pause',
},
interrupt: {
id: `interrupt-${suffix}`,
payload: { type: 'ask_user_question', actionId: `action-${suffix}` },
},
suspensionDigest: `digest-${suffix}`,
});
await expect(
methods.recordAgentEventActorReconciliation({
...owner,
reconciliation: {
invocationId: 'event-pause',
actionAdmitted: true,
status: 'invocation_pending',
checkpoint: checkpoint('fork'),
action: { toolName: 'submit_move' },
observedAt: new Date(),
},
}),
).resolves.toBe(true);
const first = suspension('first', 0);
await expect(
methods.storeAgentEventActorSuspension({
...owner,
suspension: {
...first,
interrupt: {
...first.interrupt,
payload: { type: 'ask_user_question', question: 'x'.repeat(65 * 1_024) },
},
},
actionId: 'action-oversized',
jobCreatedAt: 123,
}),
).rejects.toThrow('Event actor suspension exceeds maximum payload size');
await expect(
methods.storeAgentEventActorSuspension({
...owner,
suspension: first,
actionId: 'action-first',
jobCreatedAt: 123,
}),
).resolves.toEqual({ status: 'stored' });
await expect(methods.getAgentEventActorSnapshot(owner)).resolves.toMatchObject({
suspension: { kind: 'human_decision' },
});
await expect(
methods.storeAgentEventActorSuspension({
...owner,
suspension: { ...first, suspensionId: 'competing-suspension' },
actionId: 'action-first',
jobCreatedAt: 123,
}),
).resolves.toEqual({ status: 'stale' });
expect(
(await Conversation.collection.findOne({ conversationId }))?.agentEventActorSuspension
.status,
).toBe('pending_owned');
const oldClaim = await Conversation.collection.updateOne(
{ conversationId, user: owner.user, 'agentEventActorSuspension.status': 'pending' },
{ $set: { 'agentEventActorSuspension.status': 'claimed' } },
);
expect(oldClaim.matchedCount).toBe(0);
if (storage === 'legacy') {
await Conversation.collection.updateOne(
{ conversationId },
{ $set: { 'agentEventActorSuspension.status': 'pending' } },
);
}
const claim = {
...owner,
suspensionId: first.suspensionId,
attempt: first.attempt,
actionId: 'action-first',
jobCreatedAt: 123,
resumeAttemptId: 'resume-one',
};
const claims = await Promise.all([
methods.claimAgentEventActorSuspension(claim),
methods.claimAgentEventActorSuspension({ ...claim, resumeAttemptId: 'resume-two' }),
]);
expect(claims).toEqual(
expect.arrayContaining([{ status: 'claimed' }, { status: 'stale' }]),
);
const winningResumeAttemptId = claims[0].status === 'claimed' ? 'resume-one' : 'resume-two';
expect(
(await Conversation.collection.findOne({ conversationId }))?.agentEventActorSuspension
.status,
).toBe('claimed_owned');
expect(
(
await Conversation.collection.updateOne(
{ conversationId, user: owner.user, 'agentEventActorSuspension.status': 'claimed' },
{ $set: { 'agentEventActorSuspension.status': 'closed' } },
)
).matchedCount,
).toBe(0);
const second = suspension('second', 1);
await expect(
methods.storeAgentEventActorSuspension({
...owner,
suspension: second,
kind: 'internal_completion',
actionId: 'action-second',
jobCreatedAt: 123,
previous: {
suspensionId: first.suspensionId,
attempt: first.attempt,
resumeAttemptId: winningResumeAttemptId,
},
}),
).resolves.toEqual({ status: 'stored' });
await expect(methods.getAgentEventActorSnapshot(owner)).resolves.toMatchObject({
suspension: {
kind: 'internal_completion',
suspension: { suspensionId: second.suspensionId },
},
});
await expect(
methods.claimAgentEventActorSuspension({
...owner,
suspensionId: second.suspensionId,
attempt: second.attempt,
actionId: 'action-second',
jobCreatedAt: 123,
resumeAttemptId: 'resume-three',
}),
).resolves.toEqual({ status: 'claimed' });
await expect(
methods.commitAgentEventActorState({
...owner,
invocationId: 'event-pause',
expectedEpoch: 0,
action: { toolName: 'submit_move' },
checkpoint: checkpoint('committed'),
settlementAuthority: {
suspensionId: second.suspensionId,
attempt: second.attempt,
resumeAttemptId: 'resume-three',
},
}),
).resolves.toMatchObject({ status: 'committed' });
await expect(methods.getAgentEventActorSnapshot(owner)).resolves.toMatchObject({
suspension: {
status: 'closed',
outcome: 'committed',
resumeAttemptId: 'resume-three',
},
state: { generation: 1, checkpoint: checkpoint('committed') },
});
await expect(
methods.recordAgentEventActorReconciliation({
...owner,
reconciliation: {
invocationId: 'event-pause',
actionAdmitted: true,
status: 'history_persisted',
checkpoint: checkpoint('committed'),
action: { toolName: 'submit_move' },
observedAt: new Date(),
},
}),
).resolves.toBe(true);
await expect(
methods.resolveAgentEventActorReconciliation({
...owner,
invocationId: 'event-pause',
checkpoint: checkpoint('committed'),
resolution: 'checkpoint_verified',
}),
).resolves.toBe(true);
const cancellationCheckpoint = checkpoint('cancel');
const cancellationSuspension: IAgentEventActorSuspensionEvidence = {
...suspension('cancel', 0),
invocation: {
...suspension('cancel', 0).invocation,
invocationId: 'event-cancel',
fork: {
...cancellationCheckpoint,
invocationId: 'event-cancel',
},
},
checkpoint: {
...cancellationCheckpoint,
invocationId: 'event-cancel',
},
};
await expect(
methods.recordAgentEventActorReconciliation({
...owner,
reconciliation: {
invocationId: 'event-cancel',
status: 'invocation_pending',
checkpoint: cancellationCheckpoint,
action: { toolName: 'submit_move' },
observedAt: new Date(),
},
}),
).resolves.toBe(true);
await expect(
methods.storeAgentEventActorSuspension({
...owner,
suspension: cancellationSuspension,
actionId: 'action-cancel',
jobCreatedAt: 124,
}),
).resolves.toEqual({ status: 'stored' });
const [resumeRace, cancelRace] = await Promise.all([
methods.claimAgentEventActorSuspension({
...owner,
suspensionId: cancellationSuspension.suspensionId,
attempt: 0,
actionId: 'action-cancel',
jobCreatedAt: 124,
resumeAttemptId: 'resume-race',
}),
methods.cancelAgentEventActorSuspension({
...owner,
suspensionId: cancellationSuspension.suspensionId,
attempt: 0,
invocationId: 'event-cancel',
checkpoint: cancellationCheckpoint,
}),
]);
const raceStatuses = [resumeRace.status, cancelRace.status];
expect(raceStatuses.filter((status) => status === 'stale')).toHaveLength(1);
expect(raceStatuses).toEqual(
expect.arrayContaining([expect.stringMatching(/^(claimed|cancelled)$/), 'stale']),
);
if (resumeRace.status === 'claimed') {
await expect(
methods.cancelAgentEventActorSuspension({
...owner,
suspensionId: cancellationSuspension.suspensionId,
attempt: 0,
invocationId: 'event-cancel',
checkpoint: cancellationCheckpoint,
claimedResumeAttemptId: 'resume-race',
}),
).resolves.toEqual({ status: 'cancelled' });
}
await expect(methods.getAgentEventActorSnapshot(owner)).resolves.toMatchObject({
suspension: { status: 'closed', outcome: 'cancelled' },
});
},
);
it('closes a resumed suspension when the actor-head commit is stale', async () => {
const conversationId = uuidv4();
const owner = { user: 'stale-resume-user', tenantId: 'tenant-a', conversationId };
const baseCheckpoint = {
threadId: conversationId,
checkpointId: 'checkpoint-base',
checkpointNs: 'event-actor/base',
};
const baseState = { generation: 1, checkpoint: baseCheckpoint };
const evidence: IAgentEventActorSuspensionEvidence = {
version: 1,
suspensionId: 'suspension-stale',
attempt: 0,
issuedAt: 1_000,
expiresAt: 100_000,
invocation: {
actorThreadId: conversationId,
invocationId: 'event-stale',
depth: 1,
continuation: 'warm',
base: { actorThreadId: conversationId, ...baseState },
fork: { ...baseCheckpoint, invocationId: 'event-stale' },
},
checkpoint: {
...baseCheckpoint,
checkpointId: 'checkpoint-paused',
invocationId: 'event-stale',
},
interrupt: { id: 'interrupt-stale', payload: { type: 'tool_approval' } },
suspensionDigest: 'digest-stale',
};
await Conversation.create({
conversationId,
user: owner.user,
tenantId: owner.tenantId,
endpoint: EModelEndpoint.agents,
agent_id: 'agent-player',
agentEventBinding: {
bindingId: `evtbind_${'t'.repeat(48)}`,
sourceKeyId: 'key-a',
actorId: 'player-a',
},
subagentThread: {
rootConversationId: 'parent',
parentConversationId: 'parent',
parentMessageId: 'parent-message',
parentToolCallId: 'event-binding',
subagentType: 'agent-player',
subagentKind: 'agent',
depth: 1,
},
agentEventActor: baseState,
agentEventActorReconciliations: [
{
invocationId: 'event-stale',
actionAdmitted: true,
status: 'invocation_pending',
checkpoint: baseCheckpoint,
action: { toolName: 'submit_move' },
observedAt: new Date(),
},
],
});
await expect(
methods.storeAgentEventActorSuspension({
...owner,
suspension: evidence,
actionId: 'action-stale',
jobCreatedAt: 456,
invalidateHead: true,
}),
).resolves.toEqual({ status: 'stored' });
await expect(methods.getAgentEventActorSnapshot(owner)).resolves.toMatchObject({
state: { ...baseState, requiresColdStart: true },
suspension: { status: 'pending' },
});
await expect(
methods.claimAgentEventActorSuspension({
...owner,
suspensionId: evidence.suspensionId,
attempt: 0,
actionId: 'action-stale',
jobCreatedAt: 456,
resumeAttemptId: 'resume-stale',
}),
).resolves.toEqual({ status: 'claimed' });
const competingState = {
generation: 2,
checkpoint: {
threadId: conversationId,
checkpointId: 'checkpoint-competing',
checkpointNs: 'event-actor/competing',
},
};
await Conversation.updateOne(
{ conversationId },
{ $set: { agentEventActor: competingState } },
);
await expect(
methods.commitAgentEventActorState({
...owner,
invocationId: 'event-stale',
expectedEpoch: 0,
expected: baseState,
action: { toolName: 'submit_move' },
checkpoint: {
threadId: conversationId,
checkpointId: 'checkpoint-resumed',
checkpointNs: 'event-actor/base',
},
settlementAuthority: {
suspensionId: evidence.suspensionId,
attempt: 0,
resumeAttemptId: 'resume-stale',
},
}),
).resolves.toEqual({ status: 'stale', state: competingState });
await expect(methods.getAgentEventActorSnapshot(owner)).resolves.toMatchObject({
state: competingState,
suspension: { status: 'closed', outcome: 'stale' },
});
});
it('commits event actor heads with full checkpoint CAS and two-checkpoint retention', async () => {
const conversationId = uuidv4();
await Conversation.create({
conversationId,
user: 'actor-head-user',
tenantId: 'tenant-a',
endpoint: EModelEndpoint.agents,
agent_id: 'agent-player',
agentEventBinding: {
bindingId: `evtbind_${'c'.repeat(48)}`,
sourceKeyId: 'key-a',
actorId: 'player-a',
},
subagentThread: {
rootConversationId: 'parent',
parentConversationId: 'parent',
parentMessageId: 'parent-message',
parentToolCallId: 'event-binding',
parentAgentId: 'agent-director',
subagentType: 'agent-player',
subagentKind: 'agent',
depth: 1,
},
});
const checkpoint = (suffix: string) => ({
threadId: conversationId,
checkpointId: `checkpoint-${suffix}`,
checkpointNs: `event-actor/${suffix}`,
});
const beginInvocation = (invocationId: string, actorCheckpoint = checkpoint(invocationId)) =>
methods.recordAgentEventActorReconciliation({
user: 'actor-head-user',
tenantId: 'tenant-a',
conversationId,
reconciliation: {
invocationId,
status: 'invocation_pending',
checkpoint: actorCheckpoint,
action: { toolName: 'submit_move' },
observedAt: new Date(),
},
});
const finishInvocation = async (
invocationId: string,
actorCheckpoint: ReturnType<typeof checkpoint>,
) => {
const historyRecorded = await methods.recordAgentEventActorReconciliation({
user: 'actor-head-user',
tenantId: 'tenant-a',
conversationId,
reconciliation: {
invocationId,
status: 'history_persisted',
checkpoint: actorCheckpoint,
action: { toolName: 'submit_move' },
observedAt: new Date(),
},
});
if (!historyRecorded) {
return false;
}
return methods.resolveAgentEventActorReconciliation({
user: 'actor-head-user',
tenantId: 'tenant-a',
conversationId,
invocationId,
checkpoint: actorCheckpoint,
resolution: 'checkpoint_verified',
});
};
await expect(beginInvocation('one')).resolves.toBe(true);
await expect(beginInvocation('one')).resolves.toBe(false);
await expect(beginInvocation('one', checkpoint('different'))).resolves.toBe(false);
await expect(beginInvocation('competing', checkpoint('one'))).resolves.toBe(false);
const first = await methods.commitAgentEventActorState({
user: 'actor-head-user',
tenantId: 'tenant-a',
conversationId,
invocationId: 'one',
expectedEpoch: 0,
action: { toolName: 'submit_move' },
checkpoint: checkpoint('one'),
});
expect(first).toEqual({
status: 'committed',
state: { generation: 1, checkpoint: checkpoint('one') },
});
await expect(
methods.getAgentEventActorSnapshot({
user: 'actor-head-user',
tenantId: 'tenant-a',
conversationId,
}),
).resolves.toMatchObject({
state: first.state,
epoch: 0,
legacyTurn: null,
suspension: null,
reconciliations: [
{
invocationId: 'one',
status: 'persistence_pending',
checkpoint: checkpoint('one'),
action: { toolName: 'submit_move' },
},
],
});
await expect(
methods.recordAgentEventActorReconciliation({
user: 'actor-head-user',
tenantId: 'tenant-a',
conversationId,
reconciliation: {
invocationId: 'one',
status: 'persistence_failed',
checkpoint: checkpoint('one'),
action: { toolName: 'submit_move' },
error: 'message write unavailable',
observedAt: new Date(),
},
}),
).resolves.toBe(true);
await expect(finishInvocation('one', checkpoint('one'))).resolves.toBe(true);
await expect(
methods.recordAgentEventActorReconciliation({
user: 'actor-head-user',
tenantId: 'tenant-a',
conversationId,
reconciliation: {
invocationId: 'one',
status: 'persistence_failed',
checkpoint: checkpoint('one'),
action: { toolName: 'submit_move' },
error: 'late stale controller',
observedAt: new Date(),
},
}),
).resolves.toBe(false);
await expect(beginInvocation('one', checkpoint('one'))).resolves.toBe(false);
const stale = await methods.commitAgentEventActorState({
user: 'actor-head-user',
tenantId: 'tenant-a',
conversationId,
invocationId: 'stale',
expectedEpoch: 0,
action: { toolName: 'submit_move' },
checkpoint: checkpoint('stale'),
});
expect(stale).toEqual({ status: 'stale', state: first.state });
await expect(beginInvocation('two', checkpoint('one'))).resolves.toBe(true);
const second = await methods.commitAgentEventActorState({
user: 'actor-head-user',
tenantId: 'tenant-a',
conversationId,
invocationId: 'two',
expectedEpoch: 0,
action: { toolName: 'submit_move' },
expected: first.state,
checkpoint: checkpoint('two'),
});
expect(second).toEqual({
status: 'committed',
state: {
generation: 2,
checkpoint: checkpoint('two'),
previousCheckpoint: checkpoint('one'),
},
});
await expect(finishInvocation('two', checkpoint('two'))).resolves.toBe(true);
await expect(beginInvocation('three', checkpoint('two'))).resolves.toBe(true);
const third = await methods.commitAgentEventActorState({
user: 'actor-head-user',
tenantId: 'tenant-a',
conversationId,
invocationId: 'three',
expectedEpoch: 0,
action: { toolName: 'submit_move' },
expected: second.state,
checkpoint: checkpoint('three'),
});
expect(third).toEqual({
status: 'committed',
state: {
generation: 3,
checkpoint: checkpoint('three'),
previousCheckpoint: checkpoint('two'),
},
prunableCheckpoint: checkpoint('one'),
});
const pendingPruning = await Conversation.findOne({ conversationId })
.select('+agentEventActorCleanup')
.lean();
expect(pendingPruning?.agentEventActorCleanup).toEqual([checkpoint('one')]);
await expect(finishInvocation('three', checkpoint('three'))).resolves.toBe(true);
await expect(
methods.getAgentEventActorSnapshot({
user: 'actor-head-user',
tenantId: 'tenant-a',
conversationId,
}),
).resolves.toMatchObject({
state: third.state,
epoch: 0,
legacyTurn: null,
reconciliations: [
{ invocationId: 'one', status: 'settled' },
{ invocationId: 'two', status: 'settled' },
{ invocationId: 'three', status: 'settled' },
],
});
await expect(
methods.beginAgentEventActorLegacyTurn({
user: 'actor-head-user',
tenantId: 'tenant-a',
conversationId,
token: 'legacy-turn-1',
}),
).resolves.toBe(true);
await expect(
methods.completeAgentEventActorLegacyTurn({
user: 'actor-head-user',
tenantId: 'tenant-a',
conversationId,
token: 'legacy-turn-1',
}),
).resolves.toBe(true);
await expect(beginInvocation('stale-warm', checkpoint('three'))).resolves.toBe(true);
await expect(
methods.commitAgentEventActorState({
user: 'actor-head-user',
tenantId: 'tenant-a',
conversationId,
invocationId: 'stale-warm',
expectedEpoch: 0,
action: { toolName: 'submit_move' },
expected: third.state,
checkpoint: checkpoint('stale-warm'),
}),
).resolves.toEqual({
status: 'stale',
state: { ...third.state!, requiresColdStart: true },
});
await expect(
methods.resolveAgentEventActorReconciliation({
user: 'actor-head-user',
tenantId: 'tenant-a',
conversationId,
invocationId: 'stale-warm',
checkpoint: checkpoint('three'),
resolution: 'invocation_abandoned',
}),
).resolves.toBe(true);
await expect(
methods.getAgentEventActorSnapshot({
user: 'actor-head-user',
tenantId: 'tenant-a',
conversationId,
}),
).resolves.toEqual({
state: { ...third.state, requiresColdStart: true },
epoch: 1,
legacyTurn: null,
suspension: null,
reconciliations: expect.arrayContaining([
expect.objectContaining({ invocationId: 'one', status: 'settled' }),
expect.objectContaining({ invocationId: 'two', status: 'settled' }),
expect.objectContaining({ invocationId: 'three', status: 'settled' }),
]),
});
await expect(beginInvocation('four', checkpoint('three'))).resolves.toBe(true);
const fourth = await methods.commitAgentEventActorState({
user: 'actor-head-user',
tenantId: 'tenant-a',
conversationId,
invocationId: 'four',
expectedEpoch: 1,
action: { toolName: 'submit_move' },
expected: { ...third.state!, requiresColdStart: true },
checkpoint: checkpoint('four'),
});
expect(fourth.status).toBe('committed');
expect(fourth.state).not.toHaveProperty('requiresColdStart');
await expect(finishInvocation('four', checkpoint('four'))).resolves.toBe(true);
const competingOwners = await Promise.all([
beginInvocation('five', checkpoint('four')),
beginInvocation('five', checkpoint('four')),
]);
expect(competingOwners.sort()).toEqual([false, true]);
await expect(
methods.resolveAgentEventActorReconciliation({
user: 'actor-head-user',
tenantId: 'tenant-a',
conversationId,
invocationId: 'five',
checkpoint: checkpoint('four'),
resolution: 'invocation_abandoned',
}),
).resolves.toBe(true);
await expect(
methods.getAgentEventActorSnapshot({
user: 'actor-head-user',
tenantId: 'tenant-a',
conversationId: 'missing-actor-thread',
}),
).resolves.toBeUndefined();
expect(await methods.getConvo('actor-head-user', conversationId)).not.toHaveProperty(
'agentEventActor',
);
});
it('persists complete warm-continuation state with the actor head', async () => {
const conversationId = uuidv4();
const fingerprint = {
algorithm: 'sha256' as const,
version: 1,
digest: 'context-one',
};
const actorCheckpoint = {
threadId: conversationId,
checkpointId: 'checkpoint-context',
checkpointNs: 'event-actor/context',
};
const skillManifest = [{ id: 'skill-1', name: 'analysis', version: 3 }];
const discoveredToolNames = ['deferred_lookup', 'deferred_write'];
const summary = { text: 'Earlier compacted context.', tokenCount: 12 };
const contextMeta = { calibrationRatio: 1.25, encoding: 'o200k_base' };
const compactionSemanticIndex = {
version: 1 as const,
providedEntryCount: 9,
entries: [
{
type: 'activity_phase' as const,
sourceMessageId: 'assistant-history',
sourceContentIndex: 1,
revision: 1,
status: 'committed' as const,
text: 'Verified the release state',
},
],
};
await Conversation.create({
conversationId,
user: 'actor-context-user',
endpoint: EModelEndpoint.agents,
agent_id: 'agent-player',
agentEventBinding: {
bindingId: `evtbind_${'f'.repeat(48)}`,
sourceKeyId: 'key-a',
actorId: 'player-a',
},
subagentThread: {
rootConversationId: 'parent',
parentConversationId: 'parent',
parentMessageId: 'parent-message',
parentToolCallId: 'event-binding',
parentAgentId: 'agent-director',
subagentType: 'agent-player',
subagentKind: 'agent',
depth: 1,
},
});
await methods.recordAgentEventActorReconciliation({
user: 'actor-context-user',
conversationId,
reconciliation: {
invocationId: 'context-one',
status: 'invocation_pending',
checkpoint: actorCheckpoint,
action: { toolName: 'submit_move' },
observedAt: new Date(),
},
});
const committed = await methods.commitAgentEventActorState({
user: 'actor-context-user',
conversationId,
invocationId: 'context-one',
expectedEpoch: 0,
action: { toolName: 'submit_move' },
checkpoint: actorCheckpoint,
contextFingerprint: fingerprint,
skillManifest,
discoveredToolNames,
summary,
contextMeta,
compactionSemanticIndex,
});
expect(committed).toMatchObject({
status: 'committed',
state: {
generation: 1,
checkpoint: actorCheckpoint,
contextFingerprint: fingerprint,
skillManifest,
discoveredToolNames,
summary,
contextMeta,
compactionSemanticIndex,
},
});
await expect(
methods.getAgentEventActorSnapshot({ user: 'actor-context-user', conversationId }),
).resolves.toMatchObject({
state: {
contextFingerprint: fingerprint,
skillManifest,
discoveredToolNames,
summary,
contextMeta,
compactionSemanticIndex,
},
});
await expect(
methods.commitAgentEventActorState({
user: 'actor-context-user',
conversationId,
invocationId: 'too-many-skills',
expectedEpoch: 0,
action: { toolName: 'submit_move' },
checkpoint: actorCheckpoint,
skillManifest: Array.from({ length: 65 }, (_, index) => ({
id: `skill-${index}`,
name: `skill-${index}`,
version: 1,
})),
}),
).rejects.toThrow('Event actor Skill manifest exceeds 64');
await expect(
methods.commitAgentEventActorState({
user: 'actor-context-user',
conversationId,
invocationId: 'too-many-tools',
expectedEpoch: 0,
action: { toolName: 'submit_move' },
checkpoint: actorCheckpoint,
discoveredToolNames: Array.from({ length: 129 }, (_, index) => `tool-${index}`),
}),
).rejects.toThrow('Event actor discovered-tool state is invalid');
await expect(
methods.commitAgentEventActorState({
user: 'actor-context-user',
conversationId,
invocationId: 'invalid-summary',
expectedEpoch: 0,
action: { toolName: 'submit_move' },
checkpoint: actorCheckpoint,
summary: { text: '', tokenCount: 1 },
}),
).rejects.toThrow('Event actor summary state is invalid');
await expect(
methods.commitAgentEventActorState({
user: 'actor-context-user',
conversationId,
invocationId: 'invalid-calibration',
expectedEpoch: 0,
action: { toolName: 'submit_move' },
checkpoint: actorCheckpoint,
contextMeta: { calibrationRatio: 9, encoding: 'o200k_base' },
}),
).rejects.toThrow('Event actor context calibration is invalid');
await expect(
methods.commitAgentEventActorState({
user: 'actor-context-user',
conversationId,
invocationId: 'invalid-fading',
expectedEpoch: 0,
action: { toolName: 'submit_move' },
checkpoint: actorCheckpoint,
contextMeta: {
calibrationRatio: 1.25,
fading: { v: 1, budgetTokens: -5, masked: true },
},
}),
).rejects.toThrow('Event actor context fading tier is invalid');
await expect(
methods.commitAgentEventActorState({
user: 'actor-context-user',
conversationId,
invocationId: 'invalid-fading-tiers',
expectedEpoch: 0,
action: { toolName: 'submit_move' },
checkpoint: actorCheckpoint,
contextMeta: {
calibrationRatio: 1.25,
fadingTiers: [
{ agentId: 'agent-a', v: 1, budgetTokens: 20_000, masked: true },
{ agentId: 'agent-a', v: 1, budgetTokens: 10_000, masked: true },
],
},
}),
).rejects.toThrow('Event actor context fading tiers are invalid');
await expect(
methods.commitAgentEventActorState({
user: 'actor-context-user',
conversationId,
invocationId: 'invalid-compaction-index',
expectedEpoch: 0,
action: { toolName: 'submit_move' },
checkpoint: actorCheckpoint,
compactionSemanticIndex: {
version: 1,
entries: [{ ...compactionSemanticIndex.entries[0], sourceContentIndex: -1 }],
},
}),
).rejects.toThrow('Event actor compaction semantic index is invalid');
await expect(
methods.commitAgentEventActorState({
user: 'actor-context-user',
conversationId,
invocationId: 'invalid-compaction-count',
expectedEpoch: 0,
action: { toolName: 'submit_move' },
checkpoint: actorCheckpoint,
compactionSemanticIndex: {
version: 1,
entries: compactionSemanticIndex.entries,
providedEntryCount: 0,
},
}),
).rejects.toThrow('Event actor compaction semantic index is invalid');
});
it('retains exact legacy settled receipts until delivery-ledger migration', async () => {
const conversationId = uuidv4();
await Conversation.create({
conversationId,
user: 'actor-reconcile-user',
endpoint: EModelEndpoint.agents,
agent_id: 'agent-player',
agentEventBinding: {
bindingId: `evtbind_${'d'.repeat(48)}`,
sourceKeyId: 'key-a',
actorId: 'player-a',
},
subagentThread: {
rootConversationId: 'parent',
parentConversationId: 'parent',
parentMessageId: 'parent-message',
parentToolCallId: 'event-binding',
parentAgentId: 'agent-director',
subagentType: 'agent-player',
subagentKind: 'agent',
depth: 1,
},
});
const checkpoint = {
threadId: conversationId,
checkpointId: 'checkpoint-one',
checkpointNs: 'event-actor/one',
};
await methods.recordAgentEventActorReconciliation({
user: 'actor-reconcile-user',
conversationId,
reconciliation: {
invocationId: 'event-one',
status: 'invocation_pending',
checkpoint,
action: { toolName: 'submit_move' },
observedAt: new Date(),
},
});
const first = await methods.commitAgentEventActorState({
user: 'actor-reconcile-user',
conversationId,
invocationId: 'event-one',
expectedEpoch: 0,
action: { toolName: 'submit_move' },
checkpoint,
});
expect(first.status).toBe('committed');
await methods.recordAgentEventActorReconciliation({
user: 'actor-reconcile-user',
conversationId,
reconciliation: {
invocationId: 'event-one',
status: 'history_persisted',
checkpoint,
action: { toolName: 'submit_move' },
observedAt: new Date(),
},
});
await methods.resolveAgentEventActorReconciliation({
user: 'actor-reconcile-user',
conversationId,
invocationId: 'event-one',
checkpoint,
resolution: 'checkpoint_verified',
});
const observedAt = new Date('2026-08-25T00:00:00.000Z');
const reconciliation = {
invocationId: 'event-conflict',
status: 'commit_conflict' as const,
checkpoint: {
threadId: conversationId,
checkpointId: 'checkpoint-conflict',
checkpointNs: 'event-actor/conflict',
},
action: { toolName: 'submit_move', toolCallId: 'call-1' },
error: 'A competing checkpoint advanced the actor head',
observedAt,
};
const beginReconciliation = (next: IAgentEventActorReconciliation) =>
methods.recordAgentEventActorReconciliation({
user: 'actor-reconcile-user',
conversationId,
reconciliation: { ...next, status: 'invocation_pending' },
});
await expect(beginReconciliation(reconciliation)).resolves.toBe(true);
await expect(
methods.recordAgentEventActorReconciliation({
user: 'actor-reconcile-user',
conversationId,
reconciliation,
}),
).resolves.toBe(true);
await expect(
methods.getAgentEventActorSnapshot({
user: 'actor-reconcile-user',
conversationId,
}),
).resolves.toEqual({
state: first.state,
epoch: 0,
legacyTurn: null,
suspension: null,
reconciliations: [
expect.objectContaining({ invocationId: 'event-one', status: 'settled' }),
reconciliation,
],
});
await expect(
methods.commitAgentEventActorState({
user: 'actor-reconcile-user',
conversationId,
invocationId: 'event-blocked',
expectedEpoch: 0,
action: { toolName: 'submit_move' },
expected: first.state,
checkpoint: { ...checkpoint, checkpointId: 'checkpoint-two' },
}),
).resolves.toEqual({ status: 'stale', state: first.state });
await expect(
methods.resolveAgentEventActorReconciliation({
user: 'actor-reconcile-user',
conversationId,
invocationId: reconciliation.invocationId,
checkpoint: {
threadId: conversationId,
checkpointId: 'checkpoint-conflict',
checkpointNs: 'event-actor/conflict',
},
resolution: 'checkpoint_verified',
}),
).resolves.toBe(false);
await expect(
methods.resolveAgentEventActorReconciliation({
user: 'actor-reconcile-user',
conversationId,
invocationId: reconciliation.invocationId,
checkpoint: {
threadId: conversationId,
checkpointId: 'checkpoint-conflict',
checkpointNs: 'event-actor/conflict',
},
resolution: 'action_compensated',
}),
).resolves.toBe(true);
const checkpointless = {
...reconciliation,
invocationId: 'event-checkpointless',
checkpoint: {
threadId: conversationId,
checkpointNs: 'event-actor/checkpointless',
},
};
await expect(beginReconciliation(checkpointless)).resolves.toBe(true);
await expect(
methods.recordAgentEventActorReconciliation({
user: 'actor-reconcile-user',
conversationId,
reconciliation: checkpointless,
}),
).resolves.toBe(true);
await expect(
methods.resolveAgentEventActorReconciliation({
user: 'actor-reconcile-user',
conversationId,
invocationId: checkpointless.invocationId,
checkpoint: checkpointless.checkpoint,
resolution: 'action_compensated',
}),
).resolves.toBe(true);
const verified = {
...reconciliation,
invocationId: 'event-verified',
status: 'history_persisted' as const,
checkpoint,
};
await expect(beginReconciliation(verified)).resolves.toBe(true);
await expect(
methods.recordAgentEventActorReconciliation({
user: 'actor-reconcile-user',
conversationId,
reconciliation: verified,
}),
).resolves.toBe(true);
await expect(
methods.resolveAgentEventActorReconciliation({
user: 'actor-reconcile-user',
conversationId,
invocationId: verified.invocationId,
checkpoint,
resolution: 'checkpoint_verified',
}),
).resolves.toBe(true);
/** A crashed settle retries verification and replays its own receipt. */
await expect(
methods.resolveAgentEventActorReconciliation({
user: 'actor-reconcile-user',
conversationId,
invocationId: verified.invocationId,
checkpoint,
resolution: 'checkpoint_verified',
}),
).resolves.toBe(true);
const later = { ...reconciliation, invocationId: 'event-later' };
await expect(beginReconciliation(later)).resolves.toBe(true);
await expect(
methods.recordAgentEventActorReconciliation({
user: 'actor-reconcile-user',
conversationId,
reconciliation: later,
}),
).resolves.toBe(true);
await expect(
methods.getAgentEventActorSnapshot({
user: 'actor-reconcile-user',
conversationId,
}),
).resolves.toEqual({
state: { ...first.state!, requiresColdStart: true },
epoch: 0,
legacyTurn: null,
suspension: null,
reconciliations: [
expect.objectContaining({
invocationId: 'event-one',
status: 'settled',
resolution: 'checkpoint_verified',
}),
expect.objectContaining({
invocationId: 'event-conflict',
status: 'settled',
resolution: 'action_compensated',
}),
expect.objectContaining({
invocationId: 'event-checkpointless',
status: 'settled',
resolution: 'action_compensated',
}),
expect.objectContaining({
invocationId: 'event-verified',
status: 'settled',
resolution: 'checkpoint_verified',
}),
later,
],
});
await expect(
methods.resolveAgentEventActorReconciliation({
user: 'actor-reconcile-user',
conversationId,
invocationId: 'event-later',
checkpoint: reconciliation.checkpoint,
resolution: 'history_repaired',
}),
).resolves.toBe(true);
/** A repaired or compensated invocation keeps its receipt: it already
* applied an external action, so a delayed duplicate owner must never
* reacquire the same id. */
await expect(
methods.getAgentEventActorSnapshot({
user: 'actor-reconcile-user',
conversationId,
}),
).resolves.toEqual({
state: { ...first.state!, requiresColdStart: true },
epoch: 0,
legacyTurn: null,
suspension: null,
reconciliations: [
expect.objectContaining({ invocationId: 'event-one', status: 'settled' }),
expect.objectContaining({ invocationId: 'event-conflict', status: 'settled' }),
expect.objectContaining({ invocationId: 'event-checkpointless', status: 'settled' }),
expect.objectContaining({ invocationId: 'event-verified', status: 'settled' }),
expect.objectContaining({
invocationId: 'event-later',
status: 'settled',
resolution: 'history_repaired',
}),
],
});
await expect(beginReconciliation(later)).resolves.toBe(false);
await expect(
beginReconciliation({ ...reconciliation, invocationId: 'event-checkpointless' }),
).resolves.toBe(false);
/** Retrying a repair converges on its own retained receipt. */
await expect(
methods.resolveAgentEventActorReconciliation({
user: 'actor-reconcile-user',
conversationId,
invocationId: 'event-later',
checkpoint: reconciliation.checkpoint,
resolution: 'history_repaired',
}),
).resolves.toBe(true);
/** A different id stays admissible after those settled receipts. */
await expect(
beginReconciliation({ ...reconciliation, invocationId: 'event-fresh' }),
).resolves.toBe(true);
await expect(
methods.resolveAgentEventActorReconciliation({
user: 'actor-reconcile-user',
conversationId,
invocationId: 'event-fresh',
checkpoint: reconciliation.checkpoint,
resolution: 'invocation_abandoned',
}),
).resolves.toBe(true);
const visible = await methods.getConvo('actor-reconcile-user', conversationId);
expect(visible).not.toHaveProperty('agentEventActor');
expect(visible).not.toHaveProperty('agentEventActorReconciliations');
});
it('confirms action admission only on the exact pending lifecycle', async () => {
const conversationId = uuidv4();
await Conversation.create({
conversationId,
user: 'actor-admission-user',
endpoint: EModelEndpoint.agents,
agentEventBinding: {
bindingId: `evtbind_${'a'.repeat(48)}`,
sourceKeyId: 'key-a',
actorId: 'player-a',
},
subagentThread: {
rootConversationId: 'parent',
parentConversationId: 'parent',
parentMessageId: 'parent-message',
parentToolCallId: 'event-binding',
parentAgentId: 'agent-director',
subagentType: 'agent-player',
subagentKind: 'agent',
depth: 1,
},
});
const pending = {
invocationId: 'event-admission',
status: 'invocation_pending' as const,
checkpoint: {
threadId: conversationId,
checkpointNs: 'event-actor/admission',
},
action: { toolName: 'submit_move' },
observedAt: new Date(),
};
await expect(
methods.recordAgentEventActorReconciliation({
user: 'actor-admission-user',
conversationId,
reconciliation: pending,
}),
).resolves.toBe(true);
await expect(
methods.recordAgentEventActorReconciliation({
user: 'actor-admission-user',
conversationId,
reconciliation: { ...pending, actionAdmitted: true },
}),
).resolves.toBe(true);
await expect(
methods.recordAgentEventActorReconciliation({
user: 'actor-admission-user',
conversationId,
reconciliation: { ...pending, actionAdmitted: true },
}),
).resolves.toBe(false);
await expect(
methods.getAgentEventActorSnapshot({
user: 'actor-admission-user',
conversationId,
}),
).resolves.toMatchObject({
reconciliations: [
expect.objectContaining({
invocationId: 'event-admission',
status: 'invocation_pending',
actionAdmitted: true,
}),
],
});
await expect(
methods.resolveAgentEventActorReconciliation({
user: 'actor-admission-user',
conversationId,
invocationId: pending.invocationId,
checkpoint: pending.checkpoint,
expectedActionAdmitted: false,
resolution: 'invocation_abandoned',
}),
).resolves.toBe(false);
await expect(
methods.resolveAgentEventActorReconciliation({
user: 'actor-admission-user',
conversationId,
invocationId: pending.invocationId,
checkpoint: pending.checkpoint,
expectedActionAdmitted: true,
resolution: 'invocation_abandoned',
}),
).resolves.toBe(true);
});
it('does not confirm a stale marker after a checkpoint-distinct successor wins', async () => {
const conversationId = uuidv4();
const invocationId = 'event-stale-confirmation';
const original = {
invocationId,
status: 'invocation_pending' as const,
checkpoint: {
threadId: conversationId,
checkpointId: 'checkpoint-original',
checkpointNs: 'event-actor/original',
},
action: { toolName: 'submit_move', toolCallId: 'call-original' },
observedAt: new Date(),
};
const successor = {
...original,
checkpoint: {
threadId: conversationId,
checkpointId: 'checkpoint-successor',
checkpointNs: 'event-actor/successor',
},
action: { toolName: 'submit_move', toolCallId: 'call-successor' },
};
await Conversation.create({
conversationId,
user: 'actor-stale-confirmation-user',
endpoint: EModelEndpoint.agents,
agentEventBinding: {
bindingId: `evtbind_${'b'.repeat(48)}`,
sourceKeyId: 'key-a',
actorId: 'player-a',
},
subagentThread: {
rootConversationId: 'parent',
parentConversationId: 'parent',
parentMessageId: 'parent-message',
parentToolCallId: 'event-binding',
parentAgentId: 'agent-director',
subagentType: 'agent-player',
subagentKind: 'agent',
depth: 1,
},
agentEventActorReconciliations: [successor],
});
const staleRead = jest.spyOn(Conversation, 'findOne').mockImplementationOnce(
() =>
({
select: () => ({
lean: () => Promise.resolve({ agentEventActorReconciliations: [original] }),
}),
}) as never,
);
await expect(
methods.recordAgentEventActorReconciliation({
user: 'actor-stale-confirmation-user',
conversationId,
reconciliation: { ...original, actionAdmitted: true },
}),
).resolves.toBe(false);
staleRead.mockRestore();
await expect(
methods.getAgentEventActorSnapshot({
user: 'actor-stale-confirmation-user',
conversationId,
}),
).resolves.toMatchObject({
reconciliations: [
expect.objectContaining({
checkpoint: expect.objectContaining({ checkpointId: 'checkpoint-successor' }),
action: expect.objectContaining({ toolCallId: 'call-successor' }),
}),
],
});
});
it('clears an exact reconciled invocation without retaining a conversation receipt', async () => {
const conversationId = uuidv4();
const observedAt = new Date('2026-08-26T12:00:00.000Z');
const checkpoint = {
threadId: conversationId,
checkpointId: 'checkpoint-one',
checkpointNs: 'event-actor/event-one',
};
await Conversation.create({
conversationId,
user: 'actor-receipt-user',
endpoint: EModelEndpoint.agents,
agent_id: 'agent-player',
agentEventBinding: {
bindingId: `evtbind_${'f'.repeat(48)}`,
sourceKeyId: 'key-a',
actorId: 'player-a',
},
subagentThread: {
rootConversationId: 'parent',
parentConversationId: 'parent',
parentMessageId: 'parent-message',
parentToolCallId: 'event-binding',
parentAgentId: 'agent-director',
subagentType: 'agent-player',
subagentKind: 'agent',
depth: 1,
},
});
await methods.recordAgentEventActorReconciliation({
user: 'actor-receipt-user',
conversationId,
reconciliation: {
invocationId: 'event-one',
status: 'invocation_pending',
checkpoint,
action: { toolName: 'submit_move' },
observedAt,
},
});
await methods.commitAgentEventActorState({
user: 'actor-receipt-user',
conversationId,
invocationId: 'event-one',
expectedEpoch: 0,
action: { toolName: 'submit_move' },
checkpoint,
});
await methods.recordAgentEventActorReconciliation({
user: 'actor-receipt-user',
conversationId,
reconciliation: {
invocationId: 'event-one',
status: 'history_persisted',
checkpoint,
action: { toolName: 'submit_move' },
observedAt,
},
});
await expect(
methods.getAgentEventActorReconciliationStorageMetrics(
new Date(observedAt.getTime() + 12_000),
),
).resolves.toEqual({ pending: 1, oldestPendingAgeSeconds: 12 });
await expect(
methods.clearAgentEventActorReconciliation({
user: 'actor-receipt-user',
conversationId,
invocationId: 'event-one',
checkpoint,
resolution: 'checkpoint_verified',
}),
).resolves.toBe(true);
await expect(
methods.getAgentEventActorSnapshot({ user: 'actor-receipt-user', conversationId }),
).resolves.toMatchObject({ reconciliations: [] });
await expect(
methods.getAgentEventActorReconciliationStorageMetrics(
new Date(observedAt.getTime() + 12_000),
),
).resolves.toEqual({ pending: 0, oldestPendingAgeSeconds: 0 });
});
it('does not prune legacy settled receipts during new invocation admission', async () => {
const conversationId = uuidv4();
await Conversation.create({
conversationId,
user: 'actor-retention-user',
endpoint: EModelEndpoint.agents,
agent_id: 'agent-player',
agentEventBinding: {
bindingId: `evtbind_${'e'.repeat(48)}`,
sourceKeyId: 'key-a',
actorId: 'player-a',
},
subagentThread: {
rootConversationId: 'parent',
parentConversationId: 'parent',
parentMessageId: 'parent-message',
parentToolCallId: 'event-binding',
parentAgentId: 'agent-director',
subagentType: 'agent-player',
subagentKind: 'agent',
depth: 1,
},
});
const settleReceipt = async (invocationId: string) => {
const checkpoint = {
threadId: conversationId,
checkpointId: `checkpoint-${invocationId}`,
checkpointNs: `event-actor/${invocationId}`,
};
const base = {
invocationId,
checkpoint,
action: { toolName: 'submit_move' },
observedAt: new Date(),
};
await expect(
methods.recordAgentEventActorReconciliation({
user: 'actor-retention-user',
conversationId,
reconciliation: { ...base, status: 'invocation_pending' },
}),
).resolves.toBe(true);
await expect(
methods.recordAgentEventActorReconciliation({
user: 'actor-retention-user',
conversationId,
reconciliation: { ...base, status: 'commit_conflict', error: 'conflict' },
}),
).resolves.toBe(true);
await expect(
methods.resolveAgentEventActorReconciliation({
user: 'actor-retention-user',
conversationId,
invocationId,
checkpoint,
resolution: 'action_compensated',
}),
).resolves.toBe(true);
};
await settleReceipt('event-old');
await settleReceipt('event-recent');
await Conversation.updateOne(
{ conversationId },
{
$set: {
'agentEventActorReconciliations.$[receipt].observedAt': new Date(
Date.now() - 8 * 24 * 60 * 60 * 1000,
),
},
},
{ arrayFilters: [{ 'receipt.invocationId': 'event-old' }], timestamps: false },
);
await expect(
methods.recordAgentEventActorReconciliation({
user: 'actor-retention-user',
conversationId,
reconciliation: {
invocationId: 'event-next',
status: 'invocation_pending',
checkpoint: {
threadId: conversationId,
checkpointId: 'checkpoint-next',
checkpointNs: 'event-actor/next',
},
action: { toolName: 'submit_move' },
observedAt: new Date(),
},
}),
).resolves.toBe(true);
/** Conversation admission no longer owns receipt retention. Lazy
* delivery-ledger migration removes either legacy receipt only after its
* authoritative row is durable. */
await expect(
methods.getAgentEventActorSnapshot({
user: 'actor-retention-user',
conversationId,
}),
).resolves.toEqual({
state: null,
epoch: 0,
legacyTurn: null,
suspension: null,
reconciliations: [
expect.objectContaining({ invocationId: 'event-old', status: 'settled' }),
expect.objectContaining({ invocationId: 'event-recent', status: 'settled' }),
expect.objectContaining({ invocationId: 'event-next', status: 'invocation_pending' }),
],
});
});
it('expires dormant legacy settled receipts independently of matching delivery replay', async () => {
const oldConversationId = uuidv4();
const recentConversationId = uuidv4();
const settled = (invocationId: string, observedAt: Date) => ({
invocationId,
status: 'settled' as const,
resolution: 'action_compensated' as const,
checkpoint: {
threadId: invocationId === 'old' ? oldConversationId : recentConversationId,
checkpointNs: `event-actor/${invocationId}`,
},
action: { toolName: 'submit_move' },
observedAt,
});
const now = new Date();
await Conversation.create([
{
conversationId: oldConversationId,
user: 'actor-legacy-expiry-user',
endpoint: EModelEndpoint.agents,
agentEventActorReconciliations: [
settled('old', new Date(now.getTime() - 91 * 24 * 60 * 60_000)),
],
},
{
conversationId: recentConversationId,
user: 'actor-legacy-expiry-user',
endpoint: EModelEndpoint.agents,
agentEventActorReconciliations: [
settled('recent', new Date(now.getTime() - 89 * 24 * 60 * 60_000)),
],
},
]);
const activity = { found: false };
await expect(methods.expireLegacyAgentEventActorReceipts(now, 1, activity)).resolves.toBe(1);
expect(activity.found).toBe(true);
await expect(
Conversation.findOne({ conversationId: oldConversationId })
.select('+agentEventActorReconciliations')
.lean(),
).resolves.toMatchObject({ agentEventActorReconciliations: [] });
await expect(
Conversation.findOne({ conversationId: recentConversationId })
.select('+agentEventActorReconciliations')
.lean(),
).resolves.toMatchObject({
agentEventActorReconciliations: [expect.objectContaining({ invocationId: 'recent' })],
});
});
it('sends a pure inclusion projection for the candidate read', async () => {
/** The string form `'_id +field'` compiles to `{ _id: 1 }` plus a `: 0`
* exclusion for every other `select: false` sibling — a mixed projection
* MongoDB tolerates but Amazon DocumentDB rejects, which failed this
* sweep on every maintenance pass. The candidate read must stay a pure
* inclusion AND still return the hidden reconciliations field. */
const conversationId = uuidv4();
const now = new Date();
await Conversation.create({
conversationId,
user: 'actor-projection-user',
endpoint: EModelEndpoint.agents,
agentEventActorReconciliations: [
{
invocationId: 'projection-probe',
status: 'settled',
resolution: 'action_compensated',
checkpoint: {
threadId: conversationId,
checkpointNs: 'event-actor/projection-probe',
},
action: { toolName: 'submit_move' },
observedAt: new Date(now.getTime() - 91 * 24 * 60 * 60_000),
},
],
});
const projections: Array<Record<string, number> | undefined> = [];
const originalFind = Conversation.collection.find.bind(Conversation.collection);
const findSpy = jest
.spyOn(Conversation.collection, 'find')
.mockImplementation((filter, options) => {
projections.push(options?.projection);
return originalFind(filter, options);
});
try {
await expect(methods.expireLegacyAgentEventActorReceipts(now)).resolves.toBe(1);
} finally {
findSpy.mockRestore();
}
expect(projections[0]).toEqual({ _id: 1, agentEventActorReconciliations: 1 });
});
it('retains an expired legacy receipt while its delivery handling is nonterminal', async () => {
const conversationId = uuidv4();
const userId = new mongoose.Types.ObjectId();
const now = new Date();
await Conversation.create({
conversationId,
user: userId.toString(),
endpoint: EModelEndpoint.agents,
agentEventActorReconciliations: [
{
invocationId: 'protected-old',
status: 'settled',
resolution: 'checkpoint_verified',
checkpoint: {
threadId: conversationId,
checkpointId: 'checkpoint-old',
checkpointNs: 'event-actor/protected-old',
},
action: { toolName: 'submit_move' },
observedAt: new Date(now.getTime() - 91 * 24 * 60 * 60_000),
},
],
});
const Delivery = mongoose.models.AgentTriggerDelivery;
await Delivery.create({
deliveryKey: 'protected-old',
fingerprint: 'protected-old-fingerprint',
orderingKey: 'protected-old-lane',
laneSequence: 1,
envelope: {},
user: userId,
status: 'succeeded',
attempts: 1,
availableAt: now,
awaitTerminalHandling: true,
handling: {
status: 'started',
conversationId,
streamId: conversationId,
generationCreatedAt: now.getTime(),
startedAt: now,
},
});
await expect(methods.expireLegacyAgentEventActorReceipts(now)).resolves.toBe(0);
await expect(
Conversation.findOne({ conversationId }).select('+agentEventActorReconciliations').lean(),
).resolves.toMatchObject({
agentEventActorReconciliations: [
expect.objectContaining({ invocationId: 'protected-old' }),
],
});
await Delivery.updateOne(
{ deliveryKey: 'protected-old' },
{ $set: { 'handling.status': 'applied', 'handling.settledAt': now } },
);
const updatedAtBeforeExpiry = (
await Conversation.findOne({ conversationId }).select('updatedAt').lean()
)?.updatedAt;
/** The first call reaches the end of the protected page and resets the
* cursor; the next bounded sweep revisits it after handling is terminal. */
await expect(methods.expireLegacyAgentEventActorReceipts(now)).resolves.toBe(0);
await expect(methods.expireLegacyAgentEventActorReceipts(now)).resolves.toBe(1);
await expect(
Conversation.findOne({ conversationId }).select('updatedAt').lean(),
).resolves.toMatchObject({ updatedAt: updatedAtBeforeExpiry });
});
it('pages raw conversations before filtering and advances past protected receipts', async () => {
const freshConversationId = uuidv4();
const protectedConversationId = uuidv4();
const removableConversationId = uuidv4();
const userId = new mongoose.Types.ObjectId();
const now = new Date();
const oldReceipt = (invocationId: string, threadId: string) => ({
invocationId,
status: 'settled' as const,
resolution: 'action_compensated' as const,
checkpoint: { threadId, checkpointNs: `event-actor/${invocationId}` },
action: { toolName: 'submit_move' },
observedAt: new Date(now.getTime() - 91 * 24 * 60 * 60_000),
});
await Conversation.create([
{
conversationId: freshConversationId,
user: userId.toString(),
endpoint: EModelEndpoint.agents,
agentEventActorReconciliations: [
{ ...oldReceipt('fresh-first', freshConversationId), observedAt: now },
],
},
{
conversationId: protectedConversationId,
user: userId.toString(),
endpoint: EModelEndpoint.agents,
agentEventActorReconciliations: [oldReceipt('protected-first', protectedConversationId)],
},
{
conversationId: removableConversationId,
user: userId.toString(),
endpoint: EModelEndpoint.agents,
agentEventActorReconciliations: [oldReceipt('removable-second', removableConversationId)],
},
]);
const Delivery = mongoose.models.AgentTriggerDelivery;
await Delivery.create({
deliveryKey: 'protected-first',
fingerprint: 'protected-first-fingerprint',
orderingKey: 'protected-first-lane',
laneSequence: 1,
envelope: {},
user: userId,
status: 'succeeded',
attempts: 1,
availableAt: now,
awaitTerminalHandling: true,
});
/** The first raw page contains no expired receipt. It must still keep
* discovery active, without querying delivery protection for an empty ID set.
* The second is protected, and only the third reaches removable work. */
const activity = { found: false };
const protection = jest.spyOn(Delivery, 'find');
try {
await expect(methods.expireLegacyAgentEventActorReceipts(now, 1, activity)).resolves.toBe(
0,
);
expect(activity.found).toBe(true);
expect(protection).not.toHaveBeenCalled();
} finally {
protection.mockRestore();
}
await expect(methods.expireLegacyAgentEventActorReceipts(now, 1)).resolves.toBe(0);
await expect(methods.expireLegacyAgentEventActorReceipts(now, 1)).resolves.toBe(1);
await expect(
Conversation.findOne({ conversationId: protectedConversationId })
.select('+agentEventActorReconciliations')
.lean(),
).resolves.toMatchObject({
agentEventActorReconciliations: [
expect.objectContaining({ invocationId: 'protected-first' }),
],
});
await expect(
Conversation.findOne({ conversationId: removableConversationId })
.select('+agentEventActorReconciliations')
.lean(),
).resolves.toMatchObject({ agentEventActorReconciliations: [] });
});
it('clears a compensated headless lifecycle without creating a partial actor head', async () => {
const conversationId = uuidv4();
const checkpoint = {
threadId: conversationId,
checkpointNs: 'event-actor/headless-compensation',
};
await Conversation.create({
conversationId,
user: 'actor-headless-clear-user',
endpoint: EModelEndpoint.agents,
agent_id: 'agent-player',
agentEventBinding: {
bindingId: `evtbind_${'d'.repeat(48)}`,
sourceKeyId: 'key-a',
actorId: 'player-a',
},
subagentThread: {
rootConversationId: 'parent',
parentConversationId: 'parent',
parentMessageId: 'parent-message',
parentToolCallId: 'event-binding',
parentAgentId: 'agent-director',
subagentType: 'agent-player',
subagentKind: 'agent',
depth: 1,
},
agentEventActorReconciliations: [
{
invocationId: 'headless-compensation',
status: 'commit_conflict',
checkpoint,
action: { toolName: 'submit_move' },
observedAt: new Date(),
},
],
});
await expect(
methods.clearAgentEventActorReconciliation({
user: 'actor-headless-clear-user',
conversationId,
invocationId: 'headless-compensation',
checkpoint,
resolution: 'action_compensated',
}),
).resolves.toBe(true);
await expect(
Conversation.findOne({ conversationId })
.select('+agentEventActor +agentEventActorReconciliations')
.lean(),
).resolves.toMatchObject({ agentEventActorReconciliations: [] });
const stored = await Conversation.findOne({ conversationId })
.select('+agentEventActor')
.lean();
expect(stored?.agentEventActor).toBeUndefined();
});
it('clears an exact settled legacy receipt after delivery-ledger migration', async () => {
const conversationId = uuidv4();
const checkpoint = {
threadId: conversationId,
checkpointId: 'checkpoint-migrated',
checkpointNs: 'event-actor/migrated',
};
await Conversation.create({
conversationId,
user: 'actor-migrated-clear-user',
endpoint: EModelEndpoint.agents,
agent_id: 'agent-player',
agentEventBinding: {
bindingId: `evtbind_${'c'.repeat(48)}`,
sourceKeyId: 'key-a',
actorId: 'player-a',
},
subagentThread: {
rootConversationId: 'parent',
parentConversationId: 'parent',
parentMessageId: 'parent-message',
parentToolCallId: 'event-binding',
parentAgentId: 'agent-director',
subagentType: 'agent-player',
subagentKind: 'agent',
depth: 1,
},
agentEventActor: { generation: 1, checkpoint },
agentEventActorReconciliations: [
{
invocationId: 'migrated',
status: 'settled',
resolution: 'checkpoint_verified',
checkpoint,
action: { toolName: 'submit_move' },
observedAt: new Date(),
},
],
});
await expect(
methods.clearAgentEventActorReconciliation({
user: 'actor-migrated-clear-user',
conversationId,
invocationId: 'migrated',
checkpoint,
resolution: 'checkpoint_verified',
}),
).resolves.toBe(true);
await expect(
methods.getAgentEventActorSnapshot({
user: 'actor-migrated-clear-user',
conversationId,
}),
).resolves.toMatchObject({ reconciliations: [] });
});
it('does not compensate an action that has not passed invocation admission', async () => {
const conversationId = uuidv4();
const checkpoint = {
threadId: conversationId,
checkpointNs: 'event-actor/not-admitted',
};
await Conversation.create({
conversationId,
user: 'actor-unadmitted-user',
endpoint: EModelEndpoint.agents,
agent_id: 'agent-player',
agentEventBinding: {
bindingId: `evtbind_${'b'.repeat(48)}`,
sourceKeyId: 'key-a',
actorId: 'player-a',
},
subagentThread: {
rootConversationId: 'parent',
parentConversationId: 'parent',
parentMessageId: 'parent-message',
parentToolCallId: 'event-binding',
parentAgentId: 'agent-director',
subagentType: 'agent-player',
subagentKind: 'agent',
depth: 1,
},
agentEventActorReconciliations: [
{
invocationId: 'not-admitted',
actionAdmitted: true,
status: 'invocation_pending',
checkpoint,
action: { toolName: 'submit_move' },
observedAt: new Date(),
},
],
});
await expect(
methods.resolveAgentEventActorReconciliation({
user: 'actor-unadmitted-user',
conversationId,
invocationId: 'not-admitted',
checkpoint,
resolution: 'action_compensated',
}),
).resolves.toBe(false);
});
it('versions every legacy invalidation so a stale prepared fork cannot commit past it', async () => {
const conversationId = uuidv4();
await Conversation.create({
conversationId,
user: 'actor-epoch-user',
endpoint: EModelEndpoint.agents,
agent_id: 'agent-player',
agentEventBinding: {
bindingId: `evtbind_${'a'.repeat(48)}`,
sourceKeyId: 'key-a',
actorId: 'player-a',
},
subagentThread: {
rootConversationId: 'parent',
parentConversationId: 'parent',
parentMessageId: 'parent-message',
parentToolCallId: 'event-binding',
parentAgentId: 'agent-director',
subagentType: 'agent-player',
subagentKind: 'agent',
depth: 1,
},
});
const owner = { user: 'actor-epoch-user', conversationId };
const checkpoint = (id: string) => ({
threadId: conversationId,
checkpointId: `checkpoint-${id}`,
checkpointNs: `event-actor/${id}`,
});
/** A headless actor has nothing for the cold-start marker to mark, so
* the epoch is the invalidation's only durable trace. */
await expect(methods.getAgentEventActorSnapshot(owner)).resolves.toMatchObject({
state: null,
epoch: 0,
legacyTurn: null,
});
await expect(
methods.beginAgentEventActorLegacyTurn({ ...owner, token: 'legacy-a' }),
).resolves.toBe(true);
/** While the fence is open the epoch has NOT moved — the fence itself is
* what blocks, so a fork cannot slip through on an unchanged epoch. */
await expect(methods.getAgentEventActorSnapshot(owner)).resolves.toMatchObject({
state: null,
legacyTurn: { token: 'legacy-a' },
epoch: 0,
});
await expect(
methods.completeAgentEventActorLegacyTurn({ ...owner, token: 'legacy-a' }),
).resolves.toBe(true);
await expect(methods.getAgentEventActorSnapshot(owner)).resolves.toMatchObject({
state: null,
legacyTurn: null,
epoch: 1,
});
await expect(
methods.recordAgentEventActorReconciliation({
...owner,
reconciliation: {
invocationId: 'event-stale-cold',
status: 'invocation_pending',
checkpoint: checkpoint('stale-cold'),
action: { toolName: 'submit_move' },
observedAt: new Date(),
},
}),
).resolves.toBe(true);
/** The stale fork prepared against epoch 0; its expected-absent head
* still matches, so only the epoch defeats the commit. */
await expect(
methods.commitAgentEventActorState({
...owner,
invocationId: 'event-stale-cold',
action: { toolName: 'submit_move' },
expectedEpoch: 0,
checkpoint: checkpoint('stale-cold'),
}),
).resolves.toEqual({ status: 'stale' });
await expect(
methods.commitAgentEventActorState({
...owner,
invocationId: 'event-stale-cold',
action: { toolName: 'submit_move' },
expectedEpoch: 1,
checkpoint: checkpoint('stale-cold'),
}),
).resolves.toMatchObject({ status: 'committed', state: { generation: 1 } });
await expect(
methods.recordAgentEventActorReconciliation({
...owner,
reconciliation: {
invocationId: 'event-stale-cold',
status: 'history_persisted',
checkpoint: checkpoint('stale-cold'),
action: { toolName: 'submit_move' },
observedAt: new Date(),
},
}),
).resolves.toBe(true);
await expect(
methods.resolveAgentEventActorReconciliation({
...owner,
invocationId: 'event-stale-cold',
checkpoint: checkpoint('stale-cold'),
resolution: 'checkpoint_verified',
}),
).resolves.toBe(true);
/** An already cold-marked head shows no field change from a second
* invalidation either — the epoch must still advance every time. */
for (const token of ['legacy-b', 'legacy-c']) {
await expect(methods.beginAgentEventActorLegacyTurn({ ...owner, token })).resolves.toBe(
true,
);
await expect(methods.completeAgentEventActorLegacyTurn({ ...owner, token })).resolves.toBe(
true,
);
}
const snapshot = await methods.getAgentEventActorSnapshot(owner);
expect(snapshot).toMatchObject({
state: { generation: 1, requiresColdStart: true },
epoch: 3,
legacyTurn: null,
});
await expect(
methods.recordAgentEventActorReconciliation({
...owner,
reconciliation: {
invocationId: 'event-stale-rebuild',
status: 'invocation_pending',
checkpoint: checkpoint('stale-rebuild'),
action: { toolName: 'submit_move' },
observedAt: new Date(),
},
}),
).resolves.toBe(true);
await expect(
methods.commitAgentEventActorState({
...owner,
invocationId: 'event-stale-rebuild',
action: { toolName: 'submit_move' },
expected: { ...snapshot!.state!, requiresColdStart: true },
expectedEpoch: 2,
checkpoint: checkpoint('stale-rebuild'),
}),
).resolves.toMatchObject({ status: 'stale' });
await expect(
methods.commitAgentEventActorState({
...owner,
invocationId: 'event-stale-rebuild',
action: { toolName: 'submit_move' },
expected: { ...snapshot!.state!, requiresColdStart: true },
expectedEpoch: 3,
checkpoint: checkpoint('stale-rebuild'),
}),
).resolves.toMatchObject({ status: 'committed', state: { generation: 2 } });
/** Sealing a completed legacy turn advances the epoch. Fork admission
* and legacy admission are mutually exclusive, so neither executor can
* begin its external work while the other owns the actor. */
await expect(
methods.recordAgentEventActorReconciliation({
...owner,
reconciliation: {
invocationId: 'event-stale-rebuild',
status: 'history_persisted',
checkpoint: checkpoint('stale-rebuild'),
action: { toolName: 'submit_move' },
observedAt: new Date(),
},
}),
).resolves.toBe(true);
await expect(
methods.resolveAgentEventActorReconciliation({
...owner,
invocationId: 'event-stale-rebuild',
checkpoint: checkpoint('stale-rebuild'),
resolution: 'checkpoint_verified',
}),
).resolves.toBe(true);
await expect(
methods.beginAgentEventActorLegacyTurn({ ...owner, token: 'legacy-d' }),
).resolves.toBe(true);
/** An open legacy fence refuses fork-lifecycle admission outright. */
await expect(
methods.recordAgentEventActorReconciliation({
...owner,
reconciliation: {
invocationId: 'event-during-legacy',
status: 'invocation_pending',
checkpoint: checkpoint('during-legacy'),
action: { toolName: 'submit_move' },
observedAt: new Date(),
},
}),
).resolves.toBe(false);
const beforeSeal = await methods.getAgentEventActorSnapshot(owner);
/** Defense in depth: a commit without an admitted invocation is stale,
* even at the exact epoch observed while the legacy turn is open. */
await expect(
methods.commitAgentEventActorState({
...owner,
invocationId: 'event-during-legacy',
action: { toolName: 'submit_move' },
expected: beforeSeal!.state!,
expectedEpoch: beforeSeal!.epoch,
checkpoint: checkpoint('during-legacy'),
}),
).resolves.toMatchObject({ status: 'stale' });
/** The legacy owner can now seal its exact token and advance the epoch. */
await expect(
methods.completeAgentEventActorLegacyTurn({ ...owner, token: 'legacy-d' }),
).resolves.toBe(true);
await expect(methods.getAgentEventActorSnapshot(owner)).resolves.toMatchObject({
state: { generation: 2, requiresColdStart: true },
legacyTurn: null,
epoch: 4,
});
});
it('serializes legacy-turn and fork-lifecycle acquisition before either can execute', async () => {
const conversationId = uuidv4();
await Conversation.create({
conversationId,
user: 'actor-mutual-exclusion-user',
endpoint: EModelEndpoint.agents,
agent_id: 'agent-player',
agentEventBinding: {
bindingId: `evtbind_${'m'.repeat(48)}`,
sourceKeyId: 'key-a',
actorId: 'player-a',
},
subagentThread: {
rootConversationId: 'parent',
parentConversationId: 'parent',
parentMessageId: 'parent-message',
parentToolCallId: 'event-binding',
parentAgentId: 'agent-director',
subagentType: 'agent-player',
subagentKind: 'agent',
depth: 1,
},
});
const owner = { user: 'actor-mutual-exclusion-user', conversationId };
const checkpoint = {
threadId: conversationId,
checkpointId: 'checkpoint-mutual-exclusion',
checkpointNs: 'event-actor/mutual-exclusion',
};
const pending = (invocationId: string) => ({
invocationId,
status: 'invocation_pending' as const,
checkpoint,
action: { toolName: 'submit_move' },
observedAt: new Date(),
});
await expect(
methods.beginAgentEventActorLegacyTurn({ ...owner, token: 'legacy-wins' }),
).resolves.toBe(true);
await expect(
methods.recordAgentEventActorReconciliation({
...owner,
reconciliation: pending('fork-loses'),
}),
).resolves.toBe(false);
await expect(
methods.completeAgentEventActorLegacyTurn({ ...owner, token: 'legacy-wins' }),
).resolves.toBe(true);
await expect(
methods.recordAgentEventActorReconciliation({
...owner,
reconciliation: pending('fork-wins'),
}),
).resolves.toBe(true);
await expect(
methods.beginAgentEventActorLegacyTurn({ ...owner, token: 'legacy-loses' }),
).resolves.toBe(false);
});
it('uses a DocumentDB-compatible classic update for legacy fence open', async () => {
const conversationId = uuidv4();
await Conversation.create({
conversationId,
user: 'actor-documentdb-fence-user',
endpoint: EModelEndpoint.agents,
agent_id: 'agent-player',
agentEventBinding: {
bindingId: `evtbind_${'d'.repeat(48)}`,
sourceKeyId: 'key-a',
actorId: 'player-a',
},
subagentThread: {
rootConversationId: 'parent',
parentConversationId: 'parent',
parentMessageId: 'parent-message',
parentToolCallId: 'event-binding',
parentAgentId: 'agent-director',
subagentType: 'agent-player',
subagentKind: 'agent',
depth: 1,
},
});
const owner = { user: 'actor-documentdb-fence-user', conversationId };
const updateSpy = jest.spyOn(Conversation, 'findOneAndUpdate');
try {
await expect(
methods.beginAgentEventActorLegacyTurn({ ...owner, token: 'documentdb-token' }),
).resolves.toBe(true);
expect(updateSpy.mock.calls.length).toBeGreaterThan(0);
for (const [, update] of updateSpy.mock.calls) {
expect(Array.isArray(update)).toBe(false);
}
} finally {
updateSpy.mockRestore();
}
});
it('does not let a legacy settled journal cap block a healthy actor', async () => {
const conversationId = uuidv4();
await Conversation.create({
conversationId,
user: 'actor-cap-user',
endpoint: EModelEndpoint.agents,
agent_id: 'agent-player',
agentEventBinding: {
bindingId: `evtbind_${'f'.repeat(48)}`,
sourceKeyId: 'key-a',
actorId: 'player-a',
},
subagentThread: {
rootConversationId: 'parent',
parentConversationId: 'parent',
parentMessageId: 'parent-message',
parentToolCallId: 'event-binding',
parentAgentId: 'agent-director',
subagentType: 'agent-player',
subagentKind: 'agent',
depth: 1,
},
});
const bulkReceipts = (observedAt: Date) =>
Array.from({ length: 1025 }, (_, index) => ({
invocationId: `bulk-${index}`,
status: 'settled' as const,
resolution: 'checkpoint_verified' as const,
checkpoint: {
threadId: conversationId,
checkpointId: `checkpoint-${index}`,
checkpointNs: `event-actor/bulk-${index}`,
},
action: { toolName: 'submit_move' },
observedAt,
}));
await Conversation.updateOne(
{ conversationId },
{ $set: { agentEventActorReconciliations: bulkReceipts(new Date()) } },
{ timestamps: false },
);
const admit = () =>
methods.recordAgentEventActorReconciliation({
user: 'actor-cap-user',
conversationId,
reconciliation: {
invocationId: 'event-at-cap',
status: 'invocation_pending',
checkpoint: {
threadId: conversationId,
checkpointId: 'checkpoint-cap',
checkpointNs: 'event-actor/cap',
},
action: { toolName: 'submit_move' },
observedAt: new Date(),
},
});
await expect(admit()).resolves.toBe(true);
await expect(
methods.getAgentEventActorSnapshot({
user: 'actor-cap-user',
conversationId,
}),
).resolves.toEqual(
expect.objectContaining({
reconciliations: expect.arrayContaining([
expect.objectContaining({ invocationId: 'bulk-0' }),
expect.objectContaining({ invocationId: 'event-at-cap' }),
]),
}),
);
});
it('admits one cross-replica owner and fences renewal and release by token', async () => {
const conversationId = uuidv4();
await Conversation.create({
conversationId,
user: 'lease-user',
endpoint: EModelEndpoint.agents,
subagentThread: {
rootConversationId: 'root',
parentConversationId: 'parent',
parentMessageId: 'parent-message',
parentToolCallId: 'parent-tool',
parentAgentId: 'parent-agent',
subagentType: 'researcher',
subagentKind: 'agent',
depth: 1,
},
});
const now = new Date('2026-08-18T00:00:00.000Z');
const expiresAt = new Date(now.getTime() + 30_000);
const claims = await Promise.all(
['token-a', 'token-b'].map((token) =>
methods.acquireSubagentThreadLease({
user: 'lease-user',
conversationId,
token,
taskId: `task-${token}`,
now,
expiresAt,
}),
),
);
expect(claims.filter(Boolean)).toHaveLength(1);
const winner = claims[0] ? 'token-a' : 'token-b';
const loser = winner === 'token-a' ? 'token-b' : 'token-a';
expect(await methods.countActiveSubagentThreadLeases({ user: 'lease-user', now })).toBe(1);
await expect(
methods.listActiveSubagentThreadLeases({ user: 'lease-user', now }),
).resolves.toEqual([
{
conversationId,
parentConversationId: 'parent',
taskId: `task-${winner}`,
},
]);
expect(await methods.getConvo('lease-user', conversationId)).not.toHaveProperty(
'subagentThreadLease',
);
await expect(
methods.renewSubagentThreadLease({
user: 'lease-user',
conversationId,
token: loser,
now,
expiresAt: new Date(expiresAt.getTime() + 30_000),
}),
).resolves.toBe(false);
await expect(
methods.releaseSubagentThreadLease({
user: 'lease-user',
conversationId,
token: loser,
}),
).resolves.toBe(false);
await expect(
methods.releaseSubagentThreadLease({
user: 'lease-user',
conversationId,
token: winner,
}),
).resolves.toBe(true);
expect(await methods.countActiveSubagentThreadLeases({ user: 'lease-user', now })).toBe(0);
});
it('allows takeover only after the prior lease expires', async () => {
const conversationId = uuidv4();
await Conversation.create({
conversationId,
user: 'takeover-user',
endpoint: EModelEndpoint.agents,
subagentThread: {
rootConversationId: 'root',
parentConversationId: 'parent',
parentMessageId: 'parent-message',
parentToolCallId: 'parent-tool',
subagentType: 'graph',
subagentKind: 'graph',
depth: 1,
},
});
const startedAt = new Date('2026-08-18T00:00:00.000Z');
const firstExpiry = new Date(startedAt.getTime() + 1_000);
await methods.acquireSubagentThreadLease({
user: 'takeover-user',
conversationId,
token: 'first',
taskId: 'task-first',
now: startedAt,
expiresAt: firstExpiry,
});
await expect(
methods.acquireSubagentThreadLease({
user: 'takeover-user',
conversationId,
token: 'second',
taskId: 'task-second',
now: new Date(firstExpiry.getTime() - 1),
expiresAt: new Date(firstExpiry.getTime() + 1_000),
}),
).resolves.toBe(false);
await expect(
methods.acquireSubagentThreadLease({
user: 'takeover-user',
conversationId,
token: 'second',
taskId: 'task-second',
now: firstExpiry,
expiresAt: new Date(firstExpiry.getTime() + 1_000),
}),
).resolves.toBe(true);
});
});
describe('tenantId stripping', () => {
it('saveConvo should not write caller-supplied tenantId to the document', async () => {
const conversationId = uuidv4();
const result = await saveConvo(
{ userId: 'user123' },
{ conversationId, tenantId: 'malicious-tenant', title: 'Tenant Test' },
);
expect(result).not.toBeNull();
const doc = await Conversation.findOne({ conversationId }).lean();
expect(doc).not.toBeNull();
expect(doc?.title).toBe('Tenant Test');
expect(doc?.tenantId).toBeUndefined();
});
it('bulkSaveConvos should not overwrite tenantId via update payload', async () => {
const conversationId = uuidv4();
await tenantStorage.run({ tenantId: 'real-tenant' }, async () => {
await Conversation.create({
conversationId,
user: 'user123',
title: 'Original',
endpoint: EModelEndpoint.openAI,
});
});
await tenantStorage.run({ tenantId: 'real-tenant' }, async () => {
await methods.bulkSaveConvos([
{
conversationId,
user: 'user123',
title: 'Updated',
tenantId: 'malicious-tenant',
endpoint: EModelEndpoint.openAI,
},
]);
});
const doc = await runAsSystem(async () => Conversation.findOne({ conversationId }).lean());
expect(doc).not.toBeNull();
expect(doc?.title).toBe('Updated');
expect(doc?.tenantId).toBe('real-tenant');
});
it('bulkSaveConvos refreshes stats for cloned project conversations', async () => {
const project = await ChatProject.create({
user: 'user123',
name: 'Bulk Project',
conversationCount: 0,
lastConversationAt: null,
lastConversationId: null,
});
const conversationId = uuidv4();
const createdAt = new Date('2026-01-01T00:00:00.000Z');
await methods.bulkSaveConvos([
{
conversationId,
user: 'user123',
title: 'Cloned Project Chat',
endpoint: EModelEndpoint.openAI,
chatProjectId: project._id!.toString(),
createdAt,
updatedAt: createdAt,
},
]);
const refreshedProject = await ChatProject.findById(project._id).lean<IChatProject>();
expect(refreshedProject?.conversationCount).toBe(1);
expect(refreshedProject?.lastConversationId).toBe(conversationId);
expect(refreshedProject?.lastConversationAt?.toISOString()).toBe(createdAt.toISOString());
});
});
describe('getConvosByCursor search', () => {
it('should include conversations matched only by message content', async () => {
const titleMatch = await Conversation.create({
conversationId: uuidv4(),
user: 'user123',
title: 'Contains keyword',
endpoint: EModelEndpoint.openAI,
});
const contentMatch = await Conversation.create({
conversationId: uuidv4(),
user: 'user123',
title: 'Unrelated title',
endpoint: EModelEndpoint.openAI,
});
await Conversation.create({
conversationId: uuidv4(),
user: 'user123',
title: 'No match anywhere',
endpoint: EModelEndpoint.openAI,
});
const meiliSearch = jest
.fn()
.mockResolvedValue({ hits: [{ conversationId: titleMatch.conversationId }] });
Object.assign(Conversation, { meiliSearch });
searchMessages.mockResolvedValue({
hits: [{ conversationId: contentMatch.conversationId }],
});
const result = await getConvosByCursor('user123', { search: 'keyword' });
const searchParams = {
filter: 'user = "user123"',
limit: MEILI_SEARCH_LIMIT,
attributesToRetrieve: ['conversationId', 'originalConversationId'],
};
expect(meiliSearch).toHaveBeenCalledWith('keyword', searchParams);
expect(searchMessages).toHaveBeenCalledWith('keyword', searchParams);
const convoIds = result?.conversations.map((c) => c.conversationId);
expect(convoIds).toHaveLength(2);
expect(convoIds).toContain(titleMatch.conversationId);
expect(convoIds).toContain(contentMatch.conversationId);
});
it('should dedupe conversations matched by both title and message search', async () => {
const overlapMatch = await Conversation.create({
conversationId: uuidv4(),
user: 'user123',
title: 'Contains keyword',
endpoint: EModelEndpoint.openAI,
});
const titleOnlyMatch = await Conversation.create({
conversationId: uuidv4(),
user: 'user123',
title: 'Keyword in title',
endpoint: EModelEndpoint.openAI,
});
const messageOnlyMatch = await Conversation.create({
conversationId: uuidv4(),
user: 'user123',
title: 'Unrelated title',
endpoint: EModelEndpoint.openAI,
});
const meiliSearch = jest.fn().mockResolvedValue({
hits: [
{ conversationId: overlapMatch.conversationId },
{ conversationId: titleOnlyMatch.conversationId },
],
});
Object.assign(Conversation, { meiliSearch });
searchMessages.mockResolvedValue({
hits: [
{ conversationId: overlapMatch.conversationId },
{ conversationId: messageOnlyMatch.conversationId },
],
});
const result = await getConvosByCursor('user123', { search: 'keyword' });
const searchParams = {
filter: 'user = "user123"',
limit: MEILI_SEARCH_LIMIT,
attributesToRetrieve: ['conversationId', 'originalConversationId'],
};
expect(meiliSearch).toHaveBeenCalledWith('keyword', searchParams);
expect(searchMessages).toHaveBeenCalledWith('keyword', searchParams);
const convoIds = result?.conversations.map((c) => c.conversationId);
expect(convoIds).toHaveLength(3);
expect(convoIds).toContain(overlapMatch.conversationId);
expect(convoIds).toContain(titleOnlyMatch.conversationId);
expect(convoIds).toContain(messageOnlyMatch.conversationId);
});
it('should return an empty result when neither titles nor messages match', async () => {
await Conversation.create({
conversationId: uuidv4(),
user: 'user123',
title: 'No match anywhere',
endpoint: EModelEndpoint.openAI,
});
Object.assign(Conversation, { meiliSearch: jest.fn().mockResolvedValue({ hits: [] }) });
searchMessages.mockResolvedValue({ hits: [] });
const result = await getConvosByCursor('user123', { search: 'keyword' });
expect(result?.conversations).toHaveLength(0);
expect(result?.nextCursor).toBeNull();
});
it('should fall back to title matches when the message index search fails', async () => {
const titleMatch = await Conversation.create({
conversationId: uuidv4(),
user: 'user123',
title: 'Contains keyword',
endpoint: EModelEndpoint.openAI,
});
Object.assign(Conversation, {
meiliSearch: jest
.fn()
.mockResolvedValue({ hits: [{ conversationId: titleMatch.conversationId }] }),
});
searchMessages.mockRejectedValue(new Error('MeiliSearch plugin not registered'));
const result = await getConvosByCursor('user123', { search: 'keyword' });
expect(result?.conversations.map((c) => c.conversationId)).toEqual([
titleMatch.conversationId,
]);
});
it('should search titles when message methods are not injected', async () => {
const titleMatch = await Conversation.create({
conversationId: uuidv4(),
user: 'user123',
title: 'Contains keyword',
endpoint: EModelEndpoint.openAI,
});
Object.assign(Conversation, {
meiliSearch: jest
.fn()
.mockResolvedValue({ hits: [{ conversationId: titleMatch.conversationId }] }),
});
const scopedMethods = createConversationMethods(mongoose);
const result = await scopedMethods.getConvosByCursor('user123', { search: 'keyword' });
expect(result?.conversations.map((c) => c.conversationId)).toEqual([
titleMatch.conversationId,
]);
});
});
describe('getConvosByCursor list facets', () => {
const user = 'facet-user';
const day = 24 * 60 * 60 * 1000;
/** `timestamps: true` rewrites both dates on save, so a test that needs an old
* conversation has to set them afterwards. */
const makeConvo = async (
overrides: Partial<{
title: string;
endpoint: string;
updatedAt: Date;
createdAt: Date;
files: string[];
}> = {},
) => {
const convo = await Conversation.create({
conversationId: uuidv4(),
user,
title: overrides.title ?? 'Facet conversation',
endpoint: overrides.endpoint ?? EModelEndpoint.openAI,
...(overrides.files ? { files: overrides.files } : {}),
});
if (overrides.updatedAt || overrides.createdAt) {
/** Through the driver, not the model: Mongoose suppresses `updatedAt` only with
* `timestamps: false` and refuses `createdAt` outright, since it marks the
* field immutable. */
await Conversation.collection.updateOne(
{ _id: convo._id },
{
$set: {
...(overrides.updatedAt ? { updatedAt: overrides.updatedAt } : {}),
...(overrides.createdAt ? { createdAt: overrides.createdAt } : {}),
},
},
);
}
return convo;
};
beforeEach(async () => {
await Conversation.deleteMany({ user });
});
it('keeps only conversations updated at or after the cutoff', async () => {
const recent = await makeConvo({ title: 'recent', updatedAt: new Date() });
await makeConvo({ title: 'stale', updatedAt: new Date(Date.now() - 30 * day) });
const result = await getConvosByCursor(user, {
updatedAfter: new Date(Date.now() - 7 * day),
});
expect(result.conversations.map((c) => c.conversationId)).toEqual([recent.conversationId]);
});
it('filters on createdAt independently of updatedAt', async () => {
/** An old chat replied to today has a new updatedAt and an old createdAt. */
const revived = await makeConvo({
title: 'revived',
createdAt: new Date(Date.now() - 30 * day),
updatedAt: new Date(),
});
const fresh = await makeConvo({ title: 'fresh', createdAt: new Date() });
const byCreated = await getConvosByCursor(user, {
createdAfter: new Date(Date.now() - 7 * day),
});
expect(byCreated.conversations.map((c) => c.conversationId)).toEqual([fresh.conversationId]);
const byUpdated = await getConvosByCursor(user, {
updatedAfter: new Date(Date.now() - 7 * day),
});
expect(byUpdated.conversations.map((c) => c.conversationId).sort()).toEqual(
[revived.conversationId, fresh.conversationId].sort(),
);
});
it('matches any of the requested endpoints', async () => {
const openai = await makeConvo({ endpoint: EModelEndpoint.openAI });
const anthropic = await makeConvo({ endpoint: EModelEndpoint.anthropic });
await makeConvo({ endpoint: EModelEndpoint.google });
const result = await getConvosByCursor(user, {
endpoints: [EModelEndpoint.openAI, EModelEndpoint.anthropic],
});
expect(result.conversations.map((c) => c.conversationId).sort()).toEqual(
[openai.conversationId, anthropic.conversationId].sort(),
);
});
it('treats a missing and an emptied file list alike when filtering on attachments', async () => {
const withFiles = await makeConvo({ title: 'with files', files: ['file-1'] });
await makeConvo({ title: 'no field' });
await makeConvo({ title: 'emptied', files: [] });
const result = await getConvosByCursor(user, { hasFiles: true });
expect(result.conversations.map((c) => c.conversationId)).toEqual([withFiles.conversationId]);
});
it('includes conversations whose attachments ride on messages', async () => {
/** The standard send flow persists uploads on the user message, so a facet that
* only read the conversation's own array would miss every ordinary chat. */
const Message = mongoose.models.Message as mongoose.Model<{
user: string;
conversationId: string;
messageId: string;
files: unknown[];
}>;
const messageFiles = await makeConvo({ title: 'message files' });
await makeConvo({ title: 'neither' });
await Message.create({
user,
conversationId: messageFiles.conversationId,
messageId: uuidv4(),
text: 'here you go',
sender: 'User',
isCreatedByUser: true,
files: [{ file_id: 'file-1' }],
});
const result = await getConvosByCursor(user, { hasFiles: true });
expect(result.conversations.map((c) => c.conversationId)).toEqual([
messageFiles.conversationId,
]);
});
it('reads files attached to a message content part, such as a steer', async () => {
const Message = mongoose.models.Message as mongoose.Model<{
user: string;
conversationId: string;
messageId: string;
content: unknown[];
}>;
const steered = await makeConvo({ title: 'steered' });
const textOnly = await makeConvo({ title: 'text only' });
await Message.create([
{
user,
conversationId: steered.conversationId,
messageId: uuidv4(),
sender: 'Assistant',
isCreatedByUser: false,
content: [
{ type: 'text', text: 'working on it' },
{ type: 'steer', steer: 'use this', steerId: 's-1', files: [{ file_id: 'f-1' }] },
],
},
{
user,
conversationId: textOnly.conversationId,
messageId: uuidv4(),
sender: 'Assistant',
isCreatedByUser: false,
content: [{ type: 'steer', steer: 'no file', steerId: 's-2', files: [] }],
},
]);
const result = await getConvosByCursor(user, { hasFiles: true });
expect(result.conversations.map((c) => c.conversationId)).toEqual([steered.conversationId]);
});
it.each([
['a provider-native file part', { type: 'file', file: { file_id: 'f-native' } }],
['an image_file part', { type: 'image_file', image_file: { file_id: 'f-image' } }],
['a part carrying a bare file_id', { type: 'file', file_id: 'f-bare' }],
])('reads files attached as %s', async (_label, part) => {
const Message = mongoose.models.Message as mongoose.Model<{
user: string;
conversationId: string;
messageId: string;
content: unknown[];
}>;
const attached = await makeConvo({ title: 'attached' });
await makeConvo({ title: 'text only' });
await Message.create({
user,
conversationId: attached.conversationId,
messageId: uuidv4(),
sender: 'User',
isCreatedByUser: true,
content: [{ type: 'text', text: 'see this' }, part],
});
const result = await getConvosByCursor(user, { hasFiles: true });
expect(result.conversations.map((c) => c.conversationId)).toEqual([attached.conversationId]);
});
it('reads files a tool or assistant attached to its response', async () => {
const Message = mongoose.models.Message as mongoose.Model<{
user: string;
conversationId: string;
messageId: string;
attachments: unknown[];
}>;
const generated = await makeConvo({ title: 'generated file' });
const downloadOnly = await makeConvo({ title: 'download-only file' });
const searched = await makeConvo({ title: 'search results only' });
await Message.create([
{
user,
conversationId: generated.conversationId,
messageId: uuidv4(),
sender: 'Assistant',
isCreatedByUser: false,
attachments: [{ file_id: 'f-out', filename: 'plot.png', toolCallId: 't-1' }],
},
{
user,
conversationId: downloadOnly.conversationId,
messageId: uuidv4(),
sender: 'Assistant',
isCreatedByUser: false,
attachments: [
{ filename: 'report.csv', filepath: '/api/files/code/download/s/report.csv' },
],
},
{
user,
conversationId: searched.conversationId,
messageId: uuidv4(),
sender: 'Assistant',
isCreatedByUser: false,
attachments: [
{ type: 'web_search', toolCallId: 't-2' },
{ filename: 'blank.txt', filepath: '' },
],
},
]);
const result = await getConvosByCursor(user, { hasFiles: true });
expect(result.conversations.map((c) => c.conversationId).sort()).toEqual(
[generated.conversationId, downloadOnly.conversationId].sort(),
);
});
it('combines facets rather than widening the result', async () => {
const match = await makeConvo({
title: 'match',
endpoint: EModelEndpoint.openAI,
files: ['file-1'],
updatedAt: new Date(),
});
await makeConvo({ title: 'wrong endpoint', endpoint: EModelEndpoint.google, files: ['f'] });
await makeConvo({ title: 'no files', endpoint: EModelEndpoint.openAI });
await makeConvo({
title: 'too old',
endpoint: EModelEndpoint.openAI,
files: ['f'],
updatedAt: new Date(Date.now() - 30 * day),
});
const result = await getConvosByCursor(user, {
endpoints: [EModelEndpoint.openAI],
hasFiles: true,
updatedAfter: new Date(Date.now() - 7 * day),
});
expect(result.conversations.map((c) => c.conversationId)).toEqual([match.conversationId]);
});
it('carries the facets across a paged cursor', async () => {
const wanted = [] as string[];
for (let index = 0; index < 3; index++) {
const convo = await makeConvo({
title: `wanted ${index}`,
endpoint: EModelEndpoint.openAI,
updatedAt: new Date(Date.now() - index * 1000),
});
wanted.push(convo.conversationId);
}
for (let index = 0; index < 3; index++) {
await makeConvo({ title: `other ${index}`, endpoint: EModelEndpoint.google });
}
const first = await getConvosByCursor(user, {
endpoints: [EModelEndpoint.openAI],
limit: 2,
});
expect(first.conversations).toHaveLength(2);
expect(first.nextCursor).not.toBeNull();
const second = await getConvosByCursor(user, {
endpoints: [EModelEndpoint.openAI],
limit: 2,
cursor: first.nextCursor,
});
const paged = [...first.conversations, ...second.conversations].map((c) => c.conversationId);
/** The second page must not reintroduce the rows the filter excluded. */
expect(paged.sort()).toEqual(wanted.sort());
});
it('keeps only conversations with an active shared link', async () => {
const SharedLink = mongoose.models.SharedLink as mongoose.Model<{
conversationId: string;
user: string;
shareId: string;
expiredAt?: Date | null;
}>;
const shared = await makeConvo({ title: 'shared' });
await makeConvo({ title: 'not shared' });
const expired = await makeConvo({ title: 'share expired' });
await SharedLink.create([
{ conversationId: shared.conversationId, user, shareId: `share-${uuidv4()}` },
{
conversationId: expired.conversationId,
user,
shareId: `share-${uuidv4()}`,
expiredAt: new Date('2020-01-01T00:00:00.000Z'),
},
]);
const result = await getConvosByCursor(user, { sharedOnly: true });
/** A lapsed link is not a shared chat, which is why this reads the links rather
* than a flag stored on the conversation. */
expect(result.conversations.map((c) => c.conversationId)).toEqual([shared.conversationId]);
/** The filter already resolved the share set, so the row carries its flag from
* that answer rather than waiting on a second lookup. */
expect(result.conversations[0].isShared).toBe(true);
await SharedLink.deleteMany({ user });
});
it('returns nothing when the user shares nothing', async () => {
await makeConvo({ title: 'present' });
const result = await getConvosByCursor(user, { sharedOnly: true });
/** An empty `$in` would match every document, so this must short-circuit. */
expect(result.conversations).toEqual([]);
expect(result.nextCursor).toBeNull();
});
it('returns nothing when the deployment has sharing switched off', async () => {
const SharedLink = mongoose.models.SharedLink as mongoose.Model<{
conversationId: string;
user: string;
shareId: string;
}>;
const shared = await makeConvo({ title: 'shared' });
await SharedLink.create({
conversationId: shared.conversationId,
user,
shareId: `share-${uuidv4()}`,
});
const previous = process.env.ALLOW_SHARED_LINKS;
process.env.ALLOW_SHARED_LINKS = 'false';
try {
const result = await getConvosByCursor(user, { sharedOnly: true });
expect(result.conversations).toEqual([]);
} finally {
if (previous === undefined) {
delete process.env.ALLOW_SHARED_LINKS;
} else {
process.env.ALLOW_SHARED_LINKS = previous;
}
await SharedLink.deleteMany({ user });
}
});
it('narrows shared chats further with another facet', async () => {
const SharedLink = mongoose.models.SharedLink as mongoose.Model<{
conversationId: string;
user: string;
shareId: string;
}>;
const match = await makeConvo({ title: 'shared openai', endpoint: EModelEndpoint.openAI });
const wrongEndpoint = await makeConvo({
title: 'shared google',
endpoint: EModelEndpoint.google,
});
await SharedLink.create([
{ conversationId: match.conversationId, user, shareId: `share-${uuidv4()}` },
{ conversationId: wrongEndpoint.conversationId, user, shareId: `share-${uuidv4()}` },
]);
const result = await getConvosByCursor(user, {
sharedOnly: true,
endpoints: [EModelEndpoint.openAI],
});
expect(result.conversations.map((c) => c.conversationId)).toEqual([match.conversationId]);
await SharedLink.deleteMany({ user });
});
it('ignores an invalid date rather than filtering on NaN', async () => {
const convo = await makeConvo({ title: 'present' });
const result = await getConvosByCursor(user, {
updatedAfter: new Date('not a date'),
});
expect(result.conversations.map((c) => c.conversationId)).toEqual([convo.conversationId]);
});
});
describe('addConvoToolApprovalAllows', () => {
const seed = async (user = 'allow-user') => {
const conversationId = uuidv4();
await Conversation.create({ conversationId, user, title: 'Allow test', endpoint: 'agents' });
return conversationId;
};
it('stores tools owner-scoped and idempotently', async () => {
const conversationId = await seed();
const input = { conversationId, toolNames: ['search_mcp_github'], max: 64 };
expect(await methods.addConvoToolApprovalAllows({ ...input, user: 'intruder' })).toBe(false);
expect(await methods.addConvoToolApprovalAllows({ ...input, user: 'allow-user' })).toBe(true);
expect(await methods.addConvoToolApprovalAllows({ ...input, user: 'allow-user' })).toBe(true);
const stored = await Conversation.findOne({ conversationId }).lean();
expect(stored?.toolApprovalAllows).toEqual(['search_mcp_github']);
});
it('refuses a write that would exceed the bound', async () => {
const conversationId = await seed();
const user = 'allow-user';
expect(
await methods.addConvoToolApprovalAllows({
user,
conversationId,
toolNames: ['a', 'b'],
max: 2,
}),
).toBe(true);
expect(
await methods.addConvoToolApprovalAllows({
user,
conversationId,
toolNames: ['c'],
max: 2,
}),
).toBe(false);
const stored = await Conversation.findOne({ conversationId }).lean();
expect(stored?.toolApprovalAllows).toEqual(['a', 'b']);
});
it('charges only names not stored yet against the bound', async () => {
const conversationId = await seed();
const write = (toolNames: string[]) =>
methods.addConvoToolApprovalAllows({
user: 'allow-user',
conversationId,
toolNames,
max: 2,
});
expect(await write(['a'])).toBe(true);
expect(await write(['a', 'b'])).toBe(true);
expect(await write(['b'])).toBe(true);
expect(await write(['a', 'c'])).toBe(false);
const stored = await Conversation.findOne({ conversationId }).lean();
expect(stored?.toolApprovalAllows).toEqual(['a', 'b']);
});
it('cannot be written or cleared through generic saves or bulk imports', async () => {
const conversationId = await seed();
const user = 'allow-user';
await methods.addConvoToolApprovalAllows({
user,
conversationId,
toolNames: ['kept'],
max: 64,
});
await saveConvo(
{ userId: user },
{ conversationId, toolApprovalAllows: ['*'] },
{ unsetFields: { toolApprovalAllows: 1 } },
);
const imported = uuidv4();
await methods.bulkSaveConvos([
{ conversationId: imported, user, title: 'Imported', toolApprovalAllows: ['*'] },
]);
const stored = await Conversation.findOne({ conversationId }).lean();
expect(stored?.toolApprovalAllows).toEqual(['kept']);
const importedDoc = await Conversation.findOne({ conversationId: imported }).lean();
expect(importedDoc?.toolApprovalAllows).toBeUndefined();
});
});
});
describe('laneGit', () => {
const seed = async (user = 'lane-user') => {
const conversationId = uuidv4();
await Conversation.create({ conversationId, user, title: 'Lane test', endpoint: 'agents' });
return conversationId;
};
const head = 'a'.repeat(40);
/** A write with a sequence number drawn from the database, as the recorder draws one. */
const record = async (
input: Omit<Parameters<typeof methods.setConvoLaneGit>[0], 'seq'> & { seq?: number },
) => {
const seq =
input.seq ?? (await methods.reserveConvoLaneGitSeq(input.user, input.conversationId));
if (seq == null) return false;
return methods.setConvoLaneGit({ ...input, seq });
};
it('stores the reported branch and head for the owner and reads them back', async () => {
const conversationId = await seed();
const laneGit = { branch: 'feat/pr-chip', head };
await expect(record({ user: 'lane-user', conversationId, laneGit })).resolves.toBe(true);
await expect(methods.getConvoLaneGit('lane-user', conversationId)).resolves.toEqual(laneGit);
});
describe('linked pull request', () => {
const user = 'lane-user';
const lane = { branch: 'feat/x', head };
const read = (conversationId: string) => methods.getConvoLaneGit(user, conversationId);
it('stores the link and keeps it through later reports on the same branch', async () => {
const conversationId = await seed();
await record({ user, conversationId, laneGit: lane, repo: 'o/r', pullRequest: 7 });
const moved = { branch: 'feat/x', head: 'b'.repeat(40) };
await expect(record({ user, conversationId, laneGit: moved, repo: 'o/r' })).resolves.toBe(
true,
);
await expect(read(conversationId)).resolves.toEqual({
...moved,
repo: 'o/r',
pullRequest: 7,
});
});
it('returns the link from the batch read too', async () => {
const conversationId = await seed();
await record({ user, conversationId, laneGit: lane, repo: 'o/r', pullRequest: 7 });
await expect(methods.getConvosLaneGit(user, [conversationId])).resolves.toEqual([
{ conversationId, laneGit: { ...lane, repo: 'o/r', pullRequest: 7 } },
]);
});
it('drops the link when the branch changes', async () => {
const conversationId = await seed();
await record({ user, conversationId, laneGit: lane, repo: 'o/r', pullRequest: 7 });
await record({ user, conversationId, laneGit: { branch: 'dev', head }, repo: 'o/r' });
await expect(read(conversationId)).resolves.not.toHaveProperty('pullRequest');
});
it('drops the link when the repository changes or is no longer known', async () => {
const conversationId = await seed();
await record({ user, conversationId, laneGit: lane, repo: 'o/r', pullRequest: 7 });
await record({ user, conversationId, laneGit: lane, repo: 'o/other' });
await expect(read(conversationId)).resolves.not.toHaveProperty('pullRequest');
await record({ user, conversationId, laneGit: lane, repo: 'o/r', pullRequest: 7 });
await record({ user, conversationId, laneGit: lane });
await expect(read(conversationId)).resolves.not.toHaveProperty('pullRequest');
});
it('treats an empty repository like an unknown one when keeping the link', async () => {
const conversationId = await seed();
await record({ user, conversationId, laneGit: lane, pullRequest: 7 });
await record({ user, conversationId, laneGit: lane, repo: '' });
await expect(read(conversationId)).resolves.toEqual({ ...lane, pullRequest: 7 });
});
it('replaces the link with a newer one', async () => {
const conversationId = await seed();
await record({ user, conversationId, laneGit: lane, repo: 'o/r', pullRequest: 7 });
await record({ user, conversationId, laneGit: lane, repo: 'o/r', pullRequest: 9 });
await expect(read(conversationId)).resolves.toMatchObject({ pullRequest: 9 });
});
it('ignores a link carried by a report with a lower sequence number', async () => {
const conversationId = await seed();
const first = (await methods.reserveConvoLaneGitSeq(user, conversationId)) as number;
const second = (await methods.reserveConvoLaneGitSeq(user, conversationId)) as number;
await record({ user, conversationId, laneGit: lane, repo: 'o/r', seq: second });
await expect(
record({ user, conversationId, laneGit: lane, repo: 'o/r', pullRequest: 7, seq: first }),
).resolves.toBe(false);
await expect(read(conversationId)).resolves.not.toHaveProperty('pullRequest');
});
it('stores a branch or repository that looks like a field path as plain text', async () => {
const conversationId = await seed();
const dollar = { branch: '$laneGit.head', head };
await record({ user, conversationId, laneGit: dollar, repo: 'o/r', pullRequest: 7 });
await record({ user, conversationId, laneGit: dollar, repo: 'o/r' });
await expect(read(conversationId)).resolves.toEqual({
...dollar,
repo: 'o/r',
pullRequest: 7,
});
});
});
it('does not write for another owner or an unknown conversation', async () => {
const conversationId = await seed();
const laneGit = { branch: 'main', head };
await expect(record({ user: 'intruder', conversationId, laneGit })).resolves.toBe(false);
await expect(record({ user: 'lane-user', conversationId: uuidv4(), laneGit })).resolves.toBe(
false,
);
await expect(methods.getConvoLaneGit('lane-user', conversationId)).resolves.toBeNull();
await expect(methods.getConvoLaneGit('intruder', conversationId)).resolves.toBeNull();
});
it('ignores a report with a lower sequence number, so a delayed write cannot win', async () => {
const conversationId = await seed();
const user = 'lane-user';
const first = await methods.reserveConvoLaneGitSeq(user, conversationId);
const second = await methods.reserveConvoLaneGitSeq(user, conversationId);
const newer = { branch: 'newer', head };
const older = { branch: 'older', head: 'b'.repeat(40) };
await expect(
methods.setConvoLaneGit({ user, conversationId, laneGit: newer, seq: second as number }),
).resolves.toBe(true);
await expect(
methods.setConvoLaneGit({ user, conversationId, laneGit: older, seq: first as number }),
).resolves.toBe(false);
await expect(methods.getConvoLaneGit(user, conversationId)).resolves.toEqual(newer);
});
it('issues increasing numbers per conversation and none for an unknown one', async () => {
const conversationId = await seed();
const other = await seed();
expect(await methods.reserveConvoLaneGitSeq('lane-user', conversationId)).toBe(1);
expect(await methods.reserveConvoLaneGitSeq('lane-user', conversationId)).toBe(2);
expect(await methods.reserveConvoLaneGitSeq('lane-user', other)).toBe(1);
expect(await methods.reserveConvoLaneGitSeq('intruder', conversationId)).toBeNull();
expect(await methods.reserveConvoLaneGitSeq('lane-user', uuidv4())).toBeNull();
});
it('issues distinct numbers to reservations made at the same time', async () => {
const conversationId = await seed();
const numbers = await Promise.all(
Array.from({ length: 12 }, () => methods.reserveConvoLaneGitSeq('lane-user', conversationId)),
);
expect(new Set(numbers).size).toBe(12);
expect(Math.min(...(numbers as number[]))).toBe(1);
expect(Math.max(...(numbers as number[]))).toBe(12);
});
it('is not skewed by the clocks of the processes that report', async () => {
const conversationId = await seed();
const user = 'lane-user';
const early = await methods.reserveConvoLaneGitSeq(user, conversationId);
const later = await methods.reserveConvoLaneGitSeq(user, conversationId);
/** An older report from a replica whose clock runs far ahead still carries the lower number. */
await expect(
methods.setConvoLaneGit({
user,
conversationId,
laneGit: { branch: 'later', head },
seq: later as number,
}),
).resolves.toBe(true);
await expect(
methods.setConvoLaneGit({
user,
conversationId,
laneGit: { branch: 'early-but-future-clock', head },
seq: early as number,
}),
).resolves.toBe(false);
await expect(methods.getConvoLaneGit(user, conversationId)).resolves.toEqual({
branch: 'later',
head,
});
});
it('does not expose the sequence number or the counter through the read', async () => {
const conversationId = await seed();
await record({ user: 'lane-user', conversationId, laneGit: { branch: 'main', head } });
const stored = await methods.getConvoLaneGit('lane-user', conversationId);
expect(stored).not.toHaveProperty('seq');
const read = await Conversation.findOne({ conversationId }).lean();
expect(read).not.toHaveProperty('laneGitSeq');
});
it('replaces the stored state when the branch or head changes', async () => {
const conversationId = await seed();
const user = 'lane-user';
await record({ user, conversationId, laneGit: { branch: 'main', head } });
const next = { branch: 'feat/x', head: 'b'.repeat(40) };
await expect(record({ user, conversationId, laneGit: next })).resolves.toBe(true);
await expect(methods.getConvoLaneGit(user, conversationId)).resolves.toEqual(next);
});
it('stores the repository with the lane and replaces it when the repository changes', async () => {
const conversationId = await seed();
const user = 'lane-user';
const laneGit = { branch: 'main', head };
await expect(record({ user, conversationId, laneGit, repo: 'o/r' })).resolves.toBe(true);
await expect(methods.getConvoLaneGit(user, conversationId)).resolves.toEqual({
...laneGit,
repo: 'o/r',
});
await expect(record({ user, conversationId, laneGit, repo: 'o/other' })).resolves.toBe(true);
await expect(methods.getConvoLaneGit(user, conversationId)).resolves.toEqual({
...laneGit,
repo: 'o/other',
});
});
describe('workspace fence', () => {
const mac = { environmentId: 'code-mac', workspaceId: 'primary' };
const team = { environmentId: 'code-team', workspaceId: 'shared' };
const seedRaw = async (decision: Record<string, unknown>) => {
const conversationId = uuidv4();
await Conversation.collection.insertOne({
conversationId,
user: 'lane-user',
title: 'Fence',
endpoint: 'agents',
messages: [],
...decision,
});
return conversationId;
};
const write = (conversationId: string, workspace: Record<string, unknown>) =>
record({
user: 'lane-user',
conversationId,
laneGit: { branch: 'feat/x', head },
workspace: workspace as never,
});
it('records for the workspace the conversation is attached to', async () => {
const conversationId = await seedRaw({
codeEnvironmentMode: 'attached',
codeWorkspaces: [mac],
});
await expect(write(conversationId, mac)).resolves.toBe(true);
});
it('refuses a report from a workspace the conversation moved away from', async () => {
const conversationId = await seedRaw({
codeEnvironmentMode: 'attached',
codeWorkspaces: [team],
});
await expect(write(conversationId, mac)).resolves.toBe(false);
await expect(methods.getConvoLaneGit('lane-user', conversationId)).resolves.toBeNull();
});
it('refuses a report once the conversation has left attached execution', async () => {
const conversationId = await seedRaw({ codeEnvironmentMode: 'without_attached' });
await expect(write(conversationId, mac)).resolves.toBe(false);
});
it('does not let a write queued before a move repopulate the cleared lane', async () => {
const conversationId = await seedRaw({
codeEnvironmentMode: 'attached',
codeWorkspaces: [mac],
laneGit: { branch: 'old', head, repo: 'o/old', seq: 1 },
});
const stored = await methods.getConvoCodeEnvironmentDecision('lane-user', conversationId);
await methods.replaceConvoCodeEnvironmentDecision({
user: 'lane-user',
conversationId,
expected: {
codeEnvironmentMode: stored?.codeEnvironmentMode,
codeWorkspaces: stored?.codeWorkspaces,
codeEnvironmentRevision: stored?.codeEnvironmentRevision,
},
codeEnvironmentMode: 'attached',
codeWorkspaces: [team],
});
await expect(write(conversationId, mac)).resolves.toBe(false);
await expect(methods.getConvoLaneGit('lane-user', conversationId)).resolves.toBeNull();
});
it('records when no workspace is stored yet, as for an agent default workspace', async () => {
const conversationId = await seedRaw({});
await expect(write(conversationId, mac)).resolves.toBe(true);
});
it('refuses an unrecorded workspace when the caller requires a recorded one', async () => {
const conversationId = await seedRaw({});
await expect(write(conversationId, { ...mac, required: true })).resolves.toBe(false);
});
it('accepts a required workspace that matches the recorded one', async () => {
const conversationId = await seedRaw({
codeEnvironmentMode: 'attached',
codeWorkspaces: [mac, team],
});
await expect(write(conversationId, { ...team, required: true })).resolves.toBe(true);
});
});
describe('retention', () => {
const lane = { branch: 'feat/x', head, seq: 1 };
const seedExpiry = async (expiredAt: Date | null) => {
const conversationId = uuidv4();
await Conversation.collection.insertOne({
conversationId,
user: 'lane-user',
title: 'Retention',
endpoint: 'agents',
messages: [],
laneGit: lane,
laneGitSeq: 1,
expiredAt,
});
return conversationId;
};
const past = () => new Date(Date.now() - 60_000);
const future = () => new Date(Date.now() + 3_600_000);
it('does not serve the lane of an expired temporary chat', async () => {
const conversationId = await seedExpiry(past());
await expect(methods.getConvoLaneGit('lane-user', conversationId)).resolves.toBeNull();
});
it('does not reserve a number for, or write to, an expired temporary chat', async () => {
const conversationId = await seedExpiry(past());
await expect(methods.reserveConvoLaneGitSeq('lane-user', conversationId)).resolves.toBeNull();
await expect(
methods.setConvoLaneGit({
user: 'lane-user',
conversationId,
laneGit: { branch: 'later', head },
seq: 99,
}),
).resolves.toBe(false);
});
it.each([
['no expiry', null],
['an expiry in the future', future()],
])('still serves, reserves for and writes to a chat with %s', async (_label, expiredAt) => {
const conversationId = await seedExpiry(expiredAt);
await expect(methods.getConvoLaneGit('lane-user', conversationId)).resolves.toMatchObject({
branch: 'feat/x',
});
const seq = await methods.reserveConvoLaneGitSeq('lane-user', conversationId);
expect(seq).toBe(2);
await expect(
methods.setConvoLaneGit({
user: 'lane-user',
conversationId,
laneGit: { branch: 'later', head },
seq: seq as number,
}),
).resolves.toBe(true);
});
});
it('keeps a detached or empty lane distinct from an unknown one', async () => {
const conversationId = await seed();
const laneGit = { branch: null, head: null };
await expect(record({ user: 'lane-user', conversationId, laneGit })).resolves.toBe(true);
await expect(methods.getConvoLaneGit('lane-user', conversationId)).resolves.toEqual(laneGit);
});
describe('server-written only', () => {
const kept = { branch: 'kept', head };
const seedWithLane = async () => {
const conversationId = await seed();
await record({ user: 'lane-user', conversationId, laneGit: kept });
return conversationId;
};
it('is not overwritten by a generic save', async () => {
const conversationId = await seedWithLane();
await saveConvo(
{ userId: 'lane-user' },
{ conversationId, laneGit: { branch: 'forged', head: null } },
);
await expect(methods.getConvoLaneGit('lane-user', conversationId)).resolves.toEqual(kept);
});
it('is not cleared by a generic save', async () => {
const conversationId = await seedWithLane();
await saveConvo({ userId: 'lane-user' }, { conversationId }, { unsetFields: { laneGit: 1 } });
await expect(methods.getConvoLaneGit('lane-user', conversationId)).resolves.toEqual(kept);
});
it('is not accepted from a bulk import', async () => {
const imported = uuidv4();
await methods.bulkSaveConvos([
{
conversationId: imported,
user: 'lane-user',
title: 'Imported',
laneGit: { branch: 'x', head: null },
},
]);
await expect(methods.getConvoLaneGit('lane-user', imported)).resolves.toBeNull();
});
it('keeps the sequence counter out of generic saves, unset fields and imports', async () => {
const conversationId = await seedWithLane();
const before = await methods.reserveConvoLaneGitSeq('lane-user', conversationId);
await saveConvo({ userId: 'lane-user' }, { conversationId, laneGitSeq: 0 });
await saveConvo(
{ userId: 'lane-user' },
{ conversationId },
{ unsetFields: { laneGitSeq: 1 } },
);
const imported = uuidv4();
await methods.bulkSaveConvos([
{ conversationId: imported, user: 'lane-user', title: 'Imported', laneGitSeq: 99 },
]);
expect(await methods.reserveConvoLaneGitSeq('lane-user', conversationId)).toBe(
(before as number) + 1,
);
expect(await methods.reserveConvoLaneGitSeq('lane-user', imported)).toBe(1);
});
it('is excluded from ordinary conversation reads', async () => {
const conversationId = await seedWithLane();
const read = await Conversation.findOne({ conversationId }).lean();
expect(read).not.toHaveProperty('laneGit');
});
});
});
describe('stampForcedRetention', () => {
const ephemeral = { retentionMode: RetentionMode.EPHEMERAL, temporaryChatRetention: 1 };
let userId: string;
let conversationId: string;
let messageId: string;
const MessageModel = () => mongoose.models.Message as mongoose.Model<IMessage>;
beforeEach(async () => {
userId = `stamp-${uuidv4()}`;
conversationId = uuidv4();
messageId = `message-${uuidv4()}`;
await Conversation.create({
conversationId,
user: userId,
title: 'Permanent',
endpoint: EModelEndpoint.openAI,
isTemporary: false,
tags: ['work'],
messages: [],
});
await MessageModel().create({
messageId,
conversationId,
user: userId,
text: 'hello',
isCreatedByUser: true,
isTemporary: false,
});
await ConversationTag.create({ user: userId, tag: 'work', count: 1, position: 0 });
});
it('converts the conversation and the named message and releases its bookmark count', async () => {
await methods.stampForcedRetention(
{ userId, interfaceConfig: ephemeral },
{ conversationId, messageIds: [messageId] },
);
const convo = await Conversation.findOne({ conversationId }).lean();
const message = await MessageModel().findOne({ messageId }).lean();
expect(convo?.isTemporary).toBe(true);
expect(convo?.expiredAt).toBeInstanceOf(Date);
expect(message?.isTemporary).toBe(true);
expect(message?.expiredAt).toEqual(convo?.expiredAt);
expect((await ConversationTag.findOne({ user: userId, tag: 'work' }).lean())?.count).toBe(0);
});
it('keeps the stored deadline instead of opening a new window', async () => {
const deadline = new Date(Date.now() + 5 * 60 * 1000);
await Conversation.updateOne({ conversationId }, { isTemporary: true, expiredAt: deadline });
await methods.stampForcedRetention(
{ userId, interfaceConfig: ephemeral },
{ conversationId, messageIds: [messageId] },
);
const convo = await Conversation.findOne({ conversationId }).lean();
const message = await MessageModel().findOne({ messageId }).lean();
expect(convo?.expiredAt).toEqual(deadline);
expect(message?.expiredAt).toEqual(deadline);
});
it('releases the bookmark count only once across repeated stamps', async () => {
const stamp = () =>
methods.stampForcedRetention({ userId, interfaceConfig: ephemeral }, { conversationId });
await Promise.all([stamp(), stamp(), stamp()]);
expect((await ConversationTag.findOne({ user: userId, tag: 'work' }).lean())?.count).toBe(0);
});
it('gives a stamped message the deadline a concurrent stamp stored first', async () => {
const winningDeadline = new Date(Date.now() + 24 * 60 * 60 * 1000);
const originalUpdateOne = Conversation.updateOne.bind(Conversation);
const updateOne = jest
.spyOn(Conversation, 'updateOne')
.mockImplementationOnce(((filter, update, options) =>
originalUpdateOne(
{ conversationId },
{ $set: { isTemporary: true, expiredAt: winningDeadline, tags: [] } },
{ timestamps: false },
).then(() => originalUpdateOne(filter, update, options))) as typeof Conversation.updateOne);
try {
await methods.stampForcedRetention(
{ userId, interfaceConfig: ephemeral },
{ conversationId, messageIds: [messageId] },
);
} finally {
updateOne.mockRestore();
}
const convo = await Conversation.findOne({ conversationId }).lean();
const message = await MessageModel().findOne({ messageId }).lean();
expect(convo?.expiredAt).toEqual(winningDeadline);
expect(message?.expiredAt).toEqual(winningDeadline);
});
it('does not release the bookmark count again when the converted chat is deleted', async () => {
await Conversation.create({
conversationId: uuidv4(),
user: userId,
endpoint: EModelEndpoint.openAI,
tags: ['work'],
});
await ConversationTag.updateOne({ user: userId, tag: 'work' }, { count: 2 });
await methods.stampForcedRetention({ userId, interfaceConfig: ephemeral }, { conversationId });
await methods.deleteConvos(userId, { conversationId });
expect((await ConversationTag.findOne({ user: userId, tag: 'work' }).lean())?.count).toBe(1);
});
it('never recreates a conversation or message that is gone', async () => {
await Conversation.deleteOne({ conversationId });
await MessageModel().deleteOne({ messageId });
await methods.stampForcedRetention(
{ userId, interfaceConfig: ephemeral },
{ conversationId, messageIds: [messageId] },
);
expect(await Conversation.countDocuments({ conversationId })).toBe(0);
expect(await MessageModel().countDocuments({ messageId })).toBe(0);
});
it('leaves the message list untouched', async () => {
const messageRef = new mongoose.Types.ObjectId();
await Conversation.updateOne({ conversationId }, { messages: [messageRef] });
await methods.stampForcedRetention({ userId, interfaceConfig: ephemeral }, { conversationId });
const convo = await Conversation.findOne({ conversationId }).lean();
expect(convo?.messages?.map(String)).toEqual([String(messageRef)]);
});
it.each([RetentionMode.TEMPORARY, RetentionMode.ALL, undefined])(
'writes nothing under retentionMode %s',
async (retentionMode) => {
await methods.stampForcedRetention(
{ userId, interfaceConfig: retentionMode == null ? undefined : { retentionMode } },
{ conversationId, messageIds: [messageId] },
);
const convo = await Conversation.findOne({ conversationId }).lean();
expect(convo?.isTemporary).toBe(false);
expect(convo?.expiredAt ?? null).toBeNull();
expect((await ConversationTag.findOne({ user: userId, tag: 'work' }).lean())?.count).toBe(1);
},
);
});
describe('laneGit review hardening', () => {
const head = 'a'.repeat(40);
const mac = { environmentId: 'code-mac', workspaceId: 'primary' };
const team = { environmentId: 'code-team', workspaceId: 'shared' };
const seedAttached = async (
workspaces: Array<{ environmentId: string; workspaceId: string }>,
) => {
const conversationId = uuidv4();
await Conversation.collection.insertOne({
conversationId,
user: 'lane-user',
title: 'Hardening',
endpoint: 'agents',
messages: [],
codeEnvironmentMode: 'attached',
codeWorkspaces: workspaces,
});
return conversationId;
};
const move = async (
conversationId: string,
codeWorkspaces: Array<{ environmentId: string; workspaceId: string }>,
) => {
const stored = await methods.getConvoCodeEnvironmentDecision('lane-user', conversationId);
return methods.replaceConvoCodeEnvironmentDecision({
user: 'lane-user',
conversationId,
expected: {
codeEnvironmentMode: stored?.codeEnvironmentMode,
codeWorkspaces: stored?.codeWorkspaces,
codeEnvironmentRevision: stored?.codeEnvironmentRevision,
},
codeEnvironmentMode: 'attached',
codeWorkspaces: codeWorkspaces as never,
});
};
describe('dotted import and save keys', () => {
it('does not let an import set a lane through dotted keys', async () => {
const imported = uuidv4();
await methods.bulkSaveConvos([
{
conversationId: imported,
user: 'lane-user',
title: 'Imported',
'laneGit.branch': 'forged',
'laneGit.repo': 'o/forged',
'laneGit.seq': 999,
'laneGitSeq.x': 1,
'codeAttachmentEpoch.x': 5,
},
]);
await expect(methods.getConvoLaneGit('lane-user', imported)).resolves.toBeNull();
const raw = await Conversation.collection.findOne({ conversationId: imported });
expect(raw).not.toHaveProperty('laneGit');
expect(raw).not.toHaveProperty('codeAttachmentEpoch');
expect(await methods.reserveConvoLaneGitSeq('lane-user', imported)).toBe(1);
});
it('does not let a save set a lane through dotted keys or unset keys', async () => {
const conversationId = uuidv4();
await Conversation.create({ conversationId, user: 'lane-user', endpoint: 'agents' });
const seq = (await methods.reserveConvoLaneGitSeq('lane-user', conversationId)) as number;
await methods.setConvoLaneGit({
user: 'lane-user',
conversationId,
laneGit: { branch: 'kept', head },
seq,
});
await saveConvo(
{ userId: 'lane-user' },
{ conversationId, 'laneGit.branch': 'forged', 'laneGit.seq': 999 },
{ unsetFields: { 'laneGit.repo': 1, 'laneGit.head': 1 } },
);
await expect(methods.getConvoLaneGit('lane-user', conversationId)).resolves.toEqual({
branch: 'kept',
head,
});
expect(await methods.reserveConvoLaneGitSeq('lane-user', conversationId)).toBe(seq + 1);
});
});
describe('attachment epoch', () => {
const write = (
conversationId: string,
epoch: number | undefined,
workspace: { environmentId: string; workspaceId: string },
) =>
methods.reserveConvoLaneGitSeq('lane-user', conversationId).then((seq) =>
methods.setConvoLaneGit({
user: 'lane-user',
conversationId,
laneGit: { branch: 'feat/x', head },
seq: seq as number,
workspace: { ...workspace, ...(epoch == null ? {} : { epoch }) },
}),
);
it('reads as zero until the conversation is moved, then advances on every move', async () => {
const conversationId = await seedAttached([mac]);
expect(
(await methods.getConvoLaneContext('lane-user', conversationId))?.codeAttachmentEpoch ?? 0,
).toBe(0);
await move(conversationId, [team]);
expect(
(await methods.getConvoLaneContext('lane-user', conversationId))?.codeAttachmentEpoch,
).toBe(1);
await move(conversationId, [mac]);
expect(
(await methods.getConvoLaneContext('lane-user', conversationId))?.codeAttachmentEpoch,
).toBe(2);
});
it('applies a report from the epoch it was captured in', async () => {
const conversationId = await seedAttached([mac]);
await expect(write(conversationId, 0, mac)).resolves.toBe(true);
});
it('refuses a report from before a move away and back to the same workspace', async () => {
const conversationId = await seedAttached([mac]);
await move(conversationId, [team]);
await move(conversationId, [mac]);
await expect(write(conversationId, 0, mac)).resolves.toBe(false);
await expect(methods.getConvoLaneGit('lane-user', conversationId)).resolves.toBeNull();
await expect(write(conversationId, 2, mac)).resolves.toBe(true);
});
it('returns the epoch with the admitted decision, from the same document read', async () => {
const conversationId = await seedAttached([mac]);
await expect(
methods.readAdmittedConvoCodeEnvironmentDecision('lane-user', conversationId),
).resolves.toMatchObject({ codeWorkspaces: [mac], codeAttachmentEpoch: 0 });
await move(conversationId, [team]);
await expect(
methods.readAdmittedConvoCodeEnvironmentDecision('lane-user', conversationId),
).resolves.toMatchObject({ codeWorkspaces: [team], codeAttachmentEpoch: 1 });
await move(conversationId, [mac]);
const admitted = await methods.readAdmittedConvoCodeEnvironmentDecision(
'lane-user',
conversationId,
);
expect(admitted).toMatchObject({ codeWorkspaces: [mac], codeAttachmentEpoch: 2 });
});
it('is not advanced by admitting a generation', async () => {
const conversationId = await seedAttached([mac]);
await methods.readAdmittedConvoCodeEnvironmentDecision('lane-user', conversationId);
await methods.readAdmittedConvoCodeEnvironmentDecision('lane-user', conversationId);
await expect(write(conversationId, 0, mac)).resolves.toBe(true);
});
it('keeps the epoch out of generic saves, unset fields and ordinary reads', async () => {
const conversationId = await seedAttached([mac]);
await move(conversationId, [team]);
await saveConvo(
{ userId: 'lane-user' },
{ conversationId, codeAttachmentEpoch: 0 },
{ unsetFields: { codeAttachmentEpoch: 1 } },
);
expect(
(await methods.getConvoLaneContext('lane-user', conversationId))?.codeAttachmentEpoch,
).toBe(1);
const read = await Conversation.findOne({ conversationId }).lean();
expect(read).not.toHaveProperty('codeAttachmentEpoch');
});
});
describe('subagent thread epoch', () => {
const seedThread = async (rootId: string) => {
const conversationId = uuidv4();
await Conversation.collection.insertOne({
conversationId,
user: 'lane-user',
title: 'Thread',
endpoint: 'agents',
messages: [],
subagentThread: { rootConversationId: rootId, parentConversationId: rootId },
});
return conversationId;
};
it("reads the epoch of the visible root the report is written to, not the thread's own", async () => {
const rootId = await seedAttached([mac]);
await move(rootId, [team]);
const threadId = await seedThread(rootId);
await expect(methods.getConvoLaneContext('lane-user', threadId)).resolves.toMatchObject({
codeAttachmentEpoch: 1,
subagentThread: { rootConversationId: rootId },
});
});
it("does not read another user's conversation as the root", async () => {
const rootId = uuidv4();
await Conversation.collection.insertOne({
conversationId: rootId,
user: 'someone-else',
title: 'Not yours',
endpoint: 'agents',
messages: [],
codeAttachmentEpoch: 9,
});
const threadId = await seedThread(rootId);
await expect(methods.getConvoLaneContext('lane-user', threadId)).resolves.toMatchObject({
codeAttachmentEpoch: 0,
});
});
it('does not read an expired root, which the write path treats as gone', async () => {
const rootId = await seedAttached([mac]);
await move(rootId, [team]);
await Conversation.collection.updateOne(
{ conversationId: rootId },
{ $set: { expiredAt: new Date(Date.now() - 60_000) } },
);
const threadId = await seedThread(rootId);
await expect(methods.getConvoLaneContext('lane-user', threadId)).resolves.toMatchObject({
codeAttachmentEpoch: 0,
});
});
it("does not read another tenant's conversation as the root", async () => {
const rootId = uuidv4();
await Conversation.collection.insertOne({
conversationId: rootId,
user: 'lane-user',
title: 'Other tenant',
endpoint: 'agents',
messages: [],
codeAttachmentEpoch: 7,
tenantId: 'tenant-b',
});
const threadId = uuidv4();
await Conversation.collection.insertOne({
conversationId: threadId,
user: 'lane-user',
title: 'Thread',
endpoint: 'agents',
messages: [],
tenantId: 'tenant-a',
subagentThread: { rootConversationId: rootId, parentConversationId: rootId },
});
const context = await tenantStorage.run({ tenantId: 'tenant-a' }, () =>
methods.getConvoLaneContext('lane-user', threadId),
);
expect(context).toMatchObject({ codeAttachmentEpoch: 0 });
});
it('reads a root in the same tenant', async () => {
const rootId = uuidv4();
await Conversation.collection.insertOne({
conversationId: rootId,
user: 'lane-user',
title: 'Same tenant',
endpoint: 'agents',
messages: [],
codeAttachmentEpoch: 4,
tenantId: 'tenant-a',
});
const threadId = uuidv4();
await Conversation.collection.insertOne({
conversationId: threadId,
user: 'lane-user',
title: 'Thread',
endpoint: 'agents',
messages: [],
tenantId: 'tenant-a',
subagentThread: { rootConversationId: rootId, parentConversationId: rootId },
});
const context = await tenantStorage.run({ tenantId: 'tenant-a' }, () =>
methods.getConvoLaneContext('lane-user', threadId),
);
expect(context).toMatchObject({ codeAttachmentEpoch: 4 });
});
it('reads the thread and its root in one database operation', async () => {
const rootId = await seedAttached([mac]);
const threadId = await seedThread(rootId);
const spy = jest.spyOn(Conversation, 'findOne');
const aggregate = jest.spyOn(Conversation, 'aggregate');
await methods.getConvoLaneContext('lane-user', threadId);
expect(spy).not.toHaveBeenCalled();
expect(aggregate).toHaveBeenCalledTimes(1);
spy.mockRestore();
aggregate.mockRestore();
});
it('reads zero when the root is gone, so the write is refused rather than guessed', async () => {
const threadId = await seedThread(uuidv4());
await expect(methods.getConvoLaneContext('lane-user', threadId)).resolves.toMatchObject({
codeAttachmentEpoch: 0,
});
});
});
describe('lane context', () => {
it('returns the subagent route and the epoch in one read, owner-scoped', async () => {
const conversationId = await seedAttached([mac]);
await move(conversationId, [team]);
await expect(methods.getConvoLaneContext('lane-user', conversationId)).resolves.toMatchObject(
{
codeAttachmentEpoch: 1,
},
);
await expect(methods.getConvoLaneContext('intruder', conversationId)).resolves.toBeNull();
});
});
});
describe('getConvosLaneGit', () => {
const head = 'a'.repeat(40);
const seedLane = async (
user: string,
laneGit?: Record<string, unknown>,
extra: Record<string, unknown> = {},
) => {
const conversationId = uuidv4();
await Conversation.collection.insertOne({
conversationId,
user,
title: 'Lane',
endpoint: 'agents',
messages: [],
...(laneGit ? { laneGit: { seq: 3, ...laneGit } } : {}),
...extra,
});
return conversationId;
};
it("returns the lanes of the owner's conversations in one query, without the sequence number", async () => {
const a = await seedLane('bulk-user', { branch: 'feat/a', head, repo: 'o/r' });
const b = await seedLane('bulk-user', { branch: 'feat/b', head: null });
const found = await methods.getConvosLaneGit('bulk-user', [a, b]);
expect(found).toHaveLength(2);
expect(found).toEqual(
expect.arrayContaining([
{ conversationId: a, laneGit: { branch: 'feat/a', head, repo: 'o/r' } },
{ conversationId: b, laneGit: { branch: 'feat/b', head: null } },
]),
);
expect(JSON.stringify(found)).not.toContain('seq');
});
it("leaves out a conversation with no lane, an unknown id and another owner's conversation alike", async () => {
const mine = await seedLane('bulk-user', { branch: 'feat/a', head });
const noLane = await seedLane('bulk-user');
const theirs = await seedLane('someone-else', { branch: 'secret', head });
const found = await methods.getConvosLaneGit('bulk-user', [mine, noLane, theirs, uuidv4()]);
expect(found.map((row) => row.conversationId)).toEqual([mine]);
});
it('leaves out an expired temporary chat', async () => {
const expired = await seedLane(
'bulk-user',
{ branch: 'feat/x', head },
{ expiredAt: new Date(Date.now() - 60_000) },
);
const live = await seedLane(
'bulk-user',
{ branch: 'feat/y', head },
{ expiredAt: new Date(Date.now() + 3_600_000) },
);
const found = await methods.getConvosLaneGit('bulk-user', [expired, live]);
expect(found.map((row) => row.conversationId)).toEqual([live]);
});
it('asks nothing for an empty list', async () => {
await expect(methods.getConvosLaneGit('bulk-user', [])).resolves.toEqual([]);
});
});