@browserbasehq/orca 3.0.9-alpha-3 → 3.1.0-headers

package/dist/esm/lib/v3/runtimePaths.d.ts

@@ -0,0 +1,6 @@
+export declare const getCurrentFilePath: () => string;
+export declare const getCurrentDirPath: () => string;
+export declare const getRepoRootDir: () => string;
+export declare const getPackageRootDir: () => string;
+export declare const createRequireFromCaller: () => NodeJS.Require;
+export declare const isMainModule: () => boolean;

package/dist/esm/lib/v3/runtimePaths.js

@@ -0,0 +1,107 @@
+/**
+ * Keep this file in sync with:
+ * - /packages/core/lib/v3/runtimePaths.ts
+ * - /packages/server-v3/scripts/runtimePaths.ts
+ * - /packages/server-v4/scripts/runtimePaths.ts
+ * - /packages/evals/runtimePaths.ts
+ * - /packages/docs/scripts/runtimePaths.js
+ */
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+const PACKAGE_SEGMENT = "/packages/core/";
+const EVAL_FRAMES = new Set(["[eval]", "[eval]-wrapper"]);
+const INTERNAL_FRAME_NAMES = new Set([
+    "readCallsites",
+    "readCallsitePath",
+    "resolveCallerFilePath",
+    "getCurrentFilePath",
+    "getCurrentDirPath",
+    "getRepoRootDir",
+    "getPackageRootDir",
+    "createRequireFromCaller",
+    "isMainModule",
+]);
+const normalizePath = (value) => {
+    const input = value.startsWith("file://") ? fileURLToPath(value) : value;
+    return path.resolve(input).replaceAll("\\", "/");
+};
+const readCallsites = () => {
+    const previousPrepare = Error.prepareStackTrace;
+    try {
+        Error.prepareStackTrace = (_, stack) => stack;
+        return (new Error().stack ?? []);
+    }
+    finally {
+        Error.prepareStackTrace = previousPrepare;
+    }
+};
+const readCallsitePath = (callsite) => {
+    const callsiteWithScript = callsite;
+    const rawPath = callsite.getFileName() ?? callsiteWithScript.getScriptNameOrSourceURL?.();
+    if (!rawPath)
+        return null;
+    if (rawPath.startsWith("node:"))
+        return null;
+    if (EVAL_FRAMES.has(rawPath))
+        return null;
+    return normalizePath(rawPath);
+};
+const isInternalCallsite = (callsite) => {
+    const functionName = callsite.getFunctionName();
+    if (functionName && INTERNAL_FRAME_NAMES.has(functionName))
+        return true;
+    const methodName = callsite.getMethodName();
+    if (methodName && INTERNAL_FRAME_NAMES.has(methodName))
+        return true;
+    const callsiteString = callsite.toString();
+    for (const frameName of INTERNAL_FRAME_NAMES) {
+        if (callsiteString.includes(`${frameName} (`))
+            return true;
+        if (callsiteString.includes(`.${frameName} (`))
+            return true;
+    }
+    return false;
+};
+const resolveCallerFilePath = () => {
+    const packageCandidates = [];
+    const fallbackCandidates = [];
+    for (const callsite of readCallsites()) {
+        const filePath = readCallsitePath(callsite);
+        if (!filePath)
+            continue;
+        if (isInternalCallsite(callsite))
+            continue;
+        if (filePath.includes(PACKAGE_SEGMENT)) {
+            packageCandidates.push(filePath);
+            continue;
+        }
+        fallbackCandidates.push(filePath);
+    }
+    const packageCandidate = packageCandidates[0];
+    if (packageCandidate)
+        return packageCandidate;
+    const fallbackCandidate = fallbackCandidates[0];
+    if (fallbackCandidate)
+        return fallbackCandidate;
+    throw new Error("Unable to resolve caller file path.");
+};
+export const getCurrentFilePath = () => resolveCallerFilePath();
+export const getCurrentDirPath = () => path.dirname(getCurrentFilePath());
+export const getRepoRootDir = () => {
+    const currentFilePath = getCurrentFilePath();
+    const index = currentFilePath.lastIndexOf(PACKAGE_SEGMENT);
+    if (index === -1) {
+        throw new Error(`Unable to determine repo root from ${currentFilePath} (missing ${PACKAGE_SEGMENT}).`);
+    }
+    return currentFilePath.slice(0, index);
+};
+export const getPackageRootDir = () => `${getRepoRootDir()}${PACKAGE_SEGMENT.slice(0, -1)}`;
+export const createRequireFromCaller = () => createRequire(getCurrentFilePath());
+export const isMainModule = () => {
+    const entryScript = process.argv.at(1);
+    if (!entryScript)
+        return false;
+    return normalizePath(entryScript) === getCurrentFilePath();
+};
+//# sourceMappingURL=runtimePaths.js.map

