Skip to content

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

📬 fix: 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.js
index 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).assista
jest.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.js
index 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).assista
jest.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.js
index 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.tsx
index 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) && (
<span
aria-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.tsx
index 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 && (
<span
className="tabular-nums"
diff --git a/client/src/components/Chat/BackgroundTasks/__tests__/Button.test.tsx b/client/src/components/Chat/BackgroundTasks/__tests__/Button.test.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.tsx
index 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.ts
index 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.json
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 });