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
🧷 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.jsindex 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.jsindex 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.jsindex 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.jsindex 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.jsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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