@promptbook/cli 0.112.0 → 0.113.0-1

package/apps/agents-server/src/utils/pagePreview/livePagePreviewSessions.ts

@@ -0,0 +1,365 @@
+import type { Page } from 'playwright';
+import { spaceTrim } from 'spacetrim';
+import {
+    LIVE_PAGE_PREVIEW_VIEWPORT_HEIGHT,
+    LIVE_PAGE_PREVIEW_VIEWPORT_WIDTH,
+} from '../../../../../src/book-components/Chat/utils/livePagePreviewConstants';
+import { KnowledgeScrapeError } from '../../../../../src/errors/KnowledgeScrapeError';
+import { $provideBrowserForServer } from '../../tools/$provideBrowserForServer';
+
+/**
+ * Pattern for live-preview session identifiers created by the browser client.
+ */
+const LIVE_PAGE_PREVIEW_SESSION_ID_PATTERN = /^[a-zA-Z0-9_-]{1,128}$/;
+
+/**
+ * Navigation timeout for opening a live knowledge preview page.
+ */
+const LIVE_PAGE_PREVIEW_NAVIGATION_TIMEOUT_MS = 30_000;
+
+/**
+ * Playwright action timeout for live-preview interactions.
+ */
+const LIVE_PAGE_PREVIEW_ACTION_TIMEOUT_MS = 5_000;
+
+/**
+ * Idle session lifetime before a stale live-preview page is closed.
+ */
+const LIVE_PAGE_PREVIEW_SESSION_IDLE_TIMEOUT_MS = 60_000;
+
+/**
+ * Multipart response boundary used by the live-preview image stream.
+ */
+const LIVE_PAGE_PREVIEW_STREAM_BOUNDARY = 'page-preview-frame';
+
+/**
+ * Delay between live-preview browser frames.
+ */
+const LIVE_PAGE_PREVIEW_FRAME_INTERVAL_MS = 500;
+
+/**
+ * JPEG quality for live-preview browser frames.
+ */
+const LIVE_PAGE_PREVIEW_JPEG_QUALITY = 65;
+
+/**
+ * Browser page stored for a live knowledge preview session.
+ */
+type LivePagePreviewSession = {
+    readonly page: Page;
+    readonly url: string;
+    lastAccessedAt: number;
+};
+
+/**
+ * Pointer interaction sent from the live preview image to the browser page.
+ */
+type LivePagePreviewClickInteraction = {
+    readonly type: 'click';
+    readonly x: number;
+    readonly y: number;
+};
+
+/**
+ * Wheel interaction sent from the live preview image to the browser page.
+ */
+type LivePagePreviewWheelInteraction = {
+    readonly type: 'wheel';
+    readonly deltaX: number;
+    readonly deltaY: number;
+};
+
+/**
+ * Keyboard interaction sent from the live preview image to the browser page.
+ */
+type LivePagePreviewKeyDownInteraction = {
+    readonly type: 'keyDown';
+    readonly key: string;
+};
+
+/**
+ * Supported interaction payload for a live knowledge preview session.
+ */
+export type LivePagePreviewInteraction =
+    | LivePagePreviewClickInteraction
+    | LivePagePreviewWheelInteraction
+    | LivePagePreviewKeyDownInteraction;
+
+/**
+ * Active browser pages for live knowledge previews.
+ */
+const LIVE_PAGE_PREVIEW_SESSIONS = new Map<string, LivePagePreviewSession>();
+
+/**
+ * Content type for the live-preview multipart image stream.
+ */
+export const LIVE_PAGE_PREVIEW_STREAM_CONTENT_TYPE = `multipart/x-mixed-replace; boundary=${LIVE_PAGE_PREVIEW_STREAM_BOUNDARY}`;
+
+/**
+ * Checks whether a live-preview session identifier is safe to use as a map key.
+ *
+ * @param sessionId - Candidate session identifier.
+ * @returns True when the value is a valid live-preview session id.
+ */
+export function isLivePagePreviewSessionId(sessionId: string): boolean {
+    return LIVE_PAGE_PREVIEW_SESSION_ID_PATTERN.test(sessionId);
+}
+
+/**
+ * Opens or reuses the browser page for one live knowledge preview.
+ *
+ * @param options - Session, target URL, and request cancellation signal.
+ * @returns Playwright page backing the live preview.
+ */
+export async function getOrCreateLivePagePreviewSession(options: {
+    readonly sessionId: string;
+    readonly url: string;
+    readonly signal: AbortSignal;
+}): Promise<Page> {
+    pruneExpiredLivePagePreviewSessions();
+
+    const existingSession = LIVE_PAGE_PREVIEW_SESSIONS.get(options.sessionId);
+    if (existingSession && existingSession.url === options.url && !existingSession.page.isClosed()) {
+        existingSession.lastAccessedAt = Date.now();
+        return existingSession.page;
+    }
+
+    if (existingSession) {
+        await closeLivePagePreviewSession(options.sessionId);
+    }
+
+    const browserContext = await $provideBrowserForServer({
+        signal: options.signal,
+        sessionId: options.sessionId,
+    });
+    const page = await browserContext.newPage();
+
+    try {
+        page.setDefaultNavigationTimeout(LIVE_PAGE_PREVIEW_NAVIGATION_TIMEOUT_MS);
+        page.setDefaultTimeout(LIVE_PAGE_PREVIEW_ACTION_TIMEOUT_MS);
+        await page.setViewportSize({
+            width: LIVE_PAGE_PREVIEW_VIEWPORT_WIDTH,
+            height: LIVE_PAGE_PREVIEW_VIEWPORT_HEIGHT,
+        });
+        await page.goto(options.url, {
+            waitUntil: 'domcontentloaded',
+            timeout: LIVE_PAGE_PREVIEW_NAVIGATION_TIMEOUT_MS,
+        });
+    } catch {
+        await closeLivePagePreviewPage(page);
+        throw new KnowledgeScrapeError(
+            spaceTrim(`
+                Failed to open live knowledge preview for \`${options.url}\`.
+
+                The browser session could not navigate to the requested source.
+            `),
+        );
+    }
+
+    LIVE_PAGE_PREVIEW_SESSIONS.set(options.sessionId, {
+        page,
+        url: options.url,
+        lastAccessedAt: Date.now(),
+    });
+
+    return page;
+}
+
+/**
+ * Closes one live knowledge preview session if it exists.
+ *
+ * @param sessionId - Live-preview session identifier.
+ */
+export async function closeLivePagePreviewSession(sessionId: string): Promise<void> {
+    const existingSession = LIVE_PAGE_PREVIEW_SESSIONS.get(sessionId);
+    if (!existingSession) {
+        return;
+    }
+
+    LIVE_PAGE_PREVIEW_SESSIONS.delete(sessionId);
+    await closeLivePagePreviewPage(existingSession.page);
+}
+
+/**
+ * Creates an MJPEG stream from an active live-preview browser page.
+ *
+ * @param options - Session identifier, browser page, and request cancellation signal.
+ * @returns Readable stream that emits JPEG browser frames until the client disconnects.
+ */
+export function createLivePagePreviewStream(options: {
+    readonly sessionId: string;
+    readonly page: Page;
+    readonly signal: AbortSignal;
+}): ReadableStream<Uint8Array> {
+    const encoder = new TextEncoder();
+    let isStreamClosed = false;
+    let isSessionClosed = false;
+
+    const closeSessionOnce = async (): Promise<void> => {
+        if (isSessionClosed) {
+            return;
+        }
+
+        isSessionClosed = true;
+        await closeLivePagePreviewSession(options.sessionId);
+    };
+
+    return new ReadableStream<Uint8Array>({
+        async start(controller) {
+            const handleAbort = (): void => {
+                isStreamClosed = true;
+                void closeSessionOnce();
+            };
+
+            options.signal.addEventListener('abort', handleAbort, { once: true });
+
+            try {
+                while (!isStreamClosed && !options.signal.aborted && !options.page.isClosed()) {
+                    const buffer = await options.page.screenshot({
+                        type: 'jpeg',
+                        quality: LIVE_PAGE_PREVIEW_JPEG_QUALITY,
+                    });
+
+                    if (isStreamClosed || options.signal.aborted || options.page.isClosed()) {
+                        break;
+                    }
+
+                    const header = [
+                        '',
+                        `--${LIVE_PAGE_PREVIEW_STREAM_BOUNDARY}`,
+                        'Content-Type: image/jpeg',
+                        `Content-Length: ${buffer.length}`,
+                        '',
+                        '',
+                    ].join('\r\n');
+
+                    controller.enqueue(encoder.encode(header));
+                    controller.enqueue(buffer);
+
+                    await waitForLivePagePreviewFrame(options.signal);
+                }
+            } catch (error) {
+                if (!isStreamClosed && !options.signal.aborted) {
+                    console.error('Error streaming live page preview:', error);
+                }
+            } finally {
+                isStreamClosed = true;
+                options.signal.removeEventListener('abort', handleAbort);
+                await closeSessionOnce();
+
+                try {
+                    controller.close();
+                } catch {
+                    // The client can disconnect before the server closes the stream.
+                }
+            }
+        },
+        async cancel() {
+            isStreamClosed = true;
+            await closeSessionOnce();
+        },
+    });
+}
+
+/**
+ * Applies one browser interaction to an active live preview session.
+ *
+ * @param options - Session identifier and normalized interaction.
+ * @returns True when the interaction was applied to an active session.
+ */
+export async function applyLivePagePreviewInteraction(options: {
+    readonly sessionId: string;
+    readonly interaction: LivePagePreviewInteraction;
+}): Promise<boolean> {
+    const session = LIVE_PAGE_PREVIEW_SESSIONS.get(options.sessionId);
+    if (!session || session.page.isClosed()) {
+        LIVE_PAGE_PREVIEW_SESSIONS.delete(options.sessionId);
+        return false;
+    }
+
+    session.lastAccessedAt = Date.now();
+
+    switch (options.interaction.type) {
+        case 'click':
+            await session.page.mouse.click(
+                clampLivePagePreviewCoordinate(options.interaction.x, LIVE_PAGE_PREVIEW_VIEWPORT_WIDTH),
+                clampLivePagePreviewCoordinate(options.interaction.y, LIVE_PAGE_PREVIEW_VIEWPORT_HEIGHT),
+            );
+            return true;
+
+        case 'wheel':
+            await session.page.mouse.wheel(options.interaction.deltaX, options.interaction.deltaY);
+            return true;
+
+        case 'keyDown':
+            await session.page.keyboard.press(options.interaction.key);
+            return true;
+    }
+}
+
+/**
+ * Removes stale live-preview sessions left behind by disconnected clients.
+ */
+function pruneExpiredLivePagePreviewSessions(): void {
+    const now = Date.now();
+    for (const [sessionId, session] of LIVE_PAGE_PREVIEW_SESSIONS) {
+        const isExpired = now - session.lastAccessedAt > LIVE_PAGE_PREVIEW_SESSION_IDLE_TIMEOUT_MS;
+        if (isExpired || session.page.isClosed()) {
+            LIVE_PAGE_PREVIEW_SESSIONS.delete(sessionId);
+            void closeLivePagePreviewPage(session.page);
+        }
+    }
+}
+
+/**
+ * Waits between streamed browser frames, resolving early when the request is aborted.
+ *
+ * @param signal - Request cancellation signal.
+ */
+async function waitForLivePagePreviewFrame(signal: AbortSignal): Promise<void> {
+    if (signal.aborted) {
+        return;
+    }
+
+    await new Promise<void>((resolve) => {
+        const timeout = setTimeout(() => {
+            signal.removeEventListener('abort', handleAbort);
+            resolve();
+        }, LIVE_PAGE_PREVIEW_FRAME_INTERVAL_MS);
+
+        function handleAbort(): void {
+            clearTimeout(timeout);
+            resolve();
+        }
+
+        signal.addEventListener('abort', handleAbort, { once: true });
+    });
+}
+
+/**
+ * Closes a Playwright page while ignoring cleanup errors.
+ *
+ * @param page - Browser page to close.
+ */
+async function closeLivePagePreviewPage(page: Page): Promise<void> {
+    if (page.isClosed()) {
+        return;
+    }
+
+    await page.close().catch(() => undefined);
+}
+
+/**
+ * Clamps a pointer coordinate to the configured live-preview viewport.
+ *
+ * @param value - Raw coordinate from the web UI.
+ * @param maximum - Maximum coordinate value for one axis.
+ * @returns Coordinate safe to pass into Playwright.
+ */
+function clampLivePagePreviewCoordinate(value: number, maximum: number): number {
+    if (!Number.isFinite(value)) {
+        return 0;
+    }
+
+    return Math.min(Math.max(value, 0), maximum);
+}

