@crawlee/stagehand 4.0.0-beta.99 → 4.0.0-rc.1

package/internals/stagehand-crawler.d.ts

@@ -1,12 +1,11 @@
 import type { Action, ActOptions, ActResult, AgentConfig, ExtractOptions, LLMClient, ModelConfiguration, NonStreamingAgentInstance, ObserveOptions, Stagehand, StreamingAgentInstance } from '@browserbasehq/stagehand';
-import type { BrowserCrawlerOptions, BrowserCrawlingContext, BrowserHook, ContextPipeline, CrawlingContext, GetUserDataFromRequest, LoadedContext, RequestHandler, RouterHandler, RouterRoutes, RouteSchemas, RoutesFromSchemas } from '@crawlee/browser';
+import type { BrowserCrawlerOptions, BrowserCrawlingContext, BrowserHook, GetUserDataFromRequest, RequestHandler, RouterHandler, RouterRoutes, RouteSchemas, RoutesFromSchemas } from '@crawlee/browser';
 import { BrowserCrawler } from '@crawlee/browser';
 import type { Dictionary } from '@crawlee/types';
 // @ts-ignore optional peer dependency or compatibility with es2022
-import type { LaunchOptions, Page, Response } from 'playwright';
-import type { z } from 'zod';
+import type { Page, Response } from 'playwright';
+import { z } from 'zod';
 import type { StagehandLaunchContext } from './stagehand-launcher';
-import type { StagehandPlugin } from './stagehand-plugin';
 /**
  * Stagehand-specific configuration options.
  */