package/dist/esm/lib/v3/runtimePaths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimePaths.js","sourceRoot":"","sources":["../../../../lib/v3/runtimePaths.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Keep this file in sync with:\n * - /packages/core/lib/v3/runtimePaths.ts\n * - /packages/server-v3/scripts/runtimePaths.ts\n * - /packages/server-v4/scripts/runtimePaths.ts\n * - /packages/evals/runtimePaths.ts\n * - /packages/docs/scripts/runtimePaths.js\n */\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { createRequire } from \"node:module\";\n\nconst PACKAGE_SEGMENT = \"/packages/core/\";\nconst EVAL_FRAMES = new Set([\"[eval]\", \"[eval]-wrapper\"]);\nconst INTERNAL_FRAME_NAMES = new Set([\n  \"readCallsites\",\n  \"readCallsitePath\",\n  \"resolveCallerFilePath\",\n  \"getCurrentFilePath\",\n  \"getCurrentDirPath\",\n  \"getRepoRootDir\",\n  \"getPackageRootDir\",\n  \"createRequireFromCaller\",\n  \"isMainModule\",\n]);\n\nconst normalizePath = (value: string): string => {\n  const input = value.startsWith(\"file://\") ? fileURLToPath(value) : value;\n  return path.resolve(input).replaceAll(\"\\\\\", \"/\");\n};\n\nconst readCallsites = (): NodeJS.CallSite[] => {\n  const previousPrepare = Error.prepareStackTrace;\n  try {\n    Error.prepareStackTrace = (_, stack) => stack;\n    return (\n      (new Error().stack as unknown as NodeJS.CallSite[] | undefined) ?? []\n    );\n  } finally {\n    Error.prepareStackTrace = previousPrepare;\n  }\n};\n\ntype CallSiteWithScriptName = NodeJS.CallSite & {\n  getScriptNameOrSourceURL?: () => string | null;\n};\n\nconst readCallsitePath = (callsite: NodeJS.CallSite): string | null => {\n  const callsiteWithScript = callsite as CallSiteWithScriptName;\n  const rawPath =\n    callsite.getFileName() ?? callsiteWithScript.getScriptNameOrSourceURL?.();\n  if (!rawPath) return null;\n  if (rawPath.startsWith(\"node:\")) return null;\n  if (EVAL_FRAMES.has(rawPath)) return null;\n  return normalizePath(rawPath);\n};\n\nconst isInternalCallsite = (callsite: NodeJS.CallSite): boolean => {\n  const functionName = callsite.getFunctionName();\n  if (functionName && INTERNAL_FRAME_NAMES.has(functionName)) return true;\n\n  const methodName = callsite.getMethodName();\n  if (methodName && INTERNAL_FRAME_NAMES.has(methodName)) return true;\n\n  const callsiteString = callsite.toString();\n  for (const frameName of INTERNAL_FRAME_NAMES) {\n    if (callsiteString.includes(`${frameName} (`)) return true;\n    if (callsiteString.includes(`.${frameName} (`)) return true;\n  }\n  return false;\n};\n\nconst resolveCallerFilePath = (): string => {\n  const packageCandidates: string[] = [];\n  const fallbackCandidates: string[] = [];\n\n  for (const callsite of readCallsites()) {\n    const filePath = readCallsitePath(callsite);\n    if (!filePath) continue;\n    if (isInternalCallsite(callsite)) continue;\n    if (filePath.includes(PACKAGE_SEGMENT)) {\n      packageCandidates.push(filePath);\n      continue;\n    }\n    fallbackCandidates.push(filePath);\n  }\n\n  const packageCandidate = packageCandidates[0];\n  if (packageCandidate) return packageCandidate;\n\n  const fallbackCandidate = fallbackCandidates[0];\n  if (fallbackCandidate) return fallbackCandidate;\n\n  throw new Error(\"Unable to resolve caller file path.\");\n};\n\nexport const getCurrentFilePath = (): string => resolveCallerFilePath();\n\nexport const getCurrentDirPath = (): string =>\n  path.dirname(getCurrentFilePath());\n\nexport const getRepoRootDir = (): string => {\n  const currentFilePath = getCurrentFilePath();\n  const index = currentFilePath.lastIndexOf(PACKAGE_SEGMENT);\n  if (index === -1) {\n    throw new Error(\n      `Unable to determine repo root from ${currentFilePath} (missing ${PACKAGE_SEGMENT}).`,\n    );\n  }\n  return currentFilePath.slice(0, index);\n};\n\nexport const getPackageRootDir = (): string =>\n  `${getRepoRootDir()}${PACKAGE_SEGMENT.slice(0, -1)}`;\n\nexport const createRequireFromCaller = () =>\n  createRequire(getCurrentFilePath());\n\nexport const isMainModule = (): boolean => {\n  const entryScript = process.argv.at(1);\n  if (!entryScript) return false;\n  return normalizePath(entryScript) === getCurrentFilePath();\n};\n"]}

