Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
📬 fix: Show Background Results Still Waiting for the Agent (#16363)
Danny Avila048816acaa46
diff --git a/api/server/routes/__tests__/convos-duplicate-ratelimit.spec.js b/api/server/routes/__tests__/convos-duplicate-ratelimit.spec.jsindex 725e3c240c..4eb472d6e6 100644--- a/api/server/routes/__tests__/convos-duplicate-ratelimit.spec.js+++ b/api/server/routes/__tests__/convos-duplicate-ratelimit.spec.js@@ -50,6 +50,9 @@ jest.mock('~/server/services/Endpoints/assistants', () => require(MOCKS).assistajest.mock('~/server/services/Endpoints/agents/subagentThreadStore', () =>require(MOCKS).subagentThreadStore(),);+jest.mock('~/server/services/Endpoints/agents/backgroundCompletion', () => ({+ pendingBackgroundToolCompletions: { list: jest.fn() },+}));describe('POST /api/convos/duplicate - Rate Limiting', () => {let app;diff --git a/api/server/routes/__tests__/convos.spec.js b/api/server/routes/__tests__/convos.spec.jsindex b9302466a5..46a76a3146 100644--- a/api/server/routes/__tests__/convos.spec.js+++ b/api/server/routes/__tests__/convos.spec.js@@ -55,6 +55,9 @@ jest.mock('~/server/services/Endpoints/assistants', () => require(MOCKS).assistajest.mock('~/server/services/Endpoints/agents/subagentThreadStore', () =>require(MOCKS).subagentThreadStore(),);+jest.mock('~/server/services/Endpoints/agents/backgroundCompletion', () => ({+ pendingBackgroundToolCompletions: { list: jest.fn() },+}));describe('Convos Routes', () => {let app;diff --git a/api/server/routes/convos.js b/api/server/routes/convos.jsindex 96345a5efe..dac0f10ff2 100644--- a/api/server/routes/convos.js+++ b/api/server/routes/convos.js@@ -52,6 +52,9 @@ const { storage, importFileFilter } = require('~/server/routes/files/multer');const requireJwtAuth = require('~/server/middleware/requireJwtAuth');const { importConversations } = require('~/server/utils/import');const subagentThreadTaskStore = require('~/server/services/Endpoints/agents/subagentThreadStore');+const {+ pendingBackgroundToolCompletions,+} = require('~/server/services/Endpoints/agents/backgroundCompletion');const getLogStores = require('~/cache/getLogStores');const db = require('~/models');@@ -152,6 +155,7 @@ const subagentControlHandler = createSubagentControlHandler({const backgroundTaskPolicy = createBackgroundTaskPolicyMiddleware({ getAppConfig });const backgroundTaskIndexHandler = createBackgroundTaskIndexHandler({registry: backgroundTaskRegistry,+ pending: pendingBackgroundToolCompletions,});const backgroundTaskCancelHandler = createBackgroundTaskCancelHandler({registry: backgroundTaskRegistry,diff --git a/client/src/components/Chat/BackgroundTasks/Button.tsx b/client/src/components/Chat/BackgroundTasks/Button.tsxindex 622fba5fc6..b48d4c22a6 100644--- a/client/src/components/Chat/BackgroundTasks/Button.tsx+++ b/client/src/components/Chat/BackgroundTasks/Button.tsx@@ -30,7 +30,7 @@ function BackgroundTasksButton({const [wide, setWide] = useState(false);const [popoverElement, setPopoverElement] = useState<HTMLDivElement | null>(null);const view = useBackgroundTasks({ conversationId, isSubmitting, now });- const { rows, activeCount } = view;+ const { rows, activeCount, awaitingCount, failedCount, incomplete } = view;useEffect(() => {setNow(Date.now());@@ -41,7 +41,10 @@ function BackgroundTasksButton({const nextExpiry = rows.reduce((next, row) =>- row.settledAt != null && row.status !== 'running' && row.status !== 'stopping'+ row.settledAt != null &&+ row.delivery == null &&+ row.status !== 'running' &&+ row.status !== 'stopping'? Math.min(next, row.settledAt + RECENT_SUBAGENT_WINDOW_MS + 1): next,Infinity,@@ -52,13 +55,22 @@ function BackgroundTasksButton({return () => clearTimeout(timer);}, [nextExpiry]);- if (rows.length === 0 && !view.loadFailed) {+ if (rows.length === 0 && !view.loadFailed && !incomplete) {return null;}const title = localize('com_ui_background_tasks');const triggerLabel =- activeCount > 0 ? localize('com_ui_background_tasks_label', { 0: activeCount }) : title;+ [+ ...(activeCount > 0 ? [localize('com_ui_background_tasks_label', { 0: activeCount })] : []),+ ...(awaitingCount > 0+ ? [localize('com_ui_background_tasks_pending_label', { 0: awaitingCount })]+ : []),+ ...(failedCount > 0+ ? [localize('com_ui_background_tasks_failed_label', { 0: failedCount })]+ : []),+ ...(incomplete ? [localize('com_ui_background_tasks_incomplete')] : []),+ ].join('; ') || title;const running = rows.filter((row) => row.status === 'running' || row.status === 'stopping');const finished = rows.filter((row) => row.status !== 'running' && row.status !== 'stopping');const anyStoppable = running.some(view.canStop);@@ -94,10 +106,15 @@ function BackgroundTasksButton({className="relative inline-flex size-9 flex-shrink-0 items-center justify-center rounded-xl border border-border-light bg-presentation text-text-primary transition-all ease-in-out hover:bg-surface-tertiary aria-expanded:bg-surface-tertiary"><ListTodo className="icon-md" aria-hidden="true" />- {activeCount > 0 && (+ {(activeCount > 0 || awaitingCount > 0 || failedCount > 0 || incomplete) && (<spanaria-hidden="true"- className="absolute -right-0.5 -top-0.5 size-2 animate-pulse rounded-full bg-status-info ring-2 ring-presentation motion-reduce:animate-none"+ data-testid="background-tasks-indicator"+ className={cn(+ 'absolute -right-0.5 -top-0.5 size-2 rounded-full ring-2 ring-presentation',+ failedCount > 0 || incomplete ? 'bg-status-warning' : 'bg-status-info',+ activeCount > 0 && 'animate-pulse motion-reduce:animate-none',+ )}/>)}</Ariakit.PopoverDisclosure>@@ -138,6 +155,11 @@ function BackgroundTasksButton({</Ariakit.PopoverDismiss></div><div className="space-y-4 overflow-y-auto px-3 pb-3">+ {incomplete && (+ <p role="status" className="text-sm text-status-warning">+ {localize('com_ui_background_tasks_incomplete')}+ </p>+ )}{view.loadFailed && (<div role="alert" className="text-sm text-status-error"><p>{localize('com_ui_background_tasks_load_failed')}</p>diff --git a/client/src/components/Chat/BackgroundTasks/Card.tsx b/client/src/components/Chat/BackgroundTasks/Card.tsxindex 3cf97129f8..e80d01f30d 100644--- a/client/src/components/Chat/BackgroundTasks/Card.tsx+++ b/client/src/components/Chat/BackgroundTasks/Card.tsx@@ -2,8 +2,8 @@ import { memo, useId, useState } from 'react';import { useTranslation } from 'react-i18next';import { ChevronDown, Square } from 'lucide-react';import { Spinner, TooltipAnchor } from '@librechat/client';+import type { TaskRow, TaskRowDelivery, TaskRowStatus } from './rows';import type { TranslationKeys } from '~/hooks/useLocalize';-import type { TaskRow, TaskRowStatus } from './rows';import { getRunStepDurationLabels, getToolDisplayLabel, cn } from '~/utils';import { useLocalize } from '~/hooks';@@ -20,6 +20,15 @@ const STATUS_CLASSES: Partial<Record<TaskRowStatus, string>> = {cancelled: 'text-status-warning',};+const DELIVERY_KEYS: Record<TaskRowDelivery, TranslationKeys> = {+ pending: 'com_ui_background_tasks_result_pending',+ failed: 'com_ui_background_tasks_result_undelivered',+};++const DELIVERY_CLASSES: Partial<Record<TaskRowDelivery, string>> = {+ failed: 'text-status-warning',+};+function TaskCard({row,now,@@ -85,6 +94,14 @@ function TaskCard({</span>)}{row.status === 'stopping' && <span>{localize(STATUS_KEYS.stopping)}</span>}+ {row.delivery != null && (+ <span+ className={DELIVERY_CLASSES[row.delivery]}+ data-testid="background-task-delivery"+ >+ {localize(DELIVERY_KEYS[row.delivery])}+ </span>+ )}{duration != null && (<spanclassName="tabular-nums"diff --git a/client/src/components/Chat/BackgroundTasks/__tests__/Button.test.tsx b/client/src/components/Chat/BackgroundTasks/__tests__/Button.test.tsxindex 3e6dd8dfdc..715353bf44 100644--- a/client/src/components/Chat/BackgroundTasks/__tests__/Button.test.tsx+++ b/client/src/components/Chat/BackgroundTasks/__tests__/Button.test.tsx@@ -134,6 +134,76 @@ describe('BackgroundTasksButton', () => {await waitFor(() => expect(getTasks).toHaveBeenCalledWith(conversationId));});+ it.each(['pending', 'failed'] as const)(+ 'keeps a long-waiting %s result visible without rescheduling its expiry',+ async (delivery) => {+ jest.useFakeTimers();+ try {+ const old = new Date(Date.now() - 2 * 60 * 60_000).toISOString();+ const startedAt = new Date(Date.now() - 2 * 60 * 60_000 - 1_000).toISOString();+ jest+ .spyOn(dataService, 'getBackgroundTasks')+ .mockResolvedValue(+ index({ tasks: [{ ...index().tasks[1], startedAt, settledAt: old, delivery }] }),+ );+ renderButton([], []);+ await act(async () => {+ await jest.advanceTimersByTimeAsync(100);+ });+ const trigger = screen.getByTestId('header-background-tasks-button');+ expect(trigger).toHaveAccessibleName(+ delivery === 'pending'+ ? 'com_ui_background_tasks_pending_label'+ : 'com_ui_background_tasks_failed_label',+ );+ expect(screen.getByTestId('background-tasks-indicator')).toHaveClass(+ delivery === 'pending' ? 'bg-status-info' : 'bg-status-warning',+ );+ expect(screen.getByTestId('background-tasks-indicator')).not.toHaveClass('animate-pulse');+ await act(async () => {+ await jest.advanceTimersByTimeAsync(1_100);+ });+ expect(trigger).toBeInTheDocument();+ } finally {+ jest.useRealTimers();+ }+ },+ );++ it('announces a failed-only result inside the task list after its tool settled hours ago', async () => {+ const old = new Date(Date.now() - 2 * 60 * 60_000).toISOString();+ jest.spyOn(dataService, 'getBackgroundTasks').mockResolvedValue(+ index({+ tasks: [{ ...index().tasks[1], startedAt: old, settledAt: old, delivery: 'failed' }],+ }),+ );+ renderButton([], []);+ const trigger = await screen.findByTestId('header-background-tasks-button');+ const user = userEvent.setup();+ await user.click(trigger);+ const dialog = await screen.findByRole('dialog', { name: 'com_ui_background_tasks' });+ expect(within(dialog).getByTestId('background-task-delivery')).toHaveTextContent(+ 'com_ui_background_tasks_result_undelivered',+ );+ });++ it('keeps an incomplete empty index discoverable and recovers after the store returns', async () => {+ const getTasks = jest+ .spyOn(dataService, 'getBackgroundTasks')+ .mockResolvedValueOnce(index({ tasks: [], complete: false }))+ .mockResolvedValue(index({ tasks: [], complete: true }));+ const { queryClient } = renderButton([], []);+ const trigger = await screen.findByTestId('header-background-tasks-button');+ expect(trigger).toHaveAccessibleName('com_ui_background_tasks_incomplete');+ expect(screen.getByTestId('background-tasks-indicator')).toHaveClass('bg-status-warning');+ const user = userEvent.setup();+ await user.click(trigger);+ expect(screen.getByRole('status')).toHaveTextContent('com_ui_background_tasks_incomplete');+ await queryClient.invalidateQueries([QueryKeys.backgroundTasks, conversationId]);+ await waitFor(() => expect(screen.queryByTestId('header-background-tasks-button')).toBeNull());+ expect(getTasks).toHaveBeenCalledTimes(2);+ });+it.each(['tool', 'subagent'])('ages out the last finished %s even while the panel is closed',async (kind) => {diff --git a/client/src/components/Chat/BackgroundTasks/__tests__/rows.test.ts b/client/src/components/Chat/BackgroundTasks/__tests__/rows.test.tsindex b5ec2e072f..8ff2ecb313 100644--- a/client/src/components/Chat/BackgroundTasks/__tests__/rows.test.ts+++ b/client/src/components/Chat/BackgroundTasks/__tests__/rows.test.ts@@ -2,6 +2,8 @@ import { ContentTypes } from 'librechat-data-provider';import type { ParentSubagentSummary, TMessage } from 'librechat-data-provider';import {RECENT_SUBAGENT_WINDOW_MS,+ countAwaitingDelivery,+ countFailedDelivery,buildTaskRows,findToolCallArgs,subagentTaskKey,@@ -25,6 +27,55 @@ const child = (overrides: Partial<ParentSubagentSummary>): ParentSubagentSummary});describe('buildTaskRows', () => {+ it('keeps a finished result the agent has not received ahead of delivered ones', () => {+ const tool = (taskId: string, extra: object) => ({+ taskId,+ toolName: 'bash_tool',+ toolCallId: `call-${taskId}`,+ status: 'completed' as const,+ cancellationRequested: false,+ startedAt: iso(RECENT_SUBAGENT_WINDOW_MS * 2),+ settledAt: iso(RECENT_SUBAGENT_WINDOW_MS * 2 - 1_000),+ ...extra,+ });+ const rows = buildTaskRows({+ now,+ args: new Map(),+ describe: () => ({}),+ stoppingThreads: new Set(),+ subagents: [],+ tools: [+ tool('recent-delivered', {+ delivery: 'delivered',+ startedAt: iso(2_000),+ settledAt: iso(1_000),+ }),+ tool('old-pending', { delivery: 'pending' }),+ tool('old-failed', {+ delivery: 'failed',+ startedAt: iso(RECENT_SUBAGENT_WINDOW_MS * 3),+ settledAt: iso(RECENT_SUBAGENT_WINDOW_MS * 3 - 1_000),+ }),+ tool('old-delivered', { delivery: 'delivered' }),+ {+ ...tool('running', {}),+ status: 'running' as const,+ delivery: 'pending' as const,+ settledAt: undefined,+ },+ ],+ });++ expect(rows.map((row) => [row.id, row.status, row.delivery])).toEqual([+ ['tool:running', 'running', undefined],+ ['tool:old-pending', 'completed', 'pending'],+ ['tool:old-failed', 'completed', 'failed'],+ ['tool:recent-delivered', 'completed', undefined],+ ]);+ expect(countAwaitingDelivery(rows)).toBe(1);+ expect(countFailedDelivery(rows)).toBe(1);+ });+it('orders active rows first and drops subagents settled past the retention window', () => {const rows = buildTaskRows({now,diff --git a/client/src/components/Chat/BackgroundTasks/rows.ts b/client/src/components/Chat/BackgroundTasks/rows.tsindex e982acfbca..2e0c55ff55 100644--- a/client/src/components/Chat/BackgroundTasks/rows.ts+++ b/client/src/components/Chat/BackgroundTasks/rows.ts@@ -2,12 +2,16 @@ import { ContentTypes } from 'librechat-data-provider';import type {TMessage,BackgroundTaskSummary,+ BackgroundTaskDelivery,ParentSubagentSummary,SubagentThreadStatus,} from 'librechat-data-provider';export type TaskRowStatus = 'running' | 'stopping' | 'completed' | 'error' | 'cancelled';+/** A finished result the agent has not received yet, or never will. */+export type TaskRowDelivery = Extract<BackgroundTaskDelivery, 'pending' | 'failed'>;+export type TaskRow = {id: string;kind: 'tool' | 'subagent';@@ -22,6 +26,7 @@ export type TaskRow = {status: TaskRowStatus;startedAt?: number;settledAt?: number;+ delivery?: TaskRowDelivery;/** Subagent cancel target; present only while the child can still be stopped. */subagent?: { threadId: string; taskId: string };};@@ -87,19 +92,28 @@ export function findToolCallArgs(export type ToolCallDescriber = (args: ToolCallArgs) => Pick<TaskRow, 'title' | 'detail'>;+const undelivered = (task: BackgroundTaskSummary): TaskRowDelivery | undefined =>+ task.status !== 'running' && (task.delivery === 'pending' || task.delivery === 'failed')+ ? task.delivery+ : undefined;+const toolRow = (task: BackgroundTaskSummary,described: Pick<TaskRow, 'title' | 'detail'>,-): TaskRow => ({- id: `tool:${task.taskId}`,- kind: 'tool',- name: task.toolName,- taskId: task.taskId,- ...described,- status: task.status === 'running' && task.cancellationRequested ? 'stopping' : task.status,- startedAt: time(task.startedAt),- settledAt: time(task.settledAt),-});+): TaskRow => {+ const delivery = undelivered(task);+ return {+ id: `tool:${task.taskId}`,+ kind: 'tool',+ name: task.toolName,+ taskId: task.taskId,+ ...described,+ status: task.status === 'running' && task.cancellationRequested ? 'stopping' : task.status,+ startedAt: time(task.startedAt),+ settledAt: time(task.settledAt),+ ...(delivery == null ? {} : { delivery }),+ };+};const subagentRow = (child: ParentSubagentSummary, stopping: ReadonlySet<string>): TaskRow => {const status = subagentStatus(child.status);@@ -118,6 +132,16 @@ const subagentRow = (child: ParentSubagentSummary, stopping: ReadonlySet<string>const isActive = (row: TaskRow) => row.status === 'running' || row.status === 'stopping';+/** A finished result still on its way to the agent keeps the task relevant. */+const isAwaitingDelivery = (row: TaskRow) => row.delivery === 'pending';+const isFailedDelivery = (row: TaskRow) => row.delivery === 'failed';++const rank = (row: TaskRow): number => {+ if (isActive(row)) return 3;+ if (isAwaitingDelivery(row)) return 2;+ return isFailedDelivery(row) ? 1 : 0;+};+/*** One list across both background kinds: active rows first, then the most* recently started. Settled subagents older than the registry's retention are@@ -149,12 +173,22 @@ export function buildTaskRows({return rows.filter((row) =>- isActive(row) || row.settledAt == null || now - row.settledAt <= RECENT_SUBAGENT_WINDOW_MS,+ isActive(row) ||+ isAwaitingDelivery(row) ||+ isFailedDelivery(row) ||+ row.settledAt == null ||+ now - row.settledAt <= RECENT_SUBAGENT_WINDOW_MS,).sort((left, right) => {- const active = Number(isActive(right)) - Number(isActive(left));- return active !== 0 ? active : (right.startedAt ?? 0) - (left.startedAt ?? 0);+ const ranked = rank(right) - rank(left);+ return ranked !== 0 ? ranked : (right.startedAt ?? 0) - (left.startedAt ?? 0);});}export const countActive = (rows: readonly TaskRow[]) => rows.filter(isActive).length;++export const countAwaitingDelivery = (rows: readonly TaskRow[]) =>+ rows.filter(isAwaitingDelivery).length;++export const countFailedDelivery = (rows: readonly TaskRow[]) =>+ rows.filter(isFailedDelivery).length;diff --git a/client/src/components/Chat/BackgroundTasks/useTasks.ts b/client/src/components/Chat/BackgroundTasks/useTasks.tsindex 575ed088e4..99232403fc 100644--- a/client/src/components/Chat/BackgroundTasks/useTasks.ts+++ b/client/src/components/Chat/BackgroundTasks/useTasks.ts@@ -4,13 +4,20 @@ import { useQuery, useQueries } from '@tanstack/react-query';import { QueryKeys, dataService } from 'librechat-data-provider';import type { TMessage, ParentSubagentSummary } from 'librechat-data-provider';import type { TaskRow, ToolCallArgs } from './rows';+import {+ countActive,+ buildTaskRows,+ subagentTaskKey,+ findToolCallArgs,+ countFailedDelivery,+ countAwaitingDelivery,+} from './rows';import {useBackgroundTasksQuery,useSubagentControlMutation,useCancelBackgroundTasksMutation,} from '~/data-provider';import { useParentSubagents } from '~/components/Chat/Subagents/ParentSubagentsProvider';-import { buildTaskRows, countActive, findToolCallArgs, subagentTaskKey } from './rows';import parseJsonField from '~/components/Chat/Messages/Content/Parts/parseJsonField';import { getToolCallIntent } from '~/components/Chat/Messages/Content/Parts/intent';@@ -20,6 +27,12 @@ const noRefresh = async () => undefined;export type BackgroundTasksView = {rows: TaskRow[];activeCount: number;+ /** Finished results that will still arrive as a new agent turn. */+ awaitingCount: number;+ /** Failed automatic deliveries still recoverable through an agent poll. */+ failedCount: number;+ /** A store outage or bounded list may hide remote results. */+ incomplete: boolean;/** Whether the deployment lets users stop ordinary background tools. */toolsCancellable: boolean;isStopping: boolean;@@ -257,6 +270,9 @@ export default function useBackgroundTasks({return {rows,activeCount: countActive(rows),+ awaitingCount: countAwaitingDelivery(rows),+ failedCount: countFailedDelivery(rows),+ incomplete: data?.complete === false,toolsCancellable,isStopping,stopFailed,diff --git a/client/src/data-provider/BackgroundTasks/queries.polling.test.tsx b/client/src/data-provider/BackgroundTasks/queries.polling.test.tsxindex 50ef23a432..a160e7571c 100644--- a/client/src/data-provider/BackgroundTasks/queries.polling.test.tsx+++ b/client/src/data-provider/BackgroundTasks/queries.polling.test.tsx@@ -3,7 +3,7 @@ import { QueryKeys } from 'librechat-data-provider';import { act, renderHook, waitFor } from '@testing-library/react';import { QueryClient, QueryClientProvider } from '@tanstack/react-query';import type { BackgroundTaskIndex } from 'librechat-data-provider';-import { useBackgroundTasksQuery } from './queries';+import { backgroundTasksRefetchInterval, useBackgroundTasksQuery } from './queries';const mockGetBackgroundTasks = jest.fn();@@ -119,3 +119,30 @@ describe('background task discovery polling', () => {client.clear();});});++describe('backgroundTasksRefetchInterval', () => {+ const index = (tasks: BackgroundTaskIndex['tasks']): BackgroundTaskIndex => ({+ conversationId: 'convo-1',+ cancellable: false,+ tasks,+ });+ const task = (extra: Partial<BackgroundTaskIndex['tasks'][number]>) => ({+ taskId: 'task-1',+ toolName: 'bash_tool',+ toolCallId: 'call-1',+ status: 'completed' as const,+ cancellationRequested: false,+ startedAt: '2026-09-25T14:52:02.000Z',+ ...extra,+ });++ it('polls undelivered results slower than running work and faster than idle', () => {+ expect(backgroundTasksRefetchInterval(index([task({ status: 'running' })]))).toBe(2_000);+ expect(backgroundTasksRefetchInterval(index([task({ delivery: 'pending' })]))).toBe(10_000);+ expect(backgroundTasksRefetchInterval(index([task({ delivery: 'pending' })]), true)).toBe(+ 5_000,+ );+ expect(backgroundTasksRefetchInterval(index([task({ delivery: 'delivered' })]))).toBe(60_000);+ expect(backgroundTasksRefetchInterval(index([task({ delivery: 'failed' })]))).toBe(60_000);+ });+});diff --git a/client/src/data-provider/BackgroundTasks/queries.ts b/client/src/data-provider/BackgroundTasks/queries.tsindex 69f771629d..191fec001d 100644--- a/client/src/data-provider/BackgroundTasks/queries.ts+++ b/client/src/data-provider/BackgroundTasks/queries.ts@@ -9,6 +9,8 @@ import type {import type { UseQueryOptions } from '@tanstack/react-query';const RUNNING_REFRESH_MS = 2_000;+/** Undelivered results wait on the agent's turn, so they change slowly. */+const AWAITING_DELIVERY_REFRESH_MS = 10_000;const SUBMITTING_REFRESH_MS = 5_000;const POST_SUBMIT_DISCOVERY_MS = 10_000;const QUIET_REFRESH_MS = 60_000;@@ -24,7 +26,11 @@ export const backgroundTasksRefetchInterval = (return RUNNING_REFRESH_MS;}if (now < discoveryDeadline) return RUNNING_REFRESH_MS;- return isSubmitting ? SUBMITTING_REFRESH_MS : QUIET_REFRESH_MS;+ if (isSubmitting) return SUBMITTING_REFRESH_MS;+ if (index?.tasks.some((task) => task.delivery === 'pending') === true) {+ return AWAITING_DELIVERY_REFRESH_MS;+ }+ return QUIET_REFRESH_MS;};export const useBackgroundTasksQuery = (diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.jsonindex f89b54d879..a6fcf61481 100644--- a/client/src/locales/en/translation.json+++ b/client/src/locales/en/translation.json@@ -2,8 +2,13 @@"com_ui_background_tasks": "Background tasks","com_ui_background_tasks_cancel_disabled": "Stopping background tools is not enabled on this server","com_ui_background_tasks_completed": "Completed",+ "com_ui_background_tasks_failed_label": "Background tasks, {{0}} results not delivered","com_ui_background_tasks_finished": "Finished",+ "com_ui_background_tasks_incomplete": "Some background results may not be shown. Check again later.","com_ui_background_tasks_label": "Background tasks, {{0}} running",+ "com_ui_background_tasks_pending_label": "Background tasks, {{0}} results pending",+ "com_ui_background_tasks_result_pending": "Result pending",+ "com_ui_background_tasks_result_undelivered": "Result not delivered","com_ui_background_tasks_running": "Running","com_ui_background_tasks_stop": "Stop task","com_ui_background_tasks_stop_all": "Stop all running tasks",diff --git a/packages/api/src/agents/background.spec.ts b/packages/api/src/agents/background.spec.tsindex 2481c85344..571dca62f6 100644--- a/packages/api/src/agents/background.spec.ts+++ b/packages/api/src/agents/background.spec.ts@@ -3642,6 +3642,7 @@ describe('runCheckBackgroundTask delivery semantics', () => {list: async () => [{taskId: localTaskId,+ toolCallId: `call-${localTaskId}`,toolName: 'bash_tool',dispatchedAt: new Date('2026-09-24T12:00:00Z'),result: { status: 'completed', settledAt: new Date('2026-09-24T12:01:00Z') },@@ -3649,6 +3650,7 @@ describe('runCheckBackgroundTask delivery semantics', () => {},{taskId: 'earlier-turn-task',+ toolCallId: 'call-earlier-turn-task',toolName: 'slow_task',dispatchedAt: new Date('2026-09-24T11:00:00Z'),result: { status: 'error', settledAt: new Date('2026-09-24T11:05:00Z') },@@ -3656,6 +3658,7 @@ describe('runCheckBackgroundTask delivery semantics', () => {},{taskId: 'other-replica-task',+ toolCallId: 'call-other-replica-task',toolName: 'slow_task',dispatchedAt: new Date('2026-09-24T11:30:00Z'),claimedByWakeup: false,@@ -3751,6 +3754,7 @@ describe('runCheckBackgroundTask delivery semantics', () => {list: async () => [{taskId: waiting,+ toolCallId: `call-${waiting}`,toolName: 'bash_tool',dispatchedAt: new Date('2026-09-24T12:00:00Z'),result: { status: 'completed', settledAt: new Date('2026-09-24T12:01:00Z') },@@ -3783,12 +3787,14 @@ describe('runCheckBackgroundTask delivery semantics', () => {dead: [{taskId,+ toolCallId: `call-${taskId}`,toolName: 'bash_tool',dispatchedAt: new Date('2026-09-24T12:00:00Z'),claimedByWakeup: false,},{taskId: 'restored-dead-task',+ toolCallId: 'call-restored-dead-task',toolName: 'slow_task',dispatchedAt: new Date('2026-09-24T11:00:00Z'),result: { status: 'completed', settledAt: new Date('2026-09-24T11:01:00Z') },@@ -3882,7 +3888,7 @@ describe('runCheckBackgroundTask delivery semantics', () => {);expect(listed.outstanding).toBe(1);expect(listed.partial).toBe(true);- expect(listed.warning).toContain('More undelivered results exist');+ expect(listed.warning).toContain('result list may be incomplete');});it('lets a finished local task be cancelled without the live-cancellation policy', async () => {diff --git a/packages/api/src/agents/background.ts b/packages/api/src/agents/background.tsindex c7de708268..c95cb89524 100644--- a/packages/api/src/agents/background.ts+++ b/packages/api/src/agents/background.ts@@ -52,7 +52,7 @@ import type {BackgroundToolResultClaim,BackgroundToolResultRecord,} from '@librechat/data-schemas';-import type { AgentToolOptions } from 'librechat-data-provider';+import type { AgentToolOptions, BackgroundTaskDelivery } from 'librechat-data-provider';import type { BackgroundToolResultState } from './harvest';import type { CapabilityToolNames } from './selection';import {@@ -1868,7 +1868,7 @@ interface SerializedBackgroundTask {/** Whether the result has reached the conversation. `pending` results still* arrive as a new turn unless polled or cancelled first. Absent when the task* has no automatic delivery, so only a poll ever surfaces its result. */- delivery?: 'pending' | 'delivered' | 'failed';+ delivery?: BackgroundTaskDelivery;note?: string;error?: string;}@@ -1969,24 +1969,55 @@ function serializePendingCompletion(};}+/** One conversation's durable delivery evidence, split from what this process holds. */+export interface DurableCompletionView {+ /** Undelivered completions this process does not hold. */+ pending: PendingBackgroundCompletion[];+ /** Dead-lettered completions this process does not hold; only a poll recovers them. */+ dead: PendingBackgroundCompletion[];+ /** Every undelivered task id, present only when the listing was complete: a local+ * task absent from it was delivered on this or another replica. */+ pendingTaskIds?: ReadonlySet<string>;+ deadTaskIds: ReadonlySet<string>;+}++/** Reads the durable delivery store, which outlives the process-local registry.+ * Rejects when the store is unreachable; callers keep their local view then. */+export async function readDurableCompletions(+ controls: Pick<PendingBackgroundCompletionControls, 'list'>,+ input: { userId: string; conversationId: string },+ localTaskIds: ReadonlySet<string>,+): Promise<DurableCompletionView> {+ const durable = await controls.list(input);+ const remote = (completion: PendingBackgroundCompletion) => !localTaskIds.has(completion.taskId);+ return {+ pending: durable.completions.filter(remote),+ dead: durable.dead.filter(remote),+ ...(durable.complete && {+ pendingTaskIds: new Set(durable.completions.map(({ taskId }) => taskId)),+ }),+ deadTaskIds: new Set(durable.dead.map(({ taskId }) => taskId)),+ };+}+/** A local task whose durable delivery settled elsewhere (an automatic wake-up* on any replica) no longer holds a local claim; the complete durable listing is* the evidence. An incomplete listing proves nothing, so the local view stands. */-function reconcileDelivery(- task: SerializedBackgroundTask,- durablePendingTaskIds: ReadonlySet<string> | undefined,- deadTaskIds: ReadonlySet<string>,-): SerializedBackgroundTask {- if (task.delivery !== 'pending' || task.status === 'running') {- return task;+export function resolveTaskDelivery(+ task: BackgroundTask,+ durable?: Pick<DurableCompletionView, 'pendingTaskIds' | 'deadTaskIds'>,+): BackgroundTaskDelivery | undefined {+ const local = taskDelivery(task).delivery;+ if (local !== 'pending' || task.status === 'running' || durable == null) {+ return local;}- if (deadTaskIds.has(task.background_task_id)) {- return { ...task, delivery: 'failed' };+ if (durable.deadTaskIds.has(task.id)) {+ return 'failed';}- if (durablePendingTaskIds == null || durablePendingTaskIds.has(task.background_task_id)) {- return task;+ if (durable.pendingTaskIds == null || durable.pendingTaskIds.has(task.id)) {+ return local;}- return { ...task, delivery: 'delivered' };+ return 'delivered';}/** A completion whose automatic delivery dead-lettered and that this process no@@ -2766,27 +2797,17 @@ export async function runCheckBackgroundTask(params: {const tasks = backgroundTaskRegistry.list(userId, conversationId);let subagentTasks: SerializedSubagentTask[] = [];const listWarnings: string[] = [];- let pendingCompletions: PendingBackgroundCompletion[] = [];- /** Undelivered task ids from the durable store, when the listing was complete:- * a local task absent from it was delivered on this or another replica. */- let durablePendingTaskIds: ReadonlySet<string> | undefined;- let deadTaskIds: ReadonlySet<string> = new Set();- let deadCompletions: PendingBackgroundCompletion[] = [];+ let durable: DurableCompletionView | undefined;if (params.pendingCompletions != null) {try {- const localTaskIds = new Set(tasks.map((task) => task.id));- const durable = await params.pendingCompletions.list({ userId, conversationId });- deadTaskIds = new Set(durable.dead.map(({ taskId }) => taskId));- /** A dead letter this process no longer holds is still recoverable by a poll. */- deadCompletions = durable.dead.filter((completion) => !localTaskIds.has(completion.taskId));- pendingCompletions = durable.completions.filter(- (completion) => !localTaskIds.has(completion.taskId),+ durable = await readDurableCompletions(+ params.pendingCompletions,+ { userId, conversationId },+ new Set(tasks.map((task) => task.id)),);- if (durable.complete) {- durablePendingTaskIds = new Set(durable.completions.map(({ taskId }) => taskId));- } else {+ if (durable.pendingTaskIds == null) {listWarnings.push(- 'More undelivered results exist than could be listed; some not shown may still arrive as new turns.',+ 'The undelivered or failed result list may be incomplete; pending results not shown may still arrive as new turns.',);}} catch (error) {@@ -2823,15 +2844,13 @@ export async function runCheckBackgroundTask(params: {}}const ordinaryTasks = [- ...tasks.map((task) =>- reconcileDelivery(- serializeTask(task, { includeResult: false }),- durablePendingTaskIds,- deadTaskIds,- ),- ),- ...pendingCompletions.map(serializePendingCompletion),- ...deadCompletions.map(serializeDeadCompletion),+ ...tasks.map((task) => {+ const serialized = serializeTask(task, { includeResult: false });+ const delivery = resolveTaskDelivery(task, durable);+ return delivery == null ? serialized : { ...serialized, delivery };+ }),+ ...(durable?.pending ?? []).map(serializePendingCompletion),+ ...(durable?.dead ?? []).map(serializeDeadCompletion),];/** Pending only with durable evidence: whether a subagent's wake-up exists depends on* the policy when it was admitted, not on this request's configuration. */diff --git a/packages/api/src/agents/backgroundCompletion.ts b/packages/api/src/agents/backgroundCompletion.tsindex c657403096..8aabfefeab 100644--- a/packages/api/src/agents/backgroundCompletion.ts+++ b/packages/api/src/agents/backgroundCompletion.ts@@ -72,6 +72,7 @@ export type BackgroundToolDeadClaimRecovery = (* read from the durable delivery store rather than a process-local registry. */export interface PendingBackgroundCompletion {taskId: string;+ toolCallId: string;toolName: string;dispatchedAt: Date;/** The tool's terminal outcome once it settled; absent while it still runs. */@@ -94,7 +95,7 @@ export type BackgroundCompletionDiscardOutcome =/** Durable view and control of one principal's undelivered background completions. */export interface PendingBackgroundCompletionControls {- /** `complete` is false when more undelivered completions exist than were listed. */+ /** `complete` is false when undelivered or dead-lettered results were truncated. */list: (input: { userId: string; conversationId: string }) => Promise<{completions: PendingBackgroundCompletion[];/** Completions whose automatic delivery dead-lettered; only a poll recovers them. */diff --git a/packages/api/src/agents/backgroundCompletionWakeup.spec.ts b/packages/api/src/agents/backgroundCompletionWakeup.spec.tsindex 652ba4df25..3d8c9460a1 100644--- a/packages/api/src/agents/backgroundCompletionWakeup.spec.ts+++ b/packages/api/src/agents/backgroundCompletionWakeup.spec.ts@@ -919,6 +919,7 @@ describe('pending background completions', () => {dead: [{taskId: 'task-dead',+ toolCallId: 'call-1',toolName: 'slow_tool',dispatchedAt,claimedByWakeup: false,@@ -927,6 +928,7 @@ describe('pending background completions', () => {completions: [{taskId: 'task-1',+ toolCallId: 'call-1',toolName: 'slow_tool',dispatchedAt,result: settled,diff --git a/packages/api/src/agents/backgroundCompletionWakeup.ts b/packages/api/src/agents/backgroundCompletionWakeup.tsindex 63e6f45c89..e3df97eb04 100644--- a/packages/api/src/agents/backgroundCompletionWakeup.ts+++ b/packages/api/src/agents/backgroundCompletionWakeup.ts@@ -581,12 +581,14 @@ export function createPendingBackgroundCompletions(deps: {const { completions, dead, truncated } = await read(input);const project = ({taskId,+ toolCallId,toolName,dispatchedAt,result,claimedByWakeup,}: PendingBackgroundCompletion): PendingBackgroundCompletion => ({taskId,+ toolCallId,toolName,dispatchedAt,...(result != null && { result }),diff --git a/packages/api/src/agents/tasks.spec.ts b/packages/api/src/agents/tasks.spec.tsindex 94de8f2cab..813742ad6d 100644--- a/packages/api/src/agents/tasks.spec.ts+++ b/packages/api/src/agents/tasks.spec.ts@@ -1,4 +1,5 @@import type { Response } from 'express';+import type { PendingBackgroundCompletion } from './backgroundCompletion';import type { ServerRequest } from '~/types';import {createBackgroundTaskCancelHandler,@@ -9,6 +10,12 @@ import { BackgroundTaskRegistryClass } from './background';const conversationId = 'convo-1';+type PendingList = (input: { userId: string; conversationId: string }) => Promise<{+ completions: PendingBackgroundCompletion[];+ dead: PendingBackgroundCompletion[];+ complete: boolean;+}>;+const response = () => {const res = { status: jest.fn(), json: jest.fn() };res.status.mockReturnValue(res);@@ -73,7 +80,7 @@ describe('background task routes', () => {expect(failed.status).toHaveBeenCalledWith(503);expect(next).toHaveBeenCalledTimes(1);});- it('lists only the caller’s tasks without results', () => {+ it('lists only the caller’s tasks without results', async () => {const registry = new BackgroundTaskRegistryClass();const running = createTask(registry, 'call-1');const done = createTask(registry, 'call-2');@@ -81,7 +88,7 @@ describe('background task routes', () => {const handler = createBackgroundTaskIndexHandler({ registry });const res = response();- handler(request(), res);+ await handler(request(), res);const body = res.json.mock.calls[0][0];expect(res.status).toHaveBeenCalledWith(200);expect(body.cancellable).toBe(true);@@ -106,13 +113,130 @@ describe('background task routes', () => {registry.markCompletionPersistenceFinished('user-1', conversationId, done.id);later.mockRestore();const afterPersistence = response();- handler(request(), afterPersistence);+ await handler(request(), afterPersistence);expect(afterPersistence.json.mock.calls[0][0].tasks[1].settledAt).toBe(body.tasks[1].settledAt);expect(JSON.stringify(body)).not.toContain('secret output');const other = response();- handler(request({ userId: 'user-2', cancellation: false }), other);- expect(other.json).toHaveBeenCalledWith({ conversationId, tasks: [], cancellable: false });+ await handler(request({ userId: 'user-2', cancellation: false }), other);+ expect(other.json).toHaveBeenCalledWith({+ conversationId,+ tasks: [],+ complete: false,+ cancellable: false,+ });+ });++ describe('result delivery', () => {+ const completion = (+ taskId: string,+ overrides: Partial<PendingBackgroundCompletion> = {},+ ): PendingBackgroundCompletion => ({+ taskId,+ toolCallId: `${taskId}-call`,+ toolName: 'bash_tool',+ dispatchedAt: new Date('2026-09-25T14:52:02.000Z'),+ result: { status: 'completed', settledAt: new Date('2026-09-25T14:52:09.000Z') },+ claimedByWakeup: false,+ ...overrides,+ });++ const finishedWithWakeup = (registry: BackgroundTaskRegistryClass, toolCallId: string) => {+ const task = createTask(registry, toolCallId);+ registry.markCompletionWakeup('user-1', conversationId, task.id);+ registry.complete('user-1', conversationId, task.id, { content: 'ok' });+ return task;+ };++ const list = async (+ registry: BackgroundTaskRegistryClass,+ durable: Awaited<ReturnType<PendingList>>,+ ) => {+ const pending = { list: jest.fn<ReturnType<PendingList>, Parameters<PendingList>>() };+ pending.list.mockResolvedValue(durable);+ const res = response();+ await createBackgroundTaskIndexHandler({ registry, pending })(request(), res);+ expect(pending.list).toHaveBeenCalledWith({ userId: 'user-1', conversationId });+ expect(res.json.mock.calls[0][0].complete).toBe(durable.complete);+ return res.json.mock.calls[0][0].tasks as Array<Record<string, unknown>>;+ };++ it('marks a finished result pending until the agent receives it', async () => {+ const registry = new BackgroundTaskRegistryClass();+ const task = finishedWithWakeup(registry, 'call-1');+ const tasks = await list(registry, {+ completions: [completion(task.id)],+ dead: [],+ complete: true,+ });+ expect(tasks).toEqual([+ expect.objectContaining({ taskId: task.id, status: 'completed', delivery: 'pending' }),+ ]);+ });++ it('reports delivered once a wake-up on any replica took the result', async () => {+ const registry = new BackgroundTaskRegistryClass();+ const task = finishedWithWakeup(registry, 'call-1');+ const tasks = await list(registry, { completions: [], dead: [], complete: true });+ expect(tasks[0]).toEqual(expect.objectContaining({ taskId: task.id, delivery: 'delivered' }));+ });++ it('keeps the local view when the durable listing was truncated', async () => {+ const registry = new BackgroundTaskRegistryClass();+ const task = finishedWithWakeup(registry, 'call-1');+ const tasks = await list(registry, { completions: [], dead: [], complete: false });+ expect(tasks[0]).toEqual(expect.objectContaining({ taskId: task.id, delivery: 'pending' }));+ });++ it('lists finished results this process does not hold, but not remote running work', async () => {+ const registry = new BackgroundTaskRegistryClass();+ const tasks = await list(registry, {+ completions: [+ completion('remote-finished'),+ completion('remote-running', { result: undefined }),+ ],+ dead: [completion('remote-dead', { result: { status: 'error', settledAt: new Date() } })],+ complete: true,+ });+ expect(tasks).toEqual([+ {+ taskId: 'remote-finished',+ toolName: 'bash_tool',+ toolCallId: 'remote-finished-call',+ status: 'completed',+ cancellationRequested: false,+ startedAt: '2026-09-25T14:52:02.000Z',+ settledAt: '2026-09-25T14:52:09.000Z',+ delivery: 'pending',+ },+ expect.objectContaining({ taskId: 'remote-dead', status: 'error', delivery: 'failed' }),+ ]);+ });++ it('marks a local result whose delivery dead-lettered as failed', async () => {+ const registry = new BackgroundTaskRegistryClass();+ const task = finishedWithWakeup(registry, 'call-1');+ const tasks = await list(registry, {+ completions: [],+ dead: [completion(task.id)],+ complete: true,+ });+ expect(tasks).toHaveLength(1);+ expect(tasks[0]).toEqual(expect.objectContaining({ taskId: task.id, delivery: 'failed' }));+ });++ it('still lists local tasks when the durable store is unreachable', async () => {+ const registry = new BackgroundTaskRegistryClass();+ const task = finishedWithWakeup(registry, 'call-1');+ const pending = { list: jest.fn().mockRejectedValue(new Error('mongo down')) };+ const res = response();+ await createBackgroundTaskIndexHandler({ registry, pending })(request(), res);+ expect(res.status).toHaveBeenCalledWith(200);+ expect(res.json.mock.calls[0][0]).toMatchObject({+ complete: false,+ tasks: [expect.objectContaining({ taskId: task.id, delivery: 'pending' })],+ });+ });});it('cancels every running task when no ids are given', () => {diff --git a/packages/api/src/agents/tasks.ts b/packages/api/src/agents/tasks.tsindex 8f13e3d6d8..662ff37cc4 100644--- a/packages/api/src/agents/tasks.ts+++ b/packages/api/src/agents/tasks.ts@@ -1,15 +1,26 @@+import { logger } from '@librechat/data-schemas';import { EModelEndpoint } from 'librechat-data-provider';import type {BackgroundTaskCancelResponse,+ BackgroundTaskDelivery,BackgroundTaskSummary,BackgroundTaskIndex,TAgentsEndpoint,} from 'librechat-data-provider';import type { AppConfig } from '@librechat/data-schemas';import type { Response, NextFunction } from 'express';-import type { BackgroundTask, BackgroundTaskRegistryClass } from './background';+import type {+ PendingBackgroundCompletionControls,+ PendingBackgroundCompletion,+} from './backgroundCompletion';+import type {+ BackgroundTaskRegistryClass,+ DurableCompletionView,+ BackgroundTask,+} from './background';import type { GetAppConfigOptions } from '~/app/service';import type { ServerRequest } from '~/types';+import { readDurableCompletions, resolveTaskDelivery } from './background';import { getAppConfigOptionsFromUser } from '~/app/service';/** The registry surface the user-facing task routes read and act on. */@@ -20,6 +31,8 @@ export type BackgroundTaskRegistryView = Pick<export interface BackgroundTaskRouteDependencies {registry: BackgroundTaskRegistryView;+ /** Durable delivery store; without it the list shows only this process's tasks. */+ pending?: Pick<PendingBackgroundCompletionControls, 'list'>;}/** Resolve effective cancellation policy without enumerating code environments. */@@ -62,7 +75,10 @@ const agentsConfig = (req: ServerRequest): TAgentsEndpoint | undefined =>* Projects a registry task for the client. Results, artifacts and errors stay* server-side, matching the model tool's metadata-only list path.*/-export function toBackgroundTaskSummary(task: BackgroundTask): BackgroundTaskSummary {+export function toBackgroundTaskSummary(+ task: BackgroundTask,+ delivery?: BackgroundTaskDelivery,+): BackgroundTaskSummary {const settled = task.status !== 'running';return {taskId: task.id,@@ -76,25 +92,81 @@ export function toBackgroundTaskSummary(task: BackgroundTask): BackgroundTaskSum...(settled && task.settledAt != null? { settledAt: new Date(task.settledAt).toISOString() }: {}),+ ...(delivery == null ? {} : { delivery }),+ };+}++type SettledCompletion = PendingBackgroundCompletion &+ Required<Pick<PendingBackgroundCompletion, 'result'>>;++const isSettled = (completion: PendingBackgroundCompletion): completion is SettledCompletion =>+ completion.result != null;++/**+ * A finished result known only to the durable delivery store: it settled on+ * another replica, before a restart, or past this registry's retention, and has+ * not reached the agent. Running work stays owned by its process's registry.+ */+function toCompletionSummary(+ completion: SettledCompletion,+ delivery: Extract<BackgroundTaskDelivery, 'pending' | 'failed'>,+): BackgroundTaskSummary {+ return {+ taskId: completion.taskId,+ toolName: completion.toolName,+ toolCallId: completion.toolCallId,+ status: completion.result.status,+ cancellationRequested: false,+ startedAt: completion.dispatchedAt.toISOString(),+ settledAt: completion.result.settledAt.toISOString(),+ delivery,};}+async function readDurable(+ deps: BackgroundTaskRouteDependencies,+ input: { userId: string; conversationId: string },+ tasks: readonly BackgroundTask[],+): Promise<DurableCompletionView | undefined> {+ if (deps.pending == null) {+ return undefined;+ }+ try {+ return await readDurableCompletions(deps.pending, input, new Set(tasks.map(({ id }) => id)));+ } catch (error) {+ logger.warn('[background] Failed to read undelivered completions for the task list:', error);+ return undefined;+ }+}+/*** Lists the caller's background tool tasks for one conversation. The registry- * is keyed by user and conversation, so another user's tasks are unreachable- * without a database read; tasks owned by another replica are not visible.+ * is keyed by user and conversation, so another user's tasks are unreachable;+ * the durable delivery store adds whether each finished result has reached the+ * agent, and finished results this process does not hold.*/export function createBackgroundTaskIndexHandler(deps: BackgroundTaskRouteDependencies) {- return (req: ServerRequest, res: Response): void => {+ return async (req: ServerRequest, res: Response): Promise<void> => {const userId = req.user?.id;const { conversationId } = req.params as { conversationId?: string };if (!userId || !validConversationId(conversationId)) {res.status(404).json({ error: 'Conversation not found' });return;}+ const tasks = deps.registry.list(userId, conversationId);+ const durable = await readDurable(deps, { userId, conversationId }, tasks);const body: BackgroundTaskIndex = {conversationId,- tasks: deps.registry.list(userId, conversationId).map(toBackgroundTaskSummary),+ tasks: [+ ...tasks.map((task) => toBackgroundTaskSummary(task, resolveTaskDelivery(task, durable))),+ ...(durable?.pending ?? [])+ .filter(isSettled)+ .map((completion) => toCompletionSummary(completion, 'pending')),+ ...(durable?.dead ?? [])+ .filter(isSettled)+ .map((completion) => toCompletionSummary(completion, 'failed')),+ ],+ complete: durable?.pendingTaskIds != null,cancellable: ordinaryToolCancellationEnabled(agentsConfig(req)),};res.status(200).json(body);diff --git a/packages/data-provider/src/types/background.ts b/packages/data-provider/src/types/background.tsindex 1e50496b32..82a236810a 100644--- a/packages/data-provider/src/types/background.ts+++ b/packages/data-provider/src/types/background.ts@@ -1,5 +1,12 @@export type BackgroundTaskStatus = 'running' | 'completed' | 'error' | 'cancelled';+/**+ * Whether a finished task's result has reached the agent. `pending` results still+ * arrive as a new turn; `failed` ones never will. Absent for tasks without+ * automatic delivery.+ */+export type BackgroundTaskDelivery = 'pending' | 'delivered' | 'failed';+/*** Public projection of one ordinary background tool task. Results, artifacts* and errors stay server-side; the list carries identity, status and timing.@@ -17,11 +24,14 @@ export type BackgroundTaskSummary = {startedAt: string;/** ISO-8601 terminal time. Absent while the task is running. */settledAt?: string;+ delivery?: BackgroundTaskDelivery;};export type BackgroundTaskIndex = {conversationId: string;tasks: BackgroundTaskSummary[];+ /** False when the durable store is unavailable or its bounded list is incomplete. */+ complete?: boolean;/** Whether the deployment accepts user cancellation of ordinary tools. */cancellable: boolean;};diff --git a/packages/data-schemas/src/methods/triggerDelivery.spec.ts b/packages/data-schemas/src/methods/triggerDelivery.spec.tsindex 465ed6e316..c49c46ea22 100644--- a/packages/data-schemas/src/methods/triggerDelivery.spec.ts+++ b/packages/data-schemas/src/methods/triggerDelivery.spec.ts@@ -923,10 +923,128 @@ describe('agent trigger delivery methods', () => {sourceId: background.id,limit: 1,});- expect(page.completions.map((entry) => entry.taskId)).toEqual(['task-first']);+ expect(page.completions.map((entry) => entry.taskId)).toEqual(['task-second']);expect(page.truncated).toBe(true);});+ it('does not let 201 retained dead letters hide a new result or a late delivery failure', async () => {+ const user = new mongoose.Types.ObjectId();+ await Delivery.insertMany(+ Array.from({ length: 201 }, (_, index) => ({+ deliveryKey: `background-dead-${index}`,+ fingerprint: `background-dead-${index}`,+ orderingKey: `background-dead-${index}`,+ laneSequence: 1,+ envelope: {+ event: {+ source: background,+ payload: {+ taskId: `old-dead-${index}`,+ toolCallId: `call-old-dead-${index}`,+ toolName: 'slow_task',+ },+ },+ target: { conversationId: 'conversation-1' },+ },+ user,+ status: 'dead',+ requiredWorkerCapability:+ AGENT_TRIGGER_WORKER_CAPABILITY_BACKGROUND_COMPLETION_RECEIPT_V2,+ attempts: 1,+ availableAt: START,+ createdAt: new Date(START.getTime() + index * 1_000),+ updatedAt: new Date(START.getTime() + index * 1_000),+ backgroundToolResult: { status: 'completed', output: 'private output', settledAt: START },+ })),+ );+ const waiting = await completion(user, 'new-pending');+ await methods.persistAgentBackgroundToolResult({+ deliveryKey: waiting.delivery.deliveryKey,+ sourceId: background.id,+ result: { status: 'completed', output: 'private pending result', settledAt: START },+ });+ const late = await completion(user, 'late-failure');+ await methods.persistAgentBackgroundToolResult({+ deliveryKey: late.delivery.deliveryKey,+ sourceId: background.id,+ result: { status: 'completed', output: 'private late result', settledAt: START },+ });+ await Delivery.collection.updateOne(+ { _id: new mongoose.Types.ObjectId(late.delivery.id) },+ { $set: { createdAt: new Date(START.getTime() - 60_000) } },+ );+ await Delivery.updateOne({ _id: late.delivery.id }, { $set: { status: 'dead' } });++ const listed = await methods.listPendingAgentBackgroundToolCompletions({+ user,+ conversationId: 'conversation-1',+ sourceId: background.id,+ });+ expect(listed.completions.map(({ taskId }) => taskId)).toEqual(['new-pending']);+ expect(listed.dead).toHaveLength(200);+ expect(listed.dead[0].taskId).toBe('late-failure');+ expect(listed.dead.some(({ taskId }) => taskId === 'old-dead-0')).toBe(false);+ expect(listed.truncated).toBe(true);+ expect(JSON.stringify(listed)).not.toContain('private');+ });++ it('uses a scoped index even when other conversations have waiting deliveries', async () => {+ const user = new mongoose.Types.ObjectId();+ await completion(user, 'current');+ await Delivery.insertMany(+ Array.from({ length: 80 }, (_, index) => ({+ ...enqueueInput({+ user,+ orderingKey: `unrelated-background-${index}`,+ envelope: {+ event: {+ source: background,+ payload: {+ taskId: `unrelated-${index}`,+ toolCallId: `call-unrelated-${index}`,+ toolName: 'slow_task',+ },+ },+ target: { conversationId: 'another-conversation' },+ },+ }),+ requiredWorkerCapability:+ AGENT_TRIGGER_WORKER_CAPABILITY_BACKGROUND_COMPLETION_RECEIPT_V2,+ laneSequence: 1,+ status: 'pending',+ attempts: 0,+ })),+ );+ const indexes = await Delivery.collection.indexes();+ const scopeIndex = indexes.find(+ ({ key }) =>+ key.user === 1 &&+ key['envelope.event.source.id'] === 1 &&+ key['envelope.target.conversationId'] === 1 &&+ key.requiredWorkerCapability === 1 &&+ key.status === 1 &&+ key.updatedAt === -1,+ );+ if (scopeIndex == null) throw new Error('Conversation-scoped delivery index is missing');+ const plan = await Delivery.collection+ .find({+ user,+ 'envelope.event.source.type': 'internal',+ 'envelope.event.source.id': background.id,+ 'envelope.target.conversationId': 'conversation-1',+ requiredWorkerCapability:+ AGENT_TRIGGER_WORKER_CAPABILITY_BACKGROUND_COMPLETION_RECEIPT_V2,+ status: { $in: ['pending', 'leased', 'capability_pending'] },+ capabilityStatus: { $ne: 'dead' },+ })+ .sort({ updatedAt: -1, _id: -1 })+ .limit(1)+ .hint(scopeIndex.key)+ .explain('executionStats');+ expect(JSON.stringify(plan.queryPlanner.winningPlan)).toContain(scopeIndex.name);+ expect(plan.executionStats.totalDocsExamined).toBeLessThanOrEqual(1);+ });+it('omits legacy rows whose results live only on the parent message', async () => {const user = new mongoose.Types.ObjectId();await completion(user, 'task-legacy', {diff --git a/packages/data-schemas/src/methods/triggerDelivery.ts b/packages/data-schemas/src/methods/triggerDelivery.tsindex 601910b440..81d4d7140c 100644--- a/packages/data-schemas/src/methods/triggerDelivery.ts+++ b/packages/data-schemas/src/methods/triggerDelivery.ts@@ -50,10 +50,6 @@ const CLAIM_CANDIDATE_BATCH = 8;const MAX_PENDING_BACKGROUND_COMPLETIONS = 200;/** Every status before a delivery settles, i.e. whose result has not reached its conversation. */const DEAD_STATUSES: IAgentTriggerDelivery['status'][] = ['dead', 'capability_dead'];-/** Dead to every worker version, including a capability row a legacy worker still sees leased. */-function isDeadDelivery(row: Pick<IAgentTriggerDelivery, 'status' | 'capabilityStatus'>): boolean {- return DEAD_STATUSES.includes(row.status) || row.capabilityStatus === 'dead';-}const UNDELIVERED_STATUSES: IAgentTriggerDelivery['status'][] = ['staging','capability_staging',@@ -282,7 +278,7 @@ export interface PendingAgentBackgroundToolCompletions {completions: PendingAgentBackgroundToolCompletion[];/** Completions whose delivery dead-lettered: never delivered, recoverable only by a poll. */dead: PendingAgentBackgroundToolCompletion[];- /** More undelivered completions exist than were returned. */+ /** The first page overflowed; separate reads may not cover one complete snapshot. */truncated: boolean;}@@ -2359,37 +2355,30 @@ export function createAgentTriggerDeliveryMethods() {throw new TypeError('Invalid pending background completion lookup');}- const rows = await Delivery()- .find({- user: input.user,- 'envelope.event.source.type': 'internal',- 'envelope.event.source.id': input.sourceId,- 'envelope.target.conversationId': input.conversationId,- ...(input.taskId != null && { 'envelope.event.payload.taskId': input.taskId }),- /** Legacy rows keep results only on the parent message, so a missing- * receipt cannot tell running from finished; they drain on their own path. */- requiredWorkerCapability: AGENT_TRIGGER_WORKER_CAPABILITY_BACKGROUND_COMPLETION_RECEIPT_V2,- /** Dead letters are read too, so a caller can tell "delivered" from "failed". */- status: { $in: [...UNDELIVERED_STATUSES, ...DEAD_STATUSES] },- })- .select(- 'deliveryKey createdAt status capabilityStatus envelope.event.payload ' +- 'backgroundToolResult.status backgroundToolResult.settledAt backgroundToolResult.resultClaim',- )- .sort({ createdAt: 1, _id: 1 })- .limit(limit + 1)- .lean<- Array<- Pick<- IAgentTriggerDelivery,- 'deliveryKey' | 'createdAt' | 'backgroundToolResult' | 'status' | 'capabilityStatus'- > & {- envelope?: { event?: { payload?: Record<string, unknown> } };- }- >- >();- const dead: PendingAgentBackgroundToolCompletion[] = [];- const completions = rows.slice(0, limit).flatMap((row) => {+ type CompletionRow = Pick<+ IAgentTriggerDelivery,+ 'deliveryKey' | 'createdAt' | 'backgroundToolResult' | 'status' | 'capabilityStatus'+ > & { envelope?: { event?: { payload?: Record<string, unknown> } } };+ const scope = {+ user: input.user,+ 'envelope.event.source.type': 'internal',+ 'envelope.event.source.id': input.sourceId,+ 'envelope.target.conversationId': input.conversationId,+ ...(input.taskId != null && { 'envelope.event.payload.taskId': input.taskId }),+ /** Legacy rows keep results only on the parent message. */+ requiredWorkerCapability: AGENT_TRIGGER_WORKER_CAPABILITY_BACKGROUND_COMPLETION_RECEIPT_V2,+ };+ const read = (filter: FilterQuery<IAgentTriggerDelivery>) =>+ Delivery()+ .find({ ...scope, ...filter })+ .select(+ 'deliveryKey createdAt status capabilityStatus envelope.event.payload ' ++ 'backgroundToolResult.status backgroundToolResult.settledAt backgroundToolResult.resultClaim',+ )+ .sort({ updatedAt: -1, _id: -1 })+ .limit(limit + 1)+ .lean<CompletionRow[]>();+ const project = (row: CompletionRow): PendingAgentBackgroundToolCompletion | undefined => {const payload = row.envelope?.event?.payload;const taskId = payload?.taskId;const toolCallId = payload?.toolCallId;@@ -2400,30 +2389,60 @@ export function createAgentTriggerDeliveryMethods(typeof toolCallId !== 'string' ||typeof toolName !== 'string') {- return [];+ return undefined;}const receipt = row.backgroundToolResult;- return [- {- deliveryKey: row.deliveryKey,- taskId,- toolCallId,- toolName,- dispatchedAt: row.createdAt,- ...(receipt != null && {- result: { status: receipt.status, settledAt: receipt.settledAt },- }),- claimedByWakeup: receipt?.resultClaim != null,- },- ].filter((completion) => {- if (!isDeadDelivery(row)) {- return true;+ return {+ deliveryKey: row.deliveryKey,+ taskId,+ toolCallId,+ toolName,+ dispatchedAt: row.createdAt,+ ...(receipt != null && {+ result: { status: receipt.status, settledAt: receipt.settledAt },+ }),+ claimedByWakeup: receipt?.resultClaim != null,+ };+ };+ const classify = (rows: CompletionRow[]): PendingAgentBackgroundToolCompletions => {+ const completions: PendingAgentBackgroundToolCompletion[] = [];+ const dead: PendingAgentBackgroundToolCompletion[] = [];+ for (const row of rows.slice(0, limit)) {+ const completion = project(row);+ if (completion == null) continue;+ if (DEAD_STATUSES.includes(row.status) || row.capabilityStatus === 'dead') {+ dead.push(completion);+ } else {+ completions.push(completion);}- dead.push(completion);- return false;- });- });- return { completions, dead, truncated: rows.length > limit };+ }+ return { completions: completions.reverse(), dead, truncated: rows.length > limit };+ };+ const first = classify(+ await read({ status: { $in: [...UNDELIVERED_STATUSES, ...DEAD_STATUSES] } }),+ );+ if (!first.truncated) return first;++ /** Overfull conversations need separate bounded reads so old dead letters+ * cannot hide pending work. Separate reads can straddle a transition, so+ * absence is not evidence of delivery until a later single read fits. */+ const [waitingRows, deadRows] = await Promise.all([+ read({ status: { $in: UNDELIVERED_STATUSES }, capabilityStatus: { $ne: 'dead' } }),+ read({+ $or: [+ { status: { $in: DEAD_STATUSES } },+ { status: { $in: UNDELIVERED_STATUSES }, capabilityStatus: 'dead' },+ ],+ }),+ ]);+ const waiting = classify(waitingRows);+ const dead = classify(deadRows);+ const failedIds = new Set(dead.dead.map(({ taskId }) => taskId));+ return {+ completions: waiting.completions.filter(({ taskId }) => !failedIds.has(taskId)),+ dead: dead.dead,+ truncated: true,+ };}async function listUndeliveredAgentTriggerTaskIds(input: {diff --git a/packages/data-schemas/src/schema/triggerDelivery.ts b/packages/data-schemas/src/schema/triggerDelivery.tsindex d9b503e6c5..927e421b3d 100644--- a/packages/data-schemas/src/schema/triggerDelivery.ts+++ b/packages/data-schemas/src/schema/triggerDelivery.ts@@ -256,6 +256,17 @@ triggerDeliverySchema.index(triggerDeliverySchema.index({ status: 1, updatedAt: -1 });/** One user's waiting deliveries, read when that user's generation settles. */triggerDeliverySchema.index({ user: 1, status: 1, availableAt: 1 });+/** Bounded background-result polls by owner, conversation, capability and status. */+triggerDeliverySchema.index({+ user: 1,+ 'envelope.event.source.type': 1,+ 'envelope.event.source.id': 1,+ 'envelope.target.conversationId': 1,+ requiredWorkerCapability: 1,+ status: 1,+ updatedAt: -1,+ _id: -1,+});triggerDeliverySchema.index({ 'actorReceipt.resolution': 1 }, { sparse: true });triggerDeliverySchema.index({ user: 1, actorActionAdmittedAt: 1 }, { sparse: true });triggerDeliverySchema.index({ stagingRecoveryAt: 1 }, { sparse: true });