@promptbook/cli 0.113.0-9 → 0.114.0-0

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

@@ -1,4 +1,7 @@
 import type { AgentsServerDatabase } from '../database/schema';
+import type { ChatHistoryThread } from './chatHistoryMessage';
+
+export type { ChatHistoryThread } from './chatHistoryMessage';
 
 /**
  * Type describing chat history row.
@@ -32,6 +35,8 @@ export type ChatHistoryListParams = {
     page?: number;
     pageSize?: number;
     agentName?: string;
+    chatId?: string;
+    userId?: number;
     search?: string;
     sortBy?: ChatHistorySortField;
     sortOrder?: ChatHistorySortOrder;
@@ -46,6 +51,8 @@ function buildQuery(params: ChatHistoryListParams): string {
     if (params.page && params.page > 0) searchParams.set('page', String(params.page));
     if (params.pageSize && params.pageSize > 0) searchParams.set('pageSize', String(params.pageSize));
     if (params.agentName) searchParams.set('agentName', params.agentName);
+    if (params.chatId) searchParams.set('chatId', params.chatId);
+    if (params.userId && params.userId > 0) searchParams.set('userId', String(params.userId));
     if (params.search) searchParams.set('search', params.search);
     if (params.sortBy) searchParams.set('sortBy', params.sortBy);
     if (params.sortOrder) searchParams.set('sortOrder', params.sortOrder);
@@ -74,6 +81,43 @@ export async function $fetchChatHistory(params: ChatHistoryListParams = {}): Pro
     return (await response.json()) as ChatHistoryListResponse;
 }
 
+/**
+ * Response for the chat history threads listing.
+ */
+export type ChatHistoryThreadsResponse = {
+    threads: ChatHistoryThread[];
+};
+
+/**
+ * Fetch the recorded chat threads (grouped by canonical chat id) from the admin API.
+ *
+ * Shared by the admin chat history filters and the chat transcript view so both
+ * browse conversations thread by thread instead of one mixed pile.
+ */
+export async function $fetchChatHistoryThreads(agentName?: string, userId?: number): Promise<ChatHistoryThread[]> {
+    const searchParams = new URLSearchParams();
+
+    if (agentName) {
+        searchParams.set('agentName', agentName);
+    }
+    if (userId && userId > 0) {
+        searchParams.set('userId', String(userId));
+    }
+
+    const qs = searchParams.toString();
+    const response = await fetch(`/api/chat-history/threads${qs ? `?${qs}` : ''}`, {
+        method: 'GET',
+    });
+
+    if (!response.ok) {
+        const data = await response.json().catch(() => ({}));
+        throw new Error(data.error || 'Failed to load chat threads');
+    }
+
+    const data = (await response.json()) as ChatHistoryThreadsResponse;
+    return data.threads ?? [];
+}
+
 /**
  * Clear chat history for a specific agent.
  */

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