package/dist/esm/lib/v3/shutdown/cleanupLocal.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 declare function cleanupLocalBrowser(opts: {
+    killChrome?: () => Promise<void> | void;
+    userDataDir?: string;
+    createdTempProfile?: boolean;
+    preserveUserDataDir?: boolean;
+}): Promise<void>;

package/dist/esm/lib/v3/shutdown/cleanupLocal.js

@@ -0,0 +1,30 @@
+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) {
+    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
+        }
+    }
+}
+//# sourceMappingURL=cleanupLocal.js.map

package/dist/esm/lib/v3/shutdown/cleanupLocal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanupLocal.js","sourceRoot":"","sources":["../../../../../lib/v3/shutdown/cleanupLocal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,IAKzC;IACC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,cAAc;QAChB,CAAC;IACH,CAAC;IACD,IACE,IAAI,CAAC,kBAAkB;QACvB,CAAC,IAAI,CAAC,mBAAmB;QACzB,IAAI,CAAC,WAAW,EAChB,CAAC;QACD,IAAI,CAAC;YACH,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAChE,CAAC;QAAC,MAAM,CAAC;YACP,wBAAwB;QAC1B,CAAC;IACH,CAAC;AACH,CAAC","sourcesContent":["import fs from \"node:fs\";\n\n/**\n * Shared cleanup logic for locally launched Chrome.\n *\n * Used by both `V3.close()` (normal shutdown) and the supervisor process\n * (crash cleanup). The caller provides a `killChrome` callback since the\n * kill mechanism differs: chrome-launcher's `chrome.kill()` in-process\n * vs raw `process.kill(pid)` from the supervisor.\n */\nexport async function cleanupLocalBrowser(opts: {\n  killChrome?: () => Promise<void> | void;\n  userDataDir?: string;\n  createdTempProfile?: boolean;\n  preserveUserDataDir?: boolean;\n}): Promise<void> {\n  if (opts.killChrome) {\n    try {\n      await opts.killChrome();\n    } catch {\n      // best-effort\n    }\n  }\n  if (\n    opts.createdTempProfile &&\n    !opts.preserveUserDataDir &&\n    opts.userDataDir\n  ) {\n    try {\n      fs.rmSync(opts.userDataDir, { recursive: true, force: true });\n    } catch {\n      // ignore cleanup errors\n    }\n  }\n}\n"]}

package/dist/esm/lib/v3/shutdown/supervisor.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shutdown supervisor process.
+ *
+ * This process watches a stdin lifeline. When the parent dies, stdin closes
+ * and the supervisor performs best-effort cleanup:
+ * - LOCAL: kill Chrome + remove temp profile
+ * - STAGEHAND_API: request session release
+ */
+import type { ShutdownSupervisorConfig } from "../types/private/shutdown.js";
+export declare const runShutdownSupervisor: (initialConfig: ShutdownSupervisorConfig) => void;
+export declare const maybeRunShutdownSupervisorFromArgv: (argv?: readonly string[]) => boolean;

package/dist/esm/lib/v3/shutdown/supervisor.js

@@ -0,0 +1,185 @@
+/**
+ * Shutdown supervisor process.
+ *
+ * This process watches a stdin lifeline. When the parent dies, stdin closes
+ * and the supervisor performs best-effort cleanup:
+ * - LOCAL: kill Chrome + remove temp profile
+ * - STAGEHAND_API: request session release
+ */
+import Browserbase from "@browserbasehq/sdk";
+import { cleanupLocalBrowser } from "./cleanupLocal.js";
+const SIGKILL_POLL_MS = 250;
+const SIGKILL_TIMEOUT_MS = 7_000;
+const PID_POLL_INTERVAL_MS = 500;
+// `cleanupPromise` guarantees we execute cleanup at most once.
+let config = null;
+let cleanupPromise = null;
+let started = false;
+let localPidKnownGone = false;
+const exit = (code = 0) => {
+    try {
+        process.exit(code);
+    }
+    catch {
+        // ignore
+    }
+};
+// Best-effort two-phase kill: SIGTERM first, then SIGKILL after timeout.
+// Treat only ESRCH as "already gone"; other errors should not imply dead.
+const politeKill = async (pid) => {
+    const isAlive = () => {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (error) {
+            const err = error;
+            // ESRCH = "No such process" (PID is already gone).
+            return err.code !== "ESRCH";
+        }
+    };
+    if (!isAlive())
+        return;
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch (error) {
+        const err = error;
+        // ESRCH = process already exited; no further action needed.
+        if (err.code === "ESRCH")
+            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 pidPollTimer = null;
+// Local-only fallback: if Chrome dies while parent still lives, run cleanup and exit.
+const startPidPolling = (pid) => {
+    if (pidPollTimer)
+        return;
+    pidPollTimer = setInterval(() => {
+        try {
+            process.kill(pid, 0);
+            return;
+        }
+        catch (error) {
+            const err = error;
+            // Only ESRCH means the process is definitely gone.
+            if (err.code !== "ESRCH")
+                return;
+        }
+        localPidKnownGone = true;
+        if (pidPollTimer) {
+            clearInterval(pidPollTimer);
+            pidPollTimer = null;
+        }
+        void runCleanup("Browser process exited").finally(() => exit(0));
+    }, PID_POLL_INTERVAL_MS);
+};
+const cleanupLocal = async (cfg, reason) => {
+    const deletingUserDataDir = Boolean(cfg.createdTempProfile && !cfg.preserveUserDataDir && cfg.userDataDir);
+    await cleanupLocalBrowser({
+        // If polling already observed ESRCH, avoid a follow-up PID kill.
+        // The PID could be reused by a different process before cleanup runs.
+        killChrome: cfg.pid && !localPidKnownGone
+            ? () => {
+                console.error(`[shutdown-supervisor] Shutting down Chrome pid=${cfg.pid} ` +
+                    `(reason=${reason}, deletingUserDataDir=${deletingUserDataDir})`);
+                return politeKill(cfg.pid);
+            }
+            : undefined,
+        userDataDir: cfg.userDataDir,
+        createdTempProfile: cfg.createdTempProfile,
+        preserveUserDataDir: cfg.preserveUserDataDir,
+    });
+};
+const cleanupBrowserbase = async (cfg, reason) => {
+    if (!cfg.apiKey || !cfg.sessionId)
+        return;
+    try {
+        console.error(`[shutdown-supervisor] Ending Browserbase session ${cfg.sessionId} ` +
+            `(reason=${reason})`);
+        const bb = new Browserbase({ apiKey: cfg.apiKey });
+        await bb.sessions.update(cfg.sessionId, {
+            status: "REQUEST_RELEASE",
+            ...(cfg.projectId ? { projectId: cfg.projectId } : {}),
+        });
+    }
+    catch {
+        // best-effort cleanup
+    }
+};
+// Idempotent cleanup entrypoint used by all supervisor shutdown paths.
+const runCleanup = (reason) => {
+    if (!cleanupPromise) {
+        cleanupPromise = (async () => {
+            const cfg = config;
+            if (!cfg)
+                return;
+            if (cfg.kind === "LOCAL") {
+                await cleanupLocal(cfg, reason);
+                return;
+            }
+            if (cfg.kind === "STAGEHAND_API") {
+                await cleanupBrowserbase(cfg, reason);
+            }
+        })();
+    }
+    return cleanupPromise;
+};
+const applyConfig = (nextConfig) => {
+    config = nextConfig;
+    localPidKnownGone = false;
+    if (config.kind === "LOCAL" && config.pid) {
+        startPidPolling(config.pid);
+    }
+};
+const onLifelineClosed = (reason) => {
+    void runCleanup(reason).finally(() => exit(0));
+};
+const parseConfigFromArgv = (argv = process.argv.slice(2)) => {
+    const prefix = "--supervisor-config=";
+    const raw = argv.find((arg) => arg.startsWith(prefix))?.slice(prefix.length);
+    if (!argv.includes("--supervisor") || !raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+export const runShutdownSupervisor = (initialConfig) => {
+    if (started)
+        return;
+    started = true;
+    applyConfig(initialConfig);
+    // Stdin is the lifeline; losing it means parent is gone.
+    try {
+        process.stdin.resume();
+        process.stdin.on("end", () => onLifelineClosed("Stagehand process completed"));
+        process.stdin.on("close", () => onLifelineClosed("Stagehand process completed"));
+        process.stdin.on("error", () => onLifelineClosed("Stagehand process crashed or was killed"));
+    }
+    catch {
+        // ignore
+    }
+};
+export const maybeRunShutdownSupervisorFromArgv = (argv = process.argv.slice(2)) => {
+    const parsed = parseConfigFromArgv(argv);
+    if (!parsed)
+        return false;
+    runShutdownSupervisor(parsed);
+    return true;
+};
+//# sourceMappingURL=supervisor.js.map

package/dist/esm/lib/v3/shutdown/supervisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.js","sourceRoot":"","sources":["../../../../../lib/v3/shutdown/supervisor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shutdown supervisor process.\n *\n * This process watches a stdin lifeline. When the parent dies, stdin closes\n * and the supervisor performs best-effort cleanup:\n * - LOCAL: kill Chrome + remove temp profile\n * - STAGEHAND_API: request session release\n */\n\nimport Browserbase from \"@browserbasehq/sdk\";\nimport type { ShutdownSupervisorConfig } from \"../types/private/shutdown.js\";\nimport { cleanupLocalBrowser } from \"./cleanupLocal.js\";\n\nconst SIGKILL_POLL_MS = 250;\nconst SIGKILL_TIMEOUT_MS = 7_000;\nconst PID_POLL_INTERVAL_MS = 500;\n\n// `cleanupPromise` guarantees we execute cleanup at most once.\nlet config: ShutdownSupervisorConfig | null = null;\nlet cleanupPromise: Promise<void> | null = null;\nlet started = false;\nlet localPidKnownGone = false;\n\nconst exit = (code = 0): void => {\n  try {\n    process.exit(code);\n  } catch {\n    // ignore\n  }\n};\n\n// Best-effort two-phase kill: SIGTERM first, then SIGKILL after timeout.\n// Treat only ESRCH as \"already gone\"; other errors should not imply dead.\nconst politeKill = async (pid: number): Promise<void> => {\n  const isAlive = (): boolean => {\n    try {\n      process.kill(pid, 0);\n      return true;\n    } catch (error) {\n      const err = error as NodeJS.ErrnoException;\n      // ESRCH = \"No such process\" (PID is already gone).\n      return err.code !== \"ESRCH\";\n    }\n  };\n\n  if (!isAlive()) return;\n  try {\n    process.kill(pid, \"SIGTERM\");\n  } catch (error) {\n    const err = error as NodeJS.ErrnoException;\n    // ESRCH = process already exited; no further action needed.\n    if (err.code === \"ESRCH\") return;\n  }\n\n  const deadline = Date.now() + SIGKILL_TIMEOUT_MS;\n  while (Date.now() < deadline) {\n    await new Promise((resolve) => setTimeout(resolve, SIGKILL_POLL_MS));\n    if (!isAlive()) return;\n  }\n  try {\n    process.kill(pid, \"SIGKILL\");\n  } catch {\n    // best-effort\n  }\n};\n\nlet pidPollTimer: NodeJS.Timeout | null = null;\n\n// Local-only fallback: if Chrome dies while parent still lives, run cleanup and exit.\nconst startPidPolling = (pid: number): void => {\n  if (pidPollTimer) return;\n  pidPollTimer = setInterval(() => {\n    try {\n      process.kill(pid, 0);\n      return;\n    } catch (error) {\n      const err = error as NodeJS.ErrnoException;\n      // Only ESRCH means the process is definitely gone.\n      if (err.code !== \"ESRCH\") return;\n    }\n\n    localPidKnownGone = true;\n    if (pidPollTimer) {\n      clearInterval(pidPollTimer);\n      pidPollTimer = null;\n    }\n    void runCleanup(\"Browser process exited\").finally(() => exit(0));\n  }, PID_POLL_INTERVAL_MS);\n};\n\nconst cleanupLocal = async (\n  cfg: Extract<ShutdownSupervisorConfig, { kind: \"LOCAL\" }>,\n  reason: string,\n) => {\n  const deletingUserDataDir = Boolean(\n    cfg.createdTempProfile && !cfg.preserveUserDataDir && cfg.userDataDir,\n  );\n  await cleanupLocalBrowser({\n    // If polling already observed ESRCH, avoid a follow-up PID kill.\n    // The PID could be reused by a different process before cleanup runs.\n    killChrome:\n      cfg.pid && !localPidKnownGone\n        ? () => {\n            console.error(\n              `[shutdown-supervisor] Shutting down Chrome pid=${cfg.pid} ` +\n                `(reason=${reason}, deletingUserDataDir=${deletingUserDataDir})`,\n            );\n            return politeKill(cfg.pid);\n          }\n        : undefined,\n    userDataDir: cfg.userDataDir,\n    createdTempProfile: cfg.createdTempProfile,\n    preserveUserDataDir: cfg.preserveUserDataDir,\n  });\n};\n\nconst cleanupBrowserbase = async (\n  cfg: Extract<ShutdownSupervisorConfig, { kind: \"STAGEHAND_API\" }>,\n  reason: string,\n) => {\n  if (!cfg.apiKey || !cfg.sessionId) return;\n  try {\n    console.error(\n      `[shutdown-supervisor] Ending Browserbase session ${cfg.sessionId} ` +\n        `(reason=${reason})`,\n    );\n    const bb = new Browserbase({ apiKey: cfg.apiKey });\n    await bb.sessions.update(cfg.sessionId, {\n      status: \"REQUEST_RELEASE\",\n      ...(cfg.projectId ? { projectId: cfg.projectId } : {}),\n    } as Browserbase.Sessions.SessionUpdateParams);\n  } catch {\n    // best-effort cleanup\n  }\n};\n\n// Idempotent cleanup entrypoint used by all supervisor shutdown paths.\nconst runCleanup = (reason: string): Promise<void> => {\n  if (!cleanupPromise) {\n    cleanupPromise = (async () => {\n      const cfg = config;\n      if (!cfg) return;\n      if (cfg.kind === \"LOCAL\") {\n        await cleanupLocal(cfg, reason);\n        return;\n      }\n      if (cfg.kind === \"STAGEHAND_API\") {\n        await cleanupBrowserbase(cfg, reason);\n      }\n    })();\n  }\n  return cleanupPromise;\n};\n\nconst applyConfig = (nextConfig: ShutdownSupervisorConfig): void => {\n  config = nextConfig;\n  localPidKnownGone = false;\n  if (config.kind === \"LOCAL\" && config.pid) {\n    startPidPolling(config.pid);\n  }\n};\n\nconst onLifelineClosed = (reason: string) => {\n  void runCleanup(reason).finally(() => exit(0));\n};\n\nconst parseConfigFromArgv = (\n  argv: readonly string[] = process.argv.slice(2),\n): ShutdownSupervisorConfig | null => {\n  const prefix = \"--supervisor-config=\";\n  const raw = argv.find((arg) => arg.startsWith(prefix))?.slice(prefix.length);\n  if (!argv.includes(\"--supervisor\") || !raw) return null;\n  try {\n    return JSON.parse(raw) as ShutdownSupervisorConfig;\n  } catch {\n    return null;\n  }\n};\n\nexport const runShutdownSupervisor = (\n  initialConfig: ShutdownSupervisorConfig,\n): void => {\n  if (started) return;\n  started = true;\n  applyConfig(initialConfig);\n\n  // Stdin is the lifeline; losing it means parent is gone.\n  try {\n    process.stdin.resume();\n    process.stdin.on(\"end\", () =>\n      onLifelineClosed(\"Stagehand process completed\"),\n    );\n    process.stdin.on(\"close\", () =>\n      onLifelineClosed(\"Stagehand process completed\"),\n    );\n    process.stdin.on(\"error\", () =>\n      onLifelineClosed(\"Stagehand process crashed or was killed\"),\n    );\n  } catch {\n    // ignore\n  }\n};\n\nexport const maybeRunShutdownSupervisorFromArgv = (\n  argv: readonly string[] = process.argv.slice(2),\n): boolean => {\n  const parsed = parseConfigFromArgv(argv);\n  if (!parsed) return false;\n  runShutdownSupervisor(parsed);\n  return true;\n};\n"]}

package/dist/esm/lib/v3/shutdown/supervisorClient.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 type { ShutdownSupervisorConfig, ShutdownSupervisorHandle } from "../types/private/shutdown.js";
+/**
+ * Start a supervisor process for crash cleanup. Returns a handle that can
+ * stop the supervisor during a normal shutdown.
+ */
+export declare function startShutdownSupervisor(config: ShutdownSupervisorConfig, opts?: {
+    onError?: (error: Error, context: string) => void;
+}): ShutdownSupervisorHandle | null;

package/dist/esm/lib/v3/shutdown/supervisorClient.js

@@ -0,0 +1,89 @@
+/**
+ * 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 { createRequire } from "node:module";
+import { ShutdownSupervisorResolveError, ShutdownSupervisorSpawnError, } from "../types/private/shutdownErrors.js";
+import { getCurrentFilePath } from "../runtimePaths.js";
+const moduleFilename = getCurrentFilePath();
+const moduleDir = path.dirname(moduleFilename);
+const nodeRequire = createRequire(moduleFilename);
+const isSeaRuntime = () => {
+    try {
+        const sea = nodeRequire("node:sea");
+        return Boolean(sea.isSea?.());
+    }
+    catch {
+        return false;
+    }
+};
+// SEA: re-exec current binary with supervisor args.
+// Non-SEA: execute Stagehand CLI entrypoint with supervisor args.
+const resolveCliPath = () => `${moduleDir}/../cli.js`;
+const resolveSupervisorCommand = (config) => {
+    const baseArgs = ["--supervisor", serializeConfigArg(config)];
+    if (isSeaRuntime()) {
+        return { command: process.execPath, args: baseArgs };
+    }
+    const cliPath = resolveCliPath();
+    if (!fs.existsSync(cliPath))
+        return null;
+    const needsTsxLoader = fs.existsSync(`${moduleDir}/supervisor.ts`) &&
+        !fs.existsSync(`${moduleDir}/supervisor.js`);
+    return {
+        command: process.execPath,
+        args: needsTsxLoader
+            ? ["--import", "tsx", cliPath, ...baseArgs]
+            : [cliPath, ...baseArgs],
+    };
+};
+// Single JSON arg keeps supervisor bootstrap parsing tiny and versionable.
+const serializeConfigArg = (config) => `--supervisor-config=${JSON.stringify({
+    ...config,
+    parentPid: process.pid,
+})}`;
+/**
+ * Start a supervisor process for crash cleanup. Returns a handle that can
+ * stop the supervisor during a normal shutdown.
+ */
+export function startShutdownSupervisor(config, opts) {
+    const resolved = resolveSupervisorCommand(config);
+    if (!resolved) {
+        opts?.onError?.(new ShutdownSupervisorResolveError("Shutdown supervisor entry missing (expected Stagehand CLI entrypoint)."), "resolve");
+        return null;
+    }
+    const child = spawn(resolved.command, resolved.args, {
+        // stdin is the parent lifeline.
+        // Preserve supervisor stderr so crash-cleanup debug lines are visible.
+        stdio: ["pipe", "ignore", "inherit"],
+        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;
+        stdin?.unref?.();
+    }
+    catch {
+        // best-effort: avoid keeping the event loop alive
+    }
+    const stop = () => {
+        // Normal close path: terminate supervisor directly.
+        try {
+            child.kill("SIGTERM");
+        }
+        catch {
+            // ignore
+        }
+    };
+    return { stop };
+}
+//# sourceMappingURL=supervisorClient.js.map

package/dist/esm/lib/v3/shutdown/supervisorClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisorClient.js","sourceRoot":"","sources":["../../../../../lib/v3/shutdown/supervisorClient.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Parent-side helper for spawning the shutdown supervisor process.\n *\n * The supervisor runs out-of-process and watches a lifeline pipe. If the parent\n * dies, the supervisor performs best-effort cleanup (Chrome kill or Browserbase\n * session release) when keepAlive is false.\n */\n\nimport fs from \"node:fs\";\nimport path from \"node:path\";\nimport { spawn } from \"node:child_process\";\nimport { createRequire } from \"node:module\";\nimport type {\n  ShutdownSupervisorConfig,\n  ShutdownSupervisorHandle,\n} from \"../types/private/shutdown.js\";\nimport {\n  ShutdownSupervisorResolveError,\n  ShutdownSupervisorSpawnError,\n} from \"../types/private/shutdownErrors.js\";\nimport { getCurrentFilePath } from \"../runtimePaths.js\";\n\nconst moduleFilename = getCurrentFilePath();\nconst moduleDir = path.dirname(moduleFilename);\nconst nodeRequire = createRequire(moduleFilename);\n\nconst isSeaRuntime = (): boolean => {\n  try {\n    const sea = nodeRequire(\"node:sea\") as { isSea?: () => boolean };\n    return Boolean(sea.isSea?.());\n  } catch {\n    return false;\n  }\n};\n\n// SEA: re-exec current binary with supervisor args.\n// Non-SEA: execute Stagehand CLI entrypoint with supervisor args.\nconst resolveCliPath = (): string => `${moduleDir}/../cli.js`;\n\nconst resolveSupervisorCommand = (\n  config: ShutdownSupervisorConfig,\n): {\n  command: string;\n  args: string[];\n} | null => {\n  const baseArgs = [\"--supervisor\", serializeConfigArg(config)];\n\n  if (isSeaRuntime()) {\n    return { command: process.execPath, args: baseArgs };\n  }\n\n  const cliPath = resolveCliPath();\n  if (!fs.existsSync(cliPath)) return null;\n  const needsTsxLoader =\n    fs.existsSync(`${moduleDir}/supervisor.ts`) &&\n    !fs.existsSync(`${moduleDir}/supervisor.js`);\n  return {\n    command: process.execPath,\n    args: needsTsxLoader\n      ? [\"--import\", \"tsx\", cliPath, ...baseArgs]\n      : [cliPath, ...baseArgs],\n  };\n};\n\n// Single JSON arg keeps supervisor bootstrap parsing tiny and versionable.\nconst serializeConfigArg = (config: ShutdownSupervisorConfig): string =>\n  `--supervisor-config=${JSON.stringify({\n    ...config,\n    parentPid: process.pid,\n  })}`;\n\n/**\n * Start a supervisor process for crash cleanup. Returns a handle that can\n * stop the supervisor during a normal shutdown.\n */\nexport function startShutdownSupervisor(\n  config: ShutdownSupervisorConfig,\n  opts?: { onError?: (error: Error, context: string) => void },\n): ShutdownSupervisorHandle | null {\n  const resolved = resolveSupervisorCommand(config);\n  if (!resolved) {\n    opts?.onError?.(\n      new ShutdownSupervisorResolveError(\n        \"Shutdown supervisor entry missing (expected Stagehand CLI entrypoint).\",\n      ),\n      \"resolve\",\n    );\n    return null;\n  }\n\n  const child = spawn(resolved.command, resolved.args, {\n    // stdin is the parent lifeline.\n    // Preserve supervisor stderr so crash-cleanup debug lines are visible.\n    stdio: [\"pipe\", \"ignore\", \"inherit\"],\n    detached: true,\n  });\n  child.on(\"error\", (error) => {\n    opts?.onError?.(\n      new ShutdownSupervisorSpawnError(\n        `Shutdown supervisor failed to start: ${error.message}`,\n      ),\n      \"spawn\",\n    );\n  });\n\n  try {\n    child.unref();\n    const stdin = child.stdin as unknown as { unref?: () => void } | null;\n    stdin?.unref?.();\n  } catch {\n    // best-effort: avoid keeping the event loop alive\n  }\n\n  const stop = () => {\n    // Normal close path: terminate supervisor directly.\n    try {\n      child.kill(\"SIGTERM\");\n    } catch {\n      // ignore\n    }\n  };\n\n  return { stop };\n}\n"]}

package/dist/esm/lib/v3/timeoutConfig.d.ts

@@ -0,0 +1,2 @@
+export declare function getEnvTimeoutMs(name: string): number | undefined;
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number | null | undefined, operation: string): Promise<T>;

