@crawlee/stagehand 4.0.0-beta.198 → 4.0.0-beta.200

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

@@ -25,7 +25,6 @@ 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;
@@ -37,7 +36,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;
@@ -46,7 +44,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;
@@ -78,13 +75,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;
@@ -128,13 +123,11 @@ 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 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 toughCookieToBrowserPoolCookie = mod.toughCookieToBrowserPoolCookie;
 export const updateEnqueueLinksPatternCache = mod.updateEnqueueLinksPatternCache;
 export const urlPatternSchema = mod.urlPatternSchema;

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,7 +308,8 @@ 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
      */
@@ -366,7 +362,6 @@ export declare class StagehandCrawler<ContextExtension = Dictionary<never>, Exte
         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>>;
@@ -374,6 +369,7 @@ 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>;
     };
@@ -427,7 +423,6 @@ export declare class StagehandCrawler<ContextExtension = Dictionary<never>, Exte
         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>>;
@@ -435,6 +430,7 @@ 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>;
     }, z.core.$strict>;
@@ -444,7 +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

package/internals/stagehand-crawler.js

@@ -62,6 +62,7 @@ class StagehandCrawler extends browser_1.BrowserCrawler {
      */
     static optionsShape = {
         ...browser_1.BrowserCrawler.optionsShape,
+        launchContext: internal_1.schemas.anyObject.default(() => ({})),
         stagehandOptions: internal_1.schemas.anyObject.optional(),
         headless: zod_1.z.boolean().optional(),
     };
@@ -74,10 +75,10 @@ class StagehandCrawler extends browser_1.BrowserCrawler {
      */
     constructor(options = {}) {
         const parsedOptions = (0, internal_1.parseArgument)(options, StagehandCrawler.optionsSchema, 'StagehandCrawlerOptions');
-        const { stagehandOptions, launchContext, headless, configuration, contextPipelineBuilder, ...browserCrawlerOptions } = parsedOptions;
+        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,
@@ -85,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.
@@ -103,11 +103,11 @@ class StagehandCrawler extends browser_1.BrowserCrawler {
                     headless,
                     configuration,
                 })),
-            contextPipelineBuilder: contextPipelineBuilder ?? (() => this.buildContextPipeline()),
+            contextPipelineBuilder: () => this.#buildContextPipeline(),
         });
     }
-    buildContextPipeline() {
-        return super.buildContextPipeline().compose(this.setUpStagehand.bind(this));
+    #buildContextPipeline() {
+        return this.buildContextPipeline().compose(this.setUpStagehand.bind(this));
     }
     /**
      * Resolves the {@link StagehandController} that owns the given page, or

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.
@@ -98,7 +79,9 @@ export declare class StagehandLauncher extends BrowserLauncher<StagehandPlugin>
     /**
      * 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

@@ -29,7 +29,10 @@ class StagehandLauncher extends browser_1.BrowserLauncher {
     /**
      * All StagehandLauncher parameters are passed via the launchContext object.
      */
-    constructor(launchContext = {}, configuration = browser_1.Configuration.getGlobalConfiguration()) {
+    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;

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,7 +27,6 @@ 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.
@@ -54,8 +52,4 @@ export declare class StagehandPlugin extends BrowserPlugin<BrowserType, LaunchOp
      * 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
                 ? {
@@ -141,7 +141,7 @@ class StagehandPlugin extends browser_pool_1.BrowserPlugin {
      */
     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,6 +1,6 @@
 {
     "name": "@crawlee/stagehand",
-    "version": "4.0.0-beta.198",
+    "version": "4.0.0-beta.200",
     "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"
@@ -57,11 +57,11 @@
     },
     "dependencies": {
         "@apify/timeout": "^1.0.1",
-        "@crawlee/browser": "4.0.0-beta.198",
-        "@crawlee/browser-pool": "4.0.0-beta.198",
-        "@crawlee/core": "4.0.0-beta.198",
-        "@crawlee/types": "4.0.0-beta.198",
-        "@crawlee/utils": "4.0.0-beta.198",
+        "@crawlee/browser": "4.0.0-beta.200",
+        "@crawlee/browser-pool": "4.0.0-beta.200",
+        "@crawlee/core": "4.0.0-beta.200",
+        "@crawlee/types": "4.0.0-beta.200",
+        "@crawlee/utils": "4.0.0-beta.200",
         "tslib": "^2.8.1",
         "zod": "^4.5.4"
     },
@@ -88,5 +88,5 @@
             }
         }
     },
-    "gitHead": "889cfffcc20b2803f0d95d7cb006ad1e7f672452"
+    "gitHead": "471663956b78edb995e824dd906776a28cc04535"
 }