[akeimach]

why

We made a change to browser.close behavior, but the docs didn't contain the changes yet. This PR updates the docs to match existing close patterns

what changed

Docs are updated to match current behavior

test plan

just docs and review the changes live

---

Summary by cubic

Updates the docs to match the current browser.close() behavior, where calling it ends the session even with keep-alive enabled. To keep a session alive for later reconnection, you now close only the Stagehand runtime and skip browser.close().

• Updates the keep-alive section in the browser configuration docs with the new closing patterns for TypeScript, Python, and Go.
• Revises the Browserbase and local environment behavior tables, the migration guides, and the Python SDK README to match the new behavior.

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: 1476029

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[cubic-dev-ai]

cubic analysis

All reported issues were addressed across 5 files

Linked issue analysis

Linked issue: AP-2938: udpate browser.close\(\) docs

Status	Acceptance criteria	Notes
✅	Document that browser.close() ends sessions even with keep-alive enabled	The keep-alive section and Python README say browser.close() ends the session, while stagehand.close() alone preserves it.

Architecture diagram

sequenceDiagram
    participant User as Developer
    participant Stagehand as Stagehand Runtime
    participant Browser as Browser Handle
    participant BBase as Browserbase Cloud
    participant Local as Local Chrome

    Note over User,Local: Documented Browser Lifecycle Patterns

    alt Browserbase Launch with Keep-Alive
        User->>Browser: browserbase.launch()
        Browser->>BBase: Start session
        User->>Stagehand: stagehand.close()
        Stagehand-->>User: Runtime released
        Note over User,BBase: Session stays active (keep-alive)
        User->>Browser: browserbase.connect(sessionId)
        User->>Stagehand: stagehand.create()
        User->>Stagehand: stagehand2.close()
        User->>Browser: browser2.close()
        Browser->>BBase: End session
    else Local Launch
        User->>Browser: local_browser.launch()
        User->>Stagehand: stagehand.close()
        Stagehand-->>User: Runtime released
        Note over User,Local: Browser window stays open
        User->>Browser: browser.close()
        Browser->>Local: Kill Chrome + cleanup temp profile
    else Browserbase Connect
        User->>Browser: browserbase.connect()
        User->>Stagehand: stagehand.close()
        Note over User,BBase: Session keeps running (not owned)
        User->>Browser: browser.close()
        Browser->>BBase: Closes connection
    else Local Connect
        User->>Browser: local_browser.connect()
        User->>Stagehand: stagehand.close()
        Note over User,Local: Browser keeps running
        User->>Browser: browser.close()
        Browser->>Local: Close browser
    end

    Note over User,BBase: Extension cleanup
    User->>Browser: browser.close() (launched session)
    Browser->>BBase: Delete uploaded extension

Loading

<sub>Tip: Get a Slack DM when cubic finishes reviewing your PRs. Connect Slack

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[akeimach]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@akeimach I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

cubic analysis

No issues found across 5 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Linked issue analysis

Linked issue: AP-2938: udpate browser.close\(\) docs

Status	Acceptance criteria	Notes
✅	Clarify browser.close() ends the session with keep-alive enabled	The keep-alive section says browser.close() closes the browser even when keep-alive is on.

Architecture diagram

sequenceDiagram
    participant User as Developer
    participant SH as Stagehand Runtime
    participant B as Browser Handle
    participant BB as Browserbase Cloud
    participant L as Local Chrome

    Note over User,BB: NEW: Lifecycle Management Flow

    User->>SH: create({ browser })
    User->>B: launch() or connect()

    alt Keep-alive enabled (Browserbase)
        Note over User,BB: Session persists for reconnection
        User->>SH: close()
        SH-->>B: Detach runtime, session stays active
        User->>BB: browserbase.connect(sessionId) [later]
        BB-->>User: Reconnected session
        User->>B: close()
        alt Via launch() extension
            Note over B,BB: NEW: Extension upload retained
            B->>BB: Close session
            Note over BB: Extension remains on account
        else Via connect()
            B->>BB: Close session
        end
    else Keep-alive off (Browserbase)
        User->>B: close()
        B->>BB: Terminate session via API
    else Local environment, keep-alive on
        User->>SH: close()
        SH-->>B: Detach, Chrome keeps running
        User->>B: close()
        L->>L: Kill Chrome, remove temp profile
    else Local environment, keep-alive off
        User->>B: close()
        L->>L: Kill Chrome, remove temp profile
    end

    alt Attached over CDP (connect)
        Note over B: CHANGED: Stagehand never owns browser
        User->>SH: close()
        Note over B: Browser always left running
        User->>B: close() (ends connection)
    end

Loading

_{View guided diff | Turn on auto-fix | Re-trigger cubic}