@promptbook/cli 0.113.0-8 → 0.114.0-0

package/apps/agents-server/src/app/api/internal/agent-project-runtimes/route.ts

@@ -0,0 +1,178 @@
+import { NextResponse } from 'next/server';
+import { ParseError } from '../../../../../../../src/errors/ParseError';
+import { NotAllowed } from '../../../../../../../src/errors/NotAllowed';
+import { NotFoundError } from '../../../../../../../src/errors/NotFoundError';
+import { isTimingSafeEqualString } from '../../../../../../../src/utils/isTimingSafeEqualString';
+import { USER_CHAT_WORKER_TOKEN_HEADER } from '@/src/utils/agentProjects/agentProjectRuntimeConstants';
+import {
+    assignAgentProjectPort,
+    startAgentProjectRuntime,
+    terminateAgentProjectRuntimeForProject,
+} from '@/src/utils/agentProjects/agentProjectRuntimeRegistry';
+import { resolveUserChatWorkerInternalToken } from '@/src/utils/userChat';
+
+/**
+ * Actions accepted by the internal agent-project runtime route.
+ */
+const AGENT_PROJECT_RUNTIME_REQUEST_ACTIONS = ['assign_port', 'start', 'terminate'] as const;
+
+/**
+ * Supported internal runtime action.
+ */
+type AgentProjectRuntimeRequestAction = (typeof AGENT_PROJECT_RUNTIME_REQUEST_ACTIONS)[number];
+
+/**
+ * Normalized internal runtime request.
+ */
+type AgentProjectRuntimeRequest = {
+    readonly action: AgentProjectRuntimeRequestAction;
+    readonly agentPermanentId: string;
+    readonly projectName: string;
+    readonly serverDomain?: string;
+};
+
+/**
+ * Ensures the route always runs in the Node.js runtime because it owns local servers and child processes.
+ */
+export const runtime = 'nodejs';
+
+/**
+ * Handles project runtime commands from local agent runners.
+ */
+export async function POST(request: Request) {
+    if (!isAuthorizedInternalWorkerRequest(request)) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    try {
+        const payload = await parseAgentProjectRuntimeRequest(request);
+        const runtimeInfo = await executeAgentProjectRuntimeRequest(payload);
+
+        return NextResponse.json({ runtime: runtimeInfo });
+    } catch (error) {
+        if (error instanceof ParseError || error instanceof NotAllowed) {
+            return NextResponse.json({ error: error.message }, { status: 400 });
+        }
+
+        if (error instanceof NotFoundError) {
+            return NextResponse.json({ error: error.message }, { status: 404 });
+        }
+
+        console.error('[agent-project-runtimes] internal route failed', error);
+        return NextResponse.json(
+            {
+                error: error instanceof Error ? error.message : 'Failed to manage agent project runtime.',
+            },
+            { status: 500 },
+        );
+    }
+}
+
+/**
+ * Parses and validates the internal project runtime request body.
+ */
+async function parseAgentProjectRuntimeRequest(request: Request): Promise<AgentProjectRuntimeRequest> {
+    const rawBody = await request.json().catch(() => null);
+
+    if (!rawBody || typeof rawBody !== 'object') {
+        throw new ParseError('Expected a JSON object body.');
+    }
+
+    const body = rawBody as Record<string, unknown>;
+    const action = normalizeAgentProjectRuntimeAction(body.action);
+    const agentPermanentId = normalizeRequiredText(body.agentPermanentId, 'agentPermanentId');
+    const projectName = normalizeRequiredText(body.projectName, 'projectName');
+    const serverDomain =
+        normalizeOptionalText(body.serverDomain, 'serverDomain') || resolveServerDomainFromRequest(request);
+
+    return {
+        action,
+        agentPermanentId,
+        projectName,
+        ...(serverDomain !== undefined ? { serverDomain } : {}),
+    };
+}
+
+/**
+ * Executes one normalized project runtime request.
+ */
+async function executeAgentProjectRuntimeRequest(payload: AgentProjectRuntimeRequest) {
+    if (payload.action === 'assign_port') {
+        return await assignAgentProjectPort(payload);
+    }
+
+    if (payload.action === 'start') {
+        return await startAgentProjectRuntime(payload);
+    }
+
+    return await terminateAgentProjectRuntimeForProject(payload);
+}
+
+/**
+ * Validates one action value.
+ */
+function normalizeAgentProjectRuntimeAction(rawAction: unknown): AgentProjectRuntimeRequestAction {
+    const normalizedAction = normalizeRequiredText(rawAction, 'action');
+
+    if (AGENT_PROJECT_RUNTIME_REQUEST_ACTIONS.includes(normalizedAction as AgentProjectRuntimeRequestAction)) {
+        return normalizedAction as AgentProjectRuntimeRequestAction;
+    }
+
+    throw new ParseError(
+        `Invalid action \`${normalizedAction}\`. Use one of: \`${AGENT_PROJECT_RUNTIME_REQUEST_ACTIONS.join(
+            '`, `',
+        )}\`.`,
+    );
+}
+
+/**
+ * Normalizes one required text field.
+ */
+function normalizeRequiredText(rawValue: unknown, fieldName: string): string {
+    if (typeof rawValue !== 'string') {
+        throw new ParseError(`Missing required \`${fieldName}\` string.`);
+    }
+
+    const normalizedValue = rawValue.trim();
+    if (!normalizedValue) {
+        throw new ParseError(`Missing required \`${fieldName}\` string.`);
+    }
+
+    return normalizedValue;
+}
+
+/**
+ * Normalizes one optional text field.
+ */
+function normalizeOptionalText(rawValue: unknown, fieldName: string): string | undefined {
+    if (rawValue === undefined || rawValue === null) {
+        return undefined;
+    }
+
+    if (typeof rawValue !== 'string') {
+        throw new ParseError(`Invalid \`${fieldName}\` value. Expected a string.`);
+    }
+
+    const normalizedValue = rawValue.trim();
+    return normalizedValue || undefined;
+}
+
+/**
+ * Validates the shared internal worker token.
+ */
+function isAuthorizedInternalWorkerRequest(request: Request): boolean {
+    const token = request.headers.get(USER_CHAT_WORKER_TOKEN_HEADER);
+    return isTimingSafeEqualString(token, resolveUserChatWorkerInternalToken());
+}
+
+/**
+ * Resolves the public server domain forwarded to the internal worker request.
+ */
+function resolveServerDomainFromRequest(request: Request): string | undefined {
+    return (
+        request.headers.get('x-promptbook-server') ||
+        request.headers.get('x-forwarded-host') ||
+        request.headers.get('host') ||
+        undefined
+    );
+}