package/dist/esm/lib/v3/timeoutConfig.js

@@ -0,0 +1,32 @@
+import { TimeoutError } from "./types/public/sdkErrors.js";
+export function getEnvTimeoutMs(name) {
+    const raw = process.env[name];
+    if (!raw)
+        return undefined;
+    const normalized = raw.trim().replace(/ms$/i, "");
+    const value = Number(normalized);
+    if (!Number.isFinite(value) || value <= 0)
+        return undefined;
+    return value;
+}
+export async function withTimeout(promise, timeoutMs, operation) {
+    if (typeof timeoutMs !== "number" ||
+        !Number.isFinite(timeoutMs) ||
+        timeoutMs <= 0) {
+        return await promise;
+    }
+    let timeoutId;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+            reject(new TimeoutError(operation, timeoutMs));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([promise, timeoutPromise]);
+    }
+    finally {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+    }
+}
+//# sourceMappingURL=timeoutConfig.js.map

package/dist/esm/lib/v3/timeoutConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeoutConfig.js","sourceRoot":"","sources":["../../../../lib/v3/timeoutConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3B,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IACjC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5D,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAmB,EACnB,SAAoC,EACpC,SAAiB;IAEjB,IACE,OAAO,SAAS,KAAK,QAAQ;QAC7B,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC;QAC3B,SAAS,IAAI,CAAC,EACd,CAAC;QACD,OAAO,MAAM,OAAO,CAAC;IACvB,CAAC;IAED,IAAI,SAAqC,CAAC;IAC1C,MAAM,cAAc,GAAG,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;QACtD,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;YAC1B,MAAM,CAAC,IAAI,YAAY,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC;QACjD,CAAC,EAAE,SAAS,CAAC,CAAC;IAChB,CAAC,CAAC,CAAC;IACH,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC;IACvD,CAAC;YAAS,CAAC;QACT,IAAI,SAAS;YAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IACzC,CAAC;AACH,CAAC","sourcesContent":["import { TimeoutError } from \"./types/public/sdkErrors.js\";\n\nexport function getEnvTimeoutMs(name: string): number | undefined {\n  const raw = process.env[name];\n  if (!raw) return undefined;\n  const normalized = raw.trim().replace(/ms$/i, \"\");\n  const value = Number(normalized);\n  if (!Number.isFinite(value) || value <= 0) return undefined;\n  return value;\n}\n\nexport async function withTimeout<T>(\n  promise: Promise<T>,\n  timeoutMs: number | null | undefined,\n  operation: string,\n): Promise<T> {\n  if (\n    typeof timeoutMs !== \"number\" ||\n    !Number.isFinite(timeoutMs) ||\n    timeoutMs <= 0\n  ) {\n    return await promise;\n  }\n\n  let timeoutId: NodeJS.Timeout | undefined;\n  const timeoutPromise = new Promise<never>((_, reject) => {\n    timeoutId = setTimeout(() => {\n      reject(new TimeoutError(operation, timeoutMs));\n    }, timeoutMs);\n  });\n  try {\n    return await Promise.race([promise, timeoutPromise]);\n  } finally {\n    if (timeoutId) clearTimeout(timeoutId);\n  }\n}\n"]}

