@crawlee/stagehand 3.17.1-beta.55 → 3.17.1-beta.56

package/internals/stagehand-controller.d.ts

@@ -30,6 +30,20 @@ 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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.StagehandController = void 0;
 const tslib_1 = require("tslib");
 const browser_pool_1 = require("@crawlee/browser-pool");
+const utils_1 = require("@crawlee/utils");
 const log_1 = tslib_1.__importDefault(require("@apify/log"));
 /**
  * StagehandController manages the lifecycle of a Stagehand-controlled browser for Crawlee's BrowserPool.
@@ -63,6 +64,13 @@ class StagehandController extends browser_pool_1.BrowserController {
             page.once('close', () => {
                 this.activePages--;
             });
+            try {
+                await this.waitForStagehandToRegisterPage(page);
+            }
+            catch (error) {
+                await page.close().catch(() => { });
+                throw error;
+            }
             return page;
         }
         catch (error) {
@@ -71,6 +79,42 @@ class StagehandController extends browser_pool_1.BrowserController {
             });
         }
     }
+    /**
+     * 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.
+     */
+    async waitForStagehandToRegisterPage(page, timeoutMs = 10000) {
+        const stagehand = this.getStagehand();
+        const mainFrameId = await this.getMainFrameId(page);
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (stagehand.context.resolvePageByMainFrameId(mainFrameId)) {
+                return;
+            }
+            await (0, utils_1.sleep)(25);
+        }
+        // Stagehand skips registration entirely when it cannot install its helper script into the page's CDP
+        // session, so this is not always just a slow attach - it can never resolve.
+        throw new Error(`Stagehand did not register the page within ${timeoutMs}ms`);
+    }
+    /**
+     * Reads the page's main frame id, which is the key Stagehand resolves pages by.
+     */
+    async getMainFrameId(page) {
+        const cdpSession = await page.context().newCDPSession(page);
+        try {
+            const { frameTree } = await cdpSession.send('Page.getFrameTree');
+            return frameTree.frame.id;
+        }
+        finally {
+            await cdpSession.detach().catch(() => { });
+        }
+    }
     /**
      * Normalizes proxy options for Playwright.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@crawlee/stagehand",
-    "version": "3.17.1-beta.55",
+    "version": "3.17.1-beta.56",
     "description": "AI-powered web crawling with Stagehand integration for Crawlee - enables natural language browser automation with act(), extract(), and observe() methods.",
     "engines": {
         "node": ">=16.0.0"
@@ -58,11 +58,11 @@
     "dependencies": {
         "@apify/log": "^2.4.0",
         "@apify/timeout": "^0.3.1",
-        "@crawlee/browser": "3.17.1-beta.55",
-        "@crawlee/browser-pool": "3.17.1-beta.55",
-        "@crawlee/core": "3.17.1-beta.55",
-        "@crawlee/types": "3.17.1-beta.55",
-        "@crawlee/utils": "3.17.1-beta.55",
+        "@crawlee/browser": "3.17.1-beta.56",
+        "@crawlee/browser-pool": "3.17.1-beta.56",
+        "@crawlee/core": "3.17.1-beta.56",
+        "@crawlee/types": "3.17.1-beta.56",
+        "@crawlee/utils": "3.17.1-beta.56",
         "ow": "^0.28.1",
         "tslib": "^2.4.0"
     },
@@ -94,5 +94,5 @@
             }
         }
     },
-    "gitHead": "93d29e305f01ca6ca9bb79264a5ca553b19766ef"
+    "gitHead": "aaf56f1d6905d06fe18a93bbd2d7695a581d57cf"
 }