@promptbook/cli 0.113.0-8 → 0.114.0-0

package/apps/agents-server/src/utils/getAdminChatTasksResponse/mapVpsSelfUpdateJobToAdminChatTask.ts

@@ -1,13 +1,18 @@
+import { buildVpsSelfUpdateAdminChatTaskId, VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID_PREFIX } from '../adminChatTaskLinks';
 import type { AdminChatTaskRecord } from '../chatTasksAdmin';
 import type { UserChatJobStatus } from '../userChat/UserChatJobRecord';
 import type { VpsSelfUpdateJobSnapshot } from '../vpsSelfUpdate';
+import { resolveVpsSelfUpdateJobIdentity } from '../vpsSelfUpdate/vpsSelfUpdateJobIdentity';
 
 /**
- * Stable synthetic task id used for the singleton standalone VPS self-update task row.
+ * Stable synthetic task id prefix used for standalone VPS self-update task rows.
+ *
+ * Kept for backward compatibility; the value is single-sourced from the browser-safe
+ * `VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID_PREFIX` shared with the update page.
  *
  * @private internal admin utility of Agents Server
  */
-export const VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID = 'vps-self-update';
+export const VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID = VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID_PREFIX;
 
 /**
  * Synthetic queue name used for the standalone VPS self-update task row.
@@ -30,13 +35,17 @@ export function mapVpsSelfUpdateJobToAdminChatTask(job: VpsSelfUpdateJobSnapshot
 
     const isTerminalStatus = status === 'COMPLETED' || status === 'FAILED';
     const startedAt = job.startedAt;
-    const finishedAt = isTerminalStatus ? job.finishedAt || startedAt : null;
+    // Report the real recorded finish time only; falling back to `startedAt` would render a
+    // misleading zero-second total duration for a self-update whose finish time is unknown.
+    const finishedAt = isTerminalStatus ? job.finishedAt : null;
     const updatedAt = finishedAt || startedAt || new Date().toISOString();
     const errorSummary = job.errorMessage || null;
     const currentStepDetails = job.currentStep || null;
+    const triggerLabel = formatVpsSelfUpdateTrigger(job.trigger);
+    const taskId = buildVpsSelfUpdateAdminChatTaskId(resolveVpsSelfUpdateJobIdentity(job));
 
     return {
-        id: VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID,
+        id: taskId,
         kind: 'VPS_SELF_UPDATE',
         status,
         createdAt: startedAt || updatedAt,
@@ -56,14 +65,24 @@ export function mapVpsSelfUpdateJobToAdminChatTask(job: VpsSelfUpdateJobSnapshot
         lastErrorDetails: currentStepDetails,
         userId: 0,
         username: null,
-        agentPermanentId: VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID,
-        agentName: job.targetEnvironment.label,
+        agentPermanentId: taskId,
+        agentName: `${triggerLabel} self-update: ${job.targetEnvironment.label}`,
         chatId: job.targetBranch || job.targetEnvironment.branch || VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID,
         workerId: job.pid !== null ? String(job.pid) : null,
-        queueName: VPS_SELF_UPDATE_ADMIN_CHAT_TASK_QUEUE_NAME,
+        queueName: `${VPS_SELF_UPDATE_ADMIN_CHAT_TASK_QUEUE_NAME}:${job.trigger}`,
     };
 }
 
+/**
+ * Formats one self-update trigger for task-manager display.
+ *
+ * @param trigger - Persisted self-update trigger.
+ * @returns Capitalized trigger label.
+ */
+function formatVpsSelfUpdateTrigger(trigger: VpsSelfUpdateJobSnapshot['trigger']): string {
+    return trigger === 'automatic' ? 'Automatic' : 'Manual';
+}
+
 /**
  * Maps the shell-owned self-update status to the durable chat-task status enum used by the admin task manager.
  *

package/apps/agents-server/src/utils/getAdminChatTasksResponse/parseAdminChatTaskQuery.ts

@@ -1,4 +1,4 @@
-import type { AdminChatTaskView } from '../chatTasksAdmin';
+import type { AdminChatTaskSortField, AdminChatTaskSortOrder, AdminChatTaskView } from '../chatTasksAdmin';
 
 /**
  * Default number of task rows returned per page.
@@ -38,6 +38,8 @@ export type ParsedAdminChatTaskQuery = {
     pageSize: number;
     view: AdminChatTaskView;
     search: string;
+    sortBy: AdminChatTaskSortField;
+    sortOrder: AdminChatTaskSortOrder;
     timeWindowHours: number;
 };
 
@@ -60,6 +62,8 @@ export function parseAdminChatTaskQuery(searchParams: URLSearchParams): ParsedAd
         ),
         view,
         search: searchParams.get('search')?.trim() || '',
+        sortBy: parseAdminChatTaskSortField(searchParams.get('sortBy')),
+        sortOrder: parseAdminChatTaskSortOrder(searchParams.get('sortOrder')),
         timeWindowHours: parsePositiveInteger(
             searchParams.get('timeWindowHours'),
             DEFAULT_ADMIN_CHAT_TASK_TIME_WINDOW_HOURS,
@@ -68,6 +72,35 @@ export function parseAdminChatTaskQuery(searchParams: URLSearchParams): ParsedAd
     };
 }
 
+/**
+ * Parses the requested admin task-manager sort field.
+ *
+ * @private function of `getAdminChatTasksResponse`
+ */
+function parseAdminChatTaskSortField(value: string | null): AdminChatTaskSortField {
+    if (
+        value === 'task' ||
+        value === 'ownership' ||
+        value === 'timeline' ||
+        value === 'duration' ||
+        value === 'queue' ||
+        value === 'lastError'
+    ) {
+        return value;
+    }
+
+    return 'default';
+}
+
+/**
+ * Parses the requested admin task-manager sort order.
+ *
+ * @private function of `getAdminChatTasksResponse`
+ */
+function parseAdminChatTaskSortOrder(value: string | null): AdminChatTaskSortOrder {
+    return value === 'asc' ? 'asc' : 'desc';
+}
+
 /**
  * Parses one positive integer query parameter with fallback and upper bound.
  *

package/apps/agents-server/src/utils/getAdminChatTasksResponse.ts

@@ -1,18 +1,15 @@
 import { ensureUserChatTimeoutWorkerBootstrapped } from '@/src/utils/userChatTimeout/ensureUserChatTimeoutWorkerBootstrapped';
-import type { AdminChatTaskCounters, AdminChatTaskListResponse, AdminChatTaskRecord } from './chatTasksAdmin';
+import type { AdminChatTaskListResponse } from './chatTasksAdmin';
+import {
+    collectAdminChatTasksToInject,
+    createInjectedAwareAdminChatTaskQuery,
+    loadInjectableAdminChatTasks,
+    mergeInjectedAdminChatTaskCounters,
+    mergeInjectedAdminChatTasks,
+} from './getAdminChatTasksResponse/adminChatTaskInjection';
 import { getAdminChatTasks } from './getAdminChatTasksResponse/getAdminChatTasks';
-import { mapVpsSelfUpdateJobToAdminChatTask } from './getAdminChatTasksResponse/mapVpsSelfUpdateJobToAdminChatTask';
-import { parseAdminChatTaskQuery, type ParsedAdminChatTaskQuery } from './getAdminChatTasksResponse/parseAdminChatTaskQuery';
+import { parseAdminChatTaskQuery } from './getAdminChatTasksResponse/parseAdminChatTaskQuery';
 import { throttledAdminRecovery } from './getAdminChatTasksResponse/throttledAdminRecovery';
-import { listPagePreviewBrowserAdminTasks } from './pagePreviewBrowserSessions';
-import { readVpsSelfUpdateJobSnapshot } from './vpsSelfUpdate';
-
-/**
- * Milliseconds in one hour.
- *
- * @private internal constant of `getAdminChatTasksResponse`
- */
-const HOUR_IN_MILLISECONDS = 60 * 60 * 1000;
 
 /**
  * Successful task-manager response envelope.
@@ -44,6 +41,10 @@ export type GetAdminChatTasksResponseResult = GetAdminChatTasksResponseSuccess |
 /**
  * Builds the paginated admin task-manager payload from live durable worker state.
  *
+ * This is the per-server view: it reports durable jobs for the current request's server plus the
+ * process-local VPS tasks injected on top. The VPS-wide superadmin view lives in
+ * `getVpsAdminChatTasksResponse`.
+ *
  * @private internal admin utility of Agents Server
  */
 export async function getAdminChatTasksResponse(
@@ -62,19 +63,17 @@ export async function getAdminChatTasksResponse(
     // [🧠] Recovery operations are throttled to avoid hammering the DB on every admin poll
     await throttledAdminRecovery();
 
-    const adminChatTasks = await getAdminChatTasks(parsedQuery);
-    const vpsSelfUpdateTask = await loadVpsSelfUpdateAdminChatTask();
-    const pagePreviewBrowserTasks = listPagePreviewBrowserAdminTasks();
-    const injectableTasks = [vpsSelfUpdateTask, ...pagePreviewBrowserTasks].filter(
-        (task): task is AdminChatTaskRecord => task !== null,
-    );
+    const injectableTasks = await loadInjectableAdminChatTasks();
     const injectedTasks = collectAdminChatTasksToInject(injectableTasks, parsedQuery);
+    const databaseQuery = createInjectedAwareAdminChatTaskQuery(parsedQuery, injectedTasks.length);
+    const adminChatTasks = await getAdminChatTasks(databaseQuery);
     const { items, total } = mergeInjectedAdminChatTasks({
         databaseItems: adminChatTasks.items,
         databaseTotal: adminChatTasks.total,
         injectedTasks,
         page: parsedQuery.page,
         pageSize: parsedQuery.pageSize,
+        query: parsedQuery,
     });
     const counters = mergeInjectedAdminChatTaskCounters(adminChatTasks.counters, injectableTasks);
 
@@ -88,200 +87,10 @@ export async function getAdminChatTasksResponse(
             pageSize: parsedQuery.pageSize,
             view: parsedQuery.view,
             search: parsedQuery.search,
+            sortBy: parsedQuery.sortBy,
+            sortOrder: parsedQuery.sortOrder,
             timeWindowHours: parsedQuery.timeWindowHours,
             generatedAt: new Date().toISOString(),
         },
     };
 }
