@browserbasehq/orca 3.0.9-alpha-4 → 3.1.0-patch.1

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,166 @@
+/**
+ * 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;
+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);
+        }
+        catch {
+            if (pidPollTimer) {
+                clearInterval(pidPollTimer);
+                pidPollTimer = null;
+            }
+            void runCleanup().finally(() => exit(0));
+        }
+    }, PID_POLL_INTERVAL_MS);
+};
+const cleanupLocal = async (cfg) => {
+    await cleanupLocalBrowser({
+        killChrome: cfg.pid ? () => politeKill(cfg.pid) : undefined,
+        userDataDir: cfg.userDataDir,
+        createdTempProfile: cfg.createdTempProfile,
+        preserveUserDataDir: cfg.preserveUserDataDir,
+    });
+};
+const cleanupBrowserbase = async (cfg) => {
+    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
+    }
+};
+// Idempotent cleanup entrypoint used by all supervisor shutdown paths.
+const runCleanup = () => {
+    if (!cleanupPromise) {
+        cleanupPromise = (async () => {
+            const cfg = config;
+            if (!cfg)
+                return;
+            if (cfg.kind === "LOCAL") {
+                await cleanupLocal(cfg);
+                return;
+            }
+            if (cfg.kind === "STAGEHAND_API") {
+                await cleanupBrowserbase(cfg);
+            }
+        })();
+    }
+    return cleanupPromise;
+};
+const applyConfig = (nextConfig) => {
+    config = nextConfig;
+    if (config.kind === "LOCAL" && config.pid) {
+        startPidPolling(config.pid);
+    }
+};
+const onLifelineClosed = () => {
+    void runCleanup().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);
+        process.stdin.on("close", onLifelineClosed);
+        process.stdin.on("error", onLifelineClosed);
+    }
+    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;\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    } catch {\n      if (pidPollTimer) {\n        clearInterval(pidPollTimer);\n        pidPollTimer = null;\n      }\n      void runCleanup().finally(() => exit(0));\n    }\n  }, PID_POLL_INTERVAL_MS);\n};\n\nconst cleanupLocal = async (\n  cfg: Extract<ShutdownSupervisorConfig, { kind: \"LOCAL\" }>,\n) => {\n  await cleanupLocalBrowser({\n    killChrome: cfg.pid ? () => politeKill(cfg.pid) : 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) => {\n  if (!cfg.apiKey || !cfg.projectId || !cfg.sessionId) return;\n  try {\n    const bb = new Browserbase({ apiKey: cfg.apiKey });\n    await bb.sessions.update(cfg.sessionId, {\n      status: \"REQUEST_RELEASE\",\n      projectId: cfg.projectId,\n    });\n  } catch {\n    // best-effort cleanup\n  }\n};\n\n// Idempotent cleanup entrypoint used by all supervisor shutdown paths.\nconst runCleanup = (): 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);\n        return;\n      }\n      if (cfg.kind === \"STAGEHAND_API\") {\n        await cleanupBrowserbase(cfg);\n      }\n    })();\n  }\n  return cleanupPromise;\n};\n\nconst applyConfig = (nextConfig: ShutdownSupervisorConfig): void => {\n  config = nextConfig;\n  if (config.kind === \"LOCAL\" && config.pid) {\n    startPidPolling(config.pid);\n  }\n};\n\nconst onLifelineClosed = () => {\n  void runCleanup().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\", onLifelineClosed);\n    process.stdin.on(\"close\", onLifelineClosed);\n    process.stdin.on(\"error\", onLifelineClosed);\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,93 @@
+/**
+ * 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 { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { ShutdownSupervisorResolveError, ShutdownSupervisorSpawnError, } from "../types/private/shutdownErrors.js";
+// Resolve module path for both CJS and ESM builds.
+const normalizedFilename = typeof __filename === "string" ? __filename.replaceAll("\\", "/") : "";
+const hasAbsoluteFilename = normalizedFilename.startsWith("/") || /^[A-Za-z]:\//.test(normalizedFilename);
+const modulePath = hasAbsoluteFilename
+    ? __filename
+    : fileURLToPath(import.meta.url);
+const normalizedModulePath = modulePath.replaceAll("\\", "/");
+const moduleDir = normalizedModulePath.slice(0, normalizedModulePath.lastIndexOf("/"));
+const require = createRequire(modulePath);
+const isSeaRuntime = () => {
+    try {
+        const sea = require("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 resolveSupervisorCommand = (config) => {
+    const baseArgs = ["--supervisor", serializeConfigArg(config)];
+    if (isSeaRuntime()) {
+        return { command: process.execPath, args: baseArgs };
+    }
+    const cliPathCandidates = [`${moduleDir}/../cli.js`, `${moduleDir}/cli.js`];
+    const cliPath = cliPathCandidates.find((candidate) => fs.existsSync(candidate)) ?? null;
+    if (!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.
+        stdio: ["pipe", "ignore", "ignore"],
+        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 { spawn } from \"node:child_process\";\nimport { createRequire } from \"node:module\";\nimport { fileURLToPath } from \"node:url\";\nimport type {\n  ShutdownSupervisorConfig,\n  ShutdownSupervisorHandle,\n} from \"../types/private/shutdown.js\";\nimport {\n  ShutdownSupervisorResolveError,\n  ShutdownSupervisorSpawnError,\n} from \"../types/private/shutdownErrors.js\";\n// Resolve module path for both CJS and ESM builds.\nconst normalizedFilename =\n  typeof __filename === \"string\" ? __filename.replaceAll(\"\\\\\", \"/\") : \"\";\nconst hasAbsoluteFilename =\n  normalizedFilename.startsWith(\"/\") || /^[A-Za-z]:\\//.test(normalizedFilename);\nconst modulePath = hasAbsoluteFilename\n  ? __filename\n  : fileURLToPath(import.meta.url);\nconst normalizedModulePath = modulePath.replaceAll(\"\\\\\", \"/\");\nconst moduleDir = normalizedModulePath.slice(\n  0,\n  normalizedModulePath.lastIndexOf(\"/\"),\n);\nconst require = createRequire(modulePath);\n\nconst isSeaRuntime = (): boolean => {\n  try {\n    const sea = require(\"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 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 cliPathCandidates = [`${moduleDir}/../cli.js`, `${moduleDir}/cli.js`];\n  const cliPath =\n    cliPathCandidates.find((candidate) => fs.existsSync(candidate)) ?? null;\n  if (!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    stdio: [\"pipe\", \"ignore\", \"ignore\"],\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/tests/agent-abort-signal.spec.js

@@ -0,0 +1,113 @@
+import { test, expect } from "@playwright/test";
+import { V3 } from "../v3.js";
+import { v3TestConfig } from "./v3.config.js";
+import { AgentAbortError } from "../types/public/sdkErrors.js";
+test.describe("Stagehand agent abort signal", () => {
+  let v3;
+  test.beforeEach(async () => {
+    v3 = new V3({
+      ...v3TestConfig,
+      experimental: true
+    });
+    await v3.init();
+  });
+  test.afterEach(async () => {
+    await v3?.close?.().catch(() => {
+    });
+  });
+  test("non-streaming: abort signal stops execution and throws AgentAbortError", async () => {
+    test.setTimeout(6e4);
+    const agent = v3.agent({
+      model: "anthropic/claude-haiku-4-5-20251001"
+    });
+    const page = v3.context.pages()[0];
+    await page.goto("https://example.com");
+    const controller = new AbortController();
+    setTimeout(() => controller.abort(), 500);
+    await expect(
+      agent.execute({
+        instruction: "Describe every visual element on this page in extreme detail. Describe at least 100 different elements.",
+        maxSteps: 50,
+        signal: controller.signal
+      })
+    ).rejects.toThrow(AgentAbortError);
+  });
+  test("streaming: abort signal stops stream and rejects result with AgentAbortError", async () => {
+    test.setTimeout(6e4);
+    const agent = v3.agent({
+      stream: true,
+      model: "anthropic/claude-haiku-4-5-20251001"
+    });
+    const page = v3.context.pages()[0];
+    await page.goto("https://example.com");
+    const controller = new AbortController();
+    setTimeout(() => controller.abort(), 500);
+    const streamResult = await agent.execute({
+      instruction: "Describe every visual element on this page in extreme detail. Describe at least 100 different elements.",
+      maxSteps: 50,
+      signal: controller.signal
+    });
+    const consumeStream = async () => {
+      for await (const _ of streamResult.textStream) {
+      }
+    };
+    const [, resultError] = await Promise.allSettled([
+      consumeStream(),
+      streamResult.result
+    ]);
+    expect(resultError.status).toBe("rejected");
+    expect(resultError.reason).toBeInstanceOf(
+      AgentAbortError
+    );
+  });
+  test("non-streaming: already aborted signal throws AgentAbortError immediately", async () => {
+    test.setTimeout(2e4);
+    const agent = v3.agent({
+      model: "anthropic/claude-haiku-4-5-20251001"
+    });
+    const page = v3.context.pages()[0];
+    await page.goto("https://example.com");
+    const controller = new AbortController();
+    controller.abort();
+    await expect(
+      agent.execute({
+        instruction: "This should not run.",
+        maxSteps: 3,
+        signal: controller.signal
+      })
+    ).rejects.toThrow(AgentAbortError);
+  });
+  test("non-streaming: execution completes normally without abort signal", async () => {
+    test.setTimeout(6e4);
+    const agent = v3.agent({
+      model: "anthropic/claude-haiku-4-5-20251001"
+    });
+    const page = v3.context.pages()[0];
+    await page.goto("https://example.com");
+    const result = await agent.execute({
+      instruction: "Describe this page briefly.",
+      maxSteps: 3
+    });
+    expect(result.success).toBe(true);
+    expect(result.completed).toBe(true);
+  });
+  test("streaming: execution completes normally without abort signal", async () => {
+    test.setTimeout(6e4);
+    const agent = v3.agent({
+      stream: true,
+      model: "anthropic/claude-haiku-4-5-20251001"
+    });
+    const page = v3.context.pages()[0];
+    await page.goto("https://example.com");
+    const streamResult = await agent.execute({
+      instruction: "Describe this page briefly.",
+      maxSteps: 3
+    });
+    for await (const _ of streamResult.textStream) {
+    }
+    const result = await streamResult.result;
+    expect(result.success).toBe(true);
+    expect(result.completed).toBe(true);
+  });
+});
+//# sourceMappingURL=agent-abort-signal.spec.js.map

package/dist/esm/lib/v3/tests/agent-abort-signal.spec.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../lib/v3/tests/agent-abort-signal.spec.ts"],
+  "sourcesContent": ["import { test, expect } from \"@playwright/test\";\nimport { V3 } from \"../v3.js\";\nimport { v3TestConfig } from \"./v3.config.js\";\nimport { AgentAbortError } from \"../types/public/sdkErrors.js\";\n\ntest.describe(\"Stagehand agent abort signal\", () => {\n  let v3: V3;\n\n  test.beforeEach(async () => {\n    v3 = new V3({\n      ...v3TestConfig,\n      experimental: true,\n    });\n    await v3.init();\n  });\n\n  test.afterEach(async () => {\n    await v3?.close?.().catch(() => {});\n  });\n\n  test(\"non-streaming: abort signal stops execution and throws AgentAbortError\", async () => {\n    test.setTimeout(60000);\n\n    const agent = v3.agent({\n      model: \"anthropic/claude-haiku-4-5-20251001\",\n    });\n\n    const page = v3.context.pages()[0];\n    await page.goto(\"https://example.com\");\n\n    const controller = new AbortController();\n\n    // Abort after 500ms - should be enough for the LLM to start but not finish\n    setTimeout(() => controller.abort(), 500);\n\n    await expect(\n      agent.execute({\n        instruction:\n          \"Describe every visual element on this page in extreme detail. Describe at least 100 different elements.\",\n        maxSteps: 50,\n        signal: controller.signal,\n      }),\n    ).rejects.toThrow(AgentAbortError);\n  });\n\n  test(\"streaming: abort signal stops stream and rejects result with AgentAbortError\", async () => {\n    test.setTimeout(60000);\n\n    const agent = v3.agent({\n      stream: true,\n      model: \"anthropic/claude-haiku-4-5-20251001\",\n    });\n\n    const page = v3.context.pages()[0];\n    await page.goto(\"https://example.com\");\n\n    const controller = new AbortController();\n\n    // Abort after 500ms\n    setTimeout(() => controller.abort(), 500);\n\n    const streamResult = await agent.execute({\n      instruction:\n        \"Describe every visual element on this page in extreme detail. Describe at least 100 different elements.\",\n      maxSteps: 50,\n      signal: controller.signal,\n    });\n\n    // Handle both stream consumption and result promise together\n    // The result promise will reject with AgentAbortError when aborted\n    const consumeStream = async () => {\n      // eslint-disable-next-line @typescript-eslint/no-unused-vars\n      for await (const _ of streamResult.textStream) {\n        // Just consume chunks until stream ends\n      }\n    };\n\n    // Both should complete - stream ends and result rejects\n    const [, resultError] = await Promise.allSettled([\n      consumeStream(),\n      streamResult.result,\n    ]);\n\n    // The result should have rejected with AgentAbortError\n    expect(resultError.status).toBe(\"rejected\");\n    expect((resultError as PromiseRejectedResult).reason).toBeInstanceOf(\n      AgentAbortError,\n    );\n  });\n\n  test(\"non-streaming: already aborted signal throws AgentAbortError immediately\", async () => {\n    test.setTimeout(20000);\n\n    const agent = v3.agent({\n      model: \"anthropic/claude-haiku-4-5-20251001\",\n    });\n\n    const page = v3.context.pages()[0];\n    await page.goto(\"https://example.com\");\n\n    // Create an already aborted controller\n    const controller = new AbortController();\n    controller.abort();\n\n    await expect(\n      agent.execute({\n        instruction: \"This should not run.\",\n        maxSteps: 3,\n        signal: controller.signal,\n      }),\n    ).rejects.toThrow(AgentAbortError);\n  });\n\n  test(\"non-streaming: execution completes normally without abort signal\", async () => {\n    test.setTimeout(60000);\n\n    const agent = v3.agent({\n      model: \"anthropic/claude-haiku-4-5-20251001\",\n    });\n\n    const page = v3.context.pages()[0];\n    await page.goto(\"https://example.com\");\n\n    // No signal provided - should complete normally\n    const result = await agent.execute({\n      instruction: \"Describe this page briefly.\",\n      maxSteps: 3,\n    });\n\n    expect(result.success).toBe(true);\n    expect(result.completed).toBe(true);\n  });\n\n  test(\"streaming: execution completes normally without abort signal\", async () => {\n    test.setTimeout(60000);\n\n    const agent = v3.agent({\n      stream: true,\n      model: \"anthropic/claude-haiku-4-5-20251001\",\n    });\n\n    const page = v3.context.pages()[0];\n    await page.goto(\"https://example.com\");\n\n    // No signal provided - should complete normally\n    const streamResult = await agent.execute({\n      instruction: \"Describe this page briefly.\",\n      maxSteps: 3,\n    });\n\n    // Consume the stream first\n    // eslint-disable-next-line @typescript-eslint/no-unused-vars\n    for await (const _ of streamResult.textStream) {\n      // Just consume\n    }\n\n    // Now get the final result\n    const result = await streamResult.result;\n\n    expect(result.success).toBe(true);\n    expect(result.completed).toBe(true);\n  });\n});\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/esm/lib/v3/tests/agent-cache-self-heal.spec.js

@@ -0,0 +1,80 @@
+import { test, expect } from "@playwright/test";
+import fs from "fs/promises";
+import path from "path";
+import { V3 } from "../v3.js";
+import { v3TestConfig } from "./v3.config.js";
+test.describe("Agent cache self-heal (e2e)", () => {
+  let v3;
+  let cacheDir;
+  test.beforeEach(async ({}, testInfo) => {
+    await fs.mkdir(testInfo.outputDir, { recursive: true });
+    cacheDir = await fs.mkdtemp(path.join(testInfo.outputDir, "agent-cache-"));
+    v3 = new V3({
+      ...v3TestConfig,
+      cacheDir,
+      selfHeal: true
+    });
+    await v3.init();
+  });
+  test.afterEach(async () => {
+    await v3?.close?.().catch(() => {
+    });
+  });
+  test("replays heal corrupted selectors", async () => {
+    test.setTimeout(12e4);
+    const agent = v3.agent({
+      model: "anthropic/claude-haiku-4-5-20251001"
+    });
+    const page = v3.context.pages()[0];
+    const url = "https://browserbase.github.io/stagehand-eval-sites/sites/shadow-dom/";
+    const instruction = "click the button";
+    await page.goto(url, { waitUntil: "networkidle" });
+    const firstResult = await agent.execute({ instruction, maxSteps: 20 });
+    expect(firstResult.success).toBe(true);
+    const cachePath = await locateAgentCacheFile(cacheDir);
+    const originalEntry = await readCacheEntry(cachePath);
+    const originalActionStep = findFirstActionStep(originalEntry);
+    expect(originalActionStep).toBeDefined();
+    const originalSelector = originalActionStep?.actions?.[0]?.selector;
+    expect(typeof originalSelector).toBe("string");
+    if (originalActionStep?.actions?.[0]) {
+      originalActionStep.actions[0].selector = "xpath=/yeee";
+    }
+    await fs.writeFile(
+      cachePath,
+      JSON.stringify(originalEntry, null, 2),
+      "utf8"
+    );
+    await page.goto(url, { waitUntil: "networkidle" });
+    const replayResult = await agent.execute({ instruction, maxSteps: 20 });
+    expect(replayResult.success).toBe(true);
+    const healedEntry = await readCacheEntry(cachePath);
+    const healedActionStep = findFirstActionStep(healedEntry);
+    expect(healedActionStep?.actions?.[0]?.selector).toBe(originalSelector);
+    expect(healedActionStep?.actions?.[0]?.selector).not.toBe("xpath=/yeee");
+    expect(healedEntry.timestamp).not.toBe(originalEntry.timestamp);
+  });
+});
+async function locateAgentCacheFile(cacheDir) {
+  const deadline = Date.now() + 1e4;
+  while (Date.now() < deadline) {
+    const entries = await fs.readdir(cacheDir);
+    const agentFiles = entries.filter((file) => file.startsWith("agent-"));
+    if (agentFiles.length > 0) {
+      return path.join(cacheDir, agentFiles[0]);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+  throw new Error("Timed out waiting for agent cache entry to be written");
+}
+async function readCacheEntry(cachePath) {
+  const raw = await fs.readFile(cachePath, "utf8");
+  return JSON.parse(raw);
+}
+function findFirstActionStep(entry) {
+  return entry.steps.find((step) => {
+    const actions = step.actions;
+    return Array.isArray(actions) && actions.length > 0;
+  });
+}
+//# sourceMappingURL=agent-cache-self-heal.spec.js.map

package/dist/esm/lib/v3/tests/agent-cache-self-heal.spec.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../lib/v3/tests/agent-cache-self-heal.spec.ts"],
+  "sourcesContent": ["import { test, expect } from \"@playwright/test\";\nimport fs from \"fs/promises\";\nimport path from \"path\";\nimport { V3 } from \"../v3.js\";\nimport { v3TestConfig } from \"./v3.config.js\";\nimport type {\n  AgentReplayActStep,\n  AgentReplayFillFormStep,\n  CachedAgentEntry,\n} from \"../types/private/cache.js\";\n\ntest.describe(\"Agent cache self-heal (e2e)\", () => {\n  let v3: V3;\n  let cacheDir: string;\n\n  // eslint-disable-next-line no-empty-pattern\n  test.beforeEach(async ({}, testInfo) => {\n    await fs.mkdir(testInfo.outputDir, { recursive: true });\n    cacheDir = await fs.mkdtemp(path.join(testInfo.outputDir, \"agent-cache-\"));\n    v3 = new V3({\n      ...v3TestConfig,\n      cacheDir,\n      selfHeal: true,\n    });\n    await v3.init();\n  });\n\n  test.afterEach(async () => {\n    await v3?.close?.().catch(() => {});\n  });\n\n  test(\"replays heal corrupted selectors\", async () => {\n    test.setTimeout(120_000);\n\n    const agent = v3.agent({\n      model: \"anthropic/claude-haiku-4-5-20251001\",\n    });\n    const page = v3.context.pages()[0];\n    const url =\n      \"https://browserbase.github.io/stagehand-eval-sites/sites/shadow-dom/\";\n    const instruction = \"click the button\";\n\n    await page.goto(url, { waitUntil: \"networkidle\" });\n    const firstResult = await agent.execute({ instruction, maxSteps: 20 });\n    expect(firstResult.success).toBe(true);\n\n    const cachePath = await locateAgentCacheFile(cacheDir);\n    const originalEntry = await readCacheEntry(cachePath);\n    const originalActionStep = findFirstActionStep(originalEntry);\n    expect(originalActionStep).toBeDefined();\n    const originalSelector = originalActionStep?.actions?.[0]?.selector;\n    expect(typeof originalSelector).toBe(\"string\");\n\n    // Corrupt the cached selector so the replay needs to self-heal.\n    if (originalActionStep?.actions?.[0]) {\n      originalActionStep.actions[0].selector = \"xpath=/yeee\";\n    }\n    await fs.writeFile(\n      cachePath,\n      JSON.stringify(originalEntry, null, 2),\n      \"utf8\",\n    );\n\n    // Second run should replay from cache, self-heal, and update the file.\n    await page.goto(url, { waitUntil: \"networkidle\" });\n    const replayResult = await agent.execute({ instruction, maxSteps: 20 });\n    expect(replayResult.success).toBe(true);\n\n    const healedEntry = await readCacheEntry(cachePath);\n    const healedActionStep = findFirstActionStep(healedEntry);\n    expect(healedActionStep?.actions?.[0]?.selector).toBe(originalSelector);\n    expect(healedActionStep?.actions?.[0]?.selector).not.toBe(\"xpath=/yeee\");\n    expect(healedEntry.timestamp).not.toBe(originalEntry.timestamp);\n  });\n});\n\nasync function locateAgentCacheFile(cacheDir: string): Promise<string> {\n  const deadline = Date.now() + 10_000;\n  while (Date.now() < deadline) {\n    const entries = await fs.readdir(cacheDir);\n    const agentFiles = entries.filter((file) => file.startsWith(\"agent-\"));\n    if (agentFiles.length > 0) {\n      return path.join(cacheDir, agentFiles[0]!);\n    }\n    await new Promise((resolve) => setTimeout(resolve, 200));\n  }\n  throw new Error(\"Timed out waiting for agent cache entry to be written\");\n}\n\nasync function readCacheEntry(cachePath: string): Promise<CachedAgentEntry> {\n  const raw = await fs.readFile(cachePath, \"utf8\");\n  return JSON.parse(raw) as CachedAgentEntry;\n}\n\ntype StepWithActions = AgentReplayActStep | AgentReplayFillFormStep;\n\nfunction findFirstActionStep(\n  entry: CachedAgentEntry,\n): StepWithActions | undefined {\n  return entry.steps.find((step) => {\n    const actions = (step as StepWithActions).actions;\n    return Array.isArray(actions) && actions.length > 0;\n  }) as StepWithActions | undefined;\n}\n"],
+  "mappings": "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",
+  "names": []
+}