@@ -0,0 +1,218 @@
+/**
+ * Maximum number of characters used for a generated chat thread title.
+ *
+ * @private constant of `createChatHistoryThreadTitle`
+ */
+const CHAT_HISTORY_THREAD_TITLE_MAX_LENGTH = 80;
+
+/**
+ * One raw `ChatHistory` row used when grouping recorded messages into chat threads.
+ *
+ * This is intentionally a minimal shape so it can be produced from a lightweight
+ * `select` and reused on both the server (grouping) and the client (typing).
+ */
+export type ChatHistoryThreadSourceRow = {
+    /**
+     * Numeric id of the recorded message.
+     */
+    readonly id: number;
+    /**
+     * ISO timestamp when the message was recorded.
+     */
+    readonly createdAt: string;
+    /**
+     * Name of the agent the message belongs to.
+     */
+    readonly agentName: string;
+    /**
+     * Canonical chat id (thread identifier) or `null` for legacy unthreaded rows.
+     */
+    readonly chatId: string | null;
+    /**
+     * Recorded message payload (role/sender/content or a raw string).
+     */
+    readonly message: unknown;
+};
+
+/**
+ * One recorded chat thread grouped from `ChatHistory` rows sharing the same `chatId`.
+ */
+export type ChatHistoryThread = {
+    /**
+     * Canonical chat id shared by every message of the thread.
+     */
+    readonly chatId: string;
+    /**
+     * Name of the agent the thread belongs to.
+     */
+    readonly agentName: string;
+    /**
+     * Human-readable title derived from the first user message of the thread.
+     */
+    readonly title: string;
+    /**
+     * Number of recorded messages in the thread.
+     */
+    readonly messageCount: number;
+    /**
+     * ISO timestamp of the first recorded message.
+     */
+    readonly firstMessageAt: string;
+    /**
+     * ISO timestamp of the last recorded message.
+     */
+    readonly lastMessageAt: string;
+};
+
+/**
+ * Resolves the sender used by `<Chat/>`/`<MockedChat/>` from one recorded message.
+ *
+ * @param message - Raw recorded message payload.
+ * @returns `USER` for user turns, `ASSISTANT` otherwise.
+ *
+ * @public shared by the admin chat-history views and the threads API
+ */
+export function resolveChatHistoryMessageSender(message: unknown): 'USER' | 'ASSISTANT' {
+    const role = ((message as { role?: string })?.role || 'USER').toUpperCase();
+    return role === 'USER' ? 'USER' : 'ASSISTANT';
+}
+
+/**
+ * Resolves the raw role label of one recorded message for the table view.
+ *
+ * @param message - Raw recorded message payload.
+ * @returns The stored role string, or `-` when it is missing.
+ *
+ * @public shared by the admin chat-history views
+ */
+export function resolveChatHistoryMessageRole(message: unknown): string {
+    if (!message || typeof message !== 'object') {
+        return '-';
+    }
+
+    return (message as { role?: string }).role || '-';
+}
+
+/**
+ * Extracts the full textual content of one recorded message.
+ *
+ * Supports raw strings, `{ content }`/`{ text }` objects and array content parts,
+ * falling back to a JSON serialization so nothing is silently dropped.
+ *
+ * @param message - Raw recorded message payload.
+ * @returns The message text (may be an empty string).
+ *
+ * @public shared by the admin chat-history views and the threads API
+ */
+export function resolveChatHistoryMessageText(message: unknown): string {
+    if (message == null) {
+        return '';
+    }
+
+    if (typeof message === 'string') {
+        return message;
+    }
+
+    if (typeof message === 'object') {
+        const content = (message as { content?: unknown }).content ?? (message as { text?: unknown }).text ?? message;
+
+        if (typeof content === 'string') {
+            return content;
+        }
+
+        if (Array.isArray(content)) {
+            return content.map((part) => (typeof part === 'string' ? part : JSON.stringify(part))).join(' ');
+        }
+
+        return JSON.stringify(content);
+    }
+
+    return String(message);
+}
+
+/**
+ * Builds a compact single-line title from one message text.
+ *
+ * @param text - Source message text.
+ * @returns A whitespace-collapsed, length-limited title.
+ *
+ * @public shared by the threads API and the admin chat-history views
+ */
+export function createChatHistoryThreadTitle(text: string): string {
+    const normalizedText = text.replace(/\s+/g, ' ').trim();
+
+    if (normalizedText.length === 0) {
+        return 'Untitled chat';
+    }
+
+    if (normalizedText.length > CHAT_HISTORY_THREAD_TITLE_MAX_LENGTH) {
+        return `${normalizedText.slice(0, CHAT_HISTORY_THREAD_TITLE_MAX_LENGTH)}…`;
+    }
+
+    return normalizedText;
+}
+
+/**
+ * Returns the epoch milliseconds of an ISO timestamp, or `0` when it cannot be parsed.
+ *
+ * @private utility of `groupChatHistoryThreads`
+ */
+function resolveTimestampMs(isoTimestamp: string): number {
+    const timestampMs = new Date(isoTimestamp).getTime();
+    return Number.isNaN(timestampMs) ? 0 : timestampMs;
+}
+
+/**
+ * Groups recorded `ChatHistory` rows into chat threads keyed by `chatId`.
+ *
+ * Rows without a `chatId` (legacy unthreaded messages) are ignored because they
+ * cannot be attributed to a single conversation. The returned threads are sorted
+ * by most recent activity first, and their title is taken from the first user
+ * message so the list reads like the chat sidebar.
+ *
+ * @param rows - Minimal `ChatHistory` rows to group.
+ * @returns Chat threads sorted by last activity descending.
+ *
+ * @public used by the threads API and covered by unit tests
+ */
+export function groupChatHistoryThreads(rows: ReadonlyArray<ChatHistoryThreadSourceRow>): ChatHistoryThread[] {
+    const rowsByChatId = new Map<string, ChatHistoryThreadSourceRow[]>();
+
+    for (const row of rows) {
+        if (!row.chatId) {
+            continue;
+        }
+
+        const bucket = rowsByChatId.get(row.chatId);
+        if (bucket) {
+            bucket.push(row);
+        } else {
+            rowsByChatId.set(row.chatId, [row]);
+        }
+    }
+
+    const threads: ChatHistoryThread[] = [];
+
+    for (const [chatId, bucketRows] of rowsByChatId) {
+        const orderedRows = [...bucketRows].sort(
+            (rowA, rowB) => resolveTimestampMs(rowA.createdAt) - resolveTimestampMs(rowB.createdAt),
+        );
+
+        const firstRow = orderedRows[0]!;
+        const lastRow = orderedRows[orderedRows.length - 1]!;
+        const titleRow = orderedRows.find((row) => resolveChatHistoryMessageSender(row.message) === 'USER') ?? firstRow;
+
+        threads.push({
+            chatId,
+            agentName: firstRow.agentName,
+            title: createChatHistoryThreadTitle(resolveChatHistoryMessageText(titleRow.message)),
+            messageCount: orderedRows.length,
+            firstMessageAt: firstRow.createdAt,
+            lastMessageAt: lastRow.createdAt,
+        });
+    }
+
+    threads.sort((threadA, threadB) => resolveTimestampMs(threadB.lastMessageAt) - resolveTimestampMs(threadA.lastMessageAt));
+
+    return threads;
+}

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

