stagehand 4.3.1a0.dev1658__tar.gz → 4.4.0a0.dev1661__tar.gz

{stagehand-4.3.1a0.dev1658 → stagehand-4.4.0a0.dev1661}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stagehand
-Version: 4.3.1a0.dev1658
+Version: 4.4.0a0.dev1661
 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.1a0.dev1658 → stagehand-4.4.0a0.dev1661}/pyproject.toml

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

{stagehand-4.3.1a0.dev1658 → stagehand-4.4.0a0.dev1661}/src/stagehand/_extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Stagehand Runtime",
-  "minimum_chrome_version": "116",
+  "minimum_chrome_version": "137",
   "permissions": [
     "debugger",
     "offscreen",
@@ -31,5 +31,5 @@
     }
   ],
   "options_page": "wake-service-worker.html",
-  "version": "1.2.1"
+  "version": "1.3.0"
 }

{stagehand-4.3.1a0.dev1658 → stagehand-4.4.0a0.dev1661}/src/stagehand/_extension/service-worker.js

@@ -9206,7 +9206,7 @@ function isRecord$1(value) {
 }
 var package_default$1 = {
 	name: "@browserbasehq/stagehand-protocol",
-	version: "3.0.1-alpha-7d90812785c3ffea93b080982568fca07f952b1f",
+	version: "3.1.1-alpha-44d99dfbdd24baaf06986492792348582266d8f0",
 	"private": true,
 	type: "module",
 	exports: {
@@ -13213,6 +13213,7 @@ var RPCClient = class {
 		this.nextRequestId = 1;
 		this.pending = /* @__PURE__ */ new Map();
 		this.closed = false;
+		this.clientConnected = true;
 		this.runtime.onmessage = (message, runtimeAttachments) => this.receive(message, runtimeAttachments);
 		this.runtime.onclose = (reason) => this.close(reason);
 		this.runtime.onerror = (error) => this.close(error);
@@ -13220,6 +13221,7 @@ var RPCClient = class {
 	async send(method, params, options = {}) {
 		options.signal?.throwIfAborted();
 		if (this.closed) throw new Error("RPC client is closed");
+		if (!this.clientConnected) throw new Error("Stagehand client disconnected");
 		const parentContext = context.active();
 		const span = this.router.runtime.tracing.tracer.startSpan(method.name, {
 			kind: SpanKind.CLIENT,
@@ -13293,6 +13295,14 @@ var RPCClient = class {
 		this.runtime.onerror = void 0;
 		this.runtime.close();
 	}
+	/** Fail reverse RPCs whose client disappeared, allowing instance disposal to drain. */
+	releaseClient() {
+		this.clientConnected = false;
+		for (const [id] of this.pending) this.rejectPending(id, /* @__PURE__ */ new Error("Stagehand client disconnected"));
+	}
+	acceptClient() {
+		this.clientConnected = true;
+	}
 	waitForResponse(id, method, cleanup = () => {}) {
 		return new Promise((resolve, reject) => {
 			this.pending.set(id, {
@@ -56384,7 +56394,7 @@ var WebTracerProvider = class extends BasicTracerProvider {
 };
 var package_default = {
 	name: "@browserbasehq/stagehand-extension",
-	version: "1.2.1-alpha-7d90812785c3ffea93b080982568fca07f952b1f",
+	version: "1.3.0-alpha-44d99dfbdd24baaf06986492792348582266d8f0",
 	"private": true,
 	type: "module",
 	scripts: {
@@ -56591,7 +56601,7 @@ var FrameRegistry = class {
 	* Record that a frame attached. If `parentId` is null and `frameId` differs from the current
 	* root, this is a root swap and we rename the root id.
 	*
-	* IMPORTANT: The emitter's `sessionId` is the **owner** for the new/attached frame.
+	* The provided `sessionId` is the selected **owner** for the new/attached frame.
 	*/
 	onFrameAttached(frameId, parentId, sessionId) {
 		if (!parentId && frameId !== this.rootFrameId) {
@@ -58439,7 +58449,7 @@ var Page = class Page {
 	}
 	/**
 	* Parent/child session emitted a `frameAttached`.
-	* Topology update + ownership stamped to **emitting session**.
+	* Topology update + ownership stamped to the session selected by Context.
 	*/
 	onFrameAttached(frameId, parentId, session) {
 		this.ensureOrdinal(frameId);
@@ -58487,7 +58497,7 @@ var Page = class Page {
 	* An OOPIF child session whose **main** frame id equals the parent iframe’s frameId
 	* has been attached; adopt the session into this Page and seed ownership for its subtree.
 	*/
-	adoptOopifSession(childSession, childMainFrameId) {
+	adoptOopifSession(childSession, childMainFrameId, onFrameTreeSeeded) {
 		if (this.disposed) return;
 		const previous = childSession.id ? this.sessions.get(childSession.id) : void 0;
 		if (childSession.id) this.sessions.set(childSession.id, childSession);
@@ -58502,9 +58512,6 @@ var Page = class Page {
 		childSession.on("Page.frameNavigated", (evt) => {
 			this.onFrameNavigated(evt.frame, childSession);
 		});
-		childSession.on("Page.frameAttached", (evt) => {
-			this.onFrameAttached(evt.frameId, evt.parentFrameId ?? null, childSession);
-		});
 		childSession.on("Page.frameDetached", (evt) => {
 			this.onFrameDetached(evt.frameId, evt.reason ?? "remove");
 		});
@@ -58522,6 +58529,7 @@ var Page = class Page {
 				if (!this.disposed && this.sessions.get(childSession.id ?? "") === childSession) {
 					this.registry.seedFromFrameTree(childSession.id ?? "child", frameTree);
 					this.reconcilePendingWebMCPTools();
+					onFrameTreeSeeded?.();
 				}
 			} catch {}
 		})();
@@ -60379,6 +60387,7 @@ var StagehandRuntime = class {
 		this.state = createStore()(() => StagehandRuntimeStateSchema.parse({ status: "idle" }));
 		this.pagesById = /* @__PURE__ */ new Map();
 		this.pageEventSubscriptions = /* @__PURE__ */ new Map();
+		this.browserConnectionGeneration = 0;
 		this.initializationInProgress = false;
 		this.lifecycleTail = Promise.resolve();
 		this.stagehandInstanceClosing = false;
@@ -60387,6 +60396,7 @@ var StagehandRuntime = class {
 	}
 	async replaceBrowserConnection(params, bootstrapLogger) {
 		const { cdpUrl } = params;
+		const generation = ++this.browserConnectionGeneration;
 		const previousSession = this.browserSession;
 		this.browserSession = void 0;
 		this.browserSessionCdpUrl = void 0;
@@ -60395,14 +60405,35 @@ var StagehandRuntime = class {
 		this.responseHandles.clear();
 		await previousSession?.close();
 		try {
-			this.browserSession = await this.adapters.browserSessionFactory(cdpUrl, this.logger, bootstrapLogger);
+			const session = await this.adapters.browserSessionFactory(cdpUrl, this.logger, bootstrapLogger);
+			if (generation !== this.browserConnectionGeneration) {
+				await session.close();
+				throw new Error("Stagehand browser connection was dropped while connecting");
+			}
+			this.browserSession = session;
 			this.browserSessionCdpUrl = cdpUrl;
 		} catch (error) {
-			await this.browserSession?.close();
-			this.browserSession = void 0;
+			if (generation === this.browserConnectionGeneration) {
+				await this.browserSession?.close();
+				this.browserSession = void 0;
+			}
 			throw error;
 		}
 	}
+	/**
+	* Closes the runtime's own browser connection immediately, outside the lifecycle
+	* queue: a lost client must not wait behind lifecycle work that needs that client.
+	*/
+	async dropBrowserConnection() {
+		this.browserConnectionGeneration += 1;
+		const session = this.browserSession;
+		this.browserSession = void 0;
+		this.browserSessionCdpUrl = void 0;
+		await session?.close();
+	}
+	async ensureBrowserConnection(cdpUrl) {
+		if (!this.browserSession?.connected || this.browserSessionCdpUrl !== cdpUrl) await this.replaceBrowserConnection({ cdpUrl });
+	}
 	async initialize(params, logger = this.logger) {
 		if (this.initializationInProgress) throw new Error("Stagehand initialization is already in progress");
 		this.initializationInProgress = true;
@@ -61394,6 +61425,96 @@ function getDomainPolicyDecision(url, policy) {
 	};
 	return { action: "continue" };
 }
+var RequestSchema = discriminatedUnion("action", [strictObject({
+	action: literal("attach"),
+	targetId: string().min(1),
+	cdpUrl: string().min(1),
+	closeBrowserOnDisconnect: boolean()
+}), strictObject({
+	action: literal("detach"),
+	targetId: string().min(1)
+})]);
+/** Browser-side ownership of one SDK attachment. No heartbeat or expiry timer. */
+var ClientLifecycle = class {
+	constructor(options) {
+		this.options = options;
+		this.tail = Promise.resolve();
+	}
+	handle(input) {
+		const request = RequestSchema.parse(input);
+		return this.enqueue(async () => {
+			if (request.action === "detach") {
+				const attachment = this.attachment;
+				if (attachment?.targetId !== request.targetId) {
+					if (this.detachedTargetId === request.targetId) return;
+					throw new Error("Stagehand client attachment is no longer active");
+				}
+				attachment.closeBrowserOnDisconnect = false;
+				this.options.rejectClientCallbacks();
+				await this.options.closeConnection();
+				this.removeAttachment();
+				this.detachedTargetId = request.targetId;
+				this.options.disposeClient().catch((error) => this.options.onError(error));
+				return;
+			}
+			if (this.attachment) {
+				const previous = this.attachment;
+				if ((await previous.connection.getTargets()).some((target) => target.targetId === previous.targetId)) throw new Error("A Stagehand client is already connected");
+				await this.lost(previous);
+			}
+			const connection = await this.options.connection(request.cdpUrl);
+			const attachment = {
+				...request,
+				connection,
+				onDestroyed: ({ targetId }) => {
+					if (targetId !== request.targetId) return;
+					this.enqueue(() => this.lost(attachment)).catch((error) => this.options.onError(error));
+				}
+			};
+			this.attachment = attachment;
+			connection.on("Target.targetDestroyed", attachment.onDestroyed);
+			try {
+				const target = (await connection.getTargets()).find((target) => target.targetId === request.targetId);
+				if (!target) {
+					await this.lost(attachment);
+					throw new Error("Stagehand client disconnected during registration");
+				}
+				if (target.url !== "about:blank#stagehand-client-connection") throw new Error("Invalid Stagehand client connection target");
+			} catch (error) {
+				if (this.attachment === attachment) this.removeAttachment();
+				throw error;
+			}
+		});
+	}
+	async lost(attachment) {
+		if (this.attachment !== attachment) return;
+		this.removeAttachment();
+		if (attachment.closeBrowserOnDisconnect) {
+			try {
+				await attachment.connection.send("Browser.close");
+			} catch (error) {
+				if (attachment.connection.connected) throw error;
+			}
+			return;
+		}
+		this.options.rejectClientCallbacks();
+		try {
+			await this.options.closeConnection();
+		} finally {
+			this.options.disposeClient().catch((error) => this.options.onError(error));
+		}
+	}
+	removeAttachment() {
+		const attachment = this.attachment;
+		this.attachment = void 0;
+		attachment?.connection.off("Target.targetDestroyed", attachment.onDestroyed);
+	}
+	enqueue(work) {
+		const result = this.tail.then(work, work);
+		this.tail = result.catch(() => void 0);
+		return result;
+	}
+};
 //#endregion
 //#region understudy/context.ts
 function isMissingTargetError(error) {
@@ -61414,12 +61535,13 @@ function hasInjectableDOM(url) {
 	return false;
 }
 function isNonWebTarget(info) {
+	if (info.url === "about:blank#stagehand-client-connection") return true;
 	if (info.type === "page") return false;
 	return info.type !== "iframe" || !hasInjectableDOM(info.url);
 }
 function isTopLevelPage(info) {
 	const ti = info;
-	return info.type === "page" && ti.subtype !== "iframe";
+	return info.type === "page" && ti.subtype !== "iframe" && info.url !== "about:blank#stagehand-client-connection";
 }
 var DEFAULT_ACTIVE_PAGE_TIMEOUT_MS = 3e3;
 /**
@@ -61450,6 +61572,8 @@ var BrowserContext = class BrowserContext {
 		this.sessionOwnerPage = /* @__PURE__ */ new Map();
 		this.frameOwnerPage = /* @__PURE__ */ new Map();
 		this.pendingOopifByMainFrame = /* @__PURE__ */ new Map();
+		this.pendingOopifParentByMainFrame = /* @__PURE__ */ new Map();
+		this.adoptedOopifSessionByFrame = /* @__PURE__ */ new Map();
 		this.createdAtByTarget = /* @__PURE__ */ new Map();
 		this.typeByTarget = /* @__PURE__ */ new Map();
 		this.pendingCreatedTargetUrl = /* @__PURE__ */ new Map();
@@ -61775,6 +61899,8 @@ var BrowserContext = class BrowserContext {
 		this.sessionOwnerPage.clear();
 		this.frameOwnerPage.clear();
 		this.pendingOopifByMainFrame.clear();
+		this.pendingOopifParentByMainFrame.clear();
+		this.adoptedOopifSessionByFrame.clear();
 		this.createdAtByTarget.clear();
 		this.typeByTarget.clear();
 		this.pendingCreatedTargetUrl.clear();
@@ -61979,34 +62105,91 @@ var BrowserContext = class BrowserContext {
 				this.pendingCreatedTargetUrl.delete(info.targetId);
 				page.seedCurrentUrl(pendingSeedUrl ?? info.url ?? "");
 				this.installFrameEventBridges(sessionId, page);
+				this.adoptPendingOopifsByParent();
 				await this.applyInitScriptsToPage(page, { seedOnly: scriptsInstalled });
 				return;
 			}
 			try {
 				const { frameTree } = await session.send("Page.getFrameTree");
 				const childMainId = frameTree.frame.id;
-				let owner = this.frameOwnerPage.get(childMainId);
-				if (!owner) {
-					for (const p of this.pagesByTarget.values()) if ((function find(n) {
-						if (n.frame.id === childMainId) return true;
-						for (const c of n.childFrames ?? []) if (find(c)) return true;
-						return false;
-					})(p.asProtocolFrameTree(p.mainFrameId()))) {
-						owner = p;
-						break;
-					}
-				}
+				const parentFrameId = frameTree.frame.parentId;
+				const owner = this.findPageOwningFrame(childMainId) ?? (parentFrameId ? this.findPageOwningFrame(parentFrameId) : void 0);
 				if (owner) {
-					owner.adoptOopifSession(session, childMainId);
-					this.sessionOwnerPage.set(sessionId, owner);
-					this.installFrameEventBridges(sessionId, owner);
-					executionContexts.waitForMainWorld(session, childMainId).catch(() => {});
-				} else this.pendingOopifByMainFrame.set(childMainId, sessionId);
+					this.adoptOopif(owner, session, childMainId);
+					this.adoptPendingOopifsByParent();
+				} else {
+					this.pendingOopifByMainFrame.set(childMainId, sessionId);
+					if (parentFrameId) this.pendingOopifParentByMainFrame.set(childMainId, parentFrameId);
+				}
 			} catch {}
 		} finally {
 			await resume();
 		}
 	}
+	/**
+	* Page whose frame graph contains `frameId`, including adopted OOPIF roots.
+	*/
+	findPageOwningFrame(frameId) {
+		const known = this.frameOwnerPage.get(frameId);
+		if (known) {
+			if (this.pagesByTarget.get(known.targetId()) === known && known.registry.frames.has(frameId)) return known;
+			this.frameOwnerPage.delete(frameId);
+		}
+		for (const p of this.pagesByTarget.values()) if (p.listAllFrameIds().includes(frameId)) return p;
+	}
+	adoptOopif(owner, session, childMainId) {
+		owner.adoptOopifSession(session, childMainId, () => {
+			this.adoptPendingOopifsByParent();
+		});
+		this.adoptedOopifSessionByFrame.set(childMainId, session.id);
+		this.sessionOwnerPage.set(session.id, owner);
+		this.frameOwnerPage.set(childMainId, owner);
+		this.installFrameEventBridges(session.id, owner);
+		executionContexts.waitForMainWorld(session, childMainId).catch(() => {});
+	}
+	removePendingOopif(frameId) {
+		this.pendingOopifByMainFrame.delete(frameId);
+		this.pendingOopifParentByMainFrame.delete(frameId);
+	}
+	removePendingOopifsForPage(page) {
+		const pageFrameIds = /* @__PURE__ */ new Set([page.mainFrameId(), ...page.registry.frames.keys()]);
+		for (const [frameId, owner] of this.frameOwnerPage) if (owner === page) pageFrameIds.add(frameId);
+		let removed;
+		do {
+			removed = false;
+			for (const [frameId] of this.pendingOopifByMainFrame) {
+				const parentId = this.pendingOopifParentByMainFrame.get(frameId);
+				if (!pageFrameIds.has(frameId) && (!parentId || !pageFrameIds.has(parentId))) continue;
+				pageFrameIds.add(frameId);
+				this.removePendingOopif(frameId);
+				removed = true;
+			}
+		} while (removed);
+	}
+	/**
+	* An OOPIF that already existed when we attached (e.g. reconnecting to a live
+	* browser, or a nested OOPIF) never emits `frameAttached` on its parent, so the
+	* pending map would hold it forever. Adopt it once the page owning its parent is known.
+	*/
+	adoptPendingOopifsByParent() {
+		let adopted = true;
+		while (adopted) {
+			adopted = false;
+			for (const [childMainId, parentFrameId] of Array.from(this.pendingOopifParentByMainFrame.entries())) {
+				const childSessionId = this.pendingOopifByMainFrame.get(childMainId);
+				const child = childSessionId ? this.conn.getSession(childSessionId) : void 0;
+				if (!child) {
+					this.removePendingOopif(childMainId);
+					continue;
+				}
+				const owner = this.findPageOwningFrame(parentFrameId);
+				if (!owner) continue;
+				this.removePendingOopif(childMainId);
+				this.adoptOopif(owner, child, childMainId);
+				adopted = true;
+			}
+		}
+	}
 	async closePopupIfBlockedByDomainPolicy(info, source) {
 		if (!this.domainPolicy || !isTopLevelPage(info)) return false;
 		if (!info.openerId && !info.openerFrameId) return false;
@@ -62055,13 +62238,16 @@ var BrowserContext = class BrowserContext {
 	* - Drop any staged child for this session.
 	*/
 	onDetachedFromTarget(sessionId, targetId) {
+		const closingPage = targetId ? this.pagesByTarget.get(targetId) : void 0;
+		if (closingPage) this.removePendingOopifsForPage(closingPage);
 		const owner = this.sessionOwnerPage.get(sessionId);
 		if (owner) {
 			owner.detachOopifSession(sessionId);
 			this.sessionOwnerPage.delete(sessionId);
 		}
 		if (targetId && this.pagesByTarget.has(targetId)) this.cleanupByTarget(targetId);
-		for (const [fid, sid] of Array.from(this.pendingOopifByMainFrame.entries())) if (sid === sessionId) this.pendingOopifByMainFrame.delete(fid);
+		for (const [fid, sid] of Array.from(this.pendingOopifByMainFrame.entries())) if (sid === sessionId) this.removePendingOopif(fid);
+		for (const [fid, sid] of Array.from(this.adoptedOopifSessionByFrame.entries())) if (sid === sessionId) this.adoptedOopifSessionByFrame.delete(fid);
 		this._targetSessionListeners.delete(sessionId);
 		const session = this.conn.getSession(sessionId);
 		if (session) this.uninstallDomainPolicyHandler(session);
@@ -62075,15 +62261,12 @@ var BrowserContext = class BrowserContext {
 		this.recordPageCreationFailure(targetId, /* @__PURE__ */ new Error(`Target closed before page registration (${targetId})`), "Target closed before page registration");
 		const page = this.pagesByTarget.get(targetId);
 		if (!page) return;
+		this.removePendingOopifsForPage(page);
 		page.dispose();
 		const mainId = page.mainFrameId();
 		this.mainFrameToTarget.delete(mainId);
-		this.frameOwnerPage.delete(mainId);
+		for (const [frameId, owner] of this.frameOwnerPage) if (owner === page) this.frameOwnerPage.delete(frameId);
 		for (const [sid, p] of Array.from(this.sessionOwnerPage.entries())) if (p === page) this.sessionOwnerPage.delete(sid);
-		for (const [fid] of Array.from(this.pendingOopifByMainFrame.entries())) {
-			const owner = this.frameOwnerPage.get(fid);
-			if (!owner || owner === page) this.pendingOopifByMainFrame.delete(fid);
-		}
 		this.pagesByTarget.delete(targetId);
 		this.createdAtByTarget.delete(targetId);
 		this.typeByTarget.delete(targetId);
@@ -62096,23 +62279,21 @@ var BrowserContext = class BrowserContext {
 	}
 	/**
 	* Wire Page-domain frame events for a session into the owning Page & mappings.
-	* We forward the *emitting session* with every event so Page can stamp ownership precisely.
+	* Attachments preserve live adopted OOPIF ownership while updating topology.
 	*/
 	installFrameEventBridges(sessionId, owner) {
 		const session = this.conn.getSession(sessionId);
 		if (!session) return;
 		session.on("Page.frameAttached", (evt) => {
 			const { frameId, parentFrameId } = evt;
-			owner.onFrameAttached(frameId, parentFrameId ?? null, session);
+			const adoptedSessionId = this.adoptedOopifSessionByFrame.get(frameId);
+			const adoptedSession = adoptedSessionId ? this.conn.getSession(adoptedSessionId) : void 0;
+			owner.onFrameAttached(frameId, parentFrameId ?? null, adoptedSession ?? session);
 			const pendingChildSessionId = this.pendingOopifByMainFrame.get(frameId);
 			if (pendingChildSessionId) {
 				const child = this.conn.getSession(pendingChildSessionId);
-				if (child) {
-					owner.adoptOopifSession(child, frameId);
-					this.sessionOwnerPage.set(child.id, owner);
-					this.installFrameEventBridges(pendingChildSessionId, owner);
-				}
-				this.pendingOopifByMainFrame.delete(frameId);
+				this.removePendingOopif(frameId);
+				if (child) this.adoptOopif(owner, child, frameId);
 			}
 			this.frameOwnerPage.set(frameId, owner);
 			if (!parentFrameId) {
@@ -62121,6 +62302,7 @@ var BrowserContext = class BrowserContext {
 				if (topTargetId) this.mainFrameToTarget.set(newRoot, topTargetId);
 				this.frameOwnerPage.set(newRoot, owner);
 			}
+			this.adoptPendingOopifsByParent();
 		});
 		session.on("Page.frameDetached", (evt) => {
 			owner.onFrameDetached(evt.frameId, evt.reason ?? "remove");
@@ -62210,7 +62392,7 @@ var STAGEHAND_RUNTIME_VERSION = package_default.version;
 function startStagehandServiceWorker(scope = globalThis, runtime) {
 	const chromeRuntimeClient = new ChromeRuntimeClient(scope, STAGEHAND_SEND_TO_HOST_BINDING);
 	let rpcClient;
-	rpcClient = new RPCClient(chromeRuntimeClient, new RPCRouter(runtime ?? createStagehandRuntime({
+	const activeRuntime = runtime ?? createStagehandRuntime({
 		browserSessionFactory: async (cdpUrl, logger, bootstrapLogger) => {
 			const locatorRuntimeResponse = await fetch(chrome.runtime.getURL("content-script.js"));
 			if (!locatorRuntimeResponse.ok) throw new Error(`Failed to load Stagehand locator runtime: ${locatorRuntimeResponse.status}`);
@@ -62246,7 +62428,32 @@ function startStagehandServiceWorker(scope = globalThis, runtime) {
 			if (!rpcClient) throw new Error("Stagehand RPC client is not connected");
 			return await rpcClient.send(StagehandMethods.llmGenerate, params);
 		}
-	})));
+	});
+	rpcClient = new RPCClient(chromeRuntimeClient, new RPCRouter(activeRuntime));
+	const lifecycle = new ClientLifecycle({
+		connection: async (cdpUrl) => {
+			await activeRuntime.ensureBrowserConnection(cdpUrl);
+			const session = activeRuntime.browserSession;
+			if (!(session instanceof BrowserContext)) throw new Error("Stagehand client lifecycle requires a CDP browser connection");
+			return session.conn;
+		},
+		rejectClientCallbacks: () => rpcClient?.releaseClient(),
+		closeConnection: () => activeRuntime.dropBrowserConnection(),
+		disposeClient: () => activeRuntime.disposeStagehandInstance(),
+		onError: (error) => {
+			console.error("Stagehand client lifecycle cleanup failed", error);
+		}
+	});
+	scope.__stagehandClientLifecycle = async (input) => {
+		const action = typeof input === "object" && input !== null && "action" in input ? input.action : void 0;
+		try {
+			await lifecycle.handle(input);
+		} catch (error) {
+			if (action === "detach") rpcClient?.acceptClient();
+			throw error;
+		}
+		if (action === "attach") rpcClient?.acceptClient();
+	};
 	scope.__stagehand_runtime = {
 		protocolVersion: STAGEHAND_PROTOCOL_VERSION,
 		serverInfo: {

{stagehand-4.3.1a0.dev1658 → stagehand-4.4.0a0.dev1661}/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.1-alpha-7d90812785c3ffea93b080982568fca07f952b1f'
+STAGEHAND_PROTOCOL_VERSION = '3.1.1-alpha-44d99dfbdd24baaf06986492792348582266d8f0'

{stagehand-4.3.1a0.dev1658 → stagehand-4.4.0a0.dev1661}/src/stagehand/browser.py

@@ -107,26 +107,54 @@ class ResolvedBrowserSource:
             return
         if self._close_task is None:
             self._close_task = asyncio.create_task(_invoke_close(self._close_callback))
-        await asyncio.shield(self._close_task)
+        task = self._close_task
+        try:
+            await asyncio.shield(task)
+        except BaseException:
+            # A failed close (e.g. a transient Browserbase release error) can be retried.
+            if (
+                self._close_task is task
+                and task.done()
+                and not task.cancelled()
+                and task.exception() is not None
+            ):
+                self._close_task = None
+            raise
 
 
 async def _invoke_close(callback: Callable[[], Awaitable[None]]) -> None:
     await callback()
 
 
+async def _noop() -> None:
+    return None
+
+
 @dataclass(frozen=True)
 class _ChromeProfile:
     path: Path
     remove: bool
 
 
+_BROWSER_CLOSE_TIMEOUT_SECONDS = 5.0
+_DISCONNECT_STAGEHAND_TIMEOUT_SECONDS = 10.0
+_BROWSER_DISCONNECTED_MESSAGE = "The browser is disconnected; connect() again to close it"
+
+
 class StagehandBrowser:
     __slots__ = (
         "_attachment",
         "_claimed",
+        "_close_stagehand",
         "_close_callback",
+        "_disconnect_callback",
         "_invalidate_callback",
-        "_terminal_task",
+        "_connected",
+        "_close_without_connection",
+        "_cdp_url",
+        "_state",
+        "_disconnect_task",
+        "_close_task",
         "_context",
         "_origin",
         "_provider",
@@ -141,7 +169,11 @@ class StagehandBrowser:
         close: Callable[[], Awaitable[None]],
         *,
         invalidate: Callable[[], Awaitable[None]] | None = None,
+        disconnect: Callable[[], Awaitable[None]] | None = None,
+        connected: Callable[[], bool] | None = None,
+        close_without_connection: Callable[[], Awaitable[None]] | None = None,
         session_id: str | None = None,
+        cdp_url: str | None = None,
         _token: object | None = None,
     ) -> None:
         if _token is not _BROWSER_TOKEN:
@@ -151,9 +183,18 @@ class StagehandBrowser:
         self._attachment = attachment
         self._close_callback = close
         self._invalidate_callback = invalidate or close
+        self._disconnect_callback = disconnect or _noop
+        self._connected = connected or (lambda: True)
+        # What close() does after an unexpectedly lost connection.
+        self._close_without_connection = close_without_connection or _noop
+        self._cdp_url = cdp_url
         self._claimed = False
-        self._terminal_task: asyncio.Task[None] | None = None
+        self._state: Literal["open", "disconnected", "closed"] = "open"
+        self._disconnect_task: asyncio.Task[None] | None = None
+        self._close_task: asyncio.Task[None] | None = None
         self._context: BrowserContext | None = None
+        # Closes the attached Stagehand instance; disconnect() runs it before the connection.
+        self._close_stagehand: Callable[[], Awaitable[None]] | None = None
         self._session_id = session_id
 
     @property
@@ -169,9 +210,24 @@ class StagehandBrowser:
         """Browserbase session id backing this browser; None for local browsers."""
         return self._session_id
 
+    @property
+    def cdp_url(self) -> str | None:
+        """CDP URL to reconnect with local_browser.connect(); None for Browserbase browsers."""
+        return self._cdp_url
+
     @property
     def closed(self) -> bool:
-        return self._terminal_task is not None
+        """True once ``close()`` or ``disconnect()`` was called."""
+        return self._state != "open"
+
+    @property
+    def connected(self) -> bool:
+        """False once the handle is closed or disconnected, or its connection was lost.
+
+        After a lost connection ``close()`` can still have work to do, such as releasing a
+        Browserbase session.
+        """
+        return self._state == "open" and self._connected()
 
     @property
     def context(self) -> BrowserContext:
@@ -183,18 +239,81 @@ class StagehandBrowser:
         return self._context
 
     def close(self) -> Awaitable[None]:
-        if self._terminal_task is None:
-            self._terminal_task = asyncio.create_task(
-                _run_browser_terminal_callback(self._close_callback),
+        """Close the browser.
+
+        A local browser receives ``Browser.close`` (a launched one is also terminated if
+        it keeps running, and its temporary profile removed unless preserved), and a
+        Browserbase session is released. After ``disconnect()`` it raises: ``connect()``
+        again to close the browser. After an unexpectedly lost connection it still
+        releases a Browserbase session and does nothing for a local browser. Repeated
+        ``close()`` calls do nothing.
+        """
+        if self._close_task is None:
+            if self._state == "disconnected":
+                raise RuntimeError(_BROWSER_DISCONNECTED_MESSAGE)
+            self._close_task = asyncio.create_task(
+                _run_browser_terminal_callback(self._close_callback)
+                if self._connected()
+                else self._close_without_connection_retryable(),
                 name="stagehand-browser-close",
             )
-        return asyncio.shield(self._terminal_task)
+            self._state = "closed"
+        return asyncio.shield(self._close_task)
+
+    async def _close_without_connection_retryable(self) -> None:
+        try:
+            await self._close_without_connection()
+        except BaseException:
+            # Releasing over the Browserbase API can fail transiently: allow a retry.
+            self._close_task = None
+            raise
+
+    def disconnect(self) -> Awaitable[None]:
+        """Close the attached Stagehand instance, then Stagehand's connection.
+
+        The attached instance closes first, including the extension's own connection to
+        the browser. The browser keeps running: Stagehand never closes it or releases its
+        Browserbase session here. Browserbase still ends a session without
+        ``keep_alive`` when its CDP connection closes, so only ``keep_alive`` sessions
+        survive a disconnect. The handle is finished afterwards: ``connect()`` again for
+        a new one. Repeated ``disconnect()`` calls, or ``disconnect()`` after
+        ``close()``, do nothing.
+        """
+        if self._state == "closed" and self._close_task is not None:
+            return asyncio.shield(self._close_task)
+        if self._disconnect_task is None:
+            self._state = "disconnected"
+            self._disconnect_task = asyncio.create_task(
+                self._disconnect_after_closing_stagehand(self._close_stagehand),
+                name="stagehand-browser-disconnect",
+            )
+        return asyncio.shield(self._disconnect_task)
+
+    async def _disconnect_after_closing_stagehand(
+        self, close_stagehand: Callable[[], Awaitable[None]] | None
+    ) -> None:
+        try:
+            try:
+                if close_stagehand is not None:
+                    # stagehand.close() waits for in-flight work without a deadline;
+                    # disconnect() stops waiting and lets go anyway, which also ends that work.
+                    await _close_stagehand_within(
+                        close_stagehand, _DISCONNECT_STAGEHAND_TIMEOUT_SECONDS
+                    )
+            finally:
+                await self._disconnect_callback()
+        except BaseException:
+            # Still connected means nothing was let go: keep the handle usable for a retry.
+            if self._connected():
+                self._state = "open"
+                self._disconnect_task = None
+            raise
 
 
 def _claim_browser(browser: object) -> _ClaimedBrowser:
     if not isinstance(browser, StagehandBrowser):
         raise TypeError("browser must be created by local_browser or browserbase")
-    if browser.closed:
+    if not browser.connected:
         raise RuntimeError("Cannot attach Stagehand to a closed browser")
     if browser._claimed:
         raise RuntimeError("This browser is already attached to a Stagehand instance")
@@ -211,12 +330,15 @@ def _release_browser(browser: StagehandBrowser) -> None:
 def _invalidate_browser(browser: StagehandBrowser) -> Awaitable[None]:
     if not isinstance(browser, StagehandBrowser):
         raise TypeError("browser must be created by local_browser or browserbase")
-    if browser._terminal_task is None:
-        browser._terminal_task = asyncio.create_task(
-            _run_browser_terminal_callback(browser._invalidate_callback),
-            name="stagehand-browser-invalidate",
-        )
-    return asyncio.shield(browser._terminal_task)
+    existing = browser._close_task or browser._disconnect_task
+    if existing is not None:
+        return asyncio.shield(existing)
+    browser._state = "closed"
+    browser._close_task = asyncio.create_task(
+        _run_browser_terminal_callback(browser._invalidate_callback),
+        name="stagehand-browser-invalidate",
+    )
+    return asyncio.shield(browser._close_task)
 
 
 async def _run_browser_terminal_callback(
@@ -225,19 +347,35 @@ async def _run_browser_terminal_callback(
     await callback()
 
 
+async def _close_stagehand_within(
+    close_stagehand: Callable[[], Awaitable[None]], timeout: float
+) -> None:
+    deadline = asyncio.timeout(timeout)
+    try:
+        async with deadline:
+            await close_stagehand()
+    except TimeoutError:
+        # Only this deadline is expected; a TimeoutError from Stagehand itself is a failure.
+        if not deadline.expired():
+            raise
+
+
 def _attach_browser_context(
     browser: StagehandBrowser,
     context: BrowserContext,
+    close_stagehand: Callable[[], Awaitable[None]] | None = None,
 ) -> None:
     if not browser._claimed:
         raise RuntimeError("Cannot attach a browser context before Stagehand claims the browser")
     if browser._context is not None:
         raise RuntimeError("This browser already has a Stagehand context")
     browser._context = context
+    browser._close_stagehand = close_stagehand
 
 
 def _detach_browser_context(browser: StagehandBrowser) -> None:
     browser._context = None
+    browser._close_stagehand = None
 
 
 def _browser_session_metadata(
@@ -325,6 +463,10 @@ async def _connect_browser(
             extension_id=extension_id,
             preloaded_extension=preloaded_extension,
             service_worker_url_includes="service-worker.js",
+            # Only a local browser Stagehand launched without keep_alive is shut down when
+            # this client disappears; Browserbase applies its own keep_alive policy.
+            close_browser_on_disconnect=provider == "local" and owns_source,
+            extension_cdp_url=worker_init_metadata.browser_cdp_url,
         )
         if after_connect is not None:
             await after_connect(cdp_client)
@@ -354,6 +496,13 @@ async def _connect_browser(
 
     connected_client = cdp_client
 
+    async def disconnect() -> None:
+        # Detaching first disarms the extension's watchdog; without that acknowledgement
+        # the socket stays open, since closing it would read as a lost client and could
+        # shut the browser down.
+        await connected_client.detach_client()
+        await connected_client.close()
+
     async def invalidate() -> None:
         try:
             await connected_client.close()
@@ -364,12 +513,28 @@ async def _connect_browser(
     async def close() -> None:
         errors: list[BaseException] = []
         try:
-            if provider == "local" and origin == "connected":
+            if provider == "local":
                 try:
-                    await connected_client.send_command("Browser.close")
+                    # Bounded so an unresponsive Chrome cannot keep a launched one from
+                    # being terminated.
+                    async with asyncio.timeout(_BROWSER_CLOSE_TIMEOUT_SECONDS):
+                        await connected_client.send_command("Browser.close")
                 except CDPConnectionClosedError:
                     pass
-            else:
+                except TimeoutError:
+                    # A launched browser is terminated below; a connected one cannot be.
+                    if origin == "connected":
+                        raise RuntimeError(
+                            "Browser.close did not respond within "
+                            f"{_BROWSER_CLOSE_TIMEOUT_SECONDS} seconds"
+                        ) from None
+        except BaseException as error:
+            errors.append(error)
+        try:
+            # A launched local browser is also terminated if Browser.close failed or
+            # left it running, and its profile removed unless preserved; a Browserbase
+            # session is released.
+            if provider == "browserbase" or origin == "launched":
                 await source.close()
         except BaseException as error:
             errors.append(error)
@@ -391,6 +556,14 @@ async def _connect_browser(
         ),
         close,
         invalidate=invalidate,
+        # Never closes the browser or releases its session. Browserbase still ends a
+        # session without keep_alive once this connection closes.
+        disconnect=disconnect,
+        connected=lambda: not connected_client.closed,
+        # After an unexpected loss, a Browserbase session can still be released over its
+        # API; a local browser is left alone.
+        close_without_connection=source.close if provider == "browserbase" else None,
+        cdp_url=source.cdp_url if provider == "local" else None,
         session_id=(
             worker_init_metadata.browser.session_id if worker_init_metadata.browser else None
         ),

{stagehand-4.3.1a0.dev1658 → stagehand-4.4.0a0.dev1661}/src/stagehand/cdp_client.py

@@ -15,7 +15,7 @@ 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 websockets.exceptions import ConnectionClosed, InvalidStatus
 
 from stagehand._generated.protocol_version import (
     PROTOCOL_SEMVER_PATTERN,
@@ -239,6 +239,9 @@ class CDPConnectionClosedError(RuntimeError):
         super().__init__("CDP connection closed")
 
 
+_CLIENT_TARGET_URL = "about:blank#stagehand-client-connection"
+
+
 class CDPClient:
     def __init__(
         self,
@@ -253,6 +256,9 @@ class CDPClient:
         self._session_id: str | None = None
         self._service_worker: ServiceWorkerInfo | None = None
         self._closed = False
+        self._client_target_id: str | None = None
+        # Whether the extension shuts the browser down if this client is lost.
+        self._client_close_browser_on_loss = False
         self._background_tasks: set[asyncio.Task[dict[str, object]]] = set()
         self._reader = asyncio.create_task(self._read(), name="stagehand-cdp-reader")
 
@@ -267,6 +273,8 @@ class CDPClient:
         preloaded_extension: bool = False,
         service_worker_url_includes: str | None = None,
         headers: Mapping[str, str] | None = None,
+        close_browser_on_disconnect: bool | None = None,
+        extension_cdp_url: str | None = None,
     ) -> CDPClient:
         """Connect without an independent lifecycle deadline.
 
@@ -338,17 +346,104 @@ class CDPClient:
                 session_id=session_id,
             )
             await client._wait_for_runtime_receiver(session_id)
+            if close_browser_on_disconnect is not None:
+                await client._register_client(
+                    close_browser_on_disconnect,
+                    extension_cdp_url or web_socket_debugger_url,
+                )
             return client
         except BaseException:
             await asyncio.shield(client.close())
             raise
 
+    @property
+    def closed(self) -> bool:
+        return self._closed
+
     @property
     def service_worker(self) -> ServiceWorkerInfo:
         if self._service_worker is None:
             raise RuntimeError("Stagehand service worker is not attached")
         return self._service_worker
 
+    async def _register_client(self, close_browser_on_disconnect: bool, cdp_url: str) -> None:
+        marker = await self.send_command(
+            "Target.createTarget",
+            {"url": _CLIENT_TARGET_URL, "hidden": True, "background": True},
+        )
+        target_id = _required_string(marker, "targetId", "Target.createTarget")
+        # Chrome accepts unknown parameters: a build without hidden targets opens an
+        # ordinary tab that outlives this connection and would never signal its loss.
+        info = await self.send_command("Target.getTargetInfo", {"targetId": target_id})
+        target_info = info.get("targetInfo")
+        if not isinstance(target_info, dict) or target_info.get("type") != "other":
+            await self.send_command("Target.closeTarget", {"targetId": target_id})
+            raise RuntimeError(
+                "Stagehand requires Chrome 137 or later, which supports hidden targets"
+            )
+        if not await self._client_lifecycle_command({
+            "action": "attach",
+            "targetId": target_id,
+            "cdpUrl": cdp_url,
+            "closeBrowserOnDisconnect": close_browser_on_disconnect,
+        }):
+            # The protocol handshake already rejects older extensions; this one is
+            # inconsistent.
+            await self.send_command("Target.closeTarget", {"targetId": target_id})
+            raise RuntimeError(
+                "The Stagehand extension in this browser does not support the client "
+                "watchdog; update the extension"
+            )
+        self._client_target_id = target_id
+        self._client_close_browser_on_loss = close_browser_on_disconnect
+
+    async def detach_client(self) -> None:
+        """Acknowledge intentional detach before the socket/hidden target disappears."""
+        if self._client_target_id is None or self._closed:
+            return
+        try:
+            async with asyncio.timeout(10):
+                acknowledged = await self._client_lifecycle_command({
+                    "action": "detach",
+                    "targetId": self._client_target_id,
+                })
+        except CDPConnectionClosedError:
+            # Browserbase ends a keep_alive=False session once the extension closes its own
+            # connection, which closes this one before the acknowledgement arrives: the
+            # detach happened. A failure or timeout with this connection open still raises,
+            # and so does a lost connection when the extension shuts the browser down on
+            # loss: it may not have received the detach.
+            if self._client_close_browser_on_loss:
+                raise
+            acknowledged = True
+        if not acknowledged:
+            raise RuntimeError("The Stagehand extension did not acknowledge the detach")
+        self._client_target_id = None
+
+    async def _client_lifecycle_command(self, params: dict[str, object]) -> bool:
+        """Return False when the extension has no client lifecycle support."""
+        expression = (
+            "(async () => { "
+            'if (typeof globalThis.__stagehandClientLifecycle !== "function") return false; '
+            f"await globalThis.__stagehandClientLifecycle({json.dumps(params)}); "
+            "return true; })()"
+        )
+        result = await self.send_command(
+            "Runtime.evaluate",
+            {"expression": expression, "awaitPromise": True, "returnByValue": True},
+            session_id=self._session_id,
+        )
+        value = result.get("result")
+        if (
+            result.get("exceptionDetails")
+            or not isinstance(value, dict)
+            or not isinstance(value.get("value"), bool)
+        ):
+            raise RuntimeError(
+                f"Stagehand client lifecycle failed: {result.get('exceptionDetails')}"
+            )
+        return bool(value["value"])
+
     async def send(
         self,
         message: dict[str, object],
@@ -415,7 +510,10 @@ class CDPClient:
             message["sessionId"] = session_id
 
         try:
-            await self._socket.send(json.dumps(message, separators=(",", ":")))
+            try:
+                await self._socket.send(json.dumps(message, separators=(",", ":")))
+            except ConnectionClosed as error:
+                raise CDPConnectionClosedError() from error
             result = await response
         except BaseException:
             if not response.done():

{stagehand-4.3.1a0.dev1658 → stagehand-4.4.0a0.dev1661}/src/stagehand/stagehand.py

@@ -296,6 +296,7 @@ class Stagehand:
         _attach_browser_context(
             self._browser_handle,
             BrowserContext(rpc_client, self._browser_handle.close),
+            self.close,
         )
         self._initialized = True