@promptbook/cli 0.113.0-9 → 0.114.0-0

package/apps/agents-server/src/utils/mockedChats/createMockedChatPresetFromChatMessages.ts

@@ -0,0 +1,143 @@
+import {
+    createMockedChatId,
+    createMockedChatMessageId,
+    DEFAULT_MESSAGE_OFFSET_STEP_MS,
+    MAX_MOCKED_CHAT_MESSAGE_CONTENT_LENGTH,
+    MAX_MOCKED_CHAT_MESSAGES,
+    MAX_MOCKED_CHAT_NAME_LENGTH,
+    type MockedChatPreset,
+} from '@/src/utils/mockedChatsSchema';
+
+/**
+ * Longest playback gap kept between two recorded messages.
+ *
+ * Real chats can have hours between messages, replaying that verbatim would freeze the mock.
+ *
+ * @private constant of `createMockedChatPresetFromChatMessages`
+ */
+const MAX_MESSAGE_OFFSET_GAP_MS = 8_000;
+
+/**
+ * Participant id used for user-authored messages in generated presets.
+ *
+ * @private constant of `createMockedChatPresetFromChatMessages`
+ */
+const USER_PARTICIPANT_ID = 'USER';
+
+/**
+ * Participant id used for agent-authored messages in generated presets.
+ *
+ * @private constant of `createMockedChatPresetFromChatMessages`
+ */
+const ASSISTANT_PARTICIPANT_ID = 'ASSISTANT';
+
+/**
+ * One generic source message used to seed a mocked-chat preset.
+ */
+export type MockedChatSourceMessage = {
+    /**
+     * Message author; `USER` maps to the "me" participant, anything else to the assistant.
+     */
+    sender: string;
+    /**
+     * Plain-text message content.
+     */
+    content: string;
+    /**
+     * Optional creation timestamp used to derive playback offsets.
+     */
+    createdAt?: string | null;
+};
+
+/**
+ * Builds one mocked-chat preset from recorded chat messages.
+ *
+ * Shared by the admin chat-history page and the external-chat view so both
+ * "Create mock" buttons produce identical presets (DRY).
+ */
+export function createMockedChatPresetFromChatMessages(options: {
+    name: string;
+    messages: ReadonlyArray<MockedChatSourceMessage>;
+}): MockedChatPreset {
+    const nowIso = new Date().toISOString();
+    const limitedMessages = options.messages
+        .filter((message) => message.content.trim().length > 0)
+        .slice(0, MAX_MOCKED_CHAT_MESSAGES);
+
+    return {
+        id: createMockedChatId(),
+        name: options.name.slice(0, MAX_MOCKED_CHAT_NAME_LENGTH) || 'Recorded chat',
+        createdAt: nowIso,
+        updatedAt: nowIso,
+        participants: [
+            {
+                id: USER_PARTICIPANT_ID,
+                name: 'You',
+                isMe: true,
+                bubbleColor: '#0f766e',
+                avatarUrl: null,
+                typingAvatarUrl: null,
+            },
+            {
+                id: ASSISTANT_PARTICIPANT_ID,
+                name: 'Assistant',
+                isMe: false,
+                bubbleColor: '#2563eb',
+                avatarUrl: null,
+                typingAvatarUrl: null,
+            },
+        ],
+        messages: limitedMessages.map((message, messageIndex) => ({
+            id: createMockedChatMessageId(),
+            senderId: isUserSender(message.sender) ? USER_PARTICIPANT_ID : ASSISTANT_PARTICIPANT_ID,
+            content: message.content.slice(0, MAX_MOCKED_CHAT_MESSAGE_CONTENT_LENGTH),
+            offsetMs: resolveMessageOffsetMs(limitedMessages, messageIndex),
+        })),
+        settings: {
+            timingPreset: 'NORMAL',
+            loopPlayback: false,
+            viewportPreset: 'LAPTOP',
+            showTimestamps: true,
+            backgroundColor: '#f8fafc',
+            backgroundImageUrl: null,
+        },
+    };
+}
+
+/**
+ * Checks whether the sender represents the human user.
+ *
+ * @private function of `createMockedChatPresetFromChatMessages`
+ */
+function isUserSender(sender: string): boolean {
+    return sender.toUpperCase() === 'USER';
+}
+
+/**
+ * Derives one playback offset from recorded timestamps with a sane maximum gap.
+ *
+ * @private function of `createMockedChatPresetFromChatMessages`
+ */
+function resolveMessageOffsetMs(messages: ReadonlyArray<MockedChatSourceMessage>, messageIndex: number): number {
+    if (messageIndex === 0) {
+        return 0;
+    }
+
+    let offsetMs = 0;
+    for (let index = 1; index <= messageIndex; index++) {
+        const previousTimestamp = Date.parse(messages[index - 1]?.createdAt || '');
+        const currentTimestamp = Date.parse(messages[index]?.createdAt || '');
+        const gapMs =
+            Number.isFinite(previousTimestamp) && Number.isFinite(currentTimestamp)
+                ? currentTimestamp - previousTimestamp
+                : Number.NaN;
+
+        if (Number.isFinite(gapMs) && gapMs >= 0) {
+            offsetMs += Math.min(gapMs, MAX_MESSAGE_OFFSET_GAP_MS);
+        } else {
+            offsetMs += DEFAULT_MESSAGE_OFFSET_STEP_MS;
+        }
+    }
+
+    return offsetMs;
+}

