stagehand 4.2.0a0.dev1575__tar.gz → 4.2.0a0.dev1577__tar.gz

{stagehand-4.2.0a0.dev1575 → stagehand-4.2.0a0.dev1577}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stagehand
-Version: 4.2.0a0.dev1575
+Version: 4.2.0a0.dev1577
 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.2.0a0.dev1575 → stagehand-4.2.0a0.dev1577}/pyproject.toml

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

{stagehand-4.2.0a0.dev1575 → stagehand-4.2.0a0.dev1577}/src/stagehand/_extension/service-worker.js

@@ -7363,7 +7363,7 @@ function isRecord$1(value) {
 }
 var package_default$1 = {
 	name: "@browserbasehq/stagehand-protocol",
-	version: "2.1.0-alpha-0336409092b85beeba38ea3cd4953f45eb96ed6b",
+	version: "2.1.0-alpha-c9c8a41778b2000c9a9bdfc4b68e6c0c4866ab1a",
 	"private": true,
 	type: "module",
 	exports: {
@@ -16188,12 +16188,12 @@ function stringifyArgument(value) {
 		return "[unserializable]";
 	}
 }
-async function performUnderstudyMethod(page, frame, method, rawXPath, args, logger, domSettleTimeoutMs) {
+async function performUnderstudyMethod(page, frame, method, rawXPath, args, logger, progress, domSettleTimeoutMs) {
 	const selectorRaw = normalizeRootXPath(rawXPath);
 	try {
 		await logger.span(`Understudy${toTitleCase(method)}`, { target: selectorRaw }, async (spanLogger) => {
-			const locator = await resolveLocatorWithHops(page, frame, selectorRaw);
-			const initialUrl = await getFrameUrl(frame);
+			const locator = await resolveLocatorWithHops(page, frame, selectorRaw, progress);
+			const initialUrl = await progress.run("reading frame URL", () => frame.evaluate("location.href", void 0, progress));
 			spanLogger.debug("Performing understudy method", {
 				category: "action",
 				xpath: selectorRaw,
@@ -16209,11 +16209,12 @@ async function performUnderstudyMethod(page, frame, method, rawXPath, args, logg
 				page,
 				initialUrl,
 				logger: spanLogger,
-				domSettleTimeoutMs
+				domSettleTimeoutMs,
+				progress
 			};
 			const handler = METHOD_HANDLER_MAP[method] ?? null;
 			if (handler) {
-				await handler(ctx);
+				await progress.run(`performing ${method}`, () => handler(ctx));
 				return;
 			}
 			spanLogger.debug("Chosen method is invalid", {
@@ -16258,7 +16259,7 @@ async function selectOption(ctx) {
 	const { locator, xpath, args, logger } = ctx;
 	try {
 		const text = args[0]?.toString() || "";
-		await locator.selectOption(text);
+		await locator.selectOption(text, ctx.progress);
 	} catch (e) {
 		const msg = e instanceof Error ? e.message : String(e);
 		const stack = e instanceof Error ? e.stack : void 0;
@@ -16277,10 +16278,13 @@ async function scrollIntoView(ctx) {
 		category: "action",
 		xpath
 	});
-	const { objectId } = await locator.resolveNode();
+	const { objectId } = await locator.resolveNode(ctx.progress);
 	const ownerSession = locator.getFrame().session;
-	await ownerSession.send("DOM.scrollIntoViewIfNeeded", { objectId });
-	await ownerSession.send("Runtime.releaseObject", { objectId }).catch(() => {});
+	try {
+		await ctx.progress.run("scrolling element into view", () => ownerSession.send("DOM.scrollIntoViewIfNeeded", { objectId }));
+	} finally {
+		await ctx.progress.cleanup(() => ownerSession.send("Runtime.releaseObject", { objectId }));
+	}
 }
 async function scrollElementToPercentage(ctx) {
 	const { locator, xpath, args, logger } = ctx;
@@ -16290,15 +16294,15 @@ async function scrollElementToPercentage(ctx) {
 		coordinate: [...args]
 	});
 	const [yArg = "0%"] = args;
-	await locator.scrollTo(yArg);
+	await locator.scrollTo(yArg, ctx.progress);
 }
 /** Scroll the page by pixel offset, starting from the element's center. */
 async function scrollByPixelOffset(ctx) {
 	const { locator, page, args } = ctx;
 	const dx = Number(args[0] ?? 0);
 	const dy = Number(args[1] ?? 0);
-	const { x, y } = await locator.centroid();
-	await page.scroll(x, y, dx, dy);
+	const { x, y } = await locator.centroid(ctx.progress);
+	await page.scroll(x, y, dx, dy, ctx.progress);
 }
 async function wheelScroll(ctx) {
 	const { frame, args, logger } = ctx;
@@ -16307,19 +16311,19 @@ async function wheelScroll(ctx) {
 		category: "action",
 		deltaY
 	});
-	await frame.session.send("Input.dispatchMouseEvent", {
+	await ctx.progress.run("dispatching mouse wheel", () => frame.session.send("Input.dispatchMouseEvent", {
 		type: "mouseWheel",
 		x: 0,
 		y: 0,
 		deltaY,
 		deltaX: 0
-	});
+	}));
 }
 async function fillOrType(ctx) {
 	const { locator, xpath, args, logger } = ctx;
 	try {
-		await locator.fill("");
-		await locator.fill(args[0] ?? "");
+		await locator.fill("", ctx.progress);
+		await locator.fill(args[0] ?? "", ctx.progress);
 	} catch (e) {
 		const msg = e instanceof Error ? e.message : String(e);
 		logger.debug("Error filling element", {
@@ -16333,7 +16337,7 @@ async function fillOrType(ctx) {
 async function typeText(ctx) {
 	const { locator, xpath, args, logger } = ctx;
 	try {
-		await locator.type(args[0] ?? "");
+		await locator.type(args[0] ?? "", void 0, ctx.progress);
 	} catch (e) {
 		const msg = e instanceof Error ? e.message : String(e);
 		logger.debug("Error typing into element", {
@@ -16353,7 +16357,7 @@ async function pressKey(ctx) {
 			key,
 			xpath
 		});
-		await page.keyPress(key);
+		await page.keyPress(key, void 0, ctx.progress);
 	} catch (e) {
 		const msg = e instanceof Error ? e.message : String(e);
 		logger.debug("Error pressing key", {
@@ -16368,7 +16372,7 @@ async function pressKey(ctx) {
 async function clickElement(ctx) {
 	const { locator, xpath, args, logger } = ctx;
 	try {
-		await locator.click({ button: args[0] || void 0 });
+		await locator.click({ button: args[0] || void 0 }, ctx.progress);
 	} catch (e) {
 		const msg = e instanceof Error ? e.message : String(e);
 		logger.error("Error performing click", {
@@ -16382,7 +16386,7 @@ async function clickElement(ctx) {
 async function doubleClick(ctx) {
 	const { locator, xpath, logger } = ctx;
 	try {
-		await locator.click({ clickCount: 2 });
+		await locator.click({ clickCount: 2 }, ctx.progress);
 	} catch (e) {
 		const msg = e instanceof Error ? e.message : String(e);
 		logger.error("Error performing double click", {
@@ -16397,10 +16401,10 @@ async function dragAndDrop(ctx) {
 	const { page, frame, locator, args, xpath, logger } = ctx;
 	const toXPath = String(args[0] ?? "").trim();
 	if (!toXPath) throw new Error("dragAndDrop requires a target XPath arg");
-	const targetLocator = await resolveLocatorWithHops(page, frame, toXPath);
+	const targetLocator = await resolveLocatorWithHops(page, frame, toXPath, ctx.progress);
 	try {
-		const { x: fromLocalX, y: fromLocalY } = await locator.centroid();
-		const { x: toLocalX, y: toLocalY } = await targetLocator.centroid();
+		const { x: fromLocalX, y: fromLocalY } = await locator.centroid(ctx.progress);
+		const { x: toLocalX, y: toLocalY } = await targetLocator.centroid(ctx.progress);
 		const fromAbs = await locator.getFrame().evaluate(({ x, y }) => {
 			let X = x;
 			let Y = y;
@@ -16420,7 +16424,7 @@ async function dragAndDrop(ctx) {
 		}, {
 			x: fromLocalX,
 			y: fromLocalY
-		});
+		}, ctx.progress);
 		const toAbs = await targetLocator.getFrame().evaluate(({ x, y }) => {
 			let X = x;
 			let Y = y;
@@ -16440,11 +16444,11 @@ async function dragAndDrop(ctx) {
 		}, {
 			x: toLocalX,
 			y: toLocalY
-		});
+		}, ctx.progress);
 		await page.dragAndDrop(fromAbs.x, fromAbs.y, toAbs.x, toAbs.y, {
 			steps: 10,
 			delay: 5
-		});
+		}, ctx.progress);
 	} catch (e) {
 		const msg = e instanceof Error ? e.message : String(e);
 		logger.error("Error performing drag and drop", {
@@ -16468,9 +16472,10 @@ async function scrollByElementHeight(ctx, direction) {
 		category: "action",
 		xpath
 	});
-	const { objectId } = await locator.resolveNode();
+	const { objectId } = await locator.resolveNode(ctx.progress);
 	try {
-		await locator.getFrame().session.send("Runtime.callFunctionOn", {
+		const ownerSession = locator.getFrame().session;
+		await ctx.progress.run("scrolling by element height", () => ownerSession.send("Runtime.callFunctionOn", {
 			objectId,
 			functionDeclaration: `
           function(dir) {
@@ -16500,15 +16505,16 @@ async function scrollByElementHeight(ctx, direction) {
 			arguments: [{ value: direction }],
 			awaitPromise: true,
 			returnByValue: true
-		});
+		}));
 	} finally {
-		await locator.getFrame().session.send("Runtime.releaseObject", { objectId }).catch(() => {});
+		const ownerSession = locator.getFrame().session;
+		await ctx.progress.cleanup(() => ownerSession.send("Runtime.releaseObject", { objectId }));
 	}
 }
 async function hover(ctx) {
 	const { locator, xpath, logger } = ctx;
 	try {
-		await locator.hover();
+		await locator.hover(ctx.progress);
 	} catch (e) {
 		const msg = e instanceof Error ? e.message : String(e);
 		const stack = e instanceof Error ? e.stack : void 0;
@@ -16521,31 +16527,31 @@ async function hover(ctx) {
 		throw e;
 	}
 }
-async function getFrameUrl(frame) {
-	return await frame.evaluate("location.href");
-}
 /**
 * More robust DOM settle using Network + Page events to detect network quiet.
 * Closely modeled after the provided snippet, adapted to our Frame/session + logger.
 */
-async function waitForDomNetworkQuiet(frame, logger, timeout) {
+async function waitForDomNetworkQuiet(frame, logger, timeout, progress) {
 	const overallTimeout = typeof timeout === "number" && Number.isFinite(timeout) ? Math.max(0, timeout) : 5e3;
 	const client = frame.session;
 	const settleStart = Date.now();
 	let hasDoc;
 	try {
-		const rs = await frame.evaluate("document.readyState");
+		const rs = await progress.run("checking document readiness", () => frame.evaluate("document.readyState", void 0, progress));
 		hasDoc = rs === "interactive" || rs === "complete";
 	} catch {
+		progress.throwIfStopped();
 		hasDoc = false;
 	}
-	if (!hasDoc && overallTimeout > 0) await frame.waitForLoadState("domcontentloaded", overallTimeout).catch(() => {});
+	if (!hasDoc && overallTimeout > 0) await frame.waitForLoadState("domcontentloaded", overallTimeout, progress).catch(() => {
+		progress.throwIfStopped();
+	});
 	const elapsed = Date.now() - settleStart;
 	const remainingBudget = Math.max(0, overallTimeout - elapsed);
 	if (remainingBudget === 0) return;
-	await client.send("Network.enable").catch(() => {});
-	await client.send("Page.enable").catch(() => {});
-	await client.send("Target.setAutoAttach", {
+	await progress.run("enabling network events", () => client.send("Network.enable").catch(() => {}));
+	await progress.run("enabling page events", () => client.send("Page.enable").catch(() => {}));
+	await progress.run("attaching to frames", () => client.send("Target.setAutoAttach", {
 		autoAttach: true,
 		waitForDebuggerOnStart: false,
 		flatten: true,
@@ -16556,8 +16562,9 @@ async function waitForDomNetworkQuiet(frame, logger, timeout) {
 			type: "shared_worker",
 			exclude: true
 		}]
-	}).catch(() => {});
-	return new Promise((resolve) => {
+	}).catch(() => {}));
+	progress.throwIfStopped();
+	await new Promise((resolve) => {
 		const inflight = /* @__PURE__ */ new Set();
 		const meta = /* @__PURE__ */ new Map();
 		const docByFrame = /* @__PURE__ */ new Map();
@@ -16634,18 +16641,12 @@ async function waitForDomNetworkQuiet(frame, logger, timeout) {
 			if (quietTimer) clearTimeout(quietTimer);
 			if (stalledRequestSweepTimer) clearInterval(stalledRequestSweepTimer);
 			clearTimeout(guard);
+			progress.signal.removeEventListener("abort", resolveDone);
 			resolve();
 		};
+		progress.signal.addEventListener("abort", resolveDone, { once: true });
 	});
-}
-//#endregion
-//#region handlers/handlerUtils/timeoutGuard.ts
-function createTimeoutGuard(timeout, errorFactory) {
-	if (!timeout || timeout <= 0) return () => {};
-	const startTime = Date.now();
-	return () => {
-		if (Date.now() - startTime >= timeout) throw errorFactory?.(timeout) ?? new TimeoutError("operation", timeout);
-	};
+	progress.throwIfStopped();
 }
 //#endregion
 //#region handlers/handlerUtils/variables.ts
@@ -16958,7 +16959,7 @@ function base64ToBytes$1(base64) {
 * owning session for `this.frameId`. Page is responsible for constructing
 * Frames with the correct session.
 */
-var Frame = class Frame {
+var Frame = class {
 	constructor(session, frameId, pageId, remoteBrowser, logger) {
 		this.session = session;
 		this.frameId = frameId;
@@ -16999,22 +17000,17 @@ var Frame = class Frame {
 			height: model.height
 		};
 	}
-	/** Accessibility.getFullAXTree (+ recurse into child frames if requested) */
-	async getAccessibilityTree(withFrames = false) {
-		await this.session.send("Accessibility.enable");
+	/** Read this frame's accessibility tree. */
+	async getAccessibilityTree(progress) {
+		await runLocatorStep(progress, "enabling accessibility", () => this.session.send("Accessibility.enable"));
 		let nodes;
 		try {
-			({nodes} = await this.session.send("Accessibility.getFullAXTree", { frameId: this.frameId }));
+			({nodes} = await runLocatorStep(progress, "reading accessibility tree", () => this.session.send("Accessibility.getFullAXTree", { frameId: this.frameId })));
 		} catch (e) {
+			progress?.throwIfStopped();
 			const msg = String(e?.message ?? e ?? "");
 			if (!(msg.includes("Frame with the given") || msg.includes("does not belong to the target") || msg.includes("is not found"))) throw e;
-			({nodes} = await this.session.send("Accessibility.getFullAXTree"));
-		}
-		if (!withFrames) return nodes;
-		const children = await this.childFrames();
-		for (const child of children) {
-			const childNodes = await child.getAccessibilityTree(false);
-			nodes.push(...childNodes);
+			({nodes} = await runLocatorStep(progress, "reading accessibility tree", () => this.session.send("Accessibility.getFullAXTree")));
 		}
 		return nodes;
 	}
@@ -17125,22 +17121,12 @@ var Frame = class Frame {
 		progress.throwIfStopped();
 		return base64ToBytes$1(data);
 	}
-	/** Child frames via Page.getFrameTree */
-	async childFrames() {
-		const { frameTree } = await this.session.send("Page.getFrameTree");
-		const frames = [];
-		const collect = (tree) => {
-			if (tree.frame.parentId === this.frameId) frames.push(new Frame(this.session, tree.frame.id, this.pageId, this.remoteBrowser, this.logger));
-			tree.childFrames?.forEach(collect);
-		};
-		collect(frameTree);
-		return frames;
-	}
 	/** Wait for a lifecycle state (load/domcontentloaded/networkidle) */
-	async waitForLoadState(state = "load", timeout = 15e3) {
-		await this.session.send("Page.enable");
+	async waitForLoadState(state = "load", timeout = 15e3, progress) {
+		await runLocatorStep(progress, "enabling load events", () => this.session.send("Page.enable"));
 		const targetState = state.toLowerCase();
 		const effectiveTimeout = Math.max(0, timeout);
+		progress?.throwIfStopped();
 		await new Promise((resolve, reject) => {
 			let done = false;
 			let timer = null;
@@ -17148,6 +17134,7 @@ var Frame = class Frame {
 				if (done) return;
 				done = true;
 				this.session.off("Page.lifecycleEvent", handler);
+				progress?.signal.removeEventListener("abort", finish);
 				if (timer) {
 					clearTimeout(timer);
 					timer = null;
@@ -17160,13 +17147,16 @@ var Frame = class Frame {
 				if (sameFrame && lifecycleName === targetState) finish();
 			};
 			this.session.on("Page.lifecycleEvent", handler);
+			progress?.signal.addEventListener("abort", finish, { once: true });
 			timer = setTimeout(() => {
 				if (done) return;
 				done = true;
 				this.session.off("Page.lifecycleEvent", handler);
+				progress?.signal.removeEventListener("abort", finish);
 				reject(/* @__PURE__ */ new Error(`waitForLoadState(${state}) timed out after ${effectiveTimeout}ms for frame ${this.frameId}`));
 			}, effectiveTimeout);
 		});
+		progress?.throwIfStopped();
 	}
 	/** Simple placeholder for your own locator abstraction */
 	locator(selector, options) {
@@ -18597,11 +18587,12 @@ function missMetadata(response, reason) {
 * or whenever any cache step fails, including `onHit` itself — falls back to
 * `execute` and then persists the outcome's `cacheValue`.
 */
-async function withCache({ method, page, data, caching, bypass, context, logger, onHit, execute }) {
+async function withCache({ method, page, data, caching, bypass, context, logger, onHit, execute, progress }) {
+	progress?.throwIfStopped();
 	const resolvedCaching = caching ?? context?.defaultCaching ?? true;
 	const cachePage = resolvedCaching !== false ? asCachePage(page) : null;
 	if (bypass || !context || !cachePage) return (await execute()).result;
-	const cdpTree = await collectCdpTree(cachePage, logger);
+	const cdpTree = await collectCdpTree(cachePage, logger, progress);
 	if (!cdpTree) return (await execute()).result;
 	const baseRequest = {
 		method,
@@ -18612,8 +18603,9 @@ async function withCache({ method, page, data, caching, bypass, context, logger,
 	};
 	let getResponse = null;
 	try {
-		getResponse = await context.client.get(baseRequest);
+		getResponse = await runLocatorStep(progress, "reading cache", () => context.client.get(baseRequest));
 	} catch (error) {
+		progress?.throwIfStopped();
 		logger.warn("Cache read failed; executing without cache", {
 			category: "cache",
 			method,
@@ -18622,7 +18614,7 @@ async function withCache({ method, page, data, caching, bypass, context, logger,
 	}
 	let cacheMetadata;
 	if (getResponse?.hit && getResponse.value !== void 0 && getResponse.value !== null) try {
-		const result = await onHit(getResponse.value);
+		const result = await runLocatorStep(progress, "applying cached result", async () => onHit(getResponse.value));
 		result.metadata.cache = hitMetadata(getResponse);
 		logger.debug("Cache hit", {
 			category: "cache",
@@ -18633,6 +18625,7 @@ async function withCache({ method, page, data, caching, bypass, context, logger,
 		});
 		return result;
 	} catch (error) {
+		progress?.throwIfStopped();
 		logger.warn("Cached value could not be applied; falling back to execution", {
 			category: "cache",
 			method,
@@ -18650,14 +18643,16 @@ async function withCache({ method, page, data, caching, bypass, context, logger,
 			missReason: cacheMetadata.missReason ?? "unknown"
 		});
 	} else cacheMetadata = missMetadata(null, "read_failed");
+	progress?.throwIfStopped();
 	const outcome = await execute();
+	progress?.throwIfStopped();
 	outcome.result.metadata.cache = cacheMetadata;
 	if (outcome.cacheValue !== void 0 && outcome.cacheValue !== null) try {
-		const setResponse = await context.client.set({
+		const setResponse = await runLocatorStep(progress, "writing cache", () => context.client.set({
 			...baseRequest,
 			value: outcome.cacheValue,
 			llmUsage: outcome.llmUsage
-		});
+		}));
 		logger.debug(setResponse.written ? "Cache write completed" : "Cache write skipped", {
 			category: "cache",
 			method,
@@ -18665,6 +18660,7 @@ async function withCache({ method, page, data, caching, bypass, context, logger,
 			skippedReason: setResponse.skippedReason ?? ""
 		});
 	} catch (error) {
+		progress?.throwIfStopped();
 		logger.warn("Cache write failed", {
 			category: "cache",
 			method,
@@ -18699,19 +18695,20 @@ function asCachePage(page) {
 * Collects the verbatim Accessibility.getFullAXTree nodes for every frame.
 * Returns null (skip caching) when the payload can't be assembled.
 */
-async function collectCdpTree(page, logger) {
+async function collectCdpTree(page, logger, progress) {
 	try {
 		const mainFrame = page.mainFrame();
 		const frames = [];
 		for (const frame of page.frames()) frames.push({
 			frameId: frame.frameId,
-			axNodes: await frame.getAccessibilityTree(false)
+			axNodes: await runLocatorStep(progress, "reading cache accessibility tree", () => frame.getAccessibilityTree(progress))
 		});
 		return {
 			rootFrameId: mainFrame.frameId,
 			frames
 		};
 	} catch (error) {
+		progress?.throwIfStopped();
 		logger.warn("Failed to collect CDP tree for cache; executing without cache", {
 			category: "cache",
 			error: error instanceof Error ? error.message : String(error)
@@ -51231,11 +51228,15 @@ function disabledCacheMetadata() {
 }
 //#endregion
 //#region services/actService.ts
-async function act({ params, page, model, clientLLMGenerate, logger, systemPrompt = "", selfHeal = false, domSettleTimeoutMs, cache, gateway }) {
+async function act(options) {
+	return runWithProgress(options.progress ?? {
+		name: "act()",
+		timeout: options.params.options?.timeout ?? 0
+	}, (progress) => actWithProgress(options, progress));
+}
+async function actWithProgress({ params, page, model, clientLLMGenerate, logger, systemPrompt = "", selfHeal = false, domSettleTimeoutMs, cache, gateway }, progress) {
 	const { instruction: actInstruction, options } = params;
 	const variables = options?.variables;
-	const timeout = options?.timeout;
-	const ensureTimeRemaining = createTimeoutGuard(timeout, (ms) => new TimeoutError("act()", ms));
 	let operationUsage = zeroStagehandResultUsage();
 	const recordUsage = (response) => {
 		operationUsage = aggregateUsage(operationUsage, usageFromInference(response));
@@ -51248,11 +51249,11 @@ async function act({ params, page, model, clientLLMGenerate, logger, systemPromp
 		systemPrompt,
 		selfHeal,
 		domSettleTimeoutMs,
-		ensureTimeRemaining,
+		progress,
 		gateway,
 		recordUsage
 	};
-	ensureTimeRemaining();
+	progress.throwIfStopped();
 	if (typeof actInstruction !== "string") return actResult(await takeDeterministicAction({
 		action: actInstruction,
 		variables,
@@ -51263,8 +51264,8 @@ async function act({ params, page, model, clientLLMGenerate, logger, systemPromp
 		focusLocator: options?.locator,
 		ignoreLocators: options?.ignoreLocators
 	};
-	await waitForDomNetworkQuiet(page.mainFrame(), logger, domSettleTimeoutMs);
-	ensureTimeRemaining();
+	await waitForDomNetworkQuiet(page.mainFrame(), logger, domSettleTimeoutMs, progress);
+	progress.throwIfStopped();
 	return await withCache({
 		method: "act",
 		page,
@@ -51273,6 +51274,7 @@ async function act({ params, page, model, clientLLMGenerate, logger, systemPromp
 		bypass: shouldBypassCacheForLocatorScope(options),
 		context: cache,
 		logger,
+		progress,
 		onHit: (value) => replayCachedActions(value, instruction, variables, context),
 		execute: async () => {
 			const result = await runActPipeline();
@@ -51289,9 +51291,9 @@ async function act({ params, page, model, clientLLMGenerate, logger, systemPromp
 		}
 	});
 	async function runActPipeline() {
-		const { combinedTree, combinedXpathMap } = await page.captureSnapshot(snapshotOptions);
+		const { combinedTree, combinedXpathMap } = await page.captureSnapshot(snapshotOptions, progress);
 		const actPrompt = buildActPrompt(instruction, Object.values(SupportedUnderstudyAction), variables);
-		ensureTimeRemaining();
+		progress.throwIfStopped();
 		const firstInference = await getActionFromLLM({
 			instruction: actPrompt,
 			domElements: combinedTree,
@@ -51307,18 +51309,18 @@ async function act({ params, page, model, clientLLMGenerate, logger, systemPromp
 				actions: []
 			}, operationUsage);
 		}
-		ensureTimeRemaining();
+		progress.throwIfStopped();
 		const firstResult = await takeDeterministicAction({
 			action: firstInference.action,
 			variables,
 			context
 		});
 		if (!firstInference.response.twoStep) return actResult(firstResult, operationUsage);
-		ensureTimeRemaining();
-		const { combinedTree: nextTree, combinedXpathMap: nextXpathMap } = await page.captureSnapshot(snapshotOptions);
+		progress.throwIfStopped();
+		const { combinedTree: nextTree, combinedXpathMap: nextXpathMap } = await page.captureSnapshot(snapshotOptions, progress);
 		const changedTree = diffCombinedTrees(combinedTree, nextTree);
 		const secondInstruction = buildStepTwoPrompt(instruction, describeAction(firstInference.action), Object.values(SupportedUnderstudyAction).filter((action) => action !== SupportedUnderstudyAction.SELECT_OPTION_FROM_DROPDOWN), variables);
-		ensureTimeRemaining();
+		progress.throwIfStopped();
 		const secondInference = await getActionFromLLM({
 			instruction: secondInstruction,
 			domElements: changedTree.trim() ? changedTree : nextTree,
@@ -51326,7 +51328,7 @@ async function act({ params, page, model, clientLLMGenerate, logger, systemPromp
 			context
 		});
 		if (!secondInference.action) return actResult(firstResult, operationUsage);
-		ensureTimeRemaining();
+		progress.throwIfStopped();
 		const secondResult = await takeDeterministicAction({
 			action: secondInference.action,
 			variables,
@@ -51369,12 +51371,15 @@ async function replayCachedActions(value, instruction, variables, context) {
 	});
 }
 async function getActionFromLLM({ instruction, domElements, xpathMap, context }) {
-	const response = await act$1({
+	const response = await context.progress.run("waiting for act inference", () => act$1({
 		instruction,
 		domElements,
-		generate: (input) => generate(context.model, input, context.clientLLMGenerate, context.gateway),
+		generate: (input) => {
+			context.progress.throwIfStopped();
+			return generate(context.model, input, context.clientLLMGenerate, context.gateway);
+		},
 		userProvidedInstructions: context.systemPrompt
-	});
+	}));
 	context.recordUsage(response);
 	context.logger.info("Act inference completed", {
 		category: "action",
@@ -51391,7 +51396,7 @@ async function getActionFromLLM({ instruction, domElements, xpathMap, context })
 	} : { response };
 }
 async function takeDeterministicAction({ action, variables, context }) {
-	context.ensureTimeRemaining();
+	context.progress.throwIfStopped();
 	const method = action.method?.trim();
 	if (!method || method === "not-supported") {
 		context.logger.error("Action has no supported method", {
@@ -51408,10 +51413,11 @@ async function takeDeterministicAction({ action, variables, context }) {
 	const placeholderArgs = Array.isArray(action.arguments) ? [...action.arguments] : [];
 	const resolvedArgs = substituteVariablesInArguments(action.arguments, variables) ?? [];
 	try {
-		context.ensureTimeRemaining();
-		await performUnderstudyMethod(context.page, context.page.mainFrame(), method, action.selector, resolvedArgs, context.logger, context.domSettleTimeoutMs);
+		context.progress.throwIfStopped();
+		await performUnderstudyMethod(context.page, context.page.mainFrame(), method, action.selector, resolvedArgs, context.logger, context.progress, context.domSettleTimeoutMs);
 		return successfulActionResult(action, method, action.selector, placeholderArgs);
 	} catch (error) {
+		context.progress.throwIfStopped();
 		if (error instanceof TimeoutError) throw error;
 		const message = error instanceof Error ? error.message : String(error);
 		if (!context.selfHeal) return {
@@ -51437,8 +51443,8 @@ async function takeDeterministicAction({ action, variables, context }) {
 async function selfHealAction({ action, method, resolvedArgs, placeholderArgs, context }) {
 	const actionInstruction = action.description ? action.description.toLowerCase().startsWith(method.toLowerCase()) ? action.description : `${method} ${action.description}` : method;
 	try {
-		context.ensureTimeRemaining();
-		const { combinedTree, combinedXpathMap } = await context.page.captureSnapshot({});
+		context.progress.throwIfStopped();
+		const { combinedTree, combinedXpathMap } = await context.page.captureSnapshot({}, context.progress);
 		const inferenceResult = await getActionFromLLM({
 			instruction: buildActPrompt(actionInstruction, Object.values(SupportedUnderstudyAction), {}),
 			domElements: combinedTree,
@@ -51452,10 +51458,11 @@ async function selfHealAction({ action, method, resolvedArgs, placeholderArgs, c
 			actions: []
 		};
 		const selector = inferenceResult.action?.selector ?? action.selector;
-		context.ensureTimeRemaining();
-		await performUnderstudyMethod(context.page, context.page.mainFrame(), method, selector, resolvedArgs, context.logger, context.domSettleTimeoutMs);
+		context.progress.throwIfStopped();
+		await performUnderstudyMethod(context.page, context.page.mainFrame(), method, selector, resolvedArgs, context.logger, context.progress, context.domSettleTimeoutMs);
 		return successfulActionResult(action, method, selector, placeholderArgs);
 	} catch (error) {
+		context.progress.throwIfStopped();
 		if (error instanceof TimeoutError) throw error;
 		return {
 			success: false,
@@ -51555,9 +51562,14 @@ function transformUrlStringsToNumericIds(schema) {
 	const [finalSchema, urlPaths] = transformSchema(schema, []);
 	return [finalSchema, urlPaths];
 }
-async function extract({ params, page, model, clientLLMGenerate, logger, systemPrompt = "", cache, gateway }) {
+async function extract(options) {
+	return runWithProgress(options.progress ?? {
+		name: "extract()",
+		timeout: options.params.options?.timeout ?? 0
+	}, (progress) => extractWithProgress(options, progress));
+}
+async function extractWithProgress({ params, page, model, clientLLMGenerate, logger, systemPrompt = "", cache, gateway }, progress) {
 	const { instruction, options } = params;
-	const ensureTimeRemaining = createTimeoutGuard(options?.timeout, (ms) => new TimeoutError("extract()", ms));
 	if (options?.screenshot) return (await runExtraction()).result;
 	return await withCache({
 		method: "extract",
@@ -51567,6 +51579,7 @@ async function extract({ params, page, model, clientLLMGenerate, logger, systemP
 		bypass: shouldBypassCacheForLocatorScope(options),
 		context: cache,
 		logger,
+		progress,
 		onHit: (value) => ({
 			data: json$1().parse(value),
 			metadata: {
@@ -51577,21 +51590,17 @@ async function extract({ params, page, model, clientLLMGenerate, logger, systemP
 		execute: () => runExtraction()
 	});
 	async function runExtraction() {
-		ensureTimeRemaining();
+		progress.throwIfStopped();
 		const { combinedTree, combinedUrlMap } = await page.captureSnapshot({
 			focusLocator: options?.locator,
 			ignoreLocators: options?.ignoreLocators
-		});
-		ensureTimeRemaining();
-		const screenshot = options?.screenshot ? await (async () => {
-			ensureTimeRemaining();
-			const image = await page.screenshot({
-				fullPage: false,
-				type: "png"
-			});
-			ensureTimeRemaining();
-			return image;
-		})() : void 0;
+		}, progress);
+		progress.throwIfStopped();
+		const screenshot = options?.screenshot ? await page.screenshot({
+			fullPage: false,
+			type: "png"
+		}, progress) : void 0;
+		progress.throwIfStopped();
 		logger.info(screenshot ? "Starting extraction using an accessibility snapshot and viewport screenshot" : "Starting extraction using an accessibility snapshot", {
 			category: "extraction",
 			instruction
@@ -51605,16 +51614,16 @@ async function extract({ params, page, model, clientLLMGenerate, logger, systemP
 			data: bytesToBase64(screenshot),
 			mimeType: "image/png"
 		} : void 0;
-		ensureTimeRemaining();
+		progress.throwIfStopped();
 		const extractionResponse = await extract$1({
 			instruction,
 			domElements: combinedTree,
 			schema: transformedSchema,
-			generate: (input) => generate(model, input, clientLLMGenerate, gateway),
+			generate: (input) => progress.run("waiting for extract inference", () => generate(model, input, clientLLMGenerate, gateway)),
 			userProvidedInstructions: systemPrompt,
 			screenshot: screenshotContent
 		});
-		ensureTimeRemaining();
+		progress.throwIfStopped();
 		const { metadata: { completed }, prompt_tokens, completion_tokens, reasoning_tokens, cached_input_tokens, inference_time_ms, ...rest } = extractionResponse;
 		let output = rest;
 		const idToUrl = combinedUrlMap ?? {};
@@ -51652,9 +51661,14 @@ async function extract({ params, page, model, clientLLMGenerate, logger, systemP
 //#endregion
 //#region services/observeService.ts
 var DEFAULT_OBSERVE_INSTRUCTION = "Find elements that can be used for any future actions in the page. These may be navigation links, related pages, section/subsection links, buttons, or other interactive elements. Be comprehensive: if there are multiple elements that may be relevant for future actions, return all of them.";
-async function observe({ params, page, model, clientLLMGenerate, logger, systemPrompt = "", cache, gateway }) {
+async function observe(options) {
+	return runWithProgress(options.progress ?? {
+		name: "observe()",
+		timeout: options.params.options?.timeout ?? 0
+	}, (progress) => observeWithProgress(options, progress));
+}
+async function observeWithProgress({ params, page, model, clientLLMGenerate, logger, systemPrompt = "", cache, gateway }, progress) {
 	const { instruction, options } = params;
-	const ensureTimeRemaining = createTimeoutGuard(options?.timeout, (ms) => new TimeoutError("observe()", ms));
 	const effectiveInstruction = instruction ?? DEFAULT_OBSERVE_INSTRUCTION;
 	logger.info("Starting observation", {
 		category: "observation",
@@ -51668,6 +51682,7 @@ async function observe({ params, page, model, clientLLMGenerate, logger, systemP
 		bypass: shouldBypassCacheForLocatorScope(options),
 		context: cache,
 		logger,
+		progress,
 		onHit: (value) => {
 			const actions = normalizeCachedActions(value);
 			if (actions.length === 0) throw new Error("Cached observe value contained no usable actions");
@@ -51682,22 +51697,22 @@ async function observe({ params, page, model, clientLLMGenerate, logger, systemP
 		execute: () => runObservation()
 	});
 	async function runObservation() {
-		ensureTimeRemaining();
+		progress.throwIfStopped();
 		const { combinedTree, combinedXpathMap } = await page.captureSnapshot({
 			focusLocator: options?.locator,
 			ignoreLocators: options?.ignoreLocators
-		});
-		ensureTimeRemaining();
+		}, progress);
+		progress.throwIfStopped();
 		logger.debug("Captured accessibility snapshot for observation", { category: "observation" });
 		const observation = await observe$1({
 			instruction: effectiveInstruction,
 			domElements: combinedTree,
-			generate: (input) => generate(model, input, clientLLMGenerate, gateway),
+			generate: (input) => progress.run("waiting for observe inference", () => generate(model, input, clientLLMGenerate, gateway)),
 			userProvidedInstructions: systemPrompt,
 			supportedActions: Object.values(SupportedUnderstudyAction),
 			variables: options?.variables
 		});
-		ensureTimeRemaining();
+		progress.throwIfStopped();
 		const xpathMap = combinedXpathMap ?? {};
 		const actions = [];
 		for (const element of observation.elements) {
@@ -51738,7 +51753,7 @@ async function observe({ params, page, model, clientLLMGenerate, logger, systemP
 				arguments: resolvedArguments
 			});
 		}
-		ensureTimeRemaining();
+		progress.throwIfStopped();
 		logger.info("Observation completed", {
 			category: "observation",
 			promptTokens: observation.prompt_tokens,
@@ -54370,7 +54385,7 @@ var WebTracerProvider = class extends BasicTracerProvider {
 };
 var package_default = {
 	name: "@browserbasehq/stagehand-extension",
-	version: "1.1.0-alpha-0336409092b85beeba38ea3cd4953f45eb96ed6b",
+	version: "1.1.0-alpha-c9c8a41778b2000c9a9bdfc4b68e6c0c4866ab1a",
 	"private": true,
 	type: "module",
 	scripts: {
@@ -56316,11 +56331,13 @@ var Page = class Page {
 		await this.ensureCursorScript();
 		this.cursorEnabled = true;
 	}
-	async updateCursor(x, y) {
+	async updateCursor(x, y, progress) {
 		if (!this.cursorEnabled) return;
 		try {
-			await this.mainFrameWrapper.evaluateInLocatorWorld(`globalThis.__stagehandLocatorScripts.moveCursorOverlay(${Math.round(x)}, ${Math.round(y)})`);
-		} catch {}
+			await this.mainFrameWrapper.evaluateInLocatorWorld(`globalThis.__stagehandLocatorScripts.moveCursorOverlay(${Math.round(x)}, ${Math.round(y)})`, progress);
+		} catch {
+			progress?.throwIfStopped();
+		}
 	}
 	async addInitScript(script, arg) {
 		const source = await normalizeInitScriptSource(script, arg, "page.addInitScript");
@@ -57462,32 +57479,32 @@ var Page = class Page {
 			button: "none"
 		});
 	}
-	async scroll(x, y, deltaX, deltaY) {
-		await this.updateCursor(x, y);
-		await this.mainSession.send("Input.dispatchMouseEvent", {
+	async scroll(x, y, deltaX, deltaY, progress) {
+		await runLocatorStep(progress, "updating cursor", () => this.updateCursor(x, y, progress));
+		await runLocatorStep(progress, "scrolling page", () => this.mainSession.send("Input.dispatchMouseEvent", {
 			type: "mouseMoved",
 			x,
 			y,
 			button: "none"
-		});
-		await this.mainSession.send("Input.dispatchMouseEvent", {
+		}));
+		await runLocatorStep(progress, "scrolling page", () => this.mainSession.send("Input.dispatchMouseEvent", {
 			type: "mouseWheel",
 			x,
 			y,
 			button: "none",
 			deltaX,
 			deltaY
-		});
+		}));
 	}
 	/**
 	* Drag from (fromX, fromY) to (toX, toY) using mouse events.
 	* Sends mouseMoved → mousePressed → mouseMoved (route or steps) → mouseReleased.
 	*/
-	async dragAndDrop(fromX, fromY, toX, toY, options) {
+	async dragAndDrop(fromX, fromY, toX, toY, options, progress) {
 		const button = options?.button ?? "left";
 		const steps = Math.max(1, Math.floor(options?.steps ?? 1));
 		const delay = Math.max(0, options?.delay ?? 0);
-		const sleep = (ms) => new Promise((r) => ms > 0 ? setTimeout(r, ms) : r());
+		const sleep = (ms) => progress ? progress.delay(ms) : new Promise((r) => ms > 0 ? setTimeout(r, ms) : r());
 		const buttonMask = (b) => {
 			switch (b) {
 				case "left": return 1;
@@ -57496,57 +57513,79 @@ var Page = class Page {
 				default: return 1;
 			}
 		};
-		await this.updateCursor(fromX, fromY);
-		await this.mainSession.send("Input.dispatchMouseEvent", {
+		await runLocatorStep(progress, "updating cursor", () => this.updateCursor(fromX, fromY, progress));
+		await runLocatorStep(progress, "dragging mouse", () => this.mainSession.send("Input.dispatchMouseEvent", {
 			type: "mouseMoved",
 			x: fromX,
 			y: fromY,
 			button: "none"
-		});
-		await this.mainSession.send("Input.dispatchMouseEvent", {
-			type: "mousePressed",
-			x: fromX,
-			y: fromY,
+		}));
+		let pressed = false;
+		let x = fromX;
+		let y = fromY;
+		const release = () => this.mainSession.send("Input.dispatchMouseEvent", {
+			type: "mouseReleased",
+			x,
+			y,
 			button,
 			buttons: buttonMask(button),
 			clickCount: 1
 		});
-		const samePoint = (point, x, y) => point.x === x && point.y === y;
-		const route = options?.route ?? [];
-		let routeStart = 0;
-		let routeEnd = route.length;
-		while (routeStart < routeEnd && samePoint(route[routeStart], fromX, fromY)) routeStart++;
-		while (routeEnd > routeStart && samePoint(route[routeEnd - 1], toX, toY)) routeEnd--;
-		const movementPoints = route.length > 0 ? [...route.slice(routeStart, routeEnd), {
-			x: toX,
-			y: toY
-		}] : Array.from({ length: steps }, (_, index) => {
-			const t = (index + 1) / steps;
-			return {
-				x: fromX + (toX - fromX) * t,
-				y: fromY + (toY - fromY) * t
-			};
-		});
-		for (const { x, y } of movementPoints) {
-			await this.updateCursor(x, y);
-			await this.mainSession.send("Input.dispatchMouseEvent", {
-				type: "mouseMoved",
-				x,
-				y,
-				button,
-				buttons: buttonMask(button)
+		try {
+			progress?.throwIfStopped();
+			await runLocatorStep(progress, "pressing mouse", () => {
+				pressed = true;
+				return this.mainSession.send("Input.dispatchMouseEvent", {
+					type: "mousePressed",
+					x: fromX,
+					y: fromY,
+					button,
+					buttons: buttonMask(button),
+					clickCount: 1
+				});
 			});
-			if (delay) await sleep(delay);
+			const samePoint = (point, x, y) => point.x === x && point.y === y;
+			const route = options?.route ?? [];
+			let routeStart = 0;
+			let routeEnd = route.length;
+			while (routeStart < routeEnd && samePoint(route[routeStart], fromX, fromY)) routeStart++;
+			while (routeEnd > routeStart && samePoint(route[routeEnd - 1], toX, toY)) routeEnd--;
+			const movementPoints = route.length > 0 ? [...route.slice(routeStart, routeEnd), {
+				x: toX,
+				y: toY
+			}] : Array.from({ length: steps }, (_, index) => {
+				const t = (index + 1) / steps;
+				return {
+					x: fromX + (toX - fromX) * t,
+					y: fromY + (toY - fromY) * t
+				};
+			});
+			for (const point of movementPoints) {
+				progress?.throwIfStopped();
+				await runLocatorStep(progress, "updating cursor", () => this.updateCursor(point.x, point.y, progress));
+				await runLocatorStep(progress, "dragging mouse", () => {
+					x = point.x;
+					y = point.y;
+					return this.mainSession.send("Input.dispatchMouseEvent", {
+						type: "mouseMoved",
+						x,
+						y,
+						button,
+						buttons: buttonMask(button)
+					});
+				});
+				if (delay) await sleep(delay);
+			}
+			await runLocatorStep(progress, "updating cursor", () => this.updateCursor(toX, toY, progress));
+			await runLocatorStep(progress, "releasing mouse", () => {
+				pressed = false;
+				return release();
+			});
+		} finally {
+			if (pressed) if (progress) await progress.cleanup(release);
+			else await release().catch(() => {});
 		}
-		await this.updateCursor(toX, toY);
-		await this.mainSession.send("Input.dispatchMouseEvent", {
-			type: "mouseReleased",
-			x: toX,
-			y: toY,
-			button,
-			buttons: buttonMask(button),
-			clickCount: 1
-		});
+		progress?.throwIfStopped();
 	}
 	/**
 	* Type a string by dispatching keyDown/keyUp events per character.
@@ -57646,9 +57685,9 @@ var Page = class Page {
 	* For printable characters, uses the text path on keyDown; for named keys, sets key/code/VK.
 	* Supports key combinations with modifiers like "Cmd+A", "Ctrl+C", "Shift+Tab", etc.
 	*/
-	async keyPress(key, options) {
+	async keyPress(key, options, progress) {
 		const delay = Math.max(0, options?.delay ?? 0);
-		const sleep = (ms) => new Promise((r) => ms > 0 ? setTimeout(r, ms) : r());
+		const sleep = (ms) => progress ? progress.delay(ms) : new Promise((r) => ms > 0 ? setTimeout(r, ms) : r());
 		function split(keyString) {
 			if (keyString === "+") return ["+"];
 			const keys = [];
@@ -57663,13 +57702,19 @@ var Page = class Page {
 		const tokens = split(key);
 		const mainKey = tokens[tokens.length - 1];
 		const modifierKeys = tokens.slice(0, -1);
+		const heldKeys = /* @__PURE__ */ new Set();
 		try {
-			for (const modKey of modifierKeys) await this.keyDown(modKey);
-			await this.keyDown(mainKey);
+			for (const key of [...modifierKeys, mainKey]) await runLocatorStep(progress, "pressing key", () => {
+				heldKeys.add(key);
+				return this.keyDown(key);
+			});
 			if (delay) await sleep(delay);
-			await this.keyUp(mainKey);
-			for (let i = modifierKeys.length - 1; i >= 0; i--) await this.keyUp(modifierKeys[i]);
+			for (const key of [mainKey, ...modifierKeys.toReversed()]) await runLocatorStep(progress, "releasing key", () => {
+				heldKeys.delete(key);
+				return this.keyUp(key);
+			});
 		} catch (error) {
+			if (progress) await progress.cleanup(() => Promise.allSettled([...heldKeys].reverse().map((key) => this.keyUp(key))));
 			this._pressedModifiers.clear();
 			throw error;
 		}

{stagehand-4.2.0a0.dev1575 → stagehand-4.2.0a0.dev1577}/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 = '2.1.0-alpha-0336409092b85beeba38ea3cd4953f45eb96ed6b'
+STAGEHAND_PROTOCOL_VERSION = '2.1.0-alpha-c9c8a41778b2000c9a9bdfc4b68e6c0c4866ab1a'