package/apps/agents-server/src/utils/pagePreview/resolvePagePreviewRequestUrl.ts

@@ -0,0 +1,74 @@
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+import { assertsError } from '../../../../../src/errors/assertsError';
+import { assertSafeUrl } from '../assertSafeUrl';
+import { getCurrentUser } from '../getCurrentUser';
+
+/**
+ * Query parameter used by page-preview API endpoints.
+ */
+const PAGE_PREVIEW_URL_QUERY_PARAMETER = 'url';
+
+/**
+ * Successful page-preview request URL resolution.
+ */
+type PagePreviewRequestUrlSuccess = {
+    readonly url: string;
+    readonly errorResponse: null;
+};
+
+/**
+ * Failed page-preview request URL resolution.
+ */
+type PagePreviewRequestUrlFailure = {
+    readonly url: null;
+    readonly errorResponse: NextResponse;
+};
+
+/**
+ * Result of authenticating and validating a page-preview request URL.
+ */
+export type PagePreviewRequestUrlResolution = PagePreviewRequestUrlSuccess | PagePreviewRequestUrlFailure;
+
+/**
+ * Authenticates a page-preview request and validates its target URL against SSRF-sensitive destinations.
+ *
+ * @param request - Incoming Next.js request.
+ * @returns Valid target URL or a ready-made error response.
+ */
+export async function resolvePagePreviewRequestUrl(request: NextRequest): Promise<PagePreviewRequestUrlResolution> {
+    const currentUser = await getCurrentUser();
+    if (!currentUser) {
+        return {
+            url: null,
+            errorResponse: NextResponse.json({ error: 'Unauthorized' }, { status: 401 }),
+        };
+    }
+
+    const url = request.nextUrl.searchParams.get(PAGE_PREVIEW_URL_QUERY_PARAMETER);
+
+    if (!url) {
+        return {
+            url: null,
+            errorResponse: NextResponse.json(
+                { error: `Missing required query parameter: ${PAGE_PREVIEW_URL_QUERY_PARAMETER}` },
+                { status: 400 },
+            ),
+        };
+    }
+
+    try {
+        assertSafeUrl(url);
+    } catch (error) {
+        assertsError(error);
+        return {
+            url: null,
+            errorResponse: NextResponse.json({ error: error.message }, { status: 400 }),
+        };
+    }
+
+    return {
+        url,
+        errorResponse: null,
+    };
+}

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

