[feat]: add keepAlive param (browserbase#1672)

# 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


<!-- This is an auto-generated description by cubic. -->
---
## 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).

<sup>Written for commit 3887d8f.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1672">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->

Author: seanmcguire12

.changeset/hungry-areas-remain.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": minor
+---
+
+add boolean keepAlive parameter to allow for configuring whether the browser should be closed when stagehand.close() is called.

packages/core/lib/v3/launch/local.ts

@@ -8,6 +8,7 @@ interface LaunchLocalOptions {
   userDataDir?: string;
   port?: number;
   connectTimeoutMs?: number;
+  handleSIGINT?: boolean;
 }
 
 export async function launchLocalChrome(
@@ -29,6 +30,7 @@ export async function launchLocalChrome(
     chromeFlags,
     port: opts.port,
     userDataDir: opts.userDataDir,
+    handleSIGINT: opts.handleSIGINT,
   });
 
   const ws = await waitForWebSocketDebuggerUrl(

packages/core/lib/v3/shutdown/cleanupLocal.ts

@@ -0,0 +1,35 @@
+import fs from "node:fs";
+
+/**
+ * Shared cleanup logic for locally launched Chrome.
+ *
+ * Used by both `V3.close()` (normal shutdown) and the supervisor process
+ * (crash cleanup). The caller provides a `killChrome` callback since the
+ * kill mechanism differs: chrome-launcher's `chrome.kill()` in-process
+ * vs raw `process.kill(pid)` from the supervisor.
+ */
+export async function cleanupLocalBrowser(opts: {
+  killChrome?: () => Promise<void> | void;
+  userDataDir?: string;
+  createdTempProfile?: boolean;
+  preserveUserDataDir?: boolean;
+}): Promise<void> {
+  if (opts.killChrome) {
+    try {
+      await opts.killChrome();
+    } catch {
+      // best-effort
+    }
+  }
+  if (
+    opts.createdTempProfile &&
+    !opts.preserveUserDataDir &&
+    opts.userDataDir
+  ) {
+    try {
+      fs.rmSync(opts.userDataDir, { recursive: true, force: true });
+    } catch {
+      // ignore cleanup errors
+    }
+  }
+}

packages/core/lib/v3/shutdown/supervisor.ts

@@ -0,0 +1,163 @@
+/**
+ * Shutdown supervisor process.
+ *
+ * This process watches a lifeline (stdin/IPC). When the parent dies, the
+ * lifeline closes and the supervisor performs best-effort cleanup:
+ * - LOCAL: kill Chrome + remove temp profile (when keepAlive is false)
+ * - STAGEHAND_API: request session release (when keepAlive is false)
+ */
+
+import Browserbase from "@browserbasehq/sdk";
+import type {
+  ShutdownSupervisorConfig,
+  ShutdownSupervisorMessage,
+} from "../types/private/shutdown";
+import { cleanupLocalBrowser } from "./cleanupLocal";
+
+const SIGKILL_POLL_MS = 500;
+const SIGKILL_TIMEOUT_MS = 10_000;
+const PID_POLL_INTERVAL_MS = 500;
+
+let armed = false;
+let config: ShutdownSupervisorConfig | null = null;
+let cleanupPromise: Promise<void> | null = null;
+
+const exit = (code = 0): void => {
+  try {
+    process.exit(code);
+  } catch {
+    // ignore
+  }
+};
+
+const safeKill = async (pid: number): Promise<void> => {
+  const isAlive = (): boolean => {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  if (!isAlive()) return;
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+    return;
+  }
+
+  const deadline = Date.now() + SIGKILL_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, SIGKILL_POLL_MS));
+    if (!isAlive()) return;
+  }
+  try {
+    process.kill(pid, "SIGKILL");
+  } catch {
+    // best-effort
+  }
+};
+
+let pidGone = false;
+let pidPollTimer: NodeJS.Timeout | null = null;
+
+const startPidPolling = (pid: number): void => {
+  if (pidPollTimer) return;
+  pidPollTimer = setInterval(() => {
+    try {
+      process.kill(pid, 0);
+    } catch {
+      pidGone = true;
+      if (pidPollTimer) {
+        clearInterval(pidPollTimer);
+        pidPollTimer = null;
+      }
+    }
+  }, PID_POLL_INTERVAL_MS);
+};
+
+const cleanupLocal = async (
+  cfg: Extract<ShutdownSupervisorConfig, { kind: "LOCAL" }>,
+) => {
+  if (cfg.keepAlive) return;
+  await cleanupLocalBrowser({
+    killChrome: cfg.pid && !pidGone ? () => safeKill(cfg.pid) : undefined,
+    userDataDir: cfg.userDataDir,
+    createdTempProfile: cfg.createdTempProfile,
+    preserveUserDataDir: cfg.preserveUserDataDir,
+  });
+};
+
+const cleanupBrowserbase = async (
+  cfg: Extract<ShutdownSupervisorConfig, { kind: "STAGEHAND_API" }>,
+) => {
+  if (cfg.keepAlive) return;
+  if (!cfg.apiKey || !cfg.projectId || !cfg.sessionId) return;
+  try {
+    const bb = new Browserbase({ apiKey: cfg.apiKey });
+    await bb.sessions.update(cfg.sessionId, {
+      status: "REQUEST_RELEASE",
+      projectId: cfg.projectId,
+    });
+  } catch {
+    // best-effort cleanup
+  }
+};
+
+const runCleanup = (): Promise<void> => {
+  if (!cleanupPromise) {
+    cleanupPromise = (async () => {
+      const cfg = config;
+      if (!cfg || !armed) return;
+      armed = false;
+      if (cfg.kind === "LOCAL") {
+        await cleanupLocal(cfg);
+        return;
+      }
+      if (cfg.kind === "STAGEHAND_API") {
+        await cleanupBrowserbase(cfg);
+      }
+    })();
+  }
+  return cleanupPromise;
+};
+
+const onLifelineClosed = () => {
+  void runCleanup().finally(() => exit(0));
+};
+
+const onMessage = (raw: unknown) => {
+  if (!raw || typeof raw !== "object") return;
+  const msg = raw as ShutdownSupervisorMessage;
+  if (msg.type === "config") {
+    config = msg.config ?? null;
+    armed = Boolean(config) && config?.keepAlive === false;
+    if (armed && config?.kind === "LOCAL" && config?.pid) {
+      startPidPolling(config.pid);
+    }
+    try {
+      process.send?.({ type: "ready" });
+    } catch {
+      // ignore IPC failures
+    }
+    return;
+  }
+  if (msg.type === "exit") {
+    armed = false;
+    exit(0);
+  }
+};
+
+// Keep stdin open as a lifeline to the parent process.
+try {
+  process.stdin.resume();
+  process.stdin.on("end", onLifelineClosed);
+  process.stdin.on("close", onLifelineClosed);
+  process.stdin.on("error", onLifelineClosed);
+} catch {
+  // ignore
+}
+
+process.on("disconnect", onLifelineClosed);
+process.on("message", onMessage);