package/dist/esm/lib/v3/types/private/agent.d.ts

@@ -0,0 +1,6 @@
+export interface ActionMappingOptions {
+    toolCallName: string;
+    toolResult: unknown;
+    args: Record<string, unknown>;
+    reasoning?: string;
+}

package/dist/esm/lib/v3/types/private/agent.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agent.js.map

package/dist/esm/lib/v3/types/private/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/agent.ts"],"names":[],"mappings":"","sourcesContent":["export interface ActionMappingOptions {\n  toolCallName: string;\n  toolResult: unknown;\n  args: Record<string, unknown>;\n  reasoning?: string;\n}\n"]}

package/dist/esm/lib/v3/types/private/api.d.ts

@@ -0,0 +1,11 @@
+import type { Protocol } from "devtools-protocol";
+export interface SerializableResponse {
+    requestId: string;
+    frameId?: string;
+    loaderId?: string;
+    response: Protocol.Network.Response;
+    fromServiceWorkerFlag?: boolean;
+    finishedSettled?: boolean;
+    extraInfoHeaders?: Protocol.Network.Headers | null;
+    extraInfoHeadersText?: string;
+}

package/dist/esm/lib/v3/types/private/api.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=api.js.map

package/dist/esm/lib/v3/types/private/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/api.ts"],"names":[],"mappings":"","sourcesContent":["import type { Protocol } from \"devtools-protocol\";\n\nexport interface SerializableResponse {\n  requestId: string;\n  frameId?: string;\n  loaderId?: string;\n  response: Protocol.Network.Response;\n  fromServiceWorkerFlag?: boolean;\n  finishedSettled?: boolean;\n  extraInfoHeaders?: Protocol.Network.Headers | null;\n  extraInfoHeadersText?: string;\n}\n"]}