[feat]: add `keepAlive` param

Merged
SE
9mo ago
+1245-95

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 keepAlive parameter in the stagehand constructor params. keepAlive defaults to false
  • keepAlive on the constructor overrides browserbaseSessionCreateParams.keepAlive when 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 keepAlive is set to false, the supervisor is spawned during init() and performs best-effort cleanup if the parent dies unexpectedly:
    • if env is "LOCAL" the supervisor kills the Chrome PID (with SIGTERM → SIGKILL escalation) and removes any temp user-data directory
    • if env is "BROWSERBASE" & using the stagehand API, the supervisor sends REQUEST_RELEASE to the browserbase API
  • the supervisor also includes PID polling to guard against process reuse (killing a recycled PID
  • when keepAlive is set to true, no supervisor is spawned, & the browser is left running
  • when disableAPI is set to true (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 skips apiClient.end() when keepAlive: true

local browser launch changes:

  • updated local launch to pass chrome launcher’s handleSIGINT based on keepAlive in packages/core/lib/v3/v3.ts and packages/core/lib/v3/launch/local.ts. this prevents chrome from getting killed on Ctrl+C when keepAlive: 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: true will 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 SIGTERM or SIGINT
    • stagehand instance gets killed with an explicit call to stagehand.close()

test plan

  • added tests in keep-alive.spec.ts that 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).