@mastra/agent-browser 0.1.0-alpha.0 → 0.2.0-alpha.0

package/dist/index.d.cts

@@ -283,14 +283,32 @@ declare const browserSchemas: {
     }, z.core.$strip>;
 };
 
+/**
+ * AgentBrowser-specific configuration extensions.
+ */
+interface AgentBrowserConfigExtensions {
+    /**
+     * Path to a Playwright storage state file (JSON) containing cookies and localStorage.
+     * This is a lighter-weight alternative to `profile` — it only persists
+     * authentication state, not the full browser profile.
+     *
+     * You can export storage state from a Playwright session and reuse it later.
+     *
+     * @example
+     * ```ts
+     * { storageState: './auth-state.json' }
+     * ```
+     */
+    storageState?: string;
+}
 /**
  * Configuration options for AgentBrowser.
- * Type alias for BaseBrowserConfig.
+ * Extends the base BrowserConfig with agent-browser specific options.
  */
-type BrowserConfig = BrowserConfig$1;
+type BrowserConfig = BrowserConfig$1 & AgentBrowserConfigExtensions;
 
 /**
- * AgentBrowserThreadManager - Thread isolation for AgentBrowser
+ * AgentBrowserThreadManager - Thread scope management for AgentBrowser
  *
  * Manages thread-scoped browser sessions using agent-browser's
  * BrowserManager capabilities (newWindow, switchTo, closeTab).
@@ -322,25 +340,14 @@ interface AgentBrowserThreadManagerConfig extends ThreadManagerConfig {
  * - 'thread': Each thread gets a dedicated browser manager instance
  */
 declare class AgentBrowserThreadManager extends ThreadManager<BrowserManager> {
-    private sharedManager;
     private readonly browserConfig;
     private readonly resolveCdpUrl?;
     private readonly onBrowserCreated?;
-    /** Map of thread ID to dedicated browser manager (for 'thread' scope) */
-    private readonly threadBrowsers;
     constructor(config: AgentBrowserThreadManagerConfig);
     /**
-     * Set the shared browser manager (called after browser launch).
-     */
-    setSharedManager(manager: BrowserManager): void;
-    /**
-     * Clear the shared browser manager (called when browser disconnects).
-     */
-    clearSharedManager(): void;
-    /**
-     * Get the shared browser manager.
+     * Get the page for a specific thread, creating session if needed.
      */
-    protected getSharedManager(): BrowserManager;
+    getPageForThread(threadId?: string): Promise<Page>;
     /**
      * Create a new session for a thread.
      */
@@ -349,12 +356,6 @@ declare class AgentBrowserThreadManager extends ThreadManager<BrowserManager> {
      * Restore browser state (multiple tabs) to a browser manager.
      */
     private restoreBrowserState;
-    /**
-     * Switch to an existing session.
-     * For 'thread' scope, no switching needed - each thread has its own manager.
-     * For 'shared' scope, nothing to switch.
-     */
-    protected switchToSession(_session: AgentBrowserSession): Promise<void>;
     /**
      * Get the browser manager for a specific session.
      */
@@ -365,29 +366,9 @@ declare class AgentBrowserThreadManager extends ThreadManager<BrowserManager> {
     protected doDestroySession(session: AgentBrowserSession): Promise<void>;
     /**
      * Destroy all sessions (called during browser close).
+     * doDestroySession handles closing individual browser managers.
      */
     destroyAllSessions(): Promise<void>;
-    /**
-     * Check if any thread browsers are still running.
-     */
-    hasActiveThreadBrowsers(): boolean;
-    /**
-     * Get the browser manager for an existing thread session without creating a new one.
-     * Returns null if no session exists for the thread.
-     */
-    getExistingManagerForThread(threadId: string): BrowserManager | null;
-    /**
-     * Clear all session tracking without closing browsers.
-     * Used when browsers have been externally closed and we just need to reset state.
-     */
-    clearAllSessions(): void;
-    /**
-     * Clear a specific thread's session without closing the browser.
-     * Used when a thread's browser has been externally closed.
-     * Preserves the browser state for potential restoration.
-     * @param threadId - The thread ID to clear
-     */
-    clearSession(threadId: string): void;
 }
 
 /**
@@ -399,13 +380,11 @@ declare class AgentBrowser extends MastraBrowser {
     readonly id: string;
     readonly name = "AgentBrowser";
     readonly provider = "vercel-labs/agent-browser";
-    /** Primary browser manager (for 'none' mode, also used as fallback) */
-    private browserManager;
+    /** Shared browser manager instance (for 'shared' scope) - narrowed type from base class */
+    protected sharedManager: BrowserManager | null;
     private defaultTimeout;
-    /** Active screencast streams per thread (for triggering reconnects on tab changes) */
-    private activeScreencastStreams;
-    /** Default key for shared scope */
-    private static readonly SHARED_STREAM_KEY;
+    /** Pending PID lookups — awaited in disconnect handlers to avoid racing. */
+    private pidLookups;
     /** Thread manager - narrowed type from base class */
     protected threadManager: AgentBrowserThreadManager;
     constructor(config?: BrowserConfig);
@@ -413,32 +392,22 @@ declare class AgentBrowser extends MastraBrowser {
      * Ensure browser is ready and thread session exists.
      * Creates a new page/context for the current thread if needed.
      *
-     * For 'browser' isolation, we need to create the thread session BEFORE
+     * For 'thread' scope, we need to create the thread session BEFORE
      * calling super.ensureReady() because the base class's ensureReady() will
      * call checkBrowserAlive(), which needs at least one thread browser to exist.
      */
     ensureReady(): Promise<void>;
     /**
      * Get the browser manager for the current thread.
-     * Delegates to ThreadManager for isolation handling.
+     * Delegates to ThreadManager for scope handling.
      */
     getManagerForThread(threadId?: string): Promise<BrowserManager>;
-    /**
-     * Get the page for a specific thread.
-     * For thread-isolated modes, ensures we're on the correct context/page.
-     */
-    getPageForThread(threadId?: string): Promise<Page>;
-    /**
-     * Close a specific thread's browser session.
-     * Delegates to ThreadManager and notifies registered callbacks.
-     */
-    closeThreadSession(threadId: string): Promise<void>;
     protected doLaunch(): Promise<void>;
     /**
-     * Set up close event listeners for 'none' isolation shared browser.
+     * Set up close event listeners for 'shared' scope browser.
      * This handles the case where the shared browser is closed externally.
      */
-    private setupCloseListenerForNoneIsolation;
+    private setupCloseListenerForSharedScope;
     protected doClose(): Promise<void>;
     /**
      * Check if the browser is still alive by verifying the page is connected.
@@ -458,21 +427,15 @@ declare class AgentBrowser extends MastraBrowser {
      */
     private getPage;
     /**
-     * Handle browser disconnection by clearing internal state.
-     * For 'thread' scope, only notifies the specific thread's callbacks.
-     * For 'shared' scope, notifies all callbacks.
+     * Get the active page for a thread (implements abstract method from base class).
+     * Returns null if no page is available, unlike getPage which throws.
      */
-    handleBrowserDisconnected(): void;
+    protected getActivePage(threadId?: string): Promise<Page | null>;
     /**
      * Set up close event listener for a thread's browser manager.
      * This handles the case where a thread's browser is closed externally.
      */
     private setupCloseListenerForThread;
-    /**
-     * Handle browser disconnection for a specific thread.
-     * Called when a thread's browser is closed externally.
-     */
-    private handleThreadBrowserDisconnected;
     /**
      * Create an error response from an exception.
      * Extends base class to add agent-browser specific error handling.
@@ -494,6 +457,11 @@ declare class AgentBrowser extends MastraBrowser {
      * Get the current browser state (all tabs and active tab index).
      */
     getBrowserState(threadId?: string): Promise<BrowserState | null>;
+    /**
+     * Get browser state for a thread (implements abstract method from base class).
+     * Sync version that uses existing manager lookup without creating sessions.
+     */
+    protected getBrowserStateForThread(threadId?: string): BrowserState | null;
     /**
      * Get browser state from a specific manager instance.
      */
@@ -507,10 +475,13 @@ declare class AgentBrowser extends MastraBrowser {
      */
     getActiveTabIndex(threadId?: string): Promise<number>;
     /**
-     * Update the browser state in the thread session.
-     * Called on navigation, tab open/close to keep state fresh.
+     * Export the current browser session's storage state (cookies, localStorage) to a JSON file.
+     * This can later be loaded via the `storageState` config option to restore the session.
+     *
+     * @param path - File path to save the storage state JSON
+     * @param threadId - Optional thread ID (defaults to current thread)
      */
-    private updateSessionBrowserState;
+    exportStorageState(path: string, threadId?: string): Promise<void>;
     goto(input: GotoInput, threadId?: string): Promise<{
         success: true;
         url: string;
@@ -602,20 +573,22 @@ declare class AgentBrowser extends MastraBrowser {
         success: true;
         hint: string;
     } | BrowserToolError>;
-    /**
-     * Get the stream key for a thread (or shared key for shared scope).
-     */
-    private getStreamKey;
-    /**
-     * Trigger a screencast reconnect after tab changes.
-     * Called internally when tabs are switched or closed.
-     */
-    private reconnectScreencast;
     startScreencast(_options?: ScreencastOptions): Promise<ScreencastStream>;
     injectMouseEvent(event: MouseEventParams, threadId?: string): Promise<void>;
     injectKeyboardEvent(event: KeyboardEventParams, threadId?: string): Promise<void>;
 }
 
+/**
+ * Get the browser process PID from a BrowserManager instance via CDP.
+ *
+ * Playwright doesn't expose the browser process PID directly, so we use CDP's
+ * SystemInfo.getProcessInfo to get it. This works for both regular browser
+ * launches and persistent contexts (profiles).
+ *
+ * Returns undefined if the PID can't be retrieved (e.g., browser not running).
+ */
+declare function getBrowserPid(manager: BrowserManager): Promise<number | undefined>;
+
 /**
  * Browser Tool Constants
  */
@@ -651,4 +624,4 @@ type BrowserToolName = (typeof BROWSER_TOOLS)[keyof typeof BROWSER_TOOLS];
  */
 declare function createAgentBrowserTools(browser: AgentBrowser): Record<string, Tool<any, any>>;
 
-export { AgentBrowser, BROWSER_TOOLS, type BackInput, type BrowserConfig, type BrowserToolName, type ClickInput, type CloseInput, type DialogInput, type DragInput, type EvaluateInput, type GotoInput, type HoverInput, type PressInput, type ScrollInput, type SelectInput, type SnapshotInput, type TabsInput, type TypeInput, type WaitInput, backInputSchema, browserSchemas, clickInputSchema, closeInputSchema, createAgentBrowserTools, dialogInputSchema, dragInputSchema, evaluateInputSchema, gotoInputSchema, hoverInputSchema, pressInputSchema, scrollInputSchema, selectInputSchema, snapshotInputSchema, tabsInputSchema, typeInputSchema, waitInputSchema };
+export { AgentBrowser, BROWSER_TOOLS, type BackInput, type BrowserConfig, type BrowserToolName, type ClickInput, type CloseInput, type DialogInput, type DragInput, type EvaluateInput, type GotoInput, type HoverInput, type PressInput, type ScrollInput, type SelectInput, type SnapshotInput, type TabsInput, type TypeInput, type WaitInput, backInputSchema, browserSchemas, clickInputSchema, closeInputSchema, createAgentBrowserTools, dialogInputSchema, dragInputSchema, evaluateInputSchema, getBrowserPid, gotoInputSchema, hoverInputSchema, pressInputSchema, scrollInputSchema, selectInputSchema, snapshotInputSchema, tabsInputSchema, typeInputSchema, waitInputSchema };

package/dist/index.d.ts

@@ -283,14 +283,32 @@ declare const browserSchemas: {
     }, z.core.$strip>;
 };
 
+/**
+ * AgentBrowser-specific configuration extensions.
+ */
+interface AgentBrowserConfigExtensions {
+    /**
+     * Path to a Playwright storage state file (JSON) containing cookies and localStorage.
+     * This is a lighter-weight alternative to `profile` — it only persists
+     * authentication state, not the full browser profile.
+     *
+     * You can export storage state from a Playwright session and reuse it later.
+     *
+     * @example
+     * ```ts
+     * { storageState: './auth-state.json' }
+     * ```
+     */
+    storageState?: string;
+}
 /**
  * Configuration options for AgentBrowser.
- * Type alias for BaseBrowserConfig.
+ * Extends the base BrowserConfig with agent-browser specific options.
  */
-type BrowserConfig = BrowserConfig$1;
+type BrowserConfig = BrowserConfig$1 & AgentBrowserConfigExtensions;
 
 /**
- * AgentBrowserThreadManager - Thread isolation for AgentBrowser
+ * AgentBrowserThreadManager - Thread scope management for AgentBrowser
  *
  * Manages thread-scoped browser sessions using agent-browser's
  * BrowserManager capabilities (newWindow, switchTo, closeTab).
@@ -322,25 +340,14 @@ interface AgentBrowserThreadManagerConfig extends ThreadManagerConfig {
  * - 'thread': Each thread gets a dedicated browser manager instance
  */
 declare class AgentBrowserThreadManager extends ThreadManager<BrowserManager> {
-    private sharedManager;
     private readonly browserConfig;
     private readonly resolveCdpUrl?;
     private readonly onBrowserCreated?;
-    /** Map of thread ID to dedicated browser manager (for 'thread' scope) */
-    private readonly threadBrowsers;
     constructor(config: AgentBrowserThreadManagerConfig);
     /**
-     * Set the shared browser manager (called after browser launch).
-     */
-    setSharedManager(manager: BrowserManager): void;
-    /**
-     * Clear the shared browser manager (called when browser disconnects).
-     */
-    clearSharedManager(): void;
-    /**
-     * Get the shared browser manager.
+     * Get the page for a specific thread, creating session if needed.
      */
-    protected getSharedManager(): BrowserManager;
+    getPageForThread(threadId?: string): Promise<Page>;
     /**
      * Create a new session for a thread.
      */
@@ -349,12 +356,6 @@ declare class AgentBrowserThreadManager extends ThreadManager<BrowserManager> {
      * Restore browser state (multiple tabs) to a browser manager.
      */
     private restoreBrowserState;
-    /**
-     * Switch to an existing session.
-     * For 'thread' scope, no switching needed - each thread has its own manager.
-     * For 'shared' scope, nothing to switch.
-     */
-    protected switchToSession(_session: AgentBrowserSession): Promise<void>;
     /**
      * Get the browser manager for a specific session.
      */
@@ -365,29 +366,9 @@ declare class AgentBrowserThreadManager extends ThreadManager<BrowserManager> {
     protected doDestroySession(session: AgentBrowserSession): Promise<void>;
     /**
      * Destroy all sessions (called during browser close).
+     * doDestroySession handles closing individual browser managers.
      */
     destroyAllSessions(): Promise<void>;
-    /**
-     * Check if any thread browsers are still running.
-     */
-    hasActiveThreadBrowsers(): boolean;
-    /**
-     * Get the browser manager for an existing thread session without creating a new one.
-     * Returns null if no session exists for the thread.
-     */
-    getExistingManagerForThread(threadId: string): BrowserManager | null;
-    /**
-     * Clear all session tracking without closing browsers.
-     * Used when browsers have been externally closed and we just need to reset state.
-     */
-    clearAllSessions(): void;
-    /**
-     * Clear a specific thread's session without closing the browser.
-     * Used when a thread's browser has been externally closed.
-     * Preserves the browser state for potential restoration.
-     * @param threadId - The thread ID to clear
-     */
-    clearSession(threadId: string): void;
 }
 
 /**
@@ -399,13 +380,11 @@ declare class AgentBrowser extends MastraBrowser {
     readonly id: string;
     readonly name = "AgentBrowser";
     readonly provider = "vercel-labs/agent-browser";
-    /** Primary browser manager (for 'none' mode, also used as fallback) */
-    private browserManager;
+    /** Shared browser manager instance (for 'shared' scope) - narrowed type from base class */
+    protected sharedManager: BrowserManager | null;
     private defaultTimeout;
-    /** Active screencast streams per thread (for triggering reconnects on tab changes) */
-    private activeScreencastStreams;
-    /** Default key for shared scope */
-    private static readonly SHARED_STREAM_KEY;
+    /** Pending PID lookups — awaited in disconnect handlers to avoid racing. */
+    private pidLookups;
     /** Thread manager - narrowed type from base class */
     protected threadManager: AgentBrowserThreadManager;
     constructor(config?: BrowserConfig);
@@ -413,32 +392,22 @@ declare class AgentBrowser extends MastraBrowser {
      * Ensure browser is ready and thread session exists.
      * Creates a new page/context for the current thread if needed.
      *
-     * For 'browser' isolation, we need to create the thread session BEFORE
+     * For 'thread' scope, we need to create the thread session BEFORE
      * calling super.ensureReady() because the base class's ensureReady() will
      * call checkBrowserAlive(), which needs at least one thread browser to exist.
      */
     ensureReady(): Promise<void>;
     /**
      * Get the browser manager for the current thread.
-     * Delegates to ThreadManager for isolation handling.
+     * Delegates to ThreadManager for scope handling.
      */
     getManagerForThread(threadId?: string): Promise<BrowserManager>;
-    /**
-     * Get the page for a specific thread.
-     * For thread-isolated modes, ensures we're on the correct context/page.
-     */
-    getPageForThread(threadId?: string): Promise<Page>;
-    /**
-     * Close a specific thread's browser session.
-     * Delegates to ThreadManager and notifies registered callbacks.
-     */
-    closeThreadSession(threadId: string): Promise<void>;
     protected doLaunch(): Promise<void>;
     /**
-     * Set up close event listeners for 'none' isolation shared browser.
+     * Set up close event listeners for 'shared' scope browser.
      * This handles the case where the shared browser is closed externally.
      */
-    private setupCloseListenerForNoneIsolation;
+    private setupCloseListenerForSharedScope;
     protected doClose(): Promise<void>;
     /**
      * Check if the browser is still alive by verifying the page is connected.
@@ -458,21 +427,15 @@ declare class AgentBrowser extends MastraBrowser {
      */
     private getPage;
     /**
-     * Handle browser disconnection by clearing internal state.
-     * For 'thread' scope, only notifies the specific thread's callbacks.
-     * For 'shared' scope, notifies all callbacks.
+     * Get the active page for a thread (implements abstract method from base class).
+     * Returns null if no page is available, unlike getPage which throws.
      */
-    handleBrowserDisconnected(): void;
+    protected getActivePage(threadId?: string): Promise<Page | null>;
     /**
      * Set up close event listener for a thread's browser manager.
      * This handles the case where a thread's browser is closed externally.
      */
     private setupCloseListenerForThread;
-    /**
-     * Handle browser disconnection for a specific thread.
-     * Called when a thread's browser is closed externally.
-     */
-    private handleThreadBrowserDisconnected;
     /**
      * Create an error response from an exception.
      * Extends base class to add agent-browser specific error handling.
@@ -494,6 +457,11 @@ declare class AgentBrowser extends MastraBrowser {
      * Get the current browser state (all tabs and active tab index).
      */
     getBrowserState(threadId?: string): Promise<BrowserState | null>;
+    /**
+     * Get browser state for a thread (implements abstract method from base class).
+     * Sync version that uses existing manager lookup without creating sessions.
+     */
+    protected getBrowserStateForThread(threadId?: string): BrowserState | null;
     /**
      * Get browser state from a specific manager instance.
      */
@@ -507,10 +475,13 @@ declare class AgentBrowser extends MastraBrowser {
      */
     getActiveTabIndex(threadId?: string): Promise<number>;
     /**
-     * Update the browser state in the thread session.
-     * Called on navigation, tab open/close to keep state fresh.
+     * Export the current browser session's storage state (cookies, localStorage) to a JSON file.
+     * This can later be loaded via the `storageState` config option to restore the session.
+     *
+     * @param path - File path to save the storage state JSON
+     * @param threadId - Optional thread ID (defaults to current thread)
      */
-    private updateSessionBrowserState;
+    exportStorageState(path: string, threadId?: string): Promise<void>;
     goto(input: GotoInput, threadId?: string): Promise<{
         success: true;
         url: string;
@@ -602,20 +573,22 @@ declare class AgentBrowser extends MastraBrowser {
         success: true;
         hint: string;
     } | BrowserToolError>;
-    /**
-     * Get the stream key for a thread (or shared key for shared scope).
-     */
-    private getStreamKey;
-    /**
-     * Trigger a screencast reconnect after tab changes.
-     * Called internally when tabs are switched or closed.
-     */
-    private reconnectScreencast;
     startScreencast(_options?: ScreencastOptions): Promise<ScreencastStream>;
     injectMouseEvent(event: MouseEventParams, threadId?: string): Promise<void>;
     injectKeyboardEvent(event: KeyboardEventParams, threadId?: string): Promise<void>;
 }
 
+/**
+ * Get the browser process PID from a BrowserManager instance via CDP.
+ *
+ * Playwright doesn't expose the browser process PID directly, so we use CDP's
+ * SystemInfo.getProcessInfo to get it. This works for both regular browser
+ * launches and persistent contexts (profiles).
+ *
+ * Returns undefined if the PID can't be retrieved (e.g., browser not running).
+ */
+declare function getBrowserPid(manager: BrowserManager): Promise<number | undefined>;
+
 /**
  * Browser Tool Constants
  */
@@ -651,4 +624,4 @@ type BrowserToolName = (typeof BROWSER_TOOLS)[keyof typeof BROWSER_TOOLS];
  */
 declare function createAgentBrowserTools(browser: AgentBrowser): Record<string, Tool<any, any>>;
 
-export { AgentBrowser, BROWSER_TOOLS, type BackInput, type BrowserConfig, type BrowserToolName, type ClickInput, type CloseInput, type DialogInput, type DragInput, type EvaluateInput, type GotoInput, type HoverInput, type PressInput, type ScrollInput, type SelectInput, type SnapshotInput, type TabsInput, type TypeInput, type WaitInput, backInputSchema, browserSchemas, clickInputSchema, closeInputSchema, createAgentBrowserTools, dialogInputSchema, dragInputSchema, evaluateInputSchema, gotoInputSchema, hoverInputSchema, pressInputSchema, scrollInputSchema, selectInputSchema, snapshotInputSchema, tabsInputSchema, typeInputSchema, waitInputSchema };
+export { AgentBrowser, BROWSER_TOOLS, type BackInput, type BrowserConfig, type BrowserToolName, type ClickInput, type CloseInput, type DialogInput, type DragInput, type EvaluateInput, type GotoInput, type HoverInput, type PressInput, type ScrollInput, type SelectInput, type SnapshotInput, type TabsInput, type TypeInput, type WaitInput, backInputSchema, browserSchemas, clickInputSchema, closeInputSchema, createAgentBrowserTools, dialogInputSchema, dragInputSchema, evaluateInputSchema, getBrowserPid, gotoInputSchema, hoverInputSchema, pressInputSchema, scrollInputSchema, selectInputSchema, snapshotInputSchema, tabsInputSchema, typeInputSchema, waitInputSchema };