stagehand 4.3.0a0.dev1620__tar.gz → 4.3.0a0.dev1626__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stagehand
-Version: 4.3.0a0.dev1620
+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.dev1620 → stagehand-4.3.0a0.dev1626}/pyproject.toml

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

{stagehand-4.3.0a0.dev1620 → 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-76cd7e0f2ff04b0fb5c07e27e0db70746d0ad3c8",
+	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, {
@@ -12527,8 +12557,20 @@ strictObject({
 	acceptDownloads: boolean().optional(),
 	keepAlive: boolean().optional()
 }).meta({ id: "LocalBrowserLaunchOptions" });
+var CDPHeadersSchema = preprocess((value) => {
+	try {
+		if (typeof value !== "object" || value === null || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) return null;
+		const entries = Object.entries(value);
+		if (!entries.every(([name, content]) => name.length > 0 && !/[^!#$%&'*+\-.^_`|~0-9A-Za-z]/.test(name) && typeof content === "string" && !/[^\t\x20-\x7e]/.test(content) && content === content.replace(/^[ \t]+|[ \t]+$/g, ""))) return null;
+		return Object.fromEntries(entries);
+	} catch {
+		return null;
+	}
+}, record(string(), string(), { error: "headers must map valid HTTP header names to ASCII string values without leading or trailing spaces or tabs" }));
 strictObject({
 	cdpUrl: string().min(1),
+	/** Headers for client-side CDP discovery and WebSocket connections. */
+	headers: CDPHeadersSchema.optional(),
 	extensionId: string().optional(),
 	/**
 	* Browser-level CDP WebSocket URL dialed by the extension inside Chrome.
@@ -13005,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);
@@ -13071,6 +13117,7 @@ function createPageController(runtime) {
 		waitForLoadState,
 		waitForTimeout,
 		waitForSelector,
+		waitForFunction,
 		screenshot,
 		pdf,
 		snapshot,
@@ -16943,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);
@@ -17068,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);
 			}
 		}
 	}
@@ -52076,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);
@@ -54471,7 +54530,7 @@ var WebTracerProvider = class extends BasicTracerProvider {
 };
 var package_default = {
 	name: "@browserbasehq/stagehand-extension",
-	version: "1.2.0-alpha-76cd7e0f2ff04b0fb5c07e27e0db70746d0ad3c8",
+	version: "1.2.0-alpha-901eb276429702cddd4bfe3a3656946f3ebc166a",
 	"private": true,
 	type: "module",
 	scripts: {
@@ -55866,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) {
@@ -57424,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
@@ -58633,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.dev1620 → 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.dev1620 → 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.dev1620 → 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-76cd7e0f2ff04b0fb5c07e27e0db70746d0ad3c8'
+STAGEHAND_PROTOCOL_VERSION = '3.0.0-alpha-901eb276429702cddd4bfe3a3656946f3ebc166a'

{stagehand-4.3.0a0.dev1620 → stagehand-4.3.0a0.dev1626}/src/stagehand/_validation.py

@@ -1,8 +1,19 @@
+import re
 from collections.abc import Mapping
-from typing import Annotated
+from typing import Annotated, cast
 from urllib.parse import urlparse
 
-from pydantic import AfterValidator, AnyUrl, BaseModel, ConfigDict, TypeAdapter, model_validator
+from pydantic import (
+    AfterValidator,
+    AnyUrl,
+    BaseModel,
+    ConfigDict,
+    TypeAdapter,
+    ValidationError,
+    ValidatorFunctionWrapHandler,
+    WrapValidator,
+    model_validator,
+)
 from typing_extensions import override
 
 _url_adapter = TypeAdapter(AnyUrl)
@@ -15,6 +26,54 @@ def _validate_url(value: str) -> str:
 
 WireUrl = Annotated[str, AfterValidator(_validate_url)]
 
+# RFC 9110 field names are tokens. Restrict values to ASCII so HTTP discovery
+# and WebSocket handshakes encode them identically; allow only internal whitespace.
+_HEADER_NAME = re.compile(r"[!#$%&'*+\-.^_`|~0-9A-Za-z]+")
+_HEADER_VALUE = re.compile(r"[\t\x20-\x7e]*")
+
+
+def _validate_headers(value: Mapping[str, str]) -> Mapping[str, str]:
+    for name, header_value in value.items():
+        if not _HEADER_NAME.fullmatch(name):
+            raise ValueError
+        if not _HEADER_VALUE.fullmatch(header_value) or header_value != header_value.strip(" \t"):
+            raise ValueError
+    return value
+
+
+def _redact_header_validation_errors(
+    value: object, handler: ValidatorFunctionWrapHandler
+) -> dict[str, str]:
+    try:
+        return cast(dict[str, str], handler(value))
+    except ValidationError:
+        # Error inputs, locations, and validator context can all contain credentials.
+        # Rebuild the error rather than only hiding inputs in its formatted message.
+        raise ValidationError.from_exception_data(
+            "CDP headers",
+            [
+                {
+                    "type": "value_error",
+                    "loc": (),
+                    "input": "[redacted]",
+                    "ctx": {
+                        "error": ValueError(
+                            "headers must map valid HTTP header names to ASCII string values "
+                            "without leading or trailing spaces or tabs"
+                        )
+                    },
+                }
+            ],
+            hide_input=True,
+        ) from None
+
+
+WireHeaders = Annotated[
+    dict[str, str],
+    AfterValidator(_validate_headers),
+    WrapValidator(_redact_header_validation_errors),
+]
+
 
 def _validate_websocket_url(value: str) -> str:
     parsed = urlparse(value)

{stagehand-4.3.0a0.dev1620 → stagehand-4.3.0a0.dev1626}/src/stagehand/browser.py

@@ -312,12 +312,14 @@ async def _connect_browser(
     preloaded_extension: bool = False,
     after_connect: Callable[[CDPClient], Awaitable[None]] | None = None,
     worker_init_metadata: _WorkerInitMetadata,
+    headers: Mapping[str, str] | None = None,
 ) -> StagehandBrowser:
     owns_source = origin == "launched" and not source.keep_alive
     cdp_client: CDPClient | None = None
     try:
         cdp_client = await CDPClient.connect(
             cdp_url=source.cdp_url,
+            **({"headers": headers} if headers else {}),
             extension_dir=extension_dir,
             local_extension_dir=local_extension_dir,
             extension_id=extension_id,
@@ -536,6 +538,7 @@ class LocalBrowser:
         cdp_url: str,
         extension_id: str | None = None,
         extension_cdp_url: str | None = None,
+        headers: Mapping[str, str] | None = None,
     ) -> StagehandBrowser:
         """Connect to an existing browser.
 
@@ -547,6 +550,10 @@ class LocalBrowser:
                 client connected to. Set it when the client reaches Chrome through
                 a proxy the browser cannot or should not use, such as an
                 authenticated gateway whose URL carries credentials.
+            headers: HTTP headers to send with the CDP connection, such as a
+                gateway's credentials, so they need not ride in `cdp_url`. They
+                go to `cdp_url` and to the WebSocket it advertises when that is
+                on the same host, never elsewhere, and never to the extension.
         """
         options = LocalBrowserConnectOptions.model_validate({
             name: value
@@ -554,6 +561,7 @@ class LocalBrowser:
                 ("cdp_url", cdp_url),
                 ("extension_id", extension_id),
                 ("extension_cdp_url", extension_cdp_url),
+                ("headers", dict(headers) if isinstance(headers, Mapping) else headers),
             )
             if value is not None
         })
@@ -567,6 +575,7 @@ class LocalBrowser:
                 browser=None,
                 browser_cdp_url=options.extension_cdp_url,
             ),
+            headers=options.headers,
         )
 
 

{stagehand-4.3.0a0.dev1620 → stagehand-4.3.0a0.dev1626}/src/stagehand/cdp_client.py

@@ -2,19 +2,28 @@ from __future__ import annotations
 
 import asyncio
 import json
+import logging
 import re
 import time
 from collections.abc import Callable, Mapping
 from contextlib import suppress
 from dataclasses import dataclass
 from typing import Any, Literal, Protocol, cast
-from urllib.request import urlopen
+from urllib.error import HTTPError
+from urllib.parse import urljoin, urlsplit
+from urllib.request import HTTPRedirectHandler, Request, build_opener, urlopen
+
+from typing_extensions import override
+from websockets.asyncio.client import connect as WebSocketConnect
+from websockets.exceptions import InvalidStatus
 
 from stagehand._generated.protocol_version import (
     PROTOCOL_SEMVER_PATTERN,
     STAGEHAND_PROTOCOL_VERSION,
 )
 
+_LOGGER = logging.getLogger(__name__)
+
 STAGEHAND_SEND_TO_HOST_BINDING = "__stagehandSendToHost"
 _RUNTIME_NAME = "stagehand"
 _STAGEHAND_EXTENSION_NAME = "Stagehand Runtime"
@@ -257,6 +266,7 @@ class CDPClient:
         extension_id: str | None = None,
         preloaded_extension: bool = False,
         service_worker_url_includes: str | None = None,
+        headers: Mapping[str, str] | None = None,
     ) -> CDPClient:
         """Connect without an independent lifecycle deadline.
 
@@ -278,8 +288,16 @@ class CDPClient:
                 "or preloaded_extension is required"
             )
 
-        web_socket_debugger_url = await _resolve_browser_web_socket_url(cdp_url)
-        socket = await _connect_web_socket(web_socket_debugger_url)
+        web_socket_debugger_url = await _resolve_browser_web_socket_url(cdp_url, headers=headers)
+        web_socket_headers = headers or None
+        if web_socket_headers and not _can_forward_headers(cdp_url, web_socket_debugger_url):
+            web_socket_headers = None
+            _LOGGER.debug(
+                "CDP headers were withheld from the advertised WebSocket endpoint because "
+                "its host or port differs, or forwarding would downgrade transport security. "
+                "If the handshake is rejected, check the gateway's advertised CDP endpoint."
+            )
+        socket = await _connect_web_socket(web_socket_debugger_url, headers=web_socket_headers)
         client = cls(socket, web_socket_debugger_url)
 
         try:
@@ -659,33 +677,103 @@ class CDPClient:
         task.add_done_callback(finish)
 
 
-async def _connect_web_socket(url: str) -> _WebSocket:
-    from websockets.asyncio.client import connect
+class _UnsafeCDPRedirectError(RuntimeError):
+    """A redirect would expose caller headers to an unauthorized endpoint."""
+
+
+_DEFAULT_PORTS = {"http": 80, "ws": 80, "https": 443, "wss": 443}
+
+
+def _can_forward_headers(source: str, destination: str) -> bool:
+    """Require the same host and effective port, without a TLS downgrade."""
+    try:
+        first, second = urlsplit(source), urlsplit(destination)
+        return (
+            first.scheme in _DEFAULT_PORTS
+            and second.scheme in _DEFAULT_PORTS
+            and first.hostname is not None
+            and first.hostname == second.hostname
+            and (first.port if first.port is not None else _DEFAULT_PORTS[first.scheme])
+            == (second.port if second.port is not None else _DEFAULT_PORTS[second.scheme])
+            and not (first.scheme in ("https", "wss") and second.scheme in ("http", "ws"))
+        )
+    except ValueError:
+        return False
+
+
+class _CDPRedirectHandler(HTTPRedirectHandler):
+    @override
+    def redirect_request(
+        self, req: Request, fp: Any, code: int, msg: str, headers: Any, newurl: str
+    ) -> Request | None:
+        if not _can_forward_headers(req.full_url, newurl):
+            raise _UnsafeCDPRedirectError(
+                "Refusing CDP HTTP redirect with headers to a different host or port, "
+                "or an insecure endpoint"
+            )
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+class _CDPWebSocketConnect(WebSocketConnect):
+    @override
+    def process_redirect(self, exc: Exception) -> Exception | str:
+        if (
+            self.additional_headers
+            and isinstance(exc, InvalidStatus)
+            and exc.response.status_code in (300, 301, 302, 303, 307, 308)
+            and "Location" in exc.response.headers
+            and not _can_forward_headers(
+                self.uri, urljoin(self.uri, exc.response.headers["Location"])
+            )
+        ):
+            return _UnsafeCDPRedirectError(
+                "Refusing CDP WebSocket redirect with headers to a different host or port, "
+                "or an insecure endpoint"
+            )
+        return super().process_redirect(exc)
+
 
+async def _connect_web_socket(url: str, *, headers: Mapping[str, str] | None = None) -> _WebSocket:
     return cast(
         _WebSocket,
-        await connect(url, open_timeout=None, max_size=None),
+        await _CDPWebSocketConnect(
+            url, open_timeout=None, max_size=None, additional_headers=headers
+        ),
     )
 
 
-async def _resolve_browser_web_socket_url(cdp_url: str) -> str:
+async def _resolve_browser_web_socket_url(
+    cdp_url: str, *, headers: Mapping[str, str] | None = None
+) -> str:
     if cdp_url.startswith(("ws://", "wss://")):
         return cdp_url
 
     base_url = cdp_url.rstrip("/")
     while True:
         try:
-            version = await asyncio.to_thread(_read_json, f"{base_url}/json/version")
+            version = await asyncio.to_thread(_read_json, f"{base_url}/json/version", headers)
             debugger_url = version.get("webSocketDebuggerUrl")
             if isinstance(debugger_url, str) and debugger_url:
                 return debugger_url
+        except _UnsafeCDPRedirectError:
+            raise
+        except HTTPError as error:
+            error.close()
+            if error.code in (401, 403):
+                raise RuntimeError(
+                    f"CDP discovery was rejected with HTTP {error.code}. "
+                    "Check the gateway credentials and access permissions."
+                ) from None
         except Exception:
             pass
         await asyncio.sleep(0.25)
 
 
-def _read_json(url: str) -> dict[str, object]:
-    with urlopen(url, timeout=2) as response:  # noqa: S310 -- The user selects the CDP URL.
+def _read_json(url: str, headers: Mapping[str, str] | None = None) -> dict[str, object]:
+    request = Request(url, headers=dict(headers or {}))
+    # Keep the existing redirect behavior for connections without caller headers.
+    open_url = build_opener(_CDPRedirectHandler()).open if headers else urlopen
+    with open_url(request, timeout=2) as response:
         value: Any = json.load(response)
     if not isinstance(value, dict):
         raise RuntimeError("CDP version endpoint returned invalid JSON")

{stagehand-4.3.0a0.dev1620 → stagehand-4.3.0a0.dev1626}/src/stagehand/client_models.py

@@ -18,7 +18,7 @@ from ._generated.models import (
     StagehandResultMetadata,
     TelemetryConfig,
 )
-from ._validation import WireModel, WireUrl, WireWebSocketUrl
+from ._validation import WireHeaders, WireModel, WireUrl, WireWebSocketUrl
 from .browserbase_session import DEFAULT_BROWSERBASE_URL
 from .client_types import Cache as CacheInput
 
@@ -103,13 +103,16 @@ class LocalBrowserLaunchOptions(WireModel):
 
 
 class LocalBrowserConnectOptions(WireModel):
-    model_config = ConfigDict(extra="forbid", strict=True)
+    # Headers may carry credentials, so validation errors never echo the input.
+    model_config = ConfigDict(extra="forbid", strict=True, hide_input_in_errors=True)
 
     cdp_url: Annotated[str, Field(min_length=1)]
     extension_id: str | None = None
     """Deprecated and ignored. Omit this field; Stagehand discovers the extension automatically."""
     extension_cdp_url: WireWebSocketUrl | None = None
     """Browser-level CDP WebSocket the extension dials, when it differs from `cdp_url`."""
+    headers: WireHeaders | None = None
+    """HTTP headers sent with the CDP connection, e.g. a gateway's credentials."""
 
 
 class BrowserbaseClientOptions(WireModel):

{stagehand-4.3.0a0.dev1620 → stagehand-4.3.0a0.dev1626}/src/stagehand/client_types.py

@@ -69,6 +69,8 @@ class LocalBrowserConnectOptions(TypedDict):
     """Deprecated and ignored. Omit this field; Stagehand discovers the extension automatically."""
     extension_cdp_url: NotRequired[str]
     """Browser-level CDP WebSocket the extension dials, when it differs from `cdp_url`."""
+    headers: NotRequired[dict[str, str]]
+    """HTTP headers sent with the CDP connection, e.g. a gateway's credentials."""
 
 
 class BrowserbaseClientOptions(TypedDict, total=False):

{stagehand-4.3.0a0.dev1620 → 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.dev1620 → 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