@promptbook/cli 0.113.0-8 → 0.114.0-0

package/apps/agents-server/src/search/createDefaultServerSearchProviders/createConversationsSearchProvider.ts

@@ -28,7 +28,7 @@ type UserChatSearchRow = Pick<
  */
 type ChatHistorySearchRow = Pick<
     AgentsServerDatabase['public']['Tables']['ChatHistory']['Row'],
-    'id' | 'createdAt' | 'agentName' | 'message' | 'url' | 'ip'
+    'id' | 'createdAt' | 'agentName' | 'chatId' | 'message' | 'url' | 'ip'
 >;
 
 /**
@@ -162,7 +162,7 @@ async function searchAdminConversations(
     const supabase = $provideSupabaseForServer();
     const { data, error } = await supabase
         .from(await $getTableName('ChatHistory'))
-        .select('id, createdAt, agentName, message, url, ip')
+        .select('id, createdAt, agentName, chatId, message, url, ip')
         .order('createdAt', { ascending: false })
         .limit(defaultServerSearchProviderConfig.adminLogLimit);
 
@@ -185,6 +185,13 @@ async function searchAdminConversations(
             continue;
         }
 
+        const adminChatHistoryParams = new URLSearchParams({ agentName: row.agentName });
+        if (row.chatId) {
+            // Note: Deep-link straight to the recorded conversation (most detailed view) when the thread is known
+            adminChatHistoryParams.set('chatId', row.chatId);
+            adminChatHistoryParams.set('view', 'chat');
+        }
+
         results.push({
             id: `conversation-admin-${row.id}`,
             providerId: 'conversations',
@@ -193,7 +200,7 @@ async function searchAdminConversations(
             icon: 'conversation',
             title: `Chat log #${row.id} (${row.agentName})`,
             snippet: match.snippet,
-            href: `/admin/chat-history?agentName=${encodeURIComponent(row.agentName)}`,
+            href: `/admin/chat-history?${adminChatHistoryParams.toString()}`,
             score: match.score + 6,
         });
     }

package/apps/agents-server/src/tools/$provideBrowserForServer.ts

@@ -14,7 +14,10 @@ let browserProvider: BrowserConnectionProvider | null = null;
  * This function supports both local and remote browser connections based on environment configuration.
  * Use REMOTE_BROWSER_URL environment variable to configure a remote Playwright server.
  *
- * @param options - Optional runtime request options used for cancellation and logging context.
+ * Pass `options.browserProfileDirectory` to browse inside the persistent isolated browser profile
+ * of one agent instead of the shared default profile.
+ *
+ * @param options - Optional runtime request options used for cancellation, profile selection and logging context.
  * @returns Browser context instance
  */
 export async function $provideBrowserForServer(options: BrowserContextRequestOptions = {}): Promise<BrowserContext> {

package/apps/agents-server/src/tools/$provideServer.ts

@@ -5,11 +5,12 @@ import { isAgentsServerSqliteMode } from '../database/agentsServerDatabaseMode';
 import { resolveInternalServerOrigin } from '../utils/resolveInternalServerOrigin';
 import { createServerPublicUrl, listRegisteredServersUsingServiceRole } from '../utils/serverRegistry';
 import { resolveServerSelection } from '../utils/serverSelection';
+import { getServerContextOverride } from './serverContextOverride';
 
 /**
  * Resolved server routing context for the current request.
  */
-type ProvidedServer = {
+export type ProvidedServer = {
     /**
      * Registered server id when the request points to one.
      */
@@ -63,7 +64,7 @@ const getCachedProvidedServer = cache(async (): Promise<ProvidedServer> => {
                     };
                 }
 
-                throw new Error(`Server with host "${requestHost}" is not registered in SERVERS`);
+                throw new Error(`Server with host "${requestHost}" is not registered in the VPS server registry`);
             }
 
             return {
@@ -118,9 +119,20 @@ const getCachedProvidedServer = cache(async (): Promise<ProvidedServer> => {
 /**
  * Resolves the current server routing context.
  *
+ * When a background worker runs work on behalf of one specific VPS server (see
+ * `runWithServerContextOverride`), the explicit override wins over the request-header
+ * resolution. This lets a single detached worker tick process every registered server
+ * on the VPS without depending on a matching `host` header, which loopback self-calls
+ * never carry.
+ *
  * @returns Server routing context for the current request.
  */
 export async function $provideServer(): Promise<ProvidedServer> {
+    const overriddenServer = getServerContextOverride();
+    if (overriddenServer) {
+        return overriddenServer;
+    }
+
     return getCachedProvidedServer();
 }
 

package/apps/agents-server/src/tools/BrowserConnectionProvider.ts

@@ -1,5 +1,5 @@
 import { mkdir } from 'fs/promises';
-import { BrowserContext, chromium } from 'playwright';
+import { Browser, BrowserContext, chromium } from 'playwright';
 import { resolvePromptbookTemporaryPath } from '../../../../src/utils/filesystem/promptbookTemporaryPath';
 import { REMOTE_BROWSER_URL } from '../../config';
 import { createServerChromiumLaunchOptions } from './createServerChromiumLaunchOptions';
@@ -29,6 +29,24 @@ const DEFAULT_BROWSER_USER_DATA_DIR = resolvePromptbookTemporaryPath(
     'user-data',
 );
 
+/**
+ * Cache key used for the shared default browser context without an agent profile.
+ */
+const DEFAULT_BROWSER_PROFILE_KEY = 'default';
+
+/**
+ * Default idle time after which one unused browser context (with no open pages) is closed.
+ *
+ * The persistent profile directory outlives the closed browser, so closing idle contexts frees
+ * server resources without losing any cookies or sessions.
+ */
+const DEFAULT_BROWSER_CONTEXT_IDLE_TIMEOUT_MS = 10 * 60 * 1000;
+
+/**
+ * Interval between idle-context sweeps.
+ */
+const BROWSER_CONTEXT_IDLE_SWEEP_INTERVAL_MS = 60 * 1000;
+
 /**
  * Default remote browser connect timeout in milliseconds.
  */
@@ -81,6 +99,37 @@ export type BrowserContextRequestOptions = {
      * Optional browser run session identifier for structured logs.
      */
     readonly sessionId?: string;
+    /**
+     * Optional persistent browser-profile directory (Playwright user data dir) of one agent.
+     *
+     * When set, the browser context is launched on this profile so cookies, sessions and other
+     * browser data persist across sessions. When omitted, the shared default profile is used.
+     */
+    readonly browserProfileDirectory?: string | null;
+};
+
+/**
+ * One cached browser context together with its lifecycle metadata.
+ *
+ * @private internal type for `BrowserConnectionProvider`
+ */
+type ManagedBrowserContext = {
+    /**
+     * The cached Playwright browser context.
+     */
+    readonly context: BrowserContext;
+    /**
+     * Remote browser connection owning the context, `null` in local mode.
+     */
+    readonly remoteBrowser: Browser | null;
+    /**
+     * Connection mode used to create the context.
+     */
+    readonly mode: BrowserConnectionMode;
+    /**
+     * Timestamp of the last context acquisition, used by the idle sweep.
+     */
+    lastUsedAt: number;
 };
 
 /**
@@ -117,6 +166,10 @@ type BrowserConnectionProviderOptions = {
      * Retry jitter ratio.
      */
     readonly remoteConnectJitterRatio?: number;
+    /**
+     * Idle time after which one unused browser context (with no open pages) is closed.
+     */
+    readonly contextIdleTimeoutMs?: number;
     /**
      * Optional random provider used by retry jitter.
      */
@@ -211,14 +264,23 @@ function createAbortError(): Error {
  * - Local mode: Launches a persistent Chromium context on the same machine
  * - Remote mode: Connects to a remote Playwright browser via WebSocket
  *
+ * Contexts are cached per browser-profile directory so every agent can browse in its own
+ * persistent isolated profile. Contexts without open pages are closed after an idle timeout -
+ * the profile data on disk stays permanent, only the browser process is released.
+ *
+ * Note: Remote Playwright browsers do not support persistent user-data profiles, so in remote
+ * mode the per-profile contexts are isolated from each other but survive only for one connection.
+ *
  * The remote mode is useful for environments like Vercel where running a full browser
  * is not possible due to resource constraints.
  *
  * @private internal utility for Agents Server browser tools
  */
 export class BrowserConnectionProvider {
-    private browserContext: BrowserContext | null = null;
-    private connectionMode: BrowserConnectionMode | null = null;
+    private readonly managedBrowserContexts = new Map<string, ManagedBrowserContext>();
+    private readonly pendingBrowserContextCreations = new Map<string, Promise<BrowserContext>>();
+    private idleSweepTimer: ReturnType<typeof setInterval> | null = null;
+    private readonly contextIdleTimeoutMs: number;
     private readonly isVerbose: boolean;
     private readonly remoteConnectTimeoutMs: number;
     private readonly remoteConnectRetries: number;
@@ -258,6 +320,9 @@ export class BrowserConnectionProvider {
         this.remoteConnectJitterRatio =
             options.remoteConnectJitterRatio ??
             resolveNonNegativeNumberFromEnv('RUN_BROWSER_CONNECT_JITTER_RATIO', DEFAULT_REMOTE_CONNECT_JITTER_RATIO);
+        this.contextIdleTimeoutMs =
+            options.contextIdleTimeoutMs ??
+            resolvePositiveIntFromEnv('RUN_BROWSER_CONTEXT_IDLE_TIMEOUT_MS', DEFAULT_BROWSER_CONTEXT_IDLE_TIMEOUT_MS);
         this.random = options.random ?? Math.random;
         this.sleep = options.sleep;
     }
@@ -268,6 +333,9 @@ export class BrowserConnectionProvider {
      * This method automatically determines whether to use local or remote browser
      * based on the REMOTE_BROWSER_URL environment variable.
      *
+     * Contexts are cached per `browserProfileDirectory` so agents with a persistent
+     * browser profile never share cookies or sessions with each other.
+     *
      * @returns Browser context instance
      */
     public async getBrowserContext(options: BrowserContextRequestOptions = {}): Promise<BrowserContext> {
@@ -275,91 +343,218 @@ export class BrowserConnectionProvider {
             throw createAbortError();
         }
 
+        const browserProfileDirectory = options.browserProfileDirectory?.trim() || null;
+        const profileKey = browserProfileDirectory ?? DEFAULT_BROWSER_PROFILE_KEY;
+
         // Check if we have a cached connection that's still valid
-        if (this.browserContext !== null && this.isBrowserContextAlive(this.browserContext)) {
-            return this.browserContext;
+        const cachedManagedContext = this.managedBrowserContexts.get(profileKey);
+        if (cachedManagedContext && this.isBrowserContextAlive(cachedManagedContext.context)) {
+            cachedManagedContext.lastUsedAt = Date.now();
+            return cachedManagedContext.context;
+        }
+        this.managedBrowserContexts.delete(profileKey);
+
+        // Concurrent requests for the same profile must share one creation - a persistent
+        // Chromium profile directory can only be opened by one browser process at a time
+        const pendingCreation = this.pendingBrowserContextCreations.get(profileKey);
+        if (pendingCreation) {
+            return await pendingCreation;
+        }
+
+        const creation = this.createManagedBrowserContext(profileKey, browserProfileDirectory, options);
+        this.pendingBrowserContextCreations.set(profileKey, creation);
+        try {
+            return await creation;
+        } finally {
+            this.pendingBrowserContextCreations.delete(profileKey);
         }
+    }
 
+    /**
+     * Creates and caches one browser context for the requested profile.
+     *
+     * @param profileKey - Cache key of the created context.
+     * @param browserProfileDirectory - Persistent per-agent profile directory or `null` for the shared default profile.
+     * @param options - Runtime request options.
+     * @returns Created browser context.
+     */
+    private async createManagedBrowserContext(
+        profileKey: string,
+        browserProfileDirectory: string | null,
+        options: BrowserContextRequestOptions,
+    ): Promise<BrowserContext> {
         // Determine connection mode from configuration
         const mode = this.resolveConnectionMode();
-        this.connectionMode = mode;
 
         if (this.isVerbose) {
             console.info('[BrowserConnectionProvider] Creating new browser context', {
                 mode: mode.type,
+                profileKey,
                 wsEndpoint: mode.type === 'remote' ? mode.wsEndpoint : undefined,
             });
         }
 
         // Create new browser context based on mode
+        let managedContext: ManagedBrowserContext;
         if (mode.type === 'local') {
-            this.browserContext = await this.createLocalBrowserContext();
+            managedContext = {
+                context: await this.createLocalBrowserContext(browserProfileDirectory),
+                remoteBrowser: null,
+                mode,
+                lastUsedAt: Date.now(),
+            };
         } else {
-            this.browserContext = await this.createRemoteBrowserContext(mode.wsEndpoint, options);
+            const { context, browser } = await this.createRemoteBrowserContext(mode.wsEndpoint, options);
+            managedContext = {
+                context,
+                remoteBrowser: browser,
+                mode,
+                lastUsedAt: Date.now(),
+            };
         }
 
-        return this.browserContext;
+        this.managedBrowserContexts.set(profileKey, managedContext);
+        this.ensureIdleSweepTimerIsRunning();
+
+        return managedContext.context;
     }
 
     /**
-     * Closes all pages in the current browser context.
+     * Closes all pages in all cached browser contexts.
      *
      * This method is useful for cleanup between agent tasks without closing
-     * the entire browser instance.
+     * the browser instances themselves.
      */
     public async closeAllPages(): Promise<void> {
-        if (!this.browserContext) {
-            return;
-        }
+        for (const managedContext of this.managedBrowserContexts.values()) {
+            try {
+                const pages = managedContext.context.pages();
 
-        try {
-            const pages = this.browserContext.pages();
-
-            if (this.isVerbose) {
-                console.info('[BrowserConnectionProvider] Closing all pages', {
-                    pageCount: pages.length,
-                });
+                if (this.isVerbose) {
+                    console.info('[BrowserConnectionProvider] Closing all pages', {
+                        pageCount: pages.length,
+                    });
+                }
+
+                await Promise.all(
+                    pages.map((page) =>
+                        page.close().catch((error) => {
+                            console.error('[BrowserConnectionProvider] Failed to close page', { error });
+                        }),
+                    ),
+                );
+            } catch (error) {
+                console.error('[BrowserConnectionProvider] Error closing pages', { error });
             }
-
-            await Promise.all(
-                pages.map((page) =>
-                    page.close().catch((error) => {
-                        console.error('[BrowserConnectionProvider] Failed to close page', { error });
-                    }),
-                ),
-            );
-        } catch (error) {
-            console.error('[BrowserConnectionProvider] Error closing pages', { error });
         }
     }
 
     /**
-     * Closes the browser context and disconnects from the browser.
+     * Closes all cached browser contexts and disconnects from remote browsers.
      *
      * This should be called when the browser is no longer needed to free up resources.
-     * For local mode, this closes the browser process. For remote mode, it disconnects
-     * from the remote browser but doesn't shut down the remote server.
+     * For local mode, this closes the browser processes (the persistent profile directories stay
+     * on disk). For remote mode, it disconnects from the remote browser but doesn't shut down
+     * the remote server.
      */
     public async close(): Promise<void> {
-        if (!this.browserContext) {
-            return;
+        this.stopIdleSweepTimer();
+
+        const managedContextEntries = [...this.managedBrowserContexts.entries()];
+        this.managedBrowserContexts.clear();
+
+        for (const [profileKey, managedContext] of managedContextEntries) {
+            await this.closeManagedBrowserContext(profileKey, managedContext);
         }
+    }
 
+    /**
+     * Closes one cached browser context together with its remote connection when present.
+     *
+     * @param profileKey - Cache key of the closed context.
+     * @param managedContext - Context to close.
+     */
+    private async closeManagedBrowserContext(profileKey: string, managedContext: ManagedBrowserContext): Promise<void> {
         try {
             if (this.isVerbose) {
                 console.info('[BrowserConnectionProvider] Closing browser context', {
-                    mode: this.connectionMode?.type,
+                    mode: managedContext.mode.type,
+                    profileKey,
                 });
             }
 
-            await this.browserContext.close();
-            this.browserContext = null;
-            this.connectionMode = null;
+            await managedContext.context.close();
         } catch (error) {
-            console.error('[BrowserConnectionProvider] Error closing browser context', { error });
-            // Reset state even if close fails
-            this.browserContext = null;
-            this.connectionMode = null;
+            console.error('[BrowserConnectionProvider] Error closing browser context', { error, profileKey });
+        }
+
+        if (managedContext.remoteBrowser) {
+            try {
+                await managedContext.remoteBrowser.close();
+            } catch (error) {
+                console.error('[BrowserConnectionProvider] Error disconnecting remote browser', { error, profileKey });
+            }
+        }
+    }
+
+    /**
+     * Starts the periodic idle sweep releasing browser contexts that are no longer used.
+     *
+     * The timer is unreferenced so it never keeps the Node process alive.
+     */
+    private ensureIdleSweepTimerIsRunning(): void {
+        if (this.idleSweepTimer !== null) {
+            return;
+        }
+
+        this.idleSweepTimer = setInterval(() => {
+            void this.closeIdleBrowserContexts();
+        }, BROWSER_CONTEXT_IDLE_SWEEP_INTERVAL_MS);
+        (this.idleSweepTimer as { unref?: () => void }).unref?.();
+    }
+
+    /**
+     * Stops the periodic idle sweep.
+     */
+    private stopIdleSweepTimer(): void {
+        if (this.idleSweepTimer !== null) {
+            clearInterval(this.idleSweepTimer);
+            this.idleSweepTimer = null;
+        }
+    }
+
+    /**
+     * Closes cached browser contexts that have no open pages and were idle beyond the timeout.
+     *
+     * Persistent profile data stays on disk - only the running browser is released so the server
+     * does not keep browsers alive while no agent or user is using them.
+     */
+    private async closeIdleBrowserContexts(): Promise<void> {
+        const now = Date.now();
+
+        for (const [profileKey, managedContext] of this.managedBrowserContexts.entries()) {
+            if (now - managedContext.lastUsedAt < this.contextIdleTimeoutMs) {
+                continue;
+            }
+
+            let openPageCount = 0;
+            try {
+                openPageCount = managedContext.context.pages().length;
+            } catch {
+                openPageCount = 0;
+            }
+
+            if (openPageCount > 0) {
+                managedContext.lastUsedAt = now;
+                continue;
+            }
+
+            this.managedBrowserContexts.delete(profileKey);
+            await this.closeManagedBrowserContext(profileKey, managedContext);
+        }
+
+        if (this.managedBrowserContexts.size === 0) {
+            this.stopIdleSweepTimer();
         }
     }
 
@@ -399,14 +594,17 @@ export class BrowserConnectionProvider {
     /**
      * Creates a local browser context using persistent Chromium.
      *
+     * @param browserProfileDirectory - Persistent per-agent profile directory or `null` for the shared default profile.
      * @returns Local browser context
      */
-    private async createLocalBrowserContext(): Promise<BrowserContext> {
+    private async createLocalBrowserContext(browserProfileDirectory: string | null): Promise<BrowserContext> {
         if (this.isVerbose) {
-            console.info('[BrowserConnectionProvider] Launching local browser context');
+            console.info('[BrowserConnectionProvider] Launching local browser context', {
+                browserProfileDirectory,
+            });
         }
 
-        const userDataDir = `${DEFAULT_BROWSER_USER_DATA_DIR}/run-browser`;
+        const userDataDir = browserProfileDirectory ?? `${DEFAULT_BROWSER_USER_DATA_DIR}/run-browser`;
         await mkdir(userDataDir, { recursive: true });
 
         const launchOptions = await createServerChromiumLaunchOptions();
@@ -418,12 +616,12 @@ export class BrowserConnectionProvider {
      * Creates a remote browser context by connecting to a Playwright server.
      *
      * @param wsEndpoint - WebSocket endpoint of the remote Playwright server
-     * @returns Remote browser context
+     * @returns Remote browser context together with its owning connection
      */
     private async createRemoteBrowserContext(
         wsEndpoint: string,
         options: BrowserContextRequestOptions,
-    ): Promise<BrowserContext> {
+    ): Promise<{ context: BrowserContext; browser: Browser }> {
         const endpointDebug = sanitizeRemoteBrowserEndpoint(wsEndpoint);
         const startedAt = Date.now();
 
@@ -473,7 +671,8 @@ export class BrowserConnectionProvider {
             const browser = connectResult.value;
 
             // For remote connections, we need to create a new context
-            // Note: Remote browsers don't support persistent contexts
+            // Note: Remote browsers don't support persistent contexts, so per-agent isolation is
+            // provided by separate contexts but the profile data is not persisted remotely
             const context = await browser.newContext();
             REMOTE_BROWSER_CONNECT_METRICS.success++;
 
@@ -492,7 +691,7 @@ export class BrowserConnectionProvider {
                 console.info('[BrowserConnectionProvider] Successfully connected to remote browser');
             }
 
-            return context;
+            return { context, browser };
         } catch (error) {
             REMOTE_BROWSER_CONNECT_METRICS.failure++;
             const durationMs = Date.now() - startedAt;

package/apps/agents-server/src/tools/mapRegisteredServerContexts.ts

@@ -0,0 +1,104 @@
+import {
+    createServerPublicUrl,
+    listRegisteredServersUsingServiceRole,
+    normalizeServerDomain,
+    resolveRegisteredServerByHost,
+    type ServerRecord,
+} from '../utils/serverRegistry';
+import type { ProvidedServer } from './$provideServer';
+import { runWithServerContextOverride } from './serverContextOverride';
+
+/**
+ * Result of running one callback inside a single registered server's context.
+ *
+ * @private internal type of Agents Server server-context routing
+ */
+export type ServerContextRun<TResult> = {
+    /**
+     * Registered server the callback ran for, or `null` when the deployment has no
+     * registered servers and the callback ran once in the ambient request context.
+     */
+    readonly server: ServerRecord | null;
+
+    /**
+     * Value returned by the callback for this server.
+     */
+    readonly value: TResult;
+};
+
+/**
+ * Runs one callback once per registered VPS server, each inside that server's routing context.
+ *
+ * This is the shared VPS-wide iteration primitive: it lets a single detached process
+ * (a background worker tick or a superadmin aggregation) touch every server on the VPS
+ * without a per-server `host` header. Servers are processed sequentially so per-server
+ * work never competes for the same resources at once.
+ *
+ * When no servers are registered (for example local development or a single-tenant
+ * deployment before the registry is populated) the callback runs exactly once in the
+ * ambient request context with `server` resolved to `null`.
+ *
+ * @param callback - Work to run for each server; receives the server it runs for.
+ * @returns One run result per server, in registry order.
+ *
+ * @private internal utility of Agents Server server-context routing
+ */
+export async function mapRegisteredServerContexts<TResult>(
+    callback: (server: ServerRecord | null) => Promise<TResult>,
+): Promise<Array<ServerContextRun<TResult>>> {
+    const registeredServers = await listRegisteredServersUsingServiceRole();
+
+    if (registeredServers.length === 0) {
+        return [{ server: null, value: await callback(null) }];
+    }
+
+    const serverRuns: Array<ServerContextRun<TResult>> = [];
+    for (const server of registeredServers) {
+        const providedServer: ProvidedServer = {
+            id: server.id,
+            publicUrl: createServerPublicUrl(server.domain),
+            tablePrefix: server.tablePrefix,
+        };
+        const value = await runWithServerContextOverride(providedServer, () => callback(server));
+        serverRuns.push({ server, value });
+    }
+
+    return serverRuns;
+}
+
+/**
+ * Runs one callback inside the registered server identified by its domain.
+ *
+ * The helper is used by VPS-wide admin actions after the listing has identified the owning
+ * server. Returning `null` for an unknown domain keeps a stale task row from being treated as a
+ * task belonging to the ambient request server.
+ *
+ * @param serverDomain - Domain of the registered server to enter.
+ * @param callback - Work to run inside the selected server context.
+ * @returns Callback result, or `null` when the server is no longer registered.
+ *
+ * @private internal utility of Agents Server server-context routing
+ */
+export async function runWithRegisteredServerContext<TResult>(
+    serverDomain: string,
+    callback: () => Promise<TResult>,
+): Promise<TResult | null> {
+    const normalizedServerDomain = normalizeServerDomain(serverDomain);
+    if (!normalizedServerDomain) {
+        return null;
+    }
+
+    const registeredServers = await listRegisteredServersUsingServiceRole();
+    const server = resolveRegisteredServerByHost(normalizedServerDomain, registeredServers);
+    if (!server) {
+        return null;
+    }
+
+    const providedServer: ProvidedServer = {
+        id: server.id,
+        publicUrl: createServerPublicUrl(server.domain),
+        tablePrefix: server.tablePrefix,
+    };
+
+    return runWithServerContextOverride(providedServer, callback);
+}

package/apps/agents-server/src/tools/runBrowserWorkflow.ts

@@ -48,6 +48,10 @@ export const runBrowserWorkflow = {
         readonly sessionId: string;
         readonly timeouts: RunBrowserTimeoutConfiguration;
         readonly signal?: AbortSignal;
+        /**
+         * Persistent per-agent browser-profile directory, `null` for the shared default profile.
+         */
+        readonly browserProfileDirectory?: string | null;
     }): Promise<OpenPageWithUrlResult> {
         runBrowserErrorHandling.assertNotAborted(options.signal, options.sessionId);
 
@@ -55,6 +59,7 @@ export const runBrowserWorkflow = {
         const browserContext = await $provideBrowserForServer({
             signal: options.signal,
             sessionId: options.sessionId,
+            browserProfileDirectory: options.browserProfileDirectory,
         });
         const connectDurationMs = Date.now() - connectStartedAt;
         const page = await browserContext.newPage();