Add support for PageHandle in AnyPage

Author: monadoid

packages/core/lib/v3/types/public/agent.ts

@@ -1,10 +1,7 @@
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { ToolSet } from "ai";
 import { LogLine } from "./logs";
-import { Page as PlaywrightPage } from "playwright-core";
-import { Page as PuppeteerPage } from "puppeteer-core";
-import { Page as PatchrightPage } from "patchright-core";
-import { Page } from "../../understudy/page";
+import { AnyPage } from "./page";
 
 export interface AgentAction {
   type: string;
@@ -37,7 +34,7 @@ export interface AgentResult {
 export interface AgentExecuteOptions {
   instruction: string;
   maxSteps?: number;
-  page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
+  page?: AnyPage;
   highlightCursor?: boolean;
 }
 export type AgentType = "openai" | "anthropic" | "google";

packages/core/lib/v3/types/public/methods.ts

@@ -1,16 +1,13 @@
-import { Page as PatchrightPage } from "patchright-core";
-import { Page as PlaywrightPage } from "playwright-core";
-import { Page as PuppeteerPage } from "puppeteer-core";
 import { z } from "zod";
 import type { InferStagehandSchema, StagehandZodSchema } from "../../zodCompat";
-import { Page } from "../../understudy/page";
 import { ModelConfiguration } from "../public/model";
+import { AnyPage } from "./page";
 
 export interface ActOptions {
   model?: ModelConfiguration;
   variables?: Record<string, string>;
   timeout?: number;
-  page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
+  page?: AnyPage;
 }
 
 export interface ActResult {
@@ -41,7 +38,7 @@ export interface ExtractOptions {
   model?: ModelConfiguration;
   timeout?: number;
   selector?: string;
-  page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
+  page?: AnyPage;
 }
 
 export const defaultExtractSchema = z.object({
@@ -56,7 +53,7 @@ export interface ObserveOptions {
   model?: ModelConfiguration;
   timeout?: number;
   selector?: string;
-  page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
+  page?: AnyPage;
 }
 
 export enum V3FunctionName {

packages/core/lib/v3/types/public/page.ts

@@ -1,10 +1,27 @@
+import { z } from "zod";
 import { Page } from "../../understudy/page";
 import { Page as PlaywrightPage } from "playwright-core";
 import { Page as PatchrightPage } from "patchright-core";
 import { Page as PuppeteerPage } from "puppeteer-core";
 
 export type { PlaywrightPage, PatchrightPage, PuppeteerPage, Page };
-export type AnyPage = PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
+
+export const pageHandleSchema = z.object({
+  pageId: z.string().min(1),
+  targetId: z.string().min(1),
+});
+
+export interface PageHandle {
+  pageId: string;
+  targetId: string;
+}
+
+export type AnyPage =
+  | PlaywrightPage
+  | PuppeteerPage
+  | PatchrightPage
+  | Page
+  | PageHandle;
 
 export { ConsoleMessage } from "../../understudy/consoleMessage";
 export type { ConsoleListener } from "../../understudy/consoleMessage";

packages/core/lib/v3/understudy/context.ts

@@ -229,6 +229,10 @@ export class V3Context {
     return targetId ? this.pagesByTarget.get(targetId) : undefined;
   }
 
+  resolvePageByTargetId(targetId: string): Page | undefined {
+    return this.pagesByTarget.get(targetId);
+  }
+
   /**
    * Serialize the full frame tree for a given top-level main frame id.
    */

packages/core/lib/v3/v3.ts

@@ -56,6 +56,7 @@ import {
   LocalBrowserLaunchOptions,
   V3Options,
   AnyPage,
+  PageHandle,
   PatchrightPage,
   PlaywrightPage,
   PuppeteerPage,
@@ -1389,6 +1390,15 @@ export class V3 {
     );
   }
 
+  private hasTargetId(p: unknown): p is PageHandle {
+    return (
+      typeof p === "object" &&
+      p !== null &&
+      typeof (p as PageHandle).pageId === "string" &&
+      typeof (p as PageHandle).targetId === "string"
+    );
+  }
+
   private isPlaywrightPage(p: unknown): p is PlaywrightPage {
     return (
       typeof p === "object" &&
@@ -1413,6 +1423,20 @@ export class V3 {
     );
   }
 
+  private resolvePageFromHandle(handle: PageHandle): Page {
+    const ctx = this.ctx;
+    if (!ctx) {
+      throw new StagehandNotInitializedError("resolvePage()");
+    }
+    const page = ctx.resolvePageByTargetId(handle.targetId);
+    if (!page) {
+      throw new StagehandInitError(
+        `Failed to resolve V3 Page from handle targetId=${handle.targetId}.`,
+      );
+    }
+    return page;
+  }
+
   /** Resolve an external page reference or fall back to the active V3 page. */
   private async resolvePage(page?: AnyPage): Promise<Page> {
     if (page) {
@@ -1426,6 +1450,9 @@ export class V3 {
   }
 
   private async normalizeToV3Page(input: AnyPage): Promise<Page> {
+    if (this.hasTargetId(input)) {
+      return this.resolvePageFromHandle(input);
+    }
     if (input instanceof (await import("./understudy/page")).Page) {
       return input as Page;
     }