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 { ContentTypes, ErrorTypes } from 'librechat-data-provider';
import { COMPACTION_SEMANTIC_INDEX_LIMITS } from '@librechat/agents';
import {
MAX_COMPACTION_SEMANTIC_INDEX_ENTRIES,
MAX_COMPACTION_SEMANTIC_INDEX_IDENTITY_LENGTH,
MAX_COMPACTION_SEMANTIC_INDEX_SOURCE_CONTENT_INDEX,
MAX_COMPACTION_SEMANTIC_INDEX_TEXT_LENGTH,
AGENT_EVENT_ACTOR_SUMMARY_VERSION,
} from '@librechat/data-schemas';
import type { CompactionSemanticIndex, CompactionSemanticIndexSnapshot } from '@librechat/agents';
import type { SummaryContentPart, TMessageContentParts } from 'librechat-data-provider';
import type { ICompactionSemanticIndexProjection } from '@librechat/data-schemas';
import {
createCompactionSemanticIndexProjection,
dropUnusableSummaryParts,
findCheckpointSummaryPart,
getSummaryPartText,
markAbortedCompactionContent,
markCompactionOutcome,
persistFinalizedCompactionTurn,
isSettledJobRecord,
resolveDisconnectSnapshotMode,
resolveReconciledSnapshotEnvelope,
planAbortedTurnPersistence,
planDisconnectSnapshot,
createDisconnectSnapshotQueue,
announceDisconnectSnapshot,
resolveAbortedTurnPersistence,
resolveAbortedTurnAnchorDecision,
settleExistingRowsBeforeErrorTurn,
resolveFailedTurnContent,
resolveCheckpointMessage,
resolveFinalizedCompactionTurn,
restoreCompactionSemanticIndexSnapshot,
stripUnusableSummaryParts,
getLatestEventActorSummary,
} from './compaction';
import { MAX_RESPONSE_MESSAGE_ID_LENGTH } from '~/utils/message';
const index = [
{
type: 'activity_phase',
sourceMessageId: 'message-1',
sourceContentIndex: 2,
revision: 1,
status: 'committed',
text: 'Verified the release',
},
{
type: 'reasoning_label',
sourceMessageId: 'message-1',
sourceContentIndex: 3,
revision: 2,
status: 'pending',
text: 'This pending text must not persist',
reasoningStepId: 'reasoning-1',
},
] satisfies CompactionSemanticIndex;
describe('compaction semantic index continuation projection', () => {
it('keeps persistence bounds aligned with the SDK admission limits', () => {
expect(MAX_COMPACTION_SEMANTIC_INDEX_ENTRIES).toBe(
COMPACTION_SEMANTIC_INDEX_LIMITS.maxInputEntries,
);
expect(MAX_COMPACTION_SEMANTIC_INDEX_TEXT_LENGTH).toBe(
COMPACTION_SEMANTIC_INDEX_LIMITS.maxInputTextChars,
);
expect(MAX_COMPACTION_SEMANTIC_INDEX_IDENTITY_LENGTH).toBe(
COMPACTION_SEMANTIC_INDEX_LIMITS.maxIdentityChars,
);
expect(MAX_COMPACTION_SEMANTIC_INDEX_SOURCE_CONTENT_INDEX).toBe(
COMPACTION_SEMANTIC_INDEX_LIMITS.maxSourceContentIndex,
);
});
it('snapshots exact JSON-safe guidance and blanks pending text', () => {
const projection = createCompactionSemanticIndexProjection(index);
expect(projection).toEqual({
version: 1,
providedEntryCount: 2,
entries: [
index[0],
{
...index[1],
text: '',
},
],
});
expect(restoreCompactionSemanticIndexSnapshot(projection)?.entries).toEqual(
projection?.entries,
);
});
it('preserves cumulative omission counts across JSON persistence', () => {
const snapshot = {
entries: index,
providedEntryCount: 17,
} satisfies CompactionSemanticIndexSnapshot;
const projection = createCompactionSemanticIndexProjection(snapshot);
expect(projection).toEqual({
version: 1,
entries: [index[0], { ...index[1], text: '' }],
providedEntryCount: 17,
});
expect(restoreCompactionSemanticIndexSnapshot(JSON.parse(JSON.stringify(projection)))).toEqual({
entries: projection?.entries,
providedEntryCount: 17,
});
});
it('defaults legacy projections to their retained entry count', () => {
const legacyProjection = {
version: 1,
entries: [index[0]],
} satisfies ICompactionSemanticIndexProjection;
expect(restoreCompactionSemanticIndexSnapshot(legacyProjection)).toEqual({
entries: legacyProjection.entries,
providedEntryCount: 1,
});
});
it('fails closed for malformed or oversized continuation state', () => {
const malformed = {
version: 1,
entries: [{ ...index[0], sourceContentIndex: -1 }],
} as ICompactionSemanticIndexProjection;
const oversized = {
version: 1,
entries: Array.from({ length: MAX_COMPACTION_SEMANTIC_INDEX_ENTRIES + 1 }, () => index[0]),
} as ICompactionSemanticIndexProjection;
const corrupt = {
version: 1,
entries: [null],
} as never;
const impossibleCount = {
version: 1,
entries: index,
providedEntryCount: 1,
} as ICompactionSemanticIndexProjection;
expect(restoreCompactionSemanticIndexSnapshot(malformed)?.entries).toBeUndefined();
expect(restoreCompactionSemanticIndexSnapshot(oversized)?.entries).toBeUndefined();
expect(restoreCompactionSemanticIndexSnapshot(corrupt)?.entries).toBeUndefined();
expect(restoreCompactionSemanticIndexSnapshot(impossibleCount)).toBeUndefined();
expect(createCompactionSemanticIndexProjection(oversized.entries)).toBeUndefined();
});
it('redacts oversized text before persistence', () => {
const projection = createCompactionSemanticIndexProjection([
{
...index[0],
text: 'x'.repeat(MAX_COMPACTION_SEMANTIC_INDEX_TEXT_LENGTH + 1),
},
]);
expect(projection?.entries[0]).toEqual({
...index[0],
text: '',
redacted: true,
});
});
});
/** Only a completed round's final block carries a boundary; streamed deltas never do. */
const completedBoundary = { messageId: 'step_summary', contentIndex: 0 };
describe('markCompactionOutcome', () => {
const summary = (
text: string,
overrides: Partial<SummaryContentPart> = {},
): TMessageContentParts => ({
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text }],
boundary: completedBoundary,
...overrides,
});
const failure = (error: string): TMessageContentParts => ({ type: ContentTypes.ERROR, error });
it('marks the summary a compaction produced', () => {
const parts = [summary('Earlier turns, compacted.')];
markCompactionOutcome(parts);
expect(parts[0]).toMatchObject({ initiatedBy: 'user' });
});
/** The turn has no other record of having been a compaction: without the
* marker a failure hanging off a user message keeps a Regenerate that
* answers that message instead of redoing the compaction. */
it('marks the failure a compaction recorded instead of a summary', () => {
const parts = [failure('Nothing to summarize')];
markCompactionOutcome(parts);
expect(parts[0]).toMatchObject({ initiatedBy: 'user' });
});
it('marks the failure when only a partial summary streamed before it', () => {
const parts = [summary('Half a checkpoint', { failed: true }), failure('Summarization failed')];
markCompactionOutcome(parts);
expect(parts[0]).not.toHaveProperty('initiatedBy');
expect(parts[1]).toMatchObject({ initiatedBy: 'user' });
});
/** The fallback the reviewed head threw on: a run that produced neither a
* summary nor an explanation now records the typed failure itself, so the
* turn carries the marker on the stream and in storage instead of being
* saved as a bare error row with no content. */
it.each([
['nothing at all', []],
['an empty summary', [summary(' ')]],
[
'a partial summary with no recorded failure',
[summary('Half a checkpoint', { failed: true })],
],
])('records a marked typed failure for a run that produced %s', (_label, parts) => {
markCompactionOutcome(parts);
/** The typed failure is the turn's whole outcome: a truncated summary left
* beside it would report the same failure a second time. */
expect(parts).toEqual([
{
type: ContentTypes.ERROR,
error: JSON.stringify({ type: ErrorTypes.COMPACTION_FAILED }),
initiatedBy: 'user',
},
]);
});
/** A cancelled compaction stopped early rather than failing, and the abort
* path owns that turn: it must not be turned into a failure row. */
it('fails as a typed error when the run was cancelled', () => {
const parts: TMessageContentParts[] = [];
expect(() => markCompactionOutcome(parts, { aborted: true })).toThrow(
JSON.stringify({ type: ErrorTypes.COMPACTION_FAILED }),
);
expect(parts).toHaveLength(0);
});
});
describe('resolveFailedTurnContent', () => {
/** A thrown failure leaves the turn with no content of its own, so the row a
* compaction persists carries the marked failure instead. */
it('gives a failed compaction turn its marked failure content', () => {
expect(resolveFailedTurnContent({ compact: true }, 'Summarization failed')).toEqual({
content: [{ type: ContentTypes.ERROR, error: 'Summarization failed', initiatedBy: 'user' }],
});
});
it.each([
['an ordinary turn', { compact: false }],
['a turn that never asked to compact', {}],
['a request with no body', undefined],
])('leaves %s with its text-only shape', (_label, requestBody) => {
expect(resolveFailedTurnContent(requestBody, 'Something failed')).toEqual({});
});
});
describe('resolveCheckpointMessage', () => {
const summaryPart = {
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'Earlier context' }],
boundary: completedBoundary,
tokenCount: 7,
};
it('keeps the parts a response produced after its summary', () => {
const trailingText = { type: ContentTypes.TEXT, text: 'Answer after summarizing' };
const message = {
messageId: 'response',
tokenCount: 90,
content: [{ type: ContentTypes.TEXT, text: 'Before summarizing' }, summaryPart, trailingText],
};
const resolved = resolveCheckpointMessage(message);
expect(resolved).toEqual({ messageId: 'response', content: [summaryPart, trailingText] });
expect(resolved?.tokenCount).toBeUndefined();
});
it('starts at the last usable summary', () => {
const between = { type: ContentTypes.TEXT, text: 'Between summaries' };
const after = { type: ContentTypes.TEXT, text: 'After the latest' };
const latest = {
...summaryPart,
content: [{ type: ContentTypes.TEXT, text: 'Latest context' }],
};
expect(resolveCheckpointMessage({ content: [summaryPart, between, latest, after] })).toEqual({
content: [latest, after],
});
});
it('keeps the parts after a completed summary when a later one failed', () => {
const after = { type: ContentTypes.TEXT, text: 'After the completed summary' };
const failed = { ...summaryPart, failed: true };
expect(resolveCheckpointMessage({ content: [summaryPart, after, failed] })).toEqual({
content: [summaryPart, after, failed],
});
});
it('returns the row itself when it already starts at its summary', () => {
const message = { content: [summaryPart], tokenCount: 12 };
expect(resolveCheckpointMessage(message)).toBe(message);
});
it('replaces the whole row for a legacy summary field', () => {
expect(
resolveCheckpointMessage({ summary: 'Legacy', summaryTokenCount: 4, tokenCount: 30 }),
).toEqual({
summary: 'Legacy',
summaryTokenCount: 4,
role: 'system',
content: [{ type: ContentTypes.TEXT, text: 'Legacy' }],
tokenCount: 4,
});
});
it('is null for a row that is no checkpoint', () => {
expect(resolveCheckpointMessage({ content: [{ ...summaryPart, failed: true }] })).toBeNull();
expect(
resolveCheckpointMessage({ content: [{ type: ContentTypes.TEXT, text: 'x' }] }),
).toBeNull();
});
});
describe('markAbortedCompactionContent', () => {
const partialSummary = (text: string): TMessageContentParts => ({
type: ContentTypes.SUMMARY,
/** Streamed deltas never carry a boundary; a stopped round keeps them. */
content: [{ type: ContentTypes.TEXT, text }],
summarizing: true,
});
/** The summarizer opens the part when its round starts, so a stop can land
* between that and the first delta. */
const emptySummaryPlaceholder = (): TMessageContentParts => ({
type: ContentTypes.SUMMARY,
content: [],
summarizing: true,
});
const completedSummary = (text: string): TMessageContentParts => ({
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text }],
boundary: completedBoundary,
});
/** The abort path owns a cancelled run's row: its partial summary must still
* carry the marker, or on a branch ending in a user message the row keeps a
* Regenerate that answers that user turn instead of redoing the compaction.
* The truncated prefix is kept but marked failed, or its label presents it
* as a finished checkpoint. */
it('marks the partial summary a stopped compaction had streamed as failed', () => {
const parts = [partialSummary('Half a summary')];
const marked = markAbortedCompactionContent(parts, true);
expect(marked).toHaveLength(1);
expect(marked[0]).toMatchObject({ initiatedBy: 'user', failed: true, summarizing: true });
/** The aggregated parts belong to the live run: the input is untouched. */
expect(parts[0]).not.toHaveProperty('initiatedBy');
});
/** A round that finished before the Stop landed is a real checkpoint: the
* race is not a failure. */
it('marks a summary that completed before the stop without failing it', () => {
const parts = [completedSummary('Finished before the stop.')];
const marked = markAbortedCompactionContent(parts, true);
expect(marked).toHaveLength(1);
expect(marked[0]).toMatchObject({ initiatedBy: 'user' });
expect(marked[0]).not.toHaveProperty('failed');
});
/** Every part that can carry the marker gets it: the row's identity must not
* depend on which of its parts a reader inspects first. */
it('marks an error part the stopped run had already recorded', () => {
const parts: TMessageContentParts[] = [
partialSummary('Half a summary'),
{ type: ContentTypes.ERROR, error: 'Something else failed first' },
];
const marked = markAbortedCompactionContent(parts, true);
expect(marked[0]).toMatchObject({ initiatedBy: 'user', failed: true });
expect(marked[1]).toMatchObject({ initiatedBy: 'user' });
});
/** A summary placeholder with no text is not an outcome: nothing of the
* round survived to show, so the typed failure is the row's whole
* outcome. */
it('replaces a summary placeholder that streamed nothing with the typed failure', () => {
const parts = [emptySummaryPlaceholder()];
const marked = markAbortedCompactionContent(parts, true);
expect(marked).toEqual([
{
type: ContentTypes.ERROR,
error: JSON.stringify({ type: ErrorTypes.COMPACTION_FAILED }),
initiatedBy: 'user',
},
]);
});
/** An earlier round's checkpoint is not the stopped round's outcome: the
* failure lands beside it, or the row reads as the successful compaction
* the checkpoint describes (and as a leaf that can no longer compact). */
it('records the typed failure beside an earlier checkpoint when the current round streamed nothing', () => {
const parts = [completedSummary('An earlier checkpoint.'), emptySummaryPlaceholder()];
const marked = markAbortedCompactionContent(parts, true);
expect(marked).toEqual([
expect.objectContaining({
type: ContentTypes.SUMMARY,
initiatedBy: 'user',
}),
{
type: ContentTypes.ERROR,
error: JSON.stringify({ type: ErrorTypes.COMPACTION_FAILED }),
initiatedBy: 'user',
},
]);
});
/** Checkpoints are last-summary-wins: an earlier round that never
* finished is superseded by the later usable summary, not a failure. */
it('synthesizes no failure when a later round completed after an empty one', () => {
const parts = [emptySummaryPlaceholder(), completedSummary('The later checkpoint.')];
const marked = markAbortedCompactionContent(parts, true);
expect(marked).toEqual([
expect.objectContaining({
type: ContentTypes.SUMMARY,
initiatedBy: 'user',
}),
]);
});
/** A run stopped before any part streamed still needs an identifiable row:
* an empty one reads as an answer to the message it hangs off. */
it('records the typed failure when nothing streamed before the stop', () => {
const parts: TMessageContentParts[] = [];
const marked = markAbortedCompactionContent(parts, true);
expect(marked).toEqual([
{
type: ContentTypes.ERROR,
error: JSON.stringify({ type: ErrorTypes.COMPACTION_FAILED }),
initiatedBy: 'user',
},
]);
});
/** The disconnect save runs while the generation is still live and the
* completion path overwrites the row: it stamps identity and rewrites
* nothing else, not even the failure flag of a still-streaming part. */
it('marks a non-terminal snapshot without failing or synthesizing anything', () => {
const parts: TMessageContentParts[] = [partialSummary('Half a summary')];
const marked = markAbortedCompactionContent(parts, true, { synthesizeFailure: false });
expect(marked).toEqual([{ ...partialSummary('Half a summary'), initiatedBy: 'user' }]);
expect(parts[0]).not.toHaveProperty('initiatedBy');
});
it('returns content from a turn that was not a compaction unchanged', () => {
const parts = [partialSummary('An automatic detour partial')];
expect(markAbortedCompactionContent(parts, false)).toBe(parts);
expect(parts[0]).not.toHaveProperty('initiatedBy');
});
});
describe('resolveAbortedTurnAnchorDecision', () => {
const reader = (exists: boolean) => jest.fn(async () => exists);
const jobData = {
compact: true,
conversationId: 'conversation-1',
userMessage: { messageId: 'leaf-1' },
};
it('keeps the prerequisite user write for an ordinary turn', async () => {
const messageExists = reader(true);
await expect(resolveAbortedTurnAnchorDecision({}, { messageExists })).resolves.toBe('persist');
await expect(resolveAbortedTurnAnchorDecision(null, { messageExists })).resolves.toBe(
'persist',
);
expect(messageExists).not.toHaveBeenCalled();
});
/** The compaction's `userMessage` is the persisted leaf projected for
* identity only; upserting it would erase the leaf. */
it('skips the prerequisite write for a compaction anchored on a persisted leaf', async () => {
await expect(
resolveAbortedTurnAnchorDecision(jobData, { messageExists: reader(true) }),
).resolves.toBe('skip-anchor');
});
/** Stop can win the race before the branch loaded, leaving the projection
* with no row behind it: a response written there would be orphaned. */
it('skips the whole turn when the compaction anchor was never persisted', async () => {
await expect(
resolveAbortedTurnAnchorDecision(jobData, { messageExists: reader(false) }),
).resolves.toBe('skip-turn');
});
it('skips the whole turn when a compaction carries no anchor id', async () => {
const messageExists = reader(true);
for (const userMessage of [undefined, null, {}, { messageId: '' }]) {
await expect(
resolveAbortedTurnAnchorDecision({ ...jobData, userMessage }, { messageExists }),
).resolves.toBe('skip-turn');
}
expect(messageExists).not.toHaveBeenCalled();
});
/** A read that throws must not escape past the caller's remaining cleanup:
* nothing is known about the anchor, so nothing is written either. */
it('skips the whole turn when the anchor read fails', async () => {
const messageExists = jest.fn(async () => {
throw new Error('mongo unavailable');
});
await expect(resolveAbortedTurnAnchorDecision(jobData, { messageExists })).resolves.toBe(
'skip-turn',
);
});
});
describe('persistFinalizedCompactionTurn', () => {
it('writes the finalized content with the terminal envelope', async () => {
const saved: Record<string, unknown>[] = [];
const partialRow = {
content: [
{
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'Half a summary' }],
summarizing: true,
},
],
};
await persistFinalizedCompactionTurn(
partialRow,
{ compact: true },
{
messageId: 'response-1',
conversationId: 'conversation-1',
saveMessage: async (message) => {
saved.push(message);
return message;
},
},
);
/** The snapshot was saved `unfinished` with no error while the run was
* live; the settled row must not keep reading as an incomplete
* response. */
expect(saved).toHaveLength(1);
expect(saved[0]).toMatchObject({
messageId: 'response-1',
conversationId: 'conversation-1',
unfinished: false,
error: true,
});
expect(saved[0].content).toEqual([
expect.objectContaining({ type: ContentTypes.SUMMARY, failed: true, initiatedBy: 'user' }),
]);
});
it('writes the envelope with the marking reapplied when the parts already carry the failure', async () => {
const saved: Record<string, unknown>[] = [];
const partialRow = {
content: [{ type: ContentTypes.ERROR, error: 'Summarization failed', initiatedBy: 'user' }],
};
await persistFinalizedCompactionTurn(
partialRow,
{ compact: true },
{
messageId: 'response-1',
conversationId: 'conversation-1',
saveMessage: async (message) => {
saved.push(message);
return message;
},
},
);
expect(saved).toHaveLength(1);
expect(saved[0]).toEqual({
messageId: 'response-1',
conversationId: 'conversation-1',
unfinished: false,
error: true,
content: [{ type: ContentTypes.ERROR, error: 'Summarization failed', initiatedBy: 'user' }],
});
});
it('writes nothing when the row needs no finalization', async () => {
const saveMessage = jest.fn();
await persistFinalizedCompactionTurn(
{ content: [{ type: ContentTypes.TEXT, text: 'An ordinary partial' }] },
{},
{ messageId: 'response-1', conversationId: 'conversation-1', saveMessage },
);
expect(saveMessage).not.toHaveBeenCalled();
});
/** The surrounding failed-turn persistence treats a falsy save as a
* failure, not a settled row. */
it('fails when the injected save resolves falsy', async () => {
const partialRow = {
content: [
{
type: ContentTypes.ERROR,
error: 'Summarization failed',
initiatedBy: 'user',
},
],
};
await expect(
persistFinalizedCompactionTurn(
partialRow,
{ compact: true },
{
messageId: 'response-1',
conversationId: 'conversation-1',
saveMessage: async () => null,
},
),
).rejects.toThrow('Failed compaction turn could not be finalized');
});
});
describe('resolveFinalizedCompactionTurn', () => {
const compactionFailed = JSON.stringify({ type: ErrorTypes.COMPACTION_FAILED });
it('leaves a partial row of a turn that was not a compaction alone', () => {
const row = { content: [{ type: ContentTypes.TEXT, text: 'Partial answer' }] };
expect(resolveFinalizedCompactionTurn(row, {})).toEqual({ write: false });
});
/** The disconnect snapshot is marker-only, so a run that fails afterwards
* leaves a row with no summary or error part and no marker at all. */
it('finalizes a snapshot without a summary or error part with the typed failure', () => {
const row = { content: [{ type: ContentTypes.THINK, think: 'Picking what to summarize' }] };
expect(resolveFinalizedCompactionTurn(row, { compact: true })).toEqual({
write: true,
content: [
{ type: ContentTypes.THINK, think: 'Picking what to summarize' },
{ type: ContentTypes.ERROR, error: compactionFailed, initiatedBy: 'user' },
],
});
});
it('marks a partial summary failed beside its text', () => {
const row = {
content: [
{
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'Half a summary' }],
summarizing: true,
initiatedBy: 'user',
},
],
};
expect(resolveFinalizedCompactionTurn(row, { compact: true })).toEqual({
write: true,
content: [
{
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'Half a summary' }],
summarizing: true,
initiatedBy: 'user',
failed: true,
},
],
});
});
/** The parts already carry the failure, but the snapshot's live-run flags
* are still unsettled: the write settles the envelope with the marking
* reapplied (idempotent on marked parts). */
it('settles a row whose parts already carry the failure', () => {
const failedSummary = {
content: [
{
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'Half a summary' }],
summarizing: true,
failed: true,
initiatedBy: 'user',
},
],
};
const recordedFailure = {
content: [{ type: ContentTypes.ERROR, error: 'Summarization failed', initiatedBy: 'user' }],
};
expect(resolveFinalizedCompactionTurn(failedSummary, { compact: true })).toEqual({
write: true,
content: failedSummary.content,
});
expect(resolveFinalizedCompactionTurn(recordedFailure, { compact: true })).toEqual({
write: true,
content: recordedFailure.content,
});
});
/** Legacy and imported rows can carry failure parts that predate the
* identity marker: the settle write stamps them, or the restored turn
* keeps the wrong rerun target. */
it('stamps legacy failure parts that never carried the marker', () => {
const legacyRow = {
unfinished: true,
content: [{ type: ContentTypes.ERROR, error: 'Summarization failed' }],
};
expect(resolveFinalizedCompactionTurn(legacyRow, { compact: true })).toEqual({
write: true,
content: [{ type: ContentTypes.ERROR, error: 'Summarization failed', initiatedBy: 'user' }],
});
});
/** A checkpoint the run completed before failing is preserved as content,
* but a snapshot still flagged unfinished settles its envelope: the
* restored conversation must not keep treating the terminal job as live. */
it('settles the envelope of an unfinished snapshot holding a completed checkpoint', () => {
const snapshot = {
unfinished: true,
content: [
{
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'A finished checkpoint.' }],
boundary: completedBoundary,
},
],
};
expect(resolveFinalizedCompactionTurn(snapshot, { compact: true })).toEqual({
write: true,
content: [
{
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'A finished checkpoint.' }],
boundary: completedBoundary,
initiatedBy: 'user',
},
],
});
});
/** A stopped compaction is written settled by the abort route, and an
* error row is settled by its own write: a late failure leaves both. */
it.each([
['a settled error row', [{ type: ContentTypes.ERROR, error: 'Summarization failed' }], true],
[
'a settled stopped row',
[{ type: ContentTypes.SUMMARY, content: [], summarizing: true, initiatedBy: 'user' }],
false,
],
])('leaves %s untouched', (_label, content, error) => {
const row = { unfinished: false, error, content: content as TMessageContentParts[] };
expect(resolveFinalizedCompactionTurn(row, { compact: true })).toEqual({ write: false });
});
it('leaves an already-settled checkpoint row untouched', () => {
const row = {
unfinished: false,
content: [
{
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'A finished checkpoint.' }],
boundary: completedBoundary,
},
],
};
expect(resolveFinalizedCompactionTurn(row, { compact: true })).toEqual({ write: false });
});
/** A row can hold an earlier round's terminal outcome beside a later
* unfinished summary: only the inspection of every part catches it, and
* the failure lands on the summary that never finished. */
it('finalizes a later unfinished summary beside an earlier terminal outcome', () => {
const row = {
content: [
{
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'An earlier checkpoint.' }],
boundary: completedBoundary,
},
{
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'A later partial round.' }],
summarizing: true,
},
],
};
expect(resolveFinalizedCompactionTurn(row, { compact: true })).toEqual({
write: true,
content: [
{
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'An earlier checkpoint.' }],
boundary: completedBoundary,
initiatedBy: 'user',
},
{
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'A later partial round.' }],
summarizing: true,
initiatedBy: 'user',
failed: true,
},
],
});
});
});
describe('findCheckpointSummaryPart', () => {
const legacySummary = { type: ContentTypes.SUMMARY, text: 'Summary of conversation' };
it('takes the last summary that carries text', () => {
const content = [
{ type: ContentTypes.TEXT, text: 'some text' },
{
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'First' }],
boundary: completedBoundary,
},
{
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'Latest' }],
boundary: completedBoundary,
},
];
expect(getSummaryPartText(findCheckpointSummaryPart(content))).toBe('Latest');
});
/** Rows persisted before summary `content` blocks carry a bare `text`. */
it('reads a legacy summary’s text field', () => {
expect(findCheckpointSummaryPart([legacySummary])).toBe(legacySummary);
});
/** A round that failed or never finished holds a truncated prefix of the
* history it was summarizing, so the turn offers no checkpoint at all. */
it.each([
['failed', { failed: true }],
['still summarizing', { summarizing: true }],
])('offers no checkpoint when the only summary is %s', (_label, state) => {
const content = [
{
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'Partial' }],
boundary: completedBoundary,
...state,
},
];
expect(findCheckpointSummaryPart(content)).toBeNull();
});
/** A round that errored before failures were stamped kept its deltas and no
* flag. Deltas never carry a boundary, so the part still reads as unfinished. */
it('offers no checkpoint for a streamed summary that never recorded a boundary', () => {
const content = [
{ type: ContentTypes.TEXT, text: 'An answer' },
{ type: ContentTypes.SUMMARY, content: [{ type: ContentTypes.TEXT, text: 'Partial' }] },
];
expect(findCheckpointSummaryPart(content)).toBeNull();
});
it('keeps the last complete summary when a later round never recorded a boundary', () => {
const content = [
{
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'Complete' }],
boundary: completedBoundary,
},
{ type: ContentTypes.SUMMARY, content: [{ type: ContentTypes.TEXT, text: 'Partial' }] },
];
expect(getSummaryPartText(findCheckpointSummaryPart(content))).toBe('Complete');
});
it('keeps the last complete summary when a later round failed', () => {
const content = [
{
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'Complete' }],
boundary: completedBoundary,
},
{ type: ContentTypes.SUMMARY, text: 'Partial', failed: true },
];
expect(getSummaryPartText(findCheckpointSummaryPart(content))).toBe('Complete');
});
it.each([
['content without a summary', [{ type: ContentTypes.TEXT, text: 'some text' }]],
['an empty summary', [{ type: ContentTypes.SUMMARY, tokenCount: 10 }]],
['a whitespace-only summary', [{ type: ContentTypes.SUMMARY, text: ' \n' }]],
['string content', 'just a string'],
['missing content', undefined],
])('returns null for %s', (_label, content) => {
expect(findCheckpointSummaryPart(content)).toBeNull();
});
});
describe('getLatestEventActorSummary', () => {
const part = (text: string, extra: Record<string, unknown> = {}) => ({
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text }],
boundary: completedBoundary,
...extra,
});
it('stamps the last usable summary as actor state', () => {
expect(
getLatestEventActorSummary([
part('Earlier checkpoint', { tokenCount: 4 }),
{ type: ContentTypes.TEXT, text: 'An answer' },
part('Latest checkpoint', { tokenCount: 9 }),
]),
).toEqual({
text: 'Latest checkpoint',
tokenCount: 9,
version: AGENT_EVENT_ACTOR_SUMMARY_VERSION,
});
});
/** A later round that failed, is still running, or never recorded a boundary
* holds a truncated prefix; the continuation must keep the real checkpoint. */
it.each([
['failed', { failed: true }],
['still summarizing', { summarizing: true }],
['stored without a boundary', { boundary: undefined }],
])('skips a later summary that is %s', (_label, state) => {
expect(
getLatestEventActorSummary([
part('Real checkpoint', { tokenCount: 5 }),
part('Parti', state),
]),
).toMatchObject({ text: 'Real checkpoint', tokenCount: 5 });
});
it.each([
['a missing count', {}],
['a negative count', { tokenCount: -3 }],
['a non-finite count', { tokenCount: Number.NaN }],
])('records zero tokens for %s', (_label, extra) => {
expect(getLatestEventActorSummary([part('Checkpoint', extra)])).toMatchObject({
tokenCount: 0,
});
});
it.each([
['content without a usable summary', [part('Parti', { failed: true })]],
['non-array content', 'just a string'],
['missing content', undefined],
])('returns undefined for %s', (_label, content) => {
expect(getLatestEventActorSummary(content)).toBeUndefined();
});
});
describe('unusable summary parts', () => {
const failedSummary = {
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'Half a checkpoint' }],
boundary: completedBoundary,
failed: true,
};
const unfinishedSummary = {
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'Half a checkpoint' }],
boundary: completedBoundary,
summarizing: true,
};
const unstampedSummary = {
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'Half a checkpoint' }],
};
const completeSummary = {
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'Earlier turns, compacted.' }],
boundary: completedBoundary,
};
const emptySummary = { type: ContentTypes.SUMMARY, content: [], failed: true };
const text = { type: ContentTypes.TEXT, text: 'An answer' };
/** The formatter reads the last summary part with text as the history
* boundary, so an unusable one left on the prompt copy drops the turns it
* never summarized. */
it.each([
['a failed summary', failedSummary],
['a summary whose round never finished', unfinishedSummary],
['a streamed summary stored without a boundary or a flag', unstampedSummary],
])('drops %s from a prompt copy and keeps the rest of the turn', (_label, summary) => {
const message = { role: 'assistant', content: [text, summary] };
expect(dropUnusableSummaryParts(message)).toBe(true);
expect(message.content).toEqual([text]);
});
it('keeps a complete summary, so a real checkpoint still bounds the history', () => {
const message = { role: 'assistant', content: [completeSummary, failedSummary] };
expect(dropUnusableSummaryParts(message)).toBe(true);
expect(message.content).toEqual([completeSummary]);
});
/** A formatted prompt copy shares its content array with the stored message
* it came from, so the drop must repoint the copy rather than splice: a
* splice would reindex the persisted row's parts under every reader that
* holds it, including the edit path's `/content/N` provenance. */
it('leaves the stored content array it was handed untouched', () => {
const stored = [text, failedSummary];
const promptCopy = { role: 'assistant', content: stored };
expect(dropUnusableSummaryParts(promptCopy)).toBe(true);
expect(promptCopy.content).not.toBe(stored);
expect(stored).toEqual([text, failedSummary]);
});
it.each<[string, { role: string; content?: unknown }]>([
['no unusable summary', { role: 'assistant', content: [completeSummary] }],
['an empty summary, which bounds nothing', { role: 'assistant', content: [emptySummary] }],
['string content', { role: 'user', content: 'Plain text turn' }],
])('reports nothing dropped for %s', (_label, message) => {
const before = JSON.stringify(message);
expect(dropUnusableSummaryParts(message)).toBe(false);
expect(JSON.stringify(message)).toBe(before);
});
/** The memory payload is not the caller's to mutate, so that path gets a copy
* with the same parts removed and the same positions. */
it('strips a payload the caller does not own without touching it', () => {
const payload = [
{ role: 'user', content: [{ type: ContentTypes.TEXT, text: 'First question' }] },
{ role: 'assistant', content: [text, failedSummary] },
];
const result = stripUnusableSummaryParts(payload);
expect(result[0]).toBe(payload[0]);
expect(result[1].content).toEqual([text]);
expect(payload[1].content).toEqual([text, failedSummary]);
});
it('returns the same payload reference when nothing needed stripping', () => {
const payload = [{ role: 'assistant', content: [completeSummary] }];
expect(stripUnusableSummaryParts(payload)).toBe(payload);
});
});
describe('planAbortedTurnPersistence', () => {
it('writes both rows for an ordinary turn the abort must persist', () => {
expect(planAbortedTurnPersistence('persist', true)).toEqual({
writeUserRow: true,
writeResponseRow: true,
responseUnfinished: true,
withholdFinal: false,
});
});
it('writes only the response for a compaction anchored on a persisted leaf', () => {
expect(planAbortedTurnPersistence('skip-anchor', true)).toEqual({
writeUserRow: false,
writeResponseRow: true,
responseUnfinished: false,
withholdFinal: false,
});
});
it('withholds the final and every row when the anchor never persisted', () => {
expect(planAbortedTurnPersistence('skip-turn', true)).toEqual({
writeUserRow: false,
writeResponseRow: false,
responseUnfinished: false,
withholdFinal: true,
withholdReason: expect.stringContaining('anchor unavailable'),
});
});
it('writes nothing for a turn the abort would not persist', () => {
expect(planAbortedTurnPersistence('persist', false)).toEqual({
writeUserRow: false,
writeResponseRow: false,
responseUnfinished: true,
withholdFinal: false,
});
});
/** An abort with no persistable content and no created event publishes an
* early-abort FINAL of its own; withholding it would replace that frame
* with a reconciliation one even though no row was ever at stake. */
it('does not withhold the final when no row needed writing', () => {
expect(planAbortedTurnPersistence('skip-turn', false)).toEqual({
writeUserRow: false,
writeResponseRow: false,
responseUnfinished: false,
withholdFinal: false,
});
});
});
describe('resolveAbortedTurnPersistence', () => {
const jobData = {
compact: true,
conversationId: 'conversation-1',
userMessage: { messageId: 'leaf-1' },
};
/** Nothing continues a stopped compaction, so its row is written settled. */
it('writes a settled response under a persisted compaction anchor', async () => {
const getMessages = jest.fn(async () => [{ _id: 'row' }]);
const plan = await resolveAbortedTurnPersistence(jobData, true, {
userId: 'user-1',
getMessages,
});
expect(getMessages).toHaveBeenCalledWith(
{ user: 'user-1', messageId: 'leaf-1', conversationId: 'conversation-1' },
'_id',
);
expect(plan).toMatchObject({
writeUserRow: false,
writeResponseRow: true,
responseUnfinished: false,
withholdFinal: false,
persistenceErrors: [],
});
});
it('reports the withheld final when the compaction anchor is missing', async () => {
const plan = await resolveAbortedTurnPersistence(jobData, true, {
userId: 'user-1',
getMessages: jest.fn(async () => []),
});
expect(plan.writeResponseRow).toBe(false);
expect(plan.withholdFinal).toBe(true);
expect(plan.persistenceErrors).toHaveLength(1);
expect(plan.persistenceErrors[0].message).toContain('anchor unavailable');
});
/** The outage itself reaches the caller's error boundary, not only the
* synthetic withheld-turn reason an absent anchor also produces. */
it('reports the anchor read failure beside the withheld turn', async () => {
const outage = new Error('mongo unavailable');
const plan = await resolveAbortedTurnPersistence(jobData, true, {
userId: 'user-1',
getMessages: jest.fn(async () => {
throw outage;
}),
});
expect(plan.writeResponseRow).toBe(false);
expect(plan.withholdFinal).toBe(true);
expect(plan.persistenceErrors[0]).toBe(outage);
expect(plan.persistenceErrors[1].message).toContain('anchor unavailable');
});
it('reads no anchor and reports nothing when the abort writes no row', async () => {
const getMessages = jest.fn(async () => {
throw new Error('mongo unavailable');
});
const plan = await resolveAbortedTurnPersistence(jobData, false, { getMessages });
expect(getMessages).not.toHaveBeenCalled();
expect(plan).toMatchObject({
writeUserRow: false,
writeResponseRow: false,
withholdFinal: false,
persistenceErrors: [],
});
});
it('keeps an ordinary stopped reply unfinished without reading its anchor', async () => {
const getMessages = jest.fn(async () => []);
const plan = await resolveAbortedTurnPersistence({}, true, { getMessages });
expect(getMessages).not.toHaveBeenCalled();
expect(plan).toMatchObject({
writeUserRow: true,
writeResponseRow: true,
responseUnfinished: true,
persistenceErrors: [],
});
});
});
describe('settleExistingRowsBeforeErrorTurn', () => {
const partialSummaryRow = () => ({
messageId: 'live-response',
unfinished: true,
content: [
{
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'Half a summary' }],
summarizing: true,
},
],
});
const deps = (rowsByMessageId: Record<string, unknown[]>) => {
const saved: Record<string, unknown>[] = [];
return {
saved,
deps: {
userId: 'user-1',
conversationId: 'conversation-1',
errorMessageId: 'error-target',
liveResponseMessageId: 'live-response',
getMessages: jest.fn(async ({ messageId }: { messageId: string }) =>
(rowsByMessageId[messageId] ?? []).map((row) => row),
) as never,
saveFinalizedTurn: async (message: Record<string, unknown>) => {
saved.push(message);
return message;
},
},
};
};
it('settles a compaction snapshot under its live id and blocks the error row', async () => {
const { saved, deps: d } = deps({ 'live-response': [partialSummaryRow()] });
await expect(settleExistingRowsBeforeErrorTurn({ compact: true }, d)).resolves.toEqual({
covered: true,
});
expect(saved).toHaveLength(1);
expect(saved[0]).toMatchObject({
messageId: 'live-response',
unfinished: false,
error: true,
});
});
/** The error row's own path announces the persisted turn; a finalized live
* row stands in for it, so it is announced the same way. */
it('finalizes a partial row when the bounded error identity is the live response', async () => {
const announceSettledTurn = jest.fn(async () => undefined);
const { saved, deps: d } = deps({ 'live-response': [partialSummaryRow()] });
await expect(
settleExistingRowsBeforeErrorTurn(
{ compact: true },
{ ...d, errorMessageId: 'live-response', announceSettledTurn },
),
).resolves.toEqual({ covered: true });
expect(d.getMessages).toHaveBeenCalledTimes(1);
expect(d.getMessages).toHaveBeenCalledWith(
{ user: 'user-1', messageId: 'live-response', conversationId: 'conversation-1' },
undefined,
);
expect(saved).toHaveLength(1);
expect(saved[0]).toMatchObject({
messageId: 'live-response',
unfinished: false,
error: true,
});
expect(announceSettledTurn).toHaveBeenCalledWith('live-response');
});
it('propagates persistence failures when finalizing the bounded live identity', async () => {
const outage = new Error('database unavailable');
const { deps: d } = deps({ 'live-response': [partialSummaryRow()] });
const announceSettledTurn = jest.fn();
await expect(
settleExistingRowsBeforeErrorTurn(
{ compact: true },
{
...d,
errorMessageId: 'live-response',
saveFinalizedTurn: async () => {
throw outage;
},
announceSettledTurn,
},
),
).rejects.toBe(outage);
expect(announceSettledTurn).not.toHaveBeenCalled();
});
it('writes under the bounded live identity when its response has not persisted', async () => {
const { saved, deps: d } = deps({});
await expect(
settleExistingRowsBeforeErrorTurn(
{ compact: true },
{ ...d, errorMessageId: 'live-response' },
),
).resolves.toEqual({ covered: false, errorRowMessageId: 'live-response' });
expect(d.getMessages).toHaveBeenCalledTimes(1);
expect(saved).toHaveLength(0);
});
it('announces the live row it finalized', async () => {
const announceSettledTurn = jest.fn(async () => undefined);
const { deps: d } = deps({ 'live-response': [partialSummaryRow()] });
await settleExistingRowsBeforeErrorTurn({ compact: true }, { ...d, announceSettledTurn });
expect(announceSettledTurn).toHaveBeenCalledWith('live-response');
});
it('announces nothing when the existing row needed no write', async () => {
const announceSettledTurn = jest.fn(async () => undefined);
const { saved, deps: d } = deps({ 'live-response': [{ messageId: 'live-response' }] });
await settleExistingRowsBeforeErrorTurn({}, { ...d, announceSettledTurn });
expect(saved).toHaveLength(0);
expect(announceSettledTurn).not.toHaveBeenCalled();
});
/** The error id normalizes back to the anchor itself when the anchor ends
* in `_`: the anchor match must not stop the live row from settling, and
* nothing may be written over that match. */
it('settles the live row past an anchor-shaped collision', async () => {
const { saved, deps: d } = deps({
'error-target': [{ messageId: 'error-target', _id: 'anchor-shaped-match' }],
'live-response': [partialSummaryRow()],
});
await expect(settleExistingRowsBeforeErrorTurn({ compact: true }, d)).resolves.toEqual({
covered: true,
});
expect(saved).toHaveLength(1);
expect(saved[0]).toMatchObject({ messageId: 'live-response' });
});
/** The collision with no live row saved must not swallow the failure: the
* error row proceeds under the failed run's own response id, where it can
* never overwrite the anchor. */
it('redirects the error row to the live id when only the anchor matched', async () => {
const { saved, deps: d } = deps({
'error-target': [{ messageId: 'error-target', _id: 'anchor-shaped-match' }],
});
await expect(settleExistingRowsBeforeErrorTurn({ compact: true }, d)).resolves.toEqual({
covered: false,
errorRowMessageId: 'live-response',
});
expect(saved).toHaveLength(0);
});
/** A failure before the response id was allocated leaves nowhere safe to
* write the error row: writing it under the error id would overwrite the
* anchor, so it is withheld instead. */
it('withholds the error row when the collision has no live id to redirect to', async () => {
const { saved, deps: d } = deps({
'error-target': [{ messageId: 'error-target', _id: 'anchor-shaped-match' }],
});
const { liveResponseMessageId: _omitted, ...dWithoutLiveId } = d;
await expect(
settleExistingRowsBeforeErrorTurn({ compact: true }, dWithoutLiveId),
).resolves.toEqual({ covered: true });
expect(saved).toHaveLength(0);
});
it('blocks the error row for an ordinary turn with an existing row, writing nothing', async () => {
const { saved, deps: d } = deps({
'error-target': [{ messageId: 'error-target', _id: 'existing' }],
'live-response': [{ messageId: 'live-response', _id: 'partial' }],
});
await expect(settleExistingRowsBeforeErrorTurn({}, d)).resolves.toEqual({ covered: true });
expect(saved).toHaveLength(0);
// The ordinary early return never reads the live row.
expect(d.getMessages).toHaveBeenCalledTimes(1);
});
it('lets the error row through when no row covers the turn', async () => {
const { saved, deps: d } = deps({});
await expect(settleExistingRowsBeforeErrorTurn({ compact: true }, d)).resolves.toEqual({
covered: false,
errorRowMessageId: 'error-target',
});
expect(saved).toHaveLength(0);
});
});
describe('isSettledJobRecord', () => {
it.each(['complete', 'error', 'aborted'])('treats a %s record as settled', (status) => {
expect(isSettledJobRecord({ createdAt: 1000, status })).toBe(true);
});
/** The terminal claim precedes its row write, so the status alone does not
* prove the row is durable: the snapshot stays the fallback until the
* pending marker clears. */
it('treats a record with terminal persistence still pending as unsettled', () => {
expect(
isSettledJobRecord({ createdAt: 1000, status: 'error', terminalPersistencePending: true }),
).toBe(false);
});
/** A failed terminal write clears the marker while publishing a
* reconciliation frame: no row was persisted, so the streamed snapshot
* stays the turn's only fallback. */
it('treats a record whose durable final event is a reconciliation frame as unsettled', () => {
const reconciled = {
createdAt: 1000,
status: 'aborted',
finalEvent: JSON.stringify({ final: true, reconcile: true }),
};
const settled = {
createdAt: 1000,
status: 'aborted',
finalEvent: JSON.stringify({ final: true }),
};
expect(isSettledJobRecord(reconciled)).toBe(false);
expect(isSettledJobRecord(settled)).toBe(true);
});
it('leaves live and missing records unsettled', () => {
expect(isSettledJobRecord({ createdAt: 1000, status: 'running' })).toBe(false);
expect(isSettledJobRecord({ createdAt: 1000, status: 'requires_action' })).toBe(false);
expect(isSettledJobRecord(null)).toBe(false);
expect(isSettledJobRecord(undefined)).toBe(false);
});
/** Another epoch's record describes a different generation, not this one. */
it('ignores a record from another epoch', () => {
expect(isSettledJobRecord({ createdAt: 2000, status: 'error' }, 1000)).toBe(false);
expect(isSettledJobRecord({ createdAt: 1000, status: 'error' }, 1000)).toBe(true);
});
});
describe('resolveDisconnectSnapshotMode', () => {
it.each(['complete', 'error', 'aborted'])(
'withholds the snapshot of a %s compaction job',
async (status) => {
await expect(
resolveDisconnectSnapshotMode(true, { createdAt: 1000, status }, 1000),
).resolves.toBe('skip');
},
);
it('writes the snapshot for a live, missing, or other-epoch record', async () => {
await expect(
resolveDisconnectSnapshotMode(true, { createdAt: 1000, status: 'running' }, 1000),
).resolves.toBe('live');
await expect(resolveDisconnectSnapshotMode(true, null, 1000)).resolves.toBe('live');
await expect(
resolveDisconnectSnapshotMode(true, { createdAt: 2000, status: 'error' }, 1000),
).resolves.toBe('live');
});
/** An ordinary turn's record cannot prove its response row landed, so its
* snapshot stays the fallback whatever the record says. */
it('writes the snapshot of a settled ordinary turn', async () => {
await expect(
resolveDisconnectSnapshotMode(false, { createdAt: 1000, status: 'complete' }, 1000),
).resolves.toBe('live');
});
/** Only a compaction is promoted: an ordinary turn whose terminal write
* reconciled keeps its live snapshot as the fallback row. */
it('keeps a reconciled ordinary turn on its live snapshot', async () => {
const anchorExists = jest.fn(async () => true);
await expect(
resolveDisconnectSnapshotMode(
false,
{
createdAt: 1000,
status: 'complete',
finalEvent: JSON.stringify({ final: true, reconcile: true }),
},
1000,
{ anchorExists },
),
).resolves.toBe('live');
expect(anchorExists).not.toHaveBeenCalled();
});
const reconciled = () => ({
createdAt: 1000,
status: 'error',
finalEvent: JSON.stringify({ final: true, reconcile: true }),
});
/** The terminal write failed and settled for a reconciliation frame: the
* snapshot is promoted to the turn's terminal row, because no other row
* will ever be persisted for it. */
it('promotes a reconciled compaction snapshot to the terminal row', async () => {
await expect(resolveDisconnectSnapshotMode(true, reconciled(), 1000)).resolves.toBe('terminal');
});
/** A reconciliation frame can follow a saved error turn: a settled
* response row withholds the promotion instead of being overwritten. */
it('withholds a reconciled snapshot when the response row is settled', async () => {
await expect(
resolveDisconnectSnapshotMode(true, reconciled(), 1000, {
responseRowSettled: async () => true,
}),
).resolves.toBe('skip');
});
it('keeps the live snapshot for another epoch reconciliation frame', async () => {
const anchorExists = jest.fn(async () => true);
await expect(
resolveDisconnectSnapshotMode(true, { ...reconciled(), createdAt: 2000 }, 1000, {
anchorExists,
}),
).resolves.toBe('live');
expect(anchorExists).not.toHaveBeenCalled();
});
/** The promotion must not recreate the orphan an absent-anchor abort
* deliberately withheld: without a persisted anchor there is nothing to
* hang the terminal row on. */
it('withholds a reconciled snapshot whose anchor was never persisted', async () => {
await expect(
resolveDisconnectSnapshotMode(true, reconciled(), 1000, {
anchorExists: async () => false,
}),
).resolves.toBe('skip');
});
});
describe('resolveReconciledSnapshotEnvelope', () => {
/** The abort route writes a stopped compaction settled, so its
* reconciled fallback must not reopen it as a live row. */
it('settles an aborted claim like the abort route writes a stopped compaction', () => {
expect(resolveReconciledSnapshotEnvelope('aborted')).toEqual({
unfinished: false,
error: false,
});
});
it('settles a completed claim as a finished row', () => {
expect(resolveReconciledSnapshotEnvelope('complete')).toEqual({
unfinished: false,
error: false,
});
});
it('settles everything else with the error envelope', () => {
expect(resolveReconciledSnapshotEnvelope('error')).toEqual({
unfinished: false,
error: true,
});
expect(resolveReconciledSnapshotEnvelope(undefined)).toEqual({
unfinished: false,
error: true,
});
});
});
describe('planDisconnectSnapshot', () => {
const reconciled = {
createdAt: 1000,
status: 'error',
finalEvent: JSON.stringify({ final: true, reconcile: true }),
};
const plan = (
isCompaction: boolean,
jobRecord: Parameters<typeof planDisconnectSnapshot>[1]['jobRecord'],
content: TMessageContentParts[],
rows: Record<string, Array<{ messageId: string; unfinished?: boolean }>>,
) => {
const getMessages = jest.fn(
async (filter: { messageId: string }) => rows[filter.messageId] ?? [],
);
return {
getMessages,
result: planDisconnectSnapshot(isCompaction, {
content,
jobRecord,
jobCreatedAt: 1000,
userId: 'user-1',
conversationId: 'convo-1',
anchorMessageId: 'anchor',
responseMessageId: 'response',
getMessages,
}),
};
};
const text = { type: ContentTypes.TEXT, text: 'Partial' } as TMessageContentParts;
it('writes a live snapshot in the live shape without reading any row', async () => {
const { result, getMessages } = plan(
false,
{ createdAt: 1000, status: 'complete' },
[text],
{},
);
await expect(result).resolves.toEqual({
write: true,
content: [text],
unfinished: true,
error: false,
});
expect(getMessages).not.toHaveBeenCalled();
});
it('writes nothing for an empty live snapshot', async () => {
const { result } = plan(true, { createdAt: 1000, status: 'running' }, [], {});
await expect(result).resolves.toEqual({ write: false });
});
it('promotes a reconciled compaction under its anchor with the terminal envelope', async () => {
const { result } = plan(true, reconciled, [], { anchor: [{ messageId: 'anchor' }] });
const planned = await result;
expect(planned).toMatchObject({ write: true, unfinished: false, error: true });
expect(planned.write && planned.content).toEqual([
expect.objectContaining({ type: ContentTypes.ERROR, initiatedBy: 'user' }),
]);
});
it('promotes over an earlier live snapshot of the same turn', async () => {
const { result } = plan(true, reconciled, [text], {
anchor: [{ messageId: 'anchor' }],
response: [{ messageId: 'response', unfinished: true }],
});
await expect(result).resolves.toMatchObject({ write: true, unfinished: false });
});
it('withholds the promotion when a settled response row exists', async () => {
const { result } = plan(true, reconciled, [text], {
anchor: [{ messageId: 'anchor' }],
response: [{ messageId: 'response', unfinished: false }],
});
await expect(result).resolves.toEqual({ write: false });
});
it('reports a failed row read and writes nothing', async () => {
const readError = new Error('read failed');
const onReadError = jest.fn();
await expect(
planDisconnectSnapshot(true, {
content: [text],
jobRecord: reconciled,
jobCreatedAt: 1000,
userId: 'user-1',
conversationId: 'convo-1',
anchorMessageId: 'anchor',
responseMessageId: 'response',
getMessages: jest.fn(async () => {
throw readError;
}),
onReadError,
}),
).resolves.toEqual({ write: false });
expect(onReadError).toHaveBeenCalledWith(readError);
});
it('writes a live snapshot once but still promotes after it', async () => {
const live = planDisconnectSnapshot(true, {
content: [text],
jobRecord: { createdAt: 1000, status: 'running' },
jobCreatedAt: 1000,
userId: 'user-1',
conversationId: 'convo-1',
anchorMessageId: 'anchor',
responseMessageId: 'response',
liveSaved: true,
getMessages: jest.fn(async () => []),
});
await expect(live).resolves.toEqual({ write: false });
const getMessages = jest.fn(async (filter: { messageId: string }) =>
filter.messageId === 'anchor'
? [{ messageId: 'anchor' }]
: [{ messageId: filter.messageId, unfinished: true }],
);
const promoted = planDisconnectSnapshot(true, {
content: [text],
jobRecord: reconciled,
jobCreatedAt: 1000,
userId: 'user-1',
conversationId: 'convo-1',
anchorMessageId: 'anchor',
responseMessageId: 'response',
liveSaved: true,
getMessages,
});
await expect(promoted).resolves.toMatchObject({ write: true, unfinished: false });
});
it('withholds the promotion when the failed-turn path already saved its error row', async () => {
const { result, getMessages } = plan(true, reconciled, [text], {
anchor: [{ messageId: 'anchor' }],
anchor_: [{ messageId: 'anchor_', unfinished: false }],
});
await expect(result).resolves.toEqual({ write: false });
expect(getMessages).toHaveBeenCalledWith(
expect.objectContaining({ messageId: 'anchor_' }),
'_id unfinished',
);
});
it('still promotes when the derived error row is only an unfinished snapshot', async () => {
const { result } = plan(true, reconciled, [text], {
anchor: [{ messageId: 'anchor' }],
anchor_: [{ messageId: 'anchor_', unfinished: true }],
});
await expect(result).resolves.toMatchObject({ write: true, unfinished: false });
});
it('never treats an anchor ending in one underscore as its own terminal row', async () => {
const getMessages = jest.fn(async (filter: { messageId: string }) =>
filter.messageId === 'anchor_' ? [{ messageId: 'anchor_', unfinished: false }] : [],
);
await expect(
planDisconnectSnapshot(true, {
content: [text],
jobRecord: reconciled,
jobCreatedAt: 1000,
userId: 'user-1',
conversationId: 'convo-1',
anchorMessageId: 'anchor_',
responseMessageId: 'response',
getMessages,
}),
).resolves.toMatchObject({ write: true, unfinished: false });
expect(getMessages).toHaveBeenCalledWith(
expect.objectContaining({ messageId: 'response' }),
'_id unfinished',
);
expect(getMessages).not.toHaveBeenCalledWith(
expect.objectContaining({ messageId: 'anchor_' }),
'_id unfinished',
);
});
it('reads only the response row when a full-length anchor leaves no room for the suffix', async () => {
const anchorMessageId = 'a'.repeat(MAX_RESPONSE_MESSAGE_ID_LENGTH);
const getMessages = jest.fn(async (filter: { messageId: string }) =>
filter.messageId === anchorMessageId ? [{ messageId: anchorMessageId }] : [],
);
await expect(
planDisconnectSnapshot(true, {
content: [text],
jobRecord: reconciled,
jobCreatedAt: 1000,
userId: 'user-1',
conversationId: 'convo-1',
anchorMessageId,
responseMessageId: 'response',
getMessages,
}),
).resolves.toMatchObject({ write: true, unfinished: false });
expect(getMessages.mock.calls.map(([filter]) => filter.messageId).sort()).toEqual(
[anchorMessageId, 'response'].sort(),
);
});
});
describe('createDisconnectSnapshotQueue', () => {
const text = { type: ContentTypes.TEXT, text: 'Partial' } as TMessageContentParts;
const stored = { type: ContentTypes.TEXT, text: 'Stored' } as TMessageContentParts;
it('plans once more from the stored content when a disconnected compaction settles', async () => {
const persist = jest.fn(async () => undefined);
const queue = createDisconnectSnapshotQueue({
isCompaction: true,
persist,
readContent: async () => [stored],
});
await queue.onDisconnect([]);
await queue.settle();
expect(persist.mock.calls).toEqual([[[]], [[stored]]]);
});
it('does not plan again when nobody disconnected or the turn is not a compaction', async () => {
const persist = jest.fn(async () => undefined);
const readContent = jest.fn(async () => [stored]);
await createDisconnectSnapshotQueue({ isCompaction: true, persist, readContent }).settle();
const ordinary = createDisconnectSnapshotQueue({ isCompaction: false, persist, readContent });
await ordinary.onDisconnect([text]);
await ordinary.settle();
expect(persist.mock.calls).toEqual([[[text]]]);
expect(readContent).not.toHaveBeenCalled();
});
it('waits for an outstanding snapshot write before the settle plan starts', async () => {
const order: string[] = [];
let finishLive: () => void = () => undefined;
const persist = jest.fn(async (content: TMessageContentParts[]) => {
const label = content[0] === stored ? 'settle' : 'live';
order.push(`${label}:start`);
if (label === 'live') {
await new Promise<void>((resolve) => {
finishLive = resolve;
});
}
order.push(`${label}:end`);
});
const queue = createDisconnectSnapshotQueue({
isCompaction: true,
persist,
readContent: async () => [stored],
});
const live = queue.onDisconnect([text]);
const settled = queue.settle();
await Promise.resolve();
finishLive();
await Promise.all([live, settled]);
expect(order).toEqual(['live:start', 'live:end', 'settle:start', 'settle:end']);
});
it('reports a failed settle plan and still runs after a failed live write', async () => {
const liveError = new Error('live failed');
const settleError = new Error('read failed');
const onSettleError = jest.fn();
const queue = createDisconnectSnapshotQueue({
isCompaction: true,
persist: jest.fn(async () => {
throw liveError;
}),
readContent: async () => {
throw settleError;
},
onSettleError,
});
await expect(queue.onDisconnect([text])).rejects.toBe(liveError);
await expect(queue.settle()).resolves.toBeUndefined();
expect(onSettleError).toHaveBeenCalledWith(settleError);
});
});
describe('announceDisconnectSnapshot', () => {
const announcement = {
userId: 'user-1',
conversationId: 'convo-1',
messageId: 'response',
context: 'test',
};
it('stamps a promoted terminal snapshot on its conversation', async () => {
const stampConvoLastResponse = jest.fn(async () => null);
await announceDisconnectSnapshot(
{ stampConvoLastResponse },
{ write: true, content: [], unfinished: false, error: true },
announcement,
);
expect(stampConvoLastResponse).toHaveBeenCalledWith('user-1', 'convo-1', 'response');
});
it('leaves a live or unwritten snapshot unannounced', async () => {
const stampConvoLastResponse = jest.fn(async () => null);
await announceDisconnectSnapshot(
{ stampConvoLastResponse },
{ write: true, content: [], unfinished: true, error: false },
announcement,
);
await announceDisconnectSnapshot({ stampConvoLastResponse }, { write: false }, announcement);
expect(stampConvoLastResponse).not.toHaveBeenCalled();
});
});