@promptbook/cli 0.113.0-0 → 0.113.0-1

package/apps/agents-server/src/app/admin/task-manager/TaskManagerTaskRow.tsx

@@ -130,6 +130,10 @@ function formatTaskKind(kind: AdminChatTaskRecord['kind']): string {
         return 'Chat timeout';
     }
 
+    if (kind === 'VPS_SELF_UPDATE') {
+        return 'Self-update';
+    }
+
     return kind;
 }
 
@@ -260,8 +264,9 @@ function resolveTaskRowClassName(task: AdminChatTaskRecord, isStuck: boolean): s
  * @private function of TaskManagerTaskRow
  */
 function TaskManagerTaskActions({ busyAction, isBusy, onRunTaskAction, task }: TaskManagerTaskActionsProps) {
-    const isCancelable = task.status === 'QUEUED' || task.status === 'RUNNING';
-    const isRetryable = task.status === 'FAILED';
+    const isDurableChatTask = task.kind === 'CHAT_COMPLETION' || task.kind === 'CHAT_TIMEOUT';
+    const isCancelable = isDurableChatTask && (task.status === 'QUEUED' || task.status === 'RUNNING');
+    const isRetryable = isDurableChatTask && task.status === 'FAILED';
 
     return (
         <div className="flex justify-end gap-2">

package/apps/agents-server/src/app/api/page-preview/check/route.ts

@@ -1,9 +1,8 @@
 import type { NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
 import { assertsError } from '../../../../../../../src/errors/assertsError';
-import { assertSafeUrl } from '../../../../utils/assertSafeUrl';
-import { getCurrentUser } from '../../../../utils/getCurrentUser';
 import { checkIfUrlCanBeEmbedded } from '../../../../utils/iframe/checkIfUrlCanBeEmbedded';
+import { resolvePagePreviewRequestUrl } from '../../../../utils/pagePreview/resolvePagePreviewRequestUrl';
 
 /**
  * Checks whether a given URL can be embedded in an iframe by inspecting
@@ -18,27 +17,13 @@ import { checkIfUrlCanBeEmbedded } from '../../../../utils/iframe/checkIfUrlCanB
  * The destination URL is validated against private/internal IP ranges before fetching.
  */
 export async function GET(request: NextRequest): Promise<NextResponse> {
-    const currentUser = await getCurrentUser();
-    if (!currentUser) {
-        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-    }
-
-    const url = request.nextUrl.searchParams.get('url');
-
-    if (!url) {
-        return NextResponse.json({ error: 'Missing required query parameter: url' }, { status: 400 });
-    }
-
-    // Guard against SSRF: reject private/internal IPs and non-HTTP(S) schemes
-    try {
-        assertSafeUrl(url);
-    } catch (error) {
-        assertsError(error);
-        return NextResponse.json({ error: error.message }, { status: 400 });
+    const requestUrlResolution = await resolvePagePreviewRequestUrl(request);
+    if (requestUrlResolution.errorResponse !== null) {
+        return requestUrlResolution.errorResponse;
     }
 
     try {
-        const canEmbed = await checkIfUrlCanBeEmbedded(url);
+        const canEmbed = await checkIfUrlCanBeEmbedded(requestUrlResolution.url);
         return NextResponse.json({ canEmbed });
     } catch (error) {
         assertsError(error);

package/apps/agents-server/src/app/api/page-preview/interact/route.ts

@@ -0,0 +1,179 @@
+import { serializeError } from '@promptbook-local/utils';
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+import { assertsError } from '../../../../../../../src/errors/assertsError';
+import { getCurrentUser } from '../../../../utils/getCurrentUser';
+import {
+    applyLivePagePreviewInteraction,
+    isLivePagePreviewSessionId,
+    type LivePagePreviewInteraction,
+} from '../../../../utils/pagePreview/livePagePreviewSessions';
+
+/**
+ * Maximum wheel delta accepted from one live-preview UI event.
+ */
+const MAX_LIVE_PAGE_PREVIEW_WHEEL_DELTA = 4_000;
+
+/**
+ * Maximum keyboard key name length accepted from one live-preview UI event.
+ */
+const MAX_LIVE_PAGE_PREVIEW_KEY_LENGTH = 40;
+
+/**
+ * Parsed live-preview interaction request body.
+ */
+type ParsedLivePagePreviewInteractionRequest = {
+    readonly sessionId: string;
+    readonly interaction: LivePagePreviewInteraction;
+};
+
+/**
+ * Constant for dynamic route rendering.
+ */
+export const dynamic = 'force-dynamic';
+
+/**
+ * Applies one UI interaction to an active live browser preview.
+ *
+ * Requires authentication because interaction targets are opened by the authenticated preview route.
+ */
+export async function POST(request: NextRequest): Promise<NextResponse> {
+    const currentUser = await getCurrentUser();
+    if (!currentUser) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    const parsedRequest = await parseLivePagePreviewInteractionRequest(request);
+    if (!parsedRequest) {
+        return NextResponse.json({ error: 'Invalid live preview interaction request.' }, { status: 400 });
+    }
+
+    try {
+        const isApplied = await applyLivePagePreviewInteraction(parsedRequest);
+        if (!isApplied) {
+            return NextResponse.json({ error: 'Live preview session not found.' }, { status: 404 });
+        }
+
+        return NextResponse.json({ ok: true });
+    } catch (error) {
+        assertsError(error);
+        console.error('Error applying live page preview interaction:', error);
+        return NextResponse.json({ error: serializeError(error) }, { status: 500 });
+    }
+}
+
+/**
+ * Parses and validates a live-preview interaction request.
+ *
+ * @param request - Incoming interaction request.
+ * @returns Parsed request or null when the payload is invalid.
+ */
+async function parseLivePagePreviewInteractionRequest(
+    request: NextRequest,
+): Promise<ParsedLivePagePreviewInteractionRequest | null> {
+    let body: unknown;
+
+    try {
+        body = await request.json();
+    } catch {
+        return null;
+    }
+
+    if (!isRecord(body)) {
+        return null;
+    }
+
+    const sessionId = typeof body.sessionId === 'string' ? body.sessionId : null;
+    if (!sessionId || !isLivePagePreviewSessionId(sessionId)) {
+        return null;
+    }
+
+    const interaction = parseLivePagePreviewInteraction(body);
+    if (!interaction) {
+        return null;
+    }
+
+    return {
+        sessionId,
+        interaction,
+    };
+}
+
+/**
+ * Parses one normalized live-preview interaction from an object payload.
+ *
+ * @param body - Request body record.
+ * @returns Interaction payload or null when invalid.
+ */
+function parseLivePagePreviewInteraction(body: Record<string, unknown>): LivePagePreviewInteraction | null {
+    if (body.type === 'click') {
+        const x = readFiniteNumber(body.x);
+        const y = readFiniteNumber(body.y);
+
+        if (x === null || y === null) {
+            return null;
+        }
+
+        return { type: 'click', x, y };
+    }
+
+    if (body.type === 'wheel') {
+        const deltaX = readFiniteNumber(body.deltaX);
+        const deltaY = readFiniteNumber(body.deltaY);
+
+        if (deltaX === null || deltaY === null) {
+            return null;
+        }
+
+        return {
+            type: 'wheel',
+            deltaX: clampWheelDelta(deltaX),
+            deltaY: clampWheelDelta(deltaY),
+        };
+    }
+
+    if (body.type === 'keyDown') {
+        const key = typeof body.key === 'string' ? body.key : null;
+        if (!key || key.length > MAX_LIVE_PAGE_PREVIEW_KEY_LENGTH) {
+            return null;
+        }
+
+        return { type: 'keyDown', key };
+    }
+
+    return null;
+}
+
+/**
+ * Checks whether a value is a plain object record.
+ *
+ * @param value - Candidate value.
+ * @returns True when the value can be read as a JSON object.
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Reads one finite number from a JSON value.
+ *
+ * @param value - Candidate JSON value.
+ * @returns Number or null when invalid.
+ */
+function readFiniteNumber(value: unknown): number | null {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return null;
+    }
+
+    return value;
+}
+
+/**
+ * Clamps one wheel delta to a bounded value.
+ *
+ * @param value - Raw wheel delta.
+ * @returns Delta safe to forward to Playwright.
+ */
+function clampWheelDelta(value: number): number {
+    return Math.min(Math.max(value, -MAX_LIVE_PAGE_PREVIEW_WHEEL_DELTA), MAX_LIVE_PAGE_PREVIEW_WHEEL_DELTA);
+}

package/apps/agents-server/src/app/api/page-preview/live/route.ts

@@ -0,0 +1,67 @@
+import { serializeError } from '@promptbook-local/utils';
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+import { assertsError } from '../../../../../../../src/errors/assertsError';
+import {
+    createLivePagePreviewStream,
+    getOrCreateLivePagePreviewSession,
+    isLivePagePreviewSessionId,
+    LIVE_PAGE_PREVIEW_STREAM_CONTENT_TYPE,
+} from '../../../../utils/pagePreview/livePagePreviewSessions';
+import { resolvePagePreviewRequestUrl } from '../../../../utils/pagePreview/resolvePagePreviewRequestUrl';
+
+/**
+ * Query parameter containing the browser-side live preview session id.
+ */
+const LIVE_PAGE_PREVIEW_SESSION_ID_QUERY_PARAMETER = 'sessionId';
+
+/**
+ * Constant for dynamic route rendering.
+ */
+export const dynamic = 'force-dynamic';
+
+/**
+ * Streams a live browser preview for a knowledge source URL.
+ *
+ * Query parameters:
+ * - `url` — fully-qualified HTTP(S) URL to preview
+ * - `sessionId` — client-generated id used for forwarding interactions
+ *
+ * Requires authentication to prevent unauthenticated SSRF abuse.
+ */
+export async function GET(request: NextRequest): Promise<NextResponse> {
+    const requestUrlResolution = await resolvePagePreviewRequestUrl(request);
+    if (requestUrlResolution.errorResponse !== null) {
+        return requestUrlResolution.errorResponse;
+    }
+
+    const sessionId = request.nextUrl.searchParams.get(LIVE_PAGE_PREVIEW_SESSION_ID_QUERY_PARAMETER);
+    if (!sessionId || !isLivePagePreviewSessionId(sessionId)) {
+        return NextResponse.json({ error: 'Missing or invalid live preview session id.' }, { status: 400 });
+    }
+
+    try {
+        const page = await getOrCreateLivePagePreviewSession({
+            sessionId,
+            url: requestUrlResolution.url,
+            signal: request.signal,
+        });
+        const stream = createLivePagePreviewStream({
+            sessionId,
+            page,
+            signal: request.signal,
+        });
+
+        return new NextResponse(stream, {
+            headers: {
+                'Content-Type': LIVE_PAGE_PREVIEW_STREAM_CONTENT_TYPE,
+                'Cache-Control': 'no-cache, no-store, max-age=0',
+                Connection: 'keep-alive',
+            },
+        });
+    } catch (error) {
+        assertsError(error);
+        console.error('Error streaming live page preview:', error);
+        return NextResponse.json({ error: serializeError(error) }, { status: 500 });
+    }
+}

package/apps/agents-server/src/app/api/page-preview/screenshot/route.ts

@@ -2,9 +2,12 @@ import { $provideBrowserForServer } from '@/src/tools/$provideBrowserForServer';
 import { serializeError } from '@promptbook-local/utils';
 import type { NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
+import {
+    LIVE_PAGE_PREVIEW_VIEWPORT_HEIGHT,
+    LIVE_PAGE_PREVIEW_VIEWPORT_WIDTH,
+} from '../../../../../../../src/book-components/Chat/utils/livePagePreviewConstants';
 import { assertsError } from '../../../../../../../src/errors/assertsError';
-import { assertSafeUrl } from '../../../../utils/assertSafeUrl';
-import { getCurrentUser } from '../../../../utils/getCurrentUser';
+import { resolvePagePreviewRequestUrl } from '../../../../utils/pagePreview/resolvePagePreviewRequestUrl';
 
 /**
  * Takes a screenshot of the given URL using a headless browser.
@@ -18,23 +21,9 @@ import { getCurrentUser } from '../../../../utils/getCurrentUser';
  * The destination URL is validated against private/internal IP ranges before fetching.
  */
 export async function GET(request: NextRequest): Promise<NextResponse> {
-    const currentUser = await getCurrentUser();
-    if (!currentUser) {
-        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-    }
-
-    const url = request.nextUrl.searchParams.get('url');
-
-    if (!url) {
-        return NextResponse.json({ error: 'Missing required query parameter: url' }, { status: 400 });
-    }
-
-    // Guard against SSRF: reject private/internal IPs and non-HTTP(S) schemes
-    try {
-        assertSafeUrl(url);
-    } catch (error) {
-        assertsError(error);
-        return NextResponse.json({ error: error.message }, { status: 400 });
+    const requestUrlResolution = await resolvePagePreviewRequestUrl(request);
+    if (requestUrlResolution.errorResponse !== null) {
+        return requestUrlResolution.errorResponse;
     }
 
     try {
@@ -42,8 +31,11 @@ export async function GET(request: NextRequest): Promise<NextResponse> {
         const page = await browserContext.newPage();
 
         try {
-            await page.setViewportSize({ width: 1280, height: 800 });
-            await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
+            await page.setViewportSize({
+                width: LIVE_PAGE_PREVIEW_VIEWPORT_WIDTH,
+                height: LIVE_PAGE_PREVIEW_VIEWPORT_HEIGHT,
+            });
+            await page.goto(requestUrlResolution.url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
             const screenshotBuffer = await page.screenshot({ type: 'png' });
 
             // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/apps/agents-server/src/constants/chatVisualMode.ts

@@ -46,7 +46,7 @@ export const CHAT_VISUAL_MODE_COOKIE_NAME = 'promptbook_agents_chat_visual_mode'
 /**
  * Fallback visual mode when metadata/browser values are missing or invalid.
  */
-export const DEFAULT_CHAT_VISUAL_MODE: ChatVisualMode = CHAT_VISUAL_MODES.BUBBLE_MODE;
+export const DEFAULT_CHAT_VISUAL_MODE: ChatVisualMode = CHAT_VISUAL_MODES.ARTICLE_MODE;
 
 /**
  * Resolves one raw visual mode value to a supported mode.

package/apps/agents-server/src/constants/themeMode.ts

@@ -46,7 +46,7 @@ export const THEME_MODE_OPTIONS: ReadonlyArray<{
 /**
  * Built-in fallback theme mode applied when metadata/browser values are missing or invalid.
  */
-export const DEFAULT_THEME_MODE: ThemeMode = THEME_MODES.SYSTEM;
+export const DEFAULT_THEME_MODE: ThemeMode = THEME_MODES.LIGHT;
 
 /**
  * Local storage key used to keep the latest browser theme mode in sync.

package/apps/agents-server/src/database/migrations/2026-05-2600-default-theme.sql

@@ -1,6 +1,6 @@
 INSERT INTO "prefix_Metadata" ("key", "value", "note", "createdAt", "updatedAt")
 SELECT 'DEFAULT_THEME',
-       'SYSTEM',
+       'LIGHT',
        'Default theme mode for browsers without a saved preference. Allowed values: SYSTEM, LIGHT, DARK.',
        NOW(),
        NOW()
@@ -9,7 +9,7 @@ WHERE NOT EXISTS (SELECT 1 FROM "prefix_Metadata" WHERE "key" = 'DEFAULT_THEME')
 UPDATE "prefix_Metadata"
 SET "value" = CASE
                   WHEN UPPER(COALESCE("value", '')) IN ('SYSTEM', 'LIGHT', 'DARK') THEN UPPER("value")
-                  ELSE 'SYSTEM'
+                  ELSE 'LIGHT'
               END,
     "note" = 'Default theme mode for browsers without a saved preference. Allowed values: SYSTEM, LIGHT, DARK.',
     "updatedAt" = NOW()

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

@@ -10,9 +10,11 @@ export type AdminChatTaskView = 'active' | 'running' | 'queued' | 'failed' | 'al
 /**
  * Durable task kinds currently surfaced by the admin task manager.
  *
+ * `VPS_SELF_UPDATE` represents the standalone VPS self-update session triggered from `/admin/update`.
+ *
  * @private internal admin utility of Agents Server
  */
-export type AdminChatTaskKind = 'CHAT_COMPLETION' | 'CHAT_TIMEOUT';
+export type AdminChatTaskKind = 'CHAT_COMPLETION' | 'CHAT_TIMEOUT' | 'VPS_SELF_UPDATE';
 
 /**
  * One row shown in the admin task-manager table.

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

@@ -0,0 +1,84 @@
+import type { AdminChatTaskRecord } from '../chatTasksAdmin';
+import type { UserChatJobStatus } from '../userChat/UserChatJobRecord';
+import type { VpsSelfUpdateJobSnapshot } from '../vpsSelfUpdate';
+
+/**
+ * Stable synthetic task id used for the singleton standalone VPS self-update task row.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export const VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID = 'vps-self-update';
+
+/**
+ * Synthetic queue name used for the standalone VPS self-update task row.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export const VPS_SELF_UPDATE_ADMIN_CHAT_TASK_QUEUE_NAME = 'vps-self-update';
+
+/**
+ * Maps a persisted VPS self-update job snapshot to the admin task manager row shape.
+ *
+ * @param job - Latest persisted self-update job snapshot.
+ * @returns Task manager row or `null` when no self-update has ever been triggered on this server.
+ */
+export function mapVpsSelfUpdateJobToAdminChatTask(job: VpsSelfUpdateJobSnapshot): AdminChatTaskRecord | null {
+    const status = toAdminChatTaskStatus(job);
+    if (!status) {
+        return null;
+    }
+
+    const isTerminalStatus = status === 'COMPLETED' || status === 'FAILED';
+    const startedAt = job.startedAt;
+    const finishedAt = isTerminalStatus ? job.finishedAt || startedAt : null;
+    const updatedAt = finishedAt || startedAt || new Date().toISOString();
+    const errorSummary = job.errorMessage || null;
+    const currentStepDetails = job.currentStep || null;
+
+    return {
+        id: VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID,
+        kind: 'VPS_SELF_UPDATE',
+        status,
+        createdAt: startedAt || updatedAt,
+        queuedAt: startedAt || updatedAt,
+        startedAt,
+        updatedAt,
+        finishedAt,
+        cancelRequestedAt: null,
+        pausedAt: null,
+        lastHeartbeatAt: null,
+        leaseExpiresAt: null,
+        recurrenceIntervalMs: null,
+        priority: null,
+        attemptCount: 1,
+        retryCount: 0,
+        lastErrorSummary: errorSummary,
+        lastErrorDetails: currentStepDetails,
+        userId: 0,
+        username: null,
+        agentPermanentId: VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID,
+        agentName: 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,
+    };
+}
+
+/**
+ * Maps the shell-owned self-update status to the durable chat-task status enum used by the admin task manager.
+ *
+ * @param job - Persisted self-update job snapshot.
+ * @returns Equivalent durable chat-job status, or `null` when the job is idle (no run has been triggered yet).
+ */
+function toAdminChatTaskStatus(job: VpsSelfUpdateJobSnapshot): UserChatJobStatus | null {
+    switch (job.status) {
+        case 'running':
+            return 'RUNNING';
+        case 'succeeded':
+            return 'COMPLETED';
+        case 'failed':
+            return 'FAILED';
+        case 'idle':
+            return null;
+    }
+}