@crawlee/stagehand 4.0.0-rc.0 → 4.0.0-rc.1

package/README.md

@@ -34,7 +34,7 @@ Crawlee is available as the [`crawlee`](https://www.npmjs.com/package/crawlee) N
 
 We recommend visiting the [Introduction tutorial](https://crawlee.dev/js/docs/introduction) in Crawlee documentation for more information.
 
-> Crawlee requires **Node.js 16 or higher**.
+> Crawlee requires **Node.js 22.13 or higher**.
 
 ### With Crawlee CLI
 

package/index.d.ts

@@ -53,7 +53,6 @@ export * from '@crawlee/browser';
 export { StagehandCrawler, createStagehandRouter } from './internals/stagehand-crawler';
 export { stagehandBrowserPool, remoteStagehandBrowserPool } from './internals/stagehand-browser-pool';
 export type { StagehandBrowserPool, StagehandBrowserPoolOptions, RemoteStagehandBrowserPoolOptions, } from './internals/stagehand-browser-pool';
-export type { StagehandOptions, StagehandPage, StagehandCrawlingContext, StagehandHook, StagehandRequestHandler, StagehandGotoOptions, StagehandCrawlerOptions, } from './internals/stagehand-crawler';
+export type { StagehandOptions, StagehandPage, StagehandCrawlingContext, StagehandHook, StagehandGotoOptions, StagehandCrawlerOptions, } from './internals/stagehand-crawler';
 export type { StagehandLaunchContext } from './internals/stagehand-launcher';
-export * as stagehandUtils from './internals/utils/stagehand-utils';
-export type { ActOptions, ActResult, Action, AgentConfig, AgentResult, ExtractOptions, ModelConfiguration, ObserveOptions, Stagehand, } from '@browserbasehq/stagehand';
+export type { ActOptions, ActResult, Action, AgentConfig, ExtractOptions, ModelConfiguration, ObserveOptions, Stagehand, } from '@browserbasehq/stagehand';

package/index.js

@@ -51,7 +51,7 @@
  * @module @crawlee/stagehand
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stagehandUtils = exports.remoteStagehandBrowserPool = exports.stagehandBrowserPool = exports.createStagehandRouter = exports.StagehandCrawler = void 0;
+exports.remoteStagehandBrowserPool = exports.stagehandBrowserPool = exports.createStagehandRouter = exports.StagehandCrawler = void 0;
 const tslib_1 = require("tslib");
 // Re-export everything from @crawlee/browser for convenience
 tslib_1.__exportStar(require("@crawlee/browser"), exports);
@@ -63,5 +63,3 @@ Object.defineProperty(exports, "createStagehandRouter", { enumerable: true, get:
 var stagehand_browser_pool_1 = require("./internals/stagehand-browser-pool");
 Object.defineProperty(exports, "stagehandBrowserPool", { enumerable: true, get: function () { return stagehand_browser_pool_1.stagehandBrowserPool; } });
 Object.defineProperty(exports, "remoteStagehandBrowserPool", { enumerable: true, get: function () { return stagehand_browser_pool_1.remoteStagehandBrowserPool; } });
-// Export utilities as namespace
-exports.stagehandUtils = tslib_1.__importStar(require("./internals/utils/stagehand-utils"));

package/index.mjs

@@ -2,6 +2,7 @@ import mod from "./index.js";
 
 export default mod;
 export const API_PROCESSED_REQUESTS_DELAY_MILLIS = mod.API_PROCESSED_REQUESTS_DELAY_MILLIS;
+export const AfterCommitError = mod.AfterCommitError;
 export const ApifyLogAdapter = mod.ApifyLogAdapter;
 export const ArgumentValidationError = mod.ArgumentValidationError;
 export const AutoscaledPool = mod.AutoscaledPool;
@@ -18,13 +19,13 @@ export const ContextPipelineInitializationError = mod.ContextPipelineInitializat
 export const ContextPipelineInterruptedError = mod.ContextPipelineInterruptedError;
 export const CookieParseError = mod.CookieParseError;
 export const CpuLoadSignal = mod.CpuLoadSignal;
+export const CrawlingRequest = mod.CrawlingRequest;
 export const CriticalError = mod.CriticalError;
 export const DATASET_ITERATORS_DEFAULT_LIMIT = mod.DATASET_ITERATORS_DEFAULT_LIMIT;
 export const DEFAULT_CURRENT_HISTORY_SECS = mod.DEFAULT_CURRENT_HISTORY_SECS;
 export const DEFAULT_SNAPSHOT_HISTORY_SECS = mod.DEFAULT_SNAPSHOT_HISTORY_SECS;
 export const Dataset = mod.Dataset;
 export const EnqueueStrategy = mod.EnqueueStrategy;
-export const ErrorSnapshotter = mod.ErrorSnapshotter;
 export const ErrorTracker = mod.ErrorTracker;
 export const EventLoopLoadSignal = mod.EventLoopLoadSignal;
 export const EventManager = mod.EventManager;
@@ -36,7 +37,6 @@ export const LogLevel = mod.LogLevel;
 export const Logger = mod.Logger;
 export const LoggerJson = mod.LoggerJson;
 export const LoggerText = mod.LoggerText;
-export const MAX_POOL_SIZE = mod.MAX_POOL_SIZE;
 export const MAX_QUERIES_FOR_CONSISTENCY = mod.MAX_QUERIES_FOR_CONSISTENCY;
 export const MemoryLoadSignal = mod.MemoryLoadSignal;
 export const MemoryStorageBackend = mod.MemoryStorageBackend;
@@ -45,7 +45,6 @@ export const MissingSessionError = mod.MissingSessionError;
 export const NavigationSkippedError = mod.NavigationSkippedError;
 export const NonRetryableError = mod.NonRetryableError;
 export const OwnedOrInjected = mod.OwnedOrInjected;
-export const PERSIST_STATE_KEY = mod.PERSIST_STATE_KEY;
 export const PersistentRateLimitError = mod.PersistentRateLimitError;
 export const ProxyConfiguration = mod.ProxyConfiguration;
 export const QUERY_HEAD_BUFFER = mod.QUERY_HEAD_BUFFER;
@@ -69,6 +68,7 @@ export const ServiceLocator = mod.ServiceLocator;
 export const Session = mod.Session;
 export const SessionError = mod.SessionError;
 export const SessionPool = mod.SessionPool;
+export const SessionRetiredError = mod.SessionRetiredError;
 export const SitemapRequestLoader = mod.SitemapRequestLoader;
 export const SnapshotStore = mod.SnapshotStore;
 export const Snapshotter = mod.Snapshotter;
@@ -77,13 +77,11 @@ export const StateValidationError = mod.StateValidationError;
 export const Statistics = mod.Statistics;
 export const StorageBackendLoadSignal = mod.StorageBackendLoadSignal;
 export const StorageInstanceManager = mod.StorageInstanceManager;
-export const StorageStatsTracker = mod.StorageStatsTracker;
 export const StorageTransaction = mod.StorageTransaction;
 export const SystemStatus = mod.SystemStatus;
 export const ThrottlingRequestManager = mod.ThrottlingRequestManager;
 export const activeStorageTransaction = mod.activeStorageTransaction;
 export const applyRequestTransform = mod.applyRequestTransform;
-export const assertBrowserPoolNotConfigured = mod.assertBrowserPoolNotConfigured;
 export const assertJsonSerializable = mod.assertJsonSerializable;
 export const bindMethodsToServiceLocator = mod.bindMethodsToServiceLocator;
 export const browserPoolCookieToToughCookie = mod.browserPoolCookieToToughCookie;
@@ -101,6 +99,7 @@ export const createDeserialize = mod.createDeserialize;
 export const createDualIterable = mod.createDualIterable;
 export const createRequestDebugInfo = mod.createRequestDebugInfo;
 export const createRequestOptions = mod.createRequestOptions;
+export const createSkippedRequestArgs = mod.createSkippedRequestArgs;
 export const createStagehandRouter = mod.createStagehandRouter;
 export const createStorageTransaction = mod.createStorageTransaction;
 export const currentStorageTransaction = mod.currentStorageTransaction;
@@ -119,7 +118,6 @@ export const log = mod.log;
 export const mergeCookies = mod.mergeCookies;
 export const navigationDeadlineKey = mod.navigationDeadlineKey;
 export const operationRejectedInTransaction = mod.operationRejectedInTransaction;
-export const parseArgument = mod.parseArgument;
 export const parseRetryAfterHeader = mod.parseRetryAfterHeader;
 export const parseValue = mod.parseValue;
 export const purgeDefaultStorages = mod.purgeDefaultStorages;
@@ -127,17 +125,12 @@ export const rejectOperationInTransaction = mod.rejectOperationInTransaction;
 export const remainingNavigationWindowMillis = mod.remainingNavigationWindowMillis;
 export const remoteStagehandBrowserPool = mod.remoteStagehandBrowserPool;
 export const resolveBaseUrlForEnqueueLinksFiltering = mod.resolveBaseUrlForEnqueueLinksFiltering;
-export const resolveStorageIdentifier = mod.resolveStorageIdentifier;
-export const schemas = mod.schemas;
 export const serializeArray = mod.serializeArray;
 export const serializeValue = mod.serializeValue;
 export const serviceLocator = mod.serviceLocator;
 export const snapshotValue = mod.snapshotValue;
 export const stagehandBrowserPool = mod.stagehandBrowserPool;
-export const stagehandUtils = mod.stagehandUtils;
-export const supportsDomainThrottling = mod.supportsDomainThrottling;
 export const toughCookieToBrowserPoolCookie = mod.toughCookieToBrowserPoolCookie;
-export const tryAbsoluteURL = mod.tryAbsoluteURL;
 export const updateEnqueueLinksPatternCache = mod.updateEnqueueLinksPatternCache;
 export const urlPatternSchema = mod.urlPatternSchema;
 export const useState = mod.useState;

package/internals/stagehand-controller.d.ts

@@ -29,20 +29,6 @@ export declare class StagehandController extends BrowserController<BrowserType,
      * We use Playwright's browser API directly since we connected via CDP.
      */
     protected _newPage(_contextOptions?: unknown): Promise<Page>;
-    /**
-     * Waits until Stagehand knows about the page, so that `act()`/`extract()`/`observe()` can resolve it.
-     *
-     * Stagehand only learns about pages from CDP `Target.attachedToTarget` events on its own connection,
-     * and it maps them by main frame id. We create pages through a separate `connectOverCDP()` handle, so
-     * `context.newPage()` resolves before Stagehand has processed that event — the page is unresolvable for
-     * a short window, and the AI methods fail with 'Failed to resolve V3 Page from Playwright page'.
-     * Stagehand's own `newPage()` polls for the same reason.
-     */
-    private waitForStagehandToRegisterPage;
-    /**
-     * Reads the page's main frame id, which is the key Stagehand resolves pages by.
-     */
-    private getMainFrameId;
     /**
      * Normalizes proxy options for Playwright.
      */

package/internals/stagehand-controller.js

@@ -51,10 +51,10 @@ class StagehandController extends browser_pool_1.BrowserController {
             const page = await context.newPage();
             // Track active pages
             page.once('close', () => {
-                this.activePages--;
+                this.registerPageClosed(page);
             });
             try {
-                await this.waitForStagehandToRegisterPage(page);
+                await this.#waitForStagehandToRegisterPage(page);
             }
             catch (error) {
                 await page.close().catch(() => { });
@@ -77,9 +77,9 @@ class StagehandController extends browser_pool_1.BrowserController {
      * a short window, and the AI methods fail with 'Failed to resolve V3 Page from Playwright page'.
      * Stagehand's own `newPage()` polls for the same reason.
      */
-    async waitForStagehandToRegisterPage(page, timeoutMs = 10_000) {
+    async #waitForStagehandToRegisterPage(page, timeoutMs = 10_000) {
         const stagehand = this.getStagehand();
-        const mainFrameId = await this.getMainFrameId(page);
+        const mainFrameId = await this.#getMainFrameId(page);
         const deadline = Date.now() + timeoutMs;
         while (Date.now() < deadline) {
             if (stagehand.context.resolvePageByMainFrameId(mainFrameId)) {
@@ -94,7 +94,7 @@ class StagehandController extends browser_pool_1.BrowserController {
     /**
      * Reads the page's main frame id, which is the key Stagehand resolves pages by.
      */
-    async getMainFrameId(page) {
+    async #getMainFrameId(page) {
         const cdpSession = await page.context().newCDPSession(page);
         try {
             const { frameTree } = await cdpSession.send('Page.getFrameTree');

package/internals/stagehand-crawler.d.ts

@@ -1,9 +1,9 @@
 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 { Page, Response } from 'playwright';
 import { z } from 'zod';
 import type { StagehandLaunchContext } from './stagehand-launcher';
 /**
@@ -187,11 +187,6 @@ export interface StagehandCrawlingContext<UserData extends Dictionary = any> ext
  * Hook function for StagehandCrawler.
  */
 export type StagehandHook<UserData extends Dictionary = any> = BrowserHook<StagehandCrawlingContext<UserData>>;
-/**
- * Request handler for StagehandCrawler.
- */
-export interface StagehandRequestHandler extends RequestHandler<LoadedContext<StagehandCrawlingContext>> {
-}
 /**
  * Options for StagehandCrawler.
  */
@@ -313,21 +308,12 @@ 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']>>, StatisticStateExtension extends object = {}> extends BrowserCrawler<StagehandPage, Response, LaunchOptions, StagehandCrawlingContext, ContextExtension, ExtendedContext, Routes, StatisticStateExtension> {
+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: {
-        stagehandOptions: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
-        headless: z.ZodOptional<z.ZodBoolean>;
-        navigationTimeoutSecs: z.ZodDefault<z.ZodCustom<number, number>>;
-        preNavigationHooks: z.ZodDefault<z.ZodCustom<unknown[], unknown[]>>;
-        postNavigationHooks: z.ZodDefault<z.ZodCustom<unknown[], unknown[]>>;
-        launchContext: z.ZodDefault<z.ZodCustom<Dictionary, Dictionary>>;
-        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>;
         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>>>;
@@ -359,27 +345,23 @@ export declare class StagehandCrawler<ContextExtension = Dictionary<never>, Exte
         }, 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.ZodCustom<import("@crawlee/http-client").BaseHttpClient, import("@crawlee/http-client").BaseHttpClient>>;
+        httpClient: z.ZodOptional<z.ZodInstanceOf<import("@crawlee/http-client").BaseHttpClient>>;
 // @ts-ignore optional peer dependency or compatibility with es2022
-        configuration: z.ZodOptional<z.ZodCustom<import("@crawlee/browser").Configuration, import("@crawlee/browser").Configuration>>;
+        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.ZodCustom<import("@crawlee/browser").EventManager, import("@crawlee/browser").EventManager>>;
+        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>;
-    };
-    protected static optionsSchema: z.ZodObject<{
-        stagehandOptions: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
-        headless: z.ZodOptional<z.ZodBoolean>;
         navigationTimeoutSecs: z.ZodDefault<z.ZodCustom<number, number>>;
         preNavigationHooks: z.ZodDefault<z.ZodCustom<unknown[], unknown[]>>;
         postNavigationHooks: z.ZodDefault<z.ZodCustom<unknown[], unknown[]>>;
-        launchContext: z.ZodDefault<z.ZodCustom<Dictionary, Dictionary>>;
         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>>;
@@ -387,6 +369,12 @@ export declare class StagehandCrawler<ContextExtension = Dictionary<never>, Exte
         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>>>;
@@ -418,19 +406,33 @@ export declare class StagehandCrawler<ContextExtension = Dictionary<never>, Exte
         }, 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.ZodCustom<import("@crawlee/http-client").BaseHttpClient, import("@crawlee/http-client").BaseHttpClient>>;
+        httpClient: z.ZodOptional<z.ZodInstanceOf<import("@crawlee/http-client").BaseHttpClient>>;
 // @ts-ignore optional peer dependency or compatibility with es2022
-        configuration: z.ZodOptional<z.ZodCustom<import("@crawlee/browser").Configuration, import("@crawlee/browser").Configuration>>;
+        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.ZodCustom<import("@crawlee/browser").EventManager, import("@crawlee/browser").EventManager>>;
+        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.
@@ -438,21 +440,6 @@ export declare class StagehandCrawler<ContextExtension = Dictionary<never>, Exte
      * @param options - Crawler configuration options
      */
     constructor(options?: StagehandCrawlerOptions<ContextExtension, ExtendedContext, Routes, StatisticStateExtension>);
-    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;
     /**
      * Navigation handler for Stagehand crawler.
      * Uses standard Playwright navigation.

package/internals/stagehand-crawler.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.StagehandCrawler = void 0;
 exports.createStagehandRouter = createStagehandRouter;
 const browser_1 = require("@crawlee/browser");
+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");
@@ -56,11 +57,16 @@ const stagehand_utils_1 = require("./utils/stagehand-utils");
  * ```
  */
 class StagehandCrawler extends browser_1.BrowserCrawler {
+    /**
+     * @internal
+     */
     static optionsShape = {
         ...browser_1.BrowserCrawler.optionsShape,
-        stagehandOptions: browser_1.schemas.anyObject.optional(),
+        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.
@@ -68,11 +74,11 @@ class StagehandCrawler extends browser_1.BrowserCrawler {
      * @param options - Crawler configuration options
      */
     constructor(options = {}) {
-        const parsedOptions = (0, browser_1.parseArgument)(options, StagehandCrawler.optionsSchema, 'StagehandCrawlerOptions');
-        const { stagehandOptions, launchContext, headless, configuration, contextPipelineBuilder, ...browserCrawlerOptions } = parsedOptions;
+        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, browser_1.assertBrowserPoolNotConfigured)(new.target.name, {
+            (0, internal_1.assertBrowserPoolNotConfigured)(new.target.name, {
                 launchContext: options.launchContext,
                 stagehandOptions: options.stagehandOptions,
                 headless: options.headless,
@@ -80,7 +86,6 @@ class StagehandCrawler extends browser_1.BrowserCrawler {
         }
         super({
             ...browserCrawlerOptions,
-            launchContext,
             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.
@@ -98,11 +103,11 @@ class StagehandCrawler extends browser_1.BrowserCrawler {
                     headless,
                     configuration,
                 })),
-            contextPipelineBuilder: contextPipelineBuilder ?? (() => this.buildContextPipeline()),
+            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
@@ -113,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);
         }
@@ -122,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?');
         }

package/internals/stagehand-launcher.d.ts

@@ -14,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.
@@ -32,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.
@@ -57,13 +38,10 @@ export interface StagehandLaunchContext extends BrowserLaunchContext<LaunchOptio
 export declare class StagehandLauncher extends BrowserLauncher<StagehandPlugin> {
     #private;
     readonly configuration: Configuration;
+    /**
+     * @internal
+     */
     protected static optionsShape: {
-// @ts-ignore optional peer dependency or compatibility with es2022
-        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
-        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
-        stagehandOptions: z.ZodOptional<z.ZodCustom<import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary, import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary>>;
         proxyUrl: z.ZodOptional<z.ZodURL>;
         useChrome: z.ZodOptional<z.ZodBoolean>;
         useIncognitoPages: z.ZodOptional<z.ZodBoolean>;
@@ -73,14 +51,15 @@ export declare class StagehandLauncher extends BrowserLauncher<StagehandPlugin>
 // @ts-ignore optional peer dependency or compatibility with es2022
         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>;
-    };
-    protected static optionsSchema: z.ZodObject<{
 // @ts-ignore optional peer dependency or compatibility with es2022
         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
         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
         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>;
@@ -90,11 +69,19 @@ export declare class StagehandLauncher extends BrowserLauncher<StagehandPlugin>
 // @ts-ignore optional peer dependency or compatibility with es2022
         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
+        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
+        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
+        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.
      */

package/internals/stagehand-launcher.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StagehandLauncher = void 0;
 const browser_1 = require("@crawlee/browser");
+const internal_1 = require("@crawlee/utils/internal");
 const zod_1 = require("zod");
 const stagehand_plugin_1 = require("./stagehand-plugin");
 /**
@@ -12,20 +13,27 @@ const stagehand_plugin_1 = require("./stagehand-plugin");
  */
 class StagehandLauncher extends browser_1.BrowserLauncher {
     configuration;
+    /**
+     * @internal
+     */
     static optionsShape = {
         ...browser_1.BrowserLauncher.optionsShape,
         // Passthrough schemas — the launcher module object must keep its prototype through parsing.
-        launcher: browser_1.schemas.anyObject.optional(),
-        launchContextOptions: browser_1.schemas.anyObject.optional(),
-        stagehandOptions: browser_1.schemas.anyObject.optional(),
+        launcher: internal_1.schemas.anyObject.optional(),
+        launchContextOptions: internal_1.schemas.anyObject.optional(),
+        stagehandOptions: internal_1.schemas.anyObject.optional(),
     };
+    /** @internal */
     static optionsSchema = zod_1.z.strictObject(StagehandLauncher.optionsShape);
     #stagehandOptions;
     /**
      * All StagehandLauncher parameters are passed via the launchContext object.
      */
-    constructor(launchContext = {}, configuration = browser_1.Configuration.getGlobalConfiguration()) {
-        const parsedContext = (0, browser_1.parseArgument)(launchContext, StagehandLauncher.optionsSchema, 'StagehandLaunchContext');
+    constructor(
+    // `stagehandOptions` is not part of the public `StagehandLaunchContext`: it is how
+    // `stagehandBrowserPool()` threads the crawler's resolved Stagehand options through the launcher.
+    launchContext = {}, configuration = browser_1.Configuration.getGlobalConfiguration()) {
+        const parsedContext = (0, internal_1.parseArgument)(launchContext, StagehandLauncher.optionsSchema, 'StagehandLaunchContext');
         const { launcher = browser_1.BrowserLauncher.requireLauncherOrThrow('playwright', 'apify/actor-node-playwright-*').chromium, stagehandOptions = {}, } = parsedContext;
         const { launchOptions = {}, ...rest } = parsedContext;
         // Call super first before initializing properties

package/internals/stagehand-plugin.d.ts

@@ -1,4 +1,3 @@
-import type { Stagehand } from '@browserbasehq/stagehand';
 import type { BrowserController, BrowserPluginOptions, LaunchContext } from '@crawlee/browser-pool';
 import { BrowserPlugin } from '@crawlee/browser-pool';
 // @ts-ignore optional peer dependency or compatibility with es2022
@@ -28,16 +27,11 @@ export interface StagehandPluginOptions extends BrowserPluginOptions<LaunchOptio
  */
 export declare class StagehandPlugin extends BrowserPlugin<BrowserType, LaunchOptions, PlaywrightBrowser> {
     #private;
-    readonly stagehandOptions: StagehandOptions;
     constructor(library: BrowserType, options?: StagehandPluginOptions);
     /**
      * Launches a browser using Stagehand and connects Playwright to it via CDP.
      */
     protected _launch(launchContext: LaunchContext<BrowserType>): Promise<PlaywrightBrowser>;
-    /**
-     * Cleans up Stagehand instance when browser disconnects.
-     */
-    private cleanupStagehand;
     /**
      * Creates a controller for the Stagehand browser.
      */
@@ -50,12 +44,4 @@ export declare class StagehandPlugin extends BrowserPlugin<BrowserType, LaunchOp
      * Determines if this is a Chromium-based browser.
      */
     protected isChromiumBasedBrowser(): boolean;
-    /**
-     * Augments launch errors with helpful context.
-     */
-    private augmentLaunchError;
-    /**
-     * Gets the Stagehand instance for a given browser.
-     */
-    getStagehandForBrowser(browser: PlaywrightBrowser): Stagehand | undefined;
 }

package/internals/stagehand-plugin.js

@@ -21,11 +21,11 @@ const stagehand_controller_1 = require("./stagehand-controller");
  * - Some fingerprinting options may not be fully applied (Stagehand controls browser launch)
  */
 class StagehandPlugin extends browser_pool_1.BrowserPlugin {
-    stagehandOptions;
+    #stagehandOptions;
     #stagehandInstances = new WeakMap();
     constructor(library, options = {}) {
         super(library, options);
-        this.stagehandOptions = options.stagehandOptions ?? {};
+        this.#stagehandOptions = options.stagehandOptions ?? {};
     }
     /**
      * Launches a browser using Stagehand and connects Playwright to it via CDP.
@@ -34,26 +34,26 @@ class StagehandPlugin extends browser_pool_1.BrowserPlugin {
         const { launchOptions = {}, proxyUrl } = launchContext;
         // Import Stagehand dynamically to avoid peer dependency issues
         const { Stagehand } = await import('@browserbasehq/stagehand');
-        const isLocal = this.stagehandOptions.env === 'LOCAL' || !this.stagehandOptions.env;
+        const isLocal = this.#stagehandOptions.env === 'LOCAL' || !this.#stagehandOptions.env;
         // Use anonymizeProxy to handle proxy authentication transparently
         const [anonymizedProxyUrl, closeAnonymizedProxy] = await (0, browser_pool_1.anonymizeProxySugar)(proxyUrl, undefined, undefined, {
             ignoreProxyCertificate: launchContext.ignoreProxyCertificate,
         });
         // Build model configuration
         // For LOCAL env, we merge apiKey into the model config since Stagehand expects it there
-        let modelConfig = this.stagehandOptions.model;
-        if (isLocal && this.stagehandOptions.apiKey) {
+        let modelConfig = this.#stagehandOptions.model;
+        if (isLocal && this.#stagehandOptions.apiKey) {
             const modelName = typeof modelConfig === 'string' ? modelConfig : modelConfig?.modelName;
             modelConfig = {
                 ...(typeof modelConfig === 'object' ? modelConfig : {}),
                 ...(modelName ? { modelName } : {}),
-                apiKey: this.stagehandOptions.apiKey,
+                apiKey: this.#stagehandOptions.apiKey,
             };
         }
         // Build Stagehand configuration by spreading our options and adding launch options
         const stagehandConfig = {
-            ...this.stagehandOptions,
-            env: this.stagehandOptions.env ?? 'LOCAL',
+            ...this.#stagehandOptions,
+            env: this.#stagehandOptions.env ?? 'LOCAL',
             model: modelConfig,
             localBrowserLaunchOptions: isLocal
                 ? {
@@ -79,7 +79,7 @@ class StagehandPlugin extends browser_pool_1.BrowserPlugin {
             this.#stagehandInstances.set(browser, stagehand);
             // Handle browser disconnection - cleanup both Stagehand and anonymized proxy
             browser.on('disconnected', async () => {
-                await this.cleanupStagehand(browser);
+                await this.#cleanupStagehand(browser);
                 await closeAnonymizedProxy();
             });
             return browser;
@@ -88,7 +88,7 @@ class StagehandPlugin extends browser_pool_1.BrowserPlugin {
             // Clean up on failure
             await stagehand.close().catch(() => { });
             await closeAnonymizedProxy();
-            const augmentedError = this.augmentLaunchError(error, launchContext);
+            const augmentedError = this.#augmentLaunchError(error, launchContext);
             core_1.serviceLocator.getLogger().error('Stagehand browser launch failed', { message: augmentedError.message });
             throw augmentedError;
         }
@@ -96,7 +96,7 @@ class StagehandPlugin extends browser_pool_1.BrowserPlugin {
     /**
      * Cleans up Stagehand instance when browser disconnects.
      */
-    async cleanupStagehand(browser) {
+    async #cleanupStagehand(browser) {
         const stagehand = this.#stagehandInstances.get(browser);
         if (stagehand) {
             try {
@@ -139,9 +139,9 @@ class StagehandPlugin extends browser_pool_1.BrowserPlugin {
     /**
      * Augments launch errors with helpful context.
      */
-    augmentLaunchError(error, launchContext) {
+    #augmentLaunchError(error, launchContext) {
         const message = error instanceof Error ? error.message : String(error);
-        const model = this.stagehandOptions.model;
+        const model = this.#stagehandOptions.model;
         let helpText = '';
         if (typeof model === 'string') {
             const modelStr = model.toLowerCase();
@@ -159,11 +159,5 @@ class StagehandPlugin extends browser_pool_1.BrowserPlugin {
             `Executable path: ${launchContext.launchOptions?.executablePath ?? 'default'}\n` +
             `Model: ${model}${helpText}`, { cause: error });
     }
-    /**
-     * Gets the Stagehand instance for a given browser.
-     */
-    getStagehandForBrowser(browser) {
-        return this.#stagehandInstances.get(browser);
-    }
 }
 exports.StagehandPlugin = StagehandPlugin;

package/package.json

@@ -1,9 +1,9 @@
 {
     "name": "@crawlee/stagehand",
-    "version": "4.0.0-rc.0",
+    "version": "4.0.0-rc.1",
     "description": "AI-powered web crawling with Stagehand integration for Crawlee - enables natural language browser automation with act(), extract(), and observe() methods.",
     "engines": {
-        "node": ">=22.0.0"
+        "node": ">=22.13.0"
     },
     "main": "./index.js",
     "module": "./index.mjs",
@@ -56,14 +56,13 @@
         "access": "public"
     },
     "dependencies": {
-        "@apify/timeout": "^0.4.4",
-        "@crawlee/browser": "4.0.0-rc.0",
-        "@crawlee/browser-pool": "4.0.0-rc.0",
-        "@crawlee/core": "4.0.0-rc.0",
-        "@crawlee/types": "4.0.0-rc.0",
-        "@crawlee/utils": "4.0.0-rc.0",
+        "@crawlee/browser": "4.0.0-rc.1",
+        "@crawlee/browser-pool": "4.0.0-rc.1",
+        "@crawlee/core": "4.0.0-rc.1",
+        "@crawlee/types": "4.0.0-rc.1",
+        "@crawlee/utils": "4.0.0-rc.1",
         "tslib": "^2.8.1",
-        "zod": "^4.4.3"
+        "zod": "^4.5.4"
     },
     "peerDependencies": {
         "@browserbasehq/stagehand": "^3.0.0",
@@ -88,5 +87,5 @@
             }
         }
     },
-    "gitHead": "79ab33dacdacb83e0197e6516d145f3aceef80c7"
+    "gitHead": "f354ca5e943bed1a5c657a1fce1974c053f9fff0"
 }