@promptbook/cli 0.112.0 → 0.113.0-1

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/app/api/v1/agents/[agentId]/route.ts

@@ -18,6 +18,7 @@ import {
     ManagementAgentPathParamsSchema,
     ManagementAgentUpdateRequestSchema,
 } from '@/src/utils/managementApi/managementApiSchemas';
+import { setAgentSourceVisibility } from '@/src/utils/agentVisibility';
 import {
     createManagementApiErrorResponse,
     createManagementApiJsonResponse,
@@ -34,7 +35,6 @@ type ManagementAgentUpdateRequest = z.infer<typeof ManagementAgentUpdateRequestS
  * Agent metadata fields updated directly in the database during `PATCH`.
  */
 type ManagementAgentMetadataUpdate = {
-    visibility?: ManagementAgentUpdateRequest['visibility'];
     folderId?: ManagementAgentUpdateRequest['folderId'];
     sortOrder?: ManagementAgentUpdateRequest['sortOrder'];
     updatedAt?: string;
@@ -259,7 +259,11 @@ async function updateOwnedAgentSourceIfNeeded(
     existingAgent: OwnedAgentRow,
     updateRequest: ManagementAgentUpdateRequest,
 ): Promise<void> {
-    if (updateRequest.name === undefined && updateRequest.source === undefined) {
+    if (
+        updateRequest.name === undefined &&
+        updateRequest.source === undefined &&
+        updateRequest.visibility === undefined
+    ) {
         return;
     }
 
@@ -280,11 +284,15 @@ function createUpdatedOwnedAgentSource(
     updateRequest: ManagementAgentUpdateRequest,
 ): string_book {
     const sourceWithRequestedContent = (updateRequest.source || existingAgent.agentSource) as string_book;
-    if (!updateRequest.name) {
-        return sourceWithRequestedContent;
+    const sourceWithRequestedName = updateRequest.name
+        ? renameAgentSource(sourceWithRequestedContent, updateRequest.name)
+        : sourceWithRequestedContent;
+
+    if (updateRequest.visibility === undefined) {
+        return sourceWithRequestedName;
     }
 
-    return renameAgentSource(sourceWithRequestedContent, updateRequest.name);
+    return setAgentSourceVisibility(sourceWithRequestedName, updateRequest.visibility);
 }
 
 /**
@@ -302,9 +310,6 @@ async function createOwnedAgentMetadataUpdate(
 ): Promise<ManagementAgentMetadataUpdate> {
     const metadataUpdate: ManagementAgentMetadataUpdate = {};
 
-    if (updateRequest.visibility !== undefined) {
-        metadataUpdate.visibility = updateRequest.visibility;
-    }
     if (updateRequest.folderId !== undefined) {
         metadataUpdate.folderId = updateRequest.folderId;
     }

package/apps/agents-server/src/components/AgentProfile/AgentCapabilityChips.tsx

@@ -18,6 +18,7 @@ import {
     Users,
 } from 'lucide-react';
 import NextLink from 'next/link';
+import { isVoidPseudoAgentReference } from '../../../../../src/book-2.0/agent-source/pseudoAgentReferences';
 import { simplifyKnowledgeLabel } from '@/src/utils/knowledge/simplifyKnowledgeLabel';
 import { buildFreshAgentChatHrefFromAgentUrl } from '../../utils/agentRouting/agentRouteHrefs';
 import { TeamCommitmentChip } from './TeamCommitmentChip';
@@ -32,6 +33,11 @@ export const HOMEPAGE_CAPABILITY_CHIPS_LIMIT = 3;
  */
 export const AGENT_PROFILE_CAPABILITY_CHIPS_LIMIT = 7;
 
+/**
+ * Capability types omitted from homepage agent cards.
+ */
+export const AGENT_CARD_HIDDEN_CAPABILITY_TYPES: ReadonlyArray<AgentCapability['type']> = ['time'];
+
 /**
  * Constant for max individual knowledge chips.
  */
@@ -82,6 +88,11 @@ type AgentCapabilityChipsProps = {
      * Visual size preset for chip rendering.
      */
     readonly size?: AgentCapabilityChipsSize;
+
+    /**
+     * Capability types that should be omitted from this chip list.
+     */
+    readonly hiddenCapabilityTypes?: ReadonlyArray<AgentCapability['type']>;
 };
 
 /**
@@ -107,13 +118,23 @@ type OrderedCapability = {
 /**
  * Render capability chips for an agent with priority, grouping, and limits.
  */
-export function AgentCapabilityChips({ agent, className, maxChips, size = 'default' }: AgentCapabilityChipsProps) {
+export function AgentCapabilityChips({
+    agent,
+    className,
+    maxChips,
+    size = 'default',
+    hiddenCapabilityTypes = [],
+}: AgentCapabilityChipsProps) {
     if (!agent.capabilities || agent.capabilities.length === 0) {
         return null;
     }
 
     const maxChipsToDisplay = maxChips ?? AGENT_PROFILE_CAPABILITY_CHIPS_LIMIT;
-    const displayedCapabilities = selectCapabilitiesForDisplay(agent.capabilities, maxChipsToDisplay);
+    const displayedCapabilities = selectCapabilitiesForDisplay(
+        agent.capabilities,
+        maxChipsToDisplay,
+        hiddenCapabilityTypes,
+    );
 
     if (displayedCapabilities.length === 0) {
         return null;
@@ -228,12 +249,13 @@ export function AgentCapabilityChips({ agent, className, maxChips, size = 'defau
 function selectCapabilitiesForDisplay(
     capabilities: Array<AgentCapability>,
     maxChips: number,
+    hiddenCapabilityTypes: ReadonlyArray<AgentCapability['type']>,
 ): Array<AgentCapability> {
     if (maxChips <= 0) {
         return [];
     }
 
-    const normalizedCapabilities = normalizeCapabilities(capabilities);
+    const normalizedCapabilities = normalizeCapabilities(capabilities, hiddenCapabilityTypes);
     const groupedCapabilities = groupKnowledgeCapabilities(normalizedCapabilities);
     const prioritizedCapabilities = groupedCapabilities
         .map((item, index) => ({
@@ -263,11 +285,23 @@ function selectCapabilitiesForDisplay(
  * @param capabilities - Raw capability list from the agent.
  * @returns Normalized capabilities with ordering metadata.
  */
-function normalizeCapabilities(capabilities: Array<AgentCapability>): Array<OrderedCapability> {
+function normalizeCapabilities(
+    capabilities: Array<AgentCapability>,
+    hiddenCapabilityTypes: ReadonlyArray<AgentCapability['type']>,
+): Array<OrderedCapability> {
+    const hiddenCapabilityTypeSet = new Set(hiddenCapabilityTypes);
+
     return capabilities
         .map((capability, index) => ({ capability, order: index }))
         .filter((item) => {
-            if (item.capability.type === 'inheritance' && item.capability.agentUrl === 'VOID') {
+            if (hiddenCapabilityTypeSet.has(item.capability.type)) {
+                return false;
+            }
+
+            if (
+                item.capability.type === 'inheritance' &&
+                isVoidPseudoAgentReference(item.capability.agentUrl || item.capability.label)
+            ) {
                 return false;
             }
 

package/apps/agents-server/src/components/Homepage/AgentCard.tsx

@@ -5,7 +5,11 @@ import { CheckCircle2Icon, EyeIcon, EyeOffIcon, LockIcon, RotateCcwIcon } from '
 import Link from 'next/link';
 import { AgentBasicInformation } from '../../../../../src/book-2.0/agent-source/AgentBasicInformation';
 import type { AgentVisibility } from '../../utils/agentVisibility';
-import { AgentCapabilityChips, HOMEPAGE_CAPABILITY_CHIPS_LIMIT } from '../AgentProfile/AgentCapabilityChips';
+import {
+    AGENT_CARD_HIDDEN_CAPABILITY_TYPES,
+    AgentCapabilityChips,
+    HOMEPAGE_CAPABILITY_CHIPS_LIMIT,
+} from '../AgentProfile/AgentCapabilityChips';
 import { useAgentBackground } from '../AgentProfile/useAgentBackground';
 import { useAgentNaming } from '../AgentNaming/AgentNamingContext';
 import { AgentAvatar } from '../AgentAvatar/AgentAvatar';
@@ -153,6 +157,7 @@ export function AgentCard({
                             <AgentCapabilityChips
                                 agent={agent}
                                 className="mt-2"
+                                hiddenCapabilityTypes={AGENT_CARD_HIDDEN_CAPABILITY_TYPES}
                                 maxChips={HOMEPAGE_CAPABILITY_CHIPS_LIMIT}
                                 size="compact"
                             />
@@ -202,6 +207,7 @@ export function AgentCard({
                             <AgentCapabilityChips
                                 agent={agent}
                                 className="mt-2"
+                                hiddenCapabilityTypes={AGENT_CARD_HIDDEN_CAPABILITY_TYPES}
                                 maxChips={HOMEPAGE_CAPABILITY_CHIPS_LIMIT}
                                 size="compact"
                             />

package/apps/agents-server/src/components/Homepage/AgentsList.tsx

@@ -91,13 +91,16 @@ export function AgentsList(props: AgentsListProps) {
                 allAgentsLabel={state.allAgentsLabel}
                 breadcrumbFolders={state.breadcrumbFolders}
                 canOrganize={canOrganize}
+                hasHiddenFolders={state.hasHiddenFolders}
                 headingTitle={state.headingTitle}
                 isAdmin={isAdmin}
                 isAgentsExporting={state.isAgentsExporting}
                 isAgentsImporting={state.isAgentsImporting}
+                isHiddenFoldersVisible={state.isHiddenFoldersVisible}
                 onCreateFolder={state.handleCreateFolder}
                 onExportAgents={() => void state.handleAgentsExport()}
                 onNavigateToFolder={state.navigateToFolder}
+                onSetHiddenFoldersVisible={state.setHiddenFoldersVisible}
                 onSetViewMode={state.setViewMode}
                 viewMode={state.viewMode}
             />

package/apps/agents-server/src/components/Homepage/AgentsListHeader.tsx

@@ -3,6 +3,8 @@
 import {
     Building2,
     DownloadIcon,
+    Eye,
+    EyeOff,
     FolderPlusIcon,
     Gamepad2,
     Grid,
@@ -60,6 +62,10 @@ type AgentsListHeaderProps = {
      * Whether folder-management controls are available.
      */
     readonly canOrganize: boolean;
+    /**
+     * Whether the unfiltered organization snapshot contains at least one hidden folder.
+     */
+    readonly hasHiddenFolders: boolean;
     /**
      * Current heading title.
      */
@@ -68,6 +74,10 @@ type AgentsListHeaderProps = {
      * Whether agents import/export controls are available.
      */
     readonly isAdmin: boolean;
+    /**
+     * Whether hidden folders are currently rendered in the agents list.
+     */
+    readonly isHiddenFoldersVisible: boolean;
     /**
      * Downloads an agents archive.
      */
@@ -80,6 +90,10 @@ type AgentsListHeaderProps = {
      * Navigates to the selected folder scope.
      */
     readonly onNavigateToFolder: (folderId: number | null) => void;
+    /**
+     * Toggles whether hidden folders are visible in the agents list.
+     */
+    readonly onSetHiddenFoldersVisible: (isVisible: boolean) => void;
     /**
      * Switches the homepage view mode.
      */
@@ -124,13 +138,16 @@ export function AgentsListHeader({
     allAgentsLabel,
     breadcrumbFolders,
     canOrganize,
+    hasHiddenFolders,
     headingTitle,
     isAdmin,
     isAgentsExporting,
     isAgentsImporting,
+    isHiddenFoldersVisible,
     onCreateFolder,
     onExportAgents,
     onNavigateToFolder,
+    onSetHiddenFoldersVisible,
     onSetViewMode,
     viewMode,
 }: AgentsListHeaderProps) {
@@ -192,6 +209,30 @@ export function AgentsListHeader({
                             New Folder
                         </button>
                     )}
+                    {hasHiddenFolders && (
+                        <button
+                            type="button"
+                            onClick={() => onSetHiddenFoldersVisible(!isHiddenFoldersVisible)}
+                            className={`flex items-center gap-2 px-3 py-2 rounded-lg border text-sm transition-colors ${
+                                isHiddenFoldersVisible
+                                    ? 'border-blue-200 bg-blue-50 text-blue-700 hover:bg-blue-100'
+                                    : 'border-gray-200 bg-white text-gray-700 hover:bg-gray-50'
+                            }`}
+                            title={
+                                isHiddenFoldersVisible
+                                    ? 'Hide folders whose name starts with "."'
+                                    : 'Show folders whose name starts with "."'
+                            }
+                            aria-pressed={isHiddenFoldersVisible}
+                        >
+                            {isHiddenFoldersVisible ? (
+                                <EyeOff className="w-4 h-4" />
+                            ) : (
+                                <Eye className="w-4 h-4" />
+                            )}
+                            {isHiddenFoldersVisible ? 'Hide hidden' : 'Show hidden'}
+                        </button>
+                    )}
                     <div className="flex items-center gap-2 bg-gray-100 p-1 rounded-lg ml-4">
                         {VIEW_MODE_BUTTONS.map(({ mode, label, title, icon: Icon }) => (
                             <button