-
-/**
- * Loads the currently persisted standalone VPS self-update task, if any.
- *
- * The read is defensive so a corrupt status file cannot block the admin task manager from rendering.
- *
- * @returns Injectable task record or `null` when no self-update has ever been triggered on this server.
- */
-async function loadVpsSelfUpdateAdminChatTask(): Promise<AdminChatTaskRecord | null> {
-    try {
-        const jobSnapshot = await readVpsSelfUpdateJobSnapshot();
-        return mapVpsSelfUpdateJobToAdminChatTask(jobSnapshot);
-    } catch (error) {
-        console.error('[admin-chat-task] failed to load VPS self-update task snapshot', error);
-        return null;
-    }
-}
-
-/**
- * Filters out injected tasks that do not belong to the requested admin task-manager view or search.
- *
- * @param injectableTasks - Synthetic task rows collected from process-local state.
- * @param query - Parsed admin task-manager query.
- * @returns Tasks to inject on top of the database-backed items.
- */
-function collectAdminChatTasksToInject(
-    injectableTasks: ReadonlyArray<AdminChatTaskRecord>,
-    query: ParsedAdminChatTaskQuery,
-): ReadonlyArray<AdminChatTaskRecord> {
-    const nowTimestamp = Date.now();
-    return injectableTasks.filter(
-        (task) => matchesAdminChatTaskView(task, query, nowTimestamp) && matchesAdminChatTaskSearch(task, query.search),
-    );
-}
-
-/**
- * Prepends the injected task rows to the paginated database items so the self-update stays visible on page 1.
- *
- * @param options - Merge inputs.
- * @returns Merged items for the current page and the updated total row count.
- */
-function mergeInjectedAdminChatTasks(options: {
-    readonly databaseItems: ReadonlyArray<AdminChatTaskRecord>;
-    readonly databaseTotal: number;
-    readonly injectedTasks: ReadonlyArray<AdminChatTaskRecord>;
-    readonly page: number;
-    readonly pageSize: number;
-}): { items: Array<AdminChatTaskRecord>; total: number } {
-    const total = options.databaseTotal + options.injectedTasks.length;
-
-    if (options.injectedTasks.length === 0) {
-        return { items: [...options.databaseItems], total };
-    }
-
-    if (options.page !== 1) {
-        return { items: [...options.databaseItems], total };
-    }
-
-    const items = [...options.injectedTasks, ...options.databaseItems].slice(0, options.pageSize);
-    return { items, total };
-}
-
-/**
- * Adds injected tasks to the summary counters so the header metrics stay accurate.
- *
- * @param databaseCounters - Counters computed from durable database rows.
- * @param injectedTasks - Synthetic task rows collected from process-local state.
- * @returns Merged counters including the injected tasks.
- */
-function mergeInjectedAdminChatTaskCounters(
-    databaseCounters: AdminChatTaskCounters,
-    injectedTasks: ReadonlyArray<AdminChatTaskRecord>,
-): AdminChatTaskCounters {
-    if (injectedTasks.length === 0) {
-        return databaseCounters;
-    }
-
-    const nowTimestamp = Date.now();
-    const injectedQueuedTimestamps = injectedTasks
-        .filter((task) => task.status === 'QUEUED')
-        .map((task) => Date.parse(task.queuedAt))
-        .filter((timestamp) => Number.isFinite(timestamp));
-    const oldestInjectedQueuedAgeMs =
-        injectedQueuedTimestamps.length === 0 ? null : nowTimestamp - Math.min(...injectedQueuedTimestamps);
-
-    return {
-        runningCount: databaseCounters.runningCount + injectedTasks.filter((task) => task.status === 'RUNNING').length,
-        queuedCount: databaseCounters.queuedCount + injectedTasks.filter((task) => task.status === 'QUEUED').length,
-        failedLast24hCount:
-            databaseCounters.failedLast24hCount +
-            injectedTasks.filter(
-                (task) =>
-                    task.status === 'FAILED' &&
-                    isIsoTimestampAtOrAfter(task.finishedAt, nowTimestamp - 24 * HOUR_IN_MILLISECONDS),
-            ).length,
-        oldestQueuedAgeMs: mergeOldestQueuedAge(databaseCounters.oldestQueuedAgeMs, oldestInjectedQueuedAgeMs),
-    };
-}
-
-/**
- * Merges durable and injected queued-task ages.
- *
- * @param databaseOldestQueuedAgeMs - Oldest durable queued-task age.
- * @param injectedOldestQueuedAgeMs - Oldest injected queued-task age.
- * @returns Oldest queued age across both sources.
- */
-function mergeOldestQueuedAge(
-    databaseOldestQueuedAgeMs: number | null,
-    injectedOldestQueuedAgeMs: number | null,
-): number | null {
-    if (databaseOldestQueuedAgeMs === null) {
-        return injectedOldestQueuedAgeMs;
-    }
-
-    if (injectedOldestQueuedAgeMs === null) {
-        return databaseOldestQueuedAgeMs;
-    }
-
-    return Math.max(databaseOldestQueuedAgeMs, injectedOldestQueuedAgeMs);
-}
-
-/**
- * Returns whether the injected task belongs in the requested admin task-manager view.
- *
- * @param task - Injected task.
- * @param query - Parsed admin task-manager query.
- * @param nowTimestamp - Current epoch used for time-window filtering.
- * @returns `true` when the task should be included.
- */
-function matchesAdminChatTaskView(
-    task: AdminChatTaskRecord,
-    query: ParsedAdminChatTaskQuery,
-    nowTimestamp: number,
-): boolean {
-    switch (query.view) {
-        case 'running':
-            return task.status === 'RUNNING';
-        case 'queued':
-            return task.status === 'QUEUED';
-        case 'failed':
-            return (
-                task.status === 'FAILED' &&
-                isIsoTimestampAtOrAfter(task.finishedAt, nowTimestamp - 24 * HOUR_IN_MILLISECONDS)
-            );
-        case 'all':
-            return isIsoTimestampAtOrAfter(task.updatedAt, nowTimestamp - query.timeWindowHours * HOUR_IN_MILLISECONDS);
-        case 'active':
-        default:
-            return task.status === 'QUEUED' || task.status === 'RUNNING';
-    }
-}
-
-/**
- * Returns whether the injected task matches the free-text admin search input.
- *
- * @param task - Injected task.
- * @param search - Trimmed search text from the parsed query.
- * @returns `true` when the task should be included.
- */
-function matchesAdminChatTaskSearch(task: AdminChatTaskRecord, search: string): boolean {
-    if (!search) {
-        return true;
-    }
-
-    const normalizedSearch = search.toLowerCase();
-    if (task.id.toLowerCase().includes(normalizedSearch)) {
-        return true;
-    }
-    if (task.agentPermanentId.toLowerCase().includes(normalizedSearch)) {
-        return true;
-    }
-    if ((task.agentName || '').toLowerCase().includes(normalizedSearch)) {
-        return true;
-    }
-    return task.chatId.toLowerCase().includes(normalizedSearch);
-}
-
-/**
- * Returns whether one ISO timestamp is at or after the given cutoff.
- *
- * @param timestampIso - Optional ISO timestamp.
- * @param cutoffTimestamp - Epoch cutoff in milliseconds.
- * @returns `true` when the timestamp is at or after the cutoff.
- */
-function isIsoTimestampAtOrAfter(timestampIso: string | null, cutoffTimestamp: number): boolean {
-    if (!timestampIso) {
-        return false;
-    }
-
-    const timestamp = Date.parse(timestampIso);
-    return Number.isFinite(timestamp) && timestamp >= cutoffTimestamp;
-}