@@ -1,3 +1,4 @@
+import type { AgentMessageRunReport } from '../../../../src/book-3.0/AgentMessageRunReport';
 import type { UserChatJobStatus } from './userChat/UserChatJobRecord';
 
 /**
@@ -7,15 +8,37 @@ import type { UserChatJobStatus } from './userChat/UserChatJobRecord';
  */
 export type AdminChatTaskView = 'active' | 'running' | 'queued' | 'failed' | 'all';
 
+/**
+ * Sortable task-manager columns supported by the admin API.
+ *
+ * `default` keeps the operational order chosen for the active dashboard view.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type AdminChatTaskSortField = 'default' | 'task' | 'ownership' | 'timeline' | 'duration' | 'queue' | 'lastError';
+
+/**
+ * Sort direction supported by the admin task-manager API.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type AdminChatTaskSortOrder = 'asc' | 'desc';
+
 /**
  * Durable task kinds currently surfaced by the admin task manager.
  *
  * `VPS_SELF_UPDATE` represents a manual or automatic standalone VPS self-update session.
  * `BROWSER_PREVIEW` represents an ephemeral live browser stream used by citation previews.
+ * `VPS_SERVER_SETUP` represents VPS server bootstrap and certificate maintenance.
  *
  * @private internal admin utility of Agents Server
  */