package/apps/agents-server/src/app/api/internal/user-chat-jobs/run/route.ts

@@ -1,7 +1,6 @@
-import { processNextLocalUserChatJob, type ProcessLocalUserChatJobResult } from '@/src/utils/localChatRunner';
 import {
-    recoverExpiredRunningUserChatJobs,
     resolveUserChatWorkerInternalToken,
+    runDurableUserChatJobWorkerTick,
     triggerUserChatJobWorker,
 } from '@/src/utils/userChat';
 import { after, NextResponse } from 'next/server';
@@ -31,6 +30,10 @@ export async function POST(request: Request) {
 /**
  * Validates authorization and executes one durable user-chat worker tick.
  *
+ * A preferred job is scoped to the current request's server. A plain coordinator poll fans
+ * out across every registered server on the VPS so jobs advance for all servers, not only the
+ * first/default one.
+ *
  * @param request - Incoming route request.
  * @returns Worker execution response.
  */
@@ -49,10 +52,8 @@ async function handleUserChatJobWorkerRequest(request: Request) {
     const preferredJobId = typeof body.preferredJobId === 'string' ? body.preferredJobId : undefined;
 
     try {
-        await recoverExpiredRunningUserChatJobs();
-
-        const processedJob = await processNextLocalUserChatJob({ preferredJobId });
-        if (!processedJob || !shouldRequeueUserChatJobWorker(processedJob)) {
+        const { didMutate } = await runDurableUserChatJobWorkerTick({ preferredJobId });
+        if (!didMutate) {
             return new Response(null, { status: 204 });
         }
 
@@ -74,18 +75,6 @@ async function handleUserChatJobWorkerRequest(request: Request) {
     }
 }
 
-/**
- * Decides whether one worker outcome should immediately schedule another worker tick.
- *
- * Mutating outcomes may have exposed more queued work, while non-mutating `waiting`
- * outcomes need the foreground fallback poll instead of a tight self-requeue loop.
- *
- * @private route helper
- */
-function shouldRequeueUserChatJobWorker(processedJob: ProcessLocalUserChatJobResult): boolean {
-    return processedJob.didMutate;
-}
-
 /**
  * Validates the internal worker token.
  *

package/apps/agents-server/src/app/api/messages/route.ts

@@ -2,6 +2,7 @@ import { NextRequest, NextResponse } from 'next/server';
 import { $getTableName } from '../../../database/$getTableName';
 import { $provideSupabase } from '../../../database/$provideSupabase';
 import { isUserAdmin } from '../../../utils/isUserAdmin';
+import type { MessageSortField, MessageSortOrder } from '../../../utils/messagesAdmin';
 
 /**
  * Size of default page.
@@ -22,6 +23,24 @@ function parsePositiveInt(value: string | null, fallback: number): number {
     return parsed;
 }
 
+/**
+ * Parses message table sort field.
+ */
+function parseMessageSortField(value: string | null): MessageSortField {
+    if (value === 'channel' || value === 'direction' || value === 'content') {
+        return value;
+    }
+
+    return 'createdAt';
+}
+
+/**
+ * Parses message table sort order.
+ */
+function parseMessageSortOrder(value: string | null): MessageSortOrder {
+    return value === 'asc' ? 'asc' : 'desc';
+}
+
 /**
  * List messages with filters, search and pagination.
  */
@@ -38,6 +57,8 @@ export async function GET(request: NextRequest) {
         const search = searchParams.get('search')?.trim() || '';
         const channel = searchParams.get('channel');
         const direction = searchParams.get('direction');
+        const sortBy = parseMessageSortField(searchParams.get('sortBy'));
+        const sortOrder = parseMessageSortOrder(searchParams.get('sortOrder'));
 
         const supabase = $provideSupabase();
 
@@ -61,8 +82,7 @@ export async function GET(request: NextRequest) {
             query = query.ilike('content', `%${escaped}%`);
         }
 
-        // Default sort by createdAt desc
-        query = query.order('createdAt', { ascending: false });
+        query = query.order(sortBy, { ascending: sortOrder === 'asc' });
 
         const from = (page - 1) * pageSize;
         const to = from + pageSize - 1;
@@ -103,6 +123,8 @@ export async function GET(request: NextRequest) {
             total: count ?? 0,
             page,
             pageSize,
+            sortBy,
+            sortOrder,
         });
     } catch (error) {
         console.error('List messages error:', error);

package/apps/agents-server/src/app/api/onboarding/book/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { convertManGoDraftToBook } from '@/src/utils/manGoOnboarding/manGoOnboardingAgentRuntime';
+import { createManGoOnboardingApiErrorResponse } from '@/src/utils/manGoOnboarding/manGoOnboardingApiResponses';
+import { readManGoOnboardingStringProperty } from '@/src/utils/manGoOnboarding/manGoOnboardingApiRequest';
+
+/**
+ * Handles `POST /api/onboarding/book`.
+ *
+ * @param request - Incoming request with the editable draft input.
+ * @returns Canonical Book-language source and validation flag.
+ */
+export async function POST(request: NextRequest) {
+    try {
+        const body = await request.json();
+        const input = readManGoOnboardingStringProperty(body, 'input');
+        const result = await convertManGoDraftToBook({ input });
+
+        return NextResponse.json(result);
+    } catch (error) {
+        return createManGoOnboardingApiErrorResponse(error);
+    }
+}

package/apps/agents-server/src/app/api/onboarding/draft/route.ts

@@ -0,0 +1,23 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { createManGoOnboardingApiErrorResponse } from '@/src/utils/manGoOnboarding/manGoOnboardingApiResponses';
+import { generateManGoBookDraft } from '@/src/utils/manGoOnboarding/manGoOnboardingAgentRuntime';
+import { readManGoOnboardingStringProperty } from '@/src/utils/manGoOnboarding/manGoOnboardingApiRequest';
+
+/**
+ * Handles `POST /api/onboarding/draft`.
+ *
+ * @param request - Incoming request with `agentName` and `agentBrief`.
+ * @returns Generated Book draft.
+ */
+export async function POST(request: NextRequest) {
+    try {
+        const body = await request.json();
+        const agentName = readManGoOnboardingStringProperty(body, 'agentName');
+        const agentBrief = readManGoOnboardingStringProperty(body, 'agentBrief');
+        const draft = await generateManGoBookDraft({ agentName, agentBrief });
+
+        return NextResponse.json({ draft });
+    } catch (error) {
+        return createManGoOnboardingApiErrorResponse(error);
+    }
+}

package/apps/agents-server/src/app/api/onboarding/evaluate/route.ts

@@ -0,0 +1,25 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { evaluateManGoAgentReply } from '@/src/utils/manGoOnboarding/manGoOnboardingAgentRuntime';
+import { createManGoOnboardingApiErrorResponse } from '@/src/utils/manGoOnboarding/manGoOnboardingApiResponses';
+import { readManGoOnboardingStringProperty } from '@/src/utils/manGoOnboarding/manGoOnboardingApiRequest';
+
+/**
+ * Handles `POST /api/onboarding/evaluate`.
+ *
+ * @param request - Incoming request with source, customer input, and generated reply.
+ * @returns AI-generated reply checks.
+ */
+export async function POST(request: NextRequest) {
+    try {
+        const body = await request.json();
+        const result = await evaluateManGoAgentReply({
+            bookSource: readManGoOnboardingStringProperty(body, 'bookSource'),
+            customerEmail: readManGoOnboardingStringProperty(body, 'customerEmail'),
+            reply: readManGoOnboardingStringProperty(body, 'reply'),
+        });
+
+        return NextResponse.json(result);
+    } catch (error) {
+        return createManGoOnboardingApiErrorResponse(error);
+    }
+}

package/apps/agents-server/src/app/api/onboarding/test/route.ts

@@ -0,0 +1,29 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { runManGoAgentTest } from '@/src/utils/manGoOnboarding/manGoOnboardingAgentRuntime';
+import { createManGoOnboardingApiErrorResponse } from '@/src/utils/manGoOnboarding/manGoOnboardingApiResponses';
+import {
+    readManGoOnboardingStringArrayProperty,
+    readManGoOnboardingStringProperty,
+    readManGoOnboardingTestMessages,
+} from '@/src/utils/manGoOnboarding/manGoOnboardingApiRequest';
+
+/**
+ * Handles `POST /api/onboarding/test`.
+ *
+ * @param request - Incoming request with source, knowledge URLs, and test messages.
+ * @returns Live agent reply for the test step.
+ */
+export async function POST(request: NextRequest) {
+    try {
+        const body = await request.json();
+        const result = await runManGoAgentTest({
+            bookSource: readManGoOnboardingStringProperty(body, 'bookSource'),
+            knowledge: readManGoOnboardingStringArrayProperty(body, 'knowledge'),
+            messages: readManGoOnboardingTestMessages(body),
+        });
+
+        return NextResponse.json(result);
+    } catch (error) {
+        return createManGoOnboardingApiErrorResponse(error);
+    }
+}

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

@@ -1,55 +1,22 @@
 import type { NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
+import { normalizePagePreviewInputEvent } from '../../../../../../../src/book-components/Chat/Chat/pagePreview/normalizePagePreviewInputEvent';
+import { assertsError } from '../../../../../../../src/errors/assertsError';
+import { applyPagePreviewBrowserInput } from '../../../../utils/applyPagePreviewBrowserInput';
 import { getCurrentUser } from '../../../../utils/getCurrentUser';
+import { getPagePreviewBrowserSessionState } from '../../../../utils/getPagePreviewBrowserSessionState';
 import {
     findUserPagePreviewBrowserSession,
     normalizePagePreviewBrowserSessionId,
 } from '../../../../utils/pagePreviewBrowserSessions';
 
 /**
- * Maximum absolute wheel delta accepted from one preview input event.
+ * Applies one remote-control event to an active live browser preview session.
  *
- * @private route constant of `/api/page-preview/input`
- */
-const MAX_WHEEL_DELTA = 1600;
-
-/**
- * Payload accepted by the live page-preview input route.
- *
- * @private route type of `/api/page-preview/input`
- */
-type PagePreviewInputPayload = {
-    readonly sessionId?: unknown;
-    readonly type?: unknown;
-    readonly xRatio?: unknown;
-    readonly yRatio?: unknown;
-    readonly deltaX?: unknown;
-    readonly deltaY?: unknown;
-};
-
-/**
- * Normalized browser input event.
- *
- * @private route type of `/api/page-preview/input`
- */
-type PagePreviewInputEvent =
-    | {
-          readonly sessionId: string;
-          readonly type: 'click';
-          readonly xRatio: number;
-          readonly yRatio: number;
-      }
-    | {
-          readonly sessionId: string;
-          readonly type: 'wheel';
-          readonly xRatio: number;
-          readonly yRatio: number;
-          readonly deltaX: number;
-          readonly deltaY: number;
-      };
-
-/**
- * Applies one pointer or wheel event to an active live browser preview session.
+ * Accepts the full page-preview input protocol — pointer moves (hover), presses and releases
+ * (clicks, double-clicks, drags, text selection), wheel scrolling, keyboard typing, viewport
+ * resizes, history navigation, and direct URL navigation. Responds with the fresh session
+ * navigation state so the preview toolbar stays in sync.
  */
 export async function POST(request: NextRequest): Promise<NextResponse> {
     const currentUser = await getCurrentUser();
@@ -57,105 +24,27 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
         return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
     }
 
-    const payload = (await request.json().catch(() => null)) as PagePreviewInputPayload | null;
+    const payload = (await request.json().catch(() => null)) as { sessionId?: unknown } | null;
+    const sessionId = normalizePagePreviewBrowserSessionId(
+        typeof payload?.sessionId === 'string' ? payload.sessionId : null,
+    );
     const inputEvent = normalizePagePreviewInputEvent(payload);
-    if (!inputEvent) {
+    if (!sessionId || !inputEvent) {
         return NextResponse.json({ error: 'Invalid browser preview input.' }, { status: 400 });
     }
 
-    const session = findUserPagePreviewBrowserSession(inputEvent.sessionId, currentUser);
+    const session = findUserPagePreviewBrowserSession(sessionId, currentUser);
     if (!session?.page || !session.viewport) {
         return NextResponse.json({ error: 'Browser preview session is not active.' }, { status: 404 });
     }
 
-    const x = inputEvent.xRatio * session.viewport.width;
-    const y = inputEvent.yRatio * session.viewport.height;
-
-    if (inputEvent.type === 'click') {
-        await session.page.mouse.click(x, y);
-    } else {
-        await session.page.mouse.move(x, y);
-        await session.page.mouse.wheel(inputEvent.deltaX, inputEvent.deltaY);
+    try {
+        await applyPagePreviewBrowserInput(session, inputEvent);
+    } catch (error) {
+        assertsError(error);
+        return NextResponse.json({ error: error.message }, { status: 400 });
     }
 
-    return NextResponse.json({ ok: true });
+    const state = await getPagePreviewBrowserSessionState(session);
+    return NextResponse.json({ ok: true, state });
 }
-
-/**
- * Normalizes and validates one browser-preview input payload.
- *
- * @param payload - Unknown JSON payload.
- * @returns Normalized input event or `null` when invalid.
- */
-function normalizePagePreviewInputEvent(payload: PagePreviewInputPayload | null): PagePreviewInputEvent | null {
-    if (!payload) {
-        return null;
-    }
-
-    const sessionId = normalizePagePreviewBrowserSessionId(
-        typeof payload.sessionId === 'string' ? payload.sessionId : null,
-    );
-    const xRatio = normalizeRatio(payload.xRatio);
-    const yRatio = normalizeRatio(payload.yRatio);
-
-    if (!sessionId || xRatio === null || yRatio === null) {
-        return null;
-    }
-
-    if (payload.type === 'click') {
-        return {
-            sessionId,
-            type: 'click',
-            xRatio,
-            yRatio,
-        };
-    }
-
-    if (payload.type !== 'wheel') {
-        return null;
-    }
-
-    const deltaX = normalizeWheelDelta(payload.deltaX);
-    const deltaY = normalizeWheelDelta(payload.deltaY);
-    if (deltaX === null || deltaY === null) {
-        return null;
-    }
-
-    return {
-        sessionId,
-        type: 'wheel',
-        xRatio,
-        yRatio,
-        deltaX,
-        deltaY,
-    };
-}
-
-/**
- * Normalizes a pointer coordinate ratio.
- *
- * @param value - Unknown payload value.
- * @returns Ratio clamped to the viewport bounds, or `null` when invalid.
- */
-function normalizeRatio(value: unknown): number | null {
-    if (typeof value !== 'number' || !Number.isFinite(value)) {
-        return null;
-    }
-
-    return Math.max(0, Math.min(1, value));
-}
-
-/**
- * Normalizes one mouse-wheel delta.
- *
- * @param value - Unknown payload value.
- * @returns Clamped wheel delta, or `null` when invalid.
- */
-function normalizeWheelDelta(value: unknown): number | null {
-    if (typeof value !== 'number' || !Number.isFinite(value)) {
-        return null;
-    }
-
-    return Math.max(-MAX_WHEEL_DELTA, Math.min(MAX_WHEEL_DELTA, value));
-}
-

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

@@ -0,0 +1,46 @@
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+import { getCurrentUser } from '../../../../utils/getCurrentUser';
+import { getPagePreviewBrowserSessionState } from '../../../../utils/getPagePreviewBrowserSessionState';
+import {
+    findUserPagePreviewBrowserSession,
+    normalizePagePreviewBrowserSessionId,
+} from '../../../../utils/pagePreviewBrowserSessions';
+
+/**
+ * Forces this route to read fresh session state on every request.
+ */
+export const dynamic = 'force-dynamic';
+
+/**
+ * Returns the navigation state of one active live browser preview session.
+ *
+ * Query parameters:
+ * - `sessionId` — page-preview browser session id owned by the current user
+ *
+ * The preview toolbar polls this route to keep its URL bar and history buttons in sync with
+ * navigations that happen inside the remote page itself (for example clicked links).
+ */
+export async function GET(request: NextRequest): Promise<NextResponse> {
+    const currentUser = await getCurrentUser();
+    if (!currentUser) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    const sessionId = normalizePagePreviewBrowserSessionId(request.nextUrl.searchParams.get('sessionId'));
+    if (!sessionId) {
+        return NextResponse.json({ error: 'Missing or invalid query parameter: sessionId' }, { status: 400 });
+    }
+
+    const session = findUserPagePreviewBrowserSession(sessionId, currentUser);
+    if (!session) {
+        return NextResponse.json({ error: 'Browser preview session is not active.' }, { status: 404 });
+    }
+
+    const state = await getPagePreviewBrowserSessionState(session);
+    if (!state) {
+        return NextResponse.json({ error: 'Browser preview session has no active page.' }, { status: 404 });
+    }
+
+    return NextResponse.json({ state });
+}

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

@@ -1,7 +1,12 @@
 import { serializeError } from '@promptbook-local/utils';
 import type { NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
+import {
+    clampPagePreviewViewport,
+    PAGE_PREVIEW_DEFAULT_VIEWPORT,
+} from '../../../../../../../src/book-components/Chat/Chat/pagePreview/PagePreviewViewport';
 import { assertsError } from '../../../../../../../src/errors/assertsError';
+import { $provideAgentBrowserProfile } from '../../../../utils/agentBrowserProfile/$provideAgentBrowserProfile';
 import { assertSafeUrl } from '../../../../utils/assertSafeUrl';
 import {
     createPagePreviewBrowserStream,
@@ -24,6 +29,10 @@ export const dynamic = 'force-dynamic';
  * Query parameters:
  * - `url` — fully-qualified public HTTP(S) URL to preview
  * - `sessionId` — client-created browser-preview session id used for interaction events
+ * - `width` / `height` — optional initial viewport measured from the client preview area
+ * - `agent` — optional agent identifier (name or permanent id); when set, the live session runs
+ *   inside the agent's persistent browser profile so logins performed by the user are saved for
+ *   the agent's future browsing
  *
  * Requires authentication to prevent unauthenticated SSRF and browser-process abuse.
  */
@@ -35,6 +44,11 @@ export async function GET(request: NextRequest): Promise<NextResponse> {
 
     const url = request.nextUrl.searchParams.get('url');
     const sessionId = normalizePagePreviewBrowserSessionId(request.nextUrl.searchParams.get('sessionId'));
+    const viewport =
+        clampPagePreviewViewport(
+            Number.parseFloat(request.nextUrl.searchParams.get('width') ?? ''),
+            Number.parseFloat(request.nextUrl.searchParams.get('height') ?? ''),
+        ) ?? PAGE_PREVIEW_DEFAULT_VIEWPORT;
 
     if (!url) {
         return NextResponse.json({ error: 'Missing required query parameter: url' }, { status: 400 });
@@ -52,6 +66,14 @@ export async function GET(request: NextRequest): Promise<NextResponse> {
     }
 
     try {
+        const agentIdentifier = request.nextUrl.searchParams.get('agent')?.trim() || null;
+        const agentBrowserProfile = agentIdentifier
+            ? await $provideAgentBrowserProfile({
+                  agentIdentifier,
+                  userId: typeof currentUser.id === 'number' ? currentUser.id : undefined,
+              })
+            : null;
+
         registerPagePreviewBrowserSession({
             sessionId,
             url,
@@ -62,6 +84,8 @@ export async function GET(request: NextRequest): Promise<NextResponse> {
             request,
             sessionId,
             url,
+            viewport,
+            browserProfileDirectory: agentBrowserProfile?.directory ?? null,
         });
 
         return new NextResponse(stream, {