@mastra/stagehand 0.1.0-alpha.0 → 0.2.0-alpha.0

package/dist/index.d.cts

@@ -108,11 +108,11 @@ declare const stagehandSchemas: {
 };
 
 /**
- * StagehandThreadManager - Thread isolation for StagehandBrowser
+ * StagehandThreadManager - Thread scope management for StagehandBrowser
  *
  * Supports two scope modes:
- * - 'none': All threads share the same Stagehand instance and page
- * - 'browser': Each thread gets its own Stagehand instance (separate browser)
+ * - 'shared': All threads share the same Stagehand instance and page
+ * - 'thread': Each thread gets its own Stagehand instance (separate browser)
  *
  * @see AgentBrowserThreadManager for the equivalent implementation.
  */
@@ -139,49 +139,23 @@ interface StagehandThreadManagerConfig extends ThreadManagerConfig {
  * Thread manager for StagehandBrowser.
  *
  * Supports two scope modes:
- * - 'none': All threads share the shared Stagehand instance
- * - 'browser': Each thread gets a dedicated Stagehand instance
+ * - 'shared': All threads share the shared Stagehand instance
+ * - 'thread': Each thread gets a dedicated Stagehand instance
  */
-declare class StagehandThreadManager extends ThreadManager<V3Page$1 | V3> {
-    private sharedStagehand;
+declare class StagehandThreadManager extends ThreadManager<V3> {
     protected sessions: Map<string, StagehandThreadSession>;
     private createStagehand?;
     private onBrowserCreated?;
-    /** Map of thread ID to dedicated Stagehand instance (for 'thread' mode) */
-    private readonly threadStagehands;
     constructor(config: StagehandThreadManagerConfig);
-    /**
-     * Set the shared Stagehand instance (called after browser launch).
-     */
-    setStagehand(instance: V3): void;
-    /**
-     * Clear the shared Stagehand instance (called when browser disconnects).
-     */
-    clearStagehand(): void;
     /**
      * Set the factory function for creating new Stagehand instances.
-     * Required for 'browser' scope mode.
+     * Required for 'thread' scope mode.
      */
     setCreateStagehand(factory: () => Promise<V3>): void;
     /**
-     * Get the shared Stagehand instance.
-     */
-    getSharedStagehand(): V3;
-    /**
-     * Get the Stagehand instance for a specific thread.
-     * In 'shared' mode, returns the shared instance.
-     * In 'thread' mode, returns the thread's dedicated instance.
-     */
-    getStagehandForThread(threadId: string): V3 | undefined;
-    /**
-     * Get the Stagehand page for a thread.
-     * Returns the active page from the thread's Stagehand instance.
-     */
-    getPageForThread(threadId: string): V3Page$1 | undefined;
-    /**
-     * Get the shared manager - returns the active page or the Stagehand instance.
+     * Get the page for a specific thread, creating session if needed.
      */
-    protected getSharedManager(): V3Page$1 | V3;
+    getPageForThread(threadId?: string): Promise<V3Page$1 | null>;
     /**
      * Create a new session for a thread.
      */
@@ -191,39 +165,18 @@ declare class StagehandThreadManager extends ThreadManager<V3Page$1 | V3> {
      */
     private restoreBrowserState;
     /**
-     * Switch to an existing session.
-     * For 'thread' mode, no switching needed - each thread has its own instance.
-     * For 'shared' mode, nothing to switch.
-     */
-    protected switchToSession(_session: StagehandThreadSession): Promise<void>;
-    /**
-     * Get the manager for a specific session.
+     * Get the manager (Stagehand instance) for a specific session.
      */
-    protected getManagerForSession(session: StagehandThreadSession): V3Page$1 | V3;
+    protected getManagerForSession(session: StagehandThreadSession): V3;
     /**
      * Destroy a session and clean up resources.
      */
     protected doDestroySession(session: StagehandThreadSession): Promise<void>;
     /**
-     * Clean up all thread sessions.
+     * Destroy all sessions (called during browser close).
+     * doDestroySession handles closing individual Stagehand instances.
      */
-    destroyAll(): Promise<void>;
-    /**
-     * Check if any thread Stagehands are still running.
-     */
-    hasActiveThreadStagehands(): boolean;
-    /**
-     * 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;
+    destroyAllSessions(): Promise<void>;
 }
 
 /**
@@ -239,9 +192,9 @@ type ModelConfiguration = string | {
     baseURL?: string;
 };
 /**
- * Configuration for StagehandBrowser
+ * Stagehand-specific configuration fields.
  */
-interface StagehandBrowserConfig extends BrowserConfig {
+interface StagehandConfigExtensions {
     /**
      * Environment to run the browser in
      * - 'LOCAL': Run browser locally
@@ -285,7 +238,22 @@ interface StagehandBrowserConfig extends BrowserConfig {
      * Custom system prompt for AI operations (act, extract, observe)
      */
     systemPrompt?: string;
+    /**
+     * Whether to preserve the user data directory after the browser closes.
+     * By default, Stagehand may clean up temporary user data directories.
+     * Set to `true` to keep the profile data for future sessions.
+     *
+     * Only applicable when `profile` is provided.
+     *
+     * @default false
+     */
+    preserveUserDataDir?: boolean;
 }
+/**
+ * Configuration for StagehandBrowser.
+ * Extends the base BrowserConfig with Stagehand-specific options.
+ */
+type StagehandBrowserConfig = BrowserConfig & StagehandConfigExtensions;
 /**
  * Action returned from observe()
  */
@@ -345,31 +313,22 @@ type V3Page = NonNullable<ReturnType<NonNullable<Stagehand['context']>['activePa
  * Unlike AgentBrowser which uses refs ([ref=e1]), StagehandBrowser uses
  * natural language instructions for all interactions.
  *
- * Supports thread isolation via the scope config:
- * - 'none': All threads share the same Stagehand instance
- * - 'browser': Each thread gets its own Stagehand instance (separate browser)
+ * Supports thread scope via the scope config:
+ * - 'shared': All threads share the same Stagehand instance
+ * - 'thread': Each thread gets its own Stagehand instance (separate browser)
  */
 declare class StagehandBrowser extends MastraBrowser {
     readonly id: string;
     readonly name = "StagehandBrowser";
     readonly provider = "browserbase/stagehand";
-    private stagehand;
+    /** Shared Stagehand instance (for 'shared' scope) - narrowed type from base class */
+    protected sharedManager: Stagehand | null;
     private stagehandConfig;
     /** Thread manager - narrowed type from base class */
     protected threadManager: StagehandThreadManager;
-    /** Active screencast streams per thread (for reconnection on tab changes) */
-    private activeScreencastStreams;
     /** Debounce timers per thread for tab change reconnection */
     private tabChangeDebounceTimers;
-    /** Default key for shared scope */
-    private static readonly SHARED_STREAM_KEY;
     constructor(config?: StagehandBrowserConfig);
-    /**
-     * Close a specific thread's browser session.
-     * For 'thread' scope, this closes only that thread's Stagehand instance.
-     * For 'shared' scope, this is a no-op (use close() to close the shared browser).
-     */
-    closeThreadSession(threadId: string): Promise<void>;
     /**
      * Ensure browser is ready and thread session exists.
      * For 'thread' scope, this creates a dedicated Stagehand instance for the thread.
@@ -382,37 +341,33 @@ declare class StagehandBrowser extends MastraBrowser {
     private buildStagehandOptions;
     /**
      * Create a new Stagehand instance with the current config.
-     * Used by thread manager for 'browser' isolation mode.
+     * Used by thread manager for 'thread' scope.
      */
     private createStagehandInstance;
     protected doLaunch(): Promise<void>;
     /**
-     * Set up close event listener for a Stagehand instance.
+     * Set up close event listener for a shared Stagehand instance.
      * Listens to both context and page close events for robust detection.
      */
-    private setupCloseListener;
-    /**
-     * Set up close event listener for a thread's Stagehand instance.
-     * Uses CDP Target.targetDestroyed events to detect when all pages are gone.
-     */
-    private setupCloseListenerForThread;
     /**
-     * Handle browser disconnection for a specific thread.
-     * Called when a thread's browser is closed externally.
+     * Set up a CDP-based close listener for a Stagehand instance.
+     *
+     * Tracks page targets via CDP `Target.targetCreated` / `Target.targetDestroyed`.
+     * When all page targets are gone the `onDisconnect` callback fires. This is more
+     * reliable than Playwright's `context.close` / `page.close` events which don't
+     * fire when Chrome is killed externally (SIGTERM/SIGKILL).
      */
-    private handleThreadBrowserDisconnected;
+    private setupCloseListener;
     protected doClose(): Promise<void>;
+    handleBrowserDisconnected(): void;
+    protected handleThreadBrowserDisconnected(threadId: string): void;
+    closeThreadSession(threadId: string): Promise<void>;
+    private patchExitType;
     /**
      * Check if the browser is still alive by verifying the context and pages exist.
      * Called by base class ensureReady() to detect externally closed browsers.
      */
     protected checkBrowserAlive(): Promise<boolean>;
-    /**
-     * Handle browser disconnection by clearing internal state.
-     * For 'thread' scope, only notifies the specific thread's callbacks.
-     * For 'shared' scope, notifies all callbacks.
-     */
-    handleBrowserDisconnected(): void;
     /**
      * Create an error response from an exception.
      * Extends base class to add Stagehand-specific error handling.
@@ -420,10 +375,10 @@ declare class StagehandBrowser extends MastraBrowser {
     protected createErrorFromException(error: unknown, context: string): BrowserToolError;
     /**
      * Get the Stagehand instance for a thread, creating it if needed.
-     * For 'browser' isolation, this creates a dedicated Stagehand instance.
-     * For 'none' isolation, returns the shared instance.
+     * For 'thread' scope, this creates a dedicated Stagehand instance.
+     * For 'shared' scope, returns the shared instance.
      */
-    private getStagehandForThread;
+    getManagerForThread(threadId?: string): Promise<Stagehand | null>;
     /**
      * Require a Stagehand instance for the given or current thread.
      * Throws if no instance is available.
@@ -432,15 +387,15 @@ declare class StagehandBrowser extends MastraBrowser {
      */
     private requireStagehand;
     /**
-     * Get the current page from Stagehand v3, respecting thread isolation.
+     * Get the current page from Stagehand v3, respecting thread scope.
      * @param explicitThreadId - Optional thread ID to use instead of getCurrentThread()
      *                           Use this to avoid race conditions in concurrent tool calls.
      */
     private getPage;
     /**
-     * Get the page for a specific thread, creating session if needed.
+     * Get the active page for a thread (implements abstract method from base class).
      */
-    getPageForThread(threadId: string): Promise<V3Page | null>;
+    protected getActivePage(threadId?: string): Promise<V3Page | null>;
     /**
      * Get a CDP session for a specific page.
      */
@@ -522,6 +477,11 @@ declare class StagehandBrowser 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 Stagehand instance.
      */
@@ -534,34 +494,27 @@ declare class StagehandBrowser extends MastraBrowser {
      * Get the active tab index.
      */
     getActiveTabIndex(threadId?: string): Promise<number>;
-    /**
-     * Update the browser state in the thread session.
-     * Called on navigation, tab open/close to keep state fresh.
-     */
-    private updateSessionBrowserState;
-    /**
-     * Get the stream key for a thread (or shared key for shared scope).
-     */
-    private getStreamKey;
     startScreencast(options?: ScreencastOptions): Promise<ScreencastStream>;
     /**
      * Set up listeners to detect tab changes and reconnect the screencast.
      * Uses CDP Target events since Stagehand doesn't expose page lifecycle events.
      */
     private setupTabChangeDetection;
-    /**
-     * Reconnect the active screencast for a specific thread.
-     */
-    private reconnectScreencastForThread;
-    /**
-     * Reconnect the active screencast for the current thread.
-     * Wrapper for reconnectScreencastForThread using getCurrentThread().
-     */
-    private reconnectScreencast;
     injectMouseEvent(event: MouseEventParams, threadId?: string): Promise<void>;
     injectKeyboardEvent(event: KeyboardEventParams, threadId?: string): Promise<void>;
 }
 
+/**
+ * Extract the Chrome process PID from a Stagehand instance.
+ *
+ * Stagehand stores the chrome-launcher result in `state.chrome` after init.
+ * The PID is at `chrome.process?.pid ?? chrome.pid`. This isn't part of
+ * Stagehand's public API, so we access it via `as any`.
+ *
+ * Returns undefined if the PID can't be found (e.g. BROWSERBASE env, not yet init'd).
+ */
+declare function getStagehandChromePid(stagehand: Stagehand): number | undefined;
+
 /**
  * Stagehand Tool Constants
  */
@@ -587,4 +540,4 @@ type StagehandToolName = (typeof STAGEHAND_TOOLS)[keyof typeof STAGEHAND_TOOLS];
  */
 declare function createStagehandTools(browser: StagehandBrowser): Record<string, Tool<any, any>>;
 
-export { type ActInput, type ActResult, type CloseInput, type ExtractInput, type ExtractResult, type ModelConfiguration, type NavigateInput, type ObserveInput, type ObserveResult, STAGEHAND_TOOLS, type StagehandAction, StagehandBrowser, type StagehandBrowserConfig, type StagehandToolName, type TabsInput, actInputSchema, closeInputSchema, createStagehandTools, extractInputSchema, navigateInputSchema, observeInputSchema, stagehandSchemas, tabsInputSchema };
+export { type ActInput, type ActResult, type CloseInput, type ExtractInput, type ExtractResult, type ModelConfiguration, type NavigateInput, type ObserveInput, type ObserveResult, STAGEHAND_TOOLS, type StagehandAction, StagehandBrowser, type StagehandBrowserConfig, type StagehandToolName, type TabsInput, actInputSchema, closeInputSchema, createStagehandTools, extractInputSchema, getStagehandChromePid, navigateInputSchema, observeInputSchema, stagehandSchemas, tabsInputSchema };

package/dist/index.d.ts

@@ -108,11 +108,11 @@ declare const stagehandSchemas: {
 };
 
 /**
- * StagehandThreadManager - Thread isolation for StagehandBrowser
+ * StagehandThreadManager - Thread scope management for StagehandBrowser
  *
  * Supports two scope modes:
- * - 'none': All threads share the same Stagehand instance and page
- * - 'browser': Each thread gets its own Stagehand instance (separate browser)
+ * - 'shared': All threads share the same Stagehand instance and page
+ * - 'thread': Each thread gets its own Stagehand instance (separate browser)
  *
  * @see AgentBrowserThreadManager for the equivalent implementation.
  */
@@ -139,49 +139,23 @@ interface StagehandThreadManagerConfig extends ThreadManagerConfig {
  * Thread manager for StagehandBrowser.
  *
  * Supports two scope modes:
- * - 'none': All threads share the shared Stagehand instance
- * - 'browser': Each thread gets a dedicated Stagehand instance
+ * - 'shared': All threads share the shared Stagehand instance
+ * - 'thread': Each thread gets a dedicated Stagehand instance
  */
-declare class StagehandThreadManager extends ThreadManager<V3Page$1 | V3> {
-    private sharedStagehand;
+declare class StagehandThreadManager extends ThreadManager<V3> {
     protected sessions: Map<string, StagehandThreadSession>;
     private createStagehand?;
     private onBrowserCreated?;
-    /** Map of thread ID to dedicated Stagehand instance (for 'thread' mode) */
-    private readonly threadStagehands;
     constructor(config: StagehandThreadManagerConfig);
-    /**
-     * Set the shared Stagehand instance (called after browser launch).
-     */
-    setStagehand(instance: V3): void;
-    /**
-     * Clear the shared Stagehand instance (called when browser disconnects).
-     */
-    clearStagehand(): void;
     /**
      * Set the factory function for creating new Stagehand instances.
-     * Required for 'browser' scope mode.
+     * Required for 'thread' scope mode.
      */
     setCreateStagehand(factory: () => Promise<V3>): void;
     /**
-     * Get the shared Stagehand instance.
-     */
-    getSharedStagehand(): V3;
-    /**
-     * Get the Stagehand instance for a specific thread.
-     * In 'shared' mode, returns the shared instance.
-     * In 'thread' mode, returns the thread's dedicated instance.
-     */
-    getStagehandForThread(threadId: string): V3 | undefined;
-    /**
-     * Get the Stagehand page for a thread.
-     * Returns the active page from the thread's Stagehand instance.
-     */
-    getPageForThread(threadId: string): V3Page$1 | undefined;
-    /**
-     * Get the shared manager - returns the active page or the Stagehand instance.
+     * Get the page for a specific thread, creating session if needed.
      */
-    protected getSharedManager(): V3Page$1 | V3;
+    getPageForThread(threadId?: string): Promise<V3Page$1 | null>;
     /**
      * Create a new session for a thread.
      */
@@ -191,39 +165,18 @@ declare class StagehandThreadManager extends ThreadManager<V3Page$1 | V3> {
      */
     private restoreBrowserState;
     /**
-     * Switch to an existing session.
-     * For 'thread' mode, no switching needed - each thread has its own instance.
-     * For 'shared' mode, nothing to switch.
-     */
-    protected switchToSession(_session: StagehandThreadSession): Promise<void>;
-    /**
-     * Get the manager for a specific session.
+     * Get the manager (Stagehand instance) for a specific session.
      */
-    protected getManagerForSession(session: StagehandThreadSession): V3Page$1 | V3;
+    protected getManagerForSession(session: StagehandThreadSession): V3;
     /**
      * Destroy a session and clean up resources.
      */
     protected doDestroySession(session: StagehandThreadSession): Promise<void>;
     /**
-     * Clean up all thread sessions.
+     * Destroy all sessions (called during browser close).
+     * doDestroySession handles closing individual Stagehand instances.
      */
-    destroyAll(): Promise<void>;
-    /**
-     * Check if any thread Stagehands are still running.
-     */
-    hasActiveThreadStagehands(): boolean;
-    /**
-     * 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;
+    destroyAllSessions(): Promise<void>;
 }
 
 /**
@@ -239,9 +192,9 @@ type ModelConfiguration = string | {
     baseURL?: string;
 };
 /**
- * Configuration for StagehandBrowser
+ * Stagehand-specific configuration fields.
  */
-interface StagehandBrowserConfig extends BrowserConfig {
+interface StagehandConfigExtensions {
     /**
      * Environment to run the browser in
      * - 'LOCAL': Run browser locally
@@ -285,7 +238,22 @@ interface StagehandBrowserConfig extends BrowserConfig {
      * Custom system prompt for AI operations (act, extract, observe)
      */
     systemPrompt?: string;
+    /**
+     * Whether to preserve the user data directory after the browser closes.
+     * By default, Stagehand may clean up temporary user data directories.
+     * Set to `true` to keep the profile data for future sessions.
+     *
+     * Only applicable when `profile` is provided.
+     *
+     * @default false
+     */
+    preserveUserDataDir?: boolean;
 }
+/**
+ * Configuration for StagehandBrowser.
+ * Extends the base BrowserConfig with Stagehand-specific options.
+ */
+type StagehandBrowserConfig = BrowserConfig & StagehandConfigExtensions;
 /**
  * Action returned from observe()
  */
@@ -345,31 +313,22 @@ type V3Page = NonNullable<ReturnType<NonNullable<Stagehand['context']>['activePa
  * Unlike AgentBrowser which uses refs ([ref=e1]), StagehandBrowser uses
  * natural language instructions for all interactions.
  *
- * Supports thread isolation via the scope config:
- * - 'none': All threads share the same Stagehand instance
- * - 'browser': Each thread gets its own Stagehand instance (separate browser)
+ * Supports thread scope via the scope config:
+ * - 'shared': All threads share the same Stagehand instance
+ * - 'thread': Each thread gets its own Stagehand instance (separate browser)
  */
 declare class StagehandBrowser extends MastraBrowser {
     readonly id: string;
     readonly name = "StagehandBrowser";
     readonly provider = "browserbase/stagehand";
-    private stagehand;
+    /** Shared Stagehand instance (for 'shared' scope) - narrowed type from base class */
+    protected sharedManager: Stagehand | null;
     private stagehandConfig;
     /** Thread manager - narrowed type from base class */
     protected threadManager: StagehandThreadManager;
-    /** Active screencast streams per thread (for reconnection on tab changes) */
-    private activeScreencastStreams;
     /** Debounce timers per thread for tab change reconnection */
     private tabChangeDebounceTimers;
-    /** Default key for shared scope */
-    private static readonly SHARED_STREAM_KEY;
     constructor(config?: StagehandBrowserConfig);
-    /**
-     * Close a specific thread's browser session.
-     * For 'thread' scope, this closes only that thread's Stagehand instance.
-     * For 'shared' scope, this is a no-op (use close() to close the shared browser).
-     */
-    closeThreadSession(threadId: string): Promise<void>;
     /**
      * Ensure browser is ready and thread session exists.
      * For 'thread' scope, this creates a dedicated Stagehand instance for the thread.
@@ -382,37 +341,33 @@ declare class StagehandBrowser extends MastraBrowser {
     private buildStagehandOptions;
     /**
      * Create a new Stagehand instance with the current config.
-     * Used by thread manager for 'browser' isolation mode.
+     * Used by thread manager for 'thread' scope.
      */
     private createStagehandInstance;
     protected doLaunch(): Promise<void>;
     /**
-     * Set up close event listener for a Stagehand instance.
+     * Set up close event listener for a shared Stagehand instance.
      * Listens to both context and page close events for robust detection.
      */
-    private setupCloseListener;
-    /**
-     * Set up close event listener for a thread's Stagehand instance.
-     * Uses CDP Target.targetDestroyed events to detect when all pages are gone.
-     */
-    private setupCloseListenerForThread;
     /**
-     * Handle browser disconnection for a specific thread.
-     * Called when a thread's browser is closed externally.
+     * Set up a CDP-based close listener for a Stagehand instance.
+     *
+     * Tracks page targets via CDP `Target.targetCreated` / `Target.targetDestroyed`.
+     * When all page targets are gone the `onDisconnect` callback fires. This is more
+     * reliable than Playwright's `context.close` / `page.close` events which don't
+     * fire when Chrome is killed externally (SIGTERM/SIGKILL).
      */
-    private handleThreadBrowserDisconnected;
+    private setupCloseListener;
     protected doClose(): Promise<void>;
+    handleBrowserDisconnected(): void;
+    protected handleThreadBrowserDisconnected(threadId: string): void;
+    closeThreadSession(threadId: string): Promise<void>;
+    private patchExitType;
     /**
      * Check if the browser is still alive by verifying the context and pages exist.
      * Called by base class ensureReady() to detect externally closed browsers.
      */
     protected checkBrowserAlive(): Promise<boolean>;
-    /**
-     * Handle browser disconnection by clearing internal state.
-     * For 'thread' scope, only notifies the specific thread's callbacks.
-     * For 'shared' scope, notifies all callbacks.
-     */
-    handleBrowserDisconnected(): void;
     /**
      * Create an error response from an exception.
      * Extends base class to add Stagehand-specific error handling.
@@ -420,10 +375,10 @@ declare class StagehandBrowser extends MastraBrowser {
     protected createErrorFromException(error: unknown, context: string): BrowserToolError;
     /**
      * Get the Stagehand instance for a thread, creating it if needed.
-     * For 'browser' isolation, this creates a dedicated Stagehand instance.
-     * For 'none' isolation, returns the shared instance.
+     * For 'thread' scope, this creates a dedicated Stagehand instance.
+     * For 'shared' scope, returns the shared instance.
      */
-    private getStagehandForThread;
+    getManagerForThread(threadId?: string): Promise<Stagehand | null>;
     /**
      * Require a Stagehand instance for the given or current thread.
      * Throws if no instance is available.
@@ -432,15 +387,15 @@ declare class StagehandBrowser extends MastraBrowser {
      */
     private requireStagehand;
     /**
-     * Get the current page from Stagehand v3, respecting thread isolation.
+     * Get the current page from Stagehand v3, respecting thread scope.
      * @param explicitThreadId - Optional thread ID to use instead of getCurrentThread()
      *                           Use this to avoid race conditions in concurrent tool calls.
      */
     private getPage;
     /**
-     * Get the page for a specific thread, creating session if needed.
+     * Get the active page for a thread (implements abstract method from base class).
      */
-    getPageForThread(threadId: string): Promise<V3Page | null>;
+    protected getActivePage(threadId?: string): Promise<V3Page | null>;
     /**
      * Get a CDP session for a specific page.
      */
@@ -522,6 +477,11 @@ declare class StagehandBrowser 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 Stagehand instance.
      */
@@ -534,34 +494,27 @@ declare class StagehandBrowser extends MastraBrowser {
      * Get the active tab index.
      */
     getActiveTabIndex(threadId?: string): Promise<number>;
-    /**
-     * Update the browser state in the thread session.
-     * Called on navigation, tab open/close to keep state fresh.
-     */
-    private updateSessionBrowserState;
-    /**
-     * Get the stream key for a thread (or shared key for shared scope).
-     */
-    private getStreamKey;
     startScreencast(options?: ScreencastOptions): Promise<ScreencastStream>;
     /**
      * Set up listeners to detect tab changes and reconnect the screencast.
      * Uses CDP Target events since Stagehand doesn't expose page lifecycle events.
      */
     private setupTabChangeDetection;
-    /**
-     * Reconnect the active screencast for a specific thread.
-     */
-    private reconnectScreencastForThread;
-    /**
-     * Reconnect the active screencast for the current thread.
-     * Wrapper for reconnectScreencastForThread using getCurrentThread().
-     */
-    private reconnectScreencast;
     injectMouseEvent(event: MouseEventParams, threadId?: string): Promise<void>;
     injectKeyboardEvent(event: KeyboardEventParams, threadId?: string): Promise<void>;
 }
 
+/**
+ * Extract the Chrome process PID from a Stagehand instance.
+ *
+ * Stagehand stores the chrome-launcher result in `state.chrome` after init.
+ * The PID is at `chrome.process?.pid ?? chrome.pid`. This isn't part of
+ * Stagehand's public API, so we access it via `as any`.
+ *
+ * Returns undefined if the PID can't be found (e.g. BROWSERBASE env, not yet init'd).
+ */
+declare function getStagehandChromePid(stagehand: Stagehand): number | undefined;
+
 /**
  * Stagehand Tool Constants
  */
@@ -587,4 +540,4 @@ type StagehandToolName = (typeof STAGEHAND_TOOLS)[keyof typeof STAGEHAND_TOOLS];
  */
 declare function createStagehandTools(browser: StagehandBrowser): Record<string, Tool<any, any>>;
 
-export { type ActInput, type ActResult, type CloseInput, type ExtractInput, type ExtractResult, type ModelConfiguration, type NavigateInput, type ObserveInput, type ObserveResult, STAGEHAND_TOOLS, type StagehandAction, StagehandBrowser, type StagehandBrowserConfig, type StagehandToolName, type TabsInput, actInputSchema, closeInputSchema, createStagehandTools, extractInputSchema, navigateInputSchema, observeInputSchema, stagehandSchemas, tabsInputSchema };
+export { type ActInput, type ActResult, type CloseInput, type ExtractInput, type ExtractResult, type ModelConfiguration, type NavigateInput, type ObserveInput, type ObserveResult, STAGEHAND_TOOLS, type StagehandAction, StagehandBrowser, type StagehandBrowserConfig, type StagehandToolName, type TabsInput, actInputSchema, closeInputSchema, createStagehandTools, extractInputSchema, getStagehandChromePid, navigateInputSchema, observeInputSchema, stagehandSchemas, tabsInputSchema };