From deda142d58cfbd55b6d358cfb5f950d1a0b10061 Mon Sep 17 00:00:00 2001 From: Danny Avila Date: Sun, 6 Sep 2026 15:28:11 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=97=93=EF=B8=8F=20fix:=20Refresh=20the=20?= =?UTF-8?q?Sidebar=20When=20a=20Scheduled=20Run=20Fires=20or=20Settles=20(?= =?UTF-8?q?#15631)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * πŸ—“οΈ 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 🧹 --- .../SidePanel/Schedules/SchedulePanel.tsx | 6 +- .../Schedules/__tests__/useRunSync.spec.tsx | 382 ++++++++++++++++++ .../SidePanel/Schedules/useRunSync.ts | 101 +++++ .../src/data-provider/Schedules/admission.ts | 62 ++- .../__tests__/scheduleRunNow.test.tsx | 44 +- packages/api/src/schedules/handlers.spec.ts | 78 +++- packages/api/src/schedules/handlers.ts | 73 +++- packages/data-provider/src/types/schedules.ts | 9 + .../src/methods/schedule.methods.spec.ts | 20 + packages/data-schemas/src/methods/schedule.ts | 20 +- 10 files changed, 767 insertions(+), 28 deletions(-) create mode 100644 client/src/components/SidePanel/Schedules/__tests__/useRunSync.spec.tsx create mode 100644 client/src/components/SidePanel/Schedules/useRunSync.ts diff --git a/client/src/components/SidePanel/Schedules/SchedulePanel.tsx b/client/src/components/SidePanel/Schedules/SchedulePanel.tsx index 7878c18469..5e085e7792 100644 --- a/client/src/components/SidePanel/Schedules/SchedulePanel.tsx +++ b/client/src/components/SidePanel/Schedules/SchedulePanel.tsx @@ -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({ diff --git a/client/src/components/SidePanel/Schedules/__tests__/useRunSync.spec.tsx b/client/src/components/SidePanel/Schedules/__tests__/useRunSync.spec.tsx new file mode 100644 index 0000000000..4056d325cc --- /dev/null +++ b/client/src/components/SidePanel/Schedules/__tests__/useRunSync.spec.tsx @@ -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, [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 => ({ + ...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 => ({ + ...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 {children}; + }; + +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(); + }); +}); diff --git a/client/src/components/SidePanel/Schedules/useRunSync.ts b/client/src/components/SidePanel/Schedules/useRunSync.ts new file mode 100644 index 0000000000..eb7636be56 --- /dev/null +++ b/client/src/components/SidePanel/Schedules/useRunSync.ts @@ -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; + +const inFlightChats = (schedule: Pick): 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 | null>(null); + const announced = useRef>(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(); + const live = new Set(); + 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]); +} diff --git a/client/src/data-provider/Schedules/admission.ts b/client/src/data-provider/Schedules/admission.ts index 18358af8f7..14e0a7ea4f 100644 --- a/client/src/data-provider/Schedules/admission.ts +++ b/client/src/data-provider/Schedules/admission.ts @@ -49,16 +49,41 @@ const cacheOwner = (queryClient: QueryClient): string | undefined => queryClient.getQueryData([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(); +const watching = new Map(); -/** @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(); + +/** @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 { - 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); } } diff --git a/client/src/data-provider/__tests__/scheduleRunNow.test.tsx b/client/src/data-provider/__tests__/scheduleRunNow.test.tsx index 2a87f25926..ba10f7045e 100644 --- a/client/src/data-provider/__tests__/scheduleRunNow.test.tsx +++ b/client/src/data-provider/__tests__/scheduleRunNow.test.tsx @@ -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, [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); diff --git a/packages/api/src/schedules/handlers.spec.ts b/packages/api/src/schedules/handlers.spec.ts index a491c46d5f..f707986b3a 100644 --- a/packages/api/src/schedules/handlers.spec.ts +++ b/packages/api/src/schedules/handlers.spec.ts @@ -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 = {}): 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 => + ({ + 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 { diff --git a/packages/api/src/schedules/handlers.ts b/packages/api/src/schedules/handlers.ts index 37cf065604..4bee2da702 100644 --- a/packages/api/src/schedules/handlers.ts +++ b/packages/api/src/schedules/handlers.ts @@ -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 { + const grouped = new Map(); + 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, + 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 { - 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 { 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 { diff --git a/packages/data-provider/src/types/schedules.ts b/packages/data-provider/src/types/schedules.ts index f6601cd01f..cc0989fbf2 100644 --- a/packages/data-provider/src/types/schedules.ts +++ b/packages/data-provider/src/types/schedules.ts @@ -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; diff --git a/packages/data-schemas/src/methods/schedule.methods.spec.ts b/packages/data-schemas/src/methods/schedule.methods.spec.ts index 63f224045a..665f362eda 100644 --- a/packages/data-schemas/src/methods/schedule.methods.spec.ts +++ b/packages/data-schemas/src/methods/schedule.methods.spec.ts @@ -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'); diff --git a/packages/data-schemas/src/methods/schedule.ts b/packages/data-schemas/src/methods/schedule.ts index d51e495816..487408662a 100644 --- a/packages/data-schemas/src/methods/schedule.ts +++ b/packages/data-schemas/src/methods/schedule.ts @@ -289,7 +289,10 @@ export type ScheduleMethods = { ) => Promise; markScheduleDeleting: (id: string, userId: string | Types.ObjectId) => Promise; getActiveRunsForSchedule: (scheduleId: string) => Promise; - getActiveRunsForUser: (userId: string | Types.ObjectId) => Promise; + getActiveRunsForUser: ( + userId: string | Types.ObjectId, + statuses?: readonly ScheduleRunStatus[], + ) => Promise; suspendUserSchedulesForDeletion: ( userId: string | Types.ObjectId, token: string, @@ -1756,10 +1759,19 @@ export function createScheduleMethods(mongoose: typeof import('mongoose')): Sche .lean(); } - /** In-flight runs across all of a user's schedules β€” for account-deletion quiescing. */ - async function getActiveRunsForUser(userId: string | Types.ObjectId): Promise { + /** + * 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 { return ScheduleRun() - .find({ user: userId, status: { $in: ACTIVE_RUN_STATUSES } }) + .find({ user: userId, status: { $in: statuses } }) .lean(); }