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 mongoose from 'mongoose';
import { v4 as uuidv4 } from 'uuid';
import { MongoMemoryServer } from 'mongodb-memory-server';
import {
backgroundResultMetadata,
Constants,
RetentionMode,
Tools,
MCP_APP_MIME_TYPE,
} from 'librechat-data-provider';
import type { AppConfig, IMessage } from '..';
import {
createMessageMethods,
CLIENT_MESSAGE_SELECT,
SUBAGENT_MESSAGE_ACTIVITY_ITEM_LIMIT,
SUBAGENT_TRANSCRIPT_PAGE_LIMIT,
SUBAGENT_TRANSCRIPT_SOURCE_BYTE_LIMIT,
} from './message';
import { tenantStorage, runAsSystem } from '~/config/tenantContext';
import { MAX_MCP_APP_MESSAGE_BSON_BYTES } from './appSnapshots';
import { createModels } from '../models';
import logger from '~/config/winston';
const waitForTimestampTick = () => new Promise((resolve) => setTimeout(resolve, 2));
jest.mock('~/config/winston', () => ({
error: jest.fn(),
warn: jest.fn(),
info: jest.fn(),
debug: jest.fn(),
}));
let mongoServer: InstanceType<typeof MongoMemoryServer>;
let Message: mongoose.Model<IMessage>;
let saveMessage: ReturnType<typeof createMessageMethods>['saveMessage'];
let getMessages: ReturnType<typeof createMessageMethods>['getMessages'];
let getMessagesForSubagentThreadView: ReturnType<
typeof createMessageMethods
>['getMessagesForSubagentThreadView'];
let listSubagentTasksForThreads: ReturnType<
typeof createMessageMethods
>['listSubagentTasksForThreads'];
let updateMessage: ReturnType<typeof createMessageMethods>['updateMessage'];
let updateToolCallResult: ReturnType<typeof createMessageMethods>['updateToolCallResult'];
let deleteMessages: ReturnType<typeof createMessageMethods>['deleteMessages'];
let bulkSaveMessages: ReturnType<typeof createMessageMethods>['bulkSaveMessages'];
let claimSubagentTaskResult: ReturnType<typeof createMessageMethods>['claimSubagentTaskResult'];
let recordSubagentTaskControlReceipt: ReturnType<
typeof createMessageMethods
>['recordSubagentTaskControlReceipt'];
let getSubagentTaskControlReceipt: ReturnType<
typeof createMessageMethods
>['getSubagentTaskControlReceipt'];
let getSubagentTaskControlReplay: ReturnType<
typeof createMessageMethods
>['getSubagentTaskControlReplay'];
let releaseSubagentTaskResultClaim: ReturnType<
typeof createMessageMethods
>['releaseSubagentTaskResultClaim'];
let claimBackgroundToolResults: ReturnType<
typeof createMessageMethods
>['claimBackgroundToolResults'];
let releaseBackgroundToolResultClaims: ReturnType<
typeof createMessageMethods
>['releaseBackgroundToolResultClaims'];
function rejectUpdateArrays(beforeUpdate?: () => Promise<void>) {
const originalFindOneAndUpdate = Message.collection.findOneAndUpdate.bind(Message.collection);
return jest.spyOn(Message.collection, 'findOneAndUpdate').mockImplementation(async (...args) => {
if (Array.isArray(args[1])) {
throw new Error('Compatibility guard rejected an update array');
}
await beforeUpdate?.();
return originalFindOneAndUpdate(...args);
});
}
beforeAll(async () => {
mongoServer = await MongoMemoryServer.create();
const mongoUri = mongoServer.getUri();
const models = createModels(mongoose);
Object.assign(mongoose.models, models);
Message = mongoose.models.Message;
const methods = createMessageMethods(mongoose);
saveMessage = methods.saveMessage;
getMessages = methods.getMessages;
getMessagesForSubagentThreadView = methods.getMessagesForSubagentThreadView;
listSubagentTasksForThreads = methods.listSubagentTasksForThreads;
updateMessage = methods.updateMessage;
updateToolCallResult = methods.updateToolCallResult;
deleteMessages = methods.deleteMessages;
bulkSaveMessages = methods.bulkSaveMessages;
claimSubagentTaskResult = methods.claimSubagentTaskResult;
recordSubagentTaskControlReceipt = methods.recordSubagentTaskControlReceipt;
getSubagentTaskControlReceipt = methods.getSubagentTaskControlReceipt;
getSubagentTaskControlReplay = methods.getSubagentTaskControlReplay;
releaseSubagentTaskResultClaim = methods.releaseSubagentTaskResultClaim;
claimBackgroundToolResults = methods.claimBackgroundToolResults;
releaseBackgroundToolResultClaims = methods.releaseBackgroundToolResultClaims;
await mongoose.connect(mongoUri);
await Message.createIndexes();
});
afterAll(async () => {
await mongoose.disconnect();
await mongoServer.stop();
});
describe('Message Operations', () => {
it('constructs message methods before the host registers models', () => {
const unregistered = new mongoose.Mongoose();
expect(unregistered.models.Message).toBeUndefined();
expect(() => createMessageMethods(unregistered as unknown as typeof mongoose)).not.toThrow();
});
let mockCtx: {
userId: string;
isTemporary?: boolean;
expiredAt?: Date;
interfaceConfig?: AppConfig['interfaceConfig'];
};
let mockMessageData: Partial<IMessage> = {
messageId: 'msg123',
conversationId: uuidv4(),
text: 'Hello, world!',
user: 'user123',
};
beforeEach(async () => {
jest.clearAllMocks();
// Clear database
await Message.deleteMany({});
await mongoose.models.Conversation.deleteMany({});
mockCtx = {
userId: 'user123',
interfaceConfig: {
temporaryChatRetention: 24, // Default 24 hours
},
};
mockMessageData = {
messageId: 'msg123',
conversationId: uuidv4(),
text: 'Hello, world!',
user: 'user123',
};
});
const appAttachment = (i: number, bytes: number, toolCallId = 'call_bg') => ({
type: Tools.ui_resources,
file_id: `app-${i}`,
toolCallId,
[Tools.ui_resources]: [
{
uri: `ui://app/${i}`,
mimeType: MCP_APP_MIME_TYPE,
serverName: 'server',
serverBinding: 'authenticated-binding',
resourceId: `resource-${i}`,
toolName: 'show_app',
content: [{ type: 'text', text: 'canonical' }],
text: 'x'.repeat(bytes),
},
],
});
describe('App admission across writers', () => {
it('rebudgets aggregate sub-megabyte blocks on content-only saves', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
attachments: Array.from({ length: 11 }, (_, i) =>
appAttachment(i, 1024 * 1024),
) as unknown as IMessage['attachments'],
});
const content = Array.from({ length: 10 }, () => ({
type: 'text',
text: 'x'.repeat(700_000),
}));
await saveMessage(mockCtx, { ...mockMessageData, content, attachments: undefined });
const row = await Message.findOne({ messageId: 'msg123' }).lean();
expect(row?.content).toEqual(content);
expect(mongoose.mongo.BSON.calculateObjectSize(row!)).toBeLessThanOrEqual(
MAX_MCP_APP_MESSAGE_BSON_BYTES,
);
}, 60000);
it('rebudgets every sub-megabyte settle without a new attachment', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
content: Array.from({ length: 8 }, (_, i) => ({
type: 'tool_call',
tool_call: { id: `call-${i}`, output: 'pending' },
})),
attachments: Array.from({ length: 11 }, (_, i) =>
appAttachment(i, 1024 * 1024),
) as unknown as IMessage['attachments'],
});
for (let i = 0; i < 8; i++) {
expect(
(
await updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: mockMessageData.conversationId as string,
toolCallId: `call-${i}`,
output: 'x'.repeat(900_000),
})
).matched,
).toBe(true);
const row = await Message.findOne({ messageId: 'msg123' }).lean();
expect(mongoose.mongo.BSON.calculateObjectSize(row!)).toBeLessThanOrEqual(
MAX_MCP_APP_MESSAGE_BSON_BYTES,
);
expect(row?.attachments).toHaveLength(11);
}
}, 60000);
it('never propagates caller tenantId through a budget callback or provenance save', async () => {
await tenantStorage.run({ tenantId: 'real-tenant' }, async () => {
const result = await saveMessage(mockCtx, {
...mockMessageData,
tenantId: 'evil-tenant',
userSubmittedPaths: ['/text'],
attachments: [appAttachment(0, 4096)] as unknown as IMessage['attachments'],
});
expect(result?.tenantId).toBe('real-tenant');
});
const row = await runAsSystem(() => Message.findOne({ messageId: 'msg123' }).lean());
expect(row?.tenantId).toBe('real-tenant');
expect(row?.attachments).toHaveLength(1);
});
it('preserves omitted attachments from the retried row, not a stale preliminary read', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
content: [{ type: 'tool_call', tool_call: { id: 'call_bg', output: 'pending' } }],
attachments: [appAttachment(0, 4096)] as unknown as IMessage['attachments'],
});
const original = Message.findOneAndUpdate.bind(Message);
let inject = true;
const spy = jest.spyOn(Message, 'findOneAndUpdate').mockImplementation((...args) => {
const query = original(...args);
const execute = query.exec.bind(query);
query.exec = async () => {
if (inject && (args[0] as Record<string, unknown>)?.__v != null) {
inject = false;
await updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: mockMessageData.conversationId as string,
toolCallId: 'call_bg',
attachments: [appAttachment(1, 4096)],
});
}
return execute();
};
return query;
});
try {
await saveMessage(mockCtx, {
...mockMessageData,
text: 'x'.repeat(1024 * 1024 + 1),
attachments: undefined,
});
} finally {
spy.mockRestore();
}
const row = await Message.findOne({ messageId: 'msg123' }).lean();
expect(inject).toBe(false);
expect(row?.attachments?.map((x) => (x as { file_id: string }).file_id).sort()).toEqual([
'app-0',
'app-1',
]);
});
it('treats undefined private fields as omissions exactly as MongoDB does', async () => {
await saveMessage(mockCtx, mockMessageData);
const subagentTranscript = {
taskId: 'private',
mode: 'append',
messagesJson: 'p'.repeat(5 * 1024 * 1024),
};
await Message.updateOne({ messageId: 'msg123' }, { $set: { subagentTranscript } });
await saveMessage(mockCtx, {
...mockMessageData,
subagentTranscript: undefined,
attachments: Array.from({ length: 9 }, (_, i) =>
appAttachment(i, 1024 * 1024),
) as unknown as IMessage['attachments'],
});
const row = await Message.findOne({ messageId: 'msg123' })
.select('+subagentTranscript')
.lean();
expect(row?.subagentTranscript).toEqual(subagentTranscript);
expect(mongoose.mongo.BSON.calculateObjectSize(row!)).toBeLessThanOrEqual(
MAX_MCP_APP_MESSAGE_BSON_BYTES,
);
}, 60000);
it.each([
['part agent wins', 'mine', 'other', true],
['different part agent wins', 'other', 'mine', false],
['nested agent fallback', undefined, 'other', false],
['legacy wildcard', undefined, undefined, true],
])('sizes only parts actually updated: %s', async (_name, partAgent, callAgent, matches) => {
const content = [
{ type: 'tool_call', agentId: 'mine', tool_call: { id: 'call_bg', output: 'pending' } },
{
type: 'tool_call',
...(partAgent != null && { agentId: partAgent }),
tool_call: { id: 'call_bg', agentId: callAgent, output: 'p'.repeat(850_000) },
},
];
let configReads = 0;
const methods = createMessageMethods(mongoose, {
getMCPAppMessageBudget: async () => {
configReads++;
return 1024 * 1024;
},
});
await methods.saveMessage(mockCtx, {
...mockMessageData,
content,
attachments: [appAttachment(0, 150_000)] as unknown as IMessage['attachments'],
});
const result = await methods.updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: mockMessageData.conversationId as string,
toolCallId: 'call_bg',
agentId: 'mine',
output: 'x'.repeat(300_000),
});
expect(result.matched).toBe(true);
const row = await Message.findOne({ messageId: 'msg123' }).lean();
expect(row?.content?.[1]).toMatchObject({
tool_call: { output: matches ? 'x'.repeat(300_000) : 'p'.repeat(850_000) },
});
const ui = (row?.attachments?.[0] as { ui_resources: Array<{ text?: string }> } | undefined)
?.ui_resources;
if (matches) expect(ui?.[0].text).toBeDefined();
else expect(ui).toBeUndefined(); // Canonical-only may exceed the App target, never the storage ceiling.
expect(configReads).toBeGreaterThan(0);
});
it.each(['edit', 'bulk'] as const)(
'applies the same configurable limit through the %s writer',
async (writer) => {
const methods = createMessageMethods(mongoose, {
getMCPAppMessageBudget: async () => 150_000,
});
const base = {
...mockMessageData,
attachments: [appAttachment(0, 100_000)] as unknown as IMessage['attachments'],
};
await methods.saveMessage(mockCtx, base);
const text = 'result'.repeat(15_000);
if (writer === 'edit')
await methods.updateMessage('user123', { messageId: 'msg123', text });
if (writer === 'bulk')
await methods.bulkSaveMessages([{ ...mockMessageData, user: 'user123', text }]);
const row = await Message.findOne({ messageId: 'msg123' }).lean();
expect(row?.text).toBe(text);
expect(mongoose.mongo.BSON.calculateObjectSize(row!)).toBeLessThanOrEqual(150_000);
expect(
(row?.attachments?.[0] as { ui_resources: Array<{ text?: string }> }).ui_resources[0]
.text,
).toBeUndefined();
},
);
it('preserves bulk import counts and timestamps across ordinary and App-bearing rows', async () => {
const methods = createMessageMethods(mongoose, {
getMCPAppMessageBudget: async () => 80_000,
});
const createdAt = new Date('2020-01-01T00:00:00Z');
const messages = [
{ ...mockMessageData, messageId: 'normal', createdAt },
{
...mockMessageData,
messageId: 'app',
createdAt,
attachments: [appAttachment(0, 100_000)] as unknown as IMessage['attachments'],
},
];
const created = await methods.bulkSaveMessages(messages, true);
expect(created).toMatchObject({ upsertedCount: 2, modifiedCount: 0 });
const modified = await methods.bulkSaveMessages(messages, true);
expect(modified).toMatchObject({ upsertedCount: 0, modifiedCount: 2, matchedCount: 2 });
const row = await Message.findOne({ messageId: 'app' }).lean();
expect(row?.createdAt).toEqual(createdAt);
expect(mongoose.mongo.BSON.calculateObjectSize(row!)).toBeLessThanOrEqual(80_000);
});
it('keeps newer-producer fields in the whole BSON estimate without dropping them', async () => {
await saveMessage(mockCtx, mockMessageData);
await Message.collection.updateOne(
{ messageId: 'msg123' },
{ $set: { futurePayload: 'x'.repeat(5 * 1024 * 1024) } },
);
await saveMessage(mockCtx, {
...mockMessageData,
attachments: Array.from({ length: 9 }, (_, i) =>
appAttachment(i, 1024 * 1024),
) as unknown as IMessage['attachments'],
});
const row = await Message.collection.findOne({ messageId: 'msg123' });
expect(row?.futurePayload.length).toBe(5 * 1024 * 1024);
expect(mongoose.mongo.BSON.calculateObjectSize(row!)).toBeLessThanOrEqual(
MAX_MCP_APP_MESSAGE_BSON_BYTES,
);
}, 60000);
it('does not resolve App configuration or read a full row on ordinary saves', async () => {
const getMCPAppMessageBudget = jest.fn();
const methods = createMessageMethods(mongoose, { getMCPAppMessageBudget });
const read = jest.spyOn(Message, 'findOne');
try {
await methods.saveMessage(mockCtx, mockMessageData);
await methods.saveMessage(mockCtx, { ...mockMessageData, text: 'updated' });
expect(read).not.toHaveBeenCalled();
expect(getMCPAppMessageBudget).not.toHaveBeenCalled();
} finally {
read.mockRestore();
}
});
});
describe('saveMessage', () => {
it('bounds aggregate App BSON without changing canonical output, even on a later full save', async () => {
const content = [{ type: 'text', text: 'canonical message' }];
const attachments = Array.from({ length: 17 }, (_, i) =>
appAttachment(i, 1024 * 1024 - 2048),
);
for (let attempt = 0; attempt < 2; attempt++) {
await saveMessage(mockCtx, {
...mockMessageData,
content,
attachments: attachments as unknown as IMessage['attachments'],
});
const stored = await Message.findOne({ messageId: 'msg123' }).lean();
expect(mongoose.mongo.BSON.calculateObjectSize(stored!)).toBeLessThanOrEqual(
MAX_MCP_APP_MESSAGE_BSON_BYTES,
);
const apps =
stored?.attachments?.flatMap(
(attachment) =>
(
attachment as {
[Tools.ui_resources]: Array<{ text?: string; serverBinding?: string }>;
}
)[Tools.ui_resources],
) ?? [];
expect(apps).toHaveLength(17);
expect(apps.some((app) => app.text === undefined)).toBe(true);
expect(apps.every((app) => app.serverBinding === 'authenticated-binding')).toBe(true);
expect(stored?.content).toEqual(content);
}
}, 60000);
it('re-budgets retained Apps when a later save omits attachments and grows canonical text', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
attachments: Array.from({ length: 3 }, (_, i) =>
appAttachment(i, 3 * 1024 * 1024),
) as unknown as IMessage['attachments'],
});
const text = 'model answer '.repeat(420_000);
await saveMessage(mockCtx, { ...mockMessageData, text, attachments: undefined });
const stored = await Message.findOne({ messageId: 'msg123' }).lean();
expect(stored?.text).toBe(text);
expect(mongoose.mongo.BSON.calculateObjectSize(stored!)).toBeLessThanOrEqual(
MAX_MCP_APP_MESSAGE_BSON_BYTES,
);
expect(stored?.attachments).toHaveLength(3);
expect(
stored?.attachments?.some((attachment) =>
(attachment as { [Tools.ui_resources]: Array<{ text?: string }> })[
Tools.ui_resources
].some((resource) => resource.text === undefined),
),
).toBe(true);
}, 60000);
it('omits only oversized bound Apps, never legacy UI or canonical message text', async () => {
const original = appAttachment(1, 4 * 1024 * 1024);
const legacy = { uri: 'ui://legacy', mimeType: 'text/html', text: '<p>legacy</p>' };
const canonical = 'ordinary output '.repeat(420_000);
const attachment = {
...original,
[Tools.ui_resources]: [
{ ...original[Tools.ui_resources][0], content: [{ type: 'text', text: canonical }] },
legacy,
],
};
await saveMessage(mockCtx, {
...mockMessageData,
text: canonical,
attachments: [
attachment,
{ file_id: 'ordinary-file' },
] as unknown as IMessage['attachments'],
});
const stored = await Message.findOne({ messageId: 'msg123' }).lean();
expect(mongoose.mongo.BSON.calculateObjectSize(stored!)).toBeLessThanOrEqual(
MAX_MCP_APP_MESSAGE_BSON_BYTES,
);
expect(stored?.text).toBe(canonical);
expect(stored?.attachments).toEqual([
expect.objectContaining({ [Tools.ui_resources]: [legacy] }),
{ file_id: 'ordinary-file' },
]);
}, 60000);
it('accounts for server-private message fields that the chat projection omits', async () => {
await saveMessage(mockCtx, mockMessageData);
await Message.updateOne(
{ messageId: 'msg123' },
{
$set: {
subagentTranscript: {
taskId: 'private-task',
mode: 'append',
messagesJson: 'p'.repeat(4 * 1024 * 1024),
},
},
},
);
await saveMessage(mockCtx, {
...mockMessageData,
attachments: Array.from({ length: 9 }, (_, i) =>
appAttachment(i, 1024 * 1024 - 2048),
) as unknown as IMessage['attachments'],
});
const stored = await Message.findOne({ messageId: 'msg123' })
.select('+subagentTranscript')
.lean();
expect(mongoose.mongo.BSON.calculateObjectSize(stored!)).toBeLessThanOrEqual(
MAX_MCP_APP_MESSAGE_BSON_BYTES,
);
const apps =
stored?.attachments?.flatMap(
(item) =>
(item as { [Tools.ui_resources]: Array<{ text?: string }> })[Tools.ui_resources],
) ?? [];
expect(apps).toHaveLength(9);
expect(apps.some((item) => item.text === undefined)).toBe(true);
}, 60000);
it('applies the same App budget when merging user-submitted provenance', async () => {
const attachments = Array.from({ length: 17 }, (_, i) =>
appAttachment(i, 1024 * 1024 - 2048),
);
await saveMessage(mockCtx, {
...mockMessageData,
content: [{ type: 'steer', text: 'user-authored' }],
attachments: attachments as unknown as IMessage['attachments'],
});
const stored = await Message.findOne({ messageId: 'msg123' }).lean();
expect(mongoose.mongo.BSON.calculateObjectSize(stored!)).toBeLessThanOrEqual(
MAX_MCP_APP_MESSAGE_BSON_BYTES,
);
expect(stored?.content?.[0]).toMatchObject({ type: 'steer', text: 'user-authored' });
expect(stored?.userSubmittedPaths).toContain('/content/0');
}, 60000);
it('should save a message for an authenticated user', async () => {
const result = await saveMessage(mockCtx, mockMessageData);
expect(result?.messageId).toBe('msg123');
expect(result?.user).toBe('user123');
expect(result?.text).toBe('Hello, world!');
// Verify the message was actually saved to the database
const savedMessage = await Message.findOne({ messageId: 'msg123', user: 'user123' });
expect(savedMessage).toBeTruthy();
expect(savedMessage?.text).toBe('Hello, world!');
expect(savedMessage?.isUserSubmitted).toBeUndefined();
});
it('round-trips context usage metadata without narrowing tool fields or unknown data', async () => {
const contextUsage = {
runId: 'run-context-rich',
breakdown: {
messageTokens: 120,
toolMessageTokens: 18,
toolMessageTokenCounts: { search: 11, read_file: 4 },
sdkExtension: {
providerOnly: true,
nested: { invocationOverhead: 3, labels: ['retained'] },
},
},
sdkExtension: {
source: 'retained-snapshot-field',
nested: { calibration: { mode: 'provider' } },
},
};
const knownZero = {
...contextUsage,
breakdown: {
...contextUsage.breakdown,
toolMessageTokens: 0,
toolMessageTokenCounts: { search: 0 },
},
};
const {
toolMessageTokens: _missingToolMessageTokens,
toolMessageTokenCounts: _missingToolMessageTokenCounts,
...missingBreakdown
} = contextUsage.breakdown;
const missing = { ...contextUsage, breakdown: missingBreakdown };
await Promise.all([
saveMessage(mockCtx, {
...mockMessageData,
messageId: 'msg-context-rich',
metadata: { contextUsage },
}),
saveMessage(mockCtx, {
...mockMessageData,
messageId: 'msg-context-zero',
metadata: { contextUsage: knownZero },
}),
saveMessage(mockCtx, {
...mockMessageData,
messageId: 'msg-context-missing',
metadata: { contextUsage: missing },
}),
]);
const persisted = await Message.find({
user: 'user123',
messageId: { $in: ['msg-context-rich', 'msg-context-zero', 'msg-context-missing'] },
}).lean();
const byId = new Map(persisted.map((message) => [message.messageId, message]));
expect(byId.get('msg-context-rich')?.metadata?.contextUsage).toEqual(contextUsage);
expect(byId.get('msg-context-zero')?.metadata?.contextUsage).toEqual(knownZero);
expect(byId.get('msg-context-missing')?.metadata?.contextUsage).toEqual(missing);
const zeroBreakdown = (
byId.get('msg-context-zero')?.metadata?.contextUsage as typeof knownZero
).breakdown;
expect(zeroBreakdown.toolMessageTokens).toBe(0);
expect(Object.prototype.hasOwnProperty.call(zeroBreakdown, 'toolMessageTokens')).toBe(true);
const missingBreakdownRecord = (
byId.get('msg-context-missing')?.metadata?.contextUsage as typeof missing
).breakdown;
expect(
Object.prototype.hasOwnProperty.call(missingBreakdownRecord, 'toolMessageTokens'),
).toBe(false);
expect(missingBreakdownRecord.sdkExtension).toEqual(contextUsage.breakdown.sdkExtension);
expect(
(byId.get('msg-context-rich')?.metadata?.contextUsage as typeof contextUsage).sdkExtension
.nested,
).toEqual({ calibration: { mode: 'provider' } });
});
it('unsets a previously stored context meta in the same update as the terminal save', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
contextMeta: {
calibrationRatio: 1.2,
encoding: 'claude',
fading: { v: 1, budgetTokens: 50_000, masked: true },
},
});
const partial = await Message.findOne({ messageId: 'msg123', user: 'user123' });
expect(partial?.contextMeta?.fading?.budgetTokens).toBe(50_000);
const findOneAndUpdate = jest.spyOn(Message, 'findOneAndUpdate');
const updateOne = jest.spyOn(Message, 'updateOne');
try {
const result = await saveMessage(mockCtx, {
...mockMessageData,
text: 'Completed',
contextMeta: null,
});
expect(result?.contextMeta).toBeUndefined();
expect(result?.text).toBe('Completed');
expect(findOneAndUpdate).toHaveBeenCalledTimes(1);
expect(findOneAndUpdate).toHaveBeenCalledWith(
expect.anything(),
expect.objectContaining({ $unset: expect.objectContaining({ contextMeta: 1 }) }),
expect.anything(),
);
expect(updateOne).not.toHaveBeenCalled();
} finally {
findOneAndUpdate.mockRestore();
updateOne.mockRestore();
}
const completed = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
expect(completed).not.toHaveProperty('contextMeta');
expect(completed?.text).toBe('Completed');
});
it('unsets a stored context meta atomically through the provenance merge as well', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
contextMeta: { calibrationRatio: 1.2, encoding: 'claude' },
});
const findOneAndUpdate = jest.spyOn(Message, 'findOneAndUpdate');
try {
const result = await saveMessage(mockCtx, {
...mockMessageData,
isCreatedByUser: false,
isUserSubmitted: true,
userSubmittedPaths: ['/content/0/text'],
contextMeta: null,
});
expect(result?.contextMeta).toBeUndefined();
expect(result?.userSubmittedPaths).toEqual(['/content/0/text']);
expect(findOneAndUpdate).toHaveBeenCalledTimes(1);
expect(findOneAndUpdate).toHaveBeenCalledWith(
expect.anything(),
expect.objectContaining({ $unset: expect.objectContaining({ contextMeta: 1 }) }),
expect.anything(),
);
} finally {
findOneAndUpdate.mockRestore();
}
const completed = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
expect(completed).not.toHaveProperty('contextMeta');
expect(completed?.isUserSubmitted).toBe(true);
});
it('should persist optional user-submitted provenance independently of message role', async () => {
const result = await saveMessage(mockCtx, {
...mockMessageData,
isCreatedByUser: false,
isUserSubmitted: true,
userSubmittedPaths: ['/content/0/text'],
});
expect(result?.isCreatedByUser).toBe(false);
expect(result?.isUserSubmitted).toBe(true);
expect(result?.userSubmittedPaths).toEqual(['/content/0/text']);
const savedMessage = await Message.findOne({ messageId: 'msg123', user: 'user123' });
expect(savedMessage?.isCreatedByUser).toBe(false);
expect(savedMessage?.isUserSubmitted).toBe(true);
expect(savedMessage?.userSubmittedPaths).toEqual(['/content/0/text']);
});
it('stamps native model output without overriding explicit provenance', async () => {
const result = await saveMessage(mockCtx, {
...mockMessageData,
isCreatedByUser: false,
});
expect(result?.isUserSubmitted).toBe(false);
const explicitlySubmitted = await saveMessage(mockCtx, {
...mockMessageData,
messageId: 'msg-explicit-submitted',
isCreatedByUser: false,
isUserSubmitted: true,
});
expect(explicitlySubmitted?.isUserSubmitted).toBe(true);
const pathScoped = await saveMessage(mockCtx, {
...mockMessageData,
messageId: 'msg-path-scoped',
isCreatedByUser: false,
userSubmittedPaths: ['/content/0/text'],
});
expect(pathScoped?.isUserSubmitted).toBe(false);
expect(pathScoped?.userSubmittedPaths).toEqual(['/content/0/text']);
});
it('bounds and validates stored user-submitted provenance paths', async () => {
const submittedPaths = [
'not-a-pointer',
...Array.from({ length: 300 }, (_, index) => `/content/${index}/text`),
];
const result = await saveMessage(mockCtx, {
...mockMessageData,
isCreatedByUser: false,
userSubmittedPaths: submittedPaths,
});
expect(result?.userSubmittedPaths).toHaveLength(256);
expect(result?.userSubmittedPaths).not.toContain('not-a-pointer');
expect(result?.userSubmittedPaths?.[0]).toBe('/content/0/text');
expect(result?.isUserSubmitted).toBe(true);
});
it('validates and atomically preserves exact HITL field provenance', async () => {
const first = await saveMessage(mockCtx, {
...mockMessageData,
isCreatedByUser: false,
content: [
{
type: 'tool_call',
tool_call: { id: 'tool-1', output: 'Human response' },
},
],
userSubmittedMessageFieldPaths: [
{ path: '/content/0/tool_call/output', field: 'answer' },
{ path: '/content/0/tool_call/output', field: 'answer' },
{ path: 'not-a-pointer', field: 'decision_reason' },
],
});
expect(first?.userSubmittedMessageFieldPaths).toEqual([
expect.objectContaining({ path: '/content/0/tool_call/output', field: 'answer' }),
]);
await updateMessage(mockCtx.userId, {
messageId: 'msg123',
userSubmittedMessageFieldPaths: [
{ path: '/content/0/tool_call/output', field: 'decision_response' },
],
});
const stored = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
expect(stored?.userSubmittedMessageFieldPaths).toEqual(
expect.arrayContaining([
expect.objectContaining({ path: '/content/0/tool_call/output', field: 'answer' }),
expect.objectContaining({
path: '/content/0/tool_call/output',
field: 'decision_response',
}),
]),
);
expect(stored?.userSubmittedMessageFieldPaths).toHaveLength(2);
});
it('adds semantic steer paths without replacing existing field provenance', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
isCreatedByUser: false,
userSubmittedPaths: ['/text'],
});
const result = await saveMessage(mockCtx, {
...mockMessageData,
isCreatedByUser: false,
content: [
{ type: 'text', text: 'Model response' },
{ type: 'steer', steer: 'User direction' },
],
});
expect(result?.userSubmittedPaths).toEqual(expect.arrayContaining(['/text', '/content/1']));
expect(result?.userSubmittedPaths).toHaveLength(2);
});
it('saves provenance when update arrays are rejected at the collection boundary', async () => {
const findOneAndUpdate = rejectUpdateArrays();
await saveMessage(mockCtx, {
...mockMessageData,
isCreatedByUser: false,
userSubmittedPaths: ['/text'],
});
expect(findOneAndUpdate).toHaveBeenCalledTimes(1);
const update = findOneAndUpdate.mock.calls[0][1];
expect(update).toEqual(expect.objectContaining({ $set: expect.any(Object) }));
});
it('merges provenance from concurrent first saves', async () => {
await Message.syncIndexes();
await Promise.all([
saveMessage(mockCtx, {
...mockMessageData,
isCreatedByUser: false,
text: 'First writer',
userSubmittedPaths: ['/text'],
}),
saveMessage(mockCtx, {
...mockMessageData,
isCreatedByUser: false,
content: [{ type: 'text', text: 'Second writer' }],
userSubmittedPaths: ['/content/0/text'],
}),
]);
const savedMessages = await Message.find({ messageId: 'msg123', user: 'user123' }).lean();
expect(savedMessages).toHaveLength(1);
const [savedMessage] = savedMessages;
expect(savedMessage?.userSubmittedPaths).toEqual(
expect.arrayContaining(['/text', '/content/0/text']),
);
expect(savedMessage?.userSubmittedPaths).toHaveLength(2);
});
it('persists dollar-prefixed message values literally while merging provenance', async () => {
const created = await saveMessage(mockCtx, {
...mockMessageData,
text: '$PATH',
content: [{ type: 'text', text: '$CONTENT' }],
userSubmittedPaths: ['/text', '/content/0/text'],
});
expect(created?.text).toBe('$PATH');
expect(created?.content).toEqual([expect.objectContaining({ text: '$CONTENT' })]);
const updated = await updateMessage(mockCtx.userId, {
messageId: 'msg123',
text: '$UPDATED_PATH',
content: [{ type: 'text', text: '$UPDATED_CONTENT' }],
userSubmittedPaths: ['/text', '/content/0/text'],
});
expect(updated?.text).toBe('$UPDATED_PATH');
expect(
await Message.findOne({ messageId: 'msg123', user: 'user123' })
.lean()
.then((message) => message?.content),
).toEqual([expect.objectContaining({ text: '$UPDATED_CONTENT' })]);
});
it('should throw an error for unauthenticated user', async () => {
mockCtx.userId = null as unknown as string;
await expect(saveMessage(mockCtx, mockMessageData)).rejects.toThrow('User not authenticated');
});
it('should handle invalid conversation ID gracefully', async () => {
mockMessageData.conversationId = 'invalid-id';
const result = await saveMessage(mockCtx, mockMessageData);
expect(result).toBeUndefined();
});
it('should not log message params for invalid conversation IDs', async () => {
mockMessageData.conversationId = 'invalid-id';
mockMessageData.text = 'Sensitive prompt text';
await saveMessage(mockCtx, mockMessageData, { context: 'message-save-test' });
expect(logger.warn).toHaveBeenCalledWith(
'Invalid conversation ID: invalid-id (context: message-save-test)',
);
expect(logger.info).not.toHaveBeenCalled();
});
});
describe('bulkSaveMessages', () => {
it('preserves unknown provenance when cloning an unmarked assistant row', async () => {
const conversationId = uuidv4();
await bulkSaveMessages([
{
user: 'user123',
messageId: 'bulk-unmarked-assistant',
conversationId,
isCreatedByUser: false,
},
{
user: 'user123',
messageId: 'bulk-user-submitted',
conversationId,
isCreatedByUser: false,
isUserSubmitted: true,
},
]);
const rows = await Message.find({ conversationId }).lean();
expect(
rows.find(({ messageId }) => messageId === 'bulk-unmarked-assistant'),
).not.toHaveProperty('isUserSubmitted');
expect(
rows.find(({ messageId }) => messageId === 'bulk-user-submitted')?.isUserSubmitted,
).toBe(true);
});
it('caps exact field provenance without promoting model output to whole-message provenance', async () => {
const conversationId = uuidv4();
await bulkSaveMessages([
{
user: 'user123',
messageId: 'bulk-exact-overflow',
conversationId,
isCreatedByUser: false,
userSubmittedMessageFieldPaths: Array.from({ length: 300 }, (_, index) => ({
path: `/decision/${index}`,
field: 'decision_response' as const,
})),
},
]);
const row = await Message.findOne({ messageId: 'bulk-exact-overflow' }).lean();
expect(row?.userSubmittedMessageFieldPaths).toHaveLength(257);
expect(row).not.toHaveProperty('isUserSubmitted');
});
});
it('preserves unknown provenance when message savers update legacy assistant rows', async () => {
const conversationId = uuidv4();
const messageIds = ['legacy-save', 'legacy-bulk'];
await Message.collection.insertMany(
messageIds.map((messageId) => ({
user: 'user123',
messageId,
conversationId,
isCreatedByUser: false,
text: 'Legacy assistant output',
})),
);
await saveMessage(mockCtx, {
messageId: 'legacy-save',
conversationId,
isCreatedByUser: false,
text: 'Updated assistant output',
});
await bulkSaveMessages([
{
user: 'user123',
messageId: 'legacy-bulk',
conversationId,
isCreatedByUser: false,
text: 'Updated assistant output',
},
]);
const rows = await Message.find({ messageId: { $in: messageIds } }).lean();
expect(rows).toHaveLength(2);
for (const row of rows) {
expect(row).not.toHaveProperty('isUserSubmitted');
}
});
describe('updateMessage', () => {
it('should update a message for the authenticated user', async () => {
// First save a message
await saveMessage(mockCtx, mockMessageData);
const result = await updateMessage(mockCtx.userId, {
messageId: 'msg123',
text: 'Updated text',
});
expect(result?.messageId).toBe('msg123');
expect(result?.text).toBe('Updated text');
// Verify in database
const updatedMessage = await Message.findOne({ messageId: 'msg123', user: 'user123' });
expect(updatedMessage?.text).toBe('Updated text');
});
it('atomically merges provenance from concurrent edits to distinct fields', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
isCreatedByUser: false,
content: [{ type: 'text', text: 'Model content' }],
});
await Promise.all([
updateMessage(mockCtx.userId, {
messageId: 'msg123',
text: 'Human-edited text',
userSubmittedPaths: ['/text'],
}),
updateMessage(mockCtx.userId, {
messageId: 'msg123',
content: [{ type: 'text', text: 'Human-edited content' }],
userSubmittedPaths: ['/content/0/text'],
}),
]);
const updatedMessage = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
expect(updatedMessage?.text).toBe('Human-edited text');
expect(updatedMessage?.content).toEqual([
expect.objectContaining({ type: 'text', text: 'Human-edited content' }),
]);
expect(updatedMessage?.userSubmittedPaths).toEqual(
expect.arrayContaining(['/text', '/content/0/text']),
);
expect(updatedMessage?.userSubmittedPaths).toHaveLength(2);
});
it('retries a stale provenance snapshot without dropping either writer', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
isCreatedByUser: false,
content: [{ type: 'text', text: 'Model content' }],
});
let injectedConcurrentWrite = false;
const findOneAndUpdate = rejectUpdateArrays(async () => {
if (injectedConcurrentWrite) {
return;
}
injectedConcurrentWrite = true;
await Message.collection.updateOne(
{ messageId: 'msg123', user: 'user123' },
{ $set: { userSubmittedPaths: ['/content/0/text'] } },
);
});
await updateMessage(mockCtx.userId, {
messageId: 'msg123',
text: 'Human-edited text',
userSubmittedPaths: ['/text'],
});
const updatedMessage = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
expect(findOneAndUpdate).toHaveBeenCalledTimes(2);
expect(updatedMessage?.userSubmittedPaths).toEqual(
expect.arrayContaining(['/content/0/text', '/text']),
);
expect(updatedMessage?.userSubmittedPaths).toHaveLength(2);
for (const [, update] of findOneAndUpdate.mock.calls) {
expect(update).toEqual(expect.objectContaining({ $set: expect.any(Object) }));
}
});
it('atomically caps repeated provenance unions and promotes overflow to whole-message provenance', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
isCreatedByUser: false,
content: [{ type: 'text', text: 'Model content' }],
});
await Promise.all([
updateMessage(mockCtx.userId, {
messageId: 'msg123',
userSubmittedPaths: Array.from({ length: 200 }, (_, index) => `/path/${index}`),
userSubmittedMessageFieldPaths: Array.from({ length: 200 }, (_, index) => ({
path: `/decision/${index}`,
field: 'decision_response' as const,
})),
}),
updateMessage(mockCtx.userId, {
messageId: 'msg123',
userSubmittedPaths: Array.from({ length: 200 }, (_, index) => `/path/${index + 200}`),
userSubmittedMessageFieldPaths: Array.from({ length: 200 }, (_, index) => ({
path: `/decision/${index + 200}`,
field: 'decision_response' as const,
})),
}),
]);
const updatedMessage = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
expect(updatedMessage?.userSubmittedPaths).toHaveLength(256);
expect(updatedMessage?.userSubmittedMessageFieldPaths).toHaveLength(257);
expect(updatedMessage?.isUserSubmitted).toBe(true);
});
it('keeps repeated exact-field overflow scoped instead of promoting the whole message', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
isCreatedByUser: false,
content: [{ type: 'text', text: 'Model content' }],
});
await updateMessage(mockCtx.userId, {
messageId: 'msg123',
userSubmittedMessageFieldPaths: Array.from({ length: 200 }, (_, index) => ({
path: `/decision/${index}`,
field: 'decision_response' as const,
})),
});
await updateMessage(mockCtx.userId, {
messageId: 'msg123',
userSubmittedMessageFieldPaths: Array.from({ length: 200 }, (_, index) => ({
path: `/decision/${index + 200}`,
field: 'decision_response' as const,
})),
});
const updatedMessage = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
expect(updatedMessage?.userSubmittedPaths).toHaveLength(0);
expect(updatedMessage?.userSubmittedMessageFieldPaths).toHaveLength(257);
expect(updatedMessage?.isUserSubmitted).toBe(false);
});
it('returns the generation-time Langfuse routing decisions with feedback updates', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
langfuseSampled: true,
langfuseDestinationIds: ['destination-1'],
langfuseRunId: 'run-1',
});
const result = await updateMessage(mockCtx.userId, {
messageId: 'msg123',
feedback: { rating: 'thumbsUp', tag: undefined },
});
expect(result?.langfuseSampled).toBe(true);
expect(result?.langfuseDestinationIds).toEqual(['destination-1']);
expect(result?.langfuseRunId).toBe('run-1');
});
it('returns the temporary flag with feedback updates', async () => {
await saveMessage({ ...mockCtx, isTemporary: true }, mockMessageData);
const result = await updateMessage(mockCtx.userId, {
messageId: 'msg123',
feedback: { rating: 'thumbsDown', tag: undefined },
});
expect(result?.isTemporary).toBe(true);
});
it('reads a legacy deadline-only row as temporary with feedback updates', async () => {
const expiredAt = new Date(Date.now() + 60 * 60 * 1000);
await Message.collection.insertMany([
{ ...mockMessageData, user: mockCtx.userId, expiredAt },
{
...mockMessageData,
messageId: 'msg-permanent',
user: mockCtx.userId,
isTemporary: false,
expiredAt,
},
]);
const legacy = await updateMessage(mockCtx.userId, {
messageId: 'msg123',
feedback: { rating: 'thumbsDown', tag: undefined },
});
const permanent = await updateMessage(mockCtx.userId, {
messageId: 'msg-permanent',
feedback: { rating: 'thumbsDown', tag: undefined },
});
expect(legacy?.isTemporary).toBe(true);
expect(permanent?.isTemporary).toBe(false);
});
it('should throw an error if message is not found', async () => {
await expect(
updateMessage(mockCtx.userId, { messageId: 'nonexistent', text: 'Test' }),
).rejects.toThrow('Message not found or user not authorized.');
});
});
describe('updateToolCallResult', () => {
it('preserves a large canonical background result by downgrading existing App HTML', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
content: [
{ type: 'tool_call', tool_call: { id: 'call_bg', name: 'show_app', output: 'pending' } },
],
attachments: Array.from({ length: 3 }, (_, i) =>
appAttachment(i, 3 * 1024 * 1024),
) as unknown as IMessage['attachments'],
});
const largeOutput = 'result '.repeat(700_000);
const patched = await updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: mockMessageData.conversationId as string,
toolCallId: 'call_bg',
output: largeOutput,
});
expect(patched.matched).toBe(true);
const stored = await Message.findOne({ messageId: 'msg123' }).lean();
expect(mongoose.mongo.BSON.calculateObjectSize(stored!)).toBeLessThanOrEqual(
MAX_MCP_APP_MESSAGE_BSON_BYTES,
);
expect(stored?.content?.[0]).toMatchObject({ tool_call: { output: largeOutput } });
expect(
stored?.attachments?.some((attachment) =>
(attachment as { [Tools.ui_resources]: Array<{ text?: string }> })[
Tools.ui_resources
].some((resource) => resource.text === undefined),
),
).toBe(true);
}, 60000);
it('serializes concurrent App attachment settlements under the shared BSON budget', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
content: [
{ type: 'tool_call', tool_call: { id: 'call_bg', name: 'show_app', output: 'pending' } },
],
});
const patch = (i: number) =>
updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: mockMessageData.conversationId as string,
toolCallId: 'call_bg',
output: 'canonical result',
attachments: [appAttachment(i, 3 * 1024 * 1024)],
});
const settled = await Promise.all(Array.from({ length: 5 }, (_, i) => patch(i)));
expect(settled.every((item) => item.matched)).toBe(true);
const stored = await Message.findOne({ messageId: 'msg123' }).lean();
expect(mongoose.mongo.BSON.calculateObjectSize(stored!)).toBeLessThanOrEqual(
MAX_MCP_APP_MESSAGE_BSON_BYTES,
);
expect(stored?.attachments).toHaveLength(5);
expect(stored?.content?.[0]).toMatchObject({ tool_call: { output: 'canonical result' } });
await patch(0);
expect((await Message.findOne({ messageId: 'msg123' }).lean())?.attachments).toHaveLength(5);
}, 60000);
const toolCallContent = () => [
{ type: 'text', text: 'intro' },
{
type: 'tool_call',
tool_call: {
id: 'call_bg',
name: 'execute_code',
args: '{"lang":"py","code":"print(1)"}',
output: '{"background_task_id":"task-1"}',
progress: 1,
},
},
{
type: 'tool_call',
tool_call: { id: 'call_other', name: 'execute_code', args: '{}', output: 'untouched' },
},
];
it('patches only the matching tool_call part and appends attachments atomically', async () => {
await saveMessage(mockCtx, { ...mockMessageData, content: toolCallContent() });
const result = await updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: mockMessageData.conversationId as string,
toolCallId: 'call_bg',
output: 'stdout:\nhello',
attachments: [{ file_id: 'f1', toolCallId: 'call_bg' }],
});
expect(result).toEqual({ matched: true, unfinished: false });
const saved = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
const content = saved?.content as Array<{
type: string;
tool_call?: { id: string; output?: string };
}>;
expect(content[1].tool_call?.output).toBe('stdout:\nhello');
expect(content[2].tool_call?.output).toBe('untouched');
expect(saved?.attachments).toEqual([{ file_id: 'f1', toolCallId: 'call_bg' }]);
});
describe('a step id the persisted part lost', () => {
const conversationId = () => mockMessageData.conversationId as string;
const partOutputs = async () => {
const saved = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
return (
saved?.content as Array<{ tool_call?: { id: string; stepId?: string; output?: string } }>
)
.filter((part) => part.tool_call != null)
.map((part) => [
part.tool_call?.id,
part.tool_call?.stepId ?? null,
part.tool_call?.output,
]);
};
it('patches the one part a resumed turn saved without its step id', async () => {
await saveMessage(mockCtx, { ...mockMessageData, content: toolCallContent() });
const result = await updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: conversationId(),
toolCallId: 'call_bg',
stepId: 'step_before_pause',
output: 'stdout:\nfinished during the pause',
attachments: [{ file_id: 'report', toolCallId: 'call_bg' }],
});
expect(result).toEqual({ matched: true, unfinished: false });
expect(await partOutputs()).toEqual([
['call_bg', null, 'stdout:\nfinished during the pause'],
['call_other', null, 'untouched'],
]);
const saved = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
expect(saved?.attachments).toEqual([{ file_id: 'report', toolCallId: 'call_bg' }]);
});
it('still prefers the part whose step id matches exactly', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
content: [
{
type: 'tool_call',
tool_call: { id: 'call_0', name: 'execute_code', output: 'stepless' },
},
{
type: 'tool_call',
tool_call: { id: 'call_0', name: 'execute_code', stepId: 'step_b', output: 'handle' },
},
],
});
await updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: conversationId(),
toolCallId: 'call_0',
stepId: 'step_b',
output: 'settled',
});
expect(await partOutputs()).toEqual([
['call_0', null, 'stepless'],
['call_0', 'step_b', 'settled'],
]);
});
it.each([
{ file_id: 'shared-file' },
{ filepath: '/api/files/code/download/session/shared-file' },
])('preserves sibling step attachments when merging %j', async (fileKey) => {
const siblingAttachment = {
...fileKey,
toolCallId: 'call_bg',
agentId: 'agent-a',
stepId: 'step_b',
};
const attachment = { ...siblingAttachment, stepId: 'step_a' };
await saveMessage(mockCtx, {
...mockMessageData,
content: [
...toolCallContent(),
{
type: 'tool_call',
agentId: 'agent-a',
tool_call: { id: 'call_bg', stepId: 'step_b', output: 'sibling' },
},
],
attachments: [siblingAttachment],
});
const patch = {
userId: 'user123',
messageId: 'msg123',
conversationId: conversationId(),
toolCallId: 'call_bg',
agentId: 'agent-a',
stepId: 'step_a',
output: 'settled',
attachments: [attachment],
};
expect(await updateToolCallResult(patch)).toEqual({ matched: true, unfinished: false });
expect(await updateToolCallResult(patch)).toEqual({ matched: true, unfinished: false });
const saved = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
expect(saved?.attachments).toEqual([siblingAttachment, attachment]);
expect((await partOutputs())[2]).toEqual(['call_bg', 'step_b', 'sibling']);
});
it('retries the exact part after attachment contention without patching its stepless sibling', async () => {
const stepless = {
type: 'tool_call',
agentId: 'agent-a',
tool_call: { id: 'call_bg', output: 'stepless' },
};
await saveMessage(mockCtx, {
...mockMessageData,
content: [
stepless,
{
type: 'tool_call',
agentId: 'agent-a',
tool_call: { id: 'call_bg', stepId: 'step_b', output: 'handle' },
},
],
attachments: [],
});
const patch = {
userId: 'user123',
messageId: 'msg123',
conversationId: conversationId(),
toolCallId: 'call_bg',
stepId: 'step_b',
agentId: 'agent-a',
output: 'settled',
attachments: [{ file_id: 'result', toolCallId: 'call_bg', stepId: 'step_b' }],
backgroundTask: {
taskId: 'task-b',
toolName: 'execute_code',
status: 'completed' as const,
settledAt: new Date(),
resultClaim: {
kind: 'manual' as const,
claimId: 'poll-b',
claimedAt: new Date(),
},
},
};
const original = Message.collection.findOneAndUpdate.bind(Message.collection);
let collisions = 0;
const spy = jest
.spyOn(Message.collection, 'findOneAndUpdate')
.mockImplementation(async (...args) => {
if (Object.prototype.hasOwnProperty.call(args[0], 'attachments') && collisions < 8) {
collisions += 1;
await Message.updateOne(
{ messageId: 'msg123', user: 'user123' },
{ $push: { attachments: { file_id: `concurrent-${collisions}` } } },
);
}
return original(...args);
});
try {
expect(await updateToolCallResult(patch)).toEqual({ matched: false, unfinished: false });
expect(collisions).toBe(8);
const saved = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
expect(saved?.content?.[0]).toEqual(stepless);
expect(saved?.attachments).toHaveLength(8);
} finally {
spy.mockRestore();
}
expect(await updateToolCallResult(patch)).toEqual({ matched: true, unfinished: false });
const saved = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
expect(saved?.content?.[0]).toEqual(stepless);
expect(saved?.content?.[1]).toMatchObject({
tool_call: { output: 'settled', backgroundTask: patch.backgroundTask },
});
expect(saved?.attachments).toHaveLength(9);
});
describe.each([false, true])('fallback with attachments: %s', (withAttachments) => {
it.each(['exact', 'ambiguous', 'unfinished', 'claimed'])(
'leaves a concurrent %s change intact and retryable',
async (change) => {
await saveMessage(mockCtx, { ...mockMessageData, content: toolCallContent() });
const claim = { kind: 'manual', claimId: 'concurrent-poll', claimedAt: new Date() };
const original = Message.collection.findOneAndUpdate.bind(Message.collection);
let raced = false;
let concurrentContent: IMessage['content'];
const spy = jest
.spyOn(Message.collection, 'findOneAndUpdate')
.mockImplementation(async (...args) => {
if (
!raced &&
(Array.isArray(args[0].content) ||
args[0].content?.$elemMatch?.['tool_call.stepId'] === null)
) {
raced = true;
const filter = { messageId: 'msg123', user: 'user123' };
if (change === 'unfinished') {
await Message.updateOne(filter, { $set: { unfinished: true } });
} else if (change === 'claimed') {
await Message.updateOne(filter, {
$set: { 'content.1.tool_call.backgroundTask.resultClaim': claim },
});
} else {
await Message.updateOne(filter, {
$push: {
content: {
type: 'tool_call',
tool_call: {
id: 'call_bg',
output: 'concurrent',
...(change === 'exact' ? { stepId: 'step_a' } : {}),
},
},
},
});
}
concurrentContent = (
await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean()
)?.content;
}
return original(...args);
});
try {
const result = await updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: conversationId(),
toolCallId: 'call_bg',
stepId: 'step_a',
output: 'settled',
...(withAttachments
? { attachments: [{ file_id: 'result', toolCallId: 'call_bg' }] }
: {}),
backgroundTask: {
taskId: 'task-a',
toolName: 'execute_code',
status: 'completed',
settledAt: new Date(),
resultClaim: { kind: 'wakeup', claimId: 'wakeup-a', claimedAt: new Date() },
},
});
expect(raced).toBe(true);
expect(result).toEqual({ matched: false, unfinished: false });
const saved = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
expect(saved?.content).toEqual(concurrentContent);
expect(saved?.attachments ?? []).toEqual([]);
} finally {
spy.mockRestore();
}
},
);
});
it.each([undefined, null, { kind: 'manual', claimId: 'existing', claimedAt: new Date() }])(
'atomically settles a fallback while preserving claim ownership: %j',
async (resultClaim) => {
await saveMessage(mockCtx, {
...mockMessageData,
content: [
{
type: 'tool_call',
tool_call: {
id: 'call_bg',
stepId: null,
output: 'handle',
backgroundTask: { resultClaim },
},
},
],
});
const backgroundTask = {
taskId: 'task-a',
toolName: 'execute_code',
status: 'completed' as const,
settledAt: new Date(),
resultClaim: { kind: 'wakeup' as const, claimId: 'new', claimedAt: new Date() },
};
expect(
await updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: conversationId(),
toolCallId: 'call_bg',
stepId: 'step_a',
output: 'settled',
backgroundTask,
}),
).toEqual({ matched: true, unfinished: false });
const saved = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
expect(saved?.content?.[0]).toMatchObject({
tool_call: {
stepId: null,
output: 'settled',
backgroundTask: {
...backgroundTask,
resultClaim: resultClaim ?? backgroundTask.resultClaim,
},
},
});
},
);
it.each([
{ partAgent: 'agent-a', callAgent: 'agent-b', matched: true },
{ partAgent: 'agent-b', callAgent: 'agent-a', matched: false },
{ partAgent: null, callAgent: 'agent-a', matched: true },
{ partAgent: null, callAgent: 'agent-b', matched: false },
{ partAgent: null, callAgent: null, matched: true },
])(
'keeps agent ownership when falling back: %j',
async ({ partAgent, callAgent, matched }) => {
await saveMessage(mockCtx, {
...mockMessageData,
content: [
{
type: 'tool_call',
agentId: partAgent,
tool_call: { id: 'call_bg', agentId: callAgent, stepId: null, output: 'handle' },
},
{
type: 'tool_call',
agentId: 'agent-b',
tool_call: { id: 'call_bg', stepId: 'step_a', output: 'sibling' },
},
],
});
expect(
await updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: conversationId(),
toolCallId: 'call_bg',
agentId: 'agent-a',
stepId: 'step_a',
output: 'settled',
}),
).toEqual({ matched, unfinished: false });
expect(await partOutputs()).toEqual([
['call_bg', null, matched ? 'settled' : 'handle'],
['call_bg', 'step_a', 'sibling'],
]);
},
);
it('does not guess on a row the turn is still writing', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
unfinished: true,
content: toolCallContent(),
});
const result = await updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: conversationId(),
toolCallId: 'call_bg',
stepId: 'step_not_saved_yet',
output: 'settled',
});
expect(result).toEqual({ matched: false, unfinished: false });
expect((await partOutputs())[0]).toEqual([
'call_bg',
null,
'{"background_task_id":"task-1"}',
]);
});
it('leaves an ambiguous repeated call id unmatched rather than guessing', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
content: [
{
type: 'tool_call',
tool_call: { id: 'call_0', name: 'execute_code', output: 'first' },
},
{
type: 'tool_call',
tool_call: { id: 'call_0', name: 'execute_code', output: 'second' },
},
],
});
const result = await updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: conversationId(),
toolCallId: 'call_0',
stepId: 'step_lost',
output: 'settled',
});
expect(result).toEqual({ matched: false, unfinished: false });
expect(await partOutputs()).toEqual([
['call_0', null, 'first'],
['call_0', null, 'second'],
]);
});
});
it('appends to existing attachments instead of replacing them', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
content: toolCallContent(),
attachments: [{ file_id: 'existing' }] as unknown as IMessage['attachments'],
});
await updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: mockMessageData.conversationId as string,
toolCallId: 'call_bg',
attachments: [{ file_id: 'f2' }],
});
const saved = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
expect(saved?.attachments).toEqual([{ file_id: 'existing' }, { file_id: 'f2' }]);
});
it('is idempotent: re-applying the same patch does not duplicate attachments', async () => {
await saveMessage(mockCtx, { ...mockMessageData, content: toolCallContent() });
const patch = {
userId: 'user123',
messageId: 'msg123',
conversationId: mockMessageData.conversationId as string,
toolCallId: 'call_bg',
output: 'stdout:\nhello',
attachments: [{ file_id: 'f1', toolCallId: 'call_bg' }],
};
await updateToolCallResult(patch);
await updateToolCallResult(patch);
const saved = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
expect(saved?.attachments).toEqual([{ file_id: 'f1', toolCallId: 'call_bg' }]);
const content = saved?.content as Array<{ tool_call?: { output?: string } }>;
expect(content[1].tool_call?.output).toBe('stdout:\nhello');
});
it('dedupes download-fallback attachments (no file_id) by filepath on re-apply', async () => {
await saveMessage(mockCtx, { ...mockMessageData, content: toolCallContent() });
const patch = {
userId: 'user123',
messageId: 'msg123',
conversationId: mockMessageData.conversationId as string,
toolCallId: 'call_bg',
attachments: [
{
filepath: '/api/files/code/download/sess-1/f1',
filename: 'big.zip',
toolCallId: 'call_bg',
},
{ file_id: 'f2', toolCallId: 'call_bg' },
],
};
await updateToolCallResult(patch);
await updateToolCallResult(patch);
const saved = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
expect(saved?.attachments).toEqual([
{
filepath: '/api/files/code/download/sess-1/f1',
filename: 'big.zip',
toolCallId: 'call_bg',
},
{ file_id: 'f2', toolCallId: 'call_bg' },
]);
});
it('returns false when the message row does not exist yet (caller retries)', async () => {
const result = await updateToolCallResult({
userId: 'user123',
messageId: 'missing-msg',
conversationId: mockMessageData.conversationId as string,
toolCallId: 'call_bg',
output: 'stdout',
});
expect(result.matched).toBe(false);
});
it('scopes the patch by agentId when provider ids repeat across agents', async () => {
/* Handoff runs append multiple agents' parts to ONE response message,
* and provider ids like call_0 repeat per model response. */
await saveMessage(mockCtx, {
...mockMessageData,
content: [
{
type: 'tool_call',
agentId: 'agent_a',
tool_call: { id: 'call_0', name: 'execute_code', output: 'handle-a' },
},
{
type: 'tool_call',
agentId: 'agent_b',
tool_call: { id: 'call_0', name: 'execute_code', output: 'handle-b' },
},
],
});
const result = await updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: mockMessageData.conversationId as string,
toolCallId: 'call_0',
agentId: 'agent_b',
output: 'stdout-b',
});
expect(result.matched).toBe(true);
const saved = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
const content = saved?.content as Array<{ tool_call?: { output?: string } }>;
expect(content[0].tool_call?.output).toBe('handle-a');
expect(content[1].tool_call?.output).toBe('stdout-b');
});
it('patches only the matching run step when one agent repeats a provider id', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
content: [
{
type: 'tool_call',
agentId: 'agent_a',
tool_call: { id: 'call_0', stepId: 'step-1', name: 'slow_tool', output: 'handle-1' },
},
{
type: 'tool_call',
agentId: 'agent_a',
tool_call: { id: 'call_0', stepId: 'step-2', name: 'slow_tool', output: 'handle-2' },
},
],
});
const result = await updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: mockMessageData.conversationId as string,
toolCallId: 'call_0',
stepId: 'step-2',
agentId: 'agent_a',
output: 'terminal-2',
backgroundTask: {
taskId: 'task-2',
toolName: 'slow_tool',
status: 'completed',
settledAt: new Date(),
},
});
expect(result).toEqual({ matched: true, unfinished: false });
const saved = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
const content = saved?.content as Array<{
tool_call?: { output?: string; backgroundTask?: { taskId?: string } };
}>;
expect(content[0].tool_call).toMatchObject({ output: 'handle-1' });
expect(content[0].tool_call?.backgroundTask).toBeUndefined();
expect(content[1].tool_call).toMatchObject({
output: 'terminal-2',
backgroundTask: { taskId: 'task-2' },
});
});
it('reports no match when the targeted tool-call part is absent', async () => {
/** The call was saved under a different, stamped step: a real mismatch, not
* a part that lost its step id. */
await saveMessage(mockCtx, {
...mockMessageData,
content: toolCallContent().map((part) =>
part.tool_call?.id === 'call_bg'
? { ...part, tool_call: { ...part.tool_call, stepId: 'other-step' } }
: part,
),
});
await expect(
updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: mockMessageData.conversationId as string,
toolCallId: 'call_bg',
stepId: 'missing-step',
output: 'must not persist',
}),
).resolves.toEqual({ matched: false, unfinished: false });
});
it('flags unfinished partial rows so callers keep re-applying until finalize', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
content: toolCallContent(),
unfinished: true,
} as Parameters<typeof saveMessage>[1]);
const result = await updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: mockMessageData.conversationId as string,
toolCallId: 'call_bg',
output: 'stdout:\nhello',
});
/** The patch still lands (idempotent), but the finalize save will
* overwrite this partial row with in-memory content. */
expect(result).toEqual({ matched: true, unfinished: true });
});
it('persists a terminal background receipt without replacing its existing claim', async () => {
const content = toolCallContent();
(content[1].tool_call as Record<string, unknown>).backgroundTask = {
version: 1,
taskId: 'task-1',
toolName: 'execute_code',
status: 'completed',
settledAt: new Date('2026-08-30T12:00:00Z'),
resultClaim: {
kind: 'manual',
claimId: 'manual-1',
claimedAt: new Date('2026-08-30T12:00:01Z'),
},
};
await saveMessage(mockCtx, { ...mockMessageData, content });
await updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: mockMessageData.conversationId as string,
toolCallId: 'call_bg',
output: 'terminal output',
backgroundTask: {
taskId: 'task-1',
toolName: 'execute_code',
status: 'completed',
settledAt: new Date('2026-08-30T12:00:02Z'),
resultClaim: {
kind: 'wakeup',
claimId: 'wakeup-1',
claimedAt: new Date('2026-08-30T12:00:02Z'),
},
},
});
const saved = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
const task = (
saved?.content?.[1] as {
tool_call?: { backgroundTask?: Record<string, unknown> };
}
).tool_call?.backgroundTask;
expect(task).toMatchObject({
version: 1,
taskId: 'task-1',
status: 'completed',
resultClaim: { kind: 'manual', claimId: 'manual-1' },
});
});
it('stamps a supplied claim only on a part that carries none', async () => {
await saveMessage(mockCtx, { ...mockMessageData, content: toolCallContent() });
await updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: mockMessageData.conversationId as string,
toolCallId: 'call_bg',
backgroundTask: {
taskId: 'task-1',
toolName: 'execute_code',
status: 'completed',
settledAt: new Date('2026-08-30T12:00:02Z'),
resultClaim: {
kind: 'wakeup',
claimId: 'wakeup-1',
claimedAt: new Date('2026-08-30T12:00:02Z'),
},
},
});
const saved = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
const task = (
saved?.content?.[1] as {
tool_call?: { backgroundTask?: Record<string, unknown> };
}
).tool_call?.backgroundTask;
expect(task).toMatchObject({
taskId: 'task-1',
resultClaim: { kind: 'wakeup', claimId: 'wakeup-1' },
});
});
it('reports exhausted attachment-merge contention as unmatched instead of throwing', async () => {
await saveMessage(mockCtx, { ...mockMessageData, content: toolCallContent() });
const Message = mongoose.models.Message;
const casSpy = jest.spyOn(Message.collection, 'findOneAndUpdate').mockResolvedValue(null);
try {
/** A throw here escapes the settle retry loop and lands on ambiguous
* failure handling that can retire the completion; contention must
* surface as a retryable unmatched result. */
await expect(
updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: mockMessageData.conversationId as string,
toolCallId: 'call_bg',
output: 'settled output',
attachments: [{ file_id: 'file-contended', toolCallId: 'call_bg' }],
}),
).resolves.toEqual({ matched: false, unfinished: false });
expect(casSpy.mock.calls.length).toBeGreaterThanOrEqual(8);
} finally {
casSpy.mockRestore();
}
});
it('disarms a previously armed completion wakeup when the new receipt omits it', async () => {
const content = toolCallContent();
(content[1].tool_call as Record<string, unknown>).backgroundTask = {
version: 1,
taskId: 'task-1',
toolName: 'execute_code',
status: 'completed',
settledAt: new Date('2026-08-30T12:00:00Z'),
completionWakeup: true,
};
await saveMessage(mockCtx, { ...mockMessageData, content });
await updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: mockMessageData.conversationId as string,
toolCallId: 'call_bg',
backgroundTask: {
taskId: 'task-1',
toolName: 'execute_code',
status: 'error',
settledAt: new Date('2026-08-30T12:00:02Z'),
},
});
const saved = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
const task = (
saved?.content?.[1] as {
tool_call?: { backgroundTask?: Record<string, unknown> };
}
).tool_call?.backgroundTask;
expect(task).toMatchObject({ taskId: 'task-1', status: 'error' });
expect(task).not.toHaveProperty('completionWakeup');
});
it('lets a same-generation manual poll claim an anchored terminal receipt', async () => {
const settledAt = new Date('2026-09-22T09:00:00.000Z');
await saveMessage(mockCtx, {
...mockMessageData,
unfinished: true,
content: [
{
type: 'tool_call',
agentId: 'agent-a',
tool_call: {
id: 'call-same-generation',
name: 'slow_tool',
output: 'settled output',
backgroundTask: {
version: 1,
taskId: 'task-same-generation',
toolName: 'slow_tool',
status: 'completed',
settledAt,
completionWakeup: true,
},
},
},
],
});
await expect(
claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
taskId: 'task-same-generation',
kind: 'wakeup',
claimId: 'automatic-delivery',
}),
).resolves.toEqual({ status: 'not_ready' });
await expect(
claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
taskId: 'task-same-generation',
kind: 'manual',
claimId: 'manual-poll',
}),
).resolves.toEqual({ status: 'not_ready' });
await expect(
claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
taskId: 'task-same-generation',
kind: 'manual',
claimId: 'manual-poll',
allowUnfinished: true,
}),
).resolves.toEqual({
status: 'acquired',
results: [
{
taskId: 'task-same-generation',
toolCallId: 'call-same-generation',
toolName: 'slow_tool',
status: 'completed',
output: 'settled output',
agentId: 'agent-a',
/** Carried through so a poll can report when the task settled. */
settledAt,
},
],
});
});
it('restores same-generation claim ownership after the final response save', async () => {
const terminalContent = [
{
type: 'tool_call',
tool_call: {
id: 'call-finalize-race',
name: 'mutating_tool',
output: 'mutation completed',
backgroundTask: {
version: 1,
taskId: 'task-finalize-race',
toolName: 'mutating_tool',
status: 'completed',
settledAt: new Date(),
completionWakeup: true,
},
},
},
];
await saveMessage(mockCtx, {
...mockMessageData,
unfinished: true,
content: terminalContent,
});
await expect(
claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
taskId: 'task-finalize-race',
kind: 'manual',
claimId: 'manual-owner',
generationId: 'response-finalize-owner',
allowUnfinished: true,
}),
).resolves.toMatchObject({ status: 'acquired' });
/** The final in-memory response did not observe the concurrent claim and
* rewrites the content part without it. The detached persistence retry
* must restore the mirrored owner before the receipt can be replayed. */
await saveMessage(mockCtx, {
...mockMessageData,
unfinished: false,
content: terminalContent,
});
await updateToolCallResult({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
toolCallId: 'call-finalize-race',
output: 'mutation completed',
backgroundTask: {
taskId: 'task-finalize-race',
toolName: 'mutating_tool',
status: 'completed',
settledAt: new Date(),
completionWakeup: true,
resultClaim: {
kind: 'manual',
claimId: 'manual-owner',
claimedAt: new Date(),
generationId: 'response-finalize-owner',
},
},
});
await expect(
claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
taskId: 'task-finalize-race',
kind: 'manual',
claimId: 'competing-owner',
}),
).resolves.toEqual({
status: 'claimed',
claim: {
kind: 'manual',
claimId: 'manual-owner',
generationId: 'response-finalize-owner',
},
});
});
it('recovers an unclaimed terminal receipt by task id after process-local state is lost', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
content: [
{
type: 'tool_call',
agentId: 'agent-a',
tool_call: {
id: 'call-recovered',
name: 'slow_tool',
output: 'durable result',
backgroundTask: {
version: 1,
taskId: 'task-recovered',
toolName: 'slow_tool',
status: 'completed',
settledAt: new Date(),
},
},
},
],
});
const recovery = {
status: 'acquired',
messageId: 'msg123',
results: [
{
taskId: 'task-recovered',
toolCallId: 'call-recovered',
toolName: 'slow_tool',
status: 'completed',
output: 'durable result',
agentId: 'agent-a',
settledAt: expect.any(Date),
},
],
};
const recover = () =>
claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
taskId: 'task-recovered',
agentId: 'agent-a',
kind: 'manual',
claimId: 'recovery-poll',
generationId: 'response-recovery-owner',
});
await expect(recover()).resolves.toEqual(recovery);
await expect(recover()).resolves.toEqual(recovery);
await expect(
claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
taskId: 'task-recovered',
agentId: 'agent-a',
kind: 'manual',
claimId: 'competing-poll',
}),
).resolves.toEqual({
status: 'claimed',
messageId: 'msg123',
claim: {
kind: 'manual',
claimId: 'recovery-poll',
generationId: 'response-recovery-owner',
},
});
await expect(
claimBackgroundToolResults({
userId: 'another-user',
conversationId: mockMessageData.conversationId as string,
taskId: 'task-recovered',
kind: 'manual',
claimId: 'cross-user-poll',
}),
).resolves.toEqual({ status: 'not_found' });
});
it('reports an exact durable launch handle as outcome unknown after executor loss', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
content: [
{
type: 'tool_call',
agentId: 'agent-a',
tool_call: {
id: 'call-lost',
name: 'mutating_tool',
output: JSON.stringify({
background_task_id: 'task-lost',
tool: 'mutating_tool',
status: 'running',
message: 'Use check_background_task to poll.',
}),
},
},
],
});
await expect(
claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
taskId: 'task-lost',
agentId: 'agent-a',
kind: 'manual',
claimId: 'recovery-poll',
}),
).resolves.toEqual({ status: 'outcome_unknown', toolName: 'mutating_tool' });
await expect(
claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
taskId: 'task-lost',
agentId: 'agent-b',
kind: 'manual',
claimId: 'wrong-agent-poll',
}),
).resolves.toEqual({ status: 'not_found' });
});
it('leaves a durable subagent handle to the routed subagent store', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
content: [
{
type: 'tool_call',
tool_call: {
id: 'call-subagent',
name: 'subagent',
output: JSON.stringify({
background_task_id: 'task-subagent',
subagent_thread_id: 'thread-subagent',
tool: 'subagent',
subagent_type: 'researcher',
status: 'running',
progress: 0,
}),
},
},
],
});
await expect(
claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
taskId: 'task-subagent',
kind: 'manual',
claimId: 'subagent-poll',
}),
).resolves.toEqual({ status: 'not_found' });
});
it('claims a terminal result whose persisted claim stamp is a stored null', async () => {
/** A full-row save can persist `resultClaim: null`, and the
* subfield-preserving settle write keeps it where the old whole-object
* rewrite dropped it. Every layer must read that as unclaimed — a
* `$exists: false` fence would strand the part as terminal but
* permanently unclaimable. */
await saveMessage(mockCtx, {
...mockMessageData,
content: [
{
type: 'tool_call',
tool_call: {
id: 'call-null-claim',
name: 'slow_tool',
output: 'done',
backgroundTask: {
version: 1,
taskId: 'task-null-claim',
toolName: 'slow_tool',
status: 'completed',
settledAt: new Date(),
completionWakeup: true,
resultClaim: null,
},
},
},
],
});
/** The stored stamp must actually BE null, or this test proves nothing. */
const stored = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
const storedTask = (
stored?.content?.[0] as { tool_call?: { backgroundTask?: Record<string, unknown> } }
).tool_call?.backgroundTask;
expect(storedTask).toHaveProperty('resultClaim', null);
const claim = await claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
taskId: 'task-null-claim',
kind: 'wakeup',
claimId: 'delivery-null',
});
expect(claim.status).toBe('acquired');
});
it('claims a cancelled ordinary background-tool result as terminal evidence', async () => {
await saveMessage(mockCtx, {
...mockMessageData,
content: [
{
type: 'tool_call',
tool_call: {
id: 'call-cancelled-tool',
name: 'bash_tool',
output: 'Background task cancellation requested',
backgroundTask: {
version: 1,
taskId: 'task-cancelled-tool',
toolName: 'bash_tool',
status: 'error',
cancelled: true,
settledAt: new Date(),
completionWakeup: true,
},
},
},
],
});
await expect(
claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
taskId: 'task-cancelled-tool',
kind: 'wakeup',
claimId: 'delivery-cancelled-tool',
}),
).resolves.toEqual({
status: 'acquired',
results: [
{
taskId: 'task-cancelled-tool',
toolCallId: 'call-cancelled-tool',
toolName: 'bash_tool',
status: 'cancelled',
output: 'Background task cancellation requested',
settledAt: expect.any(Date),
},
],
});
});
it('elects one result consumer and batches terminal siblings for a wakeup', async () => {
const terminal = (id: string, taskId: string, output: string) => ({
type: 'tool_call',
agentId: 'agent-a',
tool_call: {
id,
name: 'slow_tool',
output,
backgroundTask: {
version: 1,
taskId,
toolName: 'slow_tool',
status: 'completed',
settledAt: new Date(),
completionWakeup: true,
},
},
});
await saveMessage(mockCtx, {
...mockMessageData,
content: [terminal('call-1', 'task-1', 'one'), terminal('call-2', 'task-2', 'two')],
});
const wakeup = await claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
taskId: 'task-1',
kind: 'wakeup',
claimId: 'delivery-1',
});
expect(wakeup).toEqual({
status: 'acquired',
results: [
{
taskId: 'task-1',
toolCallId: 'call-1',
toolName: 'slow_tool',
status: 'completed',
output: 'one',
agentId: 'agent-a',
settledAt: expect.any(Date),
},
{
taskId: 'task-2',
toolCallId: 'call-2',
toolName: 'slow_tool',
status: 'completed',
output: 'two',
agentId: 'agent-a',
settledAt: expect.any(Date),
},
],
});
await Message.updateOne(
{ messageId: 'msg123', user: 'user123' },
{ $push: { content: terminal('call-3', 'task-3', 'three') } },
);
await expect(
claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
taskId: 'task-1',
kind: 'wakeup',
claimId: 'delivery-1',
}),
).resolves.toEqual(wakeup);
await expect(
claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
taskId: 'task-2',
kind: 'manual',
claimId: 'poll-1',
}),
).resolves.toEqual({
status: 'claimed',
claim: { kind: 'wakeup', claimId: 'delivery-1' },
});
/** V1 producers have no completionReceipt marker, but the V1 resolver
* acquires resultClaim before delivery. A later batch must exclude it. */
await expect(
claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
taskId: 'task-3',
kind: 'wakeup',
claimId: 'delivery-2',
}),
).resolves.toMatchObject({
status: 'acquired',
results: [{ taskId: 'task-3', output: 'three' }],
});
});
it.each([true, false])(
'keeps independent receipt ownership out of message batches (root=%s)',
async (receiptRoot) => {
const terminal = (taskId: string, receipt: boolean) => ({
type: 'tool_call',
tool_call: {
id: taskId,
output: taskId,
backgroundTask: {
taskId,
toolName: 'tool',
status: 'completed',
completionWakeup: true,
...(receipt ? { completionReceipt: true } : {}),
},
},
});
await saveMessage(mockCtx, {
...mockMessageData,
content: [
terminal('root', receiptRoot),
terminal('independent', true),
terminal('message-only', false),
],
});
const input = {
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
taskId: 'root',
kind: 'wakeup' as const,
claimId: 'delivery',
limit: 16,
};
const claim = await claimBackgroundToolResults(input);
expect(claim.status).toBe('acquired');
if (claim.status !== 'acquired') throw new Error('Expected acquired claim');
expect(claim.results.map((r) => r.taskId)).toEqual(
receiptRoot ? ['root'] : ['root', 'message-only'],
);
await expect(claimBackgroundToolResults({ ...input, limit: 1 })).resolves.toEqual(claim);
await expect(
claimBackgroundToolResults({ ...input, taskId: 'independent', claimId: 'other' }),
).resolves.toMatchObject({
status: 'acquired',
results: [{ taskId: 'independent' }],
});
},
);
it('bounds escaped metadata before claiming and freezes membership across competing same-owner preparations', async () => {
const ids = Array.from({ length: 16 }, (_, i) => `${i}${'\u0001'.repeat(250)}`);
const terminal = (id: string) => ({
type: 'tool_call',
tool_call: {
id,
output: 'done',
backgroundTask: {
taskId: id,
toolName: '\u0001'.repeat(256),
status: 'completed',
completionWakeup: true,
},
},
});
await saveMessage(mockCtx, { ...mockMessageData, content: ids.map(terminal) });
const input = {
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
taskId: ids[15],
kind: 'wakeup' as const,
claimId: 'delivery',
limit: 16,
maxMetadataChars: 16 * 1024 - 256,
};
const attempts = await Promise.all([
claimBackgroundToolResults(input),
claimBackgroundToolResults(input),
]);
const claim = attempts.find((result) => result.status === 'acquired');
if (claim?.status !== 'acquired') throw new Error('No claim elected');
expect(claim.results.some((r) => r.taskId === ids[15])).toBe(true);
expect(claim.results.length).toBeLessThan(16);
expect(
JSON.stringify(claim.results.map(backgroundResultMetadata)).length,
).toBeLessThanOrEqual(input.maxMetadataChars);
await Message.updateOne(
{ messageId: 'msg123', user: 'user123' },
{ $push: { content: terminal('late') } },
);
await expect(claimBackgroundToolResults({ ...input, limit: 1 })).resolves.toEqual(claim);
await expect(
claimBackgroundToolResults({ ...input, taskId: 'late', claimId: 'later' }),
).resolves.toMatchObject({ status: 'acquired' });
});
it('revalidates each sibling inside the atomic batch claim', async () => {
const terminal = (taskId: string) => ({
type: 'tool_call',
tool_call: {
id: `call-${taskId}`,
name: 'slow_tool',
output: taskId,
backgroundTask: {
version: 1,
taskId,
toolName: 'slow_tool',
status: 'completed',
settledAt: new Date(),
completionWakeup: true,
},
},
});
await saveMessage(mockCtx, {
...mockMessageData,
content: [terminal('root'), terminal('stale-sibling')],
});
const originalFindOneAndUpdate = Message.collection.findOneAndUpdate.bind(Message.collection);
const claimWrite = jest
.spyOn(Message.collection, 'findOneAndUpdate')
.mockImplementationOnce(async (...args) => {
await Message.collection.updateOne(
{ user: 'user123', messageId: 'msg123' },
{ $set: { 'content.1.tool_call.backgroundTask.status': 'running' } },
);
return originalFindOneAndUpdate(...args);
});
try {
await expect(
claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
taskId: 'root',
kind: 'wakeup',
claimId: 'delivery-root',
}),
).resolves.toMatchObject({
status: 'acquired',
results: [expect.objectContaining({ taskId: 'root' })],
});
} finally {
claimWrite.mockRestore();
}
const saved = await Message.findOne({ user: 'user123', messageId: 'msg123' }).lean();
expect(saved?.content?.[1]).not.toHaveProperty('tool_call.backgroundTask.resultClaim');
});
it('does not batch a terminal sibling that elected poll-only delivery', async () => {
const terminal = (taskId: string, completionWakeup: boolean) => ({
type: 'tool_call',
tool_call: {
id: `call-${taskId}`,
name: 'slow_tool',
output: taskId,
backgroundTask: {
version: 1,
taskId,
toolName: 'slow_tool',
status: 'completed',
settledAt: new Date(),
...(completionWakeup ? { completionWakeup: true } : {}),
},
},
});
await saveMessage(mockCtx, {
...mockMessageData,
content: [terminal('wakeup', true), terminal('poll-only', false)],
});
await expect(
claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
taskId: 'wakeup',
kind: 'wakeup',
claimId: 'delivery-1',
}),
).resolves.toMatchObject({
status: 'acquired',
results: [expect.objectContaining({ taskId: 'wakeup' })],
});
await expect(
claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
taskId: 'poll-only',
kind: 'manual',
claimId: 'poll-1',
}),
).resolves.toMatchObject({
status: 'acquired',
results: [expect.objectContaining({ taskId: 'poll-only' })],
});
});
it('uses nested tool-call agent identity when batching sibling results', async () => {
const backgroundTask = (taskId: string) => ({
version: 1,
taskId,
toolName: 'slow_tool',
status: 'completed',
settledAt: new Date(),
completionWakeup: true,
});
await saveMessage(mockCtx, {
...mockMessageData,
content: [
{
type: 'tool_call',
agentId: 'agent-a',
tool_call: {
id: 'call-a',
name: 'slow_tool',
output: 'a',
backgroundTask: backgroundTask('task-a'),
},
},
{
type: 'tool_call',
tool_call: {
id: 'call-b',
agentId: 'agent-b',
name: 'slow_tool',
output: 'b',
backgroundTask: backgroundTask('task-b'),
},
},
],
});
await expect(
claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
taskId: 'task-a',
agentId: 'agent-a',
kind: 'wakeup',
claimId: 'delivery-a',
}),
).resolves.toEqual({
status: 'acquired',
results: [
{
taskId: 'task-a',
toolCallId: 'call-a',
toolName: 'slow_tool',
status: 'completed',
output: 'a',
agentId: 'agent-a',
settledAt: expect.any(Date),
},
],
});
await expect(
claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
taskId: 'task-b',
agentId: 'agent-b',
kind: 'manual',
claimId: 'poll-b',
}),
).resolves.toMatchObject({
status: 'acquired',
results: [expect.objectContaining({ taskId: 'task-b', agentId: 'agent-b' })],
});
});
it('releases only the exact wakeup batch claim', async () => {
const task = {
version: 1,
toolName: 'slow_tool',
status: 'completed',
settledAt: new Date(),
resultClaim: { kind: 'wakeup', claimId: 'delivery-1', claimedAt: new Date() },
};
await saveMessage(mockCtx, {
...mockMessageData,
content: [
{
type: 'tool_call',
tool_call: {
id: 'call-1',
name: 'slow_tool',
output: 'one',
backgroundTask: { ...task, taskId: 'task-1' },
},
},
{
type: 'tool_call',
tool_call: {
id: 'call-2',
name: 'slow_tool',
output: 'two',
backgroundTask: {
...task,
taskId: 'task-2',
resultClaim: { kind: 'manual', claimId: 'poll-1', claimedAt: new Date() },
},
},
},
{
type: 'tool_call',
tool_call: {
id: 'call-3',
name: 'slow_tool',
output: 'three',
backgroundTask: { ...task, taskId: 'task-3' },
},
},
],
});
await expect(
releaseBackgroundToolResultClaims({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
kind: 'wakeup',
claimId: 'delivery-1',
}),
).resolves.toBe(true);
await expect(
claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
taskId: 'task-1',
kind: 'manual',
claimId: 'poll-2',
}),
).resolves.toMatchObject({ status: 'acquired' });
await expect(
claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
taskId: 'task-3',
kind: 'manual',
claimId: 'poll-3',
}),
).resolves.toMatchObject({ status: 'acquired' });
await expect(
claimBackgroundToolResults({
userId: 'user123',
conversationId: mockMessageData.conversationId as string,
messageId: 'msg123',
taskId: 'task-2',
kind: 'wakeup',
claimId: 'delivery-2',
}),
).resolves.toEqual({
status: 'claimed',
claim: { kind: 'manual', claimId: 'poll-1' },
});
});
it('keeps a sibling AGENT’s attachment when both id and file key collide', async () => {
/* Handoff agents can share a provider tool-call id AND a claimed
* file_id (same filename in one conversation); the second agent's
* anchor must not evict the first agent's card-scoped attachment. */
await saveMessage(mockCtx, { ...mockMessageData, content: toolCallContent() });
await updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: mockMessageData.conversationId as string,
toolCallId: 'call_bg',
agentId: 'agent_a',
attachments: [{ file_id: 'shared', toolCallId: 'call_bg', agentId: 'agent_a' }],
});
await updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: mockMessageData.conversationId as string,
toolCallId: 'call_bg',
agentId: 'agent_b',
attachments: [{ file_id: 'shared', toolCallId: 'call_bg', agentId: 'agent_b' }],
});
const saved = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
expect(saved?.attachments).toEqual([
{ file_id: 'shared', toolCallId: 'call_bg', agentId: 'agent_a' },
{ file_id: 'shared', toolCallId: 'call_bg', agentId: 'agent_b' },
]);
});
it('keeps a sibling tool call’s attachment when file ids repeat across calls', async () => {
await saveMessage(mockCtx, { ...mockMessageData, content: toolCallContent() });
await updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: mockMessageData.conversationId as string,
toolCallId: 'call_bg',
attachments: [{ file_id: 'shared', toolCallId: 'call_bg' }],
});
/** A second background call regenerated the same filename — same
* claimed file_id, different tool call. The first card must keep
* its attachment (the client anchors by toolCallId). */
await updateToolCallResult({
userId: 'user123',
messageId: 'msg123',
conversationId: mockMessageData.conversationId as string,
toolCallId: 'call_other',
attachments: [{ file_id: 'shared', toolCallId: 'call_other' }],
});
const saved = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
expect(saved?.attachments).toEqual([
{ file_id: 'shared', toolCallId: 'call_bg' },
{ file_id: 'shared', toolCallId: 'call_other' },
]);
});
it('does not match another user’s message', async () => {
await saveMessage(mockCtx, { ...mockMessageData, content: toolCallContent() });
const result = await updateToolCallResult({
userId: 'someone-else',
messageId: 'msg123',
conversationId: mockMessageData.conversationId as string,
toolCallId: 'call_bg',
output: 'hijacked',
});
expect(result.matched).toBe(false);
const saved = await Message.findOne({ messageId: 'msg123', user: 'user123' }).lean();
const content = saved?.content as Array<{ tool_call?: { output?: string } }>;
expect(content[1].tool_call?.output).toBe('{"background_task_id":"task-1"}');
});
});
describe('CLIENT_MESSAGE_SELECT projection', () => {
it('strips server-internal fields and dead SERP verticals, keeping rendered data', async () => {
const conversationId = uuidv4();
await Message.create({
messageId: 'projected-msg',
conversationId,
user: 'user123',
isCreatedByUser: false,
sender: 'Agent',
text: 'visible text',
content: [
{ type: 'text', text: 'part text' },
{
type: 'tool_call',
tool_call: {
id: 'call-background',
backgroundTask: {
version: 1,
taskId: 'task-visible',
toolName: 'slow_tool',
status: 'completed',
settledAt: new Date(),
resultClaim: {
kind: 'wakeup',
claimId: 'private-delivery-identity',
claimedAt: new Date(),
},
},
},
},
],
tokenCount: 42,
conversationSignature: 'sig',
clientId: 'client-1',
invocationId: 7,
summary: 'legacy summary',
summaryTokenCount: 11,
contextMeta: { anything: true },
langfuseSampled: true,
langfuseDestinationIds: ['lf-1'],
langfuseRunId: 'run-1',
metadata: {
usage: { input: 10, output: 20 },
thoughtSignatures: { tool_1: 'opaque' },
},
subagentTask: {
attemptKey: 'private-attempt',
requestFingerprint: 'private-fingerprint',
status: 'running',
},
attachments: [
{
type: 'web_search',
toolCallId: 'tool_1',
web_search: {
turn: 0,
organic: [
{
title: 'Result',
link: 'https://example.com',
snippet: 'snippet',
sitelinks: [{ title: 'sub', link: 'https://example.com/sub' }],
highlights: ['raw scrape'],
},
],
topStories: [{ title: 'Story', link: 'https://example.com/s', highlights: ['x'] }],
references: [{ link: 'https://example.com', title: 'Result', type: 'link' }],
images: [{ imageUrl: 'https://example.com/i.png' }],
answerBox: { answer: '42' },
knowledgeGraph: { title: 'KG' },
peopleAlsoAsk: [{ question: 'q' }],
relatedSearches: ['related'],
news: [{ title: 'n' }],
videos: [{ title: 'v' }],
places: [{ title: 'p' }],
shopping: [{ title: 's' }],
},
},
],
});
const [message] = await getMessages(
{ conversationId, user: 'user123' },
CLIENT_MESSAGE_SELECT,
);
expect(message.text).toBe('visible text');
expect(message.content).toHaveLength(2);
const projectedTask = (
message.content?.[1] as { tool_call?: { backgroundTask?: Record<string, unknown> } }
).tool_call?.backgroundTask;
expect(projectedTask).toMatchObject({ taskId: 'task-visible' });
expect(projectedTask).not.toHaveProperty('resultClaim');
expect(message.tokenCount).toBe(42);
const metadata = message.metadata as Record<string, unknown>;
expect(metadata.usage).toBeDefined();
expect(metadata.thoughtSignatures).toBeUndefined();
const hidden = message as unknown as Record<string, unknown>;
for (const field of [
'_id',
'user',
'conversationSignature',
'clientId',
'invocationId',
'summary',
'summaryTokenCount',
'contextMeta',
'langfuseSampled',
'langfuseDestinationIds',
'langfuseRunId',
'subagentTask',
]) {
expect(hidden[field]).toBeUndefined();
}
type ProjectedWebSearch = {
turn: number;
organic: Array<Record<string, unknown>>;
topStories: Array<Record<string, unknown>>;
references: unknown[];
images: unknown[];
} & Record<string, unknown>;
const webSearch = (message.attachments?.[0] as { web_search: ProjectedWebSearch }).web_search;
expect(webSearch.turn).toBe(0);
expect(webSearch.organic[0].title).toBe('Result');
expect(webSearch.organic[0].link).toBe('https://example.com');
expect(webSearch.organic[0].snippet).toBe('snippet');
expect(webSearch.organic[0].sitelinks).toBeUndefined();
expect(webSearch.organic[0].highlights).toBeUndefined();
expect(webSearch.topStories[0].title).toBe('Story');
expect(webSearch.topStories[0].highlights).toBeUndefined();
expect(webSearch.references).toHaveLength(1);
expect(webSearch.images).toHaveLength(1);
/** `videos` stays: `turn…video…` citation markers resolve against it
* (the clipboard refTypeMap addresses it explicitly). */
expect(webSearch.videos).toHaveLength(1);
expect(webSearch.answerBox).toBeDefined();
for (const vertical of [
'knowledgeGraph',
'peopleAlsoAsk',
'relatedSearches',
'news',
'places',
'shopping',
]) {
expect(webSearch[vertical]).toBeUndefined();
}
});
});
describe('conversation fetch index', () => {
it('declares the compound index that serves the conversation fetch and its sort', () => {
const indexes = Message.schema.indexes() as Array<[Record<string, number>, unknown]>;
expect(indexes).toContainEqual([
{ conversationId: 1, user: 1, createdAt: 1, _id: 1 },
expect.anything(),
]);
});
});
describe('getMessages', () => {
it('should retrieve messages with the correct filter', async () => {
const conversationId = uuidv4();
// Save some messages
await saveMessage(mockCtx, {
messageId: 'msg1',
conversationId,
text: 'First message',
user: 'user123',
});
await saveMessage(mockCtx, {
messageId: 'msg2',
conversationId,
text: 'Second message',
user: 'user123',
});
const messages = await getMessages({ conversationId });
expect(messages).toHaveLength(2);
expect(messages[0].text).toBe('First message');
expect(messages[1].text).toBe('Second message');
});
it('should limit retrieved messages when requested', async () => {
const conversationId = uuidv4();
await saveMessage(mockCtx, {
messageId: 'msg1',
conversationId,
text: 'First message',
user: 'user123',
});
await saveMessage(mockCtx, {
messageId: 'msg2',
conversationId,
text: 'Second message',
user: 'user123',
});
await saveMessage(mockCtx, {
messageId: 'msg3',
conversationId,
text: 'Third message',
user: 'user123',
});
const messages = await getMessages({ conversationId }, undefined, { limit: 2 });
expect(messages).toHaveLength(2);
expect(messages[0].text).toBe('First message');
expect(messages[1].text).toBe('Second message');
});
});
describe('getMessagesForSubagentThreadView', () => {
it('projects recovery enrollment without exposing private journal metadata', async () => {
const conversationId = uuidv4();
for (const captured of [false, true, 'deleted'] as const) {
await saveMessage(mockCtx, {
messageId: `captured-${captured}:user`,
conversationId,
user: 'user123',
text: 'Input',
...(captured
? {
subagentContent: {
version: 1 as const,
throughSequence: 12,
...(captured === 'deleted' ? { deleted: true } : {}),
},
}
: {}),
});
}
const messages = await getMessagesForSubagentThreadView({
user: 'user123',
conversationId,
limit: 3,
textCodePointLimit: 100,
});
expect(messages).toEqual(
expect.arrayContaining([
expect.objectContaining({
messageId: 'captured-true:user',
contentRecoveryAvailable: true,
}),
expect.objectContaining({
messageId: 'captured-false:user',
contentRecoveryAvailable: false,
}),
expect.objectContaining({
messageId: 'captured-deleted:user',
contentRecoveryAvailable: false,
}),
]),
);
expect(JSON.stringify(messages)).not.toContain('subagentContent');
expect(JSON.stringify(messages)).not.toContain('throughSequence');
});
it('bounds text in MongoDB before returning the public projection', async () => {
const conversationId = uuidv4();
await saveMessage(mockCtx, {
messageId: 'bounded-message',
conversationId,
text: '🧵'.repeat(20_000),
user: 'user123',
});
const messages = await getMessagesForSubagentThreadView({
user: 'user123',
conversationId,
limit: 1,
textCodePointLimit: 8_192,
});
expect(messages).toHaveLength(1);
expect(Array.from(messages[0].text ?? '')).toHaveLength(8_192);
expect(Buffer.byteLength(messages[0].text ?? '', 'utf8')).toBeLessThanOrEqual(32 * 1024);
expect(messages[0].textProjectionTruncated).toBe(true);
expect(messages[0]).not.toHaveProperty('user');
expect(messages[0]).not.toHaveProperty('conversationId');
});
it('anchors older pages by an exact scoped message without exposing Mongo ids', async () => {
const conversationId = uuidv4();
for (let index = 0; index < 4; index += 1) {
await saveMessage(mockCtx, {
messageId: `task-${index}:assistant`,
conversationId,
text: `Answer ${index}`,
user: 'user123',
createdAt: new Date(Date.UTC(2026, 7, 21, 12, index)),
});
}
await saveMessage(mockCtx, {
messageId: 'foreign:user',
conversationId: uuidv4(),
text: 'Foreign anchor',
user: 'user123',
});
const page = await getMessagesForSubagentThreadView({
user: 'user123',
conversationId,
beforeMessageId: 'task-2:assistant',
limit: 2,
textCodePointLimit: 8_192,
});
const foreign = await getMessagesForSubagentThreadView({
user: 'user123',
conversationId,
beforeMessageId: 'foreign:user',
limit: 2,
textCodePointLimit: 8_192,
});
expect(page.map((message) => message.messageId)).toEqual([
'task-2:assistant',
'task-1:assistant',
]);
expect(page[0]).not.toHaveProperty('_id');
expect(foreign).toEqual([]);
});
it('projects only the bounded display-safe external event identity', async () => {
const conversationId = uuidv4();
await saveMessage(mockCtx, {
messageId: 'event:user',
conversationId,
text: 'Private event payload',
user: 'user123',
subagentTriggerProjection: {
version: 1,
eventType: 'chess.turn.ready',
sourceType: 'speed-chess',
occurredAt: new Date('2026-08-21T12:00:00.000Z'),
expectedActionToolName: 'submit_move',
},
});
const [projected] = await getMessagesForSubagentThreadView({
user: 'user123',
conversationId,
limit: 1,
textCodePointLimit: 8_192,
});
expect(projected.subagentTriggerProjection).toEqual({
version: 1,
eventType: 'chess.turn.ready',
sourceType: 'speed-chess',
occurredAt: new Date('2026-08-21T12:00:00.000Z'),
expectedActionToolName: 'submit_move',
});
expect(projected.subagentTriggerProjection).not.toHaveProperty('deliveryId');
expect(projected.subagentTriggerProjection).not.toHaveProperty('sourceId');
});
it('projects bounded private transcripts for the retained linear history', async () => {
const conversationId = uuidv4();
await saveMessage(mockCtx, {
messageId: 'task-a:assistant',
conversationId,
text: 'A',
user: 'user123',
subagentTranscript: {
taskId: 'task-a',
mode: 'append',
messagesJson: '[{"type":"ai","data":{"content":"A"}}]',
},
});
await saveMessage(mockCtx, {
messageId: 'task-b:assistant',
conversationId,
text: 'B',
user: 'user123',
subagentTranscript: {
taskId: 'task-b',
mode: 'append',
messagesJson: '[{"type":"ai","data":{"content":"B"}}]',
},
});
const messages = await getMessagesForSubagentThreadView({
user: 'user123',
conversationId,
limit: 10,
textCodePointLimit: 8_192,
});
expect(messages).toHaveLength(2);
expect(messages).toEqual(
expect.arrayContaining([
expect.objectContaining({
messageId: 'task-a:assistant',
subagentTranscript: expect.objectContaining({ taskId: 'task-a' }),
}),
expect.objectContaining({
messageId: 'task-b:assistant',
subagentTranscript: expect.objectContaining({ taskId: 'task-b' }),
}),
]),
);
});
it('keeps the budgeted timeline a contiguous newest suffix past an oversized entry', async () => {
const conversationId = uuidv4();
await saveMessage(mockCtx, {
messageId: 'task-suffix:assistant',
conversationId,
text: '',
user: 'user123',
content: [
...Array.from({ length: 5 }, (_, index) => ({
type: 'text',
text: `older-${index}`,
})),
...Array.from({ length: 8 }, (_, index) => ({
type: 'text',
text: `newest-${index}-${'b'.repeat(8_400)}`,
})),
],
});
const messages = await getMessagesForSubagentThreadView({
user: 'user123',
conversationId,
limit: 1,
textCodePointLimit: 8_192,
});
const activity = messages[0].subagentActivity as Array<{ type: string; text: string }>;
expect(activity.length).toBeGreaterThan(0);
expect(activity.length).toBeLessThan(8);
expect(activity.every((item) => item.text.startsWith('newest-'))).toBe(true);
expect(activity[activity.length - 1].text).toContain('newest-7-');
expect(JSON.stringify(activity)).not.toContain('older-');
expect(messages[0].subagentActivityProjectionTruncated).toBe(true);
});
it('fits ordinary persisted child activity into the aggregate byte budget, newest first', async () => {
const conversationId = uuidv4();
await saveMessage(mockCtx, {
messageId: 'task-budget:assistant',
conversationId,
text: '',
user: 'user123',
content: Array.from({ length: 12 }, (_, index) => ({
type: 'text',
text: `chunk-${index}-${'z'.repeat(8_000)}`,
})),
});
const messages = await getMessagesForSubagentThreadView({
user: 'user123',
conversationId,
limit: 1,
textCodePointLimit: 8_192,
});
const activity = messages[0].subagentActivity as Array<{ type: string; text: string }>;
expect(activity.length).toBeGreaterThan(0);
expect(activity.length).toBeLessThan(12);
expect(activity[activity.length - 1].text).toContain('chunk-11-');
expect(activity[0].text).toContain(`chunk-${12 - activity.length}-`);
const totalBytes = activity.reduce((sum, item) => sum + item.text.length, 0);
expect(totalBytes).toBeLessThanOrEqual(64 * 1024);
expect(messages[0].subagentActivityProjectionTruncated).toBe(true);
});
it('bounds ordinary persisted child activity before returning it to the API', async () => {
const conversationId = uuidv4();
await saveMessage(mockCtx, {
messageId: 'task-content:assistant',
conversationId,
text: '',
user: 'user123',
content: [
...Array.from({ length: SUBAGENT_MESSAGE_ACTIVITY_ITEM_LIMIT + 2 }, (_, index) => ({
type: 'text',
text: `activity-${index}`,
})),
{
type: 'tool_call',
tool_call: {
id: 'move-1',
name: 'submit_move',
args: 'x'.repeat(3_000),
output: 'y'.repeat(5_000),
progress: 1,
inputValidationError: true,
},
},
{
type: 'activity_label',
activity_label: 'Coordinating agents',
tool_call_ids: Array.from({ length: 32 }, (_, index) => `tool-${index}`),
agent_ids: Array.from({ length: 32 }, (_, index) => `agent-${index}`),
},
],
});
const messages = await getMessagesForSubagentThreadView({
user: 'user123',
conversationId,
limit: 1,
textCodePointLimit: 8_192,
});
expect(messages).toHaveLength(1);
expect(messages[0].subagentActivity).toHaveLength(SUBAGENT_MESSAGE_ACTIVITY_ITEM_LIMIT);
expect(messages[0].subagentActivityProjectionTruncated).toBe(true);
const retainedTool = messages[0].subagentActivity?.find(
(activity) => (activity as { type?: string }).type === 'tool',
) as {
input: string;
output: string;
};
expect(retainedTool).toEqual(
expect.objectContaining({
type: 'tool',
toolCallId: 'move-1',
name: 'submit_move',
inputValidationError: true,
inputTruncated: true,
outputTruncated: true,
}),
);
expect(retainedTool.input.length).toBeLessThan(3_000);
expect(retainedTool.output.length).toBeLessThan(5_000);
const retainedLabel = messages[0].subagentActivity?.find(
(activity) => (activity as { type?: string }).type === 'activity_label',
) as { agentIds: string[]; labelTruncated: boolean; toolCallIds: string[] };
expect(retainedLabel.toolCallIds).toHaveLength(8);
expect(retainedLabel.agentIds).toHaveLength(8);
expect(retainedLabel.labelTruncated).toBe(true);
expect(JSON.stringify(messages[0])).not.toContain('activity-0');
expect(JSON.stringify(messages[0])).not.toContain('x'.repeat(2_049));
expect(JSON.stringify(messages[0])).not.toContain('y'.repeat(4_097));
});
it('bounds public control receipts before materializing the message page', async () => {
const conversationId = uuidv4();
const createdAt = new Date('2026-08-21T12:00:00.000Z');
const accepted = Array.from({ length: 16 }, (_, index) => ({
invocationId: `accepted-${index}`,
fingerprint: `private-fingerprint-${index}`,
action: 'steer' as const,
status: 'accepted' as const,
createdAt,
updatedAt: createdAt,
message: 'a'.repeat(4_096),
}));
const terminal = Array.from({ length: 48 }, (_, index) => ({
invocationId: `applied-${index}`,
fingerprint: `private-fingerprint-terminal-${index}`,
action: 'queue' as const,
status: 'applied' as const,
createdAt,
updatedAt: createdAt,
message: 't'.repeat(4_096),
}));
await saveMessage(mockCtx, {
messageId: 'task-controls:user',
conversationId,
text: 'Control the child.',
user: 'user123',
subagentTask: {
attemptKey: 'private-attempt-key',
requestFingerprint: 'private-request-fingerprint',
status: 'running',
controlReceipts: [...accepted, ...terminal],
},
});
const [message] = await getMessagesForSubagentThreadView({
user: 'user123',
conversationId,
limit: 1,
textCodePointLimit: 8_192,
});
expect(message.subagentTask?.status).toBe('running');
expect(message.subagentTask?.controlReceipts).toHaveLength(32);
expect(message.subagentTask?.controlReceiptsProjectionTruncated).toBe(true);
expect(message.subagentTask?.controlReceipts?.slice(0, 16)).toEqual(
expect.arrayContaining(
accepted.map((receipt) =>
expect.objectContaining({ invocationId: receipt.invocationId, status: 'accepted' }),
),
),
);
expect(message.subagentTask?.controlReceipts?.slice(16)).toEqual(
terminal
.slice(-16)
.map((receipt) =>
expect.objectContaining({ invocationId: receipt.invocationId, status: 'applied' }),
),
);
for (const receipt of message.subagentTask?.controlReceipts ?? []) {
expect(receipt.message).toHaveLength(4_096);
expect(receipt.messageTruncated).not.toBe(true);
expect(receipt).not.toHaveProperty('fingerprint');
}
expect(message.subagentTask).not.toHaveProperty('attemptKey');
expect(message.subagentTask).not.toHaveProperty('requestFingerprint');
});
it('bounds transcript materialization while retaining the exact selected task', async () => {
const conversationId = uuidv4();
const aggregateSpy = jest.spyOn(Message, 'aggregate');
for (let index = 0; index < SUBAGENT_TRANSCRIPT_PAGE_LIMIT + 6; index += 1) {
await saveMessage(mockCtx, {
messageId: `task-${index}:assistant`,
conversationId,
text: `Answer ${index}`,
user: 'user123',
createdAt: new Date(Date.UTC(2026, 7, 21, 12, index)),
subagentTranscript: {
taskId: `task-${index}`,
mode: 'append',
messagesJson: JSON.stringify([{ type: 'ai', data: { content: `Answer ${index}` } }]),
},
});
}
const messages = await getMessagesForSubagentThreadView({
user: 'user123',
conversationId,
selectedTaskId: 'task-0',
limit: SUBAGENT_TRANSCRIPT_PAGE_LIMIT,
textCodePointLimit: 8_192,
});
const materialized = messages.filter((message) => message.subagentTranscript != null);
expect(messages).toHaveLength(SUBAGENT_TRANSCRIPT_PAGE_LIMIT + 1);
expect(materialized).toHaveLength(SUBAGENT_TRANSCRIPT_PAGE_LIMIT);
expect(materialized).toEqual(
expect.arrayContaining([
expect.objectContaining({
messageId: 'task-0:assistant',
subagentTranscript: expect.objectContaining({ taskId: 'task-0' }),
}),
]),
);
expect(
messages.filter(
(message) =>
message.subagentTranscript == null &&
message.subagentTranscriptProjectionTruncated === true,
),
).toHaveLength(1);
/** Three reads: the page, recent sources, and one single-snapshot read
* that yields both the selected task's messages and its source — the
* replacement for a `$facet`, which Amazon DocumentDB does not support. */
expect(aggregateSpy).toHaveBeenCalledTimes(3);
const messagesPipeline = aggregateSpy.mock.calls[0][0] as unknown as Array<
Record<string, unknown>
>;
const recentSourcesPipeline = aggregateSpy.mock.calls[1][0] as unknown as Array<
Record<string, unknown>
>;
const selectedPipeline = aggregateSpy.mock.calls[2][0] as unknown as Array<
Record<string, unknown>
>;
for (const [pipeline] of aggregateSpy.mock.calls) {
expect(pipeline).not.toEqual(
expect.arrayContaining([expect.objectContaining({ $facet: expect.anything() })]),
);
}
expect(messagesPipeline[2]).toEqual({ $limit: SUBAGENT_TRANSCRIPT_PAGE_LIMIT });
expect(recentSourcesPipeline[2]).toEqual({
$limit: SUBAGENT_TRANSCRIPT_PAGE_LIMIT * 2,
});
expect(selectedPipeline[0]).toEqual(
expect.objectContaining({
$match: expect.objectContaining({
messageId: {
$in: ['task-0:user', 'task-0:assistant'],
},
}),
}),
);
aggregateSpy.mockRestore();
});
it('omits an oversized private transcript before returning the application result', async () => {
const conversationId = uuidv4();
await saveMessage(mockCtx, {
messageId: 'task-large:assistant',
conversationId,
text: 'The bounded public answer remains available.',
user: 'user123',
subagentTranscript: {
taskId: 'task-large',
mode: 'append',
messagesJson: JSON.stringify([
{
type: 'ai',
data: { content: 'x'.repeat(SUBAGENT_TRANSCRIPT_SOURCE_BYTE_LIMIT + 1) },
},
]),
},
});
const messages = await getMessagesForSubagentThreadView({
user: 'user123',
conversationId,
limit: 1,
textCodePointLimit: 8_192,
});
expect(messages).toHaveLength(1);
expect(messages[0].text).toBe('The bounded public answer remains available.');
expect(messages[0]).not.toHaveProperty('subagentTranscript');
expect(messages[0].subagentTranscriptProjectionTruncated).toBe(true);
});
it.each([1, 2] as const)(
'uses projection version %s with steering-aware legacy catch-up',
async (version) => {
const conversationId = uuidv4();
const transcript = JSON.stringify([
{ type: 'human', data: { content: 'Initial task' } },
{ type: 'ai', data: { content: 'Before guidance' } },
{
type: 'human',
data: { content: 'Guidance', additional_kwargs: { injected: true, source: 'steer' } },
},
{ type: 'ai', data: { content: 'After guidance' } },
]);
const projection = JSON.stringify([
{ type: 'writing', text: 'Earlier incomplete projection' },
]);
await saveMessage(mockCtx, {
messageId: 'task-steering:assistant',
conversationId,
user: 'user123',
text: 'Final',
subagentTranscript: {
taskId: 'task-steering',
mode: 'replace',
messagesJson: transcript,
},
subagentActivityProjection: {
taskId: 'task-steering',
version,
activityJson: projection,
truncated: false,
},
});
const [message] = await getMessagesForSubagentThreadView({
user: 'user123',
conversationId,
selectedTaskId: 'task-steering',
limit: 1,
textCodePointLimit: 8192,
});
if (version === 1) {
expect(message.subagentTranscript?.messagesJson).toBe(transcript);
expect(message.subagentActivityProjectionJson).toBe(projection);
} else {
expect(message.subagentActivityProjectionJson).toBe(projection);
expect(message.subagentTranscript).toBeUndefined();
}
},
);
it.each([undefined, 'task-long'] as const)(
'retains the legacy fallback beside bounded steering history with selected task %s',
async (selectedTaskId) => {
const conversationId = uuidv4();
const prompt = 'Long current task. '.repeat(575);
const projection = JSON.stringify([
{ type: 'reasoning', text: 'Retained current reasoning.' },
{ type: 'writing', text: 'Retained current activity.' },
]);
const transcript = JSON.stringify([
{ type: 'human', data: { content: 'Previous task.' } },
{
type: 'human',
data: {
content: 'Previous guidance.',
additional_kwargs: { injected: true, source: 'steer' },
},
},
{ type: 'human', data: { content: prompt } },
{ type: 'ai', data: { content: 'Current activity.' } },
]);
await saveMessage(mockCtx, {
messageId: 'task-long:user',
conversationId,
user: 'user123',
text: prompt,
isCreatedByUser: true,
});
await saveMessage(mockCtx, {
messageId: 'task-long:assistant',
parentMessageId: 'task-long:user',
conversationId,
user: 'user123',
text: 'Result',
subagentTranscript: { taskId: 'task-long', mode: 'replace', messagesJson: transcript },
subagentActivityProjection: {
taskId: 'task-long',
version: 1,
activityJson: projection,
truncated: false,
},
});
const records = await getMessagesForSubagentThreadView({
user: 'user123',
conversationId,
selectedTaskId,
limit: 3,
textCodePointLimit: 8192,
});
const input = records.find((message) => message.messageId === 'task-long:user');
const assistant = records.find((message) => message.messageId === 'task-long:assistant');
expect(input?.textProjectionTruncated).toBe(true);
expect(assistant?.subagentActivityProjectionJson).toBe(projection);
expect(assistant?.subagentTranscript?.messagesJson).toBe(transcript);
},
);
it('prefers the bounded settlement projection without materializing its private transcript', async () => {
const conversationId = uuidv4();
await saveMessage(mockCtx, {
messageId: 'task-projected:assistant',
conversationId,
text: 'The public answer remains available.',
user: 'user123',
subagentTranscript: {
taskId: 'task-projected',
mode: 'append',
messagesJson: JSON.stringify([
{
type: 'ai',
data: { content: 'private'.repeat(SUBAGENT_TRANSCRIPT_SOURCE_BYTE_LIMIT) },
},
]),
},
subagentActivityProjection: {
taskId: 'task-projected',
version: 1,
activityJson: JSON.stringify([{ type: 'writing', text: 'Public result.' }]),
truncated: false,
},
});
const messages = await getMessagesForSubagentThreadView({
user: 'user123',
conversationId,
selectedTaskId: 'task-projected',
limit: 1,
textCodePointLimit: 8_192,
});
expect(messages).toHaveLength(1);
expect(messages[0].subagentActivityProjectionJson).toBe(
JSON.stringify([{ type: 'writing', text: 'Public result.' }]),
);
expect(messages[0]).not.toHaveProperty('subagentTranscript');
expect(messages[0]).not.toHaveProperty('subagentTranscriptProjectionTruncated');
});
});
describe('listSubagentTasksForThreads', () => {
it('derives event task status from ordinary durable turn rows', async () => {
const conversationId = uuidv4();
await Message.create([
{
user: 'user123',
messageId: 'delivery-running:user',
conversationId,
isCreatedByUser: true,
createdAt: new Date('2026-08-21T10:00:00.000Z'),
},
{
user: 'user123',
messageId: 'delivery-complete:assistant',
conversationId,
isCreatedByUser: false,
createdAt: new Date('2026-08-21T10:01:00.000Z'),
},
{
user: 'user123',
messageId: 'delivery-error:assistant',
conversationId,
isCreatedByUser: false,
error: true,
createdAt: new Date('2026-08-21T10:02:00.000Z'),
},
]);
const [record] = await listSubagentTasksForThreads({
user: 'user123',
conversationIds: [conversationId],
limitPerThread: 3,
});
expect(record.tasks).toEqual([
expect.objectContaining({
messageId: 'delivery-error:assistant',
status: 'error',
statusDerived: true,
}),
expect.objectContaining({
messageId: 'delivery-complete:assistant',
status: 'completed',
statusDerived: true,
}),
expect.objectContaining({
messageId: 'delivery-running:user',
status: 'running',
statusDerived: true,
}),
]);
});
it('batches threads, deduplicates task rows, and bounds each newest task list', async () => {
const firstThread = uuidv4();
const secondThread = uuidv4();
await saveMessage(mockCtx, {
messageId: 'task-old:user',
conversationId: firstThread,
text: 'Start old task',
isCreatedByUser: true,
subagentTask: { attemptKey: 'old', status: 'running' },
});
await waitForTimestampTick();
await saveMessage(mockCtx, {
messageId: 'task-old:assistant',
conversationId: firstThread,
text: 'Finish old task',
isCreatedByUser: false,
subagentTask: { attemptKey: 'old', status: 'completed' },
});
await waitForTimestampTick();
await saveMessage(mockCtx, {
messageId: 'task-new:user',
conversationId: firstThread,
text: 'Start new task',
isCreatedByUser: true,
subagentTask: { attemptKey: 'new', status: 'running' },
});
await saveMessage(mockCtx, {
messageId: 'task-other:assistant',
conversationId: secondThread,
text: 'Other result',
isCreatedByUser: false,
subagentTask: { attemptKey: 'other', status: 'cancelled' },
});
const records = await listSubagentTasksForThreads({
user: 'user123',
conversationIds: [firstThread, secondThread],
limitPerThread: 2,
});
const first = records.find((record) => record.conversationId === firstThread);
expect(first?.tasks).toHaveLength(2);
expect(first?.tasks[0]).toEqual(
expect.objectContaining({ messageId: 'task-new:user', status: 'running' }),
);
expect(first?.tasks[1]).toEqual(
expect.objectContaining({ messageId: 'task-old:assistant', status: 'completed' }),
);
expect(records.find((record) => record.conversationId === secondThread)?.tasks).toEqual([
expect.objectContaining({ messageId: 'task-other:assistant', status: 'cancelled' }),
]);
expect(records.every((record) => record.sourceTruncated !== true)).toBe(true);
});
it('marks every selected child truncated when one busy child fills the shared source window', async () => {
const quietThread = uuidv4();
const busyThread = uuidv4();
await Message.create([
...['quiet-old', 'quiet-new'].map((taskId, index) => ({
user: 'user123',
messageId: `${taskId}:assistant`,
conversationId: quietThread,
isCreatedByUser: false,
createdAt: new Date(`2026-08-20T10:0${index}:00.000Z`),
updatedAt: new Date(`2026-08-20T10:0${index}:00.000Z`),
subagentTask: { attemptKey: taskId, status: 'completed' },
})),
...Array.from({ length: 9 }, (_, index) => ({
user: 'user123',
messageId: `busy-${index}:assistant`,
conversationId: busyThread,
isCreatedByUser: false,
createdAt: new Date(`2026-08-21T10:${String(index).padStart(2, '0')}:00.000Z`),
updatedAt: new Date(`2026-08-21T10:${String(index).padStart(2, '0')}:00.000Z`),
subagentTask: { attemptKey: `busy-${index}`, status: 'completed' },
})),
]);
const records = await listSubagentTasksForThreads({
user: 'user123',
conversationIds: [quietThread, busyThread],
limitPerThread: 2,
});
expect(records.find((record) => record.conversationId === quietThread)).toEqual(
expect.objectContaining({
sourceTruncated: true,
tasks: [expect.objectContaining({ messageId: 'quiet-new:assistant' })],
}),
);
expect(records.find((record) => record.conversationId === busyThread)?.sourceTruncated).toBe(
true,
);
});
it('preserves a newer recent task when the latest-per-thread snapshot is stale', async () => {
const conversationId = uuidv4();
const aggregate = jest.spyOn(Message, 'aggregate') as unknown as jest.Mock;
aggregate
.mockReturnValueOnce(
Promise.resolve([
{
conversationId,
tasks: [
{
messageId: 'task-old:assistant',
createdAt: new Date('2026-08-21T10:00:00.000Z'),
status: 'completed',
},
],
},
]),
)
.mockReturnValueOnce(
Promise.resolve([
{
conversationId,
sourceRows: 1,
tasks: [
{
messageId: 'task-new:user',
createdAt: new Date('2026-08-21T11:00:00.000Z'),
status: 'running',
},
],
},
]),
);
try {
await expect(
listSubagentTasksForThreads({
user: 'user123',
conversationIds: [conversationId],
limitPerThread: 2,
}),
).resolves.toEqual([
{
conversationId,
tasks: [
expect.objectContaining({ messageId: 'task-new:user' }),
expect.objectContaining({ messageId: 'task-old:assistant' }),
],
},
]);
} finally {
aggregate.mockRestore();
}
});
it('preserves Mongo occurrence ordering when task timestamps tie', async () => {
const conversationId = uuidv4();
const aggregate = jest.spyOn(Message, 'aggregate') as unknown as jest.Mock;
aggregate
.mockReturnValueOnce(
Promise.resolve([
{
conversationId,
tasks: [
{
messageId: 'task-b:user',
createdAt: new Date('2026-08-21T10:00:00.000Z'),
occurrenceId: new mongoose.Types.ObjectId('000000000000000000000002'),
status: 'running',
},
],
},
]),
)
.mockReturnValueOnce(
Promise.resolve([
{
conversationId,
sourceRows: 1,
tasks: [
{
messageId: 'task-a:assistant',
createdAt: new Date('2026-08-21T10:00:00.000Z'),
occurrenceId: new mongoose.Types.ObjectId('000000000000000000000001'),
status: 'completed',
},
],
},
]),
);
try {
const [record] = await listSubagentTasksForThreads({
user: 'user123',
conversationIds: [conversationId],
limitPerThread: 2,
});
expect(record.tasks.map((task) => task.messageId)).toEqual([
'task-b:user',
'task-a:assistant',
]);
} finally {
aggregate.mockRestore();
}
});
});
describe('deleteMessages', () => {
it('does not discover journals for an exact ordinary message id', async () => {
const messageId = uuidv4();
await saveMessage(mockCtx, {
messageId,
conversationId: uuidv4(),
user: 'user123',
text: 'Ordinary chat',
});
const find = jest.spyOn(Message, 'find');
const journalDelete = jest.spyOn(mongoose.models.SubagentContent, 'deleteMany');
try {
await expect(deleteMessages({ user: 'user123', messageId })).resolves.toMatchObject({
deletedCount: 1,
});
expect(find).not.toHaveBeenCalled();
expect(journalDelete).not.toHaveBeenCalled();
} finally {
find.mockRestore();
journalDelete.mockRestore();
}
});
it('should delete messages with the correct filter', async () => {
// Save some messages for different users
await saveMessage(mockCtx, mockMessageData);
await saveMessage(
{ userId: 'user456' },
{
messageId: 'msg456',
conversationId: uuidv4(),
text: 'Other user message',
user: 'user456',
},
);
await deleteMessages({ user: 'user123' });
// Verify only user123's messages were deleted
const user123Messages = await Message.find({ user: 'user123' });
const user456Messages = await Message.find({ user: 'user456' });
expect(user123Messages).toHaveLength(0);
expect(user456Messages).toHaveLength(1);
});
});
describe('Conversation Hijacking Prevention', () => {
it("should not allow editing a message in another user's conversation", async () => {
const victimConversationId = uuidv4();
const victimMessageId = 'victim-msg-123';
// First, save a message as the victim (but we'll try to edit as attacker)
await saveMessage(
{ userId: 'victim123' },
{
messageId: victimMessageId,
conversationId: victimConversationId,
text: 'Victim message',
user: 'victim123',
},
);
// Attacker tries to edit the victim's message
await expect(
updateMessage('attacker123', {
messageId: victimMessageId,
conversationId: victimConversationId,
text: 'Hacked message',
}),
).rejects.toThrow('Message not found or user not authorized.');
// Verify the original message is unchanged
const originalMessage = await Message.findOne({
messageId: victimMessageId,
user: 'victim123',
});
expect(originalMessage?.text).toBe('Victim message');
});
it("should not allow inserting a new message into another user's conversation", async () => {
const victimConversationId = uuidv4();
// Attacker tries to save a message - this should succeed but with attacker's user ID
const result = await saveMessage(
{ userId: 'attacker123' },
{
conversationId: victimConversationId,
text: 'Inserted malicious message',
messageId: 'new-msg-123',
user: 'attacker123',
},
);
expect(result).toBeTruthy();
expect(result?.user).toBe('attacker123');
// Verify the message was saved with the attacker's user ID, not as an anonymous message
const savedMessage = await Message.findOne({ messageId: 'new-msg-123' });
expect(savedMessage?.user).toBe('attacker123');
expect(savedMessage?.conversationId).toBe(victimConversationId);
});
it('should allow retrieving messages from any conversation', async () => {
const victimConversationId = uuidv4();
// Save a message in the victim's conversation
await saveMessage(
{ userId: 'victim123' },
{
messageId: 'victim-msg',
conversationId: victimConversationId,
text: 'Victim message',
user: 'victim123',
},
);
// Anyone should be able to retrieve messages by conversation ID
const messages = await getMessages({ conversationId: victimConversationId });
expect(messages).toHaveLength(1);
expect(messages[0].text).toBe('Victim message');
});
});
describe('isTemporary message handling', () => {
beforeEach(() => {
// Reset mocks before each test
jest.clearAllMocks();
});
it('should save a message with expiredAt when isTemporary is true', async () => {
// Mock app config with 24 hour retention
mockCtx.interfaceConfig = { temporaryChatRetention: 24 };
mockCtx.isTemporary = true;
const beforeSave = new Date();
const result = await saveMessage(mockCtx, mockMessageData);
const afterSave = new Date();
expect(result?.messageId).toBe('msg123');
expect(result?.expiredAt).toBeDefined();
expect(result?.expiredAt).toBeInstanceOf(Date);
// Verify expiredAt is approximately 24 hours in the future
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 saveMessage(mockCtx, mockMessageData);
expect(result?.isTemporary).toBe(true);
expect(result?.expiredAt).toEqual(inheritedExpiration);
});
it('should save a message without expiredAt when isTemporary is false', async () => {
mockCtx.isTemporary = false;
const result = await saveMessage(mockCtx, mockMessageData);
expect(result?.messageId).toBe('msg123');
expect(result?.expiredAt).toBeNull();
});
it('should save a message without expiredAt when isTemporary is not provided', async () => {
// No isTemporary set
const result = await saveMessage(mockCtx, mockMessageData);
expect(result?.messageId).toBe('msg123');
expect(result?.expiredAt).toBeUndefined();
});
it('should use custom retention period from config', async () => {
// Mock app config with 48 hour retention
mockCtx.interfaceConfig = { temporaryChatRetention: 48 };
mockCtx.isTemporary = true;
const beforeSave = new Date();
const result = await saveMessage(mockCtx, mockMessageData);
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 saveMessage(mockCtx, mockMessageData);
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 saveMessage(mockCtx, mockMessageData);
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.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 saveMessage(mockCtx, mockMessageData);
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('atomically assigns general retention when inserting without a chat type', async () => {
mockCtx.isTemporary = undefined;
mockCtx.interfaceConfig = {
temporaryChatRetention: 1,
generalChatRetention: 2160,
retentionMode: RetentionMode.ALL,
};
const followupWrite = jest
.spyOn(Message, 'updateOne')
.mockRejectedValue(new Error('offline'));
const result = await saveMessage(mockCtx, mockMessageData);
expect(result?.isTemporary).toBe(false);
expect(result?.expiredAt).toBeInstanceOf(Date);
expect(followupWrite).not.toHaveBeenCalled();
});
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 saveMessage(mockCtx, {
...mockMessageData,
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 saveMessage(mockCtx, mockMessageData);
mockCtx.isTemporary = undefined;
const second = await saveMessage(mockCtx, { ...mockMessageData });
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 saveMessage(mockCtx, mockMessageData);
expect(result?.expiredAt).toEqual(mockCtx.expiredAt);
});
it('should set expiredAt for non-temporary message when retentionMode is ALL', async () => {
mockCtx.isTemporary = false;
mockCtx.interfaceConfig = {
temporaryChatRetention: 24,
retentionMode: RetentionMode.ALL,
};
const result = await saveMessage(mockCtx, mockMessageData);
expect(result?.expiredAt).toBeDefined();
expect(result?.expiredAt).toBeInstanceOf(Date);
});
it('should mark retained message non-temporary when retentionMode is ALL and isTemporary is omitted', async () => {
mockCtx.isTemporary = undefined;
mockCtx.interfaceConfig = {
temporaryChatRetention: 24,
retentionMode: RetentionMode.ALL,
};
const result = await saveMessage(mockCtx, mockMessageData);
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 saveMessage(mockCtx, mockMessageData);
mockCtx.isTemporary = undefined;
const secondSave = await saveMessage(mockCtx, {
...mockMessageData,
text: 'Updated text',
});
expect(firstSave?.isTemporary).toBe(true);
expect(secondSave?.text).toBe('Updated text');
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 saveMessage(mockCtx, mockMessageData);
expect(result?.expiredAt).toBeNull();
});
it('should force temporary message 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 saveMessage(mockCtx, mockMessageData);
expect(result?.isTemporary).toBe(true);
expect(result?.expiredAt).toBeDefined();
expect(result?.expiredAt).toBeInstanceOf(Date);
});
it('should force temporary message when retentionMode is EPHEMERAL and isTemporary is omitted', async () => {
mockCtx.isTemporary = undefined;
mockCtx.interfaceConfig = {
temporaryChatRetention: 24,
retentionMode: RetentionMode.EPHEMERAL,
};
const result = await saveMessage(mockCtx, mockMessageData);
expect(result?.isTemporary).toBe(true);
expect(result?.expiredAt).toBeDefined();
expect(result?.expiredAt).toBeInstanceOf(Date);
});
it('should handle missing config gracefully', async () => {
// Simulate missing config - should use default retention period
delete mockCtx.interfaceConfig;
mockCtx.isTemporary = true;
const beforeSave = new Date();
const result = await saveMessage(mockCtx, mockMessageData);
const afterSave = new Date();
// Should still save the message with default retention period (30 days)
expect(result?.messageId).toBe('msg123');
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 saveMessage(mockCtx, mockMessageData);
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 not update expiredAt on message update', async () => {
// First save a temporary message
mockCtx.interfaceConfig = { temporaryChatRetention: 24 };
mockCtx.isTemporary = true;
const savedMessage = await saveMessage(mockCtx, mockMessageData);
const originalExpiredAt = savedMessage?.expiredAt;
// Now update the message without isTemporary flag
mockCtx.isTemporary = undefined;
const updatedMessage = await updateMessage(mockCtx.userId, {
messageId: 'msg123',
text: 'Updated text',
});
// expiredAt should not be in the returned updated message object
expect(updatedMessage?.expiredAt).toBeUndefined();
// Verify in database that expiredAt wasn't changed
const dbMessage = await Message.findOne({ messageId: 'msg123', user: 'user123' });
expect(dbMessage?.expiredAt).toEqual(originalExpiredAt);
});
it('should preserve expiredAt when saving existing temporary message', async () => {
// First save a temporary message
mockCtx.interfaceConfig = { temporaryChatRetention: 24 };
mockCtx.isTemporary = true;
const firstSave = await saveMessage(mockCtx, mockMessageData);
const originalExpiredAt = firstSave?.expiredAt;
// Wait a bit to ensure time difference
await new Promise((resolve) => setTimeout(resolve, 100));
// Save again with same messageId but different text
const updatedData = { ...mockMessageData, text: 'Updated text' };
const secondSave = await saveMessage(mockCtx, updatedData);
// Should update text but create new expiredAt
expect(secondSave?.text).toBe('Updated text');
expect(secondSave?.expiredAt).toBeDefined();
expect(new Date(secondSave?.expiredAt ?? 0).getTime()).toBeGreaterThan(
new Date(originalExpiredAt ?? 0).getTime(),
);
});
it('should preserve temporary retention when saving without isTemporary', async () => {
mockCtx.interfaceConfig = { temporaryChatRetention: 24 };
mockCtx.isTemporary = true;
const firstSave = await saveMessage(mockCtx, mockMessageData);
const originalExpiredAt = firstSave?.expiredAt;
mockCtx.isTemporary = undefined;
const updatedData = { ...mockMessageData, text: 'Updated text' };
const secondSave = await saveMessage(mockCtx, updatedData);
expect(secondSave?.text).toBe('Updated text');
expect(secondSave?.isTemporary).toBe(true);
expect(secondSave?.expiredAt).toEqual(originalExpiredAt);
});
it('should handle bulk operations with temporary messages', async () => {
// This test verifies bulkSaveMessages doesn't interfere with expiredAt
const messages = [
{
messageId: 'bulk1',
conversationId: uuidv4(),
text: 'Bulk message 1',
user: 'user123',
expiredAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
},
{
messageId: 'bulk2',
conversationId: uuidv4(),
text: 'Bulk message 2',
user: 'user123',
expiredAt: null,
},
];
await bulkSaveMessages(messages);
const savedMessages = await Message.find({
messageId: { $in: ['bulk1', 'bulk2'] },
}).lean();
expect(savedMessages).toHaveLength(2);
const bulk1 = savedMessages.find((m) => m.messageId === 'bulk1');
const bulk2 = savedMessages.find((m) => m.messageId === 'bulk2');
expect(bulk1?.expiredAt).toBeDefined();
expect(bulk2?.expiredAt).toBeNull();
});
});
describe('Message cursor pagination', () => {
/**
* Helper to create messages with specific timestamps
* Uses collection.insertOne to bypass Mongoose timestamps
*/
const createMessageWithTimestamp = async (
index: number,
conversationId: string,
createdAt: Date,
) => {
const messageId = uuidv4();
await Message.collection.insertOne({
messageId,
conversationId,
user: 'user123',
text: `Message ${index}`,
isCreatedByUser: index % 2 === 0,
createdAt,
updatedAt: createdAt,
});
return Message.findOne({ messageId }).lean<IMessage>();
};
/**
* Simulates the pagination logic from api/server/routes/messages.js
* This tests the exact query pattern used in the route
*/
const getMessagesByCursor = async ({
conversationId,
user,
pageSize = 25,
cursor = null as string | null,
sortBy = 'createdAt',
sortDirection = 'desc',
}: {
conversationId: string;
user: string;
pageSize?: number;
cursor?: string | null;
sortBy?: string;
sortDirection?: string;
}) => {
const sortOrder = sortDirection === 'asc' ? 1 : -1;
const sortField = ['createdAt', 'updatedAt'].includes(sortBy) ? sortBy : 'createdAt';
const cursorOperator = sortDirection === 'asc' ? '$gt' : '$lt';
const filter: Record<string, unknown> = { conversationId, user };
if (cursor) {
filter[sortField] = { [cursorOperator]: new Date(cursor) };
}
const messages = await Message.find(filter)
.sort({ [sortField]: sortOrder })
.limit(pageSize + 1)
.lean();
let nextCursor: string | null = null;
if (messages.length > pageSize) {
messages.pop(); // Remove extra item used to detect next page
// Create cursor from the last RETURNED item (not the popped one)
nextCursor = (messages[messages.length - 1] as Record<string, unknown>)[
sortField
] as string;
}
return { messages, nextCursor };
};
it('should return messages for a conversation with pagination', async () => {
const conversationId = uuidv4();
const baseTime = new Date('2026-01-01T00:00:00.000Z');
// Create 30 messages to test pagination
for (let i = 0; i < 30; i++) {
const createdAt = new Date(baseTime.getTime() - i * 60000); // Each 1 minute apart
await createMessageWithTimestamp(i, conversationId, createdAt);
}
// Fetch first page (pageSize 25)
const page1 = await getMessagesByCursor({
conversationId,
user: 'user123',
pageSize: 25,
});
expect(page1.messages).toHaveLength(25);
expect(page1.nextCursor).toBeTruthy();
// Fetch second page using cursor
const page2 = await getMessagesByCursor({
conversationId,
user: 'user123',
pageSize: 25,
cursor: page1.nextCursor,
});
// Should get remaining 5 messages
expect(page2.messages).toHaveLength(5);
expect(page2.nextCursor).toBeNull();
// Verify no duplicates and no gaps
const allMessageIds = [
...page1.messages.map((m) => m.messageId),
...page2.messages.map((m) => m.messageId),
];
const uniqueIds = new Set(allMessageIds);
expect(uniqueIds.size).toBe(30); // All 30 messages accounted for
expect(allMessageIds.length).toBe(30); // No duplicates
});
it('should not skip message at page boundary (item 26 bug fix)', async () => {
const conversationId = uuidv4();
const baseTime = new Date('2026-01-01T12:00:00.000Z');
// Create exactly 26 messages
const messages: (IMessage | null)[] = [];
for (let i = 0; i < 26; i++) {
const createdAt = new Date(baseTime.getTime() - i * 60000);
const msg = await createMessageWithTimestamp(i, conversationId, createdAt);
messages.push(msg);
}
// The 26th message (index 25) should be on page 2
const item26 = messages[25];
// Fetch first page with pageSize 25
const page1 = await getMessagesByCursor({
conversationId,
user: 'user123',
pageSize: 25,
});
expect(page1.messages).toHaveLength(25);
expect(page1.nextCursor).toBeTruthy();
// Item 26 should NOT be in page 1
const page1Ids = page1.messages.map((m) => m.messageId);
expect(page1Ids).not.toContain(item26!.messageId);
// Fetch second page
const page2 = await getMessagesByCursor({
conversationId,
user: 'user123',
pageSize: 25,
cursor: page1.nextCursor,
});
// Item 26 MUST be in page 2 (this was the bug - it was being skipped)
expect(page2.messages).toHaveLength(1);
expect((page2.messages[0] as { messageId: string }).messageId).toBe(item26!.messageId);
});
it('should sort by createdAt DESC by default', async () => {
const conversationId = uuidv4();
// Create messages with specific timestamps
const msg1 = await createMessageWithTimestamp(
1,
conversationId,
new Date('2026-01-01T00:00:00.000Z'),
);
const msg2 = await createMessageWithTimestamp(
2,
conversationId,
new Date('2026-01-02T00:00:00.000Z'),
);
const msg3 = await createMessageWithTimestamp(
3,
conversationId,
new Date('2026-01-03T00:00:00.000Z'),
);
const result = await getMessagesByCursor({
conversationId,
user: 'user123',
});
// Should be sorted by createdAt DESC (newest first) by default
expect(result?.messages).toHaveLength(3);
expect((result?.messages[0] as { messageId: string }).messageId).toBe(msg3!.messageId);
expect((result?.messages[1] as { messageId: string }).messageId).toBe(msg2!.messageId);
expect((result?.messages[2] as { messageId: string }).messageId).toBe(msg1!.messageId);
});
it('should support ascending sort direction', async () => {
const conversationId = uuidv4();
const msg1 = await createMessageWithTimestamp(
1,
conversationId,
new Date('2026-01-01T00:00:00.000Z'),
);
const msg2 = await createMessageWithTimestamp(
2,
conversationId,
new Date('2026-01-02T00:00:00.000Z'),
);
const result = await getMessagesByCursor({
conversationId,
user: 'user123',
sortDirection: 'asc',
});
// Should be sorted by createdAt ASC (oldest first)
expect(result?.messages).toHaveLength(2);
expect((result?.messages[0] as { messageId: string }).messageId).toBe(msg1!.messageId);
expect((result?.messages[1] as { messageId: string }).messageId).toBe(msg2!.messageId);
});
it('should handle empty conversation', async () => {
const conversationId = uuidv4();
const result = await getMessagesByCursor({
conversationId,
user: 'user123',
});
expect(result?.messages).toHaveLength(0);
expect(result?.nextCursor).toBeNull();
});
it('should only return messages for the specified user', async () => {
const conversationId = uuidv4();
const createdAt = new Date();
// Create a message for user123
await Message.collection.insertOne({
messageId: uuidv4(),
conversationId,
user: 'user123',
text: 'User message',
createdAt,
updatedAt: createdAt,
});
// Create a message for a different user
await Message.collection.insertOne({
messageId: uuidv4(),
conversationId,
user: 'otherUser',
text: 'Other user message',
createdAt,
updatedAt: createdAt,
});
const result = await getMessagesByCursor({
conversationId,
user: 'user123',
});
// Should only return user123's message
expect(result?.messages).toHaveLength(1);
expect((result?.messages[0] as { user: string }).user).toBe('user123');
});
it('should handle exactly pageSize number of messages (no next page)', async () => {
const conversationId = uuidv4();
const baseTime = new Date('2026-01-01T00:00:00.000Z');
// Create exactly 25 messages (equal to default pageSize)
for (let i = 0; i < 25; i++) {
const createdAt = new Date(baseTime.getTime() - i * 60000);
await createMessageWithTimestamp(i, conversationId, createdAt);
}
const result = await getMessagesByCursor({
conversationId,
user: 'user123',
pageSize: 25,
});
expect(result?.messages).toHaveLength(25);
expect(result?.nextCursor).toBeNull(); // No next page
});
it('should handle pageSize of 1', async () => {
const conversationId = uuidv4();
const baseTime = new Date('2026-01-01T00:00:00.000Z');
// Create 3 messages
for (let i = 0; i < 3; i++) {
const createdAt = new Date(baseTime.getTime() - i * 60000);
await createMessageWithTimestamp(i, conversationId, createdAt);
}
// Fetch with pageSize 1
let cursor: string | null = null;
const allMessages: unknown[] = [];
for (let page = 0; page < 5; page++) {
const result = await getMessagesByCursor({
conversationId,
user: 'user123',
pageSize: 1,
cursor,
});
allMessages.push(...(result?.messages ?? []));
cursor = result?.nextCursor;
if (!cursor) {
break;
}
}
// Should get all 3 messages without duplicates
expect(allMessages).toHaveLength(3);
const uniqueIds = new Set(allMessages.map((m) => (m as { messageId: string }).messageId));
expect(uniqueIds.size).toBe(3);
});
it('should handle messages with same createdAt timestamp', async () => {
const conversationId = uuidv4();
const sameTime = new Date('2026-01-01T12:00:00.000Z');
// Create multiple messages with the exact same timestamp
const messages: (IMessage | null)[] = [];
for (let i = 0; i < 5; i++) {
const msg = await createMessageWithTimestamp(i, conversationId, sameTime);
messages.push(msg);
}
const result = await getMessagesByCursor({
conversationId,
user: 'user123',
pageSize: 10,
});
// All messages should be returned
expect(result?.messages).toHaveLength(5);
});
});
describe('tenantId stripping', () => {
it('merges provenance within the active tenant context', async () => {
const messageId = uuidv4();
const conversationId = uuidv4();
await tenantStorage.run({ tenantId: 'tenant-a' }, async () => {
await saveMessage(
{ userId: 'user123' },
{ messageId, conversationId, text: 'Original', userSubmittedPaths: ['/text'] },
);
await saveMessage(
{ userId: 'user123' },
{
messageId,
conversationId,
text: 'Updated',
userSubmittedPaths: ['/content/0/text'],
},
);
});
const doc = await runAsSystem(async () => Message.findOne({ messageId }).lean());
expect(doc?.tenantId).toBe('tenant-a');
expect(doc?.text).toBe('Updated');
expect(doc?.userSubmittedPaths).toEqual(expect.arrayContaining(['/text', '/content/0/text']));
expect(doc?.userSubmittedPaths).toHaveLength(2);
});
it('saveMessage should not write caller-supplied tenantId to the document', async () => {
const messageId = uuidv4();
const conversationId = uuidv4();
const result = await saveMessage(
{ userId: 'user123' },
{
messageId,
conversationId,
text: 'Tenant test',
tenantId: 'malicious-tenant',
userSubmittedPaths: ['/text'],
},
);
expect(result).not.toBeNull();
expect(result).toBeDefined();
const doc = await Message.findOne({ messageId }).lean();
expect(doc).not.toBeNull();
expect(doc?.text).toBe('Tenant test');
expect(doc?.tenantId).toBeUndefined();
});
it('bulkSaveMessages should not overwrite tenantId via update payload', async () => {
const messageId = uuidv4();
const conversationId = uuidv4();
await tenantStorage.run({ tenantId: 'real-tenant' }, async () => {
await Message.create({
messageId,
conversationId,
user: 'user123',
text: 'Original',
});
});
await tenantStorage.run({ tenantId: 'real-tenant' }, async () => {
await bulkSaveMessages([
{
messageId,
conversationId,
user: 'user123',
text: 'Updated',
tenantId: 'malicious-tenant',
},
]);
});
const doc = await runAsSystem(async () => Message.findOne({ messageId }).lean());
expect(doc).not.toBeNull();
expect(doc?.text).toBe('Updated');
expect(doc?.tenantId).toBe('real-tenant');
});
it('updateMessage should not write caller-supplied tenantId to the document', async () => {
const messageId = uuidv4();
const conversationId = uuidv4();
await saveMessage({ userId: 'user123' }, { messageId, conversationId, text: 'Original' });
const updateWithUnknownField = {
messageId,
text: 'Updated',
tenantId: 'malicious-tenant',
unknownPipelineField: 'malicious-value',
userSubmittedPaths: ['/text'],
};
await updateMessage('user123', updateWithUnknownField);
const doc = await Message.findOne({ messageId }).lean();
expect(doc?.text).toBe('Updated');
expect(doc?.tenantId).toBeUndefined();
expect((doc as Record<string, unknown> | null)?.unknownPipelineField).toBeUndefined();
});
});
describe('recordSubagentTaskControlReceipt', () => {
const createTaskInput = async (conversationId: string, taskId = 'task-1') => {
await Message.create({
user: 'user123',
conversationId,
messageId: `${taskId}:user`,
parentMessageId: Constants.NO_PARENT,
sender: 'User',
text: 'Do the work',
endpoint: 'agents',
isCreatedByUser: true,
subagentTask: {
attemptKey: `attempt-${taskId}`,
status: 'running',
},
});
};
it('keeps expired receipt replay private while denying public body reads', async () => {
const conversationId = uuidv4();
await createTaskInput(conversationId);
await recordSubagentTaskControlReceipt({
userId: 'user123',
conversationId,
taskId: 'task-1',
receipt: {
invocationId: 'expired-read',
fingerprint: 'private',
controlId: 'control',
action: 'steer',
status: 'accepted',
message: 'retained body',
createdAt: new Date(),
updatedAt: new Date(),
},
});
const identity = {
userId: 'user123',
conversationId,
taskId: 'task-1',
invocationId: 'expired-read',
};
expect(await getSubagentTaskControlReceipt({ ...identity, activeOnly: true })).not.toBeNull();
await Message.updateOne(
{ user: 'user123', conversationId, messageId: 'task-1:user' },
{ $set: { expiredAt: new Date(Date.now() - 1000) } },
);
expect(await getSubagentTaskControlReceipt({ ...identity, activeOnly: true })).toBeNull();
expect(await getSubagentTaskControlReceipt(identity)).not.toBeNull();
});
it('advances one invocation monotonically and enforces ownership', async () => {
const conversationId = uuidv4();
await createTaskInput(conversationId);
const accepted = {
invocationId: 'invocation-1',
fingerprint: 'fingerprint-1',
controlId: 'control-1',
action: 'steer' as const,
status: 'accepted' as const,
createdAt: new Date('2026-08-24T12:00:00.000Z'),
updatedAt: new Date('2026-08-24T12:00:00.000Z'),
message: 'Use the primary source.',
};
await expect(
recordSubagentTaskControlReceipt({
userId: 'user123',
conversationId,
taskId: 'task-1',
receipt: { ...accepted, controlId: undefined, status: 'reserved' },
}),
).resolves.toBe(true);
/** A reservation fences competing owners but is not public evidence that
* the command was accepted or applied. */
await expect(
getSubagentTaskControlReceipt({
userId: 'user123',
conversationId,
taskId: 'task-1',
invocationId: 'invocation-1',
}),
).resolves.toBeNull();
await expect(
recordSubagentTaskControlReceipt({
userId: 'user123',
conversationId,
taskId: 'task-1',
receipt: accepted,
}),
).resolves.toBe(true);
await expect(
recordSubagentTaskControlReceipt({
userId: 'user123',
conversationId,
taskId: 'task-1',
receipt: {
...accepted,
status: 'applied',
boundary: 'tool',
updatedAt: new Date('2026-08-24T12:00:01.000Z'),
},
}),
).resolves.toBe(true);
/** A delayed accepted replay cannot downgrade the durable terminal receipt. */
await expect(
recordSubagentTaskControlReceipt({
userId: 'user123',
conversationId,
taskId: 'task-1',
receipt: accepted,
}),
).resolves.toBe('unchanged');
await expect(
recordSubagentTaskControlReceipt({
userId: 'another-user',
conversationId,
taskId: 'task-1',
receipt: accepted,
}),
).resolves.toBe(false);
const stored = await Message.findOne({
user: 'user123',
conversationId,
messageId: 'task-1:user',
})
.select('+subagentTask')
.lean<IMessage>();
expect(stored).not.toBeNull();
if (stored == null) throw new Error('Expected the durable task input.');
expect(stored.subagentTask?.status).toBe('running');
expect(stored.subagentTask?.controlReceipts).toEqual([
expect.objectContaining({
invocationId: 'invocation-1',
action: 'steer',
status: 'applied',
boundary: 'tool',
}),
]);
});
it('updates only the authorized tenant when message identities collide', async () => {
const conversationId = uuidv4();
const taskId = 'tenant-task';
await Promise.all(
['tenant-a', 'tenant-b'].map((tenantId) =>
Message.create({
user: 'user123',
tenantId,
conversationId,
messageId: `${taskId}:user`,
parentMessageId: Constants.NO_PARENT,
sender: 'User',
text: 'Do the tenant work',
endpoint: 'agents',
isCreatedByUser: true,
subagentTask: { attemptKey: `attempt-${tenantId}`, status: 'running' },
}),
),
);
const now = new Date('2026-08-24T12:00:00.000Z');
await expect(
recordSubagentTaskControlReceipt({
userId: 'user123',
tenantId: 'tenant-b',
conversationId,
taskId,
receipt: {
invocationId: 'tenant-invocation',
fingerprint: 'tenant-fingerprint',
controlId: 'tenant-control',
action: 'queue',
status: 'accepted',
createdAt: now,
updatedAt: now,
},
}),
).resolves.toBe(true);
const [tenantA, tenantB] = await Promise.all(
['tenant-a', 'tenant-b'].map((tenantId) =>
Message.findOne({
user: 'user123',
tenantId,
conversationId,
messageId: `${taskId}:user`,
})
.select('+subagentTask')
.lean<IMessage>(),
),
);
expect(tenantA?.subagentTask?.controlReceipts).toBeUndefined();
expect(tenantB?.subagentTask?.controlReceipts).toEqual([
expect.objectContaining({ invocationId: 'tenant-invocation' }),
]);
});
it('reads an exact authorized receipt and persists a new terminal rejection', async () => {
const conversationId = uuidv4();
await createTaskInput(conversationId);
await mongoose.models.Conversation.create({
user: 'user123',
conversationId,
title: 'Child thread',
endpoint: 'agents',
subagentThread: {
rootConversationId: 'parent-conversation',
parentConversationId: 'parent-conversation',
parentMessageId: 'parent-message',
parentToolCallId: 'parent-tool',
subagentType: 'researcher',
subagentKind: 'agent',
depth: 1,
},
});
await Message.create({
user: 'user123',
conversationId,
messageId: 'task-1:assistant',
parentMessageId: 'task-1:user',
sender: 'researcher',
text: 'Done.',
endpoint: 'agents',
isCreatedByUser: false,
subagentTask: {
attemptKey: 'task-1-attempt',
parentRunId: 'parent-message',
status: 'completed',
resultClaim: {
kind: 'manual',
claimId: 'poll-1',
claimedAt: new Date('2026-08-24T12:00:02.000Z'),
},
},
});
const now = new Date('2026-08-24T12:00:00.000Z');
await expect(
recordSubagentTaskControlReceipt({
userId: 'user123',
conversationId,
taskId: 'task-1',
receipt: {
invocationId: 'terminal-invocation',
fingerprint: 'terminal-fingerprint',
action: 'cancel',
status: 'rejected',
reason: 'task_not_running',
createdAt: now,
updatedAt: now,
},
}),
).resolves.toBe(true);
await expect(
getSubagentTaskControlReceipt({
userId: 'user123',
conversationId,
taskId: 'task-1',
invocationId: 'terminal-invocation',
}),
).resolves.toEqual(
expect.objectContaining({
invocationId: 'terminal-invocation',
fingerprint: 'terminal-fingerprint',
status: 'rejected',
reason: 'task_not_running',
}),
);
await expect(
getSubagentTaskControlReceipt({
userId: 'another-user',
conversationId,
taskId: 'task-1',
invocationId: 'terminal-invocation',
}),
).resolves.toBeNull();
await expect(
getSubagentTaskControlReplay({
userId: 'user123',
parentConversationId: 'parent-conversation',
taskId: 'task-1',
invocationId: 'terminal-invocation',
}),
).resolves.toEqual({
receipt: expect.objectContaining({ invocationId: 'terminal-invocation' }),
task: expect.objectContaining({
taskId: 'task-1',
threadId: conversationId,
subagentType: 'researcher',
status: 'completed',
resultAvailable: true,
resultClaimed: true,
}),
});
await expect(
getSubagentTaskControlReplay({
userId: 'user123',
parentConversationId: 'different-parent',
taskId: 'task-1',
invocationId: 'terminal-invocation',
}),
).resolves.toBeNull();
const ordinaryConversationId = uuidv4();
await Message.create({
user: 'user123',
conversationId: ordinaryConversationId,
messageId: 'ordinary-task:user',
parentMessageId: Constants.NO_PARENT,
sender: 'User',
text: 'An ordinary message with a colliding id.',
endpoint: 'agents',
isCreatedByUser: true,
});
await expect(
recordSubagentTaskControlReceipt({
userId: 'user123',
conversationId: ordinaryConversationId,
taskId: 'ordinary-task',
receipt: {
invocationId: 'terminal-invocation',
fingerprint: 'terminal-fingerprint',
action: 'cancel',
status: 'rejected',
reason: 'task_not_running',
createdAt: now,
updatedAt: now,
},
}),
).resolves.toBe(false);
});
it('replays an applied cancellation as cancelled before its terminal row exists', async () => {
const conversationId = uuidv4();
await createTaskInput(conversationId);
await mongoose.models.Conversation.create({
user: 'user123',
conversationId,
title: 'Cancelling child thread',
endpoint: 'agents',
subagentThread: {
rootConversationId: 'parent-conversation',
parentConversationId: 'parent-conversation',
parentMessageId: 'parent-message',
parentToolCallId: 'parent-tool',
subagentType: 'researcher',
subagentKind: 'agent',
depth: 1,
},
});
const now = new Date('2026-08-24T12:00:00.000Z');
await expect(
recordSubagentTaskControlReceipt({
userId: 'user123',
conversationId,
taskId: 'task-1',
receipt: {
invocationId: 'cancel-invocation',
fingerprint: 'cancel-fingerprint',
action: 'cancel',
status: 'applied',
createdAt: now,
updatedAt: now,
},
}),
).resolves.toBe(true);
await expect(
getSubagentTaskControlReplay({
userId: 'user123',
parentConversationId: 'parent-conversation',
taskId: 'task-1',
invocationId: 'cancel-invocation',
}),
).resolves.toEqual({
receipt: expect.objectContaining({ invocationId: 'cancel-invocation' }),
task: expect.objectContaining({
taskId: 'task-1',
threadId: conversationId,
status: 'cancelled',
resultAvailable: false,
resultClaimed: false,
updatedAt: now,
}),
});
});
it('reports every accepted control when replaying one durable invocation', async () => {
const conversationId = uuidv4();
await createTaskInput(conversationId);
await mongoose.models.Conversation.create({
user: 'user123',
conversationId,
title: 'Controlled child thread',
endpoint: 'agents',
subagentThread: {
rootConversationId: 'parent-conversation',
parentConversationId: 'parent-conversation',
parentMessageId: 'parent-message',
parentToolCallId: 'parent-tool',
subagentType: 'researcher',
subagentKind: 'agent',
depth: 1,
},
});
const now = new Date('2026-08-24T12:00:00.000Z');
for (const index of [1, 2]) {
await expect(
recordSubagentTaskControlReceipt({
userId: 'user123',
conversationId,
taskId: 'task-1',
receipt: {
invocationId: `pending-invocation-${index}`,
fingerprint: `pending-fingerprint-${index}`,
controlId: `pending-control-${index}`,
action: 'queue',
status: 'accepted',
createdAt: now,
updatedAt: now,
},
}),
).resolves.toBe(true);
}
await expect(
getSubagentTaskControlReplay({
userId: 'user123',
parentConversationId: 'parent-conversation',
taskId: 'task-1',
invocationId: 'pending-invocation-1',
}),
).resolves.toEqual({
receipt: expect.objectContaining({ invocationId: 'pending-invocation-1' }),
task: expect.objectContaining({ pendingControls: 2 }),
});
});
it('rejects an invocation fingerprint conflict without reporting persistence', async () => {
const conversationId = uuidv4();
await createTaskInput(conversationId);
const now = new Date('2026-08-24T12:00:00.000Z');
const receipt = {
invocationId: 'conflicting-invocation',
fingerprint: 'first-fingerprint',
controlId: 'first-control',
action: 'queue' as const,
status: 'accepted' as const,
createdAt: now,
updatedAt: now,
};
await expect(
recordSubagentTaskControlReceipt({
userId: 'user123',
conversationId,
taskId: 'task-1',
receipt,
}),
).resolves.toBe(true);
await expect(
recordSubagentTaskControlReceipt({
userId: 'user123',
conversationId,
taskId: 'task-1',
receipt: { ...receipt, fingerprint: 'different-fingerprint' },
}),
).resolves.toBe('conflict');
});
it('retains concurrent receipts without requiring an aggregation-pipeline update', async () => {
const conversationId = uuidv4();
await createTaskInput(conversationId);
const createdAt = new Date('2026-08-24T12:00:00.000Z');
const invocationIds = Array.from({ length: 32 }, (_, index) => `concurrent-${index}`);
await Promise.all(
invocationIds.map((invocationId, index) =>
recordSubagentTaskControlReceipt({
userId: 'user123',
conversationId,
taskId: 'task-1',
receipt: {
invocationId,
fingerprint: `${invocationId}-fingerprint`,
controlId: `${invocationId}-control`,
action: 'queue',
status: 'accepted',
createdAt: new Date(createdAt.getTime() + index),
updatedAt: new Date(createdAt.getTime() + index),
},
}),
),
);
const stored = await Message.findOne({
user: 'user123',
conversationId,
messageId: 'task-1:user',
})
.select('+subagentTask')
.lean<IMessage>();
expect(stored?.subagentTask?.controlReceipts).toEqual(
expect.arrayContaining(
invocationIds.map((invocationId) => expect.objectContaining({ invocationId })),
),
);
});
it('retains accepted commands while bounding terminal receipt history', async () => {
const conversationId = uuidv4();
await createTaskInput(conversationId);
const createdAt = new Date('2026-08-24T12:00:00.000Z');
await recordSubagentTaskControlReceipt({
userId: 'user123',
conversationId,
taskId: 'task-1',
receipt: {
invocationId: 'pending',
fingerprint: 'pending-fingerprint',
controlId: 'pending-control',
action: 'queue',
status: 'accepted',
createdAt,
updatedAt: createdAt,
},
});
for (let index = 0; index < 70; index += 1) {
await recordSubagentTaskControlReceipt({
userId: 'user123',
conversationId,
taskId: 'task-1',
receipt: {
invocationId: `terminal-${index}`,
fingerprint: `fingerprint-${index}`,
controlId: `control-${index}`,
action: 'steer',
status: 'applied',
createdAt: new Date(createdAt.getTime() + index + 1),
updatedAt: new Date(createdAt.getTime() + index + 1),
boundary: 'tool',
},
});
}
const stored = await Message.findOne({
user: 'user123',
conversationId,
messageId: 'task-1:user',
})
.select('+subagentTask')
.lean<IMessage>();
expect(stored).not.toBeNull();
if (stored == null) throw new Error('Expected the durable task input.');
expect(stored.subagentTask?.controlReceipts).toHaveLength(64);
expect(stored.subagentTask?.controlReceipts).toEqual(
expect.arrayContaining([
expect.objectContaining({ invocationId: 'pending', status: 'accepted' }),
expect.objectContaining({ invocationId: 'terminal-69', status: 'applied' }),
]),
);
expect(stored.subagentTask?.controlReceipts).not.toEqual(
expect.arrayContaining([expect.objectContaining({ invocationId: 'terminal-0' })]),
);
/** An old idempotent retry retains its original occurrence ordering and
* cannot evict newer terminal history merely by arriving again. */
await recordSubagentTaskControlReceipt({
userId: 'user123',
conversationId,
taskId: 'task-1',
receipt: {
invocationId: 'terminal-0',
fingerprint: 'fingerprint-0',
controlId: 'control-0',
action: 'steer',
status: 'applied',
createdAt: new Date(createdAt.getTime() + 1),
updatedAt: new Date(createdAt.getTime() + 1),
boundary: 'tool',
},
});
const afterReplay = await Message.findOne({
user: 'user123',
conversationId,
messageId: 'task-1:user',
})
.select('+subagentTask')
.lean<IMessage>();
expect(afterReplay?.subagentTask?.controlReceipts).toHaveLength(64);
expect(afterReplay?.subagentTask?.controlReceipts).toEqual(
expect.arrayContaining([expect.objectContaining({ invocationId: 'terminal-7' })]),
);
expect(afterReplay?.subagentTask?.controlReceipts).not.toEqual(
expect.arrayContaining([expect.objectContaining({ invocationId: 'terminal-0' })]),
);
});
it('refuses to evict active receipt fences at durable capacity', async () => {
const conversationId = uuidv4();
await createTaskInput(conversationId);
const createdAt = new Date('2026-08-24T12:00:00.000Z');
const results: Array<boolean | 'unchanged' | 'conflict'> = [];
for (let index = 0; index < 70; index += 1) {
results.push(
await recordSubagentTaskControlReceipt({
userId: 'user123',
conversationId,
taskId: 'task-1',
receipt: {
invocationId: `accepted-${index}`,
fingerprint: `fingerprint-${index}`,
controlId: `control-${index}`,
action: 'queue',
status: 'accepted',
createdAt: new Date(createdAt.getTime() + index),
updatedAt: new Date(createdAt.getTime() + index),
},
}),
);
}
expect(results.slice(0, 64)).toEqual(Array.from({ length: 64 }, () => true));
expect(results.slice(64)).toEqual(Array.from({ length: 6 }, () => false));
const stored = await Message.findOne({
user: 'user123',
conversationId,
messageId: 'task-1:user',
})
.select('+subagentTask')
.lean<IMessage>();
expect(stored?.subagentTask?.controlReceipts).toHaveLength(64);
expect(stored?.subagentTask?.controlReceipts?.[0]?.invocationId).toBe('accepted-0');
expect(stored?.subagentTask?.controlReceipts?.[63]?.invocationId).toBe('accepted-63');
await expect(
recordSubagentTaskControlReceipt({
userId: 'user123',
conversationId,
taskId: 'task-1',
receipt: {
invocationId: 'terminal-with-no-allowance',
fingerprint: 'terminal-fingerprint',
controlId: 'terminal-control',
action: 'queue',
status: 'applied',
createdAt: new Date(createdAt.getTime() + 100),
updatedAt: new Date(createdAt.getTime() + 100),
boundary: 'turn',
},
}),
).resolves.toBe(false);
const afterTerminal = await Message.findOne({
user: 'user123',
conversationId,
messageId: 'task-1:user',
})
.select('+subagentTask')
.lean<IMessage>();
expect(afterTerminal?.subagentTask?.controlReceipts).toHaveLength(64);
expect(afterTerminal?.subagentTask?.controlReceipts).not.toEqual(
expect.arrayContaining([
expect.objectContaining({ invocationId: 'terminal-with-no-allowance' }),
]),
);
/** Completing an existing active fence always frees its own slot and wins
* over terminal history, even though its occurrence timestamp is oldest. */
await expect(
recordSubagentTaskControlReceipt({
userId: 'user123',
conversationId,
taskId: 'task-1',
receipt: {
invocationId: 'accepted-0',
fingerprint: 'fingerprint-0',
controlId: 'control-0',
action: 'queue',
status: 'applied',
createdAt,
updatedAt: new Date(createdAt.getTime() + 101),
boundary: 'turn',
},
}),
).resolves.toBe(true);
const afterTransition = await Message.findOne({
user: 'user123',
conversationId,
messageId: 'task-1:user',
})
.select('+subagentTask')
.lean<IMessage>();
expect(afterTransition?.subagentTask?.controlReceipts).toHaveLength(64);
expect(afterTransition?.subagentTask?.controlReceipts).toEqual(
expect.arrayContaining([
expect.objectContaining({ invocationId: 'accepted-0', status: 'applied' }),
expect.objectContaining({ invocationId: 'accepted-63', status: 'accepted' }),
]),
);
});
});
describe('claimSubagentTaskResult', () => {
const terminalResult = async (taskId: string, conversationId: string, status: string) =>
saveMessage({ userId: 'user123' }, {
messageId: `${taskId}:assistant`,
conversationId,
text: 'child result',
subagentTask: { attemptKey: `${taskId}:attempt`, status },
} as Partial<IMessage>);
it('hands one terminal result to a single polling invocation', async () => {
const taskId = uuidv4();
const conversationId = uuidv4();
await terminalResult(taskId, conversationId, 'completed');
const first = await claimSubagentTaskResult({
userId: 'user123',
conversationId,
taskId,
kind: 'manual',
claimId: 'poll-1',
});
expect(first.status).toBe('acquired');
expect(first.status === 'acquired' && first.message.text).toBe('child result');
/** The same invocation retrying recovers the result it never received. */
const retried = await claimSubagentTaskResult({
userId: 'user123',
conversationId,
taskId,
kind: 'manual',
claimId: 'poll-1',
});
expect(retried.status).toBe('acquired');
/** Another invocation is told it was collected instead of handed a copy. */
await expect(
claimSubagentTaskResult({
userId: 'user123',
conversationId,
taskId,
kind: 'manual',
claimId: 'poll-2',
}),
).resolves.toMatchObject({ status: 'claimed' });
});
it('elects either a manual poll or one idempotent automatic wakeup', async () => {
const manualTaskId = uuidv4();
const wakeupTaskId = uuidv4();
const conversationId = uuidv4();
await terminalResult(manualTaskId, conversationId, 'completed');
await terminalResult(wakeupTaskId, conversationId, 'completed');
await expect(
claimSubagentTaskResult({
userId: 'user123',
conversationId,
taskId: manualTaskId,
kind: 'manual',
claimId: 'poll-1',
}),
).resolves.toMatchObject({ status: 'acquired' });
await expect(
claimSubagentTaskResult({
userId: 'user123',
conversationId,
taskId: manualTaskId,
kind: 'wakeup',
claimId: 'delivery-1',
}),
).resolves.toMatchObject({ status: 'claimed' });
const wakeupClaim = {
userId: 'user123',
conversationId,
taskId: wakeupTaskId,
kind: 'wakeup' as const,
claimId: 'delivery-2',
};
await expect(claimSubagentTaskResult(wakeupClaim)).resolves.toMatchObject({
status: 'acquired',
});
await expect(claimSubagentTaskResult(wakeupClaim)).resolves.toMatchObject({
status: 'acquired',
});
await expect(
claimSubagentTaskResult({ ...wakeupClaim, claimId: 'delivery-3' }),
).resolves.toMatchObject({ status: 'claimed' });
await expect(
claimSubagentTaskResult({ ...wakeupClaim, kind: 'manual', claimId: 'poll-2' }),
).resolves.toMatchObject({ status: 'claimed' });
});
it('preserves and upgrades retries of legacy manual claims without a kind', async () => {
const taskId = uuidv4();
const conversationId = uuidv4();
await terminalResult(taskId, conversationId, 'completed');
await claimSubagentTaskResult({
userId: 'user123',
conversationId,
taskId,
kind: 'manual',
claimId: 'legacy-poll',
});
await Message.collection.updateOne(
{ user: 'user123', conversationId, messageId: `${taskId}:assistant` },
{ $unset: { 'subagentTask.resultClaim.kind': '' } },
);
await expect(
claimSubagentTaskResult({
userId: 'user123',
conversationId,
taskId,
kind: 'manual',
claimId: 'legacy-poll',
}),
).resolves.toMatchObject({
status: 'acquired',
message: { subagentTask: { resultClaim: { kind: 'manual', claimId: 'legacy-poll' } } },
});
await expect(
claimSubagentTaskResult({
userId: 'user123',
conversationId,
taskId,
kind: 'wakeup',
claimId: 'legacy-poll',
}),
).resolves.toMatchObject({ status: 'claimed' });
});
it('releases only the exact rejected wakeup so manual collection can take over', async () => {
const taskId = uuidv4();
const conversationId = uuidv4();
await terminalResult(taskId, conversationId, 'completed');
const wakeup = {
userId: 'user123',
conversationId,
taskId,
kind: 'wakeup' as const,
claimId: 'delivery-1',
};
await expect(claimSubagentTaskResult(wakeup)).resolves.toMatchObject({
status: 'acquired',
});
await expect(
releaseSubagentTaskResultClaim({ ...wakeup, claimId: 'another-delivery' }),
).resolves.toBe(false);
await expect(releaseSubagentTaskResultClaim(wakeup)).resolves.toBe(true);
await expect(
claimSubagentTaskResult({
userId: 'user123',
conversationId,
taskId,
kind: 'manual',
claimId: 'poll-after-rejection',
}),
).resolves.toMatchObject({ status: 'acquired' });
});
it('reports a result that is missing or still running as not found', async () => {
const runningTaskId = uuidv4();
const conversationId = uuidv4();
await terminalResult(runningTaskId, conversationId, 'running');
await expect(
claimSubagentTaskResult({
userId: 'user123',
conversationId,
taskId: runningTaskId,
kind: 'manual',
claimId: 'poll-1',
}),
).resolves.toEqual({ status: 'not_found' });
await expect(
claimSubagentTaskResult({
userId: 'user123',
conversationId,
taskId: uuidv4(),
kind: 'manual',
claimId: 'poll-1',
}),
).resolves.toEqual({ status: 'not_found' });
});
it('never hands one owner’s result to another user', async () => {
const taskId = uuidv4();
const conversationId = uuidv4();
await terminalResult(taskId, conversationId, 'completed');
await expect(
claimSubagentTaskResult({
userId: 'other-user',
conversationId,
taskId,
kind: 'manual',
claimId: 'poll-1',
}),
).resolves.toEqual({ status: 'not_found' });
});
});
});
describe('receipt-backed claim release before projection', () => {
it('allows a missing message only when the receipt owner explicitly opts in', async () => {
const input = {
userId: new mongoose.Types.ObjectId().toString(),
conversationId: 'missing-conversation',
messageId: 'missing-parent',
kind: 'wakeup' as const,
claimId: 'batch-root',
};
await expect(releaseBackgroundToolResultClaims(input)).resolves.toBe(false);
await expect(
releaseBackgroundToolResultClaims({ ...input, allowMissingMessage: true }),
).resolves.toBe(true);
});
});
describe('receipt batch projection epochs', () => {
it('does not let delayed cleanup remove a successor claim on the same logical request', async () => {
await Message.create({
messageId: 'epoch-parent',
conversationId: 'epoch-conversation',
user: 'epoch-owner',
isCreatedByUser: false,
unfinished: false,
content: [
{
type: 'tool_call',
tool_call: {
id: 'epoch-call',
output: 'done',
backgroundTask: {
taskId: 'epoch-task',
toolName: 'tool',
status: 'completed',
completionWakeup: true,
completionReceipt: true,
},
},
},
],
});
const input = {
userId: 'epoch-owner',
conversationId: 'epoch-conversation',
messageId: 'epoch-parent',
taskId: 'epoch-task',
kind: 'wakeup' as const,
claimId: 'logical-root',
limit: 1,
};
expect((await claimBackgroundToolResults({ ...input, batchId: 'old' })).status).toBe(
'acquired',
);
let pause: () => void = () => undefined;
let resume: () => void = () => undefined;
const paused = new Promise<void>((resolve) => {
pause = resolve;
});
const barrier = new Promise<void>((resolve) => {
resume = resolve;
});
const update = Message.findOneAndUpdate.bind(Message);
const oldCleanup = jest.spyOn(Message, 'findOneAndUpdate').mockImplementationOnce((...args) => {
const query = update(...args);
const execute = query.exec.bind(query);
jest.spyOn(query, 'exec').mockImplementationOnce(async () => {
pause();
await barrier;
return execute();
});
return query;
});
const predecessor = releaseBackgroundToolResultClaims({ ...input, batchId: 'old' });
await paused;
expect(await releaseBackgroundToolResultClaims({ ...input, batchId: 'old' })).toBe(true);
expect((await claimBackgroundToolResults({ ...input, batchId: 'new' })).status).toBe(
'acquired',
);
resume();
expect(await predecessor).toBe(true);
oldCleanup.mockRestore();
expect((await claimBackgroundToolResults({ ...input, batchId: 'new' })).status).toBe(
'acquired',
);
expect(await claimBackgroundToolResults({ ...input, batchId: 'old' })).toMatchObject({
status: 'claimed',
claim: { batchId: 'new' },
});
});
});