@promptbook/cli 0.113.0-8 → 0.114.0-0

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

@@ -0,0 +1,152 @@
+import { after } from 'next/server';
+import { cancelScheduledUserChatTimeout, getUserChatTimeoutById } from '@/src/utils/userChatTimeout';
+import {
+    getUserChatJobById,
+    persistUserChatJobTerminalState,
+    requestUserChatJobCancellation,
+    triggerUserChatJobWorker,
+} from '@/src/utils/userChat';
+import { runWithRegisteredServerContext } from '../tools/mapRegisteredServerContexts';
+
+/**
+ * Outcome of one admin-requested cancellation of a durable chat task.
+ *
+ * - `CANCELLED` — the task was queued/running and its cancellation was requested.
+ * - `ALREADY_FINISHED` — the task exists but already reached a terminal state.
+ * - `NOT_CANCELLABLE` — the task exists but its cancellation could not be persisted.
+ * - `NOT_FOUND` — no durable chat job or timeout matched the id.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type CancelAdminChatTaskOutcome = 'CANCELLED' | 'ALREADY_FINISHED' | 'NOT_CANCELLABLE' | 'NOT_FOUND';
+
+/**
+ * Inputs required to cancel one durable chat task on behalf of an administrator.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type CancelAdminChatTaskByIdOptions = {
+    /**
+     * Global id of the durable chat job or timeout to cancel.
+     */
+    taskId: string;
+
+    /**
+     * Human-readable actor recorded in the cancellation audit log.
+     */
+    actor: string;
+
+    /**
+     * Required operator-supplied reason recorded in the cancellation audit log.
+     */
+    reason: string;
+
+    /**
+     * Request origin used to wake the durable chat worker for running jobs.
+     */
+    requestOrigin: string;
+
+    /**
+     * Owning server domain for a VPS-wide task action.
+     */
+    serverDomain?: string | null;
+};
+
+/**
+ * Requests admin cancellation for one queued or running durable chat task.
+ *
+ * The function resolves the task as either a durable chat-completion job or a scheduled chat
+ * timeout, mirrors the single-task admin cancel semantics (immediately finalizing queued jobs
+ * and waking the worker for running jobs), and reports the resulting outcome to the caller.
+ *
+ * @param options - Task id, audit metadata, and request origin.
+ * @returns The cancellation outcome for the resolved task.
+ * @private internal admin utility of Agents Server
+ */
+export async function cancelAdminChatTaskById(options: CancelAdminChatTaskByIdOptions): Promise<CancelAdminChatTaskOutcome> {
+    if (options.serverDomain) {
+        const result = await runWithRegisteredServerContext(options.serverDomain, () =>
+            cancelAdminChatTaskByIdInCurrentServer(options),
+        );
+        return result ?? 'NOT_FOUND';
+    }
+
+    return cancelAdminChatTaskByIdInCurrentServer(options);
+}
+
+/**
+ * Requests cancellation against the server context already active for the current operation.
+ *
+ * @param options - Task id, audit metadata, and request origin.
+ * @returns The cancellation outcome for the resolved task.
+ *
+ * @private function of `cancelAdminChatTaskById`
+ */
+async function cancelAdminChatTaskByIdInCurrentServer(
+    options: CancelAdminChatTaskByIdOptions,
+): Promise<CancelAdminChatTaskOutcome> {
+    const { taskId, actor, reason, requestOrigin } = options;
+    const job = await getUserChatJobById(taskId);
+
+    if (job) {
+        if (job.status === 'COMPLETED' || job.status === 'FAILED' || job.status === 'CANCELLED') {
+            return 'ALREADY_FINISHED';
+        }
+
+        console.info('[admin-chat-task] cancel', {
+            actor,
+            taskId,
+            reason,
+            kind: 'CHAT_COMPLETION',
+            status: job.status,
+        });
+
+        const cancellationRequestedJob = await requestUserChatJobCancellation(taskId);
+        if (!cancellationRequestedJob) {
+            return 'NOT_CANCELLABLE';
+        }
+
+        if (job.status === 'QUEUED') {
+            await persistUserChatJobTerminalState({
+                job: cancellationRequestedJob,
+                status: 'CANCELLED',
+                failureReason: 'Chat generation was cancelled by an administrator before it started.',
+            });
+        } else {
+            after(() =>
+                triggerUserChatJobWorker({
+                    origin: requestOrigin,
+                    preferredJobId: taskId,
+                }).catch((error) =>
+                    console.error('[admin-chat-task] failed to wake worker after cancellation request', error),
+                ),
+            );
+        }
+
+        return 'CANCELLED';
+    }
+
+    const timeout = await getUserChatTimeoutById(taskId);
+    if (!timeout) {
+        return 'NOT_FOUND';
+    }
+
+    if (timeout.status === 'COMPLETED' || timeout.status === 'FAILED' || timeout.status === 'CANCELLED') {
+        return 'ALREADY_FINISHED';
+    }
+
+    console.info('[admin-chat-task] cancel', {
+        actor,
+        taskId,
+        reason,
+        kind: 'CHAT_TIMEOUT',
+        status: timeout.status,
+    });
+
+    const cancelledTimeout = await cancelScheduledUserChatTimeout(taskId);
+    if (!cancelledTimeout) {
+        return 'NOT_CANCELLABLE';
+    }
+
+    return 'CANCELLED';
+}

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

