🗓️ fix: Refresh the Sidebar When a Scheduled Run Fires or Settles (#15631)

* 🗓️ fix: Refresh the Sidebar When a Scheduled Run Fires or Settles

An automatic occurrence is the one generation nothing in the client starts,
so no submission, stream or event handler tells the sidebar its chat exists,
and the conversation list's five-minute staleness leaves it out of a tab
that stays focused.

The schedules panel is already polling for its cards, and `lastRun` moves at
exactly the two moments the list should be re-read — a fire adds a chat, a
settlement retitles and reorders it — so read the refresh out of that poll
rather than adding one. Only transitions refresh; a schedule first seen is
recorded in silence, so a panel opened long after a run does not refetch a
list that has held its chat all along.

This also settles the row Run Now seeds: the schedule's own completion is
what replaces the schedule name with the generated title.

* 🗓️ fix: Name the Running Occurrence's Chat So the Sidebar Can Fetch It

Four review rounds each found a new way the schedule projection diverges
from the run it stands in for: `lastRun` is not written at fire, `nextRunAt`
moves before the conversation exists, and an edit mid-flight fences the
terminal write so `lastRun` never changes at settlement. Nothing on a
schedule document means "this run's chat is listable now", so every signal
read from one was too early or too late.

Stop inferring. The list handler already reads the user's schedules and
limits in parallel; read their active run rows alongside — one user-scoped
query, joined by schedule id — and project the running occurrence's
conversation id as `activeRun`. It comes from the run's own row, so the
configRevision fence on the schedule projection cannot hide it, and it is
absent until dispatch has actually reserved a conversation.

The panel hook then hands every id the list names to the same admission
watch Run Now uses, which probes until the server has the chat and adds the
server's own row: one mechanism for both paths, idempotent per id. A run
leaving the list has settled, and the list is re-read once for the order
its settlement changed.

* 🗓️ fix: Fetch Every Chat the Schedule List Names, and Scope the Run Read

Three from codex on the rebuilt design.

A run short enough to start and settle between two polls is never seen
running, and most scheduled chats are short. The list also names the chat
the last occurrence produced, so the panel now fetches every chat the list
names that it has not seen — active or settled — through the same admission
watch. The first observation still fetches only runs in flight: a panel
opened long after a run must not go and fetch history.

Project every running occurrence rather than the latest. A `requires_action`
pause does not block the next occurrence, so a schedule can hold two, and
reducing to one hid the pause's settlement. This also deletes the picker.

The single-schedule route's run read started before ownership was known and
was scoped only by schedule id. The response was gated, but a speculative
read must stay scoped to the caller: use the user-bound query the list uses
and narrow it, rather than touch rows the caller may not own.

* 🗓️ fix: Let One Layer Decide What to Watch, and Say Which Runs Are Generating

Two from codex on the previous round.

The admission watch forgets a run whose delivery outlasted its budget so a
later announcement can retry, but the panel kept its own permanent record of
every id it had handed over and never announced one twice — so that retry
could never happen. Drop the panel's record: every chat the list names is
handed to the watch on every observation, and the watch is the one place
that decides whether an id is landed, in flight, or worth trying again.

The one thing the panel still must not do is fetch history. Opening it used
to start a watch per active occurrence, and a run parked on an approval can
sit there indefinitely and accumulate, its chat listed long ago. Carry each
occurrence's status on the wire, and on the first observation treat only a
generating occurrence as in flight; a settled one and a paused one are
history, and a pause resolving later still re-reads the list.

* 🗓️ fix: Read Only Generating Runs for the List, and Hand Over Only Those

Three from codex, and this round removes more than it adds.

The list's run read returned every paused row, unbounded, on each poll.
`ScheduleRun` is indexed by status rather than by user, `requires_action`
rows accumulate for as long as their approvals wait, and `started` rows are
bounded globally by the capacity slots — so the read now asks for `started`
alone, through an optional status narrowing on the existing method. A pause
resolving is still seen through `lastRun`; what this gives up is only the
corner where that projection is fenced by a mid-flight edit.

A run that failed during initialization settles with its reserved id but
never writes a conversation, so its route answers 404 for good — and handing
settled ids to the watch meant re-probing it every poll, forever. The watch
only ever needed generating runs: a settled one is already covered by the
list re-read its settlement triggers, which brings the server's own row.

A deleted schedule leaves the list, and comparing only the schedules still
present missed the abort-and-settle that deletion performs on its run. A
schedule vanishing now counts as its state moving.

* 🗓️ fix: Compare a New Schedule Against Idle, and Bound the Landed-Run Record

Two from codex on the head GitHub replayed onto dev.

A schedule created in another tab can arrive in this client's list with its
first run already settled, and a comparison that walks only the schedules
seen before never looked at it. Compare a newcomer against the idle state:
one that arrives with a run behind it is news the list should hear, one
that arrives with no run yet is not.

The watch remembers every run it landed so a later announcement is a no-op,
and a panel that stays mounted sees a new id per occurrence for as long as
schedules keep firing. Keep the most recent 256: a run is announced only
while in flight, and none is still in flight by the time that many have
started after it, so the oldest can go without a watch ever running twice.

* 🗓️ fix: Re-read on First Sight Only When a Run Outran the Sidebar, and Never Evict a Live Watch

Two from codex.

"The first observation is silent" assumed the sidebar's lists had been read
after any run they should hold, and that is not guaranteed: open the panel
after a run fired and finished with it closed, and the card says the run
succeeded while the sidebar was read before it ever fired. The first
observation has no earlier one to compare against, so compare against the
sidebar instead — re-read only if some run fired after the lists were last
read, which is precisely the case where they lack its chat, and stay silent
otherwise.

The landed-run cap assumed fewer than 256 generations could be in flight at
once, and the config schema bounds neither maxPerUser nor fireConcurrency.
Keep in-flight watches in their own set, bounded by real concurrency and
never evicted — a second watch for a run still being watched is the one
thing that set exists to prevent — and cap only the landed record, where a
forgotten id costs at most one extra probe.

* 🗓️ fix: Re-read on First Sight When Anything Has Run, Release Runs the List Drops, Observe Every Poll

Three from codex, each a defect in an earlier fix, and each answered by
removing something.

Comparing a run's fire time against the list cache's `dataUpdatedAt` was
measuring cache writes, not server reads: a foreground chat inserted after
the run advanced the stamp without adding the scheduled chat. There is no
timestamp for "last read from the server", so stop guessing — the first
observation re-reads if any schedule has run at all, and one refetch on
opening the panel is the honest price.

A run can be landed and still generating for minutes, announced on every
poll; a count cap evicted it and restarted its probes. The hook is the one
place that sees an occurrence leave the list, so it releases the id then,
and the watch remembers a run exactly as long as something can announce it.
No cap.

React Query hands back the same array for a deep-equal poll, so an effect
keyed on the data never ran again while a run stayed in flight — and a watch
that gave up was never asked to try again. Key on the poll's timestamp.

* fix: Release Scheduled Run Retention Across Admission and Unmount 🧹
This commit is contained in:
Danny Avila 2026-09-06 15:28:11 -04:00 • committed by GitHub
parent f1a21764f3
commit deda142d58
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 767 additions and 28 deletions

View file

@ -10,10 +10,14 @@ import { useSchedulesQuery } from '~/data-provider';
import { useLocalize, useHasAccess } from '~/hooks';
import ScheduleDialog from './ScheduleDialog';
import ScheduleCard from './ScheduleCard';
import useRunSync from './useRunSync';
export default function SchedulePanel() {
const localize = useLocalize();
const { data, isLoading, isError, refetch } = useSchedulesQuery();
const { data, dataUpdatedAt, isLoading, isError, refetch } = useSchedulesQuery();
/** The cards refresh themselves from this query; the sidebar cannot, so the
* chat a run just produced is read out of the same poll. */
useRunSync(data?.schedules, dataUpdatedAt);
const [createOpen, setCreateOpen] = useState(false);
const hasCreateAccess = useHasAccess({

View file

@ -0,0 +1,382 @@
import React from 'react';
import { QueryKeys } from 'librechat-data-provider';
import { act, renderHook } from '@testing-library/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import type { TSchedule, TConversation } from 'librechat-data-provider';
import type { ReactNode } from 'react';
import { resetTrackedRuns, trackedRunCount } from '~/data-provider/Schedules/admission';
import useRunSync from '../useRunSync';
const mockGetConversationById = jest.fn<Promise<TConversation>, [string]>();
jest.mock('librechat-data-provider', () => {
const actual = jest.requireActual('librechat-data-provider');
return {
...actual,
dataService: {
...actual.dataService,
getConversationById: (id: string) => mockGetConversationById(id),
},
};
});
const schedule: TSchedule = {
id: 'schedule-1',
user: 'user-1',
name: 'Morning briefing',
prompt: 'Summarize overnight activity',
agent_id: 'agent-1',
cadence: { frequency: 'daily', hour: 9, minute: 0 },
timezone: 'UTC',
target: 'new',
enabled: true,
runCount: 0,
failureCount: 0,
nextRunAt: '2026-09-05T09:00:00.000Z',
createdAt: '2026-09-01T00:00:00.000Z',
updatedAt: '2026-09-01T00:00:00.000Z',
};
/** The list naming the chat a running occurrence is producing. */
const running = (conversationId = 'run-convo-1', overrides?: Partial<TSchedule>): TSchedule => ({
...schedule,
inFlight: [{ conversationId }],
...overrides,
});
/** The list after a run settled — the only trace a run short enough to start and
* finish between two polls ever leaves. */
const settled = (conversationId = 'run-convo-1', overrides?: Partial<TSchedule>): TSchedule => ({
...schedule,
lastRun: { conversationId, status: 'success', firedAt: '2026-09-05T09:00:00.000Z' },
...overrides,
});
const serverConversation = (conversationId = 'run-convo-1'): TConversation =>
({
conversationId,
title: 'Overnight activity summary',
endpoint: 'agents',
agent_id: 'agent-1',
createdAt: '2026-09-05T09:00:01.000Z',
updatedAt: '2026-09-05T09:00:01.000Z',
}) as TConversation;
const listKey = [QueryKeys.allConversations];
function createQueryClient() {
const queryClient = new QueryClient({
defaultOptions: { queries: { retry: false, cacheTime: Infinity } },
});
queryClient.setQueryData([QueryKeys.user], { id: 'user-1' });
queryClient.setQueryData(listKey, {
pages: [{ conversations: [{ conversationId: 'existing' } as TConversation], nextCursor: null }],
pageParams: [],
});
return queryClient;
}
const createWrapper = (queryClient: QueryClient) =>
function Wrapper({ children }: { children: ReactNode }) {
return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
};
const listIds = (queryClient: QueryClient) =>
(
queryClient.getQueryData<{ pages: Array<{ conversations: TConversation[] }> }>(listKey)
?.pages[0].conversations ?? []
).map((convo) => convo.conversationId);
const isStale = (queryClient: QueryClient) =>
queryClient.getQueryState(listKey)?.isInvalidated === true;
/** Every render is a fresh poll observation, the way the panel feeds the hook —
* including one whose data is the same reference as the last. */
let observation = 0;
const renderWith = (queryClient: QueryClient, initial?: TSchedule[]) =>
renderHook((schedules?: TSchedule[]) => useRunSync(schedules, (observation += 1)), {
wrapper: createWrapper(queryClient),
initialProps: initial,
});
/** Lets the admission watch reach its first probe. */
const admit = async () => {
await act(async () => {
await jest.advanceTimersByTimeAsync(3_000);
});
};
describe('useRunSync', () => {
beforeEach(() => {
jest.resetAllMocks();
jest.useFakeTimers();
resetTrackedRuns();
mockGetConversationById.mockResolvedValue(serverConversation());
});
afterEach(() => {
jest.useRealTimers();
});
it('puts a running occurrence’s chat in the sidebar', async () => {
const queryClient = createQueryClient();
renderWith(queryClient, [running()]);
await admit();
expect(listIds(queryClient)).toEqual(['run-convo-1', 'existing']);
queryClient.clear();
});
it('watches a run once, however many polls list it', async () => {
const queryClient = createQueryClient();
const { rerender } = renderWith(queryClient, [running()]);
rerender([running()]);
rerender([running()]);
await admit();
expect(mockGetConversationById).toHaveBeenCalledTimes(1);
queryClient.clear();
});
it('re-reads the list when the run settles, so the chat takes its final order', async () => {
const queryClient = createQueryClient();
const { rerender } = renderWith(queryClient, [running()]);
await admit();
expect(isStale(queryClient)).toBe(false);
rerender([schedule]);
expect(isStale(queryClient)).toBe(true);
queryClient.clear();
});
it('sees a settlement through an edit made while the run was in flight', async () => {
const queryClient = createQueryClient();
const { rerender } = renderWith(queryClient, [running()]);
await admit();
/** The edit bumps configRevision, which fences the schedule's own `lastRun`
* projection; the run row is what this reads, and it is gone regardless. */
rerender([running('run-convo-1', { name: 'Renamed', configRevision: 2 })]);
expect(isStale(queryClient)).toBe(false);
rerender([{ ...schedule, name: 'Renamed', configRevision: 2 }]);
expect(isStale(queryClient)).toBe(true);
queryClient.clear();
});
it('re-reads the list for a run that started and settled between two polls', async () => {
const queryClient = createQueryClient();
const { rerender } = renderWith(queryClient, [schedule]);
rerender([settled()]);
await admit();
/** Never seen generating, so never handed to the watch — the refetch brings the
* server's own row, and a settled run whose generation never wrote a chat
* (a 404 for good) is not probed at all, let alone again. */
expect(isStale(queryClient)).toBe(true);
expect(mockGetConversationById).not.toHaveBeenCalled();
queryClient.clear();
});
it('fetches every generating occurrence a schedule names', async () => {
const queryClient = createQueryClient();
mockGetConversationById.mockImplementation(async (id) => serverConversation(id));
renderWith(queryClient, [
running('run-convo-1', {
inFlight: [{ conversationId: 'run-convo-1' }, { conversationId: 'run-convo-2' }],
}),
]);
await admit();
expect(listIds(queryClient)).toEqual(
expect.arrayContaining(['run-convo-1', 'run-convo-2', 'existing']),
);
queryClient.clear();
});
it('re-reads the list when a schedule with a run is deleted from under it', async () => {
const queryClient = createQueryClient();
const { rerender } = renderWith(queryClient, [running(), { ...schedule, id: 'schedule-2' }]);
await admit();
expect(isStale(queryClient)).toBe(false);
/** Deleting aborts and settles the run, and the schedule leaves the list; the
* chat's final state is only visible if the vanishing counts as a move. */
rerender([{ ...schedule, id: 'schedule-2' }]);
expect(isStale(queryClient)).toBe(true);
queryClient.clear();
});
it('announces a run again once its watch has given up', async () => {
const queryClient = createQueryClient();
mockGetConversationById.mockRejectedValue(
Object.assign(new Error('Not Found'), { isAxiosError: true, response: { status: 404 } }),
);
const { rerender } = renderWith(queryClient, [schedule]);
rerender([running()]);
/** Deferred past the whole budget: the watch forgets the id so a later
* announcement can try again — which is only useful if this hook makes one. */
await act(async () => {
await jest.advanceTimersByTimeAsync(600_000);
});
expect(listIds(queryClient)).toEqual(['existing']);
mockGetConversationById.mockResolvedValue(serverConversation());
rerender([running()]);
await admit();
expect(listIds(queryClient)).toEqual(['run-convo-1', 'existing']);
queryClient.clear();
});
it('re-reads the list when a schedule created elsewhere arrives already settled', async () => {
const queryClient = createQueryClient();
const { rerender } = renderWith(queryClient, [schedule]);
/** Made in another tab, fired, and finished — all before this poll first
* listed it. There is no earlier state to compare against; idle is the
* baseline, and this is not idle. */
rerender([schedule, { ...settled('elsewhere-convo'), id: 'schedule-2' }]);
expect(isStale(queryClient)).toBe(true);
expect(mockGetConversationById).not.toHaveBeenCalled();
queryClient.clear();
});
it('leaves the list alone when a schedule created elsewhere arrives idle', () => {
const queryClient = createQueryClient();
const { rerender } = renderWith(queryClient, [schedule]);
rerender([schedule, { ...schedule, id: 'schedule-2' }]);
expect(isStale(queryClient)).toBe(false);
queryClient.clear();
});
it('re-reads on the first observation when any schedule has run', async () => {
const queryClient = createQueryClient();
/** The sidebar may have been read before that run and nothing here can tell;
* one refetch on opening the panel is the price. Nothing is probed. */
renderWith(queryClient, [settled()]);
await admit();
expect(isStale(queryClient)).toBe(true);
expect(mockGetConversationById).not.toHaveBeenCalled();
queryClient.clear();
});
it('records the first observation in silence when nothing has ever run', async () => {
const queryClient = createQueryClient();
renderWith(queryClient, [schedule, { ...schedule, id: 'schedule-2' }]);
await admit();
expect(isStale(queryClient)).toBe(false);
expect(mockGetConversationById).not.toHaveBeenCalled();
queryClient.clear();
});
it('announces again on a poll whose data is the same reference', async () => {
const queryClient = createQueryClient();
mockGetConversationById.mockRejectedValue(
Object.assign(new Error('Not Found'), { isAxiosError: true, response: { status: 404 } }),
);
const list = [running()];
const { rerender } = renderWith(queryClient, list);
await act(async () => {
await jest.advanceTimersByTimeAsync(600_000);
});
expect(listIds(queryClient)).toEqual(['existing']);
/** Deep-equal refetch: React Query hands back the same array. Only the
* observation stamp moves, and that has to be enough to ask again. */
mockGetConversationById.mockResolvedValue(serverConversation());
rerender(list);
await admit();
expect(listIds(queryClient)).toEqual(['run-convo-1', 'existing']);
queryClient.clear();
});
it('releases a run once it leaves the list, so nothing is remembered for it', async () => {
const queryClient = createQueryClient();
const { rerender } = renderWith(queryClient, [running()]);
await admit();
expect(trackedRunCount()).toBe(1);
rerender([settled()]);
expect(trackedRunCount()).toBe(0);
queryClient.clear();
});
it('does not retain a run released before admission finishes', async () => {
const queryClient = createQueryClient();
const { rerender } = renderWith(queryClient, [running()]);
rerender([settled()]);
await admit();
expect(listIds(queryClient)).toContain('run-convo-1');
expect(trackedRunCount()).toBe(0);
queryClient.clear();
});
it.each([false, true])('releases on unmount with admission finished: %s', async (finished) => {
const queryClient = createQueryClient();
const { unmount } = renderWith(queryClient, [running()]);
if (finished) {
await admit();
}
unmount();
await admit();
expect(listIds(queryClient)).toContain('run-convo-1');
expect(trackedRunCount()).toBe(0);
expect(mockGetConversationById).toHaveBeenCalledTimes(1);
queryClient.clear();
});
it('reclaims a pending watch on remount without a duplicate probe', async () => {
const queryClient = createQueryClient();
const first = renderWith(queryClient, [running()]);
first.unmount();
const second = renderWith(queryClient, [running()]);
await admit();
expect(trackedRunCount()).toBe(1);
expect(mockGetConversationById).toHaveBeenCalledTimes(1);
second.unmount();
expect(trackedRunCount()).toBe(0);
queryClient.clear();
});
it('leaves the list alone when nothing about a run moved', async () => {
const queryClient = createQueryClient();
const { rerender } = renderWith(queryClient, [schedule]);
rerender([
{ ...schedule, name: 'Renamed', enabled: false, nextRunAt: '2026-09-06T09:00:00.000Z' },
]);
expect(isStale(queryClient)).toBe(false);
queryClient.clear();
});
it('waits for data before recording anything', () => {
const queryClient = createQueryClient();
const { rerender } = renderWith(queryClient, undefined);
rerender([schedule]);
expect(isStale(queryClient)).toBe(false);
queryClient.clear();
});
});

View file

@ -0,0 +1,101 @@
import { useRef, useEffect } from 'react';
import { QueryKeys } from 'librechat-data-provider';
import { useQueryClient } from '@tanstack/react-query';
import type { TSchedule } from 'librechat-data-provider';
import { trackScheduledRun, releaseScheduledRun } from '~/data-provider/Schedules/admission';
type Occurrences = Pick<TSchedule, 'inFlight' | 'lastRun'>;
const inFlightChats = (schedule: Pick<TSchedule, 'inFlight'>): string[] =>
(schedule.inFlight ?? []).map((run) => run.conversationId);
/** Everything about a schedule's occurrences that should send the list back to
* the server when it moves: which runs are generating, and how the last one
* ended. A run short enough to start and settle between two polls is never seen
* generating; it is still seen settled, and the refetch that follows brings its
* chat with the server's own row. */
const runState = (schedule: Occurrences): string => {
const { lastRun } = schedule;
const live = inFlightChats(schedule).sort().join(',');
return `${live}|${lastRun?.conversationId ?? ''}:${lastRun?.status ?? ''}`;
};
/** A schedule that has never run. What a schedule this client has not seen before
* is compared against — and, on the first observation, what every schedule is. */
const IDLE_STATE = runState({});
/**
* Puts an automatic occurrence's chat in the sidebar, the same way Run Now does.
*
* An automatic occurrence is the one generation nothing in this client starts, so
* no submission, stream or event handler ever tells the sidebar its chat exists —
* and the list's own five-minute staleness leaves it out of a tab that stays
* focused. This panel's query is already polling for the cards, and it names the
* chat each generating occurrence is producing, read from the run's own row rather
* than inferred from the schedule. Every one is handed to the admission watch Run
* Now uses, on every observation: that watch is the one place that decides whether
* an id is landed, in flight, or — having given up on a delivery deferred past its
* budget — worth trying again. When an occurrence leaves the list it is released,
* so the watch remembers a run only for as long as this keeps announcing it.
*
* `observedAt` is what makes "every observation" true. React Query keeps the
* previous reference when a refetch is deep-equal, which is exactly what a poll
* returns while a run stays in flight, so an effect keyed on the data alone would
* never run again — and a watch that gave up would never be asked to try again.
*
* When a run's state moves — one settles, its schedule is deleted from under it,
* or a schedule created elsewhere arrives with a run already behind it — the list
* is re-read once for the chat, order and title the settlement changed. Because
* the state includes the generating occurrences, an owner editing the schedule
* mid-flight (which fences the `lastRun` projection) still cannot hide a
* settlement. The first observation has nothing earlier to compare against, so it
* re-reads if any schedule has run at all: the sidebar may have been read before
* that run, and nothing here can tell — one refetch on opening the panel is the
* honest price of that.
*/
export default function useRunSync(schedules?: TSchedule[], observedAt?: number): void {
const queryClient = useQueryClient();
const states = useRef<Map<string, string> | null>(null);
const announced = useRef<Set<string>>(new Set());
useEffect(
() => () => {
for (const conversationId of announced.current) {
releaseScheduledRun(conversationId);
}
announced.current.clear();
},
[],
);
useEffect(() => {
if (schedules == null) {
return;
}
const previous = states.current;
const current = new Map<string, string>();
const live = new Set<string>();
for (const schedule of schedules) {
current.set(schedule.id, runState(schedule));
for (const conversationId of inFlightChats(schedule)) {
live.add(conversationId);
void trackScheduledRun(queryClient, conversationId, { retain: true });
}
}
for (const conversationId of announced.current) {
if (!live.has(conversationId)) {
releaseScheduledRun(conversationId);
}
}
announced.current = live;
states.current = current;
const moved =
previous == null
? [...current.values()].some((state) => state !== IDLE_STATE)
: [...previous].some(([id, state]) => current.get(id) !== state) ||
[...current].some(([id, state]) => !previous.has(id) && state !== IDLE_STATE);
if (moved) {
queryClient.invalidateQueries([QueryKeys.allConversations]);
}
}, [schedules, observedAt, queryClient]);
}

View file

@ -49,16 +49,41 @@ const cacheOwner = (queryClient: QueryClient): string | undefined =>
queryClient.getQueryData<TUser>([QueryKeys.user])?.id;
/**
* Runs with a watch in flight or already landed. A run can be announced twice —
* by the click that started it, and by the schedules poll that then lists it —
* and must be watched once. A watch that gave up is forgotten, so a later
* announcement of a run admitted after the budget can try again.
* Runs with a watch in flight. A run can be announced twice — by the click that
* started it, and by the schedules poll that then lists it — and must be watched
* once. Bounded by however many generations can actually be running, and never
* evicted: a second watch for a run still being watched is the one thing this
* exists to prevent.
*/
const tracked = new Set<string>();
const watching = new Map<string, { retain: boolean }>();
/** @internal Test seam. */
/**
* Runs already landed, so a later announcement is a no-op. A run is announced for
* as long as it is generating, and the announcer releases it when it stops — so
* this holds an id exactly as long as something could announce it, and is bounded
* by real concurrency rather than by a count that could evict a run still being
* announced. A watch that gave up is in neither set, so a later announcement of a
* run admitted after the budget can try again.
*/
const landed = new Set<string>();
/** @internal Test seams. */
export function resetTrackedRuns(): void {
tracked.clear();
watching.clear();
landed.clear();
}
export function trackedRunCount(): number {
return watching.size + landed.size;
}
/** The announcer no longer names this run — it settled, or its schedule went —
* so nothing can announce it again, and there is nothing left to remember. */
export function releaseScheduledRun(conversationId: string): void {
landed.delete(conversationId);
const watch = watching.get(conversationId);
if (watch) {
watch.retain = false;
}
}
/**
@ -149,6 +174,9 @@ async function admit(queryClient: QueryClient, conversationId: string): Promise<
* a 200 means the chat is listable now, and carries the server's own row rather
* than a guess assembled from the client's cached schedule.
*
* `retain` is for a polling owner that will release the id when it stops naming
* it. One-shot Run Now calls leave no retained id after admission finishes.
*
* Deliberately detached from the caller: the sidebar has to gain the chat whether
* or not the panel the run was announced in is still mounted. Bounded, and it
* writes only what the server returned — a delivery that never admits leaves
@ -157,13 +185,23 @@ async function admit(queryClient: QueryClient, conversationId: string): Promise<
export async function trackScheduledRun(
queryClient: QueryClient,
conversationId: string,
{ retain = false }: { retain?: boolean } = {},
): Promise<void> {
if (!conversationId || tracked.has(conversationId)) {
const existing = watching.get(conversationId);
if (existing && retain) {
existing.retain = true;
}
if (!conversationId || existing || landed.has(conversationId)) {
return;
}
tracked.add(conversationId);
const landed = await admit(queryClient, conversationId);
if (!landed) {
tracked.delete(conversationId);
const watch = { retain };
watching.set(conversationId, watch);
try {
const admitted = await admit(queryClient, conversationId);
if (admitted && watch.retain) {
landed.add(conversationId);
}
} finally {
watching.delete(conversationId);
}
}

View file

@ -5,13 +5,18 @@ import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import type { TConversation, TScheduleRunNowResponse } from 'librechat-data-provider';
import type { InfiniteData } from '@tanstack/react-query';
import type { ReactNode } from 'react';
import {
resetTrackedRuns,
trackScheduledRun,
trackedRunCount,
releaseScheduledRun,
} from '../Schedules/admission';
import {
ACTIVE_JOBS_POLL_MS,
resetActiveJobsGrace,
getActiveJobsRefetchInterval,
} from '../SSE/queries';
import { useRunScheduleNowMutation } from '../Schedules/mutations';
import { resetTrackedRuns } from '../Schedules/admission';
import * as sseQueries from '../SSE/queries';
const mockRunScheduleNow = jest.fn<Promise<TScheduleRunNowResponse>, [string]>();
@ -381,6 +386,43 @@ describe('run-now conversation tracking', () => {
queryClient.clear();
});
it('does not retain a one-shot admission without a polling owner', async () => {
const queryClient = createQueryClient();
signIn(queryClient, 'user-a');
seedList(queryClient);
mockGetConversationById.mockResolvedValue(serverConversation());
void trackScheduledRun(queryClient, 'run-convo-1');
await settleAdmission();
expect(readList(queryClient).some((c) => c.conversationId === 'run-convo-1')).toBe(true);
expect(trackedRunCount()).toBe(0);
queryClient.clear();
});
it('remembers a landed run until it is released, then probes it again if announced', async () => {
const queryClient = createQueryClient();
signIn(queryClient, 'user-a');
seedList(queryClient);
mockGetConversationById.mockResolvedValue(serverConversation());
void trackScheduledRun(queryClient, 'run-convo-1', { retain: true });
await settleAdmission();
void trackScheduledRun(queryClient, 'run-convo-1', { retain: true });
await settleAdmission();
expect(mockGetConversationById).toHaveBeenCalledTimes(1);
expect(trackedRunCount()).toBe(1);
releaseScheduledRun('run-convo-1');
expect(trackedRunCount()).toBe(0);
void trackScheduledRun(queryClient, 'run-convo-1', { retain: true });
await settleAdmission();
expect(mockGetConversationById).toHaveBeenCalledTimes(2);
expect(readList(queryClient).filter((c) => c.conversationId === 'run-convo-1')).toHaveLength(1);
queryClient.clear();
});
it('refuses the write when the cache is claimed while the owner is still unknown', async () => {
const queryClient = createQueryClient();
seedList(queryClient);

View file

@ -1,5 +1,5 @@
import { createHash } from 'node:crypto';
import type { ISchedule } from '@librechat/data-schemas';
import type { ISchedule, IScheduleRun } from '@librechat/data-schemas';
import type { Response } from 'express';
import type { SchedulesHandlersDeps } from './handlers';
import type { ServerRequest } from '~/types';
@ -154,6 +154,8 @@ function makeCreateDeps(over: Partial<SchedulesHandlersDeps> = {}): SchedulesHan
markScheduleDeleting: jest.fn(async () => ({ id: 'sched-1' }) as ISchedule),
updateScheduleById: jest.fn(async () => ({ id: 'sched-1' }) as ISchedule),
armSchedule: jest.fn(async () => undefined),
getActiveRunsForUser: jest.fn(async () => []),
getActiveRunsForSchedule: jest.fn(async () => []),
};
return {
methods: methods as unknown as SchedulesHandlersDeps['methods'],
@ -737,6 +739,80 @@ describe('deferred deletion retry', () => {
});
});
describe('in-flight run projection', () => {
const schedule = { id: 'sched-1', user: 'user-1', name: 'Digest' } as unknown as ISchedule;
const run = (over: Partial<IScheduleRun>): IScheduleRun =>
({
scheduleId: 'sched-1',
user: 'user-1',
scheduledFor: new Date('2026-09-06T09:00:00Z'),
status: 'started',
...over,
}) as unknown as IScheduleRun;
type Wire = { inFlight?: Array<{ conversationId: string }> };
async function listWith(runs: IScheduleRun[], schedules: ISchedule[] = [schedule]) {
const deps = makeCreateDeps();
(deps.methods.getSchedulesByUser as jest.Mock) = jest.fn(async () => schedules);
(deps.methods.getActiveRunsForUser as jest.Mock) = jest.fn(async () => runs);
(deps.methods.getDeletingScheduleIds as jest.Mock) = jest.fn(async () => []);
const { res, captured } = makeRes();
await createSchedulesHandlers(deps).listSchedules(
{ user: { id: 'user-1' } } as unknown as ServerRequest,
res,
);
return { deps, schedules: (captured.body as { schedules: Wire[] }).schedules };
}
it('names the chat a generating occurrence is producing', async () => {
const { schedules } = await listWith([run({ conversationId: 'convo-1' })]);
expect(schedules[0].inFlight).toEqual([{ conversationId: 'convo-1' }]);
});
it('asks only for generating occurrences, never the parked ones', async () => {
// Indexed by status rather than user, and `requires_action` rows accumulate for
// as long as approvals wait; `started` rows are bounded by the capacity slots.
const { deps } = await listWith([]);
expect(deps.methods.getActiveRunsForUser).toHaveBeenCalledWith('user-1', ['started']);
});
it('projects nothing for a reservation that has not been dispatched', async () => {
const { schedules } = await listWith([run({})]);
expect(schedules[0].inFlight).toBeUndefined();
});
it('projects nothing when no occurrence is generating', async () => {
const { schedules } = await listWith([]);
expect(schedules[0].inFlight).toBeUndefined();
});
it('files each occurrence under its own schedule', async () => {
const { schedules } = await listWith(
[run({ conversationId: 'convo-2', scheduleId: 'sched-2' })],
[schedule, { ...schedule, id: 'sched-2' }],
);
expect(schedules[0].inFlight).toBeUndefined();
expect(schedules[1].inFlight).toEqual([{ conversationId: 'convo-2' }]);
});
it('scopes the single-schedule read to the caller before ownership is known', async () => {
const deps = makeCreateDeps();
(deps.methods.getScheduleById as jest.Mock) = jest.fn(async () => schedule);
(deps.methods.getActiveRunsForUser as jest.Mock) = jest.fn(async () => [
run({ conversationId: 'mine' }),
run({ conversationId: 'other-schedule', scheduleId: 'sched-9' }),
]);
const { res, captured } = makeRes();
await createSchedulesHandlers(deps).getSchedule(
{ params: { id: 'sched-1' }, user: { id: 'user-1' } } as unknown as ServerRequest,
res,
);
expect(deps.methods.getActiveRunsForUser).toHaveBeenCalledWith('user-1', ['started']);
expect(deps.methods.getActiveRunsForSchedule).not.toHaveBeenCalled();
expect((captured.body as Wire).inFlight).toEqual([{ conversationId: 'mine' }]);
});
});
describe('deleteSchedule result mapping', () => {
function makeDeleteReq(): ServerRequest {
return {

View file

@ -6,7 +6,7 @@ import {
isCronCadence,
} from 'librechat-data-provider';
import type { TScheduleCadence, TCreateSchedule, TUpdateSchedule } from 'librechat-data-provider';
import type { ScheduleMethods, ISchedule } from '@librechat/data-schemas';
import type { ScheduleMethods, ISchedule, IScheduleRun } from '@librechat/data-schemas';
import type { Response } from 'express';
import type {
ScheduleDeleteResult,
@ -239,7 +239,42 @@ export type WireSchedule = Pick<
| 'configRevision'
| 'createdAt'
| 'updatedAt'
>;
> & {
/** See `TSchedule.inFlight`: the generating occurrences, from their own run rows. */
inFlight?: Array<{ conversationId: string }>;
};
/** Only generating occurrences are read for the list. `ScheduleRun` is indexed by
* status, not by user, and `started` rows are bounded globally by the capacity
* slots; `requires_action` rows accumulate for as long as their approvals wait. */
export const LISTED_RUN_STATUSES: readonly IScheduleRun['status'][] = ['started'];
/**
* The chats a schedule's generating occurrences are producing. A reservation that
* has not been dispatched yet carries no conversation id, and there is nothing to
* look for until it does.
*/
export function toWireInFlight(
runs: readonly IScheduleRun[],
): Array<{ conversationId: string }> | undefined {
const chats = runs.flatMap((run) =>
run.conversationId != null ? [{ conversationId: run.conversationId }] : [],
);
return chats.length > 0 ? chats : undefined;
}
function inFlightBySchedule(runs: readonly IScheduleRun[]): Map<string, IScheduleRun[]> {
const grouped = new Map<string, IScheduleRun[]>();
for (const run of runs) {
const list = grouped.get(run.scheduleId);
if (list) {
list.push(run);
} else {
grouped.set(run.scheduleId, [run]);
}
}
return grouped;
}
/**
* Public projection. `limits` is optional only for callers that have none to hand;
@ -251,6 +286,7 @@ export type WireSchedule = Pick<
export function toWireSchedule(
schedule: ISchedule,
limits?: Pick<ScheduleLimits, 'projectId'>,
inFlight: readonly IScheduleRun[] = [],
): WireSchedule {
return {
id: schedule.id,
@ -272,6 +308,7 @@ export function toWireSchedule(
configRevision: schedule.configRevision,
createdAt: schedule.createdAt,
updatedAt: schedule.updatedAt,
...(inFlight.length > 0 && { inFlight: toWireInFlight(inFlight) }),
};
}
@ -477,13 +514,21 @@ export function createSchedulesHandlers(deps: SchedulesHandlersDeps): SchedulesH
}
async function listSchedules(req: ServerRequest, res: Response): Promise<void> {
const [schedules, limits] = await Promise.all([
deps.methods.getSchedulesByUser(requestUser(req).id),
deps.getLimits(requestUser(req)),
const user = requestUser(req);
// Three independent, user-scoped reads; the generating runs ride alongside so
// the list can name the chat each one is producing without a second round trip
// per card.
const [schedules, limits, inFlight] = await Promise.all([
deps.methods.getSchedulesByUser(user.id),
deps.getLimits(user),
deps.methods.getActiveRunsForUser(user.id, LISTED_RUN_STATUSES),
]);
retryDeferredDeletions(requestUser(req).id);
const inFlightBySchedule_ = inFlightBySchedule(inFlight);
retryDeferredDeletions(user.id);
res.json({
schedules: schedules.map((schedule) => toWireSchedule(schedule, limits)),
schedules: schedules.map((schedule) =>
toWireSchedule(schedule, limits, inFlightBySchedule_.get(schedule.id)),
),
limits: {
maxPerUser: limits.maxPerUser,
// minIntervalMinutes ships with the list so the dialog can refuse a cadence
@ -498,15 +543,25 @@ export function createSchedulesHandlers(deps: SchedulesHandlersDeps): SchedulesH
async function getSchedule(req: ServerRequest, res: Response): Promise<void> {
const { id } = req.params as { id: string };
const user = requestUser(req);
const [schedule, limits] = await Promise.all([
// The run read starts before ownership is established, so it is scoped to the
// caller — the same user-bound query the list uses — and narrowed here, rather
// than a by-schedule read that would touch rows the caller may not own.
const [schedule, limits, inFlight] = await Promise.all([
deps.methods.getScheduleById(id, user.id),
deps.getLimits(user),
deps.methods.getActiveRunsForUser(user.id, LISTED_RUN_STATUSES),
]);
if (schedule == null) {
res.status(404).json({ error: 'Schedule not found' });
return;
}
res.json(toWireSchedule(schedule, limits));
res.json(
toWireSchedule(
schedule,
limits,
inFlight.filter((run) => run.scheduleId === id),
),
);
}
async function createSchedule(req: ServerRequest, res: Response): Promise<void> {

View file

@ -135,6 +135,15 @@ export type TSchedule = {
disabledReason?: ScheduleDisabledReason;
nextRunAt?: string;
lastRun?: TScheduleLastRun;
/**
* The occurrences generating right now. Read from their own run rows, not from
* `lastRun`, which is projected only when a run settles, pauses or skips and is
* deliberately withheld from a run whose schedule was edited mid-flight. This is
* the signal a client has that a chat is on its way, and the id to fetch it by.
* A run parked on an approval is not here: its chat was listed long ago, and the
* rows can accumulate for as long as approvals wait.
*/
inFlight?: Array<{ conversationId: string }>;
runCount: number;
failureCount: number;
configRevision?: number;

View file

@ -228,6 +228,26 @@ describe('getScheduleRunProject (occurrence scope, recorded vs unknown)', () =>
* if that ever stopped holding, a deliberately unscoped run would silently start
* being validated against the schedule's current project instead.
*/
it("narrows the user's in-flight runs to the statuses asked for", async () => {
const schedule = await methods.createSchedule(scheduleData());
const generating = new Date('2026-07-22T12:00:00Z');
const paused = new Date('2026-07-23T12:00:00Z');
await methods.reserveStartedRun(runData(schedule, { scheduledFor: paused }));
await methods.recordRunOutcome({
scheduleId: schedule.id,
scheduledFor: paused,
status: 'requires_action',
autoDisableAfterFailures: 5,
});
await methods.reserveStartedRun(runData(schedule, { scheduledFor: generating }));
const all = await methods.getActiveRunsForUser(schedule.user);
const started = await methods.getActiveRunsForUser(schedule.user, ['started']);
expect(all.map((run) => run.status).sort()).toEqual(['requires_action', 'started']);
expect(started.map((run) => run.scheduledFor)).toEqual([generating]);
});
it('reports a recorded null apart from a field that was never written', async () => {
const schedule = await methods.createSchedule(scheduleData());
const scoped = new Date('2026-07-20T12:00:00Z');

View file

@ -289,7 +289,10 @@ export type ScheduleMethods = {
) => Promise<void>;
markScheduleDeleting: (id: string, userId: string | Types.ObjectId) => Promise<ISchedule | null>;
getActiveRunsForSchedule: (scheduleId: string) => Promise<IScheduleRun[]>;
getActiveRunsForUser: (userId: string | Types.ObjectId) => Promise<IScheduleRun[]>;
getActiveRunsForUser: (
userId: string | Types.ObjectId,
statuses?: readonly ScheduleRunStatus[],
) => Promise<IScheduleRun[]>;
suspendUserSchedulesForDeletion: (
userId: string | Types.ObjectId,
token: string,
@ -1756,10 +1759,19 @@ export function createScheduleMethods(mongoose: typeof import('mongoose')): Sche
.lean<IScheduleRun[]>();
}
/** In-flight runs across all of a user's schedules — for account-deletion quiescing. */
async function getActiveRunsForUser(userId: string | Types.ObjectId): Promise<IScheduleRun[]> {
/**
* In-flight runs across all of a user's schedules — for account-deletion quiescing,
* and, narrowed to `started`, for the schedules list. The narrowing matters there:
* this collection is indexed by status, not by user, and `started` rows are bounded
* globally by the capacity slots while `requires_action` rows can accumulate for as
* long as an approval waits.
*/
async function getActiveRunsForUser(
userId: string | Types.ObjectId,
statuses: readonly ScheduleRunStatus[] = ACTIVE_RUN_STATUSES,
): Promise<IScheduleRun[]> {
return ScheduleRun()
.find({ user: userId, status: { $in: ACTIVE_RUN_STATUSES } })
.find({ user: userId, status: { $in: statuses } })
.lean<IScheduleRun[]>();
}