kill cua agent on stagehand.close #1399

tkattkat · 2025-12-10T01:34:21Z

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

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.

^{Written for commit d34c5cd. Summary will update automatically on new commits.}

changeset-bot · 2025-12-10T01:34:26Z

🦋 Changeset detected

Latest commit: d34c5cd

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

cubic-dev-ai

No issues found across 6 files

greptile-apps · 2025-12-10T01:37:10Z

Greptile Overview

Greptile Summary

This PR addresses a race condition bug where Computer Use Agent (CUA) loops continued executing after stagehand.close() was called, resulting in "Cannot read properties of null" errors. The fix introduces a new StagehandClosedError class that acts as a clear signal when the Stagehand session is closed. The V3CuaAgentHandler now includes guard checks that throw this error when attempting to take screenshots or execute actions on a null context. All CUA clients (Anthropic, Google, and OpenAI) have been updated to catch and re-throw StagehandClosedError instead of swallowing it, ensuring agent loops terminate immediately when the session is closed.

PR Description Notes:

The description mentions "All CUA clients (Anthropic, Google, OpenAI, Microsoft)" but the Microsoft client was not updated in this PR

Important Files Changed

Filename	Score	Overview
packages/core/lib/v3/types/public/sdkErrors.ts	5/5	Added new `StagehandClosedError` class extending `StagehandError`
packages/core/lib/v3/handlers/v3CuaAgentHandler.ts	5/5	Added `ensureNotClosed()` guard method and context null checks before screenshots/actions
packages/core/lib/v3/agent/AnthropicCUAClient.ts	5/5	Added `StagehandClosedError` import and re-throwing in action execution catch block
packages/core/lib/v3/agent/GoogleCUAClient.ts	5/5	Added `StagehandClosedError` import and re-throwing in action execution catch block
packages/core/lib/v3/agent/OpenAICUAClient.ts	5/5	Added `StagehandClosedError` import and re-throwing in multiple catch blocks
packages/core/tests/public-api/public-error-types.test.ts	5/5	Added `StagehandClosedError` to public error types test validation

Confidence score: 4/5

This PR addresses a real bug with a clean, targeted solution that prevents CUA agents from executing on closed sessions
Score reduced by one point because the Microsoft CUA client mentioned in the PR description was not updated, creating potential inconsistency
Pay close attention to packages/core/lib/v3/agent/MicrosoftCUAClient.ts to verify it doesn't need the same fix as other CUA clients

Sequence Diagram

sequenceDiagram
    participant User
    participant Stagehand as Stagehand Instance
    participant V3CuaHandler as V3CuaAgentHandler
    participant CUAClient as CUA Client (Anthropic/Google/OpenAI)
    participant Context as Browser Context

    User->>Stagehand: "stagehand.close()"
    Stagehand->>Context: "destroy context"
    Context->>Context: "set context to null"
    
    Note over CUAClient: Agent loop continues running
    CUAClient->>V3CuaHandler: "executeAction(action)"
    V3CuaHandler->>V3CuaHandler: "ensureNotClosed()"
    V3CuaHandler->>V3CuaHandler: "check if context is null"
    V3CuaHandler->>CUAClient: "throw StagehandClosedError()"
    
    CUAClient->>CUAClient: "catch StagehandClosedError in executeStep()"
    CUAClient->>CUAClient: "re-throw StagehandClosedError"
    
    Note over CUAClient: Agent loop terminates cleanly
    CUAClient->>User: "return AgentResult with error"

greptile-apps

_{6 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

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

miguelg719 · 2025-12-16T00:57:01Z

@greptileai

greptile-apps

_{6 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

@tkattkat

kill cua agent on stagehand.close

8bc32f8

changeset

25bcc26

cubic-dev-ai bot reviewed Dec 10, 2025

View reviewed changes

greptile-apps bot reviewed Dec 10, 2025

View reviewed changes

packages/core/lib/v3/agent/MicrosoftCUAClient.ts Outdated Show resolved Hide resolved

tkattkat added 4 commits December 9, 2025 17:38

format

a2faec0

update

8a58616

update test

2e59c82

lint

d34c5cd

greptile-apps bot reviewed Dec 16, 2025

View reviewed changes

miguelg719 approved these changes Dec 16, 2025

View reviewed changes

tkattkat merged commit 6a5496f into main Dec 16, 2025
17 checks passed

This was referenced Dec 16, 2025

Version Packages #1414

Merged

Version Packages CloudEngineHub/stagehand#1

Open

Version Packages kenchikuliu/stagehand#1

Open

Version Packages shaneholloman/stagehand#1

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

kill cua agent on stagehand.close #1399

kill cua agent on stagehand.close #1399

Uh oh!

tkattkat commented Dec 10, 2025 •

edited by cubic-dev-ai bot

Loading

Uh oh!

changeset-bot bot commented Dec 10, 2025 •

edited

Loading

Uh oh!

cubic-dev-ai bot left a comment

Uh oh!

greptile-apps bot commented Dec 10, 2025 •

edited

Loading

Uh oh!

greptile-apps bot left a comment

Uh oh!

Uh oh!

miguelg719 commented Dec 16, 2025

Uh oh!

greptile-apps bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kill cua agent on stagehand.close #1399

kill cua agent on stagehand.close #1399

Uh oh!

Conversation

tkattkat commented Dec 10, 2025 • edited by cubic-dev-ai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

What Changed

Summary by cubic

Uh oh!

changeset-bot bot commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Overview

Greptile Summary

Important Files Changed

Confidence score: 4/5

Sequence Diagram

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

miguelg719 commented Dec 16, 2025

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tkattkat commented Dec 10, 2025 •

edited by cubic-dev-ai bot

Loading

changeset-bot bot commented Dec 10, 2025 •

edited

Loading

greptile-apps bot commented Dec 10, 2025 •

edited

Loading