🔔 feat: Unseen Reply Indicators, Reply Notifications, and Mark as Unread (#15025)

* feat: add unseen reply indicators, reply notifications, and mark as unread

A reply that lands while the user is elsewhere now leaves a trace. The
conversation carries a durable reply stamp written with the assistant message
that backs it, the sidebar row shows an unread dot until that message is
actually rendered, and an optional tab badge, desktop notification and chime
announce arrivals in a tab that is away. Rows can also be marked unread by hand
from the row menu, in the archived view as well as the main list.

The stamp is written by a compare-and-swap so concurrent replies order on the
database rather than on the application hosts' clocks, and only once output that
a reader can actually see is persisted: a stopped turn with nothing to read, an
empty synchronized row, or a failed message write never lights a dot that cannot
be cleared. Read intent survives archives, metadata edits and preset applies,
and a later read always outranks a delayed unread.

* fix: gate reply alerts on config and announce only readable replies

Three review rounds kept finding the same two shapes, so both are answered once
rather than patched again.

The alert capabilities are now operator-configurable through
`interface.replyNotifications` in `librechat.yaml`: the tab badge, desktop
notifications and the chime each have a gate, and the away poll's page size is a
field rather than a constant, with defaults that reproduce the shipped behavior.
A capability the operator turns off reads as off whatever the device stored, and
its settings toggle is not offered.

Deciding whether a persisted turn may raise an indicator now lives in one place
in `packages/api`, with the Responses API controller, the abort route, the
Assistants thread sync and the client's override path all calling it instead of
carrying their own copy. That closes the last case where a reply nobody can read
lit a dot nothing could clear: a `/v1/responses` completion whose output held
only reasoning or tool calls persists an empty row, and stamping it left an
unread conversation that opening could not settle.

Also: the retention backfill no longer advances `updatedAt` past a reply stamp,
which an away tab reads as a metadata-only promotion and withholds the alert
for; arrival evidence is swept of conversations no cached list still holds, so a
long-lived tab stops growing with its lifetime number of replies; and generated
Lighthouse profile directories are ignored where the runner leaves them.

* test: open the sidebar by what the drawer paints, not by its test ids

The drawer became a mounted, sliding panel on canary, so the controls this
helper read no longer say what it assumed. `close-sidebar-button` answers from
the off-canvas copy before the expanded state commits, which returned the helper
with the conversation list still hidden behind the pane, and the panel's own
`new-chat-button` has a rail copy that a plain locator reaches first. Both
readings passed on the previous drawer, which unmounted when closed.

Settling on the close control's accessible name, and on the first candidate that
is actually painted, is what a reader perceives and survives either drawer. One
click is one toggle and the opener sits in the pane the drawer marks inert for
the whole of its travel, so each attempt is given that travel to itself rather
than reissued into it.

Also serves `interface.replyNotifications` in the operator-gate scenario with a
fresh body instead of the upstream response, since reusing its encoding headers
for a re-serialized payload leaves the client unable to read the config, which
looks exactly like an operator who configured nothing.

* fix: gate the assistant save on renderable output and stop overselling the poll limit

Two gaps this round's own work left behind.

`saveAssistantMessage` still decided to stamp from the message id alone, so an
Assistants run that persisted an empty row raised a dot that opening the
conversation could never clear. It now asks `isAnnounceableReply`, the same
predicate every other persistence path asks, which is the point of having moved
that decision into one place.

`pollLimit` advertised a range up to 1000 while `getConvosByCursor` clamps every
conversation read to a hundred-row page, so an operator who set 500 would have
been told it applied and silently served a hundred. The schema now stops at the
page the server will actually return; covering a deployment whose replies
outpace one page needs the server-side unseen query, not a wider page.

* test: let the mobile scenarios use the surface they are actually asserting on

Three scenarios opened the drawer on a page they only ever send a reply from.
On the mobile project that drawer sits over the composer and marks the pane
inert, so there was nothing left to type in and the run waited out its whole
budget. They ask for the composer now, which is what they were always about.

The two that read a row after leaving the list open it again first. A reply sent
from another tab closes this one's drawer, because `sidebarExpanded` is stored
per browser rather than per tab, and opening a chat closes it the way it does
for a reader. Both are what someone would do to look at the row, and neither
changes what is being asserted.

Mark as unread is dispatched rather than clicked, like the row controls around
it: the menu is portaled, and behind the drawer's scrim it inherits
`pointer-events: none` and goes click-dead.

* test: dispatch the row menu's unread item like the controls around it

The portaled menu sits under the mobile drawer's scrim, which intercepts the
pointer, so a real click retried until the budget ran out. The sibling scenarios
and the row's own controls already dispatch; these two were the last real
clicks.

* fix: hold reply alerts until the deployment answers, and read the resolved temporary state

The capability gate treated a startup config that had not loaded yet the same as
one that set nothing, so a device that stored "on" could badge, poll or notify in
the window before an operator's `false` arrived. Nothing is permitted now until
the config is in hand; only a loaded config that lacks the field reads as the
shipped default, which is the case a backend predating the setting produces.

The Responses API announcement read the temporary flag from the request body
alone, while the conversation save beside it resolves it from the stored
conversation first. A temporary chat restored or resolved on the server without
the flag in the body would have been announced through the unread indicators;
both completion branches now resolve it the same way the save does.

* fix: route the last reply stamps through the shared owner and hand back failed claims

Moving the announce decision into packages/api left three callers still deciding
for themselves. The agents controller re-stamped an unfinished turn whose
terminal persistence was skipped, and the resumed legacy turn stamped its
directly saved row, both from the message id alone, so a preempted or stopped
turn that persisted nothing readable lit a dot that could never be
acknowledged. Both ask isAnnounceableReply now. The non-agents abort path
carried an inline copy of the same predicate; it calls announceReply instead.
Error turns keep their direct stamp: the error card is what renders them.

A notification claim was written to shared storage before the notification
was constructed, so a constructor that throws left the reply claimed in every
tab with nothing ever shown. The claim is handed back when construction fails,
removed only while it still names that exact stamp.

* fix: judge the normal reply save by the shared predicate and hand back failed chimes

The regular BaseClient save still stamped any assistant reply that persisted,
readable or not, because the conversation write took a bare reply id. It takes
the persisted reply now and asks isAnnounceableReply before it stamps, which
leaves the error turns as the only direct stamps, and those are rendered by the
error card. saveTurnConversation is exercised against a real store in both
directions. announce.ts derives its write-context type locally so the two
modules do not import each other.

The chime claimed its replies before building the tones, so an output that
failed while they were being scheduled left them claimed in every tab with
nothing played. Those claims are handed back on failure, the same way a
notification that could not be constructed now releases its own.

* feat: let operators set the reply polling cadence

The away poll and the focused refresh were fixed at 30 seconds and five minutes,
which are request-rate levers on the conversation list and nothing an operator
could tune. Both are fields on `interface.replyNotifications` now, bounded and
defaulting to the values they had, and the watcher reads them through the same
capability hook as the rest of the block.

* fix: keep reply identity through list merges and drop rows the server no longer has

The list merge carried three of the four read-state fields by hand and left out
`lastResponseMessageId`, so an SSE update on an unseen conversation erased which
branch the reply landed on, and a missing identity reads as visible. It uses the
same `preserveReadState` helper as the other two merge paths now, and the test
that covered the other three fields covers this one too.

A local cache merge was only inspected on a list's first page for new arrivals.
A title or oldest-first sort leaves a replied row where it is, so its first
reply on a later page went into the alerts baseline without an arrival and its
chime or notification was lost. Local merges scan every loaded page; server
responses keep the first-page rule, and only rows already known are considered.

An unread request that matched nothing means the conversation is gone: the
server's owner-scoped update returns the row even for a no-op. The mutation
rolled back the read fields and kept the row; it removes it from the caches now,
as a delete does.

* fix: discard a job completion that resolves after the watcher has gone

The fetch that settles a finished job had no teardown guard, unlike the away
poll. Signing out or switching accounts unmounts the watcher, and a response
still in flight for the previous session would then merge into the caches the
next one reads. The result is dropped once the watcher has unmounted, tracked
on unmount rather than in the jobs effect's cleanup, which re-runs on every
change to the running set while its earlier completions are still wanted.

* fix: move error-turn stamps into packages/api and settle overlapping unread no-matches

Error turns were stamped in CJS: the error middleware checked eligibility, called
the stamp and shaped the event's conversation snapshot itself, and the agents
controller stamped its own. Both call announceErrorTurn now, and the
skipped-persistence restamp goes through announceReply, so no stamp is issued
directly from /api any more. The existing sendError tests pass against the real
helper unchanged.

An unread call that no longer owned the row dropped a server no-match with the
rest of its stale answers, so a deleted conversation could be restored by a newer
call's rollback. The no-match now evicts before ownership is consulted. It stays
after the superseded check: a superseded call never reached the server, and its
synthetic `modified: false` is not a no-match.

Also: Settings offers the reply toggles only once the startup config has loaded,
matching the capability hook; a cancelled reply-discovery snapshot is restarted
even though nothing observes it; and the focused refresh is capped at the five
minutes the discovery snapshot stays authoritative, since that refresh is what
renews it.

* fix: settle the assistant final in packages/api, announce attachment-only replies

Both assistant controllers carried the same persistence barrier: write the
response, check the row and the conversation both persisted, and unwrap the
settled conversation for the final event. That is behaviour, and it was
duplicated in CJS; settleAssistantFinal owns it now and the controllers call
it. Their existing tests pass unchanged.

The announce predicate ignored attachments, so a reply made only of files,
such as a resumed workspace artifact with empty content and text, raised no
dot, badge or alert. The message body renders attachments and acknowledgement
checks the body, so such a reply can be cleared as well as announced; every
announce path now passes them through.

The stopped-reply announcement took the storage engine's own id type in its
exported signature. It takes plain string ids now, and saveConvo accepts them
alongside its own, since the update casts them against the schema; the id type
stays inside data-schemas.

* fix: normalize the stopped reply's written ids in packages/api

The abort route filtered and stringified the ids of the rows it had written
before handing them to announceStoppedReply. That is data shaping, and it sat
in CJS; the announcement takes the ids as the caller holds them and drops the
unwritten ones itself.

* style: order the conversation row classes for Tailwind v4

The v4 upgrade on canary changed the class order Prettier enforces; these
three rows carried the v3 order.

* fix: replay replies a dead tab's focus lease held back, keep the focused refresh at a full page

A tab killed without firing blur or pagehide leaves its focus lease for up to
a minute. A reply arriving under it was baselined and then suppressed, and
nothing reran when the lease lapsed, so its chime and notification were lost.
Arrivals held back only by another tab's lease are kept and rechecked when
that lease expires; a lease the focused tab keeps refreshing still holds them.

The focused refresh reused the away-poll limit, so an operator who lowered it
also shrank the discovery page that keeps the unseen count complete behind a
filtered list. The limit now bounds only the away poll.

* fix: announce a held reply as soon as the focused tab releases its lease

A tab that blurs normally clears its lease long before the lapse, and a reply
held back for it is due as soon as nobody is looking. Lease changes from other
tabs now trigger the recheck, not only the expiry timer.

(cherry picked from commit b947738d0d)

Original-PR: https://github.com/LibreChat-AI/LibreChat/pull/15025
This commit is contained in:
Marco Beretta 2026-09-23 15:39:52 +02:00 • committed by Lia
parent cb78d894a9
commit cd44344647
100 changed files with 12857 additions and 188 deletions

View file

@ -68,6 +68,7 @@ const mockFilterPersistableAbortContent = jest.fn((content) =>
);
const mockGetConvo = jest.fn();
const mockGetMessages = jest.fn();
const mockStampConvoLastResponse = jest.fn().mockResolvedValue(undefined);
const mockSaveMessage = jest.fn();
const mockSaveConvo = jest.fn();
const mockAppendConvoMessageReference = jest.fn();
@ -258,6 +259,10 @@ jest.mock('@librechat/api', () => ({
getAgentErrorMetadata: (...args) =>
jest.requireActual('@librechat/api').getAgentErrorMetadata(...args),
sendEvent: jest.fn(),
/** Real, because whether a skipped-persistence turn may raise an indicator is under test. */
isAnnounceableReply: jest.requireActual('@librechat/api').isAnnounceableReply,
announceReply: jest.requireActual('@librechat/api').announceReply,
announceErrorTurn: jest.requireActual('@librechat/api').announceErrorTurn,
logAgentMemorySnapshot: jest.fn(),
isScheduleFireRequest: (...args) => mockIsScheduleFireRequest(...args),
exemptFromConcurrencyLimiter: (...args) => mockExemptFromConcurrencyLimiter(...args),
@ -401,6 +406,7 @@ jest.mock('~/models', () => ({
getAgentEventActorDetachedAction: (...args) => mockGetAgentEventActorDetachedAction(...args),
claimAgentEventActorSuspension: (...args) => mockClaimAgentEventActorSuspension(...args),
settleAgentEventActorSuspension: (...args) => mockSettleAgentEventActorSuspension(...args),
stampConvoLastResponse: (...args) => mockStampConvoLastResponse(...args),
isAgentTriggerPrincipalActive: (...args) => mockIsAgentTriggerPrincipalActive(...args),
isSubagentOwnerAdmissible: (...args) => mockIsSubagentOwnerAdmissible(...args),
}));
@ -6302,7 +6308,13 @@ describe('ResumableAgentController resume metadata', () => {
getHaltReason: () => 'preempt_incomplete',
};
const runFirstTurn = async ({ run, addTitle: suppliedAddTitle, clientOverrides } = {}) => {
const runFirstTurn = async ({
run,
addTitle: suppliedAddTitle,
clientOverrides,
databaseResult,
responseContent = [{ type: 'text', text: 'Truncated answer' }],
} = {}) => {
let signalFinished;
const finished = new Promise((resolve) => {
signalFinished = resolve;
@ -6334,10 +6346,12 @@ describe('ResumableAgentController resume metadata', () => {
messageId: 'response-msg',
parentMessageId: 'user-msg',
conversationId: options.conversationId,
content: [{ type: 'text', text: 'Truncated answer' }],
databasePromise: Promise.resolve({
conversation: { conversationId: options.conversationId, title: null },
}),
content: responseContent,
databasePromise: Promise.resolve(
databaseResult ?? {
conversation: { conversationId: options.conversationId, title: null },
},
),
};
}),
};
@ -6374,6 +6388,69 @@ describe('ResumableAgentController resume metadata', () => {
expect(addTitle).not.toHaveBeenCalled();
});
it('does not re-stamp an unfinished response already persisted by BaseClient', async () => {
const stampedAt = new Date('2026-09-07T12:00:00.000Z');
await runFirstTurn({
run: preemptIncompleteRun,
databaseResult: {
conversation: {
conversationId: 'new',
title: null,
lastResponseAt: stampedAt,
},
},
});
expect(mockStampConvoLastResponse).not.toHaveBeenCalled();
const finalEvent = mockGenerationJobManager.publishTerminalClaim.mock.calls.at(-1)[1];
expect(finalEvent.conversation.lastResponseAt).toEqual(stampedAt);
});
it('stamps and acknowledges the fallback conversation when BaseClient persistence is skipped', async () => {
const stampedAt = new Date('2026-09-07T12:00:00.000Z');
mockSaveMessage.mockImplementation(async (_ctx, message) => message);
mockGetConvo.mockResolvedValue({
conversationId: 'new',
title: null,
createdAt: '2026-06-07T00:00:00.000Z',
lastResponseAt: stampedAt,
});
await runFirstTurn({
run: preemptIncompleteRun,
databaseResult: {
persistenceSkipped: true,
conversation: {
conversationId: 'new',
title: null,
lastResponseAt: new Date('2026-09-07T11:59:00.000Z'),
},
},
});
expect(mockStampConvoLastResponse).toHaveBeenCalledTimes(1);
const finalEvent = mockGenerationJobManager.publishTerminalClaim.mock.calls.at(-1)[1];
expect(finalEvent.conversation.lastResponseAt).toEqual(stampedAt);
});
/* A preempted turn can persist its row before the model produced anything readable. A dot
raised for that row could never be acknowledged, because acknowledgement requires the
stamped reply to be on screen. */
it('does not stamp a skipped-persistence turn that persisted nothing to read', async () => {
mockSaveMessage.mockImplementation(async (_ctx, message) => message);
await runFirstTurn({
run: preemptIncompleteRun,
responseContent: [],
databaseResult: {
persistenceSkipped: true,
conversation: { conversationId: 'new', title: null },
},
});
expect(mockStampConvoLastResponse).not.toHaveBeenCalled();
});
it('still generates a deferred title for a completed first turn', async () => {
resolveTitleTiming.mockReturnValueOnce('final');

View file

@ -93,6 +93,7 @@ const mockGetRoleByName = jest.fn();
const mockCheckAccess = jest.fn();
const mockCheckPermission = jest.fn();
const mockDecryptMetadata = jest.fn();
const mockStampConvoLastResponse = jest.fn().mockResolvedValue(undefined);
const mockDisposeClient = jest.fn();
const mockGetMCPRequestContext = jest.fn();
const mockCleanupMCPRequestContextForReq = jest.fn();
@ -172,6 +173,7 @@ jest.mock('~/models', () => ({
mockMarkAgentEventActorDetachedActionRunning(...args),
settleAgentEventActorDetachedAction: (...args) =>
mockSettleAgentEventActorDetachedAction(...args),
stampConvoLastResponse: (...args) => mockStampConvoLastResponse(...args),
}));
jest.mock('~/server/services/Endpoints/agents/eventChildLease', () => ({

View file

@ -52,6 +52,8 @@ const {
resolvePersistableCodeEnvironmentDecision,
getFailedTurnTraceFields,
resolveFailedTurnContent,
announceReply,
announceErrorTurn,
} = require('@librechat/api');
const { disposeClient } = require('~/server/cleanup');
const {
@ -83,6 +85,7 @@ const {
settleAgentEventActorDetachedAction,
claimAgentEventActorSuspension,
settleAgentEventActorSuspension,
stampConvoLastResponse,
isAgentTriggerPrincipalActive,
isSubagentOwnerAdmissible,
appendConvoMessageReference,
@ -544,6 +547,18 @@ async function saveErrorTurn(
}
: { context, noUpsert: true },
);
/* A failed run still persisted an assistant message, and a user on another device has no
other way to learn the turn ended. */
await announceErrorTurn(
{ stampConvoLastResponse },
{
userId,
conversationId,
messageId: savedErrorMessage.messageId,
isTemporary: reqCtx.isTemporary,
context: 'AgentController - persisted error turn',
},
);
} catch (err) {
logger.error('[AgentController] Failed to persist error turn', err);
throw err;
@ -2901,11 +2916,12 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTit
* 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 };
const databaseResult = await databasePromise;
const { conversation: convoData = {}, persistenceSkipped = false } = databaseResult;
const responsePersistenceWasSkipped = persistenceSkipped === true;
let conversation = { ...convoData };
conversation.title =
conversation && !conversation.title ? null : conversation?.title || 'New Chat';
if (!terminalClaim) {
/** Stop/replacement won before the response persistence hook. The
* BaseClient contract skipped its completed response write; cancel
@ -3064,6 +3080,37 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTit
await eventActorTurn?.historyPersisted();
eventActorPersistenceComplete = true;
/** A persisted BaseClient response already advanced lastResponseAt. Re-stamp only
* when its terminal persistence was explicitly skipped, then refresh the payload's
* conversation snapshot so it acknowledges the durable timestamp. */
if (responseIsUnfinished && responsePersistenceWasSkipped) {
const announced = await announceReply(
{ stampConvoLastResponse },
{
userId: reqCtx.userId,
conversationId: response.conversationId,
reply: {
messageId: savedResponseMessage.messageId,
content: response.content,
text: response.text,
attachments: response.attachments,
isTemporary: reqCtx.isTemporary,
},
context: 'AgentController - skipped terminal persistence',
},
);
if (announced) {
try {
const stampedConversation = await getConvo(reqCtx.userId, response.conversationId);
if (stampedConversation) {
conversation = { ...conversation, ...stampedConversation };
}
} catch (error) {
logger.warn('[AgentController] Failed to read back the stamped conversation', error);
}
}
}
// If the user stopped this turn — or an empty preempt boundary truncated
// it, which persists under the same honest `unfinished` contract — cancel
// the title still being generated, which never reaches its save. A title

View file

@ -88,6 +88,7 @@ const {
resolveAdmittedCodeEnvironmentDecision,
resolvePersistableCodeEnvironmentDecision,
createTerminalRunErrorObserver,
announceReply,
} = require('@librechat/api');
const {
createResponsesToolEndCallback,
@ -423,7 +424,7 @@ async function saveResponseOutput(
const langfuseTraceFields = await getLangfuseTraceMessageFields(req.config, responseId);
// Save the assistant message
await db.saveMessage(
return db.saveMessage(
req,
{
messageId: responseId,
@ -1415,7 +1416,7 @@ const executeResponse = async (envelope, { req, res }) => {
// Build response for saving (use tracker with buildResponse for streaming)
const finalResponse = buildResponse(context, tracker, 'completed');
await saveResponseOutput(
const savedResponse = await saveResponseOutput(
req,
conversationId,
responseId,
@ -1423,6 +1424,15 @@ const executeResponse = async (envelope, { req, res }) => {
agentId,
tracker.usage.outputTokens,
);
await announceReply(db, {
userId: req?.user?.id,
conversationId,
reply: {
...savedResponse,
isTemporary: req?.resolvedConversation?.isTemporary ?? req?.body?.isTemporary,
},
context: 'Responses API - announce stored reply',
});
logger.debug(
`[Responses API] Stored response ${responseId} in conversation ${conversationId}`,
@ -1649,7 +1659,7 @@ const executeResponse = async (envelope, { req, res }) => {
await saveInputMessages(req, conversationId, inputMessages, agentId);
await saveResponseOutput(
const savedResponse = await saveResponseOutput(
req,
conversationId,
responseId,
@ -1657,6 +1667,15 @@ const executeResponse = async (envelope, { req, res }) => {
agentId,
aggregator.usage.outputTokens,
);
await announceReply(db, {
userId: req?.user?.id,
conversationId,
reply: {
...savedResponse,
isTemporary: req?.resolvedConversation?.isTemporary ?? req?.body?.isTemporary,
},
context: 'Responses API - announce stored reply',
});
logger.debug(
`[Responses API] Stored response ${responseId} in conversation ${conversationId}`,

View file

@ -49,6 +49,7 @@ const {
collectReachableAgents,
restoreScheduledTokenContext,
recoverTurnMessageReference,
announceReply,
} = require('@librechat/api');
const { disposeClient } = require('~/server/cleanup');
const { decryptMetadata } = require('~/server/services/ActionService');
@ -79,6 +80,7 @@ const {
markAgentEventActorDetachedActionRunning,
settleAgentEventActorDetachedAction,
appendConvoMessageReference,
stampConvoLastResponse,
} = require('~/models');
const {
acquireEventChildGenerationLease,
@ -590,6 +592,24 @@ async function finalizeResumedTurn({
metadata: meta,
});
/* This path saves the message directly, so nothing else stamps the unseen-reply
indicator. Best-effort: a missed stamp must not fail the resumed turn. */
await announceReply(
{ stampConvoLastResponse },
{
userId,
conversationId,
reply: {
messageId: savedResponseMessage.messageId,
content: responseMessage.content,
text: responseMessage.text,
attachments: responseMessage.attachments,
isTemporary,
},
context: 'ResumeAgentController - resumed response end',
},
);
const convo = await getConvo(userId, conversationId);
const conversation = { ...(convo ?? {}), conversationId };

View file

@ -5,6 +5,8 @@ const mockCreateRun = jest.fn();
const mockStreamRunManager = jest.fn();
const mockSendEvent = jest.fn();
const mockSaveUserMessage = jest.fn();
const mockSaveAssistantMessage = jest.fn();
const mockCreateRunBody = jest.fn();
const mockSendResponse = jest.fn();
const mockHandleError = jest.fn();
const mockRetrieveAssistant = jest.fn();
@ -66,7 +68,7 @@ jest.mock('~/server/services/Threads', () => ({
saveUserMessage: (...args) => mockSaveUserMessage(...args),
checkMessageGaps: jest.fn(),
addThreadMetadata: jest.fn(),
saveAssistantMessage: jest.fn(),
saveAssistantMessage: (...args) => mockSaveAssistantMessage(...args),
}));
jest.mock('~/server/services/AssistantService', () => ({
@ -104,7 +106,7 @@ jest.mock('~/server/services/Endpoints/assistants', () => ({
}));
jest.mock('~/server/services/createRunBody', () => ({
createRunBody: jest.fn(),
createRunBody: (...args) => mockCreateRunBody(...args),
}));
jest.mock('~/server/middleware/error', () => ({
@ -163,6 +165,24 @@ describe.each([
mockGetConvo.mockReset().mockResolvedValue(null);
mockEncodeAndFormat.mockReset().mockResolvedValue({ files: [], image_urls: [] });
mockInitThread.mockReset();
mockCreateRun.mockReset();
mockRunAssistant.mockReset();
mockCreateRunBody.mockReset();
/* Every run that reaches FINAL has persisted its assistant row: the controller publishes
the conversation snapshot the client acknowledges, so a test that does not care about
the write still needs one. Tests asserting on the stamp override this. */
mockSaveAssistantMessage.mockReset().mockResolvedValue({
message: { messageId: 'assistant-msg' },
conversation: { conversationId: 'convo-1' },
});
mockGetOpenAIClient.mockReset().mockResolvedValue({
openai: {
beta: {
assistants: { retrieve: mockRetrieveAssistant },
threads: { messages: { list: mockListThreadMessages }, runs: {} },
},
},
});
closeHandler = undefined;
req = {
config: {
@ -237,6 +257,67 @@ describe.each([
expect(mockHandleError).not.toHaveBeenCalled();
expect(mockSendResponse).not.toHaveBeenCalled();
}
it('persists the assistant before FINAL and forwards the settled read-state stamp', async () => {
const stamp = new Date('2026-09-08T12:00:00.000Z');
const settledConversation = {
conversationId: 'generated-id',
endpoint: 'azureAssistants',
lastResponseAt: stamp,
lastSeenAt: undefined,
lastResponseIsManual: undefined,
title: 'Existing title',
};
mockCreateRunBody.mockReturnValue({});
mockInitThread.mockResolvedValue({ thread_id: 'thread-new' });
mockCreateRun.mockResolvedValue({ id: 'run-1' });
mockRunAssistant.mockResolvedValue({
run: { status: 'completed', usage: {} },
responseMessage: { messageId: 'assistant-msg' },
text: 'done',
messages: [],
steps: [],
});
mockSaveUserMessage.mockResolvedValue({ messageId: 'user-msg' });
mockSaveAssistantMessage.mockResolvedValue({
message: { messageId: 'assistant-msg' },
conversation: settledConversation,
});
mockGetOpenAIClient.mockResolvedValue({
openai: {
_options: { model: 'gpt-4' },
responseMessage: { messageId: 'assistant-msg' },
beta: {
assistants: { retrieve: mockRetrieveAssistant },
threads: {
messages: {
list: mockListThreadMessages,
update: jest.fn().mockResolvedValue({}),
},
runs: {},
},
},
},
});
req.body.endpoint = 'azureAssistants';
await chatController(req, res);
const finalCall = mockSendEvent.mock.calls.find(([, event]) => event.final === true);
expect(finalCall?.[1]).toEqual(
expect.objectContaining({
final: true,
conversation: expect.objectContaining(settledConversation),
}),
);
expect(mockSaveAssistantMessage.mock.invocationCallOrder[0]).toBeLessThan(
mockSendEvent.mock.invocationCallOrder.at(-1),
);
expect(mockSaveAssistantMessage).toHaveBeenCalledWith(
expect.anything(),
expect.objectContaining({ messageId: 'assistant-msg' }),
);
expect(res.end).toHaveBeenCalledTimes(1);
});
it('releases a balance reservation that settles after thread initialization fails', async () => {
req.config.filters = {};

View file

@ -16,6 +16,7 @@ const {
preflightAssistantRunContent,
reportLocatorTraversalFailure,
preflightAssistantUserMessageContent,
settleAssistantFinal,
} = require('@librechat/api');
const {
Time,
@ -704,9 +705,17 @@ const chatV1 = async (req, res) => {
iconURL: endpointOption.iconURL,
};
if (userMessagePromise) {
await userMessagePromise;
}
const settledConversation = await settleAssistantFinal(() =>
saveAssistantMessage(req, { ...responseMessage, model }),
);
sendEvent(res, {
final: true,
conversation,
conversation: { ...conversation, ...settledConversation },
requestMessage: {
parentMessageId,
thread_id,
@ -714,11 +723,6 @@ const chatV1 = async (req, res) => {
});
res.end();
if (userMessagePromise) {
await userMessagePromise;
}
await saveAssistantMessage(req, { ...responseMessage, model });
if (parentMessageId === Constants.NO_PARENT && !_thread_id) {
addTitle(req, {
text,

View file

@ -15,6 +15,7 @@ const {
preflightAssistantRunContent,
reportLocatorTraversalFailure,
preflightAssistantUserMessageContent,
settleAssistantFinal,
} = require('@librechat/api');
const {
Time,
@ -542,9 +543,17 @@ const chatV2 = async (req, res) => {
iconURL: endpointOption.iconURL,
};
if (userMessagePromise) {
await userMessagePromise;
}
const settledConversation = await settleAssistantFinal(() =>
saveAssistantMessage(req, { ...responseMessage, model }),
);
sendEvent(res, {
final: true,
conversation,
conversation: { ...conversation, ...settledConversation },
requestMessage: {
parentMessageId,
thread_id,
@ -552,11 +561,6 @@ const chatV2 = async (req, res) => {
});
res.end();
if (userMessagePromise) {
await userMessagePromise;
}
await saveAssistantMessage(req, { ...responseMessage, model });
if (parentMessageId === Constants.NO_PARENT && !_thread_id) {
addTitle(req, {
text,

View file

@ -8,6 +8,7 @@ const {
GenerationJobManager,
sanitizeMessageForTransmit,
buildAbortedResponseMetadata,
announceReply,
} = require('@librechat/api');
const { truncateText, smartTruncateText } = require('~/app/clients/prompts');
const clearPendingReq = require('~/cache/clearPendingReq');
@ -78,7 +79,7 @@ async function abortMessage(req, res) {
* (`AgentClient` labels a stopped turn `'abort'`), so billing here would
* charge it a second time. This route only stops and persists. */
await db.saveMessage(
const savedMessage = await db.saveMessage(
{
userId: req?.user?.id,
isTemporary: req?.resolvedConversation?.isTemporary ?? req?.body?.isTemporary,
@ -89,6 +90,28 @@ async function abortMessage(req, res) {
{ context: 'api/server/middleware/abortMiddleware.js' },
);
/* Mirrors the agents abort route: when Stop wins the terminal claim, the request controller
can return before its own save, making this direct write the only one that could reach
the unseen-reply indicator. The assistants path stamps inside `syncMessages`; this one
saves the message directly, so the stamp rides along here. Best-effort: the row is
already durable, and a missed stamp must not suppress the final event.
The temporary flag comes from the job: the client's abort request carries only the abort
key and endpoint, so the request body alone would stamp a stopped temporary chat.
An interrupt before the first real token still persists the unfinished assistant row, but
that row renders nothing: stamping it would raise a dot for a reply with nothing to read,
and opening the conversation could never clear it. */
await announceReply(db, {
userId,
conversationId: jobData?.conversationId,
reply: {
messageId: savedMessage?.messageId,
content,
text,
isTemporary: (jobData?.isTemporary ?? req?.body?.isTemporary) === true,
},
context: 'abortMessage',
});
// Get conversation for title
const conversation = await db.getConvo(userId, conversationId);

View file

@ -26,9 +26,12 @@ jest.mock('@librechat/data-schemas', () => ({
}));
jest.mock('@librechat/api', () => ({
/** Real implementation: these tests exist to verify abort classification
* itself, so mocking it would assert the mock rather than the behavior. */
/** Real implementations: these tests exist to verify abort classification and the
* readable-reply gate themselves, so mocking them would assert the mock rather than the
* behavior. */
isAbortError: jest.requireActual('@librechat/api').isAbortError,
hasPersistableAbortContent: jest.requireActual('@librechat/api').hasPersistableAbortContent,
announceReply: jest.requireActual('@librechat/api').announceReply,
countTokens: jest.fn().mockResolvedValue(100),
isEnabled: jest.fn().mockReturnValue(false),
sendEvent: jest.fn(),
@ -64,6 +67,7 @@ const mockUpdateBalance = jest.fn().mockResolvedValue({});
const mockBulkInsertTransactions = jest.fn().mockResolvedValue(undefined);
jest.mock('~/models', () => ({
saveMessage: jest.fn().mockResolvedValue(),
stampConvoLastResponse: jest.fn().mockResolvedValue(),
getConvo: jest.fn().mockResolvedValue({ title: 'Test Chat' }),
updateBalance: mockUpdateBalance,
bulkInsertTransactions: mockBulkInsertTransactions,
@ -195,6 +199,68 @@ describe('abortMiddleware - handleAbort billing', () => {
db.getConvo.mockResolvedValue({ title: 'Test Chat' });
});
it.each([null, undefined])(
'keeps read state unchanged when the abort save returns %s',
async (saved) => {
const conversation = {
title: 'Test Chat',
lastResponseAt: '2026-09-01T10:00:00.000Z',
lastSeenAt: '2026-09-01T10:01:00.000Z',
};
db.saveMessage.mockResolvedValueOnce(saved);
db.getConvo.mockResolvedValueOnce(conversation);
GenerationJobManager.abortJob.mockResolvedValue({
success: true,
jobData: buildJobData(),
content: [],
text: 'partial',
collectedUsage: [],
});
const res = buildRes();
await handleAbort()(buildReq(), res);
expect(db.stampConvoLastResponse).not.toHaveBeenCalled();
expect(JSON.parse(res.send.mock.calls[0][0]).conversation).toEqual(conversation);
},
);
it('announces a persisted stopped reply', async () => {
db.saveMessage.mockResolvedValueOnce({ messageId: 'msg-123' });
GenerationJobManager.abortJob.mockResolvedValue({
success: true,
jobData: buildJobData(),
content: [],
text: 'partial',
collectedUsage: [],
});
const res = buildRes();
await handleAbort()(buildReq(), res);
expect(db.stampConvoLastResponse).toHaveBeenCalledWith('user-123', 'convo-123', 'msg-123');
expect(JSON.parse(res.send.mock.calls[0][0]).final).toBe(true);
});
it('does not announce a stopped turn that produced nothing to read', async () => {
/* An interrupt before the model's first real token still persists the unfinished
assistant row; a dot raised for it names a reply the user can never open. */
db.saveMessage.mockResolvedValueOnce({ messageId: 'msg-empty' });
GenerationJobManager.abortJob.mockResolvedValue({
success: true,
jobData: buildJobData(),
content: [{ type: 'text', text: ' ' }],
text: ' ',
collectedUsage: [],
});
const res = buildRes();
await handleAbort()(buildReq(), res);
expect(db.stampConvoLastResponse).not.toHaveBeenCalled();
expect(JSON.parse(res.send.mock.calls[0][0]).final).toBe(true);
});
it('leaves billing to the run even when the stopped job collected usage', async () => {
const collectedUsage = [{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' }];
GenerationJobManager.abortJob.mockResolvedValue({

View file

@ -1,8 +1,13 @@
const crypto = require('crypto');
const { logger } = require('@librechat/data-schemas');
const { parseConvo } = require('librechat-data-provider');
const { sendEvent, handleError, sanitizeMessageForTransmit } = require('@librechat/api');
const { saveMessage, getMessages, getConvo } = require('~/models');
const {
sendEvent,
handleError,
announceErrorTurn,
sanitizeMessageForTransmit,
} = require('@librechat/api');
const { saveMessage, getMessages, getConvo, stampConvoLastResponse } = require('~/models');
/**
* Processes an error with provided options, saves the error message and sends a corresponding SSE response
@ -47,10 +52,11 @@ const sendError = async (req, res, options, callback) => {
}
if (shouldSaveMessage) {
await saveMessage(
const isTemporary = req?.resolvedConversation?.isTemporary ?? req?.body?.isTemporary;
const savedError = await saveMessage(
{
userId: req?.user?.id,
isTemporary: req?.resolvedConversation?.isTemporary ?? req?.body?.isTemporary,
isTemporary,
expiredAt: req?.resolvedConversation?.expiredAt,
interfaceConfig: req?.config?.interfaceConfig,
},
@ -59,6 +65,19 @@ const sendError = async (req, res, options, callback) => {
context: 'api/server/utils/streamResponse.js - sendError',
},
);
const conversation = await announceErrorTurn(
{ stampConvoLastResponse },
{
userId: req?.user?.id ?? user,
conversationId,
messageId: savedError?.messageId,
isTemporary: isTemporary === true,
context: 'sendError',
},
);
if (conversation) {
errorMessage.conversation = conversation;
}
}
if (!errorMessage.error) {

View file

@ -0,0 +1,132 @@
/**
* Tests for sendError's reply stamping.
*
* A terminal error is a persisted assistant turn, and on the fallback paths that reach here it
* is the only one written: without a stamp another device never learns the run ended.
*/
const mockSaveMessage = jest.fn();
const mockStampConvoLastResponse = jest.fn();
const mockHandleError = jest.fn();
jest.mock('@librechat/data-schemas', () => ({
logger: { debug: jest.fn(), error: jest.fn(), warn: jest.fn(), info: jest.fn() },
}));
jest.mock('@librechat/api', () => ({
sendEvent: jest.fn(),
handleError: (...args) => mockHandleError(...args),
sanitizeMessageForTransmit: jest.fn((message) => message),
/** Real, because when an error turn is stamped and what its event carries is under test. */
announceErrorTurn: jest.requireActual('@librechat/api').announceErrorTurn,
}));
jest.mock('~/models', () => ({
saveMessage: (...args) => mockSaveMessage(...args),
getMessages: jest.fn().mockResolvedValue([]),
getConvo: jest.fn().mockResolvedValue({}),
stampConvoLastResponse: (...args) => mockStampConvoLastResponse(...args),
}));
const { sendError } = require('./error');
const CONVO_ID = 'convo-errored';
const options = {
user: 'user-123',
sender: 'AI',
conversationId: CONVO_ID,
messageId: 'error-msg',
parentMessageId: 'user-msg',
text: 'Something went wrong',
shouldSaveMessage: true,
};
const reqWith = (body = {}) => ({ user: { id: 'user-123' }, body, config: {} });
describe('sendError', () => {
const stampedAt = new Date('2026-08-16T10:00:00.000Z');
const updatedAt = new Date('2026-08-16T10:00:00.001Z');
beforeEach(() => {
mockSaveMessage.mockReset();
mockSaveMessage.mockImplementation(async (_ctx, message) => message);
mockStampConvoLastResponse.mockReset();
mockStampConvoLastResponse.mockResolvedValue({
lastResponseAt: stampedAt,
lastResponseMessageId: 'error-msg',
updatedAt,
});
mockHandleError.mockReset();
});
it('stamps the conversation once the error reply is durable and emits that settled read state', async () => {
await sendError(reqWith(), {}, options);
expect(mockStampConvoLastResponse).toHaveBeenCalledWith('user-123', CONVO_ID, 'error-msg');
expect(mockHandleError).toHaveBeenCalledWith(
{},
expect.objectContaining({
conversation: {
conversationId: CONVO_ID,
lastResponseAt: stampedAt,
lastResponseMessageId: 'error-msg',
updatedAt,
},
}),
);
});
it('never stamps or exposes a temporary conversation', async () => {
await sendError(reqWith({ isTemporary: true }), {}, options);
expect(mockStampConvoLastResponse).not.toHaveBeenCalled();
expect(mockHandleError).toHaveBeenCalledWith(
{},
expect.not.objectContaining({ conversation: expect.anything() }),
);
});
it('never stamps or exposes a reply the message write did not persist', async () => {
/* Announcing a reply that is absent from message history would show a dot for a message
nobody can open. */
mockSaveMessage.mockResolvedValue(null);
await sendError(reqWith(), {}, options);
expect(mockStampConvoLastResponse).not.toHaveBeenCalled();
expect(mockHandleError).toHaveBeenCalledWith(
{},
expect.not.objectContaining({ conversation: expect.anything() }),
);
});
it('never exposes a read stamp when the indicator write fails', async () => {
mockStampConvoLastResponse.mockRejectedValue(new Error('mongo is down'));
await expect(sendError(reqWith(), {}, options)).resolves.toBeUndefined();
expect(mockHandleError).toHaveBeenCalledWith(
{},
expect.not.objectContaining({ conversation: expect.anything() }),
);
});
it('does not expose a stamp when the conversation cannot be settled', async () => {
mockStampConvoLastResponse.mockResolvedValue(null);
await sendError(reqWith(), {}, options);
expect(mockHandleError).toHaveBeenCalledWith(
{},
expect.not.objectContaining({ conversation: expect.anything() }),
);
});
it('leaves the stamp alone when the caller does not persist the message', async () => {
await sendError(reqWith(), {}, { ...options, shouldSaveMessage: false });
expect(mockSaveMessage).not.toHaveBeenCalled();
expect(mockStampConvoLastResponse).not.toHaveBeenCalled();
});
});

View file

@ -55,6 +55,8 @@ function resetCheckpointRows(rows = []) {
checkpointRows.splice(0, checkpointRows.length, ...rows);
deletionTargets.clear();
}
const markConvoSeenHandler = jest.fn();
const markConvoUnreadHandler = jest.fn();
module.exports = {
archiveAllHandler,
@ -67,6 +69,8 @@ module.exports = {
messageUserLimiter,
checkpointRows,
resetCheckpointRows,
markConvoSeenHandler,
markConvoUnreadHandler,
agents: () => ({ sleep: jest.fn() }),
@ -173,6 +177,23 @@ module.exports = {
subagentActivityHandlerInputs.push({ deps, stream });
return (_req, res) => res.status(200).end();
}),
/* Wiring only. The handlers' own validation and error mapping are covered against the
real implementations in `packages/api/src/conversations/read.spec.ts`; mirroring them
here would leave the route suite asserting against a copy. */
createMarkConvoSeenHandler: jest.fn(({ markConvoSeen }) => {
markConvoSeenHandler.mockImplementation(async (req, res) => {
const result = await markConvoSeen(req.user.id, req.body?.arg?.conversationId);
return res.status(200).json(result);
});
return markConvoSeenHandler;
}),
createMarkConvoUnreadHandler: jest.fn(({ markConvoUnread }) => {
markConvoUnreadHandler.mockImplementation(async (req, res) => {
const result = await markConvoUnread(req.user.id, req.body?.arg?.conversationId);
return res.status(200).json(result);
});
return markConvoUnreadHandler;
}),
deleteConvoSharedLinksWithCleanup: jest.fn(),
deleteAllSharedLinksWithCleanup: jest.fn(),
deleteAgentCheckpoints,
@ -224,6 +245,8 @@ module.exports = {
archiveAllConvos: jest.fn(),
saveConvo: jest.fn(),
setConvoPinned: jest.fn(),
markConvoSeen: jest.fn(),
markConvoUnread: jest.fn(),
deleteAllSharedLinks: jest.fn(),
deleteConvoSharedLink: jest.fn(),
deleteToolCalls: jest.fn(),

View file

@ -68,6 +68,8 @@ describe('Convos Routes', () => {
deleteMessages,
getConvo,
saveConvo,
markConvoSeen,
markConvoUnread,
} = require('~/models');
const {
deleteOwnedAgentCheckpoints,
@ -1910,6 +1912,37 @@ describe('Convos Routes', () => {
});
});
describe('POST /seen', () => {
/* The handler's own validation and error mapping live in `packages/api` and are covered
against the real implementation there; what matters here is that the route reaches it
with the authenticated user. */
it('routes to the handler for the authenticated user', async () => {
markConvoSeen.mockResolvedValue({ modified: true });
const response = await request(app)
.post('/api/convos/seen')
.send({ arg: { conversationId: 'conv-seen-1' } });
expect(response.status).toBe(200);
expect(response.body).toEqual({ modified: true });
expect(markConvoSeen).toHaveBeenCalledWith('test-user-123', 'conv-seen-1');
});
});
describe('POST /unread', () => {
it('routes to the handler for the authenticated user', async () => {
markConvoUnread.mockResolvedValue({ modified: true });
const response = await request(app)
.post('/api/convos/unread')
.send({ arg: { conversationId: 'conv-unread-1' } });
expect(response.status).toBe(200);
expect(response.body).toEqual({ modified: true });
expect(markConvoUnread).toHaveBeenCalledWith('test-user-123', 'conv-unread-1');
});
});
describe('POST /archive', () => {
it('should archive a conversation successfully', async () => {
const mockConversationId = 'conv-123';

View file

@ -24,6 +24,7 @@ const mockGenerationJobManager = {
};
const mockSaveMessage = jest.fn();
const mockSaveConvo = jest.fn();
const mockRecordScheduleOutcome = jest.fn();
const mockBeginScheduledStop = jest.fn();
@ -47,6 +48,7 @@ jest.mock('@librechat/api', () => ({
jest.mock('~/models', () => ({
saveMessage: (...args) => mockSaveMessage(...args),
saveConvo: (...args) => mockSaveConvo(...args),
}));
jest.mock('~/server/services/Schedules', () => ({
@ -99,6 +101,8 @@ describe('Agent Abort Endpoint', () => {
mockGenerationJobManager.getActiveJobIdsForUser.mockReset();
mockSaveMessage.mockReset();
mockSaveMessage.mockImplementation(async (_context, message) => message);
mockSaveConvo.mockReset();
mockSaveConvo.mockResolvedValue({});
mockRecordScheduleOutcome.mockReset();
mockRecordScheduleOutcome.mockResolvedValue(true);
mockBeginScheduledStop.mockReset();
@ -343,6 +347,14 @@ describe('Agent Abort Endpoint', () => {
expect.objectContaining({ context: expect.stringContaining('abort endpoint') }),
);
/** The row renders nothing, so a dot raised for it names a reply the user can never
* open and no acknowledgement could clear. */
expect(mockSaveConvo).not.toHaveBeenCalledWith(
expect.anything(),
expect.anything(),
expect.objectContaining({ stampReply: true }),
);
/** This is the exact server-side fence hit by the queued submission
* after the abort FINAL. It must observe the row written above rather
* than reject the drain solely because the stable id ends in `_`. */
@ -494,6 +506,52 @@ describe('Agent Abort Endpoint', () => {
expect(savedResponse.contextMeta).toBeNull();
});
it('stamps the aborted reply through an upsert so an early stop still lights the dot', async () => {
const jobStreamId = 'test-stream-123';
mockGenerationJobManager.getJob.mockResolvedValue({
metadata: { userId: 'test-user-123' },
});
const abortResult = {
success: true,
jobData: {
userMessage: { messageId: 'user-msg-123' },
responseMessageId: 'response-msg-456',
conversationId: jobStreamId,
endpoint: 'anthropic',
model: 'claude-3',
},
content: [{ type: 'text', text: 'Partial response...' }],
text: 'Partial response...',
};
mockGenerationJobManager.abortJob.mockImplementation(async (_streamId, options) => {
await options.beforePublish(abortResult);
return abortResult;
});
mockSaveMessage.mockImplementation(async (_context, message) => ({
...message,
_id: `oid-${message.messageId}`,
}));
const response = await request(app)
.post('/api/agents/chat/abort')
.send({ conversationId: jobStreamId });
expect(response.status).toBe(200);
expect(mockSaveConvo).toHaveBeenCalledWith(
expect.anything(),
expect.objectContaining({
conversationId: jobStreamId,
endpoint: 'anthropic',
model: 'claude-3',
}),
expect.objectContaining({
stampReply: true,
replyMessageId: 'response-msg-456',
/* Without these `saveConvo` reloads the whole history inside the abort barrier. */
appendMessageIds: ['oid-user-msg-123', 'oid-response-msg-456'],
}),
);
});
it('saves the aborted partial as temporary from job metadata, not the request body', async () => {
const jobStreamId = 'test-stream-123';
const expiredAt = new Date('2030-01-01T00:00:00.000Z');

View file

@ -5,6 +5,7 @@ const {
GenerationJobManager,
TERMINAL_PUBLICATION_RECONNECT_ERROR,
hasPersistableAbortContent,
announceStoppedReply,
buildAbortedResponseMetadata,
isPendingActionStale,
toClientPendingAction,
@ -49,7 +50,7 @@ const {
getServerGenerationProtocol,
negotiateExistingGenerationProtocol,
} = require('~/server/controllers/agents/protocol');
const { getFiles, saveMessage } = require('~/models');
const { getFiles, saveConvo, saveMessage } = require('~/models');
const {
recordScheduleOutcome,
beginScheduledStop,
@ -828,6 +829,7 @@ router.post('/chat/abort', configMiddleware, async (req, res, next) => {
* await the user prerequisite first, but still attempt the child
* write and checkpoint cleanup so every independently useful
* operation gets a chance to succeed. */
let persistedRequestId;
try {
const persistedRequest = await saveMessage(messageContext, requestMessage, {
context: 'api/server/routes/agents/index.js - abort user prerequisite',
@ -835,6 +837,7 @@ router.post('/chat/abort', configMiddleware, async (req, res, next) => {
if (!persistedRequest) {
throw new Error('Abort user prerequisite was not persisted');
}
persistedRequestId = persistedRequest._id;
} catch (error) {
persistenceErrors.push(error);
}
@ -847,6 +850,28 @@ router.post('/chat/abort', configMiddleware, async (req, res, next) => {
throw new Error('Abort response was not persisted');
}
logger.debug(`[AgentStream] Saved partial response for: ${jobStreamId}`);
/* When Stop wins the terminal claim the request controller returns before its
own stamp, so this is the only place a stopped turn's reply reaches the
unseen-reply indicator.
The two rows this barrier just wrote are handed over directly: without them
the conversation write reloads the entire message list to rebuild `messages`,
and that serial read sits between Stop and the FINAL event. */
await announceStoppedReply(
{ saveConvo },
{
ctx: messageContext,
conversationId: jobData.conversationId,
endpoint: jobData.endpoint,
model: jobData.model,
reply: {
messageId: persistedResponse.messageId,
content,
attachments: responseMessage.attachments,
},
appendMessageIds: [persistedRequestId, persistedResponse._id],
context: 'api/server/routes/agents/index.js - abort reply stamp',
},
);
} catch (error) {
persistenceErrors.push(error);
}

View file

@ -21,6 +21,8 @@ const {
createBackgroundTaskPolicyMiddleware,
backgroundTaskRegistry,
createSubagentThreadViewHandler,
createMarkConvoSeenHandler,
createMarkConvoUnreadHandler,
resolveImportMaxFileSize,
restoreTenantContextFromReq,
deleteAllSharedLinksWithCleanup,
@ -152,13 +154,9 @@ const subagentControlHandler = createSubagentControlHandler({
getSubagentTaskControlReceipt: db.getSubagentTaskControlReceipt,
store: subagentThreadTaskStore,
});
const backgroundTaskPolicy = createBackgroundTaskPolicyMiddleware({ getAppConfig });
const backgroundTaskIndexHandler = createBackgroundTaskIndexHandler({
registry: backgroundTaskRegistry,
pending: pendingBackgroundToolCompletions,
});
const backgroundTaskCancelHandler = createBackgroundTaskCancelHandler({
registry: backgroundTaskRegistry,
const markConvoSeenHandler = createMarkConvoSeenHandler({ markConvoSeen: db.markConvoSeen });
const markConvoUnreadHandler = createMarkConvoUnreadHandler({
markConvoUnread: db.markConvoUnread,
});
router.use(requireJwtAuth);
@ -695,6 +693,10 @@ router.post('/pin', validateConvoAccess, async (req, res) => {
}
});
router.post('/seen', validateConvoAccess, markConvoSeenHandler);
router.post('/unread', validateConvoAccess, markConvoUnreadHandler);
/** Maximum allowed length for conversation titles */
const MAX_CONVO_TITLE_LENGTH = 1024;

View file

@ -172,6 +172,7 @@ const addTitle = async (
{
context: 'api/server/services/Endpoints/agents/title.js',
noUpsert: true,
preserveUpdatedAt: 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

View file

@ -80,7 +80,12 @@ const addTitle = async (req, { text, responseText, conversationId }) => {
conversationId,
title,
},
{ context: 'api/server/services/Endpoints/assistants/addTitle.js', noUpsert: true },
{
context: 'api/server/services/Endpoints/assistants/addTitle.js',
noUpsert: true,
preserveUpdatedAt: true,
appendMessageIds: [],
},
);
} catch (error) {
logger.error('[addTitle] Error generating title:', error);
@ -112,7 +117,12 @@ const addTitle = async (req, { text, responseText, conversationId }) => {
conversationId,
title: fallbackTitle,
},
{ context: 'api/server/services/Endpoints/assistants/addTitle.js', noUpsert: true },
{
context: 'api/server/services/Endpoints/assistants/addTitle.js',
noUpsert: true,
preserveUpdatedAt: true,
appendMessageIds: [],
},
);
}
};

View file

@ -0,0 +1,88 @@
const mongoose = require('mongoose');
const { MongoMemoryServer } = require('mongodb-memory-server');
const mockTitles = new Map();
const mockInitializeClient = jest.fn();
jest.mock('~/cache/getLogStores', () => () => ({
get: async (key) => mockTitles.get(key),
set: async (key, value) => mockTitles.set(key, value),
delete: async (key) => mockTitles.delete(key),
}));
jest.mock(
'./assistants/initalize',
() =>
(...args) =>
mockInitializeClient(...args),
);
const { Conversation, Message } = require('~/db/models');
const addAssistantTitle = require('./assistants/title');
const addAgentTitle = require('./agents/title');
describe('generated title reply provenance', () => {
let mongo;
beforeAll(async () => {
mongo = await MongoMemoryServer.create();
await mongoose.connect(mongo.getUri());
});
afterAll(async () => {
await mongoose.disconnect();
await mongo.stop();
});
beforeEach(async () => {
await Conversation.deleteMany({});
mockTitles.clear();
mockInitializeClient.mockReset();
});
it.each(['assistant', 'assistant fallback', 'agent'])(
'preserves reply activity through an automatic %s title without loading history',
async (mode) => {
const conversationId = 'automatic-title';
const replyAt = new Date('2026-08-16T10:00:00.000Z');
await Conversation.create({
conversationId,
user: 'title-user',
endpoint: 'assistants',
title: 'New Chat',
createdAt: replyAt,
updatedAt: replyAt,
lastResponseAt: replyAt,
});
const create = jest.fn();
if (mode === 'assistant fallback') {
create.mockRejectedValue(new Error('title service unavailable'));
} else {
create.mockResolvedValue({ choices: [{ message: { content: 'Automatic title' } }] });
}
mockInitializeClient.mockResolvedValue({ openai: { chat: { completions: { create } } } });
const req = { user: { id: 'title-user' }, body: {}, config: {} };
const history = jest.spyOn(Message, 'find');
try {
if (mode === 'agent') {
await addAgentTitle(req, {
text: 'Automatic title',
response: { conversationId },
client: {
options: { titleConvo: true },
titleConvo: async () => 'Automatic title',
},
});
} else {
await addAssistantTitle(req, {
text: 'Automatic title',
responseText: 'Assistant reply',
conversationId,
});
}
expect(history).not.toHaveBeenCalled();
const saved = await Conversation.findOne({ conversationId }).lean();
expect(saved.title).toBe('Automatic title');
expect(saved.lastResponseAt).toEqual(replyAt);
expect(saved.updatedAt).toEqual(replyAt);
} finally {
history.mockRestore();
}
},
);
});

View file

@ -1,6 +1,6 @@
const path = require('path');
const { v4 } = require('uuid');
const { countTokens } = require('@librechat/api');
const { countTokens, announceReply, isAnnounceableReply } = require('@librechat/api');
const { escapeRegExp } = require('@librechat/data-schemas');
const {
Constants,
@ -8,7 +8,13 @@ const {
AnnotationTypes,
defaultOrderQuery,
} = require('librechat-data-provider');
const { saveMessage, getMessages, spendTokens, saveConvo } = require('~/models');
const {
saveConvo,
getMessages,
spendTokens,
saveMessage,
stampConvoLastResponse,
} = require('~/models');
const { retrieveAndProcessFile } = require('~/server/services/Files/process');
/**
@ -100,7 +106,10 @@ async function saveUserMessage(req, params) {
const savedConvo = await saveConvo(
{ ...ctx, expiredAt: message?.expiredAt ?? ctx.expiredAt },
convo,
{ context: 'api/server/services/Threads/manage.js #saveUserMessage' },
{
context: 'api/server/services/Threads/manage.js #saveUserMessage',
...(message?._id != null ? { appendMessageIds: [message._id] } : {}),
},
);
if (savedConvo != null) {
req.resolvedConversation = savedConvo;
@ -128,7 +137,8 @@ async function saveUserMessage(req, params) {
* @param {string} [params.iconURL]
* Overrides the instructions of the assistant.
* @param {string} [params.promptPrefix] - Optional: from preset for `additional_instructions` field.
* @return {Promise<Run>} A promise that resolves to the created run object.
* @return {Promise<{message: Object|null, conversation: Object|null}>} The persisted assistant
* message and the conversation snapshot settled by the same write.
*/
async function saveAssistantMessage(req, params) {
// const tokenCount = // TODO: need to count each content part
@ -158,6 +168,13 @@ async function saveAssistantMessage(req, params) {
spec: params.spec,
});
const announceable = isAnnounceableReply({
messageId: message?.messageId,
content: params.content,
text: params.text,
isTemporary: ctx.isTemporary,
});
const savedConvo = await saveConvo(
{ ...ctx, expiredAt: message?.expiredAt ?? ctx.expiredAt },
{
@ -170,14 +187,23 @@ async function saveAssistantMessage(req, params) {
iconURL: params.iconURL,
spec: params.spec,
},
{ context: 'api/server/services/Threads/manage.js #saveAssistantMessage' },
{
context: 'api/server/services/Threads/manage.js #saveAssistantMessage',
/** Judged by the same predicate every other persistence path asks, so an assistant row
* that renders nothing cannot raise a dot here that opening the chat can never clear.
* `saveConvo` assigns the timestamp past its own awaited reads, so a catch-up recorded
* while one of them is in flight cannot outrank this reply. */
stampReply: announceable,
...(announceable ? { replyMessageId: message.messageId } : {}),
...(message?._id != null ? { appendMessageIds: [message._id] } : {}),
},
);
if (savedConvo != null) {
req.resolvedConversation = savedConvo;
}
return message;
return { message, conversation: savedConvo };
}
/**
@ -243,6 +269,9 @@ async function syncMessages({
expiredAt: openai.req?.resolvedConversation?.expiredAt,
interfaceConfig: openai.req?.config?.interfaceConfig,
};
/** The assistant writes this synchronization performed. Their results decide whether a reply
* is actually in the history: a write that resolved empty must not raise an indicator. */
const assistantRecordPromises = [];
/**
*
@ -253,7 +282,11 @@ async function syncMessages({
* @param {dbMessage} params.apiMessage
*/
const processNewMessage = async ({ dbMessage, apiMessage }) => {
recordPromises.push(saveMessage(ctx, { ...dbMessage, user: openai.req.user.id }));
const recorded = saveMessage(ctx, { ...dbMessage, user: openai.req.user.id });
recordPromises.push(recorded);
if (dbMessage.role === 'assistant') {
assistantRecordPromises.push(recorded);
}
if (!apiMessage.id.includes('msg_')) {
return;
@ -358,6 +391,7 @@ async function syncMessages({
}, []);
await Promise.all(modifyPromises);
const recordedAssistantReplies = await Promise.all(assistantRecordPromises);
await Promise.all(recordPromises);
const savedConvo = await saveConvo(
@ -372,6 +406,26 @@ async function syncMessages({
openai.req.resolvedConversation = savedConvo;
}
/* Every caller that reaches here recovers assistant output the normal save path never wrote:
a cancelled run, or one that errored after the model had already produced content. The
`saveConvo` above carries no reply stamp, so without this the recovered reply would never
raise its unseen indicator. Only a write that actually persisted counts, and it is
best-effort, since those messages are already durable.
A run cancelled before any output still persists the synthetic row `checkMessageGaps`
built, and the error handlers add their visible content to the returned object rather
than to that row: stamping it would raise a dot for a message that renders nothing, and
acknowledgement requires the stamped reply to be on screen. */
const persistedAssistantReply = recordedAssistantReplies.findLast((message) => message != null);
await announceReply(
{ stampConvoLastResponse },
{
userId: openai.req.user.id,
conversationId,
reply: { ...persistedAssistantReply, isTemporary: ctx.isTemporary },
context: 'syncMessages',
},
);
return result;
}

View file

@ -94,6 +94,38 @@ describe('Assistants message retention', () => {
expect(row.isTemporary).toBe(isTemporary);
expect(row.expiredAt).toEqual(userMessage.expiredAt);
}
expect(convo.lastResponseAt != null).toBe(!isTemporary);
},
);
it('appends the saved turn IDs without reloading message history', async () => {
const user = new mongoose.Types.ObjectId().toString();
const conversationId = v4();
const req = { user: { id: user }, body: {}, config: {} };
const params = {
user,
conversationId,
endpoint: 'assistants',
assistant_id: 'asst_test',
thread_id: 'thread_test',
text: 'hello',
};
const history = jest.spyOn(Message, 'find');
try {
const userMessage = await saveUserMessage(req, { ...params, messageId: v4() });
const { message, conversation } = await saveAssistantMessage(req, {
...params,
messageId: v4(),
parentMessageId: userMessage.messageId,
content: [],
});
expect(history).not.toHaveBeenCalled();
expect(new Set(conversation.messages.map(String))).toEqual(
new Set([String(userMessage._id), String(message._id)]),
);
} finally {
history.mockRestore();
}
});
});

View file

@ -10,6 +10,10 @@ const mockSpendTokens = jest.fn().mockResolvedValue();
jest.mock('@librechat/api', () => ({
countTokens: jest.fn().mockResolvedValue(0),
/* The real predicate, because what may raise an unseen indicator is the behaviour under test
here; a stub would assert only that this file calls something. */
isAnnounceableReply: jest.requireActual('@librechat/api').isAnnounceableReply,
announceReply: jest.fn().mockResolvedValue(false),
}));
jest.mock('@librechat/data-schemas', () => ({
@ -27,7 +31,8 @@ jest.mock('~/server/services/Files/process', () => ({
retrieveAndProcessFile: jest.fn(),
}));
const { recordUsage } = require('./manage');
const { recordUsage, saveAssistantMessage } = require('./manage');
const { saveConvo, saveMessage } = require('~/models');
describe('recordUsage', () => {
beforeEach(() => {
@ -89,3 +94,59 @@ describe('recordUsage', () => {
);
});
});
describe('saveAssistantMessage', () => {
beforeEach(() => {
jest.clearAllMocks();
saveMessage.mockResolvedValue({ messageId: 'assistant-msg' });
saveConvo.mockResolvedValue({});
});
const params = {
endpoint: 'assistants',
conversationId: 'convo-123',
messageId: 'assistant-msg',
parentMessageId: 'user-msg',
text: 'done',
model: 'gpt-4',
};
it('asks saveConvo to stamp the reply at write time', async () => {
/* A precomputed stamp can be outranked by a catch-up recorded while saveConvo's own reads
are in flight, which would leave the persisted reply reading as already seen. */
await saveAssistantMessage({ user: { id: 'user-123' }, body: {} }, params);
expect(saveConvo).toHaveBeenCalledWith(
expect.objectContaining({ userId: 'user-123' }),
expect.not.objectContaining({ lastResponseAt: expect.anything() }),
expect.objectContaining({ stampReply: true }),
);
});
it.each([
['no content and no text', { ...params, text: undefined, content: undefined }],
['an empty content array', { ...params, text: undefined, content: [] }],
['whitespace-only text', { ...params, text: ' ' }],
])('does not stamp an assistant row with %s', async (_case, emptyParams) => {
/* Acknowledging a reply needs the stamped message on screen, so a row that renders nothing
would leave a dot that opening the conversation could never clear. */
await saveAssistantMessage({ user: { id: 'user-123' }, body: {} }, emptyParams);
expect(saveConvo).toHaveBeenCalledWith(
expect.anything(),
expect.anything(),
expect.objectContaining({ stampReply: false }),
);
expect(saveConvo.mock.calls[0][2]).not.toHaveProperty('replyMessageId');
});
it('never stamps a temporary conversation', async () => {
await saveAssistantMessage({ user: { id: 'user-123' }, body: { isTemporary: true } }, params);
expect(saveConvo).toHaveBeenCalledWith(
expect.anything(),
expect.anything(),
expect.objectContaining({ stampReply: false }),
);
});
});

View file

@ -177,6 +177,12 @@ class ImportBatchBuilder {
};
convo._id && delete convo._id;
delete convo.subagentThread;
/* A fork or duplicate starts its own unread history; carrying the source
conversation's catch-up state over would light a dot on a never-read copy. */
delete convo.lastResponseAt;
delete convo.lastResponseMessageId;
delete convo.lastResponseIsManual;
delete convo.lastSeenAt;
this.conversations.push(convo);
return { conversation: convo, messages: this.messages };