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: Persist a Generated Title Before the Turn Ends (#16137)
lia-by-librechat[bot]e4024052e014
diff --git a/api/server/controllers/agents/__tests__/request.partialDisconnect.spec.js b/api/server/controllers/agents/__tests__/request.partialDisconnect.spec.jsindex e4524db39a..437e74c45d 100644--- a/api/server/controllers/agents/__tests__/request.partialDisconnect.spec.js+++ b/api/server/controllers/agents/__tests__/request.partialDisconnect.spec.js@@ -63,6 +63,8 @@ jest.mock('@librechat/api', () => ({})),buildMessageFiles: jest.fn(() => []),resolveTitleTiming: jest.fn(() => 'immediate'),+ createConvoPersistenceSignal: jest.requireActual('@librechat/api').createConvoPersistenceSignal,+ recoverTurnMessageReference: jest.requireActual('@librechat/api').recoverTurnMessageReference,resolveConversationAnchor: jest.requireActual('@librechat/api').resolveConversationAnchor,resolveRunCodeWorkspaces: jest.requireActual('@librechat/api').resolveRunCodeWorkspaces,shouldPersistCodeWorkspaceInitializationError:diff --git a/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js b/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.jsindex eebe5f3518..058d3302dc 100644--- a/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js+++ b/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js@@ -70,6 +70,7 @@ const mockGetConvo = jest.fn();const mockGetMessages = jest.fn();const mockSaveMessage = jest.fn();const mockSaveConvo = jest.fn();+const mockAppendConvoMessageReference = jest.fn();const mockIsAgentTriggerPrincipalActive = jest.fn();const mockIsSubagentOwnerAdmissible = jest.fn();const mockAcquireEventChildGenerationLease = jest.fn();@@ -273,6 +274,8 @@ jest.mock('@librechat/api', () => ({getViolationInfo: (...args) => mockGetViolationInfo(...args),buildMessageFiles: jest.fn(() => []),resolveTitleTiming: jest.fn(() => 'immediate'),+ createConvoPersistenceSignal: jest.requireActual('@librechat/api').createConvoPersistenceSignal,+ recoverTurnMessageReference: jest.requireActual('@librechat/api').recoverTurnMessageReference,resolveConversationAnchor: jest.requireActual('@librechat/api').resolveConversationAnchor,resolveRunCodeWorkspaces: jest.requireActual('@librechat/api').resolveRunCodeWorkspaces,AttachmentStorageError: jest.requireActual('@librechat/api').AttachmentStorageError,@@ -374,6 +377,7 @@ jest.mock('~/cache', () => ({jest.mock('~/models', () => ({saveMessage: (...args) => mockSaveMessage(...args),saveConvo: (...args) => mockSaveConvo(...args),+ appendConvoMessageReference: (...args) => mockAppendConvoMessageReference(...args),getMessages: (...args) => mockGetMessages(...args),getConvo: (...args) => mockGetConvo(...args),getAgentEventActorSnapshot: (...args) => mockGetAgentEventActorSnapshot(...args),@@ -521,6 +525,7 @@ describe('ResumableAgentController resume metadata', () => {mockGenerationJobManager.steering.consumeRecovered.mockResolvedValue(true);mockSaveMessage.mockResolvedValue({});mockSaveConvo.mockResolvedValue({});+ mockAppendConvoMessageReference.mockResolvedValue({});mockDeleteAgentCheckpoint.mockResolvedValue(undefined);mockSettleAgentQueuedTurnExecutionAdmission.mockResolvedValue(true);mockVerifyAgentQueuedTurnExecutionAdmission.mockResolvedValue(true);@@ -5911,6 +5916,307 @@ describe('ResumableAgentController resume metadata', () => {expect(mockGenerationJobManager.releaseGeneration).not.toHaveBeenCalled();});+ describe('immediate title persistence gate', () => {+ const { Constants } = require('librechat-data-provider');++ /**+ * Starts a first turn that stays mid-run until the returned `release` is+ * called, so the gate an immediate title waits on can be observed while the+ * generation is still going. `userMessageWrite` is what the client hands back+ * through `getReqData`, exactly as BaseClient does once it has started the+ * user-message write.+ */+ const startHeldFirstTurn = async ({ userMessageWrite, clientOverrides, responseWrite }) => {+ let signalFinished;+ const finished = new Promise((resolve) => {+ signalFinished = resolve;+ });+ mockGenerationJobManager.finishTerminalJob.mockImplementation(async () => signalFinished());++ let release;+ const held = new Promise((resolve) => {+ release = resolve;+ });++ let convoReadyResolved = false;+ const addTitle = jest.fn(async (_req, options) => {+ void options?.convoReady?.then(() => {+ convoReadyResolved = true;+ });+ });++ let turnConversationId;+ const client = {+ options: {},+ savedMessageIds: new Set(),+ skipSaveUserMessage: false,+ ...clientOverrides,+ sendMessage: jest.fn(async (_text, options) => {+ turnConversationId = options.conversationId;+ const userMessage = {+ messageId: 'user-msg',+ parentMessageId: Constants.NO_PARENT,+ conversationId: options.conversationId,+ text: 'First message',+ };+ options.onStart(userMessage, 'response-msg');+ options.getReqData({ userMessagePromise: userMessageWrite(options.conversationId) });+ await held;+ return {+ messageId: 'response-msg',+ parentMessageId: 'user-msg',+ conversationId: options.conversationId,+ content: [{ type: 'text', text: 'Answer' }],+ databasePromise: Promise.resolve(+ responseWrite+ ? responseWrite(options.conversationId)+ : {+ message: { _id: 'response-row-id' },+ conversation: { conversationId: options.conversationId, title: null },+ },+ ),+ };+ }),+ };++ await AgentController(+ {+ user: { id: 'user-123' },+ body: {+ text: 'First message',+ messageId: 'user-msg',+ parentMessageId: Constants.NO_PARENT,+ conversationId: 'new',+ endpointOption: { endpoint: 'agents', modelOptions: { model: 'gpt-4.1' } },+ },+ config: {},+ },+ createResumableResponse(),+ jest.fn(),+ jest.fn().mockResolvedValue({ client }),+ addTitle,+ );+ await nextTick();+ await nextTick();++ return {+ addTitle,+ conversationId: () => turnConversationId,+ isConvoReadyResolved: () => convoReadyResolved,+ finish: async () => {+ release();+ await finished;+ await nextTick();+ await nextTick();+ },+ };+ };++ /** The bug this covers: gating the title's save on the end of the turn left+ * the row on "New Chat" for the whole run, so every reader without the live+ * stream — a reloaded tab, the sidebar on another device — read the+ * placeholder until the turn finished. */+ it('lets an immediate title persist as soon as the user message write creates the row', async () => {+ const turn = await startHeldFirstTurn({+ userMessageWrite: (conversationId) =>+ Promise.resolve({ message: { messageId: 'user-msg' }, conversation: { conversationId } }),+ });++ expect(turn.addTitle).toHaveBeenCalledTimes(1);+ expect(mockGenerationJobManager.finishTerminalJob).not.toHaveBeenCalled();+ expect(turn.isConvoReadyResolved()).toBe(true);++ await turn.finish();+ });++ it('keeps the title waiting until the turn ends when no conversation was persisted', async () => {+ const turn = await startHeldFirstTurn({+ userMessageWrite: () => Promise.resolve({}),+ });++ expect(turn.addTitle).toHaveBeenCalledTimes(1);+ expect(turn.isConvoReadyResolved()).toBe(false);++ await turn.finish();++ expect(turn.isConvoReadyResolved()).toBe(true);+ });++ /** The reference repair the title's save used to perform as a side effect of+ * rebuilding the whole `messages` array. The title now writes metadata only, so+ * the recovered user row has to carry its own reference. */+ describe('recovered user message reference', () => {+ /** Distinct rows, so one reference says nothing about the other. */+ beforeEach(() => {+ mockSaveMessage.mockImplementation(async (_ctx, message) => ({+ _id: message.messageId === 'response-msg' ? 'response-row-id' : 'user-row-id',+ }));+ });++ const appendedIdsFor = (conversationId) =>+ mockAppendConvoMessageReference.mock.calls+ .filter((call) => call[1] === conversationId)+ .map((call) => call[2]);++ it('appends the recovered reference when no write reported the conversation', async () => {+ const turn = await startHeldFirstTurn({+ /** BaseClient swallows a failed user-message save and resolves with `{}`. */+ userMessageWrite: () => Promise.resolve({}),+ });++ await turn.finish();++ expect(appendedIdsFor(turn.conversationId())).toEqual(['user-row-id']);+ expect(mockAppendConvoMessageReference).toHaveBeenCalledWith(+ 'user-123',+ turn.conversationId(),+ 'user-row-id',+ );+ });++ it('does not append again when the write already recorded the reference', async () => {+ const turn = await startHeldFirstTurn({+ userMessageWrite: (conversationId) =>+ Promise.resolve({+ message: { _id: 'user-row-id' },+ conversation: { conversationId },+ }),+ });++ await turn.finish();++ expect(appendedIdsFor(turn.conversationId())).toEqual([]);+ });++ /** `saveMessage` can resolve falsy without throwing, and the conversation is still+ * written and reported with nothing appended. The row existing is not evidence+ * that this turn is referenced by it. */+ it('appends when the write reported the row but appended no message', async () => {+ const turn = await startHeldFirstTurn({+ userMessageWrite: (conversationId) =>+ Promise.resolve({ message: undefined, conversation: { conversationId } }),+ });++ await turn.finish();++ expect(appendedIdsFor(turn.conversationId())).toEqual(['user-row-id']);+ });++ /** The response row has the same exposure: its write can report the conversation+ * while appending nothing, and its terminal retry is also a bare `saveMessage`. */+ it('appends the recovered response reference when its write appended nothing', async () => {+ const turn = await startHeldFirstTurn({+ userMessageWrite: (conversationId) =>+ Promise.resolve({+ message: { _id: 'user-row-id' },+ conversation: { conversationId },+ }),+ /** The response write reports the row without appending its id. */+ responseWrite: (conversationId) => ({+ conversation: { conversationId, title: null },+ }),+ });++ await turn.finish();++ expect(appendedIdsFor(turn.conversationId())).toEqual(['response-row-id']);+ });++ /** A first turn that pauses for approval never reaches the terminal, so its rows+ * cannot wait for one. The paused response is saved bare, and the title write that+ * used to rebuild the array in passing no longer does. */+ describe('a first turn paused for approval', () => {+ const runPausedFirstTurn = async ({ clientOverrides } = {}) => {+ mockGenerationJobManager.approvals.ownsPausePersistence.mockResolvedValue(true);+ const client = {+ options: {},+ savedMessageIds: new Set(),+ skipSaveUserMessage: false,+ pendingApproval: { actionId: 'action-paused-reference' },+ ...clientOverrides,+ sendMessage: jest.fn(async (_text, options) => {+ options.onStart(+ {+ messageId: 'user-msg',+ parentMessageId: Constants.NO_PARENT,+ conversationId: options.conversationId,+ text: 'First message',+ },+ 'response-msg',+ );+ options.getReqData({+ userMessagePromise: Promise.resolve({+ message: { _id: 'user-row-id' },+ conversation: { conversationId: options.conversationId },+ }),+ });+ return { messageId: 'response-msg', conversationId: options.conversationId };+ }),+ };++ await AgentController(+ {+ user: { id: 'user-123' },+ body: {+ text: 'First message',+ messageId: 'user-msg',+ parentMessageId: Constants.NO_PARENT,+ conversationId: 'new',+ endpointOption: { endpoint: 'agents', modelOptions: { model: 'gpt-4.1' } },+ },+ config: {},+ },+ createResumableResponse(),+ jest.fn(),+ jest.fn().mockResolvedValue({ client }),+ jest.fn(async () => {}),+ );+ await nextTick();+ await nextTick();+ };++ it('appends the paused response reference', async () => {+ await runPausedFirstTurn();++ expect(mockAppendConvoMessageReference).toHaveBeenCalledTimes(1);+ expect(mockAppendConvoMessageReference).toHaveBeenCalledWith(+ 'user-123',+ expect.any(String),+ 'response-row-id',+ );+ });++ /** The BaseClient re-save reports its own conversation write, which the signal+ * never saw through `getReqData`, so it must not be appended twice. */+ it('does not append the user reference its re-save already recorded', async () => {+ await runPausedFirstTurn({+ clientOverrides: {+ getSaveOptions: () => ({}),+ saveMessageToDatabase: jest.fn().mockResolvedValue({+ message: { _id: 'user-row-id' },+ conversation: { conversationId: 'convo-paused' },+ }),+ },+ });++ const appended = mockAppendConvoMessageReference.mock.calls.map((call) => call[2]);+ expect(appended).toEqual(['response-row-id']);+ });+ });++ it('leaves the conversation alone for a turn that does not save one', async () => {+ const turn = await startHeldFirstTurn({+ userMessageWrite: () => Promise.resolve({ message: {} }),+ clientOverrides: { skipSaveConvo: true },+ });++ await turn.finish();++ expect(appendedIdsFor(turn.conversationId())).toEqual([]);+ });+ });+ });+describe('preempt-incomplete title gating', () => {const { Constants } = require('librechat-data-provider');const { resolveTitleTiming } = require('@librechat/api');diff --git a/api/server/controllers/agents/request.js b/api/server/controllers/agents/request.jsindex c1a4cfb389..3cfa9d71ae 100644--- a/api/server/controllers/agents/request.js+++ b/api/server/controllers/agents/request.js@@ -14,6 +14,8 @@ const {getReferencedQuotes,resolveTitleTiming,GenerationJobManager,+ createConvoPersistenceSignal,+ recoverTurnMessageReference,filterPersistableAbortContent,decrementPendingRequest,sanitizeMessageForTransmit,@@ -81,6 +83,7 @@ const {settleAgentEventActorSuspension,isAgentTriggerPrincipalActive,isSubagentOwnerAdmissible,+ appendConvoMessageReference,} = require('~/models');const {acquireEventChildGenerationLease,@@ -2088,6 +2091,12 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTitlet userMessage;let liveResponseMessageId = preallocatedResponseMessageId;+ /** What this turn's message writes reported about the conversation row: the+ * gate an immediate-mode title waits on, and whether the user-message write+ * ever recorded the row. Declared out here because that fact arrives through+ * `getReqData`, which the client calls from inside `sendMessage`. */+ const convoSignal = createConvoPersistenceSignal();+const getReqData = (data = {}) => {if (data.userMessage) {userMessage = data.userMessage;@@ -2095,6 +2104,11 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTitif (data.responseMessageId) {liveResponseMessageId = data.responseMessageId;}+ /** The user-message write upserts the conversation, so its result is the+ * earliest proof the title's row exists. Waiting for the turn to end+ * instead leaves the database on "New Chat" for the whole run, and every+ * reader without the live stream reads that. */+ convoSignal.observeMessageWrite(data.userMessagePromise);// conversationId is pre-generated, no need to update from callback};@@ -2179,15 +2193,27 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTitconst startGeneration = async () => {/** Immediate-mode title generation runs in parallel with the response, so* the conversation row may not exist when the title resolves. `convoReady`- * resolves once the response (and thus the conversation) has been saved,- * gating the title's `saveConvo`. Declared here so both the success tail- * and the catch block can settle it and gate `disposeClient` on the title. */+ * resolves once that row is known to exist — normally the user-message+ * write reporting it, and otherwise the success tail or the catch block,+ * which also gate `disposeClient` on the title. */let titleEventPromise = null;let acceptsTitleEvents = true;- let resolveConvoReady;- const convoReady = new Promise((resolve) => {- resolveConvoReady = resolve;- });+ const convoReady = convoSignal.ready;+ const resolveConvoReady = () => convoSignal.open();+ /** A row this turn restored with a bare `saveMessage`, which writes the message and+ * never tells the conversation about it. Every such retry hands its result here. */+ const recoverMessageReference = (savedMessage, context) =>+ recoverTurnMessageReference(+ { appendConvoMessageReference },+ {+ userId,+ conversationId,+ messageId: savedMessage?._id == null ? undefined : String(savedMessage._id),+ alreadyRecorded: convoSignal.recordedMessageReference(savedMessage?._id),+ managesConversation: !client?.skipSaveConvo,+ context,+ },+ );/** Dedicated controller so a user Stop (or a replaced stream) cancels the* in-flight title — kept separate from `job.abortController`, which* `completeJob` also aborts on *successful* completion and would otherwise@@ -2698,6 +2724,9 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTitif (!client.skipSaveConvo && !savedUserTurn.conversation) {throw new Error('Conversation could not be persisted before HITL pause');}+ /** This re-save reports its own conversation write, which the signal has+ * not seen: it does not run through `getReqData`. */+ convoSignal.observeMessageWrite(Promise.resolve(savedUserTurn));} else {// Custom clients used by integrations/tests may not inherit BaseClient.const savedUserMessage = await saveMessage(@@ -2721,6 +2750,11 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTitif (!savedUserMessage) {throw new Error('User message could not be persisted before HITL pause');}+ /** A custom client's bare save leaves the same gap as the retries below. */+ await recoverMessageReference(+ savedUserMessage,+ 'api/server/controllers/agents/request.js - recovered paused user reference',+ );}}if (!response?.messageId) {@@ -2752,6 +2786,13 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTitif (!savedResponseMessage) {throw new Error('Paused response could not be persisted as unfinished');}+ /** A paused turn may never be resumed, so this row's reference cannot wait for+ * a terminal that might not come. The save above is bare, and the title write+ * that used to rebuild the array in passing no longer does. */+ await recoverMessageReference(+ savedResponseMessage,+ 'api/server/controllers/agents/request.js - recovered paused response reference',+ );await commitRecoveredSteer();} catch (pausePersistenceError) {pausePersistenceFailed = true;@@ -2855,6 +2896,10 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTitconst databasePromise = response.databasePromise;delete response.databasePromise;+ /** Records which row this write appended, for the same reason the user+ * message's write is observed: the retry below cannot tell on its own+ * whether the conversation already references what it just re-saved. */+ convoSignal.observeMessageWrite(databasePromise);const { conversation: convoData = {} } = await databasePromise;const conversation = { ...convoData };conversation.title =@@ -2943,6 +2988,12 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTitif (!savedUserMessage) {throw new Error('User message could not be persisted before terminal publication');}+ /** The retry above restored only the Message row, so the conversation may+ * still not reference this turn. */+ await recoverMessageReference(+ savedUserMessage,+ 'api/server/controllers/agents/request.js - recovered user message reference',+ );}// Only consume the parked recovery source after the explicit user-row// write above succeeds. `response.databasePromise` alone is insufficient:@@ -2984,6 +3035,12 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTit: 'Response message could not be persisted before terminal publication',);}+ /** As for the user message above: a bare `saveMessage` restores the row+ * without telling the conversation about it. */+ await recoverMessageReference(+ savedResponseMessage,+ 'api/server/controllers/agents/request.js - recovered response message reference',+ );logAgentMemorySnapshot('after_terminal_save', terminalMemoryContext);if (appliedEventActor != null) {const recorded = await recordAgentEventActorReconciliation({@@ -3008,16 +3065,18 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTit// If the user stopped this turn — or an empty preempt boundary truncated// it, which persists under the same honest `unfinished` contract — cancel- // the title BEFORE unblocking its persistence wait; otherwise resolving- // `convoReady` lets the title task resume and save before the later abort runs.+ // the title still being generated, which never reaches its save. A title+ // that finished generating is kept, and is normally already persisted: the+ // gate opened when the user-message write created its row.if (terminalWasAborted || preemptIncomplete) {titleAbortController.abort();} else {job.abortController.signal.removeEventListener('abort', abortTitleOnJobAbort);}- // The conversation row now exists and this stream is authoritative; allow- // any in-flight immediate title generation to persist (saveConvo uses noUpsert).+ // Backstop for a turn whose user-message write never reported a conversation+ // (a deferred or skipped write): the row exists by now, so let any title+ // waiting on it persist (saveConvo uses noUpsert).resolveConvoReady();acceptsTitleEvents = false;diff --git a/api/server/controllers/agents/resume.js b/api/server/controllers/agents/resume.jsindex 2cc9a112d7..4caeceb259 100644--- a/api/server/controllers/agents/resume.js+++ b/api/server/controllers/agents/resume.js@@ -48,6 +48,7 @@ const {assertCodeExecutionApprovalBinding,collectReachableAgents,restoreScheduledTokenContext,+ recoverTurnMessageReference,} = require('@librechat/api');const { disposeClient } = require('~/server/cleanup');const { decryptMetadata } = require('~/server/services/ActionService');@@ -77,6 +78,7 @@ const {reserveAgentEventActorDetachedAction,markAgentEventActorDetachedActionRunning,settleAgentEventActorDetachedAction,+ appendConvoMessageReference,} = require('~/models');const {acquireEventChildGenerationLease,@@ -267,6 +269,28 @@ async function resolveAccumulatedAttachments({ client, conversationId, responseMreturn mergeAttachments(existing, resolved);}+/**+ * A resumed turn persists its response with a bare `saveMessage`, which writes the row and+ * never tells the conversation about it. The title write used to rebuild that array in+ * passing; it no longer does, so each resumed save carries its own reference. Nothing else+ * in a resumed turn could have appended it, so there is no prior write to consult.+ */+const recoverResumedResponseReference = (+ { userId, conversationId, client, savedResponseMessage },+ context,+) =>+ recoverTurnMessageReference(+ { appendConvoMessageReference },+ {+ userId,+ conversationId,+ messageId: savedResponseMessage?._id == null ? undefined : String(savedResponseMessage._id),+ alreadyRecorded: false,+ managesConversation: !client?.skipSaveConvo,+ context,+ },+ );+/** Resolve the segment's content for an unfinished save (mirrors finalize's source). */async function resolveSegmentContent(client, streamId, expectedCreatedAt) {const liveContent = Array.isArray(client?.contentParts) ? client.contentParts : [];@@ -333,6 +357,10 @@ async function persistRePauseProgress({ req, client, job, streamId, conversationif (!savedResponseMessage) {throw new Error('Re-pause response progress could not be persisted');}+ await recoverResumedResponseReference(+ { userId, conversationId, client, savedResponseMessage },+ 'api/server/controllers/agents/resume.js - recovered re-paused response reference',+ );}/** Untenanted jobs (pre-multi-tenancy) remain accessible if the userId check passes. */@@ -529,6 +557,10 @@ async function finalizeResumedTurn({if (!savedResponseMessage) {throw new Error('Resumed response could not be persisted before terminal publication');}+ await recoverResumedResponseReference(+ { userId, conversationId, client, savedResponseMessage },+ 'api/server/controllers/agents/resume.js - recovered resumed response reference',+ );if (appliedEventActor != null) {const recorded = await recordAgentEventActorReconciliation({user: userId,diff --git a/api/server/services/Endpoints/agents/title.js b/api/server/services/Endpoints/agents/title.jsindex 896718b71e..cdb2a62c83 100644--- a/api/server/services/Endpoints/agents/title.js+++ b/api/server/services/Endpoints/agents/title.js@@ -169,7 +169,17 @@ const addTitle = async (conversationId: convoId,title,},- { context: 'api/server/services/Endpoints/agents/title.js', noUpsert: true },+ {+ context: 'api/server/services/Endpoints/agents/title.js',+ noUpsert: true,+ /** Metadata-only: write the title and nothing else. Without this, `saveConvo`+ * reads every message id and `$set`s the whole `messages` array, and an+ * immediate-mode title saves while the turn is still running — so a response+ * appending its own id between that read and that write would be erased from+ * the array for good. An empty append is the option's no-message path: it+ * skips both the read and the rewrite. */+ appendMessageIds: [],+ },);} catch (error) {logger.error('Error generating title:', error);diff --git a/api/server/services/Endpoints/agents/title.test.js b/api/server/services/Endpoints/agents/title.test.jsindex a5711c6ed4..f666771b44 100644--- a/api/server/services/Endpoints/agents/title.test.js+++ b/api/server/services/Endpoints/agents/title.test.js@@ -340,4 +340,26 @@ describe('agents addTitle', () => {);expect(mockCache.delete).not.toHaveBeenCalled();});++ /** An immediate-mode title saves while the turn is still running, so its write can+ * overlap the response's. Rebuilding `messages` from a pre-response snapshot would+ * erase the response's own appended id for good, so the title asks for the+ * metadata-only path: an empty append writes the title and touches nothing else. */+ it('saves the title without rewriting the conversation message array', async () => {+ const client = makeClient('Metadata Only');++ await addTitle(makeReq(), {+ text: 'hello',+ client,+ conversationId: 'cid-metadata',+ immediate: true,+ convoReady: Promise.resolve(),+ });++ expect(mockSaveConvo).toHaveBeenCalledWith(+ expect.anything(),+ expect.objectContaining({ conversationId: 'cid-metadata', title: 'Metadata Only' }),+ expect.objectContaining({ noUpsert: true, appendMessageIds: [] }),+ );+ });});diff --git a/packages/api/src/agents/convoPersistence.spec.ts b/packages/api/src/agents/convoPersistence.spec.tsnew file mode 100644index 0000000000..2a13c639fc--- /dev/null+++ b/packages/api/src/agents/convoPersistence.spec.ts@@ -0,0 +1,198 @@+import { createConvoPersistenceSignal } from './convoPersistence';++/** Resolves to true only if the gate is already open at this microtask depth. */+const isOpen = async (ready: Promise<void>): Promise<boolean> => {+ const sentinel = Symbol('shut');+ const result = await Promise.race([+ ready.then(() => 'open' as const),+ Promise.resolve().then(() => Promise.resolve().then(() => sentinel)),+ ]);+ return result === 'open';+};++const settled = () => new Promise((resolve) => setImmediate(resolve));++describe('createConvoPersistenceSignal', () => {+ it('starts shut, with no reference recorded', async () => {+ const signal = createConvoPersistenceSignal();++ await expect(isOpen(signal.ready)).resolves.toBe(false);+ expect(signal.recordedMessageReference('message-row')).toBe(false);+ });++ /** Each of a turn's rows is asked about separately, so one row's append says+ * nothing about another's. */+ it('records only the row that was appended', async () => {+ const signal = createConvoPersistenceSignal();++ signal.observeMessageWrite(+ Promise.resolve({+ message: { _id: 'user-row' },+ conversation: { conversationId: 'convo-1' },+ }),+ );+ await settled();++ expect(signal.recordedMessageReference('user-row')).toBe(true);+ expect(signal.recordedMessageReference('response-row')).toBe(false);+ });++ it('compares ids by value, so a re-read of the same row matches', async () => {+ const signal = createConvoPersistenceSignal();+ const id = { toString: () => 'row-abc' };++ signal.observeMessageWrite(+ Promise.resolve({ message: { _id: id }, conversation: { conversationId: 'convo-1' } }),+ );+ await settled();++ expect(signal.recordedMessageReference({ toString: () => 'row-abc' })).toBe(true);+ });++ it('records nothing for a missing id', async () => {+ const signal = createConvoPersistenceSignal();++ signal.observeMessageWrite(+ Promise.resolve({+ message: { _id: 'user-row' },+ conversation: { conversationId: 'convo-1' },+ }),+ );+ await settled();++ expect(signal.recordedMessageReference(undefined)).toBe(false);+ expect(signal.recordedMessageReference(null)).toBe(false);+ });++ it('opens and records the reference when a write saved both', async () => {+ const signal = createConvoPersistenceSignal();++ signal.observeMessageWrite(+ Promise.resolve({+ message: { _id: 'message-row' },+ conversation: { conversationId: 'convo-1' },+ }),+ );++ await expect(signal.ready).resolves.toBeUndefined();+ expect(signal.recordedMessageReference('message-row')).toBe(true);+ });++ /** `saveMessage` can resolve falsy without throwing, and `saveTurnConversation` then+ * appends nothing while still writing and reporting the row. The title may save+ * against that row; the reference still has to be repaired. */+ it.each([+ ['resolved no message', { conversation: { conversationId: 'convo-1' } }],+ [+ 'resolved a falsy message',+ { message: undefined, conversation: { conversationId: 'convo-1' } },+ ],+ [+ 'resolved a message without an id',+ { message: {}, conversation: { conversationId: 'convo-1' } },+ ],+ ])('opens the gate but records no reference when the write %s', async (_label, result) => {+ const signal = createConvoPersistenceSignal();++ signal.observeMessageWrite(Promise.resolve(result));++ await expect(signal.ready).resolves.toBeUndefined();+ expect(signal.recordedMessageReference('message-row')).toBe(false);+ });++ it.each([+ ['persisted no conversation', () => Promise.resolve({ message: { _id: 'message-row' } })],+ ['failed', () => Promise.reject(new Error('write failed'))],+ ['reported a null conversation', () => Promise.resolve({ conversation: null })],+ [+ 'reported an empty conversationId',+ () => Promise.resolve({ conversation: { conversationId: '' } }),+ ],+ ])('stays shut and reports nothing when the write %s', async (_label, makeWrite) => {+ const signal = createConvoPersistenceSignal();++ signal.observeMessageWrite(makeWrite());+ await settled();++ await expect(isOpen(signal.ready)).resolves.toBe(false);+ expect(signal.recordedMessageReference('message-row')).toBe(false);+ });++ it('stays shut while the write is still pending', async () => {+ const signal = createConvoPersistenceSignal();+ let settle: (value: unknown) => void = () => {};+ signal.observeMessageWrite(+ new Promise((resolve) => {+ settle = resolve;+ }),+ );++ await expect(isOpen(signal.ready)).resolves.toBe(false);+ expect(signal.recordedMessageReference('message-row')).toBe(false);++ settle({ message: { _id: 'message-row' }, conversation: { conversationId: 'convo-1' } });++ await expect(signal.ready).resolves.toBeUndefined();+ expect(signal.recordedMessageReference('message-row')).toBe(true);+ });++ it('ignores a value that is not a promise', async () => {+ const signal = createConvoPersistenceSignal();++ signal.observeMessageWrite(undefined);+ signal.observeMessageWrite({+ message: { _id: 'message-row' },+ conversation: { conversationId: 'convo-1' },+ });+ await settled();++ await expect(isOpen(signal.ready)).resolves.toBe(false);+ expect(signal.recordedMessageReference('message-row')).toBe(false);+ });++ /** The terminal backstop opens the gate for a title, but it is not evidence that+ * any write recorded the row — the reference repair must still run. */+ it('does not record a reference just because open() was called', async () => {+ const signal = createConvoPersistenceSignal();++ signal.open();+ signal.open();+ signal.observeMessageWrite(Promise.resolve({ message: { _id: 'message-row' } }));+ await settled();++ await expect(signal.ready).resolves.toBeUndefined();+ expect(signal.recordedMessageReference('message-row')).toBe(false);+ });++ it('records the reference when a later write succeeds after an earlier one did not', async () => {+ const signal = createConvoPersistenceSignal();++ signal.observeMessageWrite(Promise.resolve({ conversation: { conversationId: 'convo-1' } }));+ signal.observeMessageWrite(+ Promise.resolve({+ message: { _id: 'message-row' },+ conversation: { conversationId: 'convo-1' },+ }),+ );+ await settled();++ expect(signal.recordedMessageReference('message-row')).toBe(true);+ });++ /** A later write that appended nothing must not unset what an earlier one recorded. */+ it('keeps a recorded reference when a later write appends nothing', async () => {+ const signal = createConvoPersistenceSignal();++ signal.observeMessageWrite(+ Promise.resolve({+ message: { _id: 'message-row' },+ conversation: { conversationId: 'convo-1' },+ }),+ );+ await settled();+ signal.observeMessageWrite(Promise.resolve({ conversation: { conversationId: 'convo-1' } }));+ await settled();++ expect(signal.recordedMessageReference('message-row')).toBe(true);+ });+});diff --git a/packages/api/src/agents/convoPersistence.ts b/packages/api/src/agents/convoPersistence.tsnew file mode 100644index 0000000000..64ba703ca0--- /dev/null+++ b/packages/api/src/agents/convoPersistence.ts@@ -0,0 +1,109 @@+/**+ * What a turn's message writes reported about the conversation row.+ *+ * `saveMessageToDatabase` writes a message and upserts its conversation, and+ * resolves with both. That result is the only in-band evidence of either, and two+ * things in a resumable turn depend on it:+ *+ * - An immediate-mode title is generated in parallel with the response, so it can+ * resolve before the row exists, and its `saveConvo` runs with `noUpsert` — a+ * silent no-op against a missing row. It waits on `ready`, which opens as soon+ * as a write reports the row. Waiting for the end of the turn instead leaves the+ * database on `New Chat` for the whole run, and every reader that does not hold+ * the live stream reads that.+ * - A message write that failed is swallowed by BaseClient, or resolves falsy on a+ * duplicate key it cannot re-read, and the turn retries it later as a bare+ * message row — which does not append its id to the conversation. The caller asks+ * `recordedMessageReference(id)` whether that exact row was ever appended, and+ * repairs the reference when it was not.+ *+ * Those are different facts about one write. `saveMessageToDatabase` hands its saved+ * id to `saveTurnConversation` as `savedMessageId`, which appends only when the id+ * is present — so a write that saved no message still writes the conversation and+ * still reports it, having appended nothing. The row exists, so the title may save;+ * the reference does not, so the repair must run. Tracking the ids rather than a+ * single flag is what lets each of a turn's rows be asked about separately.+ */+export interface ConvoPersistenceSignal {+ /** Awaited by title persistence; resolves once the conversation row exists. */+ readonly ready: Promise<void>;+ /** Opens `ready` unconditionally. The caller knows the row is written. */+ open(): void;+ /**+ * Records what a message write reported. A write that rejects, never settles, or+ * persisted no conversation leaves `ready` shut for the caller's own `open()` to+ * settle: a title written against a row that does not exist is a title silently+ * dropped.+ */+ observeMessageWrite(write: unknown): void;+ /**+ * Whether an observed write appended this exact message row to the conversation.+ * False also means "not yet", so read it only once the writes it observes have+ * settled, and false for a missing id, which nothing could have appended.+ */+ recordedMessageReference(messageId: unknown): boolean;+}++/** What a message write resolves with once it has saved the row and the conversation. */+type MessageWriteResult = {+ message?: { _id?: unknown } | null;+ conversation?: { conversationId?: string | null } | null;+};++const asResult = (value: unknown): MessageWriteResult | undefined =>+ value != null && typeof value === 'object' ? (value as MessageWriteResult) : undefined;++const persistedConversationId = (result?: MessageWriteResult): string | undefined => {+ const conversation = result?.conversation;+ if (conversation == null || typeof conversation !== 'object') {+ return undefined;+ }+ const { conversationId } = conversation;+ return typeof conversationId === 'string' && conversationId !== '' ? conversationId : undefined;+};++/** The id `saveTurnConversation` would have appended. Absent means it appended nothing. */+const appendedMessageId = (result?: MessageWriteResult): unknown => {+ const message = result?.message;+ if (message == null || typeof message !== 'object') {+ return undefined;+ }+ return message._id ?? undefined;+};++export function createConvoPersistenceSignal(): ConvoPersistenceSignal {+ let openGate: () => void = () => {};+ const ready = new Promise<void>((resolve) => {+ openGate = resolve;+ });+ /** Stringified so an id object and its re-read equivalent compare equal. */+ const appended = new Set<string>();++ return {+ ready,+ open: () => openGate(),+ recordedMessageReference: (messageId: unknown) =>+ messageId != null && appended.has(String(messageId)),+ observeMessageWrite: (write: unknown) => {+ if (write == null || typeof (write as PromiseLike<unknown>).then !== 'function') {+ return;+ }+ void Promise.resolve(write as PromiseLike<unknown>).then(+ (value) => {+ const result = asResult(value);+ if (persistedConversationId(result) == null) {+ return;+ }+ const messageId = appendedMessageId(result);+ if (messageId != null) {+ appended.add(String(messageId));+ }+ openGate();+ },+ /** The write's own owner logs and recovers it; the signal only learns that+ * nothing was persisted. */+ () => {},+ );+ },+ };+}diff --git a/packages/api/src/agents/index.ts b/packages/api/src/agents/index.tsindex cfca8b0cfc..7c0533e006 100644--- a/packages/api/src/agents/index.ts+++ b/packages/api/src/agents/index.ts@@ -65,6 +65,7 @@ export * from './run';export * from './fading';export * from './publication';export * from './runtime';+export * from './convoPersistence';export * from './testHook';export * from './tools';export * from './validation';diff --git a/packages/api/src/conversations/save.spec.ts b/packages/api/src/conversations/save.spec.tsindex e39a71d2e7..6edc25832e 100644--- a/packages/api/src/conversations/save.spec.ts+++ b/packages/api/src/conversations/save.spec.ts@@ -9,9 +9,10 @@ import {saveTurnConversation,seedTurnConversation,getConversationWriteContext,+ recoverTurnMessageReference,} from './save';-type Store = Pick<ConversationMethods, 'getConvo' | 'saveConvo'> &+type Store = Pick<ConversationMethods, 'getConvo' | 'saveConvo' | 'appendConvoMessageReference'> &Pick<MessageMethods, 'saveMessage'>;let mongoServer: MongoMemoryServer;@@ -47,6 +48,7 @@ beforeAll(async () => {store = {getConvo: methods.getConvo,saveConvo: methods.saveConvo,+ appendConvoMessageReference: methods.appendConvoMessageReference,saveMessage: methods.saveMessage,};});@@ -180,6 +182,176 @@ describe('seedTurnConversation', () => {});});+describe('recoverTurnMessageReference', () => {+ /** The whole failure path, in order: the user-message write fails and is swallowed, the+ * response's write creates the row referencing only itself, the terminal retries the user+ * row with a bare `saveMessage` that never touches the conversation, and the recovery+ * carries the reference the turn would otherwise have lost for good. */+ const runFailedUserWriteTurn = async () => {+ const userId = new mongoose.Types.ObjectId().toString();+ const conversationId = randomUUID();+ const req = createRequest(userId);+ const ctx = getConversationWriteContext(req);++ const responseRow = await store.saveMessage(ctx, {+ messageId: randomUUID(),+ conversationId,+ text: 'Answer',+ isCreatedByUser: false,+ });+ await saveTurnConversation(store, {+ ...seedFields(req, conversationId),+ ctx,+ savedMessageId: responseRow?._id,+ });++ /** The retry: the row is restored, the conversation is not told. */+ const recoveredUserRow = await store.saveMessage(ctx, {+ messageId: randomUUID(),+ conversationId,+ text: 'First message',+ isCreatedByUser: true,+ });++ return { userId, conversationId, ctx, responseRow, recoveredUserRow };+ };++ it('appends a recovered reference the conversation never received', async () => {+ const turn = await runFailedUserWriteTurn();+ const before = await store.getConvo(turn.userId, turn.conversationId);+ expect(before?.messages?.map(String)).toEqual([String(turn.responseRow?._id)]);++ const wrote = await recoverTurnMessageReference(store, {+ userId: turn.userId,+ conversationId: turn.conversationId,+ messageId: String(turn.recoveredUserRow?._id),+ alreadyRecorded: false,+ managesConversation: true,+ context: 'save.spec recovery',+ });++ expect(wrote).toBe(true);+ const row = await store.getConvo(turn.userId, turn.conversationId);+ expect(row?.messages?.map(String)).toEqual(+ [turn.responseRow?._id, turn.recoveredUserRow?._id].map(String),+ );+ });++ it('is idempotent, so a repeated recovery cannot duplicate the reference', async () => {+ const turn = await runFailedUserWriteTurn();+ const recovery = {+ userId: turn.userId,+ conversationId: turn.conversationId,+ messageId: String(turn.recoveredUserRow?._id),+ alreadyRecorded: false,+ managesConversation: true,+ context: 'save.spec recovery',+ };++ await recoverTurnMessageReference(store, recovery);+ await recoverTurnMessageReference(store, recovery);++ const row = await store.getConvo(turn.userId, turn.conversationId);+ expect(row?.messages?.map(String)).toEqual(+ [turn.responseRow?._id, turn.recoveredUserRow?._id].map(String),+ );+ });++ /** A repair is bookkeeping beside an already-durable row, so it reorders nothing. */+ it('does not count as activity, leaving the sidebar order alone', async () => {+ const turn = await runFailedUserWriteTurn();+ const before = await store.getConvo(turn.userId, turn.conversationId);++ await recoverTurnMessageReference(store, {+ userId: turn.userId,+ conversationId: turn.conversationId,+ messageId: String(turn.recoveredUserRow?._id),+ alreadyRecorded: false,+ managesConversation: true,+ context: 'save.spec recovery',+ });++ const after = await store.getConvo(turn.userId, turn.conversationId);+ expect(after?.updatedAt?.getTime()).toBe(before?.updatedAt?.getTime());+ });++ it.each([+ ['the reference is already recorded', { alreadyRecorded: true, managesConversation: true }],+ ['the turn does not own the row', { alreadyRecorded: false, managesConversation: false }],+ ])('writes nothing when %s', async (_label, overrides) => {+ const turn = await runFailedUserWriteTurn();+ const append = jest.spyOn(store, 'appendConvoMessageReference');++ const wrote = await recoverTurnMessageReference(store, {+ userId: turn.userId,+ conversationId: turn.conversationId,+ messageId: String(turn.recoveredUserRow?._id),+ context: 'save.spec recovery',+ ...overrides,+ });++ expect(wrote).toBe(false);+ expect(append).not.toHaveBeenCalled();+ });++ it.each([+ ['there is no recovered row to reference', undefined],+ ['the recovered id is empty', ''],+ ])('writes nothing when %s', async (_label, messageId) => {+ const turn = await runFailedUserWriteTurn();+ const append = jest.spyOn(store, 'appendConvoMessageReference');++ const wrote = await recoverTurnMessageReference(store, {+ userId: turn.userId,+ conversationId: turn.conversationId,+ messageId,+ alreadyRecorded: false,+ managesConversation: true,+ context: 'save.spec recovery',+ });++ expect(wrote).toBe(false);+ expect(append).not.toHaveBeenCalled();+ });++ it('never creates a row of its own', async () => {+ const userId = new mongoose.Types.ObjectId().toString();+ const conversationId = randomUUID();++ const wrote = await recoverTurnMessageReference(store, {+ userId,+ conversationId,+ messageId: new mongoose.Types.ObjectId().toString(),+ alreadyRecorded: false,+ managesConversation: true,+ context: 'save.spec recovery',+ });++ expect(wrote).toBe(true);+ expect(await store.getConvo(userId, conversationId)).toBeNull();+ });++ /** The repair must never take a turn down with it: the message it points at is already+ * durable, and the reference is the only thing at stake. */+ it('reports failure instead of throwing when the append fails', async () => {+ const turn = await runFailedUserWriteTurn();+ jest+ .spyOn(store, 'appendConvoMessageReference')+ .mockRejectedValue(new Error('Error appending the message reference'));++ await expect(+ recoverTurnMessageReference(store, {+ userId: turn.userId,+ conversationId: turn.conversationId,+ messageId: String(turn.recoveredUserRow?._id),+ alreadyRecorded: false,+ managesConversation: true,+ context: 'save.spec recovery',+ }),+ ).resolves.toBe(false);+ });+});+describe('runAfterSeed', () => {it('holds the write while the seed is in flight', async () => {let finishSeed: () => void = () => undefined;diff --git a/packages/api/src/conversations/save.ts b/packages/api/src/conversations/save.tsindex ab355fbed0..1d85a2e118 100644--- a/packages/api/src/conversations/save.ts+++ b/packages/api/src/conversations/save.ts@@ -177,6 +177,63 @@ export async function saveTurnConversation(return writeConversation(deps, write, existing, appendMessageIds);}+/**+ * Adds one message's id to its conversation. Declared structurally, and by plain id, so this+ * operation's callers never name the storage engine's own id type.+ */+export interface MessageReferenceAppender {+ appendConvoMessageReference(+ user: string,+ conversationId: string,+ messageId: string,+ ): Promise<unknown>;+}++/** What a turn knows about a message row whose conversation reference may be missing. */+export interface TurnMessageReferenceRecovery {+ userId: string;+ conversationId: string;+ /** The row a retry restored. Absent means there is nothing to reference. */+ messageId?: string;+ /** Whether the write that should have appended this reference already did. */+ alreadyRecorded: boolean;+ /** False for a turn whose conversation row another run owns, which holds no messages. */+ managesConversation: boolean;+ /** Names the caller in the repair log. */+ context: string;+}++/**+ * Appends a recovered message's reference when nothing else recorded it.+ *+ * A message write can fail and be swallowed, or resolve falsy on a duplicate key it cannot+ * re-read; either way its conversation is written with nothing appended. The turn then retries+ * the row with a bare `saveMessage`, which never touches the conversation, so that row would+ * stay absent from `messages` for good — every other write appends only its own id.+ *+ * Skipped whenever the reference is already recorded, which is every ordinary turn, so the happy+ * path costs no write. Returns whether it wrote.+ */+export async function recoverTurnMessageReference(+ deps: MessageReferenceAppender,+ recovery: TurnMessageReferenceRecovery,+): Promise<boolean> {+ const { userId, conversationId, messageId, alreadyRecorded, managesConversation } = recovery;+ if (alreadyRecorded || !managesConversation || messageId == null || messageId === '') {+ return false;+ }+ try {+ await deps.appendConvoMessageReference(userId, conversationId, messageId);+ return true;+ } catch (error) {+ /** Bookkeeping beside the row it points at: the message itself is already durable, and+ * failing a turn over its reference would trade a wrong field for a lost response. The+ * next write that appends to this conversation carries it. */+ logger.error(`[recoverTurnMessageReference] ${recovery.context}`, error);+ return false;+ }+}+/*** Creates a new conversation's row ahead of a deferred first message, without the message, so* the conversation lists return a running chat. An existing row is left to the message save.diff --git a/packages/data-schemas/src/methods/conversation.spec.ts b/packages/data-schemas/src/methods/conversation.spec.tsindex 92ff017399..6c1b2eea3d 100644--- a/packages/data-schemas/src/methods/conversation.spec.ts+++ b/packages/data-schemas/src/methods/conversation.spec.ts@@ -1427,6 +1427,139 @@ describe('Conversation Operations', () => {const stored = await Conversation.findOne({ conversationId }).lean();expect(stored?.messages?.map(String)).toEqual(rebuilt.map(String));});++ /** An empty append is how a metadata-only write asks for the title (or any other+ * field) to land without the array being rebuilt underneath it. */+ it('leaves the array untouched when the append is empty', async () => {+ const existing = new mongoose.Types.ObjectId();+ await saveConvo(ctx, { conversationId }, { appendMessageIds: [existing] });+ getMessages.mockClear();++ await saveConvo(ctx, { conversationId, title: 'metadata only' }, { appendMessageIds: [] });++ expect(getMessages).not.toHaveBeenCalled();+ const stored = await Conversation.findOne({ conversationId }).lean();+ expect(stored?.title).toBe('metadata only');+ expect(stored?.messages?.map(String)).toEqual([String(existing)]);+ });++ /** The concurrency an immediate-mode title introduced: it saves while the turn is+ * still running, so its write and the response's own append overlap. A title that+ * rebuilt the array from a snapshot taken before the response existed erased the+ * response's id permanently — nothing later re-adds it. Asking for no messages at+ * all is what makes the interleaving irrelevant. */+ it('keeps a concurrently appended id when a metadata-only write overlaps it', async () => {+ const userMessage = new mongoose.Types.ObjectId();+ await saveConvo(ctx, { conversationId }, { appendMessageIds: [userMessage] });+ /** What a rebuilding write would have read: the turn before the response. The+ * outer `beforeEach` restores the default, so this cannot leak. */+ getMessages.mockResolvedValue([{ _id: userMessage }]);+ getMessages.mockClear();++ const responseMessage = new mongoose.Types.ObjectId();+ await Promise.all([+ saveConvo(ctx, { conversationId, title: 'generated mid-turn' }, { appendMessageIds: [] }),+ saveConvo(ctx, { conversationId }, { appendMessageIds: [responseMessage] }),+ ]);++ const stored = await Conversation.findOne({ conversationId }).lean();+ expect(stored?.title).toBe('generated mid-turn');+ expect(stored?.messages?.map(String)).toEqual([userMessage, responseMessage].map(String));+ /** No snapshot was taken, so there was no window to lose the append in. */+ expect(getMessages).not.toHaveBeenCalled();+ });+ });++ describe('appendConvoMessageReference', () => {+ const ctx = { userId: 'append-ref-user' };+ const conversationId = 'append-ref-conversation';++ const appendConvoMessageReference = (+ ...args: Parameters<ConversationMethods['appendConvoMessageReference']>+ ) => methods.appendConvoMessageReference(...args);++ beforeEach(async () => {+ await Conversation.deleteMany({});+ getMessages.mockClear();+ });++ it('appends the id without reading or rewriting the message array', async () => {+ const existing = new mongoose.Types.ObjectId();+ await saveConvo(ctx, { conversationId, title: 'seeded' }, { appendMessageIds: [existing] });+ getMessages.mockClear();++ const recovered = new mongoose.Types.ObjectId();+ const row = await appendConvoMessageReference(ctx.userId, conversationId, String(recovered));++ expect(row?.messages?.map(String)).toEqual([existing, recovered].map(String));+ expect(getMessages).not.toHaveBeenCalled();+ });++ it('does not duplicate an id the conversation already references', async () => {+ const id = new mongoose.Types.ObjectId();+ await saveConvo(ctx, { conversationId }, { appendMessageIds: [id] });++ await appendConvoMessageReference(ctx.userId, conversationId, String(id));+ await appendConvoMessageReference(ctx.userId, conversationId, String(id));++ const stored = await Conversation.findOne({ conversationId }).lean();+ expect(stored?.messages?.map(String)).toEqual([String(id)]);+ });++ /** Repairing a reference is not activity: the sidebar orders by `updatedAt`, and+ * hoisting an untouched chat to Today would be a visible lie. */+ it('leaves updatedAt alone', async () => {+ await saveConvo(ctx, { conversationId }, { appendMessageIds: [] });+ const before = await Conversation.findOne({ conversationId }).lean();++ await appendConvoMessageReference(+ ctx.userId,+ conversationId,+ String(new mongoose.Types.ObjectId()),+ );++ const after = await Conversation.findOne({ conversationId }).lean();+ expect(after?.updatedAt?.getTime()).toBe(before?.updatedAt?.getTime());+ });++ it('never inserts a conversation that does not exist', async () => {+ const row = await appendConvoMessageReference(+ ctx.userId,+ 'no-such-conversation',+ String(new mongoose.Types.ObjectId()),+ );++ expect(row).toBeNull();+ expect(+ await Conversation.findOne({ conversationId: 'no-such-conversation' }).lean(),+ ).toBeNull();+ });++ /** The repair runs on a turn's own behalf, so it must never reach another owner's row. */+ it("cannot touch another owner's conversation", async () => {+ const owner = new mongoose.Types.ObjectId();+ await saveConvo(ctx, { conversationId }, { appendMessageIds: [owner] });++ const row = await appendConvoMessageReference(+ 'someone-else',+ conversationId,+ String(new mongoose.Types.ObjectId()),+ );++ expect(row).toBeNull();+ const stored = await Conversation.findOne({ conversationId }).lean();+ expect(stored?.messages?.map(String)).toEqual([String(owner)]);+ });++ it('ignores an id the store could never hold', async () => {+ await saveConvo(ctx, { conversationId }, { appendMessageIds: [] });++ const row = await appendConvoMessageReference(ctx.userId, conversationId, 'not-an-id');++ expect(row).toBeNull();+ const stored = await Conversation.findOne({ conversationId }).lean();+ expect(stored?.messages ?? []).toEqual([]);+ });});describe('isTemporary conversation handling', () => {diff --git a/packages/data-schemas/src/methods/conversation.ts b/packages/data-schemas/src/methods/conversation.tsindex 3d44b0e641..f81e52fb11 100644--- a/packages/data-schemas/src/methods/conversation.ts+++ b/packages/data-schemas/src/methods/conversation.ts@@ -285,6 +285,11 @@ export interface ConversationMethods {conversationId: string,pinned: boolean,): Promise<IConversation | null>;+ appendConvoMessageReference(+ user: string,+ conversationId: string,+ messageId: string,+ ): Promise<IConversation | null>;replaceConvoCodeEnvironmentDecision(params: {user: string;conversationId: string;@@ -2582,6 +2587,42 @@ export function createConversationMethods(}}+ /**+ * Adds one message's id to a conversation's message list, and nothing else.+ *+ * A message write that failed, or that resolved falsy on a duplicate key it could not+ * re-read, leaves its row out of `messages`, and the bare `saveMessage` retries that+ * restore the row never add it. Going direct keeps the repair to what it is: no+ * `getMessages` round trip, no rewrite of the whole array, and no `$set` of fields the+ * caller never meant to touch. `timestamps: false` because repairing a reference is not+ * activity and must not reorder the sidebar.+ *+ * Takes the id as a string so callers stay free of the storage engine's own id type; the+ * cast to it happens here. Returns null when no conversation matched, so a repair can+ * never insert one.+ */+ async function appendConvoMessageReference(+ user: string,+ conversationId: string,+ messageId: string,+ ) {+ if (!isValidObjectIdString(messageId)) {+ logger.warn('[appendConvoMessageReference] Ignoring an unusable message id');+ return null;+ }+ try {+ const Conversation = mongoose.models.Conversation as Model<IConversation>;+ return await Conversation.findOneAndUpdate(+ { conversationId, user },+ { $addToSet: { messages: new mongoose.Types.ObjectId(messageId) } },+ { new: true, timestamps: false },+ ).lean<IConversation>();+ } catch (error) {+ logger.error('[appendConvoMessageReference] Error appending the message reference', error);+ throw new Error('Error appending the message reference');+ }+ }+/*** Compare-and-swap for an owner's explicit move of an attached code-environment decision.* The filter repeats the stored decision being replaced, so a writer that changed it first@@ -3454,6 +3495,7 @@ export function createConversationMethods(deleteNullOrEmptyConversations,saveConvo,setConvoPinned,+ appendConvoMessageReference,replaceConvoCodeEnvironmentDecision,bulkSaveConvos,getConvosByCursor,