package/apps/agents-server/src/utils/mockedChatsSchema/normalizeMockedChatPreset.ts

@@ -96,9 +96,10 @@ function normalizeMockedChatParticipants(value: unknown): Array<MockedChatPartic
         };
     });
 
-    if (!uniqueParticipants.some((participant) => participant.isMe)) {
+    const firstParticipant = uniqueParticipants[0];
+    if (firstParticipant && !uniqueParticipants.some((participant) => participant.isMe)) {
         uniqueParticipants[0] = {
-            ...uniqueParticipants[0],
+            ...firstParticipant,
             isMe: true,
         };
     }

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

@@ -1,22 +1,13 @@
-import type { Page } from 'playwright';
+import type { CDPSession, Page } from 'playwright';
+import {
+    PAGE_PREVIEW_SESSION_ID_PATTERN,
+    PAGE_PREVIEW_SESSION_ID_PREFIX,
+} from '../../../../src/book-components/Chat/Chat/pagePreview/createPagePreviewSessionId';
+import type { PagePreviewViewport } from '../../../../src/book-components/Chat/Chat/pagePreview/PagePreviewViewport';
 import type { AdminChatTaskRecord } from './chatTasksAdmin';
 import type { UserInfo } from './getCurrentUser';
 import { appendTaskTerminalLogLine, markTaskTerminalLogFinished } from './taskTerminal/taskTerminalLog';
 
-/**
- * Prefix for browser-preview session identifiers created by the citation preview UI.
- *
- * @private internal constant of Agents Server page-preview streaming
- */
-const PAGE_PREVIEW_BROWSER_SESSION_ID_PREFIX = 'page-preview-';
-
-/**
- * Pattern accepted for client-created page-preview session identifiers.
- *
- * @private internal constant of Agents Server page-preview streaming
- */
-const PAGE_PREVIEW_BROWSER_SESSION_ID_PATTERN = /^page-preview-[a-z0-9-]{16,80}$/;
-
 /**
  * Queue name used when active browser previews are surfaced in the admin task manager.
  *
@@ -45,19 +36,38 @@ export type PagePreviewBrowserSession = {
     readonly startedAt: string;
     readonly processId: number | null;
     page: Page | null;
-    viewport: PagePreviewBrowserViewport | null;
+    viewport: PagePreviewViewport | null;
+    cdpSession: CDPSession | null;
+    applyViewport: ((viewport: PagePreviewViewport) => Promise<void>) | null;
     updatedAt: string;
     lastFrameAt: string | null;
 };
 
 /**
- * Browser viewport used to convert pointer ratios into Playwright coordinates.
+ * Live page attachment of one browser preview stream.
  *
  * @private internal type of Agents Server page-preview streaming
  */
-export type PagePreviewBrowserViewport = {
-    readonly width: number;
-    readonly height: number;
+export type AttachPagePreviewBrowserSessionPageOptions = {
+    /**
+     * Playwright page bound to the stream.
+     */
+    readonly page: Page;
+
+    /**
+     * Viewport used by the stream.
+     */
+    readonly viewport: PagePreviewViewport;
+
+    /**
+     * CDP session used for screencasting and navigation-history lookups, when available.
+     */
+    readonly cdpSession?: CDPSession | null;
+
+    /**
+     * Applies a new viewport to the running stream (resizes the page and restarts the screencast).
+     */
+    readonly applyViewport?: (viewport: PagePreviewViewport) => Promise<void>;
 };
 
 /**
@@ -93,7 +103,7 @@ export function normalizePagePreviewBrowserSessionId(requestedSessionId: string
     }
 
     const normalizedSessionId = requestedSessionId.trim().toLowerCase();
-    return PAGE_PREVIEW_BROWSER_SESSION_ID_PATTERN.test(normalizedSessionId) ? normalizedSessionId : null;
+    return PAGE_PREVIEW_SESSION_ID_PATTERN.test(normalizedSessionId) ? normalizedSessionId : null;
 }
 
 /**
@@ -123,6 +133,8 @@ export function registerPagePreviewBrowserSession(
         processId: typeof process.pid === 'number' ? process.pid : null,
         page: null,
         viewport: null,
+        cdpSession: null,
+        applyViewport: null,
     };
 
     pagePreviewBrowserSessions.set(options.sessionId, session);
@@ -137,28 +149,44 @@ export function registerPagePreviewBrowserSession(
  * Attaches the Playwright page used by one live browser preview.
  *
  * @param sessionId - Active session id.
- * @param page - Playwright page bound to the stream.
- * @param viewport - Viewport used by the stream.
+ * @param options - Live page attachment.
  */
 export function attachPagePreviewBrowserSessionPage(
     sessionId: string,
-    page: Page,
-    viewport: PagePreviewBrowserViewport,
+    options: AttachPagePreviewBrowserSessionPageOptions,
 ): void {
     const session = pagePreviewBrowserSessions.get(sessionId);
     if (!session) {
         return;
     }
 
-    session.page = page;
-    session.viewport = viewport;
+    session.page = options.page;
+    session.viewport = options.viewport;
+    session.cdpSession = options.cdpSession ?? null;
+    session.applyViewport = options.applyViewport ?? null;
     session.updatedAt = new Date().toISOString();
     appendTaskTerminalLogLine(
         sessionId,
-        `Browser page attached with a ${viewport.width}x${viewport.height} viewport, streaming frames.`,
+        `Browser page attached with a ${options.viewport.width}x${options.viewport.height} viewport, streaming frames.`,
     );
 }
 
+/**
+ * Updates the viewport recorded for one live browser preview.
+ *
+ * @param sessionId - Active session id.
+ * @param viewport - New viewport of the streamed page.
+ */
+export function updatePagePreviewBrowserSessionViewport(sessionId: string, viewport: PagePreviewViewport): void {
+    const session = pagePreviewBrowserSessions.get(sessionId);
+    if (!session) {
+        return;
+    }
+
+    session.viewport = viewport;
+    session.updatedAt = new Date().toISOString();
+}
+
 /**
  * Marks that one stream frame has been delivered.
  *
@@ -237,7 +265,7 @@ export function listPagePreviewBrowserAdminTasks(): Array<AdminChatTaskRecord> {
         lastErrorDetails: session.url,
         userId: session.userId,
         username: session.username,
-        agentPermanentId: PAGE_PREVIEW_BROWSER_SESSION_ID_PREFIX,
+        agentPermanentId: PAGE_PREVIEW_SESSION_ID_PREFIX,
         agentName: PAGE_PREVIEW_BROWSER_TASK_AGENT_NAME,
         chatId: session.url,
         workerId: session.processId === null ? null : String(session.processId),

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

@@ -0,0 +1,20 @@
+/**
+ * Parses a positive numeric user id from an optional query-string value.
+ *
+ * @param value - Raw user id value.
+ * @returns A positive user id, or `null` when the value is missing or invalid.
+ *
+ * @private shared by admin user-scoped API routes
+ */
+export function parsePositiveUserId(value: string | null): number | null {
+    if (!value) {
+        return null;
+    }
+
+    if (!/^\d+$/u.test(value)) {
+        return null;
+    }
+
+    const parsedUserId = Number.parseInt(value, 10);
+    return Number.isFinite(parsedUserId) && parsedUserId > 0 ? parsedUserId : null;
+}

package/apps/agents-server/src/utils/pdf/getPromptbookLogoDataUrl.ts

@@ -0,0 +1,40 @@
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+
+/**
+ * Public asset used as the Promptbook mark in server-rendered exports.
+ *
+ * @private internal constant of `getPromptbookLogoDataUrl`
+ */
+const PROMPTBOOK_LOGO_ASSET_PATH = ['public', 'logo-blue-white-256.png'];
+
+/**
+ * Cached data URL, so repeated exports do not re-read the asset.
+ *
+ * @private internal state of `getPromptbookLogoDataUrl`
+ */
+let promptbookLogoDataUrl: string | null | undefined;
+
+/**
+ * Loads the Promptbook logo as an inline `data:` URL.
+ *
+ * The PDF renderer blocks every network request, therefore branding assets must
+ * be embedded directly into the exported document.
+ *
+ * @returns Inline logo URL, or `null` when the asset is unavailable.
+ */
+export async function getPromptbookLogoDataUrl(): Promise<string | null> {
+    if (promptbookLogoDataUrl !== undefined) {
+        return promptbookLogoDataUrl;
+    }
+
+    try {
+        const logo = await readFile(join(process.cwd(), ...PROMPTBOOK_LOGO_ASSET_PATH));
+        promptbookLogoDataUrl = `data:image/png;base64,${logo.toString('base64')}`;
+    } catch (error) {
+        console.error('Failed to inline the Promptbook logo into a PDF export:', error);
+        promptbookLogoDataUrl = null;
+    }
+
+    return promptbookLogoDataUrl;
+}

package/apps/agents-server/src/utils/pdf/renderHtmlToPdfOnServer.ts

@@ -0,0 +1,86 @@
+import { createServerChromiumLaunchOptions } from '@/src/tools/createServerChromiumLaunchOptions';
+import { chromium } from 'playwright';
+
+/**
+ * URL protocols that can be allowed through the PDF renderer request
+ * interception because they cannot reach a server-side network destination.
+ */
+const PDF_RENDERER_ALLOWED_REQUEST_PROTOCOLS = new Set(['about:', 'data:']);
+
+/**
+ * Browser viewport used while rendering standalone HTML exports to PDF.
+ */
+const PDF_RENDERER_VIEWPORT = {
+    width: 1280,
+    height: 1600,
+} as const;
+
+/**
+ * Page margins applied to every exported PDF page.
+ */
+const PDF_RENDERER_MARGIN = {
+    top: '0.5in',
+    right: '0.5in',
+    bottom: '0.5in',
+    left: '0.5in',
+} as const;
+
+/**
+ * Prints standalone HTML into a PDF using a short-lived headless Chromium instance.
+ *
+ * @param html - Fully rendered standalone HTML document.
+ * @returns PDF bytes ready for an HTTP response.
+ */
+export async function renderHtmlToPdfOnServer(html: string): Promise<Buffer> {
+    const browser = await chromium.launch(await createServerChromiumLaunchOptions());
+
+    try {
+        const page = await browser.newPage();
+
+        try {
+            await page.route('**/*', async (route) => {
+                const requestUrl = route.request().url();
+
+                if (isAllowedPdfRendererRequestUrl(requestUrl)) {
+                    await route.continue();
+                    return;
+                }
+
+                await route.abort('blockedbyclient');
+            });
+            await page.setViewportSize(PDF_RENDERER_VIEWPORT);
+            await page.emulateMedia({ media: 'print' });
+            await page.setContent(html, { waitUntil: 'load' });
+            await page.evaluate(async () => {
+                await document.fonts?.ready;
+            });
+
+            return await page.pdf({
+                format: 'Letter',
+                margin: PDF_RENDERER_MARGIN,
+                printBackground: true,
+                preferCSSPageSize: true,
+            });
+        } finally {
+            await page.close();
+        }
+    } finally {
+        await browser.close();
+    }
+}
+
+/**
+ * Returns whether a PDF-renderer request can proceed without connecting to a host.
+ *
+ * @param requestUrl - URL reported by Playwright for one intercepted request.
+ * @returns Whether the request cannot reach an external or internal network host.
+ *
+ * @private internal helper of `renderHtmlToPdfOnServer`
+ */
+function isAllowedPdfRendererRequestUrl(requestUrl: string): boolean {
+    try {
+        return PDF_RENDERER_ALLOWED_REQUEST_PROTOCOLS.has(new URL(requestUrl).protocol);
+    } catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Reads and validates the required admin reason payload shared by admin task actions.
+ *
+ * @param request - Incoming admin action request whose JSON body may carry a `reason`.
+ * @returns The trimmed non-empty reason, or `null` when it is missing or blank.
+ * @private internal admin utility of Agents Server
+ */
+export async function readRequiredAdminReason(request: Request): Promise<string | null> {
+    const payload = (await request.json().catch(() => ({}))) as {
+        reason?: unknown;
+    };
+
+    if (typeof payload.reason !== 'string') {
+        return null;
+    }
+
+    const reason = payload.reason.trim();
+    return reason.length > 0 ? reason : null;
+}

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

@@ -0,0 +1,36 @@
+import { $getTableName } from '@/src/database/$getTableName';
+import type { AgentsServerDatabase } from '@/src/database/schema';
+import { $provideSupabaseForServer } from '@/src/database/$provideSupabaseForServer';
+import { buildAgentNameOrIdFilter } from '@/src/utils/agentIdentifier';
+
+/**
+ * Minimal row used to resolve the current source hash for an agent.
+ */
+type AgentHashRow = Pick<AgentsServerDatabase['public']['Tables']['Agent']['Row'], 'agentHash'>;
+
+/**
+ * Resolves an agent identifier (name or permanent id) to the current `Agent.agentHash`.
+ *
+ * The hash is maintained automatically on every `agentSource` change, so this read
+ * is a cheap alternative to loading and hashing the whole agent source.
+ *
+ * @param agentIdentifier - Agent route identifier, either `agentName` or `permanentId`.
+ * @returns Current `agentHash` or `null` when no matching agent exists.
+ */
+export async function resolveAgentHash(agentIdentifier: string): Promise<string | null> {
+    const supabase = $provideSupabaseForServer();
+    const agentTable = await $getTableName('Agent');
+
+    const { data, error } = await supabase
+        .from(agentTable)
+        .select('agentHash')
+        .or(buildAgentNameOrIdFilter(agentIdentifier))
+        .limit(1)
+        .single();
+
+    if (error || !data) {
+        return null;
+    }
+
+    return (data as AgentHashRow).agentHash;
+}

package/apps/agents-server/src/utils/resourceMonitor/readAgentProjectRuntimesResourceUsage.ts

@@ -0,0 +1,28 @@
+import { listAgentProjectRuntimes } from '../agentProjects/agentProjectRuntimeRegistry';
+import type { AgentProjectRuntimesResourceUsage } from './resourceMonitorTypes';
+
+/**
+ * Reads project runtime port usage for the resource monitor.
+ *
+ * @returns Assigned project runtime ports and counters.
+ */
+export async function readAgentProjectRuntimesResourceUsage(): Promise<AgentProjectRuntimesResourceUsage> {
+    try {
+        const runtimes = await listAgentProjectRuntimes();
+
+        return {
+            runtimes,
+            totalRuntimeCount: runtimes.length,
+            runningRuntimeCount: runtimes.filter((runtime) => runtime.isRunning).length,
+            errorMessage: null,
+        };
+    } catch (error) {
+        return {
+            runtimes: [],
+            totalRuntimeCount: 0,
+            runningRuntimeCount: 0,
+            errorMessage: error instanceof Error ? error.message : 'Failed to read agent project runtimes.',
+        };
+    }
+}
+

package/apps/agents-server/src/utils/resourceMonitor/readAgentProjectsResourceUsage.ts

@@ -0,0 +1,49 @@
+import { listAllAgentProjectSummaries } from '../agentProjects/listAllAgentProjectSummaries';
+import { resolveCurrentServerRegistryContext } from '../currentServerRegistryContext';
+import { resolveLocalAgentRootPath } from '../localChatRunner/ensureLocalAgentFolder';
+import type { AgentProjectsResourceUsage } from './resourceMonitorTypes';
+
+/**
+ * Reads the storage usage of all agent projects for the resource monitor.
+ *
+ * Measurement failures are reported inside the usage value so the resource monitor page
+ * can still render the remaining resources.
+ *
+ * @returns Aggregated project storage usage per agent and in total.
+ */
+export async function readAgentProjectsResourceUsage(): Promise<AgentProjectsResourceUsage> {
+    try {
+        const [report, currentServerContext] = await Promise.all([
+            listAllAgentProjectSummaries({ scope: 'vps' }),
+            resolveCurrentServerRegistryContext(),
+        ]);
+
+        return {
+            rootPath: report.rootPath,
+            totalSizeBytes: report.totalSizeBytes,
+            totalProjectCount: report.totalProjectCount,
+            currentServerDomain: currentServerContext.currentServer?.domain ?? null,
+            agents: report.summaries.map((summary) => ({
+                agentPermanentId: summary.agentPermanentId,
+                agentName: summary.agentName,
+                agentDirectoryName: summary.agentDirectoryName,
+                serverId: summary.serverId,
+                serverName: summary.serverName,
+                serverDomain: summary.serverDomain,
+                projectCount: summary.projects.length,
+                projects: summary.projects,
+                sizeBytes: summary.totalSizeBytes,
+            })),
+            errorMessage: null,
+        };
+    } catch (error) {
+        return {
+            rootPath: resolveLocalAgentRootPath(),
+            totalSizeBytes: 0,
+            totalProjectCount: 0,
+            currentServerDomain: null,
+            agents: [],
+            errorMessage: error instanceof Error ? error.message : 'Failed to measure agent project sizes.',
+        };
+    }
+}

package/apps/agents-server/src/utils/resourceMonitor/readServerResourceMonitorSnapshot.ts

@@ -1,5 +1,7 @@
 import { cache } from 'react';
 
+import { readAgentProjectsResourceUsage } from './readAgentProjectsResourceUsage';
+import { readAgentProjectRuntimesResourceUsage } from './readAgentProjectRuntimesResourceUsage';
 import { readCpuResourceUsage } from './readCpuResourceUsage';
 import { readDiskResourceUsage } from './readDiskResourceUsage';
 import { readMemoryResourceUsage } from './readMemoryResourceUsage';
@@ -13,10 +15,12 @@ import type { ServerResourceMonitorSnapshot, ServerResourceWarningStatus } from
  * @returns Full resource monitor snapshot.
  */
 export const readServerResourceMonitorSnapshot = cache(async (): Promise<ServerResourceMonitorSnapshot> => {
-    const [cpu, disk, network] = await Promise.all([
+    const [cpu, disk, network, projects, projectRuntimes] = await Promise.all([
         readCpuResourceUsage({ isProcessUsageSampled: true }),
         readDiskResourceUsage(),
         readNetworkResourceUsage(),
+        readAgentProjectsResourceUsage(),
+        readAgentProjectRuntimesResourceUsage(),
     ]);
     const memory = readMemoryResourceUsage();
     const warningStatus = resolveServerResourceWarningStatus({ cpu, memory, disk });
@@ -27,6 +31,8 @@ export const readServerResourceMonitorSnapshot = cache(async (): Promise<ServerR
         memory,
         disk,
         network,
+        projects,
+        projectRuntimes,
         warningStatus,
     };
 });