@mastra/browser-viewer 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,335 @@
+import { BrowserConfigBase, ThreadManager, ThreadManagerConfig, ThreadSession, MastraBrowser, BrowserState, ScreencastOptions, ScreencastStream, MouseEventParams, KeyboardEventParams } from '@mastra/core/browser';
+import { Tool } from '@mastra/core/tools';
+import { Browser, Page, CDPSession, BrowserContext, BrowserServer } from 'playwright-core';
+
+/**
+ * Types for @mastra/browser-viewer
+ */
+
+/**
+ * Supported CLI providers that can be used with BrowserViewer.
+ */
+type CLIProvider = 'agent-browser' | 'browser-use' | 'browse-cli';
+/**
+ * Configuration for BrowserViewer.
+ */
+interface BrowserViewerConfig extends BrowserConfigBase {
+    /**
+     * Which CLI the agent will use for browser automation.
+     * The CLI connects to Mastra's Chrome via the CDP URL.
+     */
+    cli: CLIProvider;
+    /**
+     * Port for Chrome's remote debugging protocol.
+     * Only used when launching Chrome (not when connecting via cdpUrl).
+     *
+     * @default 0 (auto-assign available port)
+     */
+    cdpPort?: number;
+    /**
+     * Path to Chrome user data directory (profile).
+     * Persists cookies, localStorage, extensions, etc.
+     */
+    userDataDir?: string;
+}
+
+/**
+ * BrowserViewerThreadManager - Thread scope management for BrowserViewer
+ *
+ * Manages thread-scoped browser sessions using Playwright to launch
+ * separate Chrome instances per thread.
+ */
+
+/**
+ * Extended session info for BrowserViewer.
+ */
+interface BrowserViewerSession extends ThreadSession {
+    /**
+     * Playwright browser server (owns the Chrome process).
+     * Null for external CDP connections where we don't own the browser process.
+     */
+    browserServer: BrowserServer | null;
+    /** Playwright browser instance (connected to server) */
+    browser: Browser;
+    /** Browser context */
+    context: BrowserContext;
+    /** CDP session for the active page */
+    cdpSession: CDPSession | null;
+    /** CDP WebSocket URL (null if discovery failed) */
+    cdpUrl: string | null;
+}
+/**
+ * Configuration for BrowserViewerThreadManager.
+ */
+interface BrowserViewerThreadManagerConfig extends ThreadManagerConfig {
+    /** Browser configuration */
+    browserConfig: BrowserViewerConfig;
+    /** Callback when a browser is created for a thread */
+    onBrowserCreated?: (browser: Browser, threadId: string, cdpUrl: string | null) => void;
+    /** Callback when a browser is closed for a thread */
+    onBrowserClosed?: (threadId: string) => void;
+}
+/**
+ * Thread manager implementation for BrowserViewer.
+ *
+ * Supports two scope modes:
+ * - 'shared': All threads share one Chrome instance
+ * - 'thread': Each thread gets a dedicated Chrome instance
+ */
+declare class BrowserViewerThreadManager extends ThreadManager<Browser> {
+    private readonly browserConfig;
+    private readonly onBrowserCreated?;
+    private readonly onBrowserClosed?;
+    /** Map of thread ID to session info (for 'thread' scope) */
+    private readonly threadSessions;
+    /** Shared session info (for 'shared' scope) */
+    private sharedSession;
+    /** Cached CDP sessions for input injection, keyed by threadId */
+    private inputCdpSessions;
+    constructor(config: BrowserViewerThreadManagerConfig);
+    /**
+     * Check if a thread should use the shared session slot.
+     * In shared scope, all threads use the shared session.
+     * In thread scope, DEFAULT_THREAD_ID also uses the shared session.
+     */
+    private usesSharedSlot;
+    /**
+     * Get the viewer session for a thread, using consistent routing.
+     * Handles both shared and thread-scoped sessions.
+     */
+    private getViewerSession;
+    /**
+     * Store a session in the appropriate slot based on scope.
+     * Consolidates session storage logic used by createSession, createSharedSession,
+     * createSharedSessionFromCdp, and connectToExternalCdp.
+     */
+    private storeSession;
+    /**
+     * Clear a session from the appropriate slot based on scope.
+     * Must be called BEFORE async cleanup operations to prevent double callbacks
+     * from disconnect handlers.
+     */
+    private clearSessionState;
+    /**
+     * Clean up a session's resources (CDP session, browser, server).
+     * Consolidates cleanup logic used by closeThreadBrowser, closeSharedBrowser,
+     * and doDestroySession.
+     *
+     * @param session - The session to clean up
+     * @param threadId - The thread ID (for onBrowserClosed callback)
+     */
+    private cleanupSession;
+    /**
+     * Launch a new browser instance and return the components.
+     * Consolidates the launch logic shared by createSession and createSharedSession.
+     *
+     * @param threadId - Thread ID for logging and disconnect handler
+     */
+    private launchBrowser;
+    /**
+     * Get CDP URL for a specific thread.
+     */
+    getCdpUrlForThread(threadId?: string): string | null;
+    /**
+     * Get the active page for a thread.
+     */
+    getActivePageForThread(threadId?: string): Promise<Page | null>;
+    /**
+     * Resolve the active page from a browser context.
+     * Uses last page (most recently opened) with fallback to first page.
+     */
+    private resolveActivePage;
+    /**
+     * Get or create a CDP session for the active page in a thread.
+     *
+     * CDP sessions are page-scoped, so we create a fresh one for the currently active page
+     * rather than caching one that may point to a closed or inactive page.
+     */
+    getCdpSessionForThread(threadId?: string): Promise<CDPSession | null>;
+    /**
+     * Get the browser context for a thread.
+     */
+    getContextForThread(threadId?: string): BrowserContext | null;
+    /**
+     * Create a fresh CDP session for the active page (not cached).
+     * Used by screencast which needs fresh sessions on tab switches.
+     */
+    createFreshCdpSession(threadId?: string): Promise<CDPSession | null>;
+    /**
+     * Create a new session for a thread.
+     */
+    protected createSession(threadId: string): Promise<BrowserViewerSession>;
+    /**
+     * Discover the actual CDP WebSocket URL from Chrome's DevToolsActivePort file.
+     *
+     * Playwright's BrowserServer exposes _userDataDirForTest which points to Chrome's
+     * user data directory. Chrome writes a DevToolsActivePort file there containing:
+     *   Line 1: The debugging port number
+     *   Line 2: The browser WebSocket path (e.g., /devtools/browser/<guid>)
+     *
+     * This gives us the real CDP URL that external tools like agent-browser can connect to.
+     * Returns null if discovery fails - callers should handle this case.
+     */
+    private discoverCdpUrl;
+    /**
+     * Create a shared session by connecting to an existing browser via CDP URL.
+     * Used when BrowserViewer is configured with a cdpUrl to connect to an external browser.
+     */
+    createSharedSessionFromCdp(cdpUrl: string): Promise<void>;
+    /**
+     * Create a shared session (for 'shared' scope).
+     */
+    createSharedSession(): Promise<void>;
+    /**
+     * Handle browser disconnection for a thread.
+     */
+    private handleBrowserDisconnected;
+    /**
+     * Connect to an external browser via CDP URL for screencast.
+     *
+     * This is used when an agent is using their own external CDP (e.g., browser-use cloud).
+     * We connect Playwright to the external browser to enable screencast without launching
+     * our own browser.
+     *
+     * @param cdpUrl - The external CDP WebSocket URL (wss://... or ws://...)
+     * @param threadId - Thread ID to associate the session with
+     */
+    connectToExternalCdp(cdpUrl: string, threadId: string): Promise<BrowserViewerSession>;
+    /**
+     * Connect to a browser via CDP URL and create a session.
+     * Shared implementation for createSharedSessionFromCdp and connectToExternalCdp.
+     */
+    private connectToCdp;
+    /**
+     * Close a specific thread's browser.
+     */
+    closeThreadBrowser(threadId: string): Promise<void>;
+    /**
+     * Close the shared browser.
+     */
+    closeSharedBrowser(): Promise<void>;
+    /**
+     * Close all browsers.
+     */
+    closeAll(): Promise<void>;
+    /**
+     * Get the manager for a session.
+     * Required by base class.
+     */
+    protected getManagerForSession(session: ThreadSession): Browser;
+    /**
+     * Get the shared manager.
+     * Required by base class.
+     */
+    protected getSharedManager(): Browser;
+    /**
+     * Destroy a session and clean up resources.
+     * Required by base class.
+     */
+    protected doDestroySession(session: ThreadSession): Promise<void>;
+    /**
+     * Check if browser is running for a thread.
+     */
+    isBrowserRunning(threadId?: string): boolean;
+}
+
+/**
+ * BrowserViewer - Playwright-managed Chrome for CLI providers
+ *
+ * Launches Chrome via Playwright and exposes the CDP URL for CLI tools
+ * (agent-browser, browser-use, browse-cli) to connect as secondary clients.
+ *
+ * This gives us:
+ * - Direct page-level CDP sessions (fixes screencast sessionId issues)
+ * - Full browser lifecycle control
+ * - Predictable CDP URL for CLI injection
+ * - Thread-scoped browser isolation
+ */
+
+/**
+ * BrowserViewer - CLI provider with Playwright-managed Chrome
+ *
+ * Use this with Workspace to enable browser automation via CLI tools.
+ * The agent uses skills + workspace_execute_command to drive the CLI,
+ * while Mastra handles screencast, input injection, and lifecycle.
+ *
+ * @example
+ * ```ts
+ * import { Workspace } from '@mastra/core';
+ * import { BrowserViewer } from '@mastra/browser-viewer';
+ *
+ * const workspace = new Workspace({
+ *   browser: new BrowserViewer({
+ *     cli: 'agent-browser',
+ *     headless: false,
+ *   }),
+ * });
+ * ```
+ */
+declare class BrowserViewer extends MastraBrowser {
+    readonly id: string;
+    readonly name = "BrowserViewer";
+    readonly provider = "browser-viewer";
+    readonly providerType: "cli";
+    /** Which CLI the agent uses */
+    readonly cli: CLIProvider;
+    /** Viewer-specific config (stored for reference) */
+    readonly viewerConfig: BrowserViewerConfig;
+    /** Thread manager for browser sessions */
+    protected threadManager: BrowserViewerThreadManager;
+    constructor(config: BrowserViewerConfig);
+    /**
+     * Get the CDP WebSocket URL for CLI tools to connect.
+     * For thread scope, returns the CDP URL for the specified thread.
+     * For shared scope, returns the single shared CDP URL.
+     *
+     * @param threadId - Thread identifier (optional, uses current thread if not specified)
+     * @returns CDP URL or null if browser not running for that thread
+     */
+    getCdpUrl(threadId?: string): string | null;
+    protected doLaunch(): Promise<void>;
+    protected doClose(): Promise<void>;
+    /**
+     * Connect to an existing browser via CDP URL.
+     */
+    private connectToExisting;
+    /**
+     * Ensure browser is ready for the current thread.
+     * For thread scope, creates a new browser if needed.
+     */
+    ensureReady(): Promise<void>;
+    /**
+     * Check if browser is running (for current thread in thread scope).
+     */
+    isBrowserRunning(threadId?: string): boolean;
+    /**
+     * Launch browser, optionally for a specific thread.
+     * For thread scope, creates a browser for that thread.
+     * For shared scope, launches the single shared browser.
+     */
+    launch(threadId?: string): Promise<void>;
+    /**
+     * Handle browser disconnection.
+     * Overrides base class method.
+     */
+    handleBrowserDisconnected(): void;
+    /**
+     * Connect to an external browser via CDP URL for screencast.
+     *
+     * Use this when an agent is using their own external CDP (e.g., browser-use cloud).
+     * Connects Playwright to the external browser to enable screencast without launching
+     * our own browser.
+     *
+     * @param cdpUrl - The external CDP WebSocket URL (wss://... or ws://...)
+     * @param threadId - Thread ID to associate the session with
+     */
+    connectToExternalCdp(cdpUrl: string, threadId?: string): Promise<void>;
+    protected getActivePage(threadId?: string): Promise<Page | null>;
+    protected getBrowserStateForThread(threadId?: string): BrowserState | null;
+    startScreencast(options?: ScreencastOptions): Promise<ScreencastStream>;
+    injectMouseEvent(params: MouseEventParams, threadId?: string): Promise<void>;
+    injectKeyboardEvent(params: KeyboardEventParams, threadId?: string): Promise<void>;
+    getTools(): Record<string, Tool>;
+}
+
+export { BrowserViewer, type BrowserViewerConfig, BrowserViewerThreadManager, type BrowserViewerThreadManagerConfig, type CLIProvider };