Skip to content

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

✒️ fix: 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.js
index 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.js
index 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.js
index 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, addTit
let 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, addTit
if (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, addTit
const 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, addTit
if (!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, addTit
if (!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, addTit
if (!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, addTit
const 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, addTit
if (!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.js
index 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, responseM
return 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, conversation
if (!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.js
index 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.js
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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,