stagehand 4.0.3a0.dev1474__tar.gz → 4.0.3a0.dev1476__tar.gz

{stagehand-4.0.3a0.dev1474 → stagehand-4.0.3a0.dev1476}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stagehand
-Version: 4.0.3a0.dev1474
+Version: 4.0.3a0.dev1476
 Summary: Browserbase's SDK for building browser agents
 Keywords: ai,browser,automation,web-scraping,testing
 Author: Browserbase

{stagehand-4.0.3a0.dev1474 → stagehand-4.0.3a0.dev1476}/pyproject.toml

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

{stagehand-4.0.3a0.dev1474 → stagehand-4.0.3a0.dev1476}/src/stagehand/_extension/service-worker.js

@@ -7359,7 +7359,7 @@ function isRecord$1(value) {
 }
 var package_default$1 = {
 	name: "@browserbasehq/stagehand-protocol",
-	version: "2.0.0-alpha-d49d643ce9311f16b3ab21289c3bcc01bf0eb097",
+	version: "2.0.0-alpha-6555e81e837012088eb12a39c06aed0527a2e5af",
 	"private": true,
 	type: "module",
 	scripts: {
@@ -8302,7 +8302,6 @@ var PageNavigationOptionsSchema = strictObject({
 }).meta({ id: "PageNavigationOptions" });
 var PageVoidResultSchema = strictObject({ ok: literal(true) }).meta({ id: "PageVoidResult" });
 var ContextVoidResultSchema = strictObject({ ok: literal(true) }).meta({ id: "ContextVoidResult" });
-var ContextCloseResultSchema = strictObject({ closed: literal(true) }).meta({ id: "ContextCloseResult" });
 var PageScreenshotClipSchema = strictObject({
 	x: number$1(),
 	y: number$1(),
@@ -8784,11 +8783,6 @@ var StagehandMethods = {
 		params: ContextSetActivePageParamsSchema,
 		result: ContextVoidResultSchema
 	},
-	contextClose: {
-		name: "context.close",
-		params: EmptyParamsSchema,
-		result: ContextCloseResultSchema
-	},
 	contextAddInitScript: {
 		name: "context.add_init_script",
 		params: ContextAddInitScriptParamsSchema,
@@ -11460,7 +11454,9 @@ var RPCClient = class {
 			});
 			return;
 		}
+		let releaseStagehandInstanceRequest;
 		try {
+			if (request.data.method !== StagehandMethods.stagehandInit.name && request.data.method !== StagehandMethods.stagehandClose.name) releaseStagehandInstanceRequest = this.router.runtime.acquireStagehandInstanceRequest();
 			const result = await this.router.handle(stagehandRequest.data, runtimeAttachments);
 			const parsedResult = method.result.safeParse(result);
 			if (!parsedResult.success) {
@@ -11470,6 +11466,7 @@ var RPCClient = class {
 				});
 				return;
 			}
+			await this.router.beforeResponse(stagehandRequest.data);
 			await this.runtime.send(JSONRPCSuccessResponseSchema.parse({
 				jsonrpc: "2.0",
 				id: request.data.id,
@@ -11484,6 +11481,8 @@ var RPCClient = class {
 				return;
 			}
 			await this.sendError(request.data.id, JSONRPCErrorCodes.internalError, error instanceof Error ? error.message : String(error), { name: error instanceof Error ? error.name : "Error" });
+		} finally {
+			releaseStagehandInstanceRequest?.();
 		}
 	}
 	receiveResponse(response) {
@@ -11550,10 +11549,6 @@ function createContextController(runtime) {
 		logger.debug("context.set_active_page", {});
 		return runtime.contextSetActivePage(params);
 	}
-	async function close(_params, { logger }) {
-		logger.debug("context.close", {});
-		return runtime.contextClose();
-	}
 	async function addInitScript(params, { logger }) {
 		logger.debug("context.add_init_script", {});
 		return runtime.contextAddInitScript(params);
@@ -11611,7 +11606,6 @@ function createContextController(runtime) {
 		newPage,
 		activePage,
 		setActivePage,
-		close,
 		addInitScript,
 		setExtraHTTPHeaders,
 		getDomainPolicy,
@@ -12330,8 +12324,9 @@ function reportPageEventListenerError(error) {
 //#endregion
 //#region ../sdk-ts/src/browserContext.ts
 var BrowserContext$1 = class {
-	constructor(rpcClient) {
+	constructor(rpcClient, closeBrowser) {
 		this.rpcClient = rpcClient;
+		this.closeBrowser = closeBrowser;
 	}
 	get clipboard() {
 		return this.clipboardRef ??= new BrowserClipboard(this.rpcClient);
@@ -12351,9 +12346,10 @@ var BrowserContext$1 = class {
 	async setActivePage(page) {
 		await this.rpcClient.send(StagehandMethods.contextSetActivePage, { pageId: page.pageId });
 	}
-	/** Close the remote context. Call Stagehand.close() to dispose the SDK's local resources. */
+	/** Close the underlying browser. */
 	async close() {
-		await this.rpcClient.send(StagehandMethods.contextClose, {});
+		if (!this.closeBrowser) throw new Error("Browser context is not attached to a browser");
+		await this.closeBrowser();
 	}
 	async addInitScript(script, arg) {
 		const source = await normalizeInitScriptSource$1(script, arg, "context.addInitScript");
@@ -50846,13 +50842,13 @@ async function observe({ params, page, model, clientLLMGenerate, logger, systemP
 //#endregion
 //#region controllers/stagehandController.ts
 function createStagehandController(runtime, options = {}) {
-	const closeRuntime = options.close ?? (() => runtime.close());
+	const closeRuntime = options.close ?? (() => runtime.disposeStagehandInstance());
 	async function runOperation(name, { logger, telemetryScope }, run) {
 		return await logger.span(name, {}, (logger) => runtime.runWithTelemetryContext(telemetryScope, logger, () => run(logger)));
 	}
 	async function init(params, { logger }) {
 		const compatibility = checkProtocolCompatibility(params.protocolVersion, STAGEHAND_PROTOCOL_VERSION);
-		if (!compatibility.compatible) throw new StagehandProtocolCompatibilityError(compatibility.reason);
+		if (compatibility.compatible === false) throw new StagehandProtocolCompatibilityError(compatibility.reason);
 		logger.setLevel(params.logLevel);
 		logger.info("stagehand.init", {});
 		return options.initialize ? await options.initialize(params) : await runtime.initialize(params, logger);
@@ -50961,7 +50957,7 @@ var RPCRouter = class {
 	}
 	async handle(request, runtimeAttachments) {
 		const initParams = request.method === StagehandMethods.stagehandInit.name ? request.params : void 0;
-		if (initParams) this.runtime.tracing.configure(initParams.telemetry, initParams.clientInfo);
+		if (initParams) await this.runtime.tracing.configure(initParams.telemetry, initParams.clientInfo);
 		const parentContext = W3C_TRACE_CONTEXT_PROPAGATOR.extract(ROOT_CONTEXT, request, {
 			get(carrier, key) {
 				if (key === "traceparent" || key === "tracestate") return carrier[key];
@@ -50996,9 +50992,12 @@ var RPCRouter = class {
 			throw error;
 		} finally {
 			span.end();
-			if (request.method === StagehandMethods.stagehandClose.name) await this.runtime.tracing.shutdown();
 		}
 	}
+	async beforeResponse(request) {
+		if (request.method !== StagehandMethods.stagehandClose.name) return;
+		await this.runtime.tracing.forceFlush().catch(() => void 0);
+	}
 	async route(request, context, parsedInitParams) {
 		switch (request.method) {
 			case "stagehand.init": return this.stagehandController.init(parsedInitParams ?? parseParams(StagehandMethods.stagehandInit, request.params), context);
@@ -51012,7 +51011,6 @@ var RPCRouter = class {
 			case "context.new_page": return this.contextController.newPage(parseParams(StagehandMethods.contextNewPage, request.params), context);
 			case "context.active_page": return this.contextController.activePage(parseParams(StagehandMethods.contextActivePage, request.params), context);
 			case "context.set_active_page": return this.contextController.setActivePage(parseParams(StagehandMethods.contextSetActivePage, request.params), context);
-			case "context.close": return this.contextController.close(parseParams(StagehandMethods.contextClose, request.params), context);
 			case "context.add_init_script": return this.contextController.addInitScript(parseParams(StagehandMethods.contextAddInitScript, request.params), context);
 			case "context.set_extra_http_headers": return this.contextController.setExtraHTTPHeaders(parseParams(StagehandMethods.contextSetExtraHTTPHeaders, request.params), context);
 			case "context.get_domain_policy": return this.contextController.getDomainPolicy(parseParams(StagehandMethods.contextGetDomainPolicy, request.params), context);
@@ -51260,14 +51258,10 @@ var StagehandLogger = class StagehandLogger {
 };
 //#endregion
 //#region runtimeState.ts
-var StagehandRuntimeStateSchema = discriminatedUnion("status", [
-	strictObject({ status: literal("created") }),
-	strictObject({
-		status: literal("initialized"),
-		initParams: StagehandInitParamsSchema
-	}),
-	strictObject({ status: literal("closed") })
-]);
+var StagehandRuntimeStateSchema = discriminatedUnion("status", [strictObject({ status: literal("idle") }), strictObject({
+	status: literal("initialized"),
+	initParams: StagehandInitParamsSchema
+})]);
 //#endregion
 //#region ../../node_modules/.pnpm/@opentelemetry+otlp-exporter-base@0.220.0_@opentelemetry+api@1.9.1/node_modules/@opentelemetry/otlp-exporter-base/build/esm/OTLPExporterBase.js
 var OTLPExporterBase = class {
@@ -53443,7 +53437,7 @@ var WebTracerProvider = class extends BasicTracerProvider {
 };
 var package_default = {
 	name: "@browserbasehq/stagehand-extension",
-	version: "1.0.2-alpha-d49d643ce9311f16b3ab21289c3bcc01bf0eb097",
+	version: "1.0.2-alpha-6555e81e837012088eb12a39c06aed0527a2e5af",
 	"private": true,
 	type: "module",
 	scripts: {
@@ -53518,22 +53512,48 @@ function createStagehandTracing(options = {}, dependencies = DEFAULT_TRACING_RUN
 	const pendingTracer = trace.getTracer(STAGEHAND_TRACER_NAME);
 	let runtime;
 	let shutDown = false;
+	let globalsRegistered = false;
+	let lifecycleTail = Promise.resolve();
+	let activeTelemetry;
+	let activeClientInfo;
+	function enqueueLifecycle(run) {
+		const result = lifecycleTail.then(run, run);
+		lifecycleTail = result.catch(() => void 0);
+		return result;
+	}
 	return {
 		get tracer() {
 			return runtime?.tracer ?? pendingTracer;
 		},
 		configure(telemetry, clientInfo) {
-			if (runtime || shutDown) return;
-			runtime = createStagehandTracingRuntime({
-				...options,
-				clientName: clientInfo.name,
-				clientVersion: clientInfo.version
-			}, { spanProcessors: [...dependencies.spanProcessors, createOtlpSpanProcessor(telemetry.traces)] });
+			return enqueueLifecycle(async () => {
+				if (shutDown) return;
+				if (runtime && telemetry === activeTelemetry && clientInfo === activeClientInfo) return;
+				const previousRuntime = runtime;
+				runtime = void 0;
+				await previousRuntime?.shutdown();
+				const registerGlobals = options.registerGlobals !== false && !globalsRegistered;
+				runtime = createStagehandTracingRuntime({
+					...options,
+					clientName: clientInfo.name,
+					clientVersion: clientInfo.version,
+					registerGlobals
+				}, { spanProcessors: [...dependencies.spanProcessors, createOtlpSpanProcessor(telemetry.traces)] });
+				activeTelemetry = telemetry;
+				activeClientInfo = clientInfo;
+				globalsRegistered ||= registerGlobals;
+			});
 		},
-		forceFlush: () => runtime?.forceFlush() ?? Promise.resolve(),
+		forceFlush: () => enqueueLifecycle(() => runtime?.forceFlush() ?? Promise.resolve()),
 		shutdown: () => {
 			shutDown = true;
-			return runtime?.shutdown() ?? Promise.resolve();
+			return enqueueLifecycle(async () => {
+				const activeRuntime = runtime;
+				runtime = void 0;
+				activeTelemetry = void 0;
+				activeClientInfo = void 0;
+				await activeRuntime?.shutdown();
+			});
 		}
 	};
 }
@@ -56822,6 +56842,9 @@ var StagehandMetricsAccumulator = class {
 	snapshot() {
 		return { ...this.values };
 	}
+	reset() {
+		Object.assign(this.values, EMPTY_METRICS);
+	}
 };
 //#endregion
 //#region responseHandleTable.ts
@@ -56909,10 +56932,13 @@ var StagehandRuntime = class {
 		this.tracing = tracing;
 		this.metrics = new StagehandMetricsAccumulator();
 		this.responseHandles = new ResponseHandleTable();
-		this.state = createStore()(() => StagehandRuntimeStateSchema.parse({ status: "created" }));
+		this.state = createStore()(() => StagehandRuntimeStateSchema.parse({ status: "idle" }));
 		this.pagesById = /* @__PURE__ */ new Map();
 		this.pageEventSubscriptions = /* @__PURE__ */ new Map();
 		this.initializationInProgress = false;
+		this.lifecycleTail = Promise.resolve();
+		this.stagehandInstanceClosing = false;
+		this.activeStagehandInstanceRequests = 0;
 		this.logger = new StagehandLogger(tracing, adapters.emitLog);
 	}
 	async replaceBrowserConnection(params, bootstrapLogger) {
@@ -56932,29 +56958,31 @@ var StagehandRuntime = class {
 		}
 	}
 	async initialize(params, logger = this.logger) {
-		const state = this.state.getState();
-		if (state.status === "closed") throw new Error("Stagehand has been closed and cannot be initialized again");
 		if (this.initializationInProgress) throw new Error("Stagehand initialization is already in progress");
 		this.initializationInProgress = true;
 		try {
-			this.logger.setLevel(params.logLevel);
-			if (!this.browserSession) {
-				if (!params.browserCdpUrl) throw new Error("stagehand.init requires browserCdpUrl until resident mode is active");
-				await this.replaceBrowserConnection({ cdpUrl: params.browserCdpUrl }, logger);
-			}
-			const pages = await this.runWithTelemetryContext(Symbol("stagehand.init"), logger, async () => {
-				if (state.status === "created") await this.browserSession?.prepareForInitialization?.();
-				return await this.contextPages();
-			});
-			this.tracing.configure(params.telemetry, params.clientInfo);
-			this.state.setState(StagehandRuntimeStateSchema.parse({
-				status: "initialized",
-				initParams: params
-			}), true);
-			return {
-				initialized: true,
-				pages
-			};
+			return await this.enqueueLifecycle(async () => {
+				const state = this.state.getState();
+				if (state.status !== "idle") throw new Error("A Stagehand instance is already initialized");
+				this.logger.setLevel(params.logLevel);
+				if (!this.browserSession?.connected) {
+					if (!params.browserCdpUrl) throw new Error("stagehand.init requires browserCdpUrl until resident mode is active");
+					await this.replaceBrowserConnection({ cdpUrl: params.browserCdpUrl }, logger);
+				}
+				const pages = await this.runWithTelemetryContext(Symbol("stagehand.init"), logger, async () => {
+					if (state.status === "idle") await this.browserSession?.prepareForInitialization?.();
+					return await this.contextPages();
+				});
+				await this.tracing.configure(params.telemetry, params.clientInfo);
+				this.state.setState(StagehandRuntimeStateSchema.parse({
+					status: "initialized",
+					initParams: params
+				}), true);
+				return {
+					initialized: true,
+					pages
+				};
+			});
 		} finally {
 			this.initializationInProgress = false;
 		}
@@ -56992,10 +57020,6 @@ var StagehandRuntime = class {
 		await this.requireBrowserSession().setActivePage(page);
 		return { ok: true };
 	}
-	async contextClose() {
-		await this.close();
-		return { closed: true };
-	}
 	async contextAddInitScript(params) {
 		await this.requireBrowserSession().addInitScript(params.source);
 		return { ok: true };
@@ -57291,16 +57315,64 @@ var StagehandRuntime = class {
 		return { set: true };
 	}
 	async close() {
-		const session = this.browserSession;
-		this.browserSession = void 0;
+		await this.enqueueLifecycle(async () => {
+			const session = this.browserSession;
+			this.browserSession = void 0;
+			this.clearStagehandInstance();
+			await session?.close();
+		});
+	}
+	async disposeStagehandInstance() {
+		if (this.stagehandInstanceDisposal) return await this.stagehandInstanceDisposal;
+		this.stagehandInstanceClosing = true;
+		const disposal = this.enqueueLifecycle(async () => {
+			await this.waitForStagehandInstanceRequests();
+			this.clearStagehandInstance();
+		});
+		this.stagehandInstanceDisposal = disposal.finally(() => {
+			this.stagehandInstanceClosing = false;
+			this.stagehandInstanceDisposal = void 0;
+		});
+		return await this.stagehandInstanceDisposal;
+	}
+	acquireStagehandInstanceRequest() {
+		if (this.stagehandInstanceClosing) throw new Error("Stagehand instance is closing");
+		this.activeStagehandInstanceRequests += 1;
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			this.activeStagehandInstanceRequests -= 1;
+			if (this.activeStagehandInstanceRequests !== 0) return;
+			this.stagehandInstanceRequestsDrained?.resolve();
+			this.stagehandInstanceRequestsDrained = void 0;
+		};
+	}
+	clearStagehandInstance() {
 		this.disposeAllPageEventSubscriptions();
 		this.pagesById.clear();
 		this.responseHandles.clear();
-		try {
-			await session?.close();
-		} finally {
-			this.state.setState(StagehandRuntimeStateSchema.parse({ status: "closed" }), true);
+		this.metrics.reset();
+		this.state.setState(StagehandRuntimeStateSchema.parse({ status: "idle" }), true);
+	}
+	enqueueLifecycle(run) {
+		const result = this.lifecycleTail.then(run, run);
+		this.lifecycleTail = result.then(() => void 0, () => void 0);
+		return result;
+	}
+	waitForStagehandInstanceRequests() {
+		if (this.activeStagehandInstanceRequests === 0) return Promise.resolve();
+		if (!this.stagehandInstanceRequestsDrained) {
+			let resolve;
+			const promise = new Promise((drained) => {
+				resolve = drained;
+			});
+			this.stagehandInstanceRequestsDrained = {
+				promise,
+				resolve
+			};
 		}
+		return this.stagehandInstanceRequestsDrained.promise;
 	}
 	pageRefForId(pageId) {
 		return pageRefFromUnderstudyPage(this.resolvePage(pageId));

{stagehand-4.0.3a0.dev1474 → stagehand-4.0.3a0.dev1476}/src/stagehand/_generated/input_types.py

@@ -140,10 +140,6 @@ class ContextClipboardWriteTextParams(TypedDict):
     text: str
 
 
-class ContextCloseResult(TypedDict):
-    closed: Literal[True]
-
-
 class ContextCookiesParams(TypedDict):
     urls: NotRequired[str | list[str]]
 

{stagehand-4.0.3a0.dev1474 → stagehand-4.0.3a0.dev1476}/src/stagehand/_generated/models.py

@@ -430,14 +430,6 @@ class ContextClipboardWriteTextParams(WireModel):
     text: StrictStr
 
 
-class ContextCloseResult(WireModel):
-    model_config = ConfigDict(
-        extra="forbid",
-        validate_by_name=True,
-    )
-    closed: Literal[True]
-
-
 class ContextCookiesParams(WireModel):
     model_config = ConfigDict(
         extra="forbid",

{stagehand-4.0.3a0.dev1474 → stagehand-4.0.3a0.dev1476}/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.0.0-alpha-d49d643ce9311f16b3ab21289c3bcc01bf0eb097'
+STAGEHAND_PROTOCOL_VERSION = '2.0.0-alpha-6555e81e837012088eb12a39c06aed0527a2e5af'

{stagehand-4.0.3a0.dev1474 → stagehand-4.0.3a0.dev1476}/src/stagehand/browser.py

@@ -22,7 +22,7 @@ from ._generated.models import (
     BrowserSessionMetadata,
 )
 from .browserbase_session import DEFAULT_BROWSERBASE_URL, _create_browserbase_session_client
-from .cdp_client import CDPClient
+from .cdp_client import CDPClient, CDPConnectionClosedError
 from .client_models import (
     BrowserbaseConnectOptions,
     LocalBrowserConnectOptions,
@@ -98,7 +98,8 @@ class StagehandBrowser:
         "_attachment",
         "_claimed",
         "_close_callback",
-        "_close_task",
+        "_invalidate_callback",
+        "_terminal_task",
         "_context",
         "_origin",
         "_provider",
@@ -112,6 +113,7 @@ class StagehandBrowser:
         attachment: _ClaimedBrowser,
         close: Callable[[], Awaitable[None]],
         *,
+        invalidate: Callable[[], Awaitable[None]] | None = None,
         session_id: str | None = None,
         _token: object | None = None,
     ) -> None:
@@ -121,8 +123,9 @@ class StagehandBrowser:
         self._origin = origin
         self._attachment = attachment
         self._close_callback = close
+        self._invalidate_callback = invalidate or close
         self._claimed = False
-        self._close_task: asyncio.Task[None] | None = None
+        self._terminal_task: asyncio.Task[None] | None = None
         self._context: BrowserContext | None = None
         self._session_id = session_id
 
@@ -141,7 +144,7 @@ class StagehandBrowser:
 
     @property
     def closed(self) -> bool:
-        return self._close_task is not None
+        return self._terminal_task is not None
 
     @property
     def context(self) -> BrowserContext:
@@ -153,15 +156,12 @@ class StagehandBrowser:
         return self._context
 
     def close(self) -> Awaitable[None]:
-        if self._close_task is None:
-            self._close_task = asyncio.create_task(
-                self._run_close(),
+        if self._terminal_task is None:
+            self._terminal_task = asyncio.create_task(
+                _run_browser_terminal_callback(self._close_callback),
                 name="stagehand-browser-close",
             )
-        return asyncio.shield(self._close_task)
-
-    async def _run_close(self) -> None:
-        await self._close_callback()
+        return asyncio.shield(self._terminal_task)
 
 
 def _claim_browser(browser: object) -> _ClaimedBrowser:
@@ -181,6 +181,23 @@ def _release_browser(browser: StagehandBrowser) -> None:
     browser._claimed = False
 
 
+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)
+
+
+async def _run_browser_terminal_callback(
+    callback: Callable[[], Awaitable[None]],
+) -> None:
+    await callback()
+
+
 def _attach_browser_context(
     browser: StagehandBrowser,
     context: BrowserContext,
@@ -289,13 +306,34 @@ async def _connect_browser(
 
     connected_client = cdp_client
 
-    async def close() -> None:
+    async def invalidate() -> None:
         try:
             await connected_client.close()
         finally:
             if owns_source:
                 await source.close()
 
+    async def close() -> None:
+        errors: list[BaseException] = []
+        try:
+            if provider == "local" and origin == "connected":
+                try:
+                    await connected_client.send_command("Browser.close")
+                except CDPConnectionClosedError:
+                    pass
+            else:
+                await source.close()
+        except BaseException as error:
+            errors.append(error)
+        try:
+            await connected_client.close()
+        except BaseException as error:
+            errors.append(error)
+        if len(errors) == 1:
+            raise errors[0]
+        if errors:
+            raise BaseExceptionGroup("Browser termination and cleanup failed", errors)
+
     return StagehandBrowser(
         provider,
         origin,
@@ -304,6 +342,7 @@ async def _connect_browser(
             worker_init_metadata=worker_init_metadata,
         ),
         close,
+        invalidate=invalidate,
         session_id=(
             worker_init_metadata.browser.session_id if worker_init_metadata.browser else None
         ),
@@ -563,7 +602,11 @@ class BrowserbaseBrowser:
         return await _connect_browser(
             provider="browserbase",
             origin="connected",
-            source=_ConnectedBrowserSource(connection.cdp_url),
+            source=ResolvedBrowserSource(
+                cdp_url=connection.cdp_url,
+                keep_alive=True,
+                _close_callback=connection.close,
+            ),
             extension_id=options.extension_id,
             preloaded_extension=options.extension_id is None,
             worker_init_metadata=_WorkerInitMetadata(

{stagehand-4.0.3a0.dev1474 → stagehand-4.0.3a0.dev1476}/src/stagehand/browser_context.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import re
-from collections.abc import Mapping, Sequence
+from collections.abc import Awaitable, Callable, Mapping, Sequence
 from pathlib import Path
 
 from ._generated.input_types import CookieParam
@@ -12,7 +12,6 @@ from ._generated.models import (
     ContextAddCookiesParams,
     ContextAddInitScriptParams,
     ContextClearCookiesParams,
-    ContextCloseResult,
     ContextCookiesParams,
     ContextCookiesResult,
     ContextGetDomainPolicyResult,
@@ -35,8 +34,13 @@ from .rpc_client import RPCClient
 
 
 class BrowserContext:
-    def __init__(self, rpc_client: RPCClient) -> None:
+    def __init__(
+        self,
+        rpc_client: RPCClient,
+        close_browser: Callable[[], Awaitable[None]] | None = None,
+    ) -> None:
         self._rpc_client = rpc_client
+        self._close_browser = close_browser
         self._clipboard: BrowserClipboard | None = None
 
     @property
@@ -76,12 +80,10 @@ class BrowserContext:
         )
 
     async def close(self) -> None:
-        """Close the remote context; use Stagehand.close() to release local resources."""
-        await self._rpc_client.send(
-            "context.close",
-            EmptyParams(),
-            ContextCloseResult,
-        )
+        """Close the underlying browser."""
+        if self._close_browser is None:
+            raise RuntimeError("Browser context is not attached to a browser")
+        await self._close_browser()
 
     async def add_init_script(self, source: str | Path) -> None:
         if isinstance(source, Path):

{stagehand-4.0.3a0.dev1474 → stagehand-4.0.3a0.dev1476}/src/stagehand/browserbase_session.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Mapping
+from collections.abc import Awaitable, Callable, Mapping
 from dataclasses import dataclass, field
 from typing import Any, Protocol
 
@@ -142,6 +142,11 @@ class _BrowserbaseSessionConnection:
     session_id: str
     cdp_url: str
     region: BrowserbaseRegion | None = None
+    _close_callback: Callable[[], Awaitable[None]] | None = field(default=None, repr=False)
+
+    async def close(self) -> None:
+        if self._close_callback is not None:
+            await self._close_callback()
 
 
 @dataclass
@@ -254,10 +259,22 @@ class _BrowserbaseSessionClient:
         cdp_url = connect_url.strip() if connect_url is not None else ""
         if not cdp_url:
             raise BrowserbaseSessionError("Browserbase session is not available for connection")
+        released = False
+        close_lock = asyncio.Lock()
+
+        async def close() -> None:
+            nonlocal released
+            async with close_lock:
+                if released:
+                    return
+                await self._api.release_session(retrieved_id.strip() or normalized_session_id)
+                released = True
+
         return _BrowserbaseSessionConnection(
             session_id=retrieved_id.strip() or normalized_session_id,
             cdp_url=cdp_url,
             region=region,
+            _close_callback=close,
         )
 
     async def _delete_extension_best_effort(self, extension_id: str | None) -> None:

{stagehand-4.0.3a0.dev1474 → stagehand-4.0.3a0.dev1476}/src/stagehand/rpc_client.py

@@ -38,7 +38,6 @@ _UNBOUNDED_BY_DEFAULT_METHODS = {
     "stagehand.extract",
     "stagehand.observe",
     "context.new_page",
-    "context.close",
     "context.add_init_script",
     "context.set_extra_http_headers",
     "context.get_domain_policy",

{stagehand-4.0.3a0.dev1474 → stagehand-4.0.3a0.dev1476}/src/stagehand/stagehand.py

@@ -47,6 +47,7 @@ from .browser import (
     _claim_browser,
     _ClaimedBrowser,
     _detach_browser_context,
+    _invalidate_browser,
     _release_browser,
 )
 from .browser_context import BrowserContext
@@ -278,7 +279,10 @@ class Stagehand:
             init_params,
             StagehandInitResult,
         )
-        _attach_browser_context(self._browser_handle, BrowserContext(rpc_client))
+        _attach_browser_context(
+            self._browser_handle,
+            BrowserContext(rpc_client, self._browser_handle.close),
+        )
         self._initialized = True
 
     async def act(
@@ -450,6 +454,7 @@ class Stagehand:
 
     async def close(self) -> None:
         async def close_impl() -> None:
+            release_browser_claim = not self._initialized
             try:
                 if self._initialized and self._rpc_client is not None:
                     try:
@@ -458,10 +463,15 @@ class Stagehand:
                             EmptyParams(),
                             StagehandCloseResult,
                         )
+                        release_browser_claim = True
                     except CDPConnectionClosedError:
-                        pass
+                        release_browser_claim = True
             finally:
-                await asyncio.shield(self._release_resources())
+                try:
+                    await asyncio.shield(self._release_resources())
+                finally:
+                    if release_browser_claim:
+                        _release_browser(self._browser_handle)
 
         if self._close_task is None:
             self._close_task = asyncio.create_task(
@@ -541,11 +551,11 @@ class Stagehand:
         fail_closed: bool,
     ) -> None:
         if fail_closed:
-            browser_close = browser.close()
+            browser_invalidation = _invalidate_browser(browser)
             try:
                 await self._release_resources()
             finally:
-                await browser_close
+                await browser_invalidation
             return
 
         try: