[feat]: add `keepAlive` param
Merged
SE
9mo ago+1245+1245+0123456789012345678901234567890123456789-95-95-01234567890123456789
why
- to give users the freedom to decide whether the browser should be kept open or "alive" when their stagehand instance is killed
- to follow best practices by avoiding usage of global signal handlers inside library code
what changed
new keepAlive option:
- added an optional, boolean
keepAliveparameter in the stagehand constructor params.keepAlivedefaults tofalse keepAliveon the constructor overridesbrowserbaseSessionCreateParams.keepAlivewhen both are provided out-of-process shutdown supervisor (packages/core/lib/v3/shutdown/):- replaced the old in-process global signal handlers (process.once("SIGINT"), etc.) with a detached supervisor process that watches a lifeline (stdin pipe + IPC channel) to the parent
- when
keepAliveis set tofalse, the supervisor is spawned duringinit()and performs best-effort cleanup if the parent dies unexpectedly:- if
envis"LOCAL"the supervisor kills the Chrome PID (with SIGTERM → SIGKILL escalation) and removes any temp user-data directory - if
envis"BROWSERBASE"& using the stagehand API, the supervisor sendsREQUEST_RELEASEto the browserbase API
- if
- the supervisor also includes PID polling to guard against process reuse (killing a recycled PID
- when
keepAliveis set totrue, no supervisor is spawned, & the browser is left running - when
disableAPIis set totrue(direct WS to Browserbase), no supervisor is spawned since the browser will auto release when the WS is dropped
refactored close() into helpers:
- pulled browser teardown logic into
shutdown/shutdownBrowser.ts(shutdownBrowserSession,shutdownLocalBrowser) - pulled stagehand internal state cleanup into
shutdown/shutdownStagehand.ts(shutdownStagehandResources,finalizeStagehandShutdown)
-.close()now skipsapiClient.end()whenkeepAlive: true
local browser launch changes:
- updated local launch to pass chrome launcher’s
handleSIGINTbased onkeepAliveinpackages/core/lib/v3/v3.tsandpackages/core/lib/v3/launch/local.ts. this prevents chrome from getting killed on Ctrl+C whenkeepAlive: true - updated local launch so that we
unref()the chrome child process after launch so Node can exit while chrome stays open (packages/core/lib/v3/v3.ts)
behaviour notes:
- setting
keepAlive: truewill keep the browser alive in the following scenarios:- stagehand instance gets killed because of an uncaught error (eg,
unhandledRejection,unhandledException) - stagehand instance gets killed because of a
SIGTERMorSIGINT - stagehand instance gets killed with an explicit call to
stagehand.close()
- stagehand instance gets killed because of an uncaught error (eg,
test plan
- added tests in
keep-alive.spec.tsthat validate expected behaviour across the following scenarios:unhandledRejection/unhandledException,SIGTERM/SIGINT,stagehand.close()
- each scenario is validated in each of the following browser configurations:
- using a local browser launched by stagehand
- using a browserbase browser, connected directly over the WS
- using a browserbase browser + the stagehand API
Summary by cubic
Adds a keepAlive option to Stagehand V3 so you control whether the browser/session stays up after stagehand.close(), signals, or uncaught errors. Replaces global process handlers with a per‑instance crash‑only supervisor with a ready handshake and PID polling to avoid race conditions (STG‑1338).
-
New Features
- keepAlive?: boolean (default false) on the V3 constructor; overrides browserbaseSessionCreateParams.keepAlive when set.
- Local: set handleSIGINT based on keepAlive and unref Chrome when true; when false, a detached supervisor watches a stdin/IPC lifeline and on parent crash/error SIGTERM→SIGKILLs Chrome and removes the temp profile (with PID polling). A shared cleanup helper is used by both close() and the supervisor for consistent local teardown.
- Browserbase: propagate keepAlive to session creation; when keepAlive is true, close() skips apiClient.end() so the session stays RUNNING; when false (and API enabled), the supervisor requests REQUEST_RELEASE on crash/error; when disableAPI is true (direct WS), no supervisor is spawned and the session ends when the WS drops.
-
Migration
- Set keepAlive: true in the V3 constructor to keep the browser/session open on errors, signals, or stagehand.close(); this overrides any value in browserbaseSessionCreateParams.
- When keepAlive is true, close resources yourself when done (Local: send Browser.close; Browserbase: request release/end the session).