stagehand 4.3.0a0.dev1624__tar.gz → 4.3.0a0.dev1626__tar.gz

{stagehand-4.3.0a0.dev1624 → stagehand-4.3.0a0.dev1626}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stagehand
-Version: 4.3.0a0.dev1624
+Version: 4.3.0a0.dev1626
 Summary: Browserbase's SDK for building browser agents
 Keywords: ai,agent,ai-agent,browser,browser-agent,browser-automation,computer-use,headless,playwright,cdp,llm,automation,web-scraping,testing
 Author: Browserbase

{stagehand-4.3.0a0.dev1624 → stagehand-4.3.0a0.dev1626}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stagehand"
-version = "4.3.0a0.dev1624"
+version = "4.3.0a0.dev1626"
 description = "Browserbase's SDK for building browser agents"
 readme = "README.md"
 requires-python = ">=3.11"

{stagehand-4.3.0a0.dev1624 → stagehand-4.3.0a0.dev1626}/src/stagehand/_extension/service-worker.js

@@ -7363,7 +7363,7 @@ function isRecord$1(value) {
 }
 var package_default$1 = {
 	name: "@browserbasehq/stagehand-protocol",
-	version: "3.0.0-alpha-77170ed9f8252581458360ab511c55a4be31fb44",
+	version: "3.0.0-alpha-901eb276429702cddd4bfe3a3656946f3ebc166a",
 	"private": true,
 	type: "module",
 	exports: {
@@ -8553,6 +8553,13 @@ var PageWaitForLoadStateParamsSchema = PageIdParamsSchema.extend({
 	timeout: number$1().int().nonnegative().optional()
 }).meta({ id: "PageWaitForLoadStateParams" });
 var PageWaitForTimeoutParamsSchema = PageIdParamsSchema.extend({ ms: number$1().int().nonnegative() }).meta({ id: "PageWaitForTimeoutParams" });
+var PageWaitForFunctionParamsSchema = PageIdParamsSchema.extend({
+	expression: string(),
+	options: strictObject({
+		polling: union([literal("raf"), number$1().positive().max(2147483647)]).optional(),
+		timeout: number$1().int().nonnegative().optional()
+	}).meta({ id: "PageWaitForFunctionOptions" }).optional()
+}).meta({ id: "PageWaitForFunctionParams" });
 var PageWaitForSelectorParamsSchema = PageIdParamsSchema.extend({
 	selector: string().min(1),
 	options: strictObject({
@@ -8626,6 +8633,7 @@ var PageEvaluateResultSchema = strictObject({ value: json$1() }).meta({ id: "Pag
 var PageScreenshotResultSchema = strictObject({ data: base64().meta({ format: "byte" }) }).meta({ id: "PageScreenshotResult" });
 var PagePDFResultSchema = strictObject({ data: base64().meta({ format: "byte" }) }).meta({ id: "PagePDFResult" });
 var PageWaitForSelectorResultSchema = strictObject({ matched: boolean() }).meta({ id: "PageWaitForSelectorResult" });
+var PageWaitForFunctionResultSchema = strictObject({ value: json$1() }).meta({ id: "PageWaitForFunctionResult" });
 var LocatorClickResultSchema = strictObject({ clicked: literal(true) }).meta({ id: "LocatorClickResult" });
 var LocatorFillResultSchema = strictObject({ filled: literal(true) }).meta({ id: "LocatorFillResult" });
 var LocatorHoverResultSchema = strictObject({ hovered: literal(true) }).meta({ id: "LocatorHoverResult" });
@@ -8940,6 +8948,12 @@ var StagehandMethods = {
 		params: PageWaitForSelectorParamsSchema,
 		result: PageWaitForSelectorResultSchema
 	},
+	pageWaitForFunction: {
+		name: "page.wait_for_function",
+		params: PageWaitForFunctionParamsSchema,
+		result: PageWaitForFunctionResultSchema,
+		resultWire: { opaqueKeys: ["value"] }
+	},
 	pageWebMCPTools: {
 		name: "page.webmcp_tools",
 		params: PageWebMCPToolsParamsSchema,
@@ -12001,9 +12015,18 @@ var Locator$1 = class Locator$1 {
 };
 //#endregion
 //#region ../sdk-ts/src/pageScripts.ts
-function normalizeEvaluationExpression(expression, arg) {
+function normalizeEvaluationExpression(expression, arg, caller = "page.evaluate") {
 	if (typeof expression === "string") return expression;
-	return `(${expression.toString()})(${serializeArgument(arg, "page.evaluate")})`;
+	return `(${expression.toString()})(${serializeArgument(arg, caller)})`;
+}
+function normalizeFunctionWaitExpression(expression, arg, caller = "page.waitForFunction") {
+	if (typeof expression === "function") return `() => (${expression.toString()})(${parsedArgument(arg, caller)})`;
+	if (arg === void 0) return expression;
+	return `((value) => typeof value === "function" ? () => value(${parsedArgument(arg, caller)}) : value)((${expression}))`;
+}
+function parsedArgument(arg, caller) {
+	if (arg === void 0) return "undefined";
+	return `JSON.parse(${JSON.stringify(serializeArgument(arg, caller))})`;
 }
 async function normalizeInitScriptSource$1(script, arg, caller = "page.addInitScript") {
 	if (typeof script === "function") return `(${script.toString()})(${serializeArgument(arg, caller)})`;
@@ -12026,9 +12049,8 @@ async function normalizeInitScriptSource$1(script, arg, caller = "page.addInitSc
 }
 function serializeArgument(arg, caller) {
 	if (arg === void 0) return "undefined";
-	const parsed = json$1().safeParse(arg);
-	if (!parsed.success) throw new TypeError(`${caller}: 'arg' must be JSON-serializable.`);
-	const serialized = JSON.stringify(parsed.data);
+	if (!json$1().safeParse(arg).success) throw new TypeError(`${caller}: 'arg' must be JSON-serializable.`);
+	const serialized = JSON.stringify(arg);
 	if (serialized === void 0) throw new TypeError(`${caller}: 'arg' must be JSON-serializable.`);
 	return serialized;
 }
@@ -12362,6 +12384,14 @@ var Page$1 = class {
 			...options ? { options } : {}
 		})).matched;
 	}
+	/** Poll in the page's main world until the expression returns a truthy JSON value. */
+	async waitForFunction(expression, arg, options) {
+		return (await this.rpcClient.send(StagehandMethods.pageWaitForFunction, {
+			pageId: this.pageId,
+			expression: normalizeFunctionWaitExpression(expression, arg),
+			...options ? { options } : {}
+		})).value;
+	}
 	async screenshot(options) {
 		const { path, mask, ...screenshotOptions } = options ?? {};
 		return await decodeCaptureResult((await this.rpcClient.send(StagehandMethods.pageScreenshot, {
@@ -13017,6 +13047,10 @@ function createPageController(runtime) {
 		logger.debug("page.wait_for_selector", {});
 		return runtime.pageWaitForSelector(params);
 	}
+	async function waitForFunction(params, { logger }) {
+		logger.debug("page.wait_for_function", {});
+		return runtime.pageWaitForFunction(params);
+	}
 	async function screenshot(params, { logger }) {
 		logger.debug("page.screenshot", {});
 		return runtime.pageScreenshot(params);
@@ -13083,6 +13117,7 @@ function createPageController(runtime) {
 		waitForLoadState,
 		waitForTimeout,
 		waitForSelector,
+		waitForFunction,
 		screenshot,
 		pdf,
 		snapshot,
@@ -16955,6 +16990,38 @@ async function act$1(params) {
 	};
 }
 //#endregion
+//#region understudy/browserWait.ts
+/** Browser exceptions are not transient CDP context-loss errors. */
+var BrowserWaitError = class extends Error {};
+/** Own a browser-side promise and dispose its resources, even after late installation. */
+async function browserWait(session, progress, install, phase) {
+	const dispose = (objectId) => Promise.all([progress.cleanup(() => session.send("Runtime.callFunctionOn", {
+		objectId,
+		functionDeclaration: "function() { this.dispose(); }",
+		returnByValue: true
+	})), progress.cleanup(() => session.send("Runtime.releaseObject", { objectId }))]);
+	const response = await install(async (late) => {
+		if (late.result.objectId) await dispose(late.result.objectId);
+	});
+	const objectId = response.result.objectId;
+	let completed = false;
+	try {
+		if (response.exceptionDetails || !objectId) throw new BrowserWaitError(response.exceptionDetails?.exception?.description ?? response.exceptionDetails?.text ?? "Browser wait handle was not returned");
+		const result = await progress.run(phase, () => session.send("Runtime.callFunctionOn", {
+			objectId,
+			functionDeclaration: "function() { return this.promise; }",
+			awaitPromise: true,
+			returnByValue: true
+		}));
+		if (result.exceptionDetails) throw new BrowserWaitError(result.exceptionDetails.exception?.description ?? result.exceptionDetails.text ?? "Browser wait failed");
+		completed = true;
+		return result.result.value;
+	} finally {
+		if (objectId) if (completed) progress.cleanup(() => session.send("Runtime.releaseObject", { objectId }));
+		else await dispose(objectId);
+	}
+}
+//#endregion
 //#region understudy/frame.ts
 function base64ToBytes$1(base64) {
 	const binary = globalThis.atob(base64);
@@ -17080,46 +17147,25 @@ var Frame = class {
 	}
 	/** Own a disposable browser wait, including a handle delivered after expiry. */
 	async waitInLocatorWorld(buildExpression, progress) {
-		const dispose = (objectId) => Promise.all([progress.cleanup(() => this.session.send("Runtime.callFunctionOn", {
-			objectId,
-			functionDeclaration: "function() { this.dispose(); }",
-			returnByValue: true
-		})), progress.cleanup(() => this.session.send("Runtime.releaseObject", { objectId }))]);
 		for (let attempt = 0;; attempt++) {
 			progress.throwIfStopped();
-			const response = await this.evaluateLocatorExpression(buildExpression, {
-				progress,
-				returnByValue: false,
-				awaitPromise: false,
-				onLateResult: async (late) => {
-					if (late.result.objectId) await dispose(late.result.objectId);
-				}
-			});
-			const objectId = response.result.objectId;
-			let completed = false;
+			let contextId;
 			try {
-				if (response.exceptionDetails || !objectId) throw new Error(response.exceptionDetails?.exception?.description ?? response.exceptionDetails?.text ?? "Selector wait handle was not returned");
-				let result;
-				try {
-					result = await progress.run("waiting for selector", () => this.session.send("Runtime.callFunctionOn", {
-						objectId,
-						functionDeclaration: "function() { return this.promise; }",
-						awaitPromise: true,
-						returnByValue: true
-					}));
-				} catch (error) {
-					progress.throwIfStopped();
-					const message = error instanceof Error ? error.message : String(error);
-					if (attempt !== 0 || !message.includes("Cannot find context with specified id")) throw error;
-					executionContexts.unregisterLocatorContext(this.session, response.contextId);
-					continue;
-				}
-				if (result.exceptionDetails) throw new Error(result.exceptionDetails.exception?.description ?? result.exceptionDetails.text ?? "Selector wait failed");
-				completed = true;
-				return result.result.value;
-			} finally {
-				if (objectId) if (completed) progress.cleanup(() => this.session.send("Runtime.releaseObject", { objectId }));
-				else await dispose(objectId);
+				return await browserWait(this.session, progress, async (onLateResult) => {
+					const response = await this.evaluateLocatorExpression(buildExpression, {
+						progress,
+						returnByValue: false,
+						awaitPromise: false,
+						onLateResult
+					});
+					contextId = response.contextId;
+					return response;
+				}, "waiting for selector");
+			} catch (error) {
+				progress.throwIfStopped();
+				const message = error instanceof Error ? error.message : String(error);
+				if (attempt !== 0 || contextId === void 0 || error instanceof BrowserWaitError || !message.includes("Cannot find context with specified id")) throw error;
+				executionContexts.unregisterLocatorContext(this.session, contextId);
 			}
 		}
 	}
@@ -52088,6 +52134,7 @@ var RPCRouter = class {
 			case "page.wait_for_load_state": return this.pageController.waitForLoadState(parseParams(StagehandMethods.pageWaitForLoadState, request.params), context);
 			case "page.wait_for_timeout": return this.pageController.waitForTimeout(parseParams(StagehandMethods.pageWaitForTimeout, request.params), context);
 			case "page.wait_for_selector": return this.pageController.waitForSelector(parseParams(StagehandMethods.pageWaitForSelector, request.params), context);
+			case "page.wait_for_function": return this.pageController.waitForFunction(parseParams(StagehandMethods.pageWaitForFunction, request.params), context);
 			case "page.screenshot": return this.pageController.screenshot(parseParams(StagehandMethods.pageScreenshot, request.params), context);
 			case "page.pdf": return this.pageController.pdf(parseParams(StagehandMethods.pagePDF, request.params), context);
 			case "page.snapshot": return this.pageController.snapshot(parseParams(StagehandMethods.pageSnapshot, request.params), context);
@@ -54483,7 +54530,7 @@ var WebTracerProvider = class extends BasicTracerProvider {
 };
 var package_default = {
 	name: "@browserbasehq/stagehand-extension",
-	version: "1.2.0-alpha-77170ed9f8252581458360ab511c55a4be31fb44",
+	version: "1.2.0-alpha-901eb276429702cddd4bfe3a3656946f3ebc166a",
 	"private": true,
 	type: "module",
 	scripts: {
@@ -55878,6 +55925,83 @@ async function normalizeInitScriptSource(script, arg, caller = DEFAULT_CALLER) {
 	throw new TypeError(`${caller}: provide a string, function, or an object with content.`);
 }
 //#endregion
+//#region understudy/functionWait.ts
+/** Runs in the page's main world; keep this function self-contained. */
+function createFunctionWait(predicate, polling) {
+	let stopped = false;
+	let timer;
+	let animationFrame;
+	let resolve;
+	let reject;
+	const promise = new Promise((done, fail) => {
+		resolve = done;
+		reject = fail;
+	});
+	promise.catch(() => {});
+	const stop = () => {
+		stopped = true;
+		clearTimeout(timer);
+		if (animationFrame !== void 0) cancelAnimationFrame(animationFrame);
+	};
+	const poll = async () => {
+		if (stopped) return;
+		try {
+			const evaluated = predicate();
+			const value = await (typeof evaluated === "function" ? evaluated() : evaluated);
+			if (stopped) return;
+			if (value) {
+				const serialized = JSON.stringify(value);
+				if (serialized === void 0) throw new TypeError("waitForFunction result must be JSON-serializable");
+				const result = JSON.parse(serialized);
+				stop();
+				resolve(result);
+			} else if (polling === "raf") animationFrame = requestAnimationFrame(() => void poll());
+			else timer = setTimeout(() => void poll(), polling);
+		} catch (error) {
+			stop();
+			reject(error);
+		}
+	};
+	poll();
+	return {
+		promise,
+		dispose() {
+			if (stopped) return;
+			stop();
+			reject(/* @__PURE__ */ new Error("Function wait disposed"));
+		}
+	};
+}
+async function waitForFunction(getFrame, expression, options = {}) {
+	const polling = options.polling ?? "raf";
+	if (polling !== "raf" && (!Number.isFinite(polling) || polling <= 0 || polling > 2147483647)) throw new RangeError("Polling must be 'raf' or a positive interval up to 2147483647ms");
+	return runWithProgress({
+		name: "waitForFunction",
+		timeout: options.timeout ?? 0
+	}, async (progress) => {
+		for (;;) {
+			progress.throwIfStopped();
+			const frame = getFrame();
+			try {
+				const contextId = await frame.getMainWorldExecutionContextId(progress);
+				if (getFrame() !== frame) continue;
+				return await browserWait(frame.session, progress, (onLateResult) => progress.run("installing function wait", () => frame.session.send("Runtime.evaluate", {
+					expression: `(${createFunctionWait.toString()})(() => (${expression}), ${JSON.stringify(polling)})`,
+					contextId,
+					awaitPromise: false,
+					returnByValue: false
+				}), onLateResult), "waiting for function");
+			} catch (error) {
+				progress.throwIfStopped();
+				if (error instanceof BrowserWaitError) throw error;
+				const message = error instanceof Error ? error.message : String(error);
+				if (!message.includes("Cannot find context with specified id") && !message.includes("Execution context was destroyed") && !message.includes("Cannot find object with given id") && !message.includes("Inspected target navigated or closed") && !message.startsWith("main world not ready for frame ")) throw error;
+				await progress.delay(25);
+			}
+		}
+	});
+}
+//#endregion
 //#region dom/screenshotScripts/resolveMaskRect.ts
 function resolveMaskRect(maskToken) {
 	function safeClosest(el, selector) {
@@ -57436,6 +57560,14 @@ var Page = class Page {
 	async waitForTimeout(ms) {
 		return new Promise((resolve) => setTimeout(resolve, ms));
 	}
+	/** Poll an expression in the page's main world until its value is truthy. */
+	async waitForFunction(expression, options) {
+		return waitForFunction(() => {
+			if (this.disposed) throw new Error("Page is disposed");
+			if (!this.conn.connected) throw new Error("CDP connection closed: function wait stopped");
+			return this.mainFrameWrapper;
+		}, expression, options);
+	}
 	/**
 	* Wait for an element matching the selector to appear in the DOM.
 	* Uses MutationObserver for efficiency
@@ -58645,6 +58777,9 @@ var StagehandRuntime = class {
 	async pageWaitForSelector(params) {
 		return { matched: await this.resolvePage(params.pageId).waitForSelector(params.selector, params.options) };
 	}
+	async pageWaitForFunction(params) {
+		return { value: await this.resolvePage(params.pageId).waitForFunction(params.expression, params.options) };
+	}
 	async pageScreenshot(params) {
 		const page = this.resolvePage(params.pageId);
 		let options;

{stagehand-4.3.0a0.dev1624 → stagehand-4.3.0a0.dev1626}/src/stagehand/_generated/input_types.py

@@ -277,6 +277,9 @@ FieldSchema13: TypeAlias = Optional[Union[str, float, bool, list["FieldSchema13"
 FieldSchema14: TypeAlias = Optional[Union[str, float, bool, list["FieldSchema14"], dict[str, "FieldSchema14"]]]
 
 
+FieldSchema15: TypeAlias = Optional[Union[str, float, bool, list["FieldSchema15"], dict[str, "FieldSchema15"]]]
+
+
 FieldSchema2: TypeAlias = Optional[Union[str, float, bool, list["FieldSchema2"], dict[str, "FieldSchema2"]]]
 
 
@@ -332,7 +335,7 @@ class InputFilePayload(TypedDict):
 class JSONRPCErrorObject(TypedDict):
     code: int
     message: str
-    data: NotRequired[FieldSchema14]
+    data: NotRequired[FieldSchema15]
 
 
 JSONRPCRequestId: TypeAlias = int
@@ -718,7 +721,7 @@ class PageAddInitScriptParams(TypedDict):
     source: str
 
 
-PageCDPEventParams: TypeAlias = dict[str, FieldSchema12]
+PageCDPEventParams: TypeAlias = dict[str, FieldSchema13]
 
 
 class PageCDPEvent(TypedDict):
@@ -984,6 +987,21 @@ class PageVoidResult(TypedDict):
     ok: Literal[True]
 
 
+class PageWaitForFunctionOptions(TypedDict):
+    polling: NotRequired[Literal["raf"] | float]
+    timeout: NotRequired[int]
+
+
+class PageWaitForFunctionParams(TypedDict):
+    page_id: str
+    expression: str
+    options: NotRequired[PageWaitForFunctionOptions]
+
+
+class PageWaitForFunctionResult(TypedDict):
+    value: FieldSchema10
+
+
 class PageWaitForLoadStateParams(TypedDict):
     page_id: str
     state: LoadState
@@ -1101,7 +1119,7 @@ class StagehandInitResult(TypedDict):
     pages: list[PageRef]
 
 
-StagehandLogData: TypeAlias = dict[str, FieldSchema11]
+StagehandLogData: TypeAlias = dict[str, FieldSchema12]
 
 
 StagehandLogLevel: TypeAlias = Literal["debug", "info", "warn", "error"]
@@ -1242,7 +1260,7 @@ class WebMCPAnnotation(TypedDict):
 WebMCPInvocationStatus: TypeAlias = Literal["Completed", "Canceled", "Error"]
 
 
-WebMCPJsonValue: TypeAlias = FieldSchema10
+WebMCPJsonValue: TypeAlias = FieldSchema11
 
 
 class PageWebMCPInvokeToolParams(TypedDict):

{stagehand-4.3.0a0.dev1624 → stagehand-4.3.0a0.dev1626}/src/stagehand/_generated/models.py

@@ -710,6 +710,12 @@ class FieldSchema14(
     root: Optional[Union[StrictStr, StrictInt, StrictFloat, StrictBool, list[Optional["FieldSchema14"]], dict[StrictStr, Optional["FieldSchema14"]]]]
 
 
+class FieldSchema15(
+    RootModel[Optional[Union[StrictStr, StrictInt, StrictFloat, StrictBool, list[Optional["FieldSchema15"]], dict[StrictStr, Optional["FieldSchema15"]]]]]
+):
+    root: Optional[Union[StrictStr, StrictInt, StrictFloat, StrictBool, list[Optional["FieldSchema15"]], dict[StrictStr, Optional["FieldSchema15"]]]]
+
+
 class FieldSchema2(
     RootModel[Optional[Union[StrictStr, StrictInt, StrictFloat, StrictBool, list[Optional["FieldSchema2"]], dict[StrictStr, Optional["FieldSchema2"]]]]]
 ):
@@ -811,7 +817,7 @@ class JSONRPCErrorObject(WireModel):
     )
     code: Annotated[StrictInt, Field(ge=-9007199254740991, le=9007199254740991)]
     message: StrictStr
-    data: Optional[FieldSchema14] = None
+    data: Optional[FieldSchema15] = None
 
 
 class JSONRPCRequestId(RootModel[StrictInt]):
@@ -1564,8 +1570,8 @@ class PageCDPEventNotification(WireModel):
     event: PageCDPEvent
 
 
-class PageCDPEventParams(RootModel[dict[StrictStr, Optional[FieldSchema12]]]):
-    root: dict[StrictStr, Optional[FieldSchema12]]
+class PageCDPEventParams(RootModel[dict[StrictStr, Optional[FieldSchema13]]]):
+    root: dict[StrictStr, Optional[FieldSchema13]]
 
 
 class PageClickOptions(WireModel):
@@ -2027,6 +2033,33 @@ class PageVoidResult(WireModel):
     ok: Literal[True]
 
 
+class PageWaitForFunctionOptions(WireModel):
+    model_config = ConfigDict(
+        extra="forbid",
+        validate_by_name=True,
+    )
+    polling: Optional[Union[Literal["raf"], Polling]] = None
+    timeout: Annotated[Optional[StrictInt], Field(ge=0, le=9007199254740991)] = None
+
+
+class PageWaitForFunctionParams(WireModel):
+    model_config = ConfigDict(
+        extra="forbid",
+        validate_by_name=True,
+    )
+    page_id: StrictStr
+    expression: StrictStr
+    options: Optional[PageWaitForFunctionOptions] = None
+
+
+class PageWaitForFunctionResult(WireModel):
+    model_config = ConfigDict(
+        extra="forbid",
+        validate_by_name=True,
+    )
+    value: Optional[FieldSchema10]
+
+
 class PageWaitForLoadStateParams(WireModel):
     model_config = ConfigDict(
         extra="forbid",
@@ -2123,6 +2156,10 @@ class PageWebMCPToolsResult(WireModel):
     tools: list[WebMCPToolDescriptor]
 
 
+class Polling(RootModel[StrictFloat]):
+    root: Annotated[StrictFloat, Field(gt=0.0, le=2147483647.0)]
+
+
 class ProxyConfig(RootModel[Union[BrowserbaseProxyConfig, ExternalProxyConfig]]):
     root: Union[BrowserbaseProxyConfig, ExternalProxyConfig]
 
@@ -2321,8 +2358,8 @@ class StagehandLog(WireModel):
     data: StagehandLogData
 
 
-class StagehandLogData(RootModel[dict[StrictStr, Optional[FieldSchema11]]]):
-    root: dict[StrictStr, Optional[FieldSchema11]]
+class StagehandLogData(RootModel[dict[StrictStr, Optional[FieldSchema12]]]):
+    root: dict[StrictStr, Optional[FieldSchema12]]
 
 
 class StagehandLogLevel(StrEnum):
@@ -2481,8 +2518,8 @@ class WebMCPInvocationStatus(StrEnum):
     error = "Error"
 
 
-class WebMCPJsonValue(RootModel[Optional[FieldSchema10]]):
-    root: Optional[FieldSchema10]
+class WebMCPJsonValue(RootModel[Optional[FieldSchema11]]):
+    root: Optional[FieldSchema11]
 
 
 class WebMCPRemoteObject(RootModel[dict[StrictStr, WebMCPJsonValue]]):
@@ -2548,6 +2585,7 @@ FieldSchema11.model_rebuild()
 FieldSchema12.model_rebuild()
 FieldSchema13.model_rebuild()
 FieldSchema14.model_rebuild()
+FieldSchema15.model_rebuild()
 FieldSchema2.model_rebuild()
 FieldSchema3.model_rebuild()
 FieldSchema4.model_rebuild()

{stagehand-4.3.0a0.dev1624 → stagehand-4.3.0a0.dev1626}/src/stagehand/_generated/protocol_version.py

@@ -1,4 +1,4 @@
 """Generated from packages/protocol/package.json. Do not edit."""
 
 PROTOCOL_SEMVER_PATTERN = '^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$'
-STAGEHAND_PROTOCOL_VERSION = '3.0.0-alpha-77170ed9f8252581458360ab511c55a4be31fb44'
+STAGEHAND_PROTOCOL_VERSION = '3.0.0-alpha-901eb276429702cddd4bfe3a3656946f3ebc166a'

{stagehand-4.3.0a0.dev1624 → stagehand-4.3.0a0.dev1626}/src/stagehand/page.py

@@ -4,6 +4,7 @@ import asyncio
 import base64
 import builtins
 import inspect
+import json
 from collections.abc import Awaitable, Callable, Mapping, Sequence
 from pathlib import Path
 from typing import Literal, TypeVar, cast, overload
@@ -67,6 +68,9 @@ from ._generated.models import (
     PageTypeParams,
     PageUrlResult,
     PageVoidResult,
+    PageWaitForFunctionOptions,
+    PageWaitForFunctionParams,
+    PageWaitForFunctionResult,
     PageWaitForLoadStateParams,
     PageWaitForSelectorOptions,
     PageWaitForSelectorParams,
@@ -94,6 +98,9 @@ ToolsAddedListener = Callable[[list[WebMCPTool]], object | Awaitable[object]]
 ToolsRemovedListener = Callable[[list[WebMCPToolIdentity]], object | Awaitable[object]]
 NotificationT = TypeVar("NotificationT", PageCDPEventNotification, PageEventNotification)
 
+# Distinguishes an omitted wait_for_function ``arg`` from an explicit JSON null.
+_UNSET_ARG = object()
+
 
 class CDPSubscription:
     def __init__(
@@ -539,6 +546,44 @@ class Page:
             PageVoidResult,
         )
 
+    async def wait_for_function(
+        self,
+        expression: str,
+        *,
+        arg: JsonValue = cast(JsonValue, _UNSET_ARG),
+        polling: Literal["raf"] | float | None = None,
+        timeout: int | None = None,
+    ) -> JsonValue:
+        """Poll JavaScript in the page until it returns a truthy JSON value."""
+        if arg is not _UNSET_ARG:
+            try:
+                serialized_arg = json.dumps(arg, allow_nan=False)
+            except (TypeError, ValueError) as error:
+                message = "page.wait_for_function: 'arg' must be JSON-serializable."
+                raise TypeError(message) from error
+            # Like Playwright, a function expression receives arg; other expressions ignore it.
+            # The browser invokes the returned thunk once per poll. JSON.parse keeps own
+            # "__proto__" keys that an object literal would treat as a prototype.
+            parsed_arg = f"JSON.parse({json.dumps(serialized_arg)})"
+            expression = (
+                f'((value) => typeof value === "function" ? () => value({parsed_arg}) : value)'
+                f"(({expression}))"
+            )
+        params = PageWaitForFunctionParams(page_id=self.page_id, expression=expression)
+        options = PageWaitForFunctionOptions.model_validate({
+            name: value
+            for name, value in (("polling", polling), ("timeout", timeout))
+            if value is not None
+        })
+        if options.model_fields_set:
+            params.options = options
+        result = await self._rpc_client.send(
+            "page.wait_for_function",
+            params,
+            PageWaitForFunctionResult,
+        )
+        return None if result.value is None else cast(JsonValue, result.value.model_dump())
+
     async def wait_for_selector(
         self,
         selector: str,

{stagehand-4.3.0a0.dev1624 → stagehand-4.3.0a0.dev1626}/src/stagehand/rpc_client.py

@@ -36,6 +36,7 @@ _DEFAULT_OPERATION_TIMEOUT_MS = {
     "page.webmcp_tools": 1_000,
 }
 _UNBOUNDED_BY_DEFAULT_METHODS = {
+    "page.wait_for_function",
     "stagehand.init",
     "stagehand.close",
     "stagehand.act",
@@ -602,6 +603,7 @@ def _rpc_response_timeout_seconds(method: str, params: BaseModel) -> float | Non
         "page.screenshot",
         "page.pdf",
         "page.snapshot",
+        "page.wait_for_function",
         "page.wait_for_selector",
         "page.webmcp_tools",
         "page.webmcp_invocation_result",
@@ -613,10 +615,12 @@ def _rpc_response_timeout_seconds(method: str, params: BaseModel) -> float | Non
         operation_timeout_ms = _numeric_property(params, "ms")
 
     if operation_timeout_ms is not None:
-        if (
-            method in {"page.pdf", "page.snapshot", "page.wait_for_selector"}
-            and operation_timeout_ms == 0
-        ):
+        if operation_timeout_ms == 0 and method in {
+            "page.pdf",
+            "page.snapshot",
+            "page.wait_for_function",
+            "page.wait_for_selector",
+        }:
             return None
         return (_RPC_RESPONSE_GRACE_MS + max(0, operation_timeout_ms)) / 1_000