@@ -0,0 +1,199 @@
+import { cancelAdminChatTaskById } from '@/src/utils/cancelAdminChatTaskById';
+import { getAdminChatTasks } from '@/src/utils/getAdminChatTasksResponse/getAdminChatTasks';
+import { getVpsAdminChatTasksResponse } from '@/src/utils/getVpsAdminChatTasksResponse';
+import type { AdminChatTaskRecord } from '@/src/utils/chatTasksAdmin';
+import type { ParsedAdminChatTaskQuery } from '@/src/utils/getAdminChatTasksResponse/parseAdminChatTaskQuery';
+
+/**
+ * Number of active task rows loaded per page while collecting bulk cancellation targets.
+ *
+ * @private internal constant of `cancelAllActiveAdminChatTasks`
+ */
+const BULK_ADMIN_CHAT_TASK_PAGE_SIZE = 200;
+
+/**
+ * Hard cap for one bulk cancellation run.
+ *
+ * The cap protects runtime latency and prevents one admin action from cancelling an unbounded
+ * number of tasks in a single request.
+ *
+ * @private internal constant of `cancelAllActiveAdminChatTasks`
+ */
+const MAX_BULK_ADMIN_CHAT_TASK_CANCEL_TARGETS = 2_000;
+
+/**
+ * Summary returned after bulk-cancelling every active durable chat task.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type CancelAllActiveAdminChatTasksSummary = {
+    /**
+     * Number of active tasks that were selected for cancellation.
+     */
+    matchedCount: number;
+
+    /**
+     * Number of tasks whose cancellation was actually requested.
+     */
+    cancelledCount: number;
+
+    /**
+     * Whether more active tasks existed than the per-run cap allowed to cancel.
+     */
+    hasMore: boolean;
+};
+
+/**
+ * Inputs required to bulk-cancel every active durable chat task on behalf of an administrator.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type CancelAllActiveAdminChatTasksOptions = {
+    /**
+     * Human-readable actor recorded in the cancellation audit log.
+     */
+    actor: string;
+
+    /**
+     * Required operator-supplied reason recorded in the cancellation audit log.
+     */
+    reason: string;
+
+    /**
+     * Request origin used to wake the durable chat worker for running jobs.
+     */
+    requestOrigin: string;
+
+    /**
+     * Whether active tasks should be collected across every registered server on the VPS.
+     */
+    isVpsWide?: boolean;
+};
+
+/**
+ * Cancels every active (queued or running) durable chat task across all users.
+ *
+ * The active task ids are collected up front so cancellations do not shift the pagination window,
+ * then each task is cancelled by reusing the single-task admin cancellation flow.
+ *
+ * @param options - Audit metadata and request origin.
+ * @returns Summary counters describing how many active tasks were matched and cancelled.
+ * @private internal admin utility of Agents Server
+ */
+export async function cancelAllActiveAdminChatTasks(
+    options: CancelAllActiveAdminChatTasksOptions,
+): Promise<CancelAllActiveAdminChatTasksSummary> {
+    const collectedActiveTasks = await collectActiveAdminChatTasks(options.isVpsWide ?? false);
+    let cancelledCount = 0;
+
+    for (const task of collectedActiveTasks.tasks) {
+        const outcome = await cancelAdminChatTaskById({
+            taskId: task.id,
+            actor: options.actor,
+            reason: options.reason,
+            requestOrigin: options.requestOrigin,
+            serverDomain: task.serverDomain,
+        });
+
+        if (outcome === 'CANCELLED') {
+            cancelledCount += 1;
+        }
+    }
+
+    return {
+        matchedCount: collectedActiveTasks.tasks.length,
+        cancelledCount,
+        hasMore: collectedActiveTasks.hasMore,
+    };
+}
+
+/**
+ * Collects one bounded snapshot of active durable chat tasks for bulk cancellation.
+ *
+ * @returns The collected tasks and whether the per-run cap truncated them.
+ * @private function of `cancelAllActiveAdminChatTasks`
+ */
+async function collectActiveAdminChatTasks(isVpsWide: boolean): Promise<{
+    tasks: Array<AdminChatTaskRecord>;
+    hasMore: boolean;
+}> {
+    const collectedTasks: Array<AdminChatTaskRecord> = [];
+    let page = 1;
+    let totalActiveTaskCount = 0;
+
+    while (collectedTasks.length < MAX_BULK_ADMIN_CHAT_TASK_CANCEL_TARGETS) {
+        const activeTasks = isVpsWide
+            ? await getVpsAdminChatTasksResponse(createActiveAdminChatTaskSearchParams(page))
+            : {
+                  status: 200 as const,
+                  response: {
+                      ...(await getAdminChatTasks(createActiveAdminChatTaskQuery(page))),
+                      generatedAt: new Date().toISOString(),
+                  },
+              };
+
+        if (activeTasks.status !== 200) {
+            break;
+        }
+
+        const activeTaskPage = activeTasks.response;
+        totalActiveTaskCount = activeTaskPage.total;
+
+        if (activeTaskPage.items.length === 0) {
+            break;
+        }
+
+        collectedTasks.push(...activeTaskPage.items);
+
+        if (collectedTasks.length >= totalActiveTaskCount) {
+            break;
+        }
+
+        page += 1;
+    }
+
+    const cappedTasks = collectedTasks.slice(0, MAX_BULK_ADMIN_CHAT_TASK_CANCEL_TARGETS);
+
+    return {
+        tasks: cappedTasks,
+        hasMore: totalActiveTaskCount > cappedTasks.length,
+    };
+}
+
+/**
+ * Converts the normalized active-task query into the URL-search format used by the VPS listing.
+ *
+ * @param page - One-based page number.
+ * @returns Search parameters for the VPS-wide task listing.
+ *
+ * @private function of `cancelAllActiveAdminChatTasks`
+ */
+function createActiveAdminChatTaskSearchParams(page: number): URLSearchParams {
+    const searchParams = new URLSearchParams();
+    const query = createActiveAdminChatTaskQuery(page);
+
+    for (const [key, value] of Object.entries(query)) {
+        searchParams.set(key, String(value));
+    }
+
+    return searchParams;
+}
+
+/**
+ * Builds the admin task query used to page through active durable chat tasks.
+ *
+ * @param page - One-based page number to load.
+ * @returns Parsed admin task query scoped to the active view.
+ * @private function of `cancelAllActiveAdminChatTasks`
+ */
+function createActiveAdminChatTaskQuery(page: number): ParsedAdminChatTaskQuery {
+    return {
+        page,
+        pageSize: BULK_ADMIN_CHAT_TASK_PAGE_SIZE,
+        view: 'active',
+        search: '',
+        sortBy: 'default',
+        sortOrder: 'desc',
+        timeWindowHours: 24,
+    };
+}