@@ -46,6 +46,7 @@ export type SpawnAgentLimits = {
  */
 export type LocalAgentRunnerLimits = {
     readonly maxFailedAttempts: number;
+    readonly maxParallelMessages: number;
 };
 
 /**
@@ -270,6 +271,7 @@ export async function getLocalAgentRunnerLimits(): Promise<LocalAgentRunnerLimit
     const limits = await getServerLimits();
     return {
         maxFailedAttempts: limits[SERVER_LIMIT_KEYS.LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS],
+        maxParallelMessages: limits[SERVER_LIMIT_KEYS.LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES],
     };
 }
 

package/apps/agents-server/src/utils/serverManagement/createManagedServer/seedServerCoreAgents.ts

@@ -35,7 +35,7 @@ export async function seedServerCoreAgents(
         const createdAt = new Date().toISOString();
         const { agentInsertRecord, agentHistoryInsertRecord } = createAgentPersistenceRecords(
             coreAgentBook,
-            { folderId: coreFolderId, sortOrder: index, visibility: DEFAULT_AGENT_VISIBILITY },
+            { folderId: coreFolderId, sortOrder: index },
             createdAt,
         );
 
@@ -158,5 +158,5 @@ async function insertCoreFolder(
         }),
     );
 
-    return insertResult.rows[0].id;
+    return insertResult.rows[0]!.id;
 }

package/apps/agents-server/src/utils/serverManagement/createManagedServer/seedServerDefaultAgents.ts

@@ -29,7 +29,7 @@ export async function seedServerDefaultAgents(
         const createdAt = new Date().toISOString();
         const { agentInsertRecord, agentHistoryInsertRecord } = createAgentPersistenceRecords(
             defaultAgentBook,
-            { sortOrder: index, visibility: DEFAULT_AGENT_VISIBILITY },
+            { sortOrder: index },
             createdAt,
         );
 

package/apps/agents-server/src/utils/userChat/createUserChatHarnessProgressCard.ts

@@ -4,11 +4,6 @@ import { TOOL_TITLES } from '../../../../../src/book-components/Chat/utils/getTo
 import { isVisibleChatToolCall } from '../../../../../src/book-components/Chat/utils/isVisibleChatToolCall';
 import { resolveToolCallState } from '../../../../../src/book-components/Chat/utils/resolveToolCallState';
 
-/**
- * Default title used while a running chat job reports harness action progress.
- */
-const USER_CHAT_HARNESS_PROGRESS_TITLE = 'Working on your request';
-
 /**
  * Creates a user-facing progress card from the latest visible harness/tool action.
  *
@@ -24,7 +19,6 @@ export function createUserChatHarnessProgressCard(
     }
 
     return {
-        title: USER_CHAT_HARNESS_PROGRESS_TITLE,
         now: createHarnessProgressNowText(latestVisibleToolCall),
         items: [],
         updatedAt: new Date().toISOString() as NonNullable<ChatMessage['progressCard']>['updatedAt'],

package/apps/agents-server/src/utils/userChat/createUserChatRunnerProgressCard.ts

@@ -11,11 +11,6 @@ export type UserChatRunnerKind = 'local' | 'external';
  */
 export type UserChatRunnerProgressPhase = 'queued_for_runner';
 
-/**
- * Default title used while an out-of-process runner is working on a chat answer.
- */
-const USER_CHAT_RUNNER_PROGRESS_TITLE = 'Working on your request';
-
 /**
  * User-facing labels for durable chat runners.
  */
@@ -35,7 +30,6 @@ export function createUserChatRunnerProgressCard(options: {
     readonly phase: UserChatRunnerProgressPhase;
 }): NonNullable<ChatMessage['progressCard']> {
     return {
-        title: USER_CHAT_RUNNER_PROGRESS_TITLE,
         now: createUserChatRunnerProgressNowText(options),
         items: [],
         updatedAt: new Date().toISOString() as NonNullable<ChatMessage['progressCard']>['updatedAt'],

package/apps/agents-server/src/utils/userChat/userChatMessageLifecycle.ts

@@ -4,6 +4,13 @@ import type { ChatMessage } from '../../../../../src/_packages/types.index';
  */
 export type UserChatMessageLifecycleState = NonNullable<ChatMessage['lifecycleState']>;
 
+/**
+ * Message shape written into local/external chat-runner `.book` files.
+ */
+export type UserChatRunnerThreadMessage = Pick<ChatMessage, 'content'> & {
+    sender: 'USER' | 'AGENT';
+};
+
 /**
  * Creates one persisted user-authored message for a durable chat turn.
  */
@@ -89,6 +96,36 @@ export function resolvePromptThreadBeforeUserMessage(
     return messages.slice(0, userMessageIndex);
 }
 
+/**
+ * Creates the complete chat thread mirrored to a runner before it writes the next answer.
+ */
+export function createUserChatRunnerThreadMessages(options: {
+    messages: ReadonlyArray<ChatMessage>;
+    userMessageId: string;
+    resolveInitialAgentMessage: () => string | null | undefined;
+}): Array<UserChatRunnerThreadMessage> {
+    const userMessage = options.messages.find((message) => message.id === options.userMessageId);
+    if (!userMessage) {
+        return [];
+    }
+
+    const previousThreadMessages = resolvePromptThreadBeforeUserMessage(options.messages, options.userMessageId);
+
+    return [
+        ...createInitialUserChatRunnerThreadMessages({
+            isFirstUserTurn: previousThreadMessages.length === 0,
+            resolveInitialAgentMessage: options.resolveInitialAgentMessage,
+        }),
+        ...previousThreadMessages,
+        userMessage,
+    ]
+        .filter(isUserChatRunnerThreadMessage)
+        .map((message) => ({
+            sender: message.sender,
+            content: message.content,
+        }));
+}
+
 /**
  * Maps durable job status values to message lifecycle labels rendered by the UI.
  */
@@ -107,3 +144,35 @@ export function resolveMessageLifecycleStateFromJobStatus(status: string): UserC
             return 'completed';
     }
 }
+
+/**
+ * Recreates the synthetic first agent message that the UI shows for empty durable chats.
+ */
+function createInitialUserChatRunnerThreadMessages(options: {
+    isFirstUserTurn: boolean;
+    resolveInitialAgentMessage: () => string | null | undefined;
+}): Array<UserChatRunnerThreadMessage> {
+    if (!options.isFirstUserTurn) {
+        return [];
+    }
+
+    const initialAgentMessage = options.resolveInitialAgentMessage();
+    if (!initialAgentMessage || initialAgentMessage.trim().length === 0) {
+        return [];
+    }
+
+    return [
+        {
+            sender: 'AGENT',
+            content: initialAgentMessage,
+        },
+    ];
+}
+
+/**
+ * Returns true when one persisted message should be visible to out-of-process runners.
+ */
+function isUserChatRunnerThreadMessage(message: ChatMessage): message is ChatMessage & UserChatRunnerThreadMessage {
+    const isRunnerSender = message.sender === 'USER' || message.sender === 'AGENT';
+    return message.isComplete !== false && isRunnerSender;
+}

package/apps/agents-server/src/utils/userChat/userChatProgressCard.ts

@@ -75,11 +75,6 @@ export type UserChatProgressContext = {
     readonly isAgentKitCached?: boolean;
 };
 
-/**
- * Default title used by durable chat progress cards.
- */
-const USER_CHAT_PROGRESS_TITLE = 'Working on your request';
-
 /**
  * Ordered progress item identifiers shared across all durable chat phases.
  */
@@ -165,7 +160,6 @@ export function createUserChatProgressCard(
     const { now, next } = composeUserChatProgressPhaseText(phase, context);
 
     return {
-        title: USER_CHAT_PROGRESS_TITLE,
         now,
         next,
         items: USER_CHAT_PROGRESS_ITEMS.map((item) => ({