feat: add browser.disconnect() to the TypeScript and Python SDKs by miguelg719 · Pull Request #3305 · browserbase/stagehand

miguelg719 · 2026-10-22T18:42:05Z

why

there's no public way to detach from a browser without closing it. browser.close() quits a browser attached with localBrowser.connect(), & stagehand.close() keeps the connection open, so callers attached to a long-lived browser (e.g. one holding signed-in profiles) can't cleanly let go

what changed

added browser.disconnect() (ts) / await browser.disconnect() (python): closes an attached stagehand instance (incl. the extension's loopback cdp connection), then stagehand's connection. a later connect() + Stagehand.create() on the same browser works; before, it failed with "A Stagehand instance is already initialized". stagehand never sends Browser.close, never closes a launched process or profile, & never releases a browserbase session
on browserbase, keepAlive decides whether the session survives: with keepAlive: false (the default) browserbase ends the session when any cdp connection closes, including disconnect(). only keepAlive: true sessions keep running
the handle is finished after disconnect(): close() then throws ("connect() again to close it"); reconnect with localBrowser.connect({ cdpUrl }) / browserbase.connect({ sessionId }) & close that handle. repeated disconnect() / close() calls are idempotent
if the connection drops without disconnect(), close() still releases a browserbase session over its api & does nothing for local browsers
close() on a launched local browser sends Browser.close before the launcher terminates it (temp profile removed unless preserveUserDataDir)
handles expose cdpUrl (cdp_url in python) for local browsers, and connected: closed only means close()/disconnect() was called, so callers still close() a handle whose connection dropped
disconnect() waits at most 10s for the attached stagehand instance to close, then lets go anyway
docs: a disconnect section with a keepAlive warning & a per-case "to close it later" table, a disconnect column in the behavior-by-environment table split by keepAlive, & a corrected note about close() on connected browsers
go is intentionally not included

test plan

unit tests in both sdks across local & browserbase, launched & connected, keepAlive on & off: idempotency, close after disconnect (throws, releases nothing), close after a lost connection (browserbase released, local untouched), Browser.close before termination, cdpUrl, & re-attach
real chrome tests in both sdks: attach to a separately launched chrome, disconnect, & check it still serves its pages (they fail if close() is used instead); & connect → create → disconnect (no stagehand.close()) → connect → create → navigate (fails on the previous head)
pnpm check, pnpm test:unit, sdk-ts unit tests, python tests, ruff, ty, docs tests, sdk parity rules

disconnect() closes Stagehand's connection to a browser and leaves the browser running, whichever way it was obtained: it never sends Browser.close, never closes a launched process or profile, and never releases a Browserbase session. Like close() it is terminal, and later close() or disconnect() calls do nothing. Go is not included.

changeset-bot · 2026-10-22T18:42:12Z

🦋 Changeset detected

Latest commit: 0406aed

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

This PR includes changesets to release 22 packages

Name	Type
@browserbasehq/stagehand	Minor
@browserbasehq/stagehand-python	Minor
browse	Patch
@browserbasehq/stagehand-examples	Patch
@browserbasehq/stagehand-integrations-claude-cua-sdk	Patch
@browserbasehq/stagehand-integrations	Patch
@browserbasehq/eve	Patch
@browserbasehq/stagehand-integrations-gemini-cua-sdk	Patch
@browserbasehq/stagehand-integrations-example-pi-facade	Patch
@browserbasehq/stagehand-integrations-claude-agent-sdk	Patch
@browserbasehq/stagehand-integrations-example-claude-code-facade	Patch
@browserbasehq/stagehand-integrations-codex-sdk	Patch
@browserbasehq/stagehand-integrations-example-codex-facade	Patch
@browserbasehq/stagehand-integrations-cursor-sdk	Patch
@browserbasehq/stagehand-integrations-example-cursor-facade	Patch
@browserbasehq/stagehand-integrations-deepagents-sdk	Patch
@browserbasehq/stagehand-integrations-eve-sdk	Patch
@browserbasehq/stagehand-integrations-fx-sdk	Patch
@browserbasehq/stagehand-integrations-mastra-sdk	Patch
@browserbasehq/stagehand-integrations-example-mastra-facade	Patch
@browserbasehq/stagehand-integrations-pi-sdk	Patch
@browserbasehq/stagehand-integrations-example-vercel-ai-facade	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

All reported issues were addressed across 9 files

Architecture diagram

sequenceDiagram
    participant User as SDK Caller
    participant Browser as StagehandBrowser Handle
    participant Internals as Browser Handle Internals
    participant CDP as CDP Client
    participant BrowserProc as Browser Process (Chrome)
    participant BBSession as Browserbase Session

    Note over User,BBSession: Browser disconnect flow - detach without closing

    User->>Browser: disconnect()
    Browser->>Internals: Require internals
    Internals->>Internals: Check terminalPromise
    
    alt First disconnect call
        Internals->>Internals: Store disconnect callback as terminalPromise
        Internals->>CDP: close() (WebSocket connection)
        CDP-->>Internals: Connection closed
        Internals-->>Browser: Mark as closed
        Browser-->>User: Promise resolves
    else Subsequent disconnect or close calls
        Internals->>Internals: Return existing terminalPromise (no-op)
        Internals-->>Browser: Resolve immediately
        Browser-->>User: No action
    end

    Note over BrowserProc,BBSession: Browser remains running

    BrowserProc->>BrowserProc: Stays alive (no Browser.close command)
    BBSession->>BBSession: Session persists (not released)

    User->>User: Browser handle is terminal - cannot re-attach

_{Reply with feedback, questions, or to request a fix.

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

The handle is now a small state machine (open -> disconnected -> closed, or open -> closed). close() after disconnect() releases what Stagehand launched (the local Chrome process and profile, or the Browserbase session) without the connection, and does nothing for connected browsers. Bounds the real Chrome tests at 60 s.

cubic-dev-ai

All reported issues were addressed across 8 files (changes from recent commits).

_{Reply with feedback, questions, or to request a fix.

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

seanmcguire12 · 2026-10-26T17:01:09Z

+   * session) and does nothing for a browser you connected to; repeated
+   * disconnect() calls, or disconnect() after close(), do nothing.
+   */
+  disconnect(): Promise<void>;


if browserbase session is keepAlive: false (which is the default btw), won't disconnect close the session?

…nect()

cubic-dev-ai

All reported issues were addressed across 6 files (changes from recent commits).

_{Tip: Review your code locally with the cubic CLI to iterate faster.

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

… re-attached

cubic-dev-ai

All reported issues were addressed across 10 files (changes from recent commits).

_{Reply with feedback, questions, or to request a fix.

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

…rowser.close before terminating launched Chrome

cubic-dev-ai

All reported issues were addressed across 11 files (changes from recent commits).

_{Reply with feedback, questions, or to request a fix.

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

…ope test

…ailed release after a lost connection

…d; retry a failed Python source close

…ehand; pi closes a lost browser

cubic-dev-ai

All reported issues were addressed across 7 files (changes from recent commits).

_{Reply with feedback, questions, or to request a fix.

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

…he timeout test

…feat/browser-disconnect

# why if the sdk process dies without `disconnect()` / `close()` (crash, `SIGKILL`, dropped connection), nothing tells the browser: a local chrome stagehand launched keeps running, and the extension stays initialized, so reconnecting fails with "A Stagehand instance is already initialized". builds on #3305 & adopts the mechanism from `service-watchdog` # what changed - on connect the sdk creates a hidden target on its own cdp connection; chrome destroys it when that connection ends. the extension watches `Target.targetDestroyed` over its own connection, with no heartbeat or timers - on loss: a local browser stagehand launched without `keepAlive` gets `Browser.close`; anything else keeps running, and the extension releases the instance & closes its own connection, so browserbase applies its `keepAlive` policy and a new client can attach - `disconnect()` detaches (disarms the watchdog) before closing; if the detach isn't acknowledged, the socket & handle stay open, since closing would read as a loss - registration checks the marker really is hidden (`type: "other"`); with an older extension or a chrome without hidden targets the sdk warns once & continues without the watchdog - one client per browser: a second client gets "A Stagehand client is already connected" - ts & python; docs & changeset # test plan - extension unit tests: loss/terminate/detach ordering, close of the extension's connection on loss, registration races - sdk unit tests in both sdks: loss policy per provider/origin/keepAlive, unacknowledged detach keeps the handle usable - real chrome (ts & python): `SIGKILL`/`SIGINT` matrix (owned keepAlive=false is shut down, keepAlive=true & externally launched chrome survive and re-attach), disconnect → reconnect → create - live browserbase: hidden target works through the proxy; after `SIGKILL` of the host, a `keepAlive: false` session is `COMPLETED` within 5s, and a `keepAlive: true` session stays `RUNNING` & accepts `connect()` + `Stagehand.create()` --------- Co-authored-by: Sean McGuire <seanmcguire1@outlook.com>

miguelg719 requested a review from a team as a code owner October 22, 2026 18:42

cubic-dev-ai Bot reviewed Oct 22, 2026

View reviewed changes

Comment thread packages/sdk-ts/tests/browser-runtime/browserDisconnect.test.ts

Comment thread packages/sdk-ts/src/browser/index.ts Outdated

Comment thread packages/sdk-python/src/stagehand/browser.py

cubic-dev-ai Bot reviewed Oct 22, 2026

View reviewed changes

Comment thread packages/docs/v4/configuration/browser.mdx Outdated

docs: use active voice for reattaching after disconnect()

8169643

seanmcguire12 reviewed Oct 26, 2026

View reviewed changes

docs: keepAlive decides whether a Browserbase session survives discon…

3bb7d5b

…nect()

cubic-dev-ai Bot reviewed Oct 26, 2026

View reviewed changes

Comment thread packages/docs/v4/configuration/browser.mdx Outdated

fix: disconnect() closes the attached Stagehand so the browser can be…

96b325e

… re-attached

mintlify Bot deployed to staging - packages/docs October 26, 2026 23:11

View deployment

docs: reuse one browser variable in the disconnect example

30623c8

mintlify Bot deployed to staging - packages/docs October 26, 2026 23:11

View deployment

cubic-dev-ai Bot reviewed Oct 26, 2026

View reviewed changes

Comment thread packages/sdk-python/tests/test_browser.py

Comment thread packages/sdk-python/tests/test_browser_disconnect_live.py

feat: close() needs a connection after disconnect(); expose cdpUrl; B…

21cde60

…rowser.close before terminating launched Chrome

mintlify Bot deployed to staging - packages/docs October 27, 2026 00:42

View deployment

Merge remote-tracking branch 'origin/main' into feat/browser-disconnect

e8800d9

cubic-dev-ai Bot reviewed Oct 27, 2026

View reviewed changes

Comment thread packages/sdk-ts/src/browser/factories.ts

Comment thread packages/sdk-python/src/stagehand/browser.py

Comment thread packages/docs/v4/configuration/browser.mdx Outdated

Comment thread packages/sdk-ts/src/browser/index.ts Outdated

mintlify Bot deployed to staging - packages/docs October 27, 2026 00:47

View deployment

miguelg719 mentioned this pull request Oct 27, 2026

feat: extension watchdog for lost SDK clients #3325

Merged

miguelg719 added 2 commits October 26, 2026 18:22

test: expect the middleware fixture package in the Go-less release sc…

2476707

…ope test

fix: terminate launched Chrome even if Browser.close fails; retry a f…

04f28c4

…ailed release after a lost connection

mintlify Bot deployed to staging - packages/docs October 27, 2026 18:02

View deployment

miguelg719 added this pull request to stack #3331 October 27, 2026 18:30

miguelg719 added 2 commits October 27, 2026 15:00

fix: bound Browser.close so an unresponsive Chrome is still terminate…

5ea73be

…d; retry a failed Python source close

feat: split connected from closed; bound disconnect()'s wait for Stag…

1719971

…ehand; pi closes a lost browser

mintlify Bot deployed to staging - packages/docs October 27, 2026 22:32

View deployment

cubic-dev-ai Bot reviewed Oct 27, 2026

View reviewed changes

Comment thread packages/sdk-ts/tests/browser/factories.test.ts Outdated

Comment thread packages/sdk-python/src/stagehand/browser.py Outdated

fix: only the disconnect deadline's own timeout is ignored; tighten t…

5f7113e

…he timeout test

Merge branch 'main' of https://github.com/browserbase/stagehand into …

0406aed

…feat/browser-disconnect

mintlify Bot deployed to staging - packages/docs October 28, 2026 22:11

View deployment

seanmcguire12 approved these changes Oct 28, 2026

View reviewed changes

miguelg719 merged commit aeb1ba0 into main Oct 29, 2026
25 checks passed

miguelg719 deleted the feat/browser-disconnect branch October 29, 2026 01:15

github-actions Bot mentioned this pull request Oct 29, 2026

Release Stagehand packages #3332

Open

Conversation

miguelg719 commented Oct 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

why

what changed

test plan

Uh oh!

changeset-bot Bot commented Oct 22, 2026 • 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 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

seanmcguire12 Oct 26, 2026

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

miguelg719 commented Oct 22, 2026 •

edited

Loading

changeset-bot Bot commented Oct 22, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading