@mastra/stagehand 0.0.0-async-hooks-fix-20260405144639

package/dist/index.d.cts

@@ -0,0 +1,524 @@
+import { Stagehand } from '@browserbasehq/stagehand';
+import { ThreadManager, ThreadSession, ThreadManagerConfig, BrowserConfigBase, BrowserScope, CdpUrlProvider, 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 scope management for StagehandBrowser
+ *
+ * Supports two scope modes:
+ * - '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.
+ */
+
+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:
+ * - 'shared': All threads share the shared Stagehand instance
+ * - 'thread': Each thread gets a dedicated Stagehand instance
+ */
+declare class StagehandThreadManager extends ThreadManager<V3> {
+    protected sessions: Map<string, StagehandThreadSession>;
+    private createStagehand?;
+    private onBrowserCreated?;
+    constructor(config: StagehandThreadManagerConfig);
+    /**
+     * Set the factory function for creating new Stagehand instances.
+     * Required for 'thread' scope mode.
+     */
+    setCreateStagehand(factory: () => Promise<V3>): void;
+    /**
+     * Get the page for a specific thread, creating session if needed.
+     */
+    getPageForThread(threadId?: string): Promise<V3Page$1 | null>;
+    /**
+     * Create a new session for a thread.
+     */
+    protected createSession(threadId: string): Promise<StagehandThreadSession>;
+    /**
+     * Restore browser state (multiple tabs) to a Stagehand instance.
+     */
+    private restoreBrowserState;
+    /**
+     * Get the manager (Stagehand instance) for a specific session.
+     */
+    protected getManagerForSession(session: StagehandThreadSession): V3;
+    /**
+     * Destroy a session and clean up resources.
+     */
+    protected doDestroySession(session: StagehandThreadSession): Promise<void>;
+    /**
+     * Destroy all sessions (called during browser close).
+     * doDestroySession handles closing individual Stagehand instances.
+     */
+    destroyAllSessions(): Promise<void>;
+}
+
+/**
+ * Stagehand Browser Types
+ */
+
+/**
+ * Model configuration for Stagehand AI operations
+ */
+type ModelConfiguration = string | {
+    modelName: string;
+    apiKey?: string;
+    baseURL?: string;
+};
+/**
+ * Stagehand-specific configuration fields.
+ */
+interface StagehandConfigExtensions {
+    /**
+     * 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;
+}
+/**
+ * Configuration for StagehandBrowser with compile-time enforcement of cdpUrl/scope compatibility.
+ *
+ * This type enforces that `cdpUrl` and `scope: 'thread'` cannot be used together:
+ * - When `cdpUrl` is provided, `scope` must be `'shared'` or omitted
+ * - When `scope: 'thread'` is used, `cdpUrl` must not be provided
+ */
+type StagehandBrowserConfig = (BrowserConfigBase & StagehandConfigExtensions & {
+    cdpUrl?: undefined;
+    scope?: BrowserScope;
+}) | (BrowserConfigBase & StagehandConfigExtensions & {
+    cdpUrl: CdpUrlProvider;
+    scope?: 'shared';
+});
+/**
+ * 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 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";
+    /** 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;
+    /** Debounce timers per thread for tab change reconnection */
+    private tabChangeDebounceTimers;
+    constructor(config?: StagehandBrowserConfig);
+    /**
+     * 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 'thread' scope.
+     */
+    private createStagehandInstance;
+    protected doLaunch(): Promise<void>;
+    /**
+     * Set up close event listener for a shared Stagehand instance.
+     * Listens to both context and page close events for robust detection.
+     */
+    private setupCloseListenerForSharedScope;
+    /**
+     * 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;
+    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>;
+    /**
+     * 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 'thread' scope, this creates a dedicated Stagehand instance.
+     * For 'shared' scope, returns the shared instance.
+     */
+    getManagerForThread(threadId?: string): Promise<Stagehand | null>;
+    /**
+     * 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 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 active page for a thread (implements abstract method from base class).
+     */
+    protected getActivePage(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 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.
+     */
+    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>;
+    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;
+    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 };