@mastra/stagehand 0.0.0

package/dist/index.d.cts

@@ -0,0 +1,590 @@
+import { Stagehand } from '@browserbasehq/stagehand';
+import { ThreadManager, ThreadSession, ThreadManagerConfig, BrowserConfig, MastraBrowser, BrowserToolError, BrowserState, BrowserTabState, ScreencastOptions, ScreencastStream, MouseEventParams, KeyboardEventParams } from '@mastra/core/browser';
+import { Tool } from '@mastra/core/tools';
+import { z } from 'zod';
+
+/**
+ * Stagehand Tool Schemas
+ *
+ * AI-powered browser tools using natural language instructions.
+ * These are fundamentally different from the deterministic AgentBrowser tools.
+ */
+
+/**
+ * stagehand_act - Perform an action using natural language
+ */
+declare const actInputSchema: z.ZodObject<{
+    instruction: z.ZodString;
+    variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    useVision: z.ZodOptional<z.ZodBoolean>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type ActInput = z.output<typeof actInputSchema>;
+/**
+ * stagehand_extract - Extract structured data from a page
+ */
+declare const extractInputSchema: z.ZodObject<{
+    instruction: z.ZodString;
+    schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type ExtractInput = z.output<typeof extractInputSchema>;
+/**
+ * stagehand_observe - Discover actionable elements on a page
+ */
+declare const observeInputSchema: z.ZodObject<{
+    instruction: z.ZodOptional<z.ZodString>;
+    onlyVisible: z.ZodOptional<z.ZodBoolean>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type ObserveInput = z.output<typeof observeInputSchema>;
+/**
+ * stagehand_navigate - Navigate to a URL
+ */
+declare const navigateInputSchema: z.ZodObject<{
+    url: z.ZodString;
+    waitUntil: z.ZodOptional<z.ZodEnum<{
+        load: "load";
+        domcontentloaded: "domcontentloaded";
+        networkidle: "networkidle";
+    }>>;
+}, z.core.$strip>;
+type NavigateInput = z.output<typeof navigateInputSchema>;
+/**
+ * stagehand_close - Close the browser
+ */
+declare const closeInputSchema: z.ZodObject<{}, z.core.$strip>;
+type CloseInput = z.output<typeof closeInputSchema>;
+/**
+ * stagehand_tabs - Manage browser tabs
+ */
+declare const tabsInputSchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        list: "list";
+        new: "new";
+        switch: "switch";
+        close: "close";
+    }>;
+    index: z.ZodOptional<z.ZodNumber>;
+    url: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type TabsInput = z.output<typeof tabsInputSchema>;
+declare const stagehandSchemas: {
+    readonly act: z.ZodObject<{
+        instruction: z.ZodString;
+        variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        useVision: z.ZodOptional<z.ZodBoolean>;
+        timeout: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    readonly extract: z.ZodObject<{
+        instruction: z.ZodString;
+        schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        timeout: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    readonly observe: z.ZodObject<{
+        instruction: z.ZodOptional<z.ZodString>;
+        onlyVisible: z.ZodOptional<z.ZodBoolean>;
+        timeout: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    readonly navigate: z.ZodObject<{
+        url: z.ZodString;
+        waitUntil: z.ZodOptional<z.ZodEnum<{
+            load: "load";
+            domcontentloaded: "domcontentloaded";
+            networkidle: "networkidle";
+        }>>;
+    }, z.core.$strip>;
+    readonly tabs: z.ZodObject<{
+        action: z.ZodEnum<{
+            list: "list";
+            new: "new";
+            switch: "switch";
+            close: "close";
+        }>;
+        index: z.ZodOptional<z.ZodNumber>;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly close: z.ZodObject<{}, z.core.$strip>;
+};
+
+/**
+ * StagehandThreadManager - Thread isolation 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)
+ *
+ * @see AgentBrowserThreadManager for the equivalent implementation.
+ */
+
+type V3 = Stagehand;
+type V3Page$1 = NonNullable<ReturnType<NonNullable<Stagehand['context']>['activePage']>>;
+/**
+ * Extended session info for Stagehand threads.
+ */
+interface StagehandThreadSession extends ThreadSession {
+    /** For 'thread' mode: dedicated Stagehand instance */
+    stagehand?: V3;
+}
+/**
+ * Configuration for StagehandThreadManager.
+ */
+interface StagehandThreadManagerConfig extends ThreadManagerConfig {
+    /** Function to create a new Stagehand instance (for 'thread' mode) */
+    createStagehand?: () => Promise<V3>;
+    /** Callback when a new browser/Stagehand instance is created for a thread */
+    onBrowserCreated?: (stagehand: V3, threadId: string) => void;
+}
+/**
+ * Thread manager for StagehandBrowser.
+ *
+ * Supports two scope modes:
+ * - 'none': All threads share the shared Stagehand instance
+ * - 'browser': Each thread gets a dedicated Stagehand instance
+ */
+declare class StagehandThreadManager extends ThreadManager<V3Page$1 | V3> {
+    private sharedStagehand;
+    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.
+     */
+    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.
+     */
+    protected getSharedManager(): V3Page$1 | V3;
+    /**
+     * Create a new session for a thread.
+     */
+    protected createSession(threadId: string): Promise<StagehandThreadSession>;
+    /**
+     * Restore browser state (multiple tabs) to a Stagehand instance.
+     */
+    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.
+     */
+    protected getManagerForSession(session: StagehandThreadSession): V3Page$1 | V3;
+    /**
+     * Destroy a session and clean up resources.
+     */
+    protected doDestroySession(session: StagehandThreadSession): Promise<void>;
+    /**
+     * Clean up all thread sessions.
+     */
+    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;
+}
+
+/**
+ * Stagehand Browser Types
+ */
+
+/**
+ * Model configuration for Stagehand AI operations
+ */
+type ModelConfiguration = string | {
+    modelName: string;
+    apiKey?: string;
+    baseURL?: string;
+};
+/**
+ * Configuration for StagehandBrowser
+ */
+interface StagehandBrowserConfig extends BrowserConfig {
+    /**
+     * Environment to run the browser in
+     * - 'LOCAL': Run browser locally
+     * - 'BROWSERBASE': Use Browserbase cloud
+     * @default 'LOCAL'
+     */
+    env?: 'LOCAL' | 'BROWSERBASE';
+    /**
+     * Browserbase API key (required when env = 'BROWSERBASE')
+     */
+    apiKey?: string;
+    /**
+     * Browserbase project ID (required when env = 'BROWSERBASE')
+     */
+    projectId?: string;
+    /**
+     * Model configuration for AI operations
+     * @default 'openai/gpt-4o'
+     */
+    model?: ModelConfiguration;
+    /**
+     * Enable self-healing selectors.
+     * When enabled, Stagehand uses AI to find elements even when selectors fail.
+     * @default true
+     */
+    selfHeal?: boolean;
+    /**
+     * Timeout for DOM to settle after actions (ms)
+     * @default 5000
+     */
+    domSettleTimeout?: number;
+    /**
+     * Logging verbosity level
+     * - 0: Silent
+     * - 1: Errors only
+     * - 2: Verbose
+     * @default 1
+     */
+    verbose?: 0 | 1 | 2;
+    /**
+     * Custom system prompt for AI operations (act, extract, observe)
+     */
+    systemPrompt?: string;
+}
+/**
+ * Action returned from observe()
+ */
+interface StagehandAction {
+    /** XPath selector to locate element */
+    selector: string;
+    /** Human-readable description */
+    description: string;
+    /** Suggested action method */
+    method?: string;
+    /** Additional action parameters */
+    arguments?: string[];
+}
+/**
+ * Result from act()
+ */
+interface ActResult {
+    success: boolean;
+    message?: string;
+    action?: string;
+    url?: string;
+    hint?: string;
+}
+/**
+ * Result from extract()
+ */
+interface ExtractResult<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    url?: string;
+    hint?: string;
+}
+/**
+ * Result from observe()
+ */
+interface ObserveResult {
+    success: boolean;
+    actions: StagehandAction[];
+    url?: string;
+    hint?: string;
+}
+
+/**
+ * StagehandBrowser - AI-powered browser automation using Stagehand v3
+ *
+ * Uses natural language instructions for browser interactions.
+ * Fundamentally different from AgentBrowser's deterministic refs approach.
+ *
+ * Stagehand v3 is CDP-native and provides direct CDP access for screencast/input injection.
+ */
+
+type V3Page = NonNullable<ReturnType<NonNullable<Stagehand['context']>['activePage']>>;
+/**
+ * StagehandBrowser - AI-powered browser using Stagehand v3
+ *
+ * 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)
+ */
+declare class StagehandBrowser extends MastraBrowser {
+    readonly id: string;
+    readonly name = "StagehandBrowser";
+    readonly provider = "browserbase/stagehand";
+    private stagehand;
+    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.
+     */
+    ensureReady(): Promise<void>;
+    /**
+     * Build Stagehand options from config.
+     * Returns the configuration object expected by Stagehand constructor.
+     */
+    private buildStagehandOptions;
+    /**
+     * Create a new Stagehand instance with the current config.
+     * Used by thread manager for 'browser' isolation mode.
+     */
+    private createStagehandInstance;
+    protected doLaunch(): Promise<void>;
+    /**
+     * Set up close event listener for a 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.
+     */
+    private handleThreadBrowserDisconnected;
+    protected doClose(): Promise<void>;
+    /**
+     * 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.
+     */
+    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.
+     */
+    private getStagehandForThread;
+    /**
+     * Require a Stagehand instance for the given or current thread.
+     * Throws if no instance is available.
+     * @param explicitThreadId - Optional thread ID to use instead of getCurrentThread()
+     *                           Use this to avoid race conditions in concurrent tool calls.
+     */
+    private requireStagehand;
+    /**
+     * Get the current page from Stagehand v3, respecting thread isolation.
+     * @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.
+     */
+    getPageForThread(threadId: string): Promise<V3Page | null>;
+    /**
+     * Get a CDP session for a specific page.
+     */
+    private getCdpSessionForPage;
+    getTools(): Record<string, Tool<any, any>>;
+    /**
+     * Perform an action using natural language instruction
+     * @param input - Action input
+     * @param threadId - Optional thread ID for thread-safe operation
+     */
+    act(input: ActInput, threadId?: string): Promise<{
+        success: true;
+        message?: string;
+        action?: string;
+        url: string;
+        hint: string;
+    } | BrowserToolError>;
+    /**
+     * Extract structured data from a page using natural language
+     * @param input - Extract input
+     * @param threadId - Optional thread ID for thread-safe operation
+     */
+    extract(input: ExtractInput, threadId?: string): Promise<{
+        success: true;
+        data: unknown;
+        url: string;
+        hint: string;
+    } | BrowserToolError>;
+    /**
+     * Discover actionable elements on a page
+     * @param input - Observe input
+     * @param threadId - Optional thread ID for thread-safe operation
+     */
+    observe(input: ObserveInput, threadId?: string): Promise<{
+        success: true;
+        actions: StagehandAction[];
+        url: string;
+        hint: string;
+    } | BrowserToolError>;
+    /**
+     * Navigate to a URL
+     * @param input - Navigate input
+     * @param threadId - Optional thread ID for thread-safe operation
+     */
+    navigate(input: NavigateInput, threadId?: string): Promise<{
+        success: true;
+        url: string;
+        title: string;
+        hint: string;
+    } | BrowserToolError>;
+    /**
+     * Manage browser tabs - list, create, switch, close
+     * @param input - Tabs input
+     * @param threadId - Optional thread ID for thread-safe operation
+     */
+    tabs(input: TabsInput, threadId?: string): Promise<{
+        success: true;
+        tabs?: Array<{
+            index: number;
+            url: string;
+            title: string;
+            active: boolean;
+        }>;
+        hint: string;
+    } | {
+        success: true;
+        index?: number;
+        url?: string;
+        title?: string;
+        remaining?: number;
+        hint: string;
+    } | BrowserToolError>;
+    getCurrentUrl(threadId?: string): Promise<string | null>;
+    /**
+     * Navigate to a URL (simple version). Used internally for restoring state on relaunch.
+     */
+    navigateTo(url: string): Promise<void>;
+    /**
+     * Get the current browser state (all tabs and active tab index).
+     */
+    getBrowserState(threadId?: string): Promise<BrowserState | null>;
+    /**
+     * Get browser state from a specific Stagehand instance.
+     */
+    private getBrowserStateFromStagehand;
+    /**
+     * Get all open tabs with their URLs and titles.
+     */
+    getTabState(threadId?: string): Promise<BrowserTabState[]>;
+    /**
+     * 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>;
+}
+
+/**
+ * Stagehand Tool Constants
+ */
+declare const STAGEHAND_TOOLS: {
+    readonly ACT: "stagehand_act";
+    readonly EXTRACT: "stagehand_extract";
+    readonly OBSERVE: "stagehand_observe";
+    readonly NAVIGATE: "stagehand_navigate";
+    readonly TABS: "stagehand_tabs";
+    readonly CLOSE: "stagehand_close";
+};
+type StagehandToolName = (typeof STAGEHAND_TOOLS)[keyof typeof STAGEHAND_TOOLS];
+
+/**
+ * Stagehand Tools
+ *
+ * Creates AI-powered browser tools bound to a StagehandBrowser instance.
+ */
+
+/**
+ * Creates all Stagehand tools bound to a StagehandBrowser instance.
+ * The browser is lazily initialized on first tool use.
+ */
+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 };