@@ -172,7 +171,7 @@ export interface StagehandPage extends Page {
  * Goto options for StagehandCrawler navigation.
  */
 export type StagehandGotoOptions = NonNullable<Parameters<Page['goto']>[1]>;
-export interface StagehandCrawlingContext<UserData extends Dictionary = Dictionary> extends BrowserCrawlingContext<StagehandPage, Response, UserData, StagehandGotoOptions> {
+export interface StagehandCrawlingContext<UserData extends Dictionary = any> extends BrowserCrawlingContext<StagehandPage, Response, UserData, StagehandGotoOptions> {
     /**
      * Enhanced Playwright page with Stagehand AI methods.
      * Use page.act(), page.extract(), page.observe(), page.agent() for AI-powered operations.
@@ -187,19 +186,11 @@ export interface StagehandCrawlingContext<UserData extends Dictionary = Dictiona
 /**
  * Hook function for StagehandCrawler.
  */
-export interface StagehandHook extends BrowserHook<StagehandCrawlingContext> {
-}
-/**
- * Request handler for StagehandCrawler.
- */
-export interface StagehandRequestHandler extends RequestHandler<LoadedContext<StagehandCrawlingContext>> {
-}
+export type StagehandHook<UserData extends Dictionary = any> = BrowserHook<StagehandCrawlingContext<UserData>>;
 /**
  * Options for StagehandCrawler.
  */
-export interface StagehandCrawlerOptions<ContextExtension = Dictionary<never>, ExtendedContext extends StagehandCrawlingContext = StagehandCrawlingContext & ContextExtension, Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<StagehandCrawlingContext['request']>>> extends BrowserCrawlerOptions<StagehandPage, Response, StagehandCrawlingContext, ContextExtension, ExtendedContext, {
-    browserPlugins: [StagehandPlugin];
-}, Routes> {
+export interface StagehandCrawlerOptions<ContextExtension = Dictionary<never>, ExtendedContext extends StagehandCrawlingContext = StagehandCrawlingContext & ContextExtension, Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<StagehandCrawlingContext['request']>>, StatisticStateExtension extends object = {}> extends BrowserCrawlerOptions<StagehandPage, Response, StagehandCrawlingContext, ContextExtension, ExtendedContext, Routes, StatisticStateExtension> {
     /**
      * Stagehand-specific configuration options.
      * These options configure the AI behavior and Browserbase integration.
@@ -209,6 +200,11 @@ export interface StagehandCrawlerOptions<ContextExtension = Dictionary<never>, E
      * Launch context with Stagehand-specific options.
      */
     launchContext?: StagehandLaunchContext;
+    /**
+     * Whether to run browser in headless mode. Defaults to `true`.
+     * Can be also set via {@link Configuration}.
+     */
+    headless?: boolean;
     /**
      * Function that is called to process each request.
      *
@@ -257,11 +253,11 @@ export interface StagehandCrawlerOptions<ContextExtension = Dictionary<never>, E
     /**
      * Async functions that are sequentially evaluated before the navigation.
      */
-    preNavigationHooks?: StagehandHook[];
+    preNavigationHooks?: BrowserHook<StagehandCrawlingContext<GetUserDataFromRequest<ExtendedContext['request']>>, ContextExtension>[];
     /**
      * Async functions that are sequentially evaluated after the navigation.
      */
-    postNavigationHooks?: StagehandHook[];
+    postNavigationHooks?: BrowserHook<StagehandCrawlingContext<GetUserDataFromRequest<ExtendedContext['request']>>, ContextExtension>[];
 }
 /**
  * StagehandCrawler provides AI-powered web crawling using Browserbase's Stagehand library.
@@ -312,127 +308,143 @@ export interface StagehandCrawlerOptions<ContextExtension = Dictionary<never>, E
  * await crawler.run(['https://example.com']);
  * ```
  */
-export declare class StagehandCrawler<ContextExtension = Dictionary<never>, ExtendedContext extends StagehandCrawlingContext = StagehandCrawlingContext & ContextExtension, Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<StagehandCrawlingContext['request']>>> extends BrowserCrawler<StagehandPage, Response, {
-    browserPlugins: [StagehandPlugin];
-}, LaunchOptions, StagehandCrawlingContext, ContextExtension, ExtendedContext, Routes> {
+export declare class StagehandCrawler<ContextExtension = Dictionary<never>, ExtendedContext extends StagehandCrawlingContext = StagehandCrawlingContext & ContextExtension, Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<StagehandCrawlingContext['request']>>, StatisticStateExtension extends object = {}> extends BrowserCrawler<StagehandPage, Response, StagehandCrawlingContext, ContextExtension, ExtendedContext, Routes, StatisticStateExtension> {
+    #private;
+    /**
+     * @internal
+     */
     protected static optionsShape: {
-// @ts-ignore optional peer dependency or compatibility with es2022
-        stagehandOptions: import("ow", { with: { "resolution-mode": "import" } }).ObjectPredicate<object> & import("ow", { with: { "resolution-mode": "import" } }).BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        browserPoolOptions: import("ow", { with: { "resolution-mode": "import" } }).ObjectPredicate<object> & import("ow", { with: { "resolution-mode": "import" } }).BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        navigationTimeoutSecs: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        preNavigationHooks: import("ow").ArrayPredicate<unknown> & import("ow").BasePredicate<unknown[] | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        postNavigationHooks: import("ow").ArrayPredicate<unknown> & import("ow").BasePredicate<unknown[] | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        launchContext: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        headless: import("ow").AnyPredicate<string | boolean>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        browserPool: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        remoteBrowser: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        saveResponseCookies: import("ow").BooleanPredicate & import("ow").BasePredicate<boolean | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        proxyConfiguration: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        contextPipelineBuilder: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        extendContext: import("ow").Predicate<Function> & import("ow").BasePredicate<Function | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        requestList: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        requestQueue: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        requestHandler: import("ow").Predicate<Function> & import("ow").BasePredicate<Function | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        requestHandlerTimeoutSecs: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        errorHandler: import("ow").Predicate<Function> & import("ow").BasePredicate<Function | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        failedRequestHandler: import("ow").Predicate<Function> & import("ow").BasePredicate<Function | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        maxRequestRetries: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        sameDomainDelaySecs: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        maxRequestsPerCrawl: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        maxCrawlDepth: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        taskLoopOptions: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        concurrencySystem: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        sessionPool: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        statusMessageLoggingInterval: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        statusMessageCallback: import("ow").Predicate<Function> & import("ow").BasePredicate<Function | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        additionalHttpErrorStatusCodes: import("ow").ArrayPredicate<number>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        ignoreHttpErrorStatusCodes: import("ow").ArrayPredicate<number>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        blockedStatusCodes: import("ow").ArrayPredicate<number>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        retryOnBlocked: import("ow").BooleanPredicate & import("ow").BasePredicate<boolean | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        respectRobotsTxtFile: import("ow").AnyPredicate<boolean | object>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        onSkippedRequest: import("ow").Predicate<Function> & import("ow").BasePredicate<Function | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        httpClient: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        configuration: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        storageBackend: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        eventManager: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        logger: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        minConcurrency: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        maxConcurrency: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        maxRequestsPerMinute: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        keepAlive: import("ow").BooleanPredicate & import("ow").BasePredicate<boolean | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        statisticsOptions: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        id: import("ow").StringPredicate & import("ow").BasePredicate<string | undefined>;
+        contextPipelineBuilder: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        extendContext: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+        requestList: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        requestQueue: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        requestManager: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        requestHandler: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+        requestHandlerTimeoutSecs: z.ZodOptional<z.ZodCustom<number, number>>;
+        errorHandler: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+        failedRequestHandler: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+        maxRequestRetries: z.ZodDefault<z.ZodCustom<number, number>>;
+        sameDomainDelaySecs: z.ZodDefault<z.ZodCustom<number, number>>;
+        maxRequestsPerCrawl: z.ZodOptional<z.ZodCustom<number, number>>;
+        maxCrawlDepth: z.ZodOptional<z.ZodCustom<number, number>>;
+        taskLoopOptions: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        concurrencySystem: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        sessionPool: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        statusMessageLoggingInterval: z.ZodDefault<z.ZodCustom<number, number>>;
+        statusMessageCallback: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+        additionalHttpErrorStatusCodes: z.ZodDefault<z.ZodArray<z.ZodCustom<number, number>>>;
+        ignoreHttpErrorStatusCodes: z.ZodDefault<z.ZodArray<z.ZodCustom<number, number>>>;
+        blockedStatusCodes: z.ZodOptional<z.ZodArray<z.ZodCustom<number, number>>>;
+        retryOnBlocked: z.ZodDefault<z.ZodBoolean>;
+        respectRobotsTxtFile: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodCustom<Dictionary, Dictionary>]>>;
+        transactionalStorage: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            requestQueue: z.ZodOptional<z.ZodEnum<{
+                deferred: "deferred";
+                writeThrough: "writeThrough";
+            }>>;
+        }, z.core.$strict>]>>;
+        onSkippedRequest: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+// @ts-ignore optional peer dependency or compatibility with es2022
+        httpClient: z.ZodOptional<z.ZodInstanceOf<import("@crawlee/http-client").BaseHttpClient>>;
+// @ts-ignore optional peer dependency or compatibility with es2022
+        configuration: z.ZodOptional<z.ZodInstanceOf<import("@crawlee/browser").Configuration>>;
+        storageBackend: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+// @ts-ignore optional peer dependency or compatibility with es2022
+        eventManager: z.ZodOptional<z.ZodInstanceOf<import("@crawlee/browser").EventManager>>;
+        logger: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        minConcurrency: z.ZodOptional<z.ZodCustom<number, number>>;
+        maxConcurrency: z.ZodOptional<z.ZodCustom<number, number>>;
+        initialConcurrency: z.ZodOptional<z.ZodCustom<number, number>>;
+        maxRequestsPerMinute: z.ZodOptional<z.ZodCustom<number, number>>;
+        keepAlive: z.ZodOptional<z.ZodBoolean>;
+        statistics: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        id: z.ZodOptional<z.ZodString>;
+        navigationTimeoutSecs: z.ZodDefault<z.ZodCustom<number, number>>;
+        preNavigationHooks: z.ZodDefault<z.ZodCustom<unknown[], unknown[]>>;
+        postNavigationHooks: z.ZodDefault<z.ZodCustom<unknown[], unknown[]>>;
+        browserPool: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        browserPoolBuilder: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+        remoteBrowser: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        saveResponseCookies: z.ZodDefault<z.ZodBoolean>;
+        proxyConfiguration: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        ignoreIframes: z.ZodDefault<z.ZodBoolean>;
+        ignoreShadowRoots: z.ZodDefault<z.ZodBoolean>;
+        launchContext: z.ZodDefault<z.ZodCustom<Dictionary, Dictionary>>;
+        stagehandOptions: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        headless: z.ZodOptional<z.ZodBoolean>;
     };
+    /** @internal */
+    protected static optionsSchema: z.ZodObject<{
+        contextPipelineBuilder: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        extendContext: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+        requestList: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        requestQueue: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        requestManager: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        requestHandler: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+        requestHandlerTimeoutSecs: z.ZodOptional<z.ZodCustom<number, number>>;
+        errorHandler: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+        failedRequestHandler: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+        maxRequestRetries: z.ZodDefault<z.ZodCustom<number, number>>;
+        sameDomainDelaySecs: z.ZodDefault<z.ZodCustom<number, number>>;
+        maxRequestsPerCrawl: z.ZodOptional<z.ZodCustom<number, number>>;
+        maxCrawlDepth: z.ZodOptional<z.ZodCustom<number, number>>;
+        taskLoopOptions: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        concurrencySystem: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        sessionPool: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        statusMessageLoggingInterval: z.ZodDefault<z.ZodCustom<number, number>>;
+        statusMessageCallback: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+        additionalHttpErrorStatusCodes: z.ZodDefault<z.ZodArray<z.ZodCustom<number, number>>>;
+        ignoreHttpErrorStatusCodes: z.ZodDefault<z.ZodArray<z.ZodCustom<number, number>>>;
+        blockedStatusCodes: z.ZodOptional<z.ZodArray<z.ZodCustom<number, number>>>;
+        retryOnBlocked: z.ZodDefault<z.ZodBoolean>;
+        respectRobotsTxtFile: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodCustom<Dictionary, Dictionary>]>>;
+        transactionalStorage: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            requestQueue: z.ZodOptional<z.ZodEnum<{
+                deferred: "deferred";
+                writeThrough: "writeThrough";
+            }>>;
+        }, z.core.$strict>]>>;
+        onSkippedRequest: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+// @ts-ignore optional peer dependency or compatibility with es2022
+        httpClient: z.ZodOptional<z.ZodInstanceOf<import("@crawlee/http-client").BaseHttpClient>>;
+// @ts-ignore optional peer dependency or compatibility with es2022
+        configuration: z.ZodOptional<z.ZodInstanceOf<import("@crawlee/browser").Configuration>>;
+        storageBackend: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+// @ts-ignore optional peer dependency or compatibility with es2022
+        eventManager: z.ZodOptional<z.ZodInstanceOf<import("@crawlee/browser").EventManager>>;
+        logger: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        minConcurrency: z.ZodOptional<z.ZodCustom<number, number>>;
+        maxConcurrency: z.ZodOptional<z.ZodCustom<number, number>>;
+        initialConcurrency: z.ZodOptional<z.ZodCustom<number, number>>;
+        maxRequestsPerMinute: z.ZodOptional<z.ZodCustom<number, number>>;
+        keepAlive: z.ZodOptional<z.ZodBoolean>;
+        statistics: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        id: z.ZodOptional<z.ZodString>;
+        navigationTimeoutSecs: z.ZodDefault<z.ZodCustom<number, number>>;
+        preNavigationHooks: z.ZodDefault<z.ZodCustom<unknown[], unknown[]>>;
+        postNavigationHooks: z.ZodDefault<z.ZodCustom<unknown[], unknown[]>>;
+        browserPool: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        browserPoolBuilder: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+        remoteBrowser: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        saveResponseCookies: z.ZodDefault<z.ZodBoolean>;
+        proxyConfiguration: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        ignoreIframes: z.ZodDefault<z.ZodBoolean>;
+        ignoreShadowRoots: z.ZodDefault<z.ZodBoolean>;
+        launchContext: z.ZodDefault<z.ZodCustom<Dictionary, Dictionary>>;
+        stagehandOptions: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        headless: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>;
     /**
      * Creates a new instance of StagehandCrawler.
      *
      * @param options - Crawler configuration options
      */
-    constructor(options?: StagehandCrawlerOptions<ContextExtension, ExtendedContext, Routes>);
-    protected buildContextPipeline(): ContextPipeline<CrawlingContext, StagehandCrawlingContext>;
-    /**
-     * Resolves the {@link StagehandController} that owns the given page, or
-     * `undefined` when the pool does not expose controllers (e.g. a custom
-     * {@link IBrowserPool} implementation).
-     *
-     * Stagehand needs direct controller access to reach the `Stagehand`
-     * instance bound to the page's browser, which is why it reaches past the
-     * {@link IBrowserPool} abstraction here.
-     */
-    private getBrowserControllerByPage;
-    /**
-     * Enhance the page with Stagehand AI methods.
-     */
-    private setUpStagehand;
+    constructor(options?: StagehandCrawlerOptions<ContextExtension, ExtendedContext, Routes, StatisticStateExtension>);
     /**
      * Navigation handler for Stagehand crawler.
      * Uses standard Playwright navigation.
      */
-    protected _navigationHandler(crawlingContext: StagehandCrawlingContext, gotoOptions: StagehandGotoOptions): Promise<Response | null>;
+    protected navigationHandler(crawlingContext: StagehandCrawlingContext, gotoOptions: StagehandGotoOptions): Promise<Response | null>;
 }
 /**
  * Creates a new router for StagehandCrawler with type-safe route handlers.
@@ -450,7 +462,7 @@ export declare class StagehandCrawler<ContextExtension = Dictionary<never>, Exte
  * });
  *
  * router.addDefaultHandler(async ({ page, enqueueLinks }) => {
- *   await enqueueLinks({ globs: ['https://example.com/products/*'] });
+ *   await enqueueLinks({ include: ['https://example.com/products/*'] });
  * });
  *
  * const crawler = new StagehandCrawler({

package/internals/stagehand-crawler.js

@@ -2,10 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StagehandCrawler = void 0;
 exports.createStagehandRouter = createStagehandRouter;
-const tslib_1 = require("tslib");
 const browser_1 = require("@crawlee/browser");
-const ow_1 = tslib_1.__importDefault(require("ow"));
-const stagehand_launcher_1 = require("./stagehand-launcher");
+const internal_1 = require("@crawlee/utils/internal");
+const zod_1 = require("zod");
+const stagehand_browser_pool_1 = require("./stagehand-browser-pool");
 const stagehand_utils_1 = require("./utils/stagehand-utils");
 /**
  * StagehandCrawler provides AI-powered web crawling using Browserbase's Stagehand library.
@@ -57,38 +57,57 @@ const stagehand_utils_1 = require("./utils/stagehand-utils");
  * ```
  */
 class StagehandCrawler extends browser_1.BrowserCrawler {
+    /**
+     * @internal
+     */
     static optionsShape = {
         ...browser_1.BrowserCrawler.optionsShape,
-        stagehandOptions: ow_1.default.optional.object,
-        browserPoolOptions: ow_1.default.optional.object,
+        launchContext: internal_1.schemas.anyObject.default(() => ({})),
+        stagehandOptions: internal_1.schemas.anyObject.optional(),
+        headless: zod_1.z.boolean().optional(),
     };
+    /** @internal */
+    static optionsSchema = zod_1.z.strictObject(StagehandCrawler.optionsShape);
     /**
      * Creates a new instance of StagehandCrawler.
      *
      * @param options - Crawler configuration options
      */
     constructor(options = {}) {
-        (0, ow_1.default)(options, 'StagehandCrawlerOptions', ow_1.default.object.exactShape(StagehandCrawler.optionsShape));
-        const { stagehandOptions = {}, launchContext = {}, contextPipelineBuilder, ...browserCrawlerOptions } = options;
-        const browserPoolOptions = {
-            ...options.browserPoolOptions,
-        };
-        // Create launcher with Stagehand plugin
-        const launcher = new stagehand_launcher_1.StagehandLauncher({
-            ...launchContext,
-            stagehandOptions,
-        });
-        browserPoolOptions.browserPlugins = [launcher.createBrowserPlugin()];
-        // Initialize BrowserCrawler with Stagehand plugin and fingerprinting enabled
+        const parsedOptions = (0, internal_1.parseArgument)(options, StagehandCrawler.optionsSchema, 'StagehandCrawlerOptions');
+        const { stagehandOptions, launchContext, headless, configuration, ...browserCrawlerOptions } = parsedOptions;
+        if (options.browserPool) {
+            // The raw options, not the parsed ones: `launchContext` has a default, so by now it is always set.
+            (0, internal_1.assertBrowserPoolNotConfigured)(new.target.name, {
+                launchContext: options.launchContext,
+                stagehandOptions: options.stagehandOptions,
+                headless: options.headless,
+            });
+        }
         super({
             ...browserCrawlerOptions,
-            launchContext,
-            browserPoolOptions,
-            contextPipelineBuilder: contextPipelineBuilder ?? (() => this.buildContextPipeline()),
+            configuration,
+            // The pool serves plain Playwright pages - a page only becomes a `StagehandPage` further down the
+            // pipeline, once `setUpStagehand` enhances it - so its page type is narrower than the crawler's.
+            browserPoolBuilder: (remoteBrowser) => (remoteBrowser
+                ? (0, stagehand_browser_pool_1.remoteStagehandBrowserPool)({
+                    ...remoteBrowser,
+                    launchContext,
+                    stagehandOptions,
+                    headless,
+                    configuration,
+                })
+                : (0, stagehand_browser_pool_1.stagehandBrowserPool)({
+                    launchContext,
+                    stagehandOptions,
+                    headless,
+                    configuration,
+                })),
+            contextPipelineBuilder: () => this.#buildContextPipeline(),
         });
     }
-    buildContextPipeline() {
-        return super.buildContextPipeline().compose({ action: this.setUpStagehand.bind(this) });
+    #buildContextPipeline() {
+        return this.buildContextPipeline().compose(this.#setUpStagehand.bind(this));
     }
     /**
      * Resolves the {@link StagehandController} that owns the given page, or
@@ -99,7 +118,7 @@ class StagehandCrawler extends browser_1.BrowserCrawler {
      * instance bound to the page's browser, which is why it reaches past the
      * {@link IBrowserPool} abstraction here.
      */
-    getBrowserControllerByPage(page) {
+    #getBrowserControllerByPage(page) {
         if ('getBrowserControllerByPage' in this.browserPool) {
             return this.browserPool.getBrowserControllerByPage(page);
         }
@@ -108,8 +127,8 @@ class StagehandCrawler extends browser_1.BrowserCrawler {
     /**
      * Enhance the page with Stagehand AI methods.
      */
-    async setUpStagehand(crawlingContext) {
-        const controller = this.getBrowserControllerByPage(crawlingContext.page);
+    async #setUpStagehand(crawlingContext) {
+        const controller = this.#getBrowserControllerByPage(crawlingContext.page);
         if (!controller) {
             throw new Error('Could not resolve StagehandController for page — is the browser pool configured correctly?');
         }
@@ -123,7 +142,7 @@ class StagehandCrawler extends browser_1.BrowserCrawler {
      * Navigation handler for Stagehand crawler.
      * Uses standard Playwright navigation.
      */
-    async _navigationHandler(crawlingContext, gotoOptions) {
+    async navigationHandler(crawlingContext, gotoOptions) {
         // Use standard page.goto for navigation
         return crawlingContext.page.goto(crawlingContext.request.url, gotoOptions);
     }

package/internals/stagehand-launcher.d.ts

@@ -2,6 +2,7 @@ import type { BrowserLaunchContext } from '@crawlee/browser';
 import { BrowserLauncher, Configuration } from '@crawlee/browser';
 // @ts-ignore optional peer dependency or compatibility with es2022
 import type { BrowserType, LaunchOptions } from 'playwright';
+import { z } from 'zod';
 import type { StagehandOptions } from './stagehand-crawler';
 import { StagehandPlugin } from './stagehand-plugin';
 /**
@@ -13,10 +14,6 @@ export interface StagehandLaunchContext extends BrowserLaunchContext<LaunchOptio
      * These will be passed to Stagehand's localBrowserLaunchOptions after fingerprinting is applied.
      */
     launchOptions?: LaunchOptions & Parameters<BrowserType['launchPersistentContext']>[1];
-    /**
-     * Stagehand-specific configuration for AI operations.
-     */
-    stagehandOptions?: StagehandOptions;
     /**
      * URL to a HTTP proxy server. It must define the port number,
      * and it may also contain proxy username and password.
@@ -31,21 +28,6 @@ export interface StagehandLaunchContext extends BrowserLaunchContext<LaunchOptio
      * @default false
      */
     useChrome?: boolean;
-    /**
-     * With this option selected, all pages will be opened in a new incognito browser context.
-     * @default false
-     */
-    useIncognitoPages?: boolean;
-    /**
-     * Sets the User Data Directory path.
-     * The user data directory contains profile data such as history, bookmarks, and cookies.
-     */
-    userDataDir?: string;
-    /**
-     * By default this function uses `require("playwright").chromium`.
-     * If you want to use a different browser you can pass it by this property.
-     */
-    launcher?: BrowserType;
 }
 /**
  * StagehandLauncher is based on BrowserLauncher and creates StagehandPlugin instances.
@@ -54,36 +36,52 @@ export interface StagehandLaunchContext extends BrowserLaunchContext<LaunchOptio
  * @ignore
  */
 export declare class StagehandLauncher extends BrowserLauncher<StagehandPlugin> {
+    #private;
     readonly configuration: Configuration;
+    /**
+     * @internal
+     */
     protected static optionsShape: {
+        proxyUrl: z.ZodOptional<z.ZodURL>;
+        useChrome: z.ZodOptional<z.ZodBoolean>;
+        useIncognitoPages: z.ZodOptional<z.ZodBoolean>;
+        browserPerProxy: z.ZodOptional<z.ZodBoolean>;
+        ignoreProxyCertificate: z.ZodOptional<z.ZodBoolean>;
+        userDataDir: z.ZodOptional<z.ZodString>;
 // @ts-ignore optional peer dependency or compatibility with es2022
-        launcher: import("ow", { with: { "resolution-mode": "import" } }).ObjectPredicate<object> & import("ow", { with: { "resolution-mode": "import" } }).BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        launchContextOptions: import("ow", { with: { "resolution-mode": "import" } }).ObjectPredicate<object> & import("ow", { with: { "resolution-mode": "import" } }).BasePredicate<object | undefined>;
+        launchOptions: z.ZodOptional<z.ZodCustom<import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary, import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary>>;
+        userAgent: z.ZodOptional<z.ZodString>;
 // @ts-ignore optional peer dependency or compatibility with es2022
-        stagehandOptions: import("ow", { with: { "resolution-mode": "import" } }).ObjectPredicate<object> & import("ow", { with: { "resolution-mode": "import" } }).BasePredicate<object | undefined>;
+        launcher: z.ZodOptional<z.ZodCustom<import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary, import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary>>;
 // @ts-ignore optional peer dependency or compatibility with es2022
-        proxyUrl: import("ow").StringPredicate & import("ow").BasePredicate<string | undefined>;
+        launchContextOptions: z.ZodOptional<z.ZodCustom<import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary, import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary>>;
 // @ts-ignore optional peer dependency or compatibility with es2022
-        useChrome: import("ow").BooleanPredicate & import("ow").BasePredicate<boolean | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        useIncognitoPages: import("ow").BooleanPredicate & import("ow").BasePredicate<boolean | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        browserPerProxy: import("ow").BooleanPredicate & import("ow").BasePredicate<boolean | undefined>;
+        stagehandOptions: z.ZodOptional<z.ZodCustom<import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary, import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary>>;
+    };
+    /** @internal */
+    protected static optionsSchema: z.ZodObject<{
+        proxyUrl: z.ZodOptional<z.ZodURL>;
+        useChrome: z.ZodOptional<z.ZodBoolean>;
+        useIncognitoPages: z.ZodOptional<z.ZodBoolean>;
+        browserPerProxy: z.ZodOptional<z.ZodBoolean>;
+        ignoreProxyCertificate: z.ZodOptional<z.ZodBoolean>;
+        userDataDir: z.ZodOptional<z.ZodString>;
 // @ts-ignore optional peer dependency or compatibility with es2022
-        ignoreProxyCertificate: import("ow").BooleanPredicate & import("ow").BasePredicate<boolean | undefined>;
+        launchOptions: z.ZodOptional<z.ZodCustom<import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary, import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary>>;
+        userAgent: z.ZodOptional<z.ZodString>;
 // @ts-ignore optional peer dependency or compatibility with es2022
-        userDataDir: import("ow").StringPredicate & import("ow").BasePredicate<string | undefined>;
+        launcher: z.ZodOptional<z.ZodCustom<import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary, import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary>>;
 // @ts-ignore optional peer dependency or compatibility with es2022
-        launchOptions: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
+        launchContextOptions: z.ZodOptional<z.ZodCustom<import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary, import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary>>;
 // @ts-ignore optional peer dependency or compatibility with es2022
-        userAgent: import("ow").StringPredicate & import("ow").BasePredicate<string | undefined>;
-    };
-    private readonly stagehandOptions;
+        stagehandOptions: z.ZodOptional<z.ZodCustom<import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary, import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary>>;
+    }, z.core.$strict>;
     /**
      * All StagehandLauncher parameters are passed via the launchContext object.
      */
-    constructor(launchContext?: StagehandLaunchContext, configuration?: Configuration);
+    constructor(launchContext?: StagehandLaunchContext & {
+        stagehandOptions?: StagehandOptions;
+    }, configuration?: Configuration);
     /**
      * Creates a new StagehandPlugin instance with resolved options.
      */