packages/core/lib/v3/shutdown/supervisorClient.ts

@@ -0,0 +1,121 @@
+/**
+ * Parent-side helper for spawning the shutdown supervisor process.
+ *
+ * The supervisor runs out-of-process and watches a lifeline pipe. If the parent
+ * dies, the supervisor performs best-effort cleanup (Chrome kill or Browserbase
+ * session release) when keepAlive is false.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import type {
+  ShutdownSupervisorConfig,
+  ShutdownSupervisorHandle,
+  ShutdownSupervisorMessage,
+} from "../types/private/shutdown";
+import {
+  ShutdownSupervisorResolveError,
+  ShutdownSupervisorSpawnError,
+} from "../types/private/shutdownErrors";
+
+const READY_TIMEOUT_MS = 500;
+
+const resolveSupervisorScript = (): {
+  command: string;
+  args: string[];
+} | null => {
+  const jsPath = path.resolve(__dirname, "supervisor.js");
+  if (fs.existsSync(jsPath)) {
+    return { command: process.execPath, args: [jsPath] };
+  }
+  const tsPath = path.resolve(__dirname, "supervisor.ts");
+  if (fs.existsSync(tsPath)) {
+    return { command: process.execPath, args: ["--import", "tsx", tsPath] };
+  }
+  return null;
+};
+
+/**
+ * Start a supervisor process for crash cleanup. Returns a handle that can
+ * stop the supervisor during a normal shutdown.
+ */
+export function startShutdownSupervisor(
+  config: ShutdownSupervisorConfig,
+  opts?: { onError?: (error: Error, context: string) => void },
+): ShutdownSupervisorHandle | null {
+  const resolved = resolveSupervisorScript();
+  if (!resolved) {
+    opts?.onError?.(
+      new ShutdownSupervisorResolveError(
+        "Shutdown supervisor script missing (expected supervisor.js or supervisor.ts next to shutdown/supervisorClient).",
+      ),
+      "resolve",
+    );
+    return null;
+  }
+
+  const child = spawn(resolved.command, resolved.args, {
+    stdio: ["pipe", "ignore", "ignore", "ipc"],
+    detached: true,
+  });
+  child.on("error", (error) => {
+    opts?.onError?.(
+      new ShutdownSupervisorSpawnError(
+        `Shutdown supervisor failed to start: ${error.message}`,
+      ),
+      "spawn",
+    );
+  });
+
+  try {
+    child.unref();
+    const stdin = child.stdin as unknown as { unref?: () => void } | null;
+    stdin?.unref?.();
+  } catch {
+    // best-effort: avoid keeping the event loop alive
+  }
+
+  try {
+    const message: ShutdownSupervisorMessage = { type: "config", config };
+    child.send?.(message);
+  } catch {
+    // ignore IPC failures
+  }
+
+  const ready = new Promise<void>((resolve) => {
+    let resolved = false;
+    const done = () => {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timer);
+      child.off("message", onMessage);
+      resolve();
+    };
+    const timer = setTimeout(done, READY_TIMEOUT_MS);
+    const onMessage = (msg: unknown) => {
+      const payload = msg as ShutdownSupervisorMessage;
+      if (payload?.type === "ready") {
+        done();
+      }
+    };
+    child.on("message", onMessage);
+    child.on("exit", done);
+  });
+
+  const stop = () => {
+    try {
+      const message: ShutdownSupervisorMessage = { type: "exit" };
+      child.send?.(message);
+    } catch {
+      // ignore
+    }
+    try {
+      child.disconnect?.();
+    } catch {
+      // ignore
+    }
+  };
+
+  return { stop, ready };
+}