Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🧷 fix: Finalize Stopped Compactions and Verify Their Anchor (#16551)

Marco Berettacac13c42e77b
diff --git a/api/server/controllers/agents/__tests__/request.partialDisconnect.spec.js b/api/server/controllers/agents/__tests__/request.partialDisconnect.spec.js
index 2350045fe4..85d5ec045e 100644
--- a/api/server/controllers/agents/__tests__/request.partialDisconnect.spec.js
+++ b/api/server/controllers/agents/__tests__/request.partialDisconnect.spec.js
@@ -57,6 +57,10 @@ jest.mock('@librechat/api', () => ({
resolveResumableRetention: jest.requireActual('@librechat/api').resolveResumableRetention,
markAbortedCompactionContent: (...args) =>
jest.requireActual('@librechat/api').markAbortedCompactionContent(...args),
+ resolveDisconnectSnapshotMode: (...args) =>
+ jest.requireActual('@librechat/api').resolveDisconnectSnapshotMode(...args),
+ settleExistingRowsBeforeErrorTurn: (...args) =>
+ jest.requireActual('@librechat/api').settleExistingRowsBeforeErrorTurn(...args),
sendEvent: jest.fn(),
persistedReasoningOverrideFields:
jest.requireActual('@librechat/api').persistedReasoningOverrideFields,
@@ -342,4 +346,16 @@ describe('ResumableAgentController tenant context', () => {
});
expect(savedMessage.content).toHaveLength(1);
});
+ /** The settling path (completion, error, abort) owns the final row: a
+ * disconnect snapshot landing after it would reopen the settled turn as
+ * an unfinished response. */
+ it('skips the partial save when the job record has settled', async () => {
+ await firePartialDisconnect(
+ { id: 'user-123' },
+ { createdAt: 1000, status: 'error' },
+ { aggregatedContent: [{ type: 'text', text: 'Partial response' }] },
+ );
+
+ expect(mockSaveMessage).not.toHaveBeenCalled();
+ });
});
diff --git a/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js b/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js
index 6125e4aa7e..1d0790a95a 100644
--- a/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js
+++ b/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js
@@ -269,6 +269,10 @@ jest.mock('@librechat/api', () => ({
resolveResumableRetention: jest.requireActual('@librechat/api').resolveResumableRetention,
markAbortedCompactionContent: (...args) =>
jest.requireActual('@librechat/api').markAbortedCompactionContent(...args),
+ resolveDisconnectSnapshotMode: (...args) =>
+ jest.requireActual('@librechat/api').resolveDisconnectSnapshotMode(...args),
+ settleExistingRowsBeforeErrorTurn: (...args) =>
+ jest.requireActual('@librechat/api').settleExistingRowsBeforeErrorTurn(...args),
sendEvent: jest.fn(),
/** Real, because whether a skipped-persistence turn may raise an indicator is under test. */
isAnnounceableReply: jest.requireActual('@librechat/api').isAnnounceableReply,
diff --git a/api/server/controllers/agents/request.js b/api/server/controllers/agents/request.js
index b75182e19b..8eb3bbd2c9 100644
--- a/api/server/controllers/agents/request.js
+++ b/api/server/controllers/agents/request.js
@@ -63,6 +63,8 @@ const {
stampPreliminaryPrivateTextMessage,
announceReply,
announceErrorTurn,
+ settleExistingRowsBeforeErrorTurn,
+ resolveDisconnectSnapshotMode,
markAbortedCompactionContent,
} = require('@librechat/api');
const { disposeClient } = require('~/server/cleanup');
@@ -458,23 +460,6 @@ async function saveErrorTurn(
}
const userId = req.user.id;
- const existing = await getMessages(
- { user: userId, messageId: errorMessageId, conversationId },
- '_id',
- );
- if (existing.length > 0) {
- return;
- }
- if (liveResponseMessageId != null && liveResponseMessageId !== errorMessageId) {
- const partial = await getMessages(
- { user: userId, messageId: liveResponseMessageId, conversationId },
- '_id',
- );
- if (partial.length > 0) {
- return;
- }
- }
-
const reqCtx = {
userId,
isTemporary:
@@ -485,6 +470,35 @@ async function saveErrorTurn(
req?._agentEventBindingRetention?.expiredAt ?? req?.resolvedConversation?.expiredAt,
interfaceConfig: req?.config?.interfaceConfig,
};
+ /** The existing-row settlement (which row a failed turn settles, and
+ * whether its error row may be written at all) lives in @librechat/api;
+ * this supplies the caller's reads and write. */
+ const coveredByExistingRow = await settleExistingRowsBeforeErrorTurn(req.body, {
+ userId,
+ conversationId,
+ errorMessageId,
+ liveResponseMessageId,
+ getMessages,
+ saveFinalizedTurn: (message) =>
+ saveMessage(reqCtx, message, {
+ context: 'api/server/controllers/agents/request.js - finalize failed compaction turn',
+ }),
+ announceSettledTurn: (messageId) =>
+ announceErrorTurn(
+ { stampConvoLastResponse },
+ {
+ userId,
+ conversationId,
+ messageId,
+ isTemporary: reqCtx.isTemporary,
+ context: 'AgentController - finalized failed compaction turn',
+ },
+ ),
+ });
+ if (coveredByExistingRow) {
+ return;
+ }
+
const context = 'api/server/controllers/agents/request.js - failed turn';
const endpoint = endpointOption?.endpoint;
const model = getAgentResponseModel(req, endpointOption);
@@ -596,6 +610,13 @@ async function saveErrorTurn(
}
}
+/**
+ * The disconnect save is marker-only while the run is still live; a failed
+ * turn is what settles it, so a compaction's partial row is finalized here
+ * with the terminal outcome instead of keeping the snapshot's live-run
+ * marking. The decision lives in @librechat/api; this is the wiring, reusing
+ * the row the caller already loaded.
+ */
function classifyScheduledFailure(error, aborted = false) {
if (aborted || error?.code === 'SCHEDULE_NO_LONGER_ACTIVE') {
return { status: 'interrupted', error: error?.message };
@@ -1937,6 +1958,10 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTit
* record is the source, since the client-facing resume snapshot never
* carries server-private state. */
const contextMeta = jobRecord?.createdAt === jobCreatedAt ? jobRecord.contextMeta : undefined;
+ if (resolveDisconnectSnapshotMode(jobRecord, jobCreatedAt) === 'skip') {
+ logger.debug('[ResumableAgentController] Skipping partial response save for a settled job');
+ return;
+ }
try {
const partialMessage = {
diff --git a/api/server/routes/agents/__tests__/abort.spec.js b/api/server/routes/agents/__tests__/abort.spec.js
index 1656bb0a44..8ba35e57f6 100644
--- a/api/server/routes/agents/__tests__/abort.spec.js
+++ b/api/server/routes/agents/__tests__/abort.spec.js
@@ -27,6 +27,7 @@ const mockSaveMessage = jest.fn();
const mockHasPersistedPrivateText = jest.fn();
const mockGetPrivateMessageTexts = jest.fn();
const mockSaveConvo = jest.fn();
+const mockGetMessages = jest.fn(async () => [{ _id: 'existing-anchor' }]);
const mockRecordScheduleOutcome = jest.fn();
const mockBeginScheduledStop = jest.fn();
@@ -55,6 +56,7 @@ jest.mock('~/models', () => ({
(await mockHasPersistedPrivateText(...args)) ? 'protected-row-id' : null,
getPrivateMessageTexts: (...args) => mockGetPrivateMessageTexts(...args),
saveConvo: (...args) => mockSaveConvo(...args),
+ getMessages: (...args) => mockGetMessages(...args),
}));
jest.mock('~/server/services/Schedules', () => ({
@@ -437,12 +439,72 @@ describe('Agent Abort Endpoint', () => {
expect.objectContaining({
messageId: compactionRowId,
parentMessageId: anchorId,
- unfinished: true,
+ unfinished: false,
isCreatedByUser: false,
}),
expect.objectContaining({ context: expect.stringContaining('abort endpoint') }),
);
});
+
+ /** Stop can win the race before the branch loaded, so the projected
+ * anchor names a row that was never written: a response persisted
+ * there would be orphaned on reload. */
+ it('persists nothing when the compaction anchor was never written', async () => {
+ mockGetMessages.mockResolvedValueOnce([]);
+ const jobStreamId = 'test-stream-compact-unanchored';
+
+ mockGenerationJobManager.getJob.mockResolvedValue({
+ metadata: { userId: 'test-user-123', generationProtocolVersion: 2 },
+ });
+
+ const abortResult = {
+ success: true,
+ jobData: {
+ compact: true,
+ createdEventEmitted: true,
+ userMessage: {
+ messageId: 'never-persisted-leaf',
+ parentMessageId: 'older-response',
+ conversationId: jobStreamId,
+ text: '',
+ },
+ responseMessageId: 'compaction-response-2',
+ conversationId: jobStreamId,
+ endpoint: 'agents',
+ sender: 'TestAgent',
+ model: 'agent-1',
+ },
+ content: [
+ {
+ type: 'error',
+ error: JSON.stringify({ type: 'compaction_failed' }),
+ initiatedBy: 'user',
+ },
+ ],
+ text: '',
+ };
+ let beforePublishError;
+ mockGenerationJobManager.abortJob.mockImplementation(async (_streamId, options) => {
+ try {
+ await options.beforePublish(abortResult);
+ } catch (error) {
+ /** The manager catches this failure and publishes a
+ * reconciliation frame instead of the normal FINAL. */
+ beforePublishError = error;
+ }
+ return abortResult;
+ });
+
+ const response = await request(app)
+ .post('/api/agents/chat/abort')
+ .set('X-LibreChat-Generation-Protocol', '2')
+ .send({ conversationId: jobStreamId, generationProtocolVersion: 2 });
+
+ expect(response.status).toBe(200);
+ expect(mockSaveMessage).not.toHaveBeenCalled();
+ expect(beforePublishError).toBeInstanceOf(Error);
+ expect(beforePublishError.message).toContain('anchor unavailable');
+ });
});
describe('Partial Response Saving', () => {
diff --git a/api/server/routes/agents/index.js b/api/server/routes/agents/index.js
index b2579f3dc8..04e22c246a 100644
--- a/api/server/routes/agents/index.js
+++ b/api/server/routes/agents/index.js
@@ -6,6 +6,7 @@ const {
TERMINAL_PUBLICATION_RECONNECT_ERROR,
hasPersistableAbortContent,
announceStoppedReply,
+ resolveAbortedTurnPersistence,
buildAbortedResponseMetadata,
isPendingActionStale,
toClientPendingAction,
@@ -56,6 +57,7 @@ const {
} = require('~/server/controllers/agents/protocol');
const {
getFiles,
+ getMessages,
saveMessage,
saveConvo,
getPersistedPrivateTextId,
@@ -789,15 +791,21 @@ router.post('/chat/abort', chatConfigMiddleware, async (req, res, next) => {
* its parent and the preliminary-parent fence correctly rejects it. */
const shouldPersistAbortedTurn =
hasPersistableAbortContent(content) || jobData?.createdEventEmitted === true;
- /** A compaction's `userMessage` is the already-persisted leaf
- * projected for identity only; upserting it would erase a user
- * leaf's text or turn an assistant leaf into an empty user row. */
- const shouldPersistAnchor = jobData?.compact !== true;
+ /** The stopped turn's persistence plan (which rows to write, and
+ * whether the normal FINAL must be withheld for a reconciliation
+ * frame instead) comes from @librechat/api, decided from the
+ * compaction anchor this route reads. */
+ const abortPersistencePlan = await resolveAbortedTurnPersistence(
+ jobData,
+ shouldPersistAbortedTurn,
+ { userId: req?.user?.id, getMessages },
+ );
+ persistenceErrors.push(...abortPersistencePlan.persistenceErrors);
if (
jobData?.userMessage?.messageId &&
jobData?.responseMessageId &&
- shouldPersistAbortedTurn
+ abortPersistencePlan.writeResponseRow
) {
const messageContext = {
userId: req?.user?.id,
@@ -827,7 +835,7 @@ router.post('/chat/abort', chatConfigMiddleware, async (req, res, next) => {
endpoint: jobData.endpoint,
iconURL: jobData.iconURL,
model: jobData.model,
- unfinished: true,
+ unfinished: abortPersistencePlan.responseUnfinished,
error: false,
isCreatedByUser: false,
...(Array.isArray(jobData.userSubmittedPaths) &&
@@ -859,7 +867,7 @@ router.post('/chat/abort', chatConfigMiddleware, async (req, res, next) => {
* operation gets a chance to succeed. A compaction skips the
* prerequisite: its anchor is the persisted leaf itself. */
let persistedRequestId;
- if (shouldPersistAnchor) {
+ if (abortPersistencePlan.writeUserRow) {
try {
const persistedRequest = await saveAbortedUserMessage(
{ saveMessage, getPersistedPrivateTextId, getPrivateMessageTexts },
diff --git a/e2e/specs/mock/scenarios/compaction-abort-finalize.spec.ts b/e2e/specs/mock/scenarios/compaction-abort-finalize.spec.ts
new file mode 100644
index 0000000000..b7ed81d7a2
--- /dev/null
+++ b/e2e/specs/mock/scenarios/compaction-abort-finalize.spec.ts
@@ -0,0 +1,236 @@
+import { expect, test } from '@playwright/test';
+import type { APIRequestContext, Page } from '@playwright/test';
+import { randomUUID } from 'node:crypto';
+import { getE2EUser } from '../../../setup/user';
+import { deleteConversations, deleteMessagesByConversation, seedMessages, withMongo } from '../db';
+import {
+ MOCK_ENDPOINTS,
+ NEW_CHAT_PATH,
+ messagesView,
+ sendMessage,
+ selectMockEndpoint,
+ sendMessageAndWaitForCompletion,
+} from '../helpers';
+
+const userEmail = getE2EUser().email;
+const LABEL_SERVER = `http://127.0.0.1:${process.env.E2E_LABEL_PORT || '8889'}`;
+
+type Row = Record<string, unknown>;
+
+async function cleanup(conversationId: string) {
+ await deleteMessagesByConversation([conversationId]);
+ await deleteConversations([conversationId]);
+}
+
+function findRow(filter: Row): Promise<Row | null> {
+ return withMongo((db) => db.collection('messages').findOne(filter));
+}
+
+/** A finished exchange plus a user leaf seeded under its answer, then a manual
+ * compaction held open on that leaf until the caller presses Stop. */
+async function startCompactionOnUserLeaf(page: Page, request: APIRequestContext, label: string) {
+ await page.goto('/c/new');
+ await sendMessageAndWaitForCompletion(page, `tell me about ${label}`);
+ const conversationId = new URL(page.url()).pathname.replace('/c/', '');
+ expect(conversationId).not.toBe('new');
+
+ const answer = await withMongo((db) =>
+ db
+ .collection('messages')
+ .findOne({ conversationId, isCreatedByUser: false }, { sort: { createdAt: -1 } }),
+ );
+ expect(answer?.messageId).toBeTruthy();
+
+ const leafUserId = randomUUID();
+ const leafText = `Compact this before answering ${label}`;
+ await seedMessages(userEmail, conversationId, [
+ {
+ messageId: leafUserId,
+ parentMessageId: answer?.messageId as string,
+ text: leafText,
+ isCreatedByUser: true,
+ sender: 'User',
+ },
+ ]);
+
+ const behavior = await request.post(`${LABEL_SERVER}/__e2e/behavior`, {
+ data: { mode: 'ok', delayMs: 60_000 },
+ });
+ expect(behavior.ok()).toBeTruthy();
+
+ await page.goto(`/c/${conversationId}`);
+ await expect(messagesView(page).getByText(leafText)).toBeVisible();
+ await page.getByTestId('token-usage').click();
+ await page.getByRole('button', { name: 'Compact context' }).click();
+ const stop = page.getByTestId('stop-generation-button');
+ await expect(stop).toBeVisible({ timeout: 20_000 });
+ return { conversationId, leafUserId, leafText, stop };
+}
+
+test.describe('compaction abort finalize', () => {
+ test.afterEach(async ({ request }) => {
+ const response = await request.post(`${LABEL_SERVER}/__e2e/reset`);
+ expect(response.ok()).toBeTruthy();
+ });
+
+ /* The stopped compaction's anchor is the persisted leaf itself: the abort
+ writes a settled response under it and leaves the leaf exactly as it was. */
+ test('a stopped compaction settles under its anchor and survives a reload @scenario:stopped-compaction-settles-under-its-anchor', async ({
+ page,
+ request,
+ }) => {
+ const { conversationId, leafUserId, leafText, stop } = await startCompactionOnUserLeaf(
+ page,
+ request,
+ 'stopped-anchor',
+ );
+ try {
+ await stop.click();
+
+ let compaction: Row | null = null;
+ await expect
+ .poll(
+ async () => {
+ compaction = await findRow({
+ conversationId,
+ parentMessageId: leafUserId,
+ isCreatedByUser: false,
+ });
+ return compaction != null;
+ },
+ { timeout: 20_000 },
+ )
+ .toBeTruthy();
+ const compactionId = (compaction as Row | null)?.messageId as string;
+ await expect(stop).toBeHidden({ timeout: 20_000 });
+
+ /* The live row comes from the stopped run's final event, before any
+ reload: it must not present the stopped compaction as a reply that
+ was cut short (the notice renders 250ms after the run settles). */
+ const liveRow = page.locator(`[id="${compactionId}"]`);
+ await expect(liveRow).toBeVisible();
+ await page.waitForTimeout(1_000);
+ await expect(liveRow.getByText('This response stopped before it finished')).toHaveCount(0);
+
+ /* A live snapshot's shape would leave the turn reading as still running. */
+ const settled = await findRow({ conversationId, messageId: compactionId });
+ expect(settled?.unfinished).not.toBe(true);
+
+ const leaf = await findRow({ conversationId, messageId: leafUserId });
+ expect(leaf?.isCreatedByUser).toBe(true);
+ expect(leaf?.text).toBe(leafText);
+
+ await page.reload();
+ const row = page.locator(`[id="${compactionId}"]`);
+ await expect(row).toBeVisible({ timeout: 20_000 });
+ await expect(row.getByText('Could not compact the context', { exact: false })).toBeVisible();
+ await expect(row.getByText('Summarizing...')).toHaveCount(0);
+ await expect(messagesView(page).getByText(leafText)).toBeVisible();
+ await expect(
+ page.getByRole('navigation', { name: 'Sibling message navigation' }),
+ ).toHaveCount(0);
+ } finally {
+ await cleanup(conversationId);
+ }
+ });
+
+ /* Stop can win before the anchor exists in storage. The response would then
+ hang off a row that was never written, so the abort persists nothing for
+ it, and the run still settles instead of waiting on a final. */
+ test('a stopped compaction whose anchor is not stored writes no orphaned response @scenario:stopped-compaction-without-stored-anchor-writes-no-orphan', async ({
+ page,
+ request,
+ }) => {
+ const { conversationId, leafUserId, stop } = await startCompactionOnUserLeaf(
+ page,
+ request,
+ 'missing-anchor',
+ );
+ try {
+ await withMongo((db) =>
+ db.collection('messages').deleteOne({ conversationId, messageId: leafUserId }),
+ );
+
+ const abort = page.waitForResponse(
+ (response) =>
+ response.request().method() === 'POST' &&
+ new URL(response.url()).pathname === '/api/agents/chat/abort',
+ { timeout: 20_000 },
+ );
+ await stop.click();
+ expect((await abort).ok()).toBeTruthy();
+ await expect(stop).toBeHidden({ timeout: 20_000 });
+
+ /* Neither the anchor nor a response parented on it may appear later. */
+ await expect
+ .poll(
+ () =>
+ withMongo((db) =>
+ db.collection('messages').countDocuments({
+ conversationId,
+ $or: [{ messageId: leafUserId }, { parentMessageId: leafUserId }],
+ }),
+ ),
+ { timeout: 5_000, intervals: [1_000] },
+ )
+ .toBe(0);
+ } finally {
+ await cleanup(conversationId);
+ }
+ });
+
+ /* An ordinary reply carries no compaction anchor: Stop keeps the user turn
+ and the partial reply under it, as it did before. */
+ test('a stopped ordinary reply keeps its turn and partial answer @scenario:stopped-reply-keeps-turn-and-partial-answer', async ({
+ page,
+ }) => {
+ test.setTimeout(120_000);
+ const label = `stopped-reply-${randomUUID().slice(0, 8)}`;
+ const prompt = `E2E_SLOW_REPLY:${label}`;
+
+ await page.goto(NEW_CHAT_PATH);
+ await selectMockEndpoint(page, MOCK_ENDPOINTS[0]);
+ const run = await sendMessage(page, prompt);
+ expect(run.ok()).toBeTruthy();
+ await expect(messagesView(page).getByText('chunk-010')).toBeVisible({ timeout: 15_000 });
+
+ /* Stop while the reply is still streaming; the conversation id is read
+ once the run has settled. */
+ const stop = page.getByRole('button', { name: 'Stop generating' });
+ await stop.click({ timeout: 10_000 });
+ await expect(stop).toBeHidden({ timeout: 20_000 });
+ await expect(page).toHaveURL(/\/c\/[0-9a-fA-F-]{36}(\?|$)/, { timeout: 15_000 });
+ const conversationId = new URL(page.url()).pathname.replace('/c/', '');
+
+ try {
+ let reply: Row | null = null;
+ await expect
+ .poll(
+ async () => {
+ const user = await findRow({ conversationId, isCreatedByUser: true });
+ if (!user) {
+ return false;
+ }
+ reply = await findRow({
+ conversationId,
+ parentMessageId: user.messageId,
+ isCreatedByUser: false,
+ });
+ return reply != null;
+ },
+ { timeout: 20_000 },
+ )
+ .toBeTruthy();
+ expect(reply).not.toBeNull();
+
+ await page.reload();
+ await expect(messagesView(page).getByText(prompt)).toBeVisible({ timeout: 20_000 });
+ await expect(messagesView(page).getByText('chunk-010')).toBeVisible();
+ /* Stopped well before the end of the scripted stream. */
+ await expect(messagesView(page).getByText('chunk-159')).toHaveCount(0);
+ await expect(page.getByRole('button', { name: 'Stop generating' })).toHaveCount(0);
+ } finally {
+ await cleanup(conversationId);
+ }
+ });
+});
diff --git a/packages/api/src/agents/compaction.spec.ts b/packages/api/src/agents/compaction.spec.ts
index 5e6c2b924a..fa5bc41c02 100644
--- a/packages/api/src/agents/compaction.spec.ts
+++ b/packages/api/src/agents/compaction.spec.ts
@@ -17,8 +17,16 @@ import {
getSummaryPartText,
markAbortedCompactionContent,
markCompactionOutcome,
+ persistFinalizedCompactionTurn,
+ isSettledJobRecord,
+ resolveDisconnectSnapshotMode,
+ planAbortedTurnPersistence,
+ resolveAbortedTurnPersistence,
+ resolveAbortedTurnAnchorDecision,
+ settleExistingRowsBeforeErrorTurn,
resolveFailedTurnContent,
resolveCheckpointMessage,
+ resolveFinalizedCompactionTurn,
restoreCompactionSemanticIndex,
restoreCompactionSemanticIndexSnapshot,
stripUnusableSummaryParts,
@@ -397,6 +405,42 @@ describe('markAbortedCompactionContent', () => {
]);
});
+ /** 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()];
+
+ markAbortedCompactionContent(parts, true);
+
+ expect(parts).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.')];
+
+ markAbortedCompactionContent(parts, true);
+
+ expect(parts).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', () => {
@@ -432,6 +476,336 @@ describe('markAbortedCompactionContent', () => {
});
});
+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 only the envelope 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,
+ });
+ });
+
+ 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 without touching
+ * content. */
+ it('settles only the envelope of 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,
+ });
+ expect(resolveFinalizedCompactionTurn(recordedFailure, { compact: true })).toEqual({
+ write: true,
+ });
+ });
+
+ /** 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 });
+ });
+
+ /** 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' };
@@ -671,3 +1045,280 @@ describe('unusable summary parts', () => {
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.toBe(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('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.toBe(true);
+
+ expect(saved).toHaveLength(1);
+ expect(saved[0]).toMatchObject({ messageId: 'live-response' });
+ });
+
+ 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.toBe(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.toBe(false);
+
+ 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);
+ });
+
+ 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 job', (status) => {
+ expect(resolveDisconnectSnapshotMode({ createdAt: 1000, status }, 1000)).toBe('skip');
+ });
+
+ it('writes the snapshot for a live, missing, or other-epoch record', () => {
+ expect(resolveDisconnectSnapshotMode({ createdAt: 1000, status: 'running' }, 1000)).toBe(
+ 'live',
+ );
+ expect(resolveDisconnectSnapshotMode(null, 1000)).toBe('live');
+ expect(resolveDisconnectSnapshotMode({ createdAt: 2000, status: 'error' }, 1000)).toBe('live');
+ });
+});
diff --git a/packages/api/src/agents/compaction.ts b/packages/api/src/agents/compaction.ts
index 063870965a..529b49754d 100644
--- a/packages/api/src/agents/compaction.ts
+++ b/packages/api/src/agents/compaction.ts
@@ -224,6 +224,7 @@ export function markAbortedCompactionContent(
return contentParts;
}
let hasOutcome = false;
+ let removedUnfinishedRound = false;
for (let index = contentParts.length - 1; index >= 0; index -= 1) {
const part = contentParts[index];
if (part == null) {
@@ -256,13 +257,381 @@ export function markAbortedCompactionContent(
continue;
}
contentParts.splice(index, 1);
+ /** Walking backwards, an outcome already seen belongs to a later round:
+ * this placeholder is an earlier round the later one superseded. */
+ if (!hasOutcome) {
+ removedUnfinishedRound = true;
+ }
}
- if (!hasOutcome && synthesizeFailure) {
+ /** An earlier round's checkpoint is not this round's outcome: a round the
+ * run opened but never finished still records the typed failure beside it,
+ * or the stopped turn reads as the successful compaction the checkpoint
+ * describes. */
+ if ((!hasOutcome || removedUnfinishedRound) && synthesizeFailure) {
contentParts.push(...compactionFailureContent());
}
return contentParts;
}
+/** Whether a job record has reached a status whose path owns the turn's final
+ * row (completion, error, or abort): the disconnect snapshot must not be
+ * written over it, or the settled row reopens as an unfinished response.
+ * Only a same-epoch record is trusted. */
+export function isSettledJobRecord(
+ jobRecord: { createdAt?: number; status?: string } | null | undefined,
+ jobCreatedAt?: number,
+): boolean {
+ if (jobRecord == null || (jobCreatedAt != null && jobRecord.createdAt !== jobCreatedAt)) {
+ return false;
+ }
+ return (
+ jobRecord.status === 'complete' ||
+ jobRecord.status === 'error' ||
+ jobRecord.status === 'aborted'
+ );
+}
+
+/** How the last-subscriber disconnect may persist this turn's snapshot. */
+export type DisconnectSnapshotMode =
+ /** The run is still live: the snapshot is written as the fallback row. */
+ | 'live'
+ /** A settling path owns the final row: the snapshot is withheld so it
+ * cannot reopen the settled turn as an unfinished response. */
+ | 'skip';
+
+/**
+ * How the last-subscriber disconnect may persist this turn's snapshot, read
+ * from the same-epoch job record the caller already loaded. The guard reads
+ * the record the settling path writes, so the remaining window is that
+ * path's own commit span.
+ */
+export function resolveDisconnectSnapshotMode(
+ jobRecord: { createdAt?: number; status?: string } | null | undefined,
+ jobCreatedAt?: number,
+): DisconnectSnapshotMode {
+ return isSettledJobRecord(jobRecord, jobCreatedAt) ? 'skip' : 'live';
+}
+
+/** How the abort route persists a stopped turn's prerequisite rows. */
+export type AbortAnchorDecision = 'persist' | 'skip-anchor' | 'skip-turn';
+
+/**
+ * Decides how a stopped turn's persistence treats its user row, reading the
+ * anchor through the caller's database reader. A compaction's `userMessage`
+ * is the branch leaf projected for identity only: when the leaf is persisted,
+ * the projection must never be upserted over it (an ordinary prerequisite
+ * write would erase a user leaf's text or turn an assistant leaf into an
+ * empty user row), so only the aborted response is written. When the leaf is
+ * NOT persisted, Stop won the race before the branch loaded and there is
+ * nothing to anchor the response onto, so nothing is written at all; a read
+ * that fails says the same thing, without throwing past the caller's
+ * remaining cleanup. Ordinary turns keep the prerequisite write.
+ */
+export async function resolveAbortedTurnAnchorDecision(
+ jobData:
+ | {
+ compact?: boolean;
+ conversationId?: string;
+ userMessage?: { messageId?: string } | null;
+ }
+ | null
+ | undefined,
+ {
+ messageExists,
+ }: { messageExists: (messageId: string, conversationId?: string) => Promise<boolean> },
+): Promise<AbortAnchorDecision> {
+ if (jobData?.compact !== true) {
+ return 'persist';
+ }
+ /** A compaction with no anchor id has nothing to hang its response on. */
+ const anchorId = jobData.userMessage?.messageId;
+ if (anchorId == null || anchorId.length === 0) {
+ return 'skip-turn';
+ }
+ try {
+ const anchorExists = await messageExists(anchorId, jobData.conversationId);
+ return anchorExists ? 'skip-anchor' : 'skip-turn';
+ } catch {
+ return 'skip-turn';
+ }
+}
+
+/** The abort route's persistence plan for a stopped turn: which rows to write
+ * and whether the normal FINAL must be withheld (the manager publishes a
+ * reconciliation frame instead, so the client is never pointed at a response
+ * that was deliberately never persisted). */
+export interface AbortedTurnPersistencePlan {
+ writeUserRow: boolean;
+ writeResponseRow: boolean;
+ /** An ordinary stopped reply stays `unfinished` so it can be continued; a
+ * stopped compaction is settled, since nothing continues it and a live
+ * envelope would keep restored sessions reading it as still running. */
+ responseUnfinished: boolean;
+ withholdFinal: boolean;
+ withholdReason?: string;
+}
+
+export function planAbortedTurnPersistence(
+ anchorDecision: AbortAnchorDecision,
+ shouldPersistAbortedTurn: boolean,
+): AbortedTurnPersistencePlan {
+ const active = shouldPersistAbortedTurn && anchorDecision !== 'skip-turn';
+ /** Withholding the FINAL only matters when a row would otherwise have been
+ * written: an abort with no persistable content and no created event
+ * publishes an early-abort FINAL of its own, and nothing was withheld. */
+ const withhold = shouldPersistAbortedTurn && anchorDecision === 'skip-turn';
+ return {
+ writeUserRow: active && anchorDecision === 'persist',
+ writeResponseRow: active,
+ responseUnfinished: anchorDecision === 'persist',
+ withholdFinal: withhold,
+ ...(withhold && {
+ withholdReason: 'Compaction anchor unavailable; abort turn withheld',
+ }),
+ };
+}
+
+/**
+ * The abort route's whole persistence decision for a stopped turn: reads the
+ * compaction anchor through the caller's message reader (id-only), plans the
+ * rows, and returns the failures the route must report so the manager
+ * publishes a reconciliation frame instead of a normal FINAL.
+ */
+export async function resolveAbortedTurnPersistence(
+ jobData: Parameters<typeof resolveAbortedTurnAnchorDecision>[0],
+ shouldPersistAbortedTurn: boolean,
+ {
+ userId,
+ getMessages,
+ }: {
+ userId?: string;
+ getMessages: (
+ filter: { user?: string; messageId: string; conversationId?: string },
+ projection?: string,
+ ) => Promise<unknown[]>;
+ },
+): Promise<AbortedTurnPersistencePlan & { persistenceErrors: Error[] }> {
+ /** No row to write means no anchor to verify: the read is skipped, so an
+ * outage cannot turn an early abort's own FINAL into a reconciliation. */
+ if (!shouldPersistAbortedTurn) {
+ return { ...planAbortedTurnPersistence('persist', false), persistenceErrors: [] };
+ }
+ /** A failed read still resolves to skip-turn, so cleanup runs; the failure
+ * itself is reported beside the withheld turn, keeping an outage
+ * distinguishable from an absent anchor at the caller's error boundary. */
+ let readError: Error | undefined;
+ const anchorDecision = await resolveAbortedTurnAnchorDecision(jobData, {
+ messageExists: async (messageId, conversationId) => {
+ try {
+ return (await getMessages({ user: userId, messageId, conversationId }, '_id')).length > 0;
+ } catch (error) {
+ readError = error instanceof Error ? error : new Error(String(error));
+ throw error;
+ }
+ },
+ });
+ const plan = planAbortedTurnPersistence(anchorDecision, shouldPersistAbortedTurn);
+ const persistenceErrors: Error[] = [];
+ if (readError != null) {
+ persistenceErrors.push(readError);
+ }
+ if (plan.withholdFinal && plan.withholdReason) {
+ persistenceErrors.push(new Error(plan.withholdReason));
+ }
+ return { ...plan, persistenceErrors };
+}
+
+/** A message row as the failed-turn settlement reads it: identity for the
+ * anchor-shaped check, content and envelope for the live row it finalizes. */
+export type ReadableMessageRow = {
+ messageId: string;
+ content?: unknown;
+ unfinished?: boolean;
+};
+
+/**
+ * Settles the rows a failed generation already persisted before its error row
+ * is written, through the caller's injected reads and write. Returns whether
+ * an existing row covers the turn, in which case the caller skips the fresh
+ * error row entirely.
+ *
+ * The error id can normalize back to the compaction anchor itself when the
+ * anchor ends in `_`: a match there never receives the error row, and the
+ * failed run settles its own distinct live response row instead. Ordinary
+ * turns keep their existing behavior: a found partial row is preserved as it
+ * stands and blocks the error row.
+ */
+export async function settleExistingRowsBeforeErrorTurn(
+ requestBody: { compact?: boolean } | null | undefined,
+ {
+ userId,
+ conversationId,
+ errorMessageId,
+ liveResponseMessageId,
+ getMessages,
+ saveFinalizedTurn,
+ announceSettledTurn,
+ }: {
+ userId: string;
+ conversationId: string;
+ errorMessageId: string;
+ liveResponseMessageId?: string | null;
+ getMessages: (
+ filter: { user: string; messageId: string; conversationId: string },
+ projection?: string,
+ ) => Promise<ReadableMessageRow[]>;
+ saveFinalizedTurn: (message: Record<string, unknown>) => Promise<unknown>;
+ /** Announces a row this settlement finalized, as the error row's own
+ * path does, so other devices learn the persisted turn ended. */
+ announceSettledTurn?: (messageId: string) => Promise<unknown>;
+ },
+): Promise<boolean> {
+ const isCompaction = requestBody?.compact === true;
+ const settleLiveRow = async (): Promise<boolean> => {
+ if (liveResponseMessageId == null || liveResponseMessageId === errorMessageId) {
+ return false;
+ }
+ /** Full documents only where the compaction finalization needs the
+ * content; ordinary failures keep the id-only projection. */
+ const partial = await getMessages(
+ { user: userId, messageId: liveResponseMessageId, conversationId },
+ isCompaction ? undefined : '_id',
+ );
+ if (partial.length === 0) {
+ return false;
+ }
+ const finalized = await persistFinalizedCompactionTurn(partial[0], requestBody, {
+ messageId: liveResponseMessageId,
+ conversationId,
+ saveMessage: saveFinalizedTurn,
+ });
+ if (finalized) {
+ await announceSettledTurn?.(liveResponseMessageId);
+ }
+ return true;
+ };
+ const existing = await getMessages(
+ { user: userId, messageId: errorMessageId, conversationId },
+ '_id',
+ );
+ if (existing.length > 0) {
+ if (isCompaction) {
+ await settleLiveRow();
+ }
+ return true;
+ }
+ return settleLiveRow();
+}
+
+/**
+ * Finalizes a failed compaction's already-persisted partial row, with the
+ * write injected so the operation runs against whatever persistence the
+ * caller owns. The row settles with the terminal envelope the error path
+ * writes (an errored, finished turn): with the snapshot's `unfinished` flag
+ * left in place, restored sessions and downstream readers would keep
+ * classifying the failed turn as an incomplete response. Returns whether a
+ * write happened.
+ */
+export async function persistFinalizedCompactionTurn(
+ partialRow: { content?: unknown } | null | undefined,
+ requestBody: { compact?: boolean } | null | undefined,
+ {
+ messageId,
+ conversationId,
+ saveMessage,
+ }: {
+ messageId: string;
+ conversationId: string;
+ saveMessage: (message: Record<string, unknown>) => Promise<unknown>;
+ },
+): Promise<boolean> {
+ const finalized = resolveFinalizedCompactionTurn(partialRow, requestBody);
+ if (!finalized.write) {
+ return false;
+ }
+ const saved = await saveMessage({
+ messageId,
+ conversationId,
+ unfinished: false,
+ error: true,
+ ...(finalized.content != null && { content: finalized.content }),
+ });
+ if (saved == null) {
+ /** The same contract the surrounding failed-turn persistence holds: a
+ * falsy save is a failure to settle, not a settled row. */
+ throw new Error('Failed compaction turn could not be finalized');
+ }
+ return true;
+}
+
+/** What a failed compaction does with its already-persisted partial row. */
+export type FinalizedCompactionTurn =
+ /** Not the failed run's row, or one holding nothing but a completed
+ * checkpoint worth keeping exactly as it stands. */
+ | { write: false }
+ /** The parts already carry the failure (an error part, a failed summary);
+ * only the snapshot's live-run flags remain to settle. */
+ | { write: true; content?: undefined }
+ /** The parts need the terminal marking applied. */
+ | { write: true; content: TMessageContentParts[] };
+
+/**
+ * The disconnect save is marker-only because the run is still live when it
+ * fires, so when the run then fails that snapshot is the row that stays: a
+ * partial summary is marked failed beside its text, a snapshot with no
+ * summary or error part gets the typed failure, and a snapshot whose parts
+ * already carry the failure still settles its live-run flags. A completed
+ * checkpoint is preserved as content, but a snapshot still flagged
+ * `unfinished` settles its envelope even then, or the restored conversation
+ * keeps treating the terminal job as live; a row that was already settled is
+ * left alone. Rows of turns that were not compactions are never written.
+ */
+export function resolveFinalizedCompactionTurn(
+ partialRow: { content?: unknown; unfinished?: boolean } | null | undefined,
+ requestBody: { compact?: boolean } | null | undefined,
+): FinalizedCompactionTurn {
+ if (requestBody?.compact !== true) {
+ return { write: false };
+ }
+ /** A settled row belongs to the path that settled it, whatever its
+ * parts hold: a late failure must not rewrite or re-announce it. */
+ if (partialRow?.unfinished === false) {
+ return { write: false };
+ }
+ const content = Array.isArray(partialRow?.content)
+ ? (partialRow.content as TMessageContentParts[])
+ : [];
+ /** Every part is inspected: a row can hold an earlier round's terminal
+ * outcome beside a later unfinished summary, and that summary still needs
+ * its failure marked. */
+ let sawFailure = false;
+ let sawCheckpoint = false;
+ let unfinishedSummary = false;
+ for (const part of content) {
+ if (part?.type === ContentTypes.SUMMARY) {
+ if (part.failed === true) {
+ sawFailure = true;
+ } else if (isUsableSummaryPart(part)) {
+ sawCheckpoint = true;
+ } else {
+ unfinishedSummary = true;
+ }
+ } else if (part?.type === ContentTypes.ERROR) {
+ sawFailure = true;
+ }
+ }
+ if (unfinishedSummary) {
+ return { write: true, content: markAbortedCompactionContent(content, true) };
+ }
+ if (sawFailure) {
+ return { write: true };
+ }
+ if (sawCheckpoint) {
+ return partialRow?.unfinished === true ? { write: true } : { write: false };
+ }
+ return { write: true, content: markAbortedCompactionContent(content, true) };
+}
+
/**
* Stamps `initiatedBy: 'user'` on the part that carries a manual compaction's
* outcome, which is the turn's only record of having been one: the run emits no