package/apps/agents-server/src/utils/getPagePreviewBrowserSessionState.ts

@@ -0,0 +1,41 @@
+import type { PagePreviewSessionState } from '../../../../src/book-components/Chat/Chat/pagePreview/PagePreviewSessionState';
+import type { PagePreviewBrowserSession } from './pagePreviewBrowserSessions';
+
+/**
+ * Reads the current navigation state of one live browser preview session.
+ *
+ * `canGoBack` / `canGoForward` are resolved from the CDP navigation history when the stream
+ * runs on a CDP screencast; otherwise they stay `null` and the preview toolbar keeps its
+ * history buttons enabled.
+ *
+ * @param session - Active browser preview session.
+ * @returns Session navigation state, or `null` when the session has no usable page.
+ *
+ * @private internal utility of Agents Server page-preview streaming
+ */
+export async function getPagePreviewBrowserSessionState(
+    session: PagePreviewBrowserSession,
+): Promise<PagePreviewSessionState | null> {
+    const page = session.page;
+    if (!page || page.isClosed()) {
+        return null;
+    }
+
+    const url = page.url();
+    const title = await page.title().catch(() => null);
+
+    let canGoBack: boolean | null = null;
+    let canGoForward: boolean | null = null;
+
+    if (session.cdpSession) {
+        try {
+            const navigationHistory = await session.cdpSession.send('Page.getNavigationHistory');
+            canGoBack = navigationHistory.currentIndex > 0;
+            canGoForward = navigationHistory.currentIndex < navigationHistory.entries.length - 1;
+        } catch {
+            // The CDP session may already be detached — the toolbar keeps its buttons enabled
+        }
+    }
+
+    return { url, title, canGoBack, canGoForward };
+}

package/apps/agents-server/src/utils/getVpsAdminChatTasksResponse.ts

@@ -0,0 +1,150 @@
+import { ensureUserChatTimeoutWorkerBootstrapped } from '@/src/utils/userChatTimeout/ensureUserChatTimeoutWorkerBootstrapped';
+import { mapRegisteredServerContexts } from '../tools/mapRegisteredServerContexts';
+import type { ServerRecord } from './serverRegistry';
+import type { AdminChatTaskCounters, AdminChatTaskListResponse, AdminChatTaskRecord } from './chatTasksAdmin';
+import type { GetAdminChatTasksResponseResult } from './getAdminChatTasksResponse';
+import {
+    addAdminChatTaskCounters,
+    collectAdminChatTasksToInject,
+    expandAdminChatTaskQueryToPageSpan,
+    loadInjectableAdminChatTasks,
+    mergeInjectedAdminChatTaskCounters,
+} from './getAdminChatTasksResponse/adminChatTaskInjection';
+import { getAdminChatTasks } from './getAdminChatTasksResponse/getAdminChatTasks';
+import { compareAdminChatTasks } from './getAdminChatTasksResponse/getAdminChatTasks/compareAdminChatTasks';
+import type { GetAdminChatTasksData } from './getAdminChatTasksResponse/getAdminChatTasks';
+import { parseAdminChatTaskQuery, type ParsedAdminChatTaskQuery } from './getAdminChatTasksResponse/parseAdminChatTaskQuery';
+
+/**
+ * Empty durable-task counters used as the accumulator when summing servers.
+ *
+ * @private function of `getVpsAdminChatTasksResponse`
+ */
+const EMPTY_ADMIN_CHAT_TASK_COUNTERS: AdminChatTaskCounters = {
+    runningCount: 0,
+    queuedCount: 0,
+    failedLast24hCount: 0,
+    oldestQueuedAgeMs: null,
+};
+
+/**
+ * Builds the paginated task-manager payload aggregated across **every** server on the VPS.
+ *
+ * This is the superadmin VPS-wide view. It loads each registered server's durable tasks inside that
+ * server's routing context (so per-server isolation is preserved), tags every row with its server,
+ * and merges them with the process-local VPS tasks (self-updates, browser previews) that are injected
+ * exactly once because they belong to the VPS rather than to any single server.
+ *
+ * @param searchParams - Task-manager query string shared with the per-server endpoint.
+ * @returns Aggregated, paginated VPS-wide task-manager payload.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function getVpsAdminChatTasksResponse(
+    searchParams: URLSearchParams,
+): Promise<GetAdminChatTasksResponseResult> {
+    const parsedQuery = parseAdminChatTaskQuery(searchParams);
+    if (!parsedQuery) {
+        return {
+            status: 400,
+            error: 'Invalid admin task query.',
+        };
+    }
+
+    ensureUserChatTimeoutWorkerBootstrapped();
+
+    const injectableTasks = await loadInjectableAdminChatTasks();
+    const injectedTasks = collectAdminChatTasksToInject(injectableTasks, parsedQuery);
+
+    // Note: Every server must return all rows up to the requested page, because the final global order
+    //       is only known once all servers and the injected VPS tasks are merged together.
+    const perServerQuery = expandAdminChatTaskQueryToPageSpan(parsedQuery);
+    const serverRuns = await mapRegisteredServerContexts((server) => loadServerAdminChatTasks(server, perServerQuery));
+
+    const databaseItems: Array<AdminChatTaskRecord> = [];
+    let databaseTotal = 0;
+    let databaseCounters = EMPTY_ADMIN_CHAT_TASK_COUNTERS;
+    for (const serverRun of serverRuns) {
+        databaseItems.push(...serverRun.value.items);
+        databaseTotal += serverRun.value.total;
+        databaseCounters = addAdminChatTaskCounters(databaseCounters, serverRun.value.counters);
+    }
+
+    const { items, total } = mergeVpsAdminChatTaskPage({
+        databaseItems,
+        databaseTotal,
+        injectedTasks,
+        query: parsedQuery,
+    });
+    const counters = mergeInjectedAdminChatTaskCounters(databaseCounters, injectableTasks);
+
+    return {
+        status: 200,
+        response: {
+            items,
+            counters,
+            total,
+            page: parsedQuery.page,
+            pageSize: parsedQuery.pageSize,
+            view: parsedQuery.view,
+            search: parsedQuery.search,
+            sortBy: parsedQuery.sortBy,
+            sortOrder: parsedQuery.sortOrder,
+            timeWindowHours: parsedQuery.timeWindowHours,
+            generatedAt: new Date().toISOString(),
+        } satisfies AdminChatTaskListResponse,
+    };
+}
+
+/**
+ * Loads one server's durable tasks and tags each row with that server.
+ *
+ * Runs inside the server's routing context established by `mapRegisteredServerContexts`.
+ *
+ * @param server - Registered server the tasks belong to, or `null` for the ambient context.
+ * @param query - Page-spanning query used for every server.
+ * @returns Server-tagged durable task data.
+ *
+ * @private function of `getVpsAdminChatTasksResponse`
+ */
+async function loadServerAdminChatTasks(
+    server: ServerRecord | null,
+    query: ParsedAdminChatTaskQuery,
+): Promise<GetAdminChatTasksData> {
+    const data = await getAdminChatTasks(query);
+
+    return {
+        ...data,
+        items: data.items.map((task) => ({
+            ...task,
+            serverName: server?.name ?? null,
+            serverDomain: server?.domain ?? null,
+        })),
+    };
+}
+
+/**
+ * Merges the injected VPS tasks with the server-tagged database rows and slices the requested page.
+ *
+ * Unlike the per-server merge, this always sorts and slices because the concatenated per-server rows
+ * have no meaningful order until merged.
+ *
+ * @param options - Merge inputs.
+ * @returns Merged items for the current page and the combined total row count.
+ *
+ * @private function of `getVpsAdminChatTasksResponse`
+ */
+function mergeVpsAdminChatTaskPage(options: {
+    readonly databaseItems: ReadonlyArray<AdminChatTaskRecord>;
+    readonly databaseTotal: number;
+    readonly injectedTasks: ReadonlyArray<AdminChatTaskRecord>;
+    readonly query: ParsedAdminChatTaskQuery;
+}): { items: Array<AdminChatTaskRecord>; total: number } {
+    const total = options.databaseTotal + options.injectedTasks.length;
+    const pageOffset = (options.query.page - 1) * options.query.pageSize;
+    const items = [...options.injectedTasks, ...options.databaseItems]
+        .sort((leftTask, rightTask) => compareAdminChatTasks(leftTask, rightTask, options.query))
+        .slice(pageOffset, pageOffset + options.query.pageSize);
+
+    return { items, total };
+}