package/apps/agents-server/src/utils/chat/createAttachmentAwareCitationLabelResolver.ts

@@ -0,0 +1,147 @@
+'use client';
+
+import type { CitationLabelResolver, ChatMessage, ParsedCitation } from '@promptbook-local/types';
+import { resolveAgentsServerCitationLabel } from './resolveAgentsServerCitationLabel';
+
+/**
+ * Pattern matching trailing punctuation a model may append after a cited URL.
+ *
+ * @private utility constant of Agents Server chat citations
+ */
+const TRAILING_URL_PUNCTUATION_REGEX = /[.,;:!?)\]]+$/;
+
+/**
+ * Creates a citation-label resolver that prefers original chat attachment filenames.
+ *
+ * Attached images and files are cited by their CDN URL, but that URL only carries
+ * a normalized (kebab-cased) filename, so the shared resolver would otherwise fetch
+ * the binary and show unreadable content. This resolver maps a citation whose URL
+ * points to one of the chat attachments back to the attachment's original `name`
+ * (for example `DSC_0139 (2).JPG`) and delegates every other citation to
+ * `resolveAgentsServerCitationLabel`.
+ *
+ * @param messages - Chat messages whose attachments provide the original filenames.
+ * @returns Resolver returning the attachment filename, or the shared server label.
+ *
+ * @private utility of Agents Server chat citations
+ */
+export function createAttachmentAwareCitationLabelResolver(
+    messages: ReadonlyArray<ChatMessage>,
+): CitationLabelResolver {
+    const attachmentNamesByUrlKey = collectAttachmentNamesByUrlKey(messages);
+
+    return async (citation) => {
+        const attachmentName = resolveAttachmentNameForCitation(citation, attachmentNamesByUrlKey);
+        if (attachmentName) {
+            return attachmentName;
+        }
+
+        return resolveAgentsServerCitationLabel(citation);
+    };
+}
+
+/**
+ * Builds a lookup from normalized attachment URL to the original attachment filename.
+ *
+ * @param messages - Chat messages that may carry file attachments.
+ * @returns Map keyed by normalized attachment URL with the original filename as value.
+ *
+ * @private utility of Agents Server chat citations
+ */
+function collectAttachmentNamesByUrlKey(messages: ReadonlyArray<ChatMessage>): Map<string, string> {
+    const attachmentNamesByUrlKey = new Map<string, string>();
+
+    for (const message of messages) {
+        for (const attachment of message.attachments ?? []) {
+            const attachmentUrlKey = normalizeAttachmentUrlKey(attachment.url);
+            const attachmentName = attachment.name.trim();
+
+            if (attachmentUrlKey && attachmentName && !attachmentNamesByUrlKey.has(attachmentUrlKey)) {
+                attachmentNamesByUrlKey.set(attachmentUrlKey, attachmentName);
+            }
+        }
+    }
+
+    return attachmentNamesByUrlKey;
+}
+
+/**
+ * Resolves the original filename for one citation when it points to a known attachment.
+ *
+ * @param citation - Citation whose `url`/`source` may reference an attachment.
+ * @param attachmentNamesByUrlKey - Lookup produced by `collectAttachmentNamesByUrlKey`.
+ * @returns Original attachment filename or `null` when the citation is not an attachment.
+ *
+ * @private utility of Agents Server chat citations
+ */
+function resolveAttachmentNameForCitation(
+    citation: ParsedCitation,
+    attachmentNamesByUrlKey: Map<string, string>,
+): string | null {
+    if (attachmentNamesByUrlKey.size === 0) {
+        return null;
+    }
+
+    for (const citationTarget of [citation.url, citation.source]) {
+        if (!citationTarget) {
+            continue;
+        }
+
+        const citationUrlKey = normalizeAttachmentUrlKey(citationTarget);
+        if (!citationUrlKey) {
+            continue;
+        }
+
+        const attachmentName = attachmentNamesByUrlKey.get(citationUrlKey);
+        if (attachmentName) {
+            return attachmentName;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Normalizes an attachment/citation URL into a stable comparison key.
+ *
+ * Only the origin and decoded pathname are compared so that citations reproduced
+ * by the model still match regardless of query strings or trailing punctuation.
+ *
+ * @param rawUrl - Raw URL value from an attachment or citation.
+ * @returns Comparison key, or `null` when the value is not an HTTP(S) URL.
+ *
+ * @private utility of Agents Server chat citations
+ */
+function normalizeAttachmentUrlKey(rawUrl: string): string | null {
+    const trimmedUrl = rawUrl.trim().replace(TRAILING_URL_PUNCTUATION_REGEX, '');
+    if (!trimmedUrl) {
+        return null;
+    }
+
+    try {
+        const url = new URL(trimmedUrl);
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            return null;
+        }
+
+        return `${url.origin}${decodeUrlPathnameSafely(url.pathname)}`;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Safely decodes a URL pathname, falling back to the raw value on malformed input.
+ *
+ * @param pathname - Raw URL pathname.
+ * @returns Decoded pathname or the original value when decoding fails.
+ *
+ * @private utility of Agents Server chat citations
+ */
+function decodeUrlPathnameSafely(pathname: string): string {
+    try {
+        return decodeURIComponent(pathname);
+    } catch {
+        return pathname;
+    }
+}

package/apps/agents-server/src/utils/chat/createChatHistoryRecorder.ts

@@ -23,7 +23,7 @@ type ChatHistoryInsertError = {
 /**
  * Source value for chat-history records.
  */
-export type ChatHistorySource = NonNullable<ChatHistoryInsert['source']>;
+export type ChatHistorySource = NonNullable<ChatHistoryInsert['source']> | 'EMAIL';
 
 /**
  * Actor type value for chat-history records.
@@ -35,9 +35,12 @@ export type ChatHistoryActorType = NonNullable<ChatHistoryInsert['actorType']>;
  */
 export type CreateChatHistoryRecorderOptions = {
     /**
-     * HTTP request that carries telemetry headers and URL.
+     * Optional HTTP request that carries telemetry headers and URL.
+     *
+     * Server-side callers (for example durable chat-job workers) have no request,
+     * telemetry columns stay `null` for them.
      */
-    request: Request;
+    request?: Request | null;
     /**
      * Agent route identifier (`agentName` or `permanentId`).
      */
@@ -62,6 +65,10 @@ export type CreateChatHistoryRecorderOptions = {
      * Optional database user id responsible for the call.
      */
     userId?: number | null;
+    /**
+     * Optional id of the canonical `UserChat` the recorded messages belong to.
+     */
+    chatId?: string | null;
     /**
      * When false, recorder computes hashes but skips DB writes.
      */
@@ -84,6 +91,10 @@ export type RecordChatHistoryMessageOptions = {
      * Optional usage tracking statistics.
      */
     usage?: ChatHistoryInsert['usage'];
+    /**
+     * Optional id of the durable chat-completion task (`UserChatJob`) linked to this message.
+     */
+    taskId?: string | null;
 };
 
 /**
@@ -94,7 +105,7 @@ export type RecordChatHistoryMessage = (options: RecordChatHistoryMessageOptions
 /**
  * Optional columns that may be missing on partially migrated databases.
  */
-const CHAT_HISTORY_OPTIONAL_COLUMNS = ['source', 'apiKey', 'actorType', 'usage', 'userId'] as const;
+const CHAT_HISTORY_OPTIONAL_COLUMNS = ['source', 'apiKey', 'actorType', 'usage', 'userId', 'chatId', 'taskId'] as const;
 
 /**
  * Optional chat-history columns that may be unavailable before migrations are applied.
@@ -108,26 +119,32 @@ export async function createChatHistoryRecorder(
     options: CreateChatHistoryRecorderOptions,
 ): Promise<RecordChatHistoryMessage> {
     const {
-        request,
+        request = null,
         agentIdentifier,
         agentHash,
         source,
         apiKey = null,
         actorType,
         userId = null,
+        chatId = null,
         isEnabled = true,
     } = options;
     const supabase = $provideSupabaseForServer();
     const tableName = await $getTableName('ChatHistory');
-    const userAgent = request.headers.get('user-agent');
-    const ip = resolveIpAddress(request);
-    const language = request.headers.get('accept-language');
+    const userAgent = request ? request.headers.get('user-agent') : null;
+    const ip = request ? resolveIpAddress(request) : null;
+    const language = request ? request.headers.get('accept-language') : null;
     const platform = resolvePlatform(userAgent);
     const resolvedActorType = actorType ?? inferActorType({ request, apiKey });
     const canonicalAgentName = isEnabled ? await resolveCanonicalAgentName(agentIdentifier) : null;
     const agentNameForInsert = canonicalAgentName || agentIdentifier;
 
-    return async ({ message, previousMessageHash = null, usage = null }: RecordChatHistoryMessageOptions): Promise<string> => {
+    return async ({
+        message,
+        previousMessageHash = null,
+        usage = null,
+        taskId = null,
+    }: RecordChatHistoryMessageOptions): Promise<string> => {
         const messageHash = computeHash(message);
         if (!isEnabled) {
             return messageHash;
@@ -141,16 +158,18 @@ export async function createChatHistoryRecorder(
             agentHash,
             message,
             promptbookEngineVersion: PROMPTBOOK_ENGINE_VERSION,
-            url: request.url,
+            url: request ? request.url : null,
             ip,
             userAgent,
             language,
             platform,
-            source,
+            source: source as ChatHistoryInsert['source'],
             apiKey,
             actorType: resolvedActorType,
             usage,
             userId,
+            chatId,
+            taskId,
         };
 
         const { error } = await supabase.from(tableName).insert(row);
@@ -231,7 +250,7 @@ function resolvePlatform(userAgent: string | null): string | null {
  * Infers actor type from request auth context.
  */
 function inferActorType(options: {
-    request: Request;
+    request: Request | null;
     apiKey: string | null;
 }): ChatHistoryActorType {
     const { request, apiKey } = options;
@@ -239,7 +258,7 @@ function inferActorType(options: {
         return 'API_KEY';
     }
 
-    const cookieHeader = request.headers.get('cookie') || '';
+    const cookieHeader = request?.headers.get('cookie') || '';
     if (/(^|;\s*)(sessionToken|adminToken)=/.test(cookieHeader)) {
         return 'TEAM_MEMBER';
     }