kill cua agent on stagehand.close (#1399)

# Why

CUA agent loops continued running after `stagehand.close()` was called,
causing errors like "Cannot read properties of null (reading
'awaitActivePage')".

# What Changed

- Added `StagehandClosedError` class to detect when Stagehand session is
closed
- `V3CuaAgentHandler` now checks if context is null before executing
actions/screenshots and throws `StagehandClosedError`
- All CUA clients (Anthropic, Google, OpenAI, Microsoft) re-throw
`StagehandClosedError` in catch blocks to stop the agent loop
immediately instead of swallowing the error











<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Stops CUA agent loops immediately after stagehand.close() to prevent
null-context errors and stray actions. Adds a clear signal so clients
and handlers halt cleanly.

- **Bug Fixes**
  - Introduced StagehandClosedError to indicate a closed session.
- V3CuaAgentHandler checks context before screenshots/actions and throws
StagehandClosedError.
- Anthropic, Google, and OpenAI CUA clients rethrow StagehandClosedError
to exit loops.

<sup>Written for commit d34c5cd.
Summary will update automatically on new commits.</sup>

<!-- End of auto-generated description by cubic. -->

Author: tkattkat

.changeset/five-mammals-fix.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+Ensure cua agent is killed when stagehand.close is called

packages/core/lib/v3/agent/AnthropicCUAClient.ts

@@ -11,7 +11,10 @@ import {
 } from "../types/public/agent";
 import { LogLine } from "../types/public/logs";
 import { ClientOptions } from "../types/public/model";
-import { AgentScreenshotProviderError } from "../types/public/sdkErrors";
+import {
+  AgentScreenshotProviderError,
+  StagehandClosedError,
+} from "../types/public/sdkErrors";
 import Anthropic from "@anthropic-ai/sdk";
 import { ToolSet } from "ai";
 import { AgentClient } from "./AgentClient";
@@ -320,6 +323,9 @@ export class AnthropicCUAClient extends AgentClient {
             });
             await this.actionHandler(action);
           } catch (error) {
+            if (error instanceof StagehandClosedError) {
+              throw error;
+            }
             const errorMessage =
               error instanceof Error ? error.message : String(error);
             logger({

packages/core/lib/v3/agent/GoogleCUAClient.ts

@@ -20,6 +20,7 @@ import { AgentClient } from "./AgentClient";
 import {
   AgentScreenshotProviderError,
   LLMResponseError,
+  StagehandClosedError,
 } from "../types/public/sdkErrors";
 import { buildGoogleCUASystemPrompt } from "../../prompt";
 import { compressGoogleConversationImages } from "./utils/imageCompression";
@@ -486,6 +487,9 @@ export class GoogleCUAClient extends AgentClient {
                 await new Promise((resolve) => setTimeout(resolve, delay));
               }
             } catch (actionError) {
+              if (actionError instanceof StagehandClosedError) {
+                throw actionError;
+              }
               logger({
                 category: "agent",
                 message: `Error executing action ${action.type}: ${actionError}`,

packages/core/lib/v3/agent/OpenAICUAClient.ts

@@ -12,7 +12,10 @@ import {
 } from "../types/public/agent";
 import { ClientOptions } from "../types/public/model";
 import { AgentClient } from "./AgentClient";
-import { AgentScreenshotProviderError } from "../types/public/sdkErrors";
+import {
+  AgentScreenshotProviderError,
+  StagehandClosedError,
+} from "../types/public/sdkErrors";
 import { ToolSet } from "ai";
 import {
   SessionFileLogger,
@@ -547,6 +550,9 @@ export class OpenAICUAClient extends AgentClient {
 
           nextInputItems.push(outputItem);
         } catch (error) {
+          if (error instanceof StagehandClosedError) {
+            throw error;
+          }
           const errorMessage =
             error instanceof Error ? error.message : String(error);
 
@@ -613,6 +619,9 @@ export class OpenAICUAClient extends AgentClient {
 
             nextInputItems.push(errorOutputItem);
           } catch (screenshotError) {
+            if (screenshotError instanceof StagehandClosedError) {
+              throw screenshotError;
+            }
             // If we can't capture a screenshot, just send the error
             logger({
               category: "agent",
@@ -688,6 +697,9 @@ export class OpenAICUAClient extends AgentClient {
 
           nextInputItems.push(outputItem);
         } catch (error) {
+          if (error instanceof StagehandClosedError) {
+            throw error;
+          }
           const errorMessage =
             error instanceof Error ? error.message : String(error);
 

packages/core/lib/v3/handlers/v3CuaAgentHandler.ts

@@ -14,6 +14,7 @@ import {
 import { LogLine } from "../types/public/logs";
 import { type Action, V3FunctionName } from "../types/public/methods";
 import { SessionFileLogger } from "../flowLogger";
+import { StagehandClosedError } from "../types/public/sdkErrors";
 
 export class V3CuaAgentHandler {
   private v3: V3;
@@ -46,16 +47,28 @@ export class V3CuaAgentHandler {
     this.agent = client;
   }
 
+  /**
+   * Ensures the V3 context is still available (not closed).
+   * Throws StagehandClosedError if stagehand.close() was called.
+   */
+  private ensureNotClosed(): void {
+    if (!this.v3.context) {
+      throw new StagehandClosedError();
+    }
+  }
+
   private setupAgentClient(): void {
     // Provide screenshots to the agent client
     this.agentClient.setScreenshotProvider(async () => {
+      this.ensureNotClosed();
       const page = await this.v3.context.awaitActivePage();
       const base64 = await page.screenshot({ fullPage: false });
       return base64.toString("base64"); // base64 png
     });
 
     // Provide action executor
     this.agentClient.setActionHandler(async (action) => {
+      this.ensureNotClosed();
       action.pageUrl = (await this.v3.context.awaitActivePage()).url();
 
       const defaultDelay = 500;

packages/core/lib/v3/types/public/sdkErrors.ts

@@ -364,3 +364,9 @@ export class AgentAbortError extends StagehandError {
     this.reason = reason || "aborted";
   }
 }
+
+export class StagehandClosedError extends StagehandError {
+  constructor() {
+    super("Stagehand session was closed");
+  }
+}

packages/core/tests/public-api/public-error-types.test.ts

@@ -26,6 +26,7 @@ export const publicErrorTypes = {
   StagehandAPIError: Stagehand.StagehandAPIError,
   StagehandAPIUnauthorizedError: Stagehand.StagehandAPIUnauthorizedError,
   StagehandClickError: Stagehand.StagehandClickError,
+  StagehandClosedError: Stagehand.StagehandClosedError,
   StagehandDefaultError: Stagehand.StagehandDefaultError,
   StagehandDomProcessError: Stagehand.StagehandDomProcessError,
   StagehandElementNotFoundError: Stagehand.StagehandElementNotFoundError,