-export type AdminChatTaskKind = 'CHAT_COMPLETION' | 'CHAT_TIMEOUT' | 'VPS_SELF_UPDATE' | 'BROWSER_PREVIEW';
+export type AdminChatTaskKind =
+    | 'CHAT_COMPLETION'
+    | 'CHAT_TIMEOUT'
+    | 'VPS_SELF_UPDATE'
+    | 'VPS_SERVER_SETUP'
+    | 'BROWSER_PREVIEW';
 
 /**
  * One row shown in the admin task-manager table.
@@ -48,6 +71,24 @@ export type AdminChatTaskRecord = {
     chatId: string;
     workerId: string | null;
     queueName: string | null;
+
+    /**
+     * Registered server this task belongs to, when the source task is bound to one server or the
+     * VPS-wide superadmin aggregation adds the owning server.
+     *
+     * `null` (or absent) means the per-server view, or a VPS-level task not bound to any one server.
+     */
+    serverName?: string | null;
+
+    /**
+     * Domain of the registered server this task belongs to, set only by the VPS-wide superadmin aggregation.
+     */
+    serverDomain?: string | null;
+
+    /**
+     * Harness run report of the answered turn (runner, model, Codex login method, usage), when the runner reported one.
+     */
+    runReport?: AgentMessageRunReport | null;
 };
 
 /**
@@ -75,6 +116,8 @@ export type AdminChatTaskListResponse = {
     pageSize: number;
     view: AdminChatTaskView;
     search: string;
+    sortBy: AdminChatTaskSortField;
+    sortOrder: AdminChatTaskSortOrder;
     timeWindowHours: number;
     generatedAt: string;
 };
@@ -89,6 +132,8 @@ export type AdminChatTaskListParams = {
     pageSize?: number;
     view?: AdminChatTaskView;
     search?: string;
+    sortBy?: AdminChatTaskSortField;
+    sortOrder?: AdminChatTaskSortOrder;
     timeWindowHours?: number;
 };
 
@@ -101,6 +146,17 @@ export type AdminChatTaskActionPayload = {
     reason: string;
 };
 
+/**
+ * Summary returned after bulk-cancelling every active durable chat task.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type CancelAllAdminChatTasksSummary = {
+    matchedCount: number;
+    cancelledCount: number;
+    hasMore: boolean;
+};
+
 /**
  * Builds the admin task-manager query string.
  *
@@ -121,6 +177,12 @@ function buildAdminChatTaskQuery(params: AdminChatTaskListParams): string {
     if (params.search) {
         searchParams.set('search', params.search);
     }
+    if (params.sortBy) {
+        searchParams.set('sortBy', params.sortBy);
+    }
+    if (params.sortOrder) {
+        searchParams.set('sortOrder', params.sortOrder);
+    }
     if (params.timeWindowHours && params.timeWindowHours > 0) {
         searchParams.set('timeWindowHours', String(params.timeWindowHours));
     }
@@ -147,19 +209,69 @@ export async function $fetchAdminChatTasks(params: AdminChatTaskListParams = {})
     return (await response.json()) as AdminChatTaskListResponse;
 }
 
+/**
+ * Fetches the paginated task-manager payload aggregated across every server on the VPS.
+ *
+ * Superadmin-only companion to `$fetchAdminChatTasks`; each task carries its `serverName`/`serverDomain`.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function $fetchVpsAdminChatTasks(
+    params: AdminChatTaskListParams = {},
+): Promise<AdminChatTaskListResponse> {
+    const response = await fetch(`/api/admin/vps/chat-tasks${buildAdminChatTaskQuery(params)}`, {
+        method: 'GET',
+    });
+
+    if (!response.ok) {
+        const payload = await response.json().catch(() => ({}));
+        throw new Error(payload.error || 'Failed to load VPS-wide background chat tasks.');
+    }
+
+    return (await response.json()) as AdminChatTaskListResponse;
+}
+
+/**
+ * Fetches one durable background task for the admin task detail page.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function $fetchAdminChatTask(taskId: string, serverDomain?: string | null): Promise<AdminChatTaskRecord> {
+    const response = await fetch(
+        `/api/admin/chat-tasks/${encodeURIComponent(taskId)}${buildServerDomainQuery(serverDomain)}`,
+        {
+            method: 'GET',
+        },
+    );
+
+    const payload = (await response.json().catch(() => ({}))) as { task?: AdminChatTaskRecord; error?: string };
+    if (!response.ok || !payload.task) {
+        throw new Error(payload.error || 'Failed to load the background task.');
+    }
+
+    return payload.task;
+}
+
 /**
  * Requests admin cancellation for one durable chat task.
  *
  * @private internal admin utility of Agents Server
  */
