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

package/internals/stagehand-launcher.js

@@ -1,9 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StagehandLauncher = void 0;
-const tslib_1 = require("tslib");
 const browser_1 = require("@crawlee/browser");
-const ow_1 = tslib_1.__importDefault(require("ow"));
+const internal_1 = require("@crawlee/utils/internal");
+const zod_1 = require("zod");
 const stagehand_plugin_1 = require("./stagehand-plugin");
 /**
  * StagehandLauncher is based on BrowserLauncher and creates StagehandPlugin instances.
@@ -13,31 +13,40 @@ const stagehand_plugin_1 = require("./stagehand-plugin");
  */
 class StagehandLauncher extends browser_1.BrowserLauncher {
     configuration;
+    /**
+     * @internal
+     */
     static optionsShape = {
         ...browser_1.BrowserLauncher.optionsShape,
-        launcher: ow_1.default.optional.object,
-        launchContextOptions: ow_1.default.optional.object,
-        stagehandOptions: ow_1.default.optional.object,
+        // Passthrough schemas — the launcher module object must keep its prototype through parsing.
+        launcher: internal_1.schemas.anyObject.optional(),
+        launchContextOptions: internal_1.schemas.anyObject.optional(),
+        stagehandOptions: internal_1.schemas.anyObject.optional(),
     };
-    stagehandOptions;
+    /** @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()) {
-        (0, ow_1.default)(launchContext, 'StagehandLaunchContext', ow_1.default.object.exactShape(StagehandLauncher.optionsShape));
-        const { launcher = browser_1.BrowserLauncher.requireLauncherOrThrow('playwright', 'apify/actor-node-playwright-*').chromium, stagehandOptions = {}, } = launchContext;
-        const { launchOptions = {}, ...rest } = launchContext;
+    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
         super({
             ...rest,
             launchOptions: {
                 ...launchOptions,
-                executablePath: getDefaultExecutablePath(launchContext, configuration),
+                executablePath: getDefaultExecutablePath(parsedContext, configuration),
             },
             launcher,
         }, configuration);
         this.configuration = configuration;
-        this.stagehandOptions = {
+        this.#stagehandOptions = {
             env: 'LOCAL',
             model: 'openai/gpt-4.1-mini',
             ...stagehandOptions,
@@ -52,7 +61,7 @@ class StagehandLauncher extends browser_1.BrowserLauncher {
             ...this.otherLaunchContextProps,
             proxyUrl: this.proxyUrl,
             launchOptions: this.createLaunchOptions(),
-            stagehandOptions: this.stagehandOptions, // Set AFTER to override any unresolved options
+            stagehandOptions: this.#stagehandOptions, // Set AFTER to override any unresolved options
         });
     }
 }

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
@@ -27,17 +26,12 @@ export interface StagehandPluginOptions extends BrowserPluginOptions<LaunchOptio
  * - Some fingerprinting options may not be fully applied (Stagehand controls browser launch)
  */
 export declare class StagehandPlugin extends BrowserPlugin<BrowserType, LaunchOptions, PlaywrightBrowser> {
-    readonly stagehandOptions: StagehandOptions;
-    private readonly stagehandInstances;
+    #private;
     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.
      */
@@ -45,17 +39,9 @@ export declare class StagehandPlugin extends BrowserPlugin<BrowserType, LaunchOp
     /**
      * Adds proxy configuration to launch options.
      */
-    protected _addProxyToLaunchOptions(launchContext: LaunchContext<BrowserType>): Promise<void>;
+    protected addProxyToLaunchOptions(launchContext: LaunchContext<BrowserType>): Promise<void>;
     /**
      * 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;
+    protected isChromiumBasedBrowser(): boolean;
 }

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;
-    stagehandInstances = new WeakMap();
+    #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
                 ? {
@@ -76,10 +76,10 @@ class StagehandPlugin extends browser_pool_1.BrowserPlugin {
             }
             const browser = await playwright_1.chromium.connectOverCDP(cdpUrl);
             // Store the Stagehand instance for AI operations
-            this.stagehandInstances.set(browser, stagehand);
+            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,8 +96,8 @@ class StagehandPlugin extends browser_pool_1.BrowserPlugin {
     /**
      * Cleans up Stagehand instance when browser disconnects.
      */
-    async _cleanupStagehand(browser) {
-        const stagehand = this.stagehandInstances.get(browser);
+    async #cleanupStagehand(browser) {
+        const stagehand = this.#stagehandInstances.get(browser);
         if (stagehand) {
             try {
                 await stagehand.close();
@@ -105,19 +105,19 @@ class StagehandPlugin extends browser_pool_1.BrowserPlugin {
             catch {
                 // Ignore cleanup errors
             }
-            this.stagehandInstances.delete(browser);
+            this.#stagehandInstances.delete(browser);
         }
     }
     /**
      * Creates a controller for the Stagehand browser.
      */
     createController() {
-        return new stagehand_controller_1.StagehandController(this, this.stagehandInstances);
+        return new stagehand_controller_1.StagehandController(this, this.#stagehandInstances);
     }
     /**
      * Adds proxy configuration to launch options.
      */
-    async _addProxyToLaunchOptions(launchContext) {
+    async addProxyToLaunchOptions(launchContext) {
         launchContext.launchOptions ??= {};
         const { launchOptions, proxyUrl } = launchContext;
         if (proxyUrl) {
@@ -132,16 +132,16 @@ class StagehandPlugin extends browser_pool_1.BrowserPlugin {
     /**
      * Determines if this is a Chromium-based browser.
      */
-    _isChromiumBasedBrowser() {
+    isChromiumBasedBrowser() {
         const name = this.library?.name?.();
         return name === 'chromium';
     }
     /**
      * 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-beta.99",
+    "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,19 +56,17 @@
         "access": "public"
     },
     "dependencies": {
-        "@apify/timeout": "^0.4.4",
-        "@crawlee/browser": "4.0.0-beta.99",
-        "@crawlee/browser-pool": "4.0.0-beta.99",
-        "@crawlee/core": "4.0.0-beta.99",
-        "@crawlee/types": "4.0.0-beta.99",
-        "@crawlee/utils": "4.0.0-beta.99",
-        "ow": "^2.0.0",
-        "tslib": "^2.8.1"
+        "@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.5.4"
     },
     "peerDependencies": {
         "@browserbasehq/stagehand": "^3.0.0",
-        "playwright": "*",
-        "zod": "^3.0.0 || ^4.0.0"
+        "playwright": "*"
     },
     "peerDependenciesMeta": {
         "@browserbasehq/stagehand": {
@@ -76,15 +74,11 @@
         },
         "playwright": {
             "optional": true
-        },
-        "zod": {
-            "optional": true
         }
     },
     "devDependencies": {
         "@browserbasehq/stagehand": "3.0.7",
-        "playwright": "^1.60.0",
-        "zod": "^4.3.5"
+        "playwright": "^1.60.0"
     },
     "lerna": {
         "command": {
@@ -93,5 +87,5 @@
             }
         }
     },
-    "gitHead": "ad2748380941842bb10cff100f4b4caad92049e3"
+    "gitHead": "f354ca5e943bed1a5c657a1fce1974c053f9fff0"
 }