-export async function $cancelAdminChatTask(taskId: string, payload: AdminChatTaskActionPayload): Promise<void> {
-    const response = await fetch(`/api/admin/chat-tasks/${encodeURIComponent(taskId)}/cancel`, {
-        method: 'POST',
-        headers: {
-            'Content-Type': 'application/json',
+export async function $cancelAdminChatTask(
+    taskId: string,
+    payload: AdminChatTaskActionPayload,
+    serverDomain?: string | null,
+): Promise<void> {
+    const response = await fetch(
+        `/api/admin/chat-tasks/${encodeURIComponent(taskId)}/cancel${buildServerDomainQuery(serverDomain)}`,
+        {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(payload),
         },
-        body: JSON.stringify(payload),
-    });
+    );
 
     if (!response.ok) {
         const data = await response.json().catch(() => ({}));
@@ -172,8 +284,39 @@ export async function $cancelAdminChatTask(taskId: string, payload: AdminChatTas
  *
  * @private internal admin utility of Agents Server
  */
-export async function $retryAdminChatTask(taskId: string, payload: AdminChatTaskActionPayload): Promise<void> {
-    const response = await fetch(`/api/admin/chat-tasks/${encodeURIComponent(taskId)}/retry`, {
+export async function $retryAdminChatTask(
+    taskId: string,
+    payload: AdminChatTaskActionPayload,
+    serverDomain?: string | null,
+): Promise<void> {
+    const response = await fetch(
+        `/api/admin/chat-tasks/${encodeURIComponent(taskId)}/retry${buildServerDomainQuery(serverDomain)}`,
+        {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(payload),
+        },
+    );
+
+    if (!response.ok) {
+        const data = await response.json().catch(() => ({}));
+        throw new Error(data.error || 'Failed to retry task.');
+    }
+}
+
+/**
+ * Requests admin cancellation for every active durable chat task at once.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function $cancelAllAdminChatTasks(
+    payload: AdminChatTaskActionPayload,
+    isVpsScope = false,
+): Promise<CancelAllAdminChatTasksSummary> {
+    const cancelAllPath = isVpsScope ? '/api/admin/vps/chat-tasks/cancel-all' : '/api/admin/chat-tasks/cancel-all';
+    const response = await fetch(cancelAllPath, {
         method: 'POST',
         headers: {
             'Content-Type': 'application/json',
@@ -181,8 +324,29 @@ export async function $retryAdminChatTask(taskId: string, payload: AdminChatTask
         body: JSON.stringify(payload),
     });
 
+    const data = (await response.json().catch(() => ({}))) as Partial<CancelAllAdminChatTasksSummary> & {
+        error?: string;
+    };
+
     if (!response.ok) {
-        const data = await response.json().catch(() => ({}));
-        throw new Error(data.error || 'Failed to retry task.');
+        throw new Error(data.error || 'Failed to cancel all tasks.');
     }
+
+    return {
+        matchedCount: data.matchedCount ?? 0,
+        cancelledCount: data.cancelledCount ?? 0,
+        hasMore: data.hasMore ?? false,
+    };
+}
+
+/**
+ * Builds the optional owning-server query used by VPS-wide task actions.
+ *
+ * @param serverDomain - Owning server domain, when the task came from the VPS-wide listing.
+ * @returns Encoded query string or an empty string.
+ *
+ * @private function of Agents Server admin task utilities
+ */
+function buildServerDomainQuery(serverDomain?: string | null): string {
+    return serverDomain ? `?serverDomain=${encodeURIComponent(serverDomain)}` : '';
 }

package/apps/agents-server/src/utils/cloudflare/CloudflareApi.ts

@@ -0,0 +1,159 @@
+/**
+ * Cloudflare DNS records managed by Promptbook are never proxied.
+ *
+ * Both the domain sync and the Cloudflare DNS wizard need the original DNS target to stay visible, because Vercel
+ * matches on it and the Agents Server verifies that a hostname resolves directly to the VPS.
+ */
+export const CLOUDFLARE_DNS_RECORD_PROXIED = false;
+
+/**
+ * Cloudflare TTL `1` means automatic.
+ */
+export const CLOUDFLARE_DNS_RECORD_TTL_AUTOMATIC = 1;
+
+/**
+ * DNS record types for which Cloudflare offers a proxy-status choice.
+ */
+const CLOUDFLARE_PROXYABLE_DNS_RECORD_TYPES: ReadonlySet<string> = new Set(['A', 'AAAA', 'CNAME']);
+
+/**
+ * Cloudflare API configuration.
+ */
+export type CloudflareApiConfiguration = {
+    /**
+     * API token used for authentication.
+     */
+    readonly token: string;
+};
+
+/**
+ * Minimal Cloudflare zone metadata used for domain-to-zone matching.
+ */
+export type CloudflareZone = {
+    /**
+     * Cloudflare zone id.
+     */
+    readonly id: string;
+
+    /**
+     * Zone apex name.
+     */
+    readonly name: string;
+};
+
+/**
+ * Minimal Cloudflare DNS record payload.
+ */
+export type CloudflareDnsRecord = {
+    /**
+     * Cloudflare DNS record id.
+     */
+    readonly id: string;
+
+    /**
+     * DNS record type.
+     */
+    readonly type: string;
+
+    /**
+     * Fully qualified record name.
+     */
+    readonly name: string;
+
+    /**
+     * Record content or target.
+     */
+    readonly content: string;
+
+    /**
+     * Mail exchanger priority of `MX` records.
+     */
+    readonly priority?: number | null;
+
+    /**
+     * Whether the record is proxied through Cloudflare.
+     */
+    readonly proxied?: boolean | null;
+
+    /**
+     * Record TTL.
+     */
+    readonly ttl?: number | null;
+
+    /**
+     * Optional user-visible record comment.
+     */
+    readonly comment?: string | null;
+
+    /**
+     * Optional record tags.
+     */
+    readonly tags?: ReadonlyArray<string>;
+};
+
+/**
+ * One DNS record written to Cloudflare.
+ */
+export type CloudflareDnsRecordWriteInput = {
+    /**
+     * Zone id that contains the DNS record.
+     */
+    readonly zoneId: string;
+
+    /**
+     * DNS record type.
+     */
+    readonly type: string;
+
+    /**
+     * Fully qualified record name.
+     */
+    readonly name: string;
+
+    /**
+     * Record value as written in a zone file, for example `10 mail.example.com.` for an `MX` record.
+     */
+    readonly content: string;
+
+    /**
+     * Whether the record is proxied through Cloudflare.
+     */
+    readonly proxied: boolean;
+
+    /**
+     * Record TTL.
+     */
+    readonly ttl: number;
+
+    /**
+     * User-visible record comment marking the record as managed by Promptbook.
+     */
+    readonly comment: string;
+
+    /**
+     * Optional record tags.
+     */
+    readonly tags?: ReadonlyArray<string>;
+};
+
+/**
+ * Checks whether Cloudflare offers a proxy-status choice for one DNS record type.
+ *
+ * @param type - DNS record type.
+ * @returns `true` when the record can be proxied through Cloudflare.
+ */
+export function isProxyableCloudflareDnsRecordType(type: string): boolean {
+    return CLOUDFLARE_PROXYABLE_DNS_RECORD_TYPES.has(type.toUpperCase());
+}
+
+/**
+ * Normalizes one DNS record name for comparison between Cloudflare and the Agents Server DNS manual.
+ *
+ * Unlike generic domain normalization this keeps wildcard and underscore labels intact.
+ *
+ * @param name - Raw DNS record name.
+ * @returns Comparable record name.
+ */
+export function normalizeCloudflareDnsRecordName(name: string): string {
+    return name.trim().toLowerCase().replace(/\.$/, '');
+}