@browserbasehq/orca 3.1.0-patch.3 → 3.2.0-middleware.1

package/dist/esm/lib/v3/mcp/connection.js

@@ -1,11 +1,12 @@
 import { Client, } from "@modelcontextprotocol/sdk/client/index.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { StreamableHTTPClientTransport, } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { MCPConnectionError } from "../types/public/sdkErrors.js";
 export const connectToMCPServer = async (serverConfig) => {
     try {
         let transport;
         let clientOptions;
+        let requestOptions;
         // Check if it's a stdio config (has 'command' property)
         if (typeof serverConfig === "object" && "command" in serverConfig) {
             transport = new StdioClientTransport(serverConfig);
@@ -20,8 +21,10 @@ export const connectToMCPServer = async (serverConfig) => {
                 serverUrl = serverConfig.serverUrl;
                 clientOptions = serverConfig
                     .clientOptions;
+                requestOptions = serverConfig
+                    .requestOptions;
             }
-            transport = new StreamableHTTPClientTransport(new URL(serverUrl));
+            transport = new StreamableHTTPClientTransport(new URL(serverUrl), requestOptions);
         }
         const client = new Client({
             name: "Stagehand",

package/dist/esm/lib/v3/mcp/connection.js.map

@@ -1 +1 @@
-{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../../../../lib/v3/mcp/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,GAEP,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AACnG,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAalE,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,EACrC,YAA0E,EACzD,EAAE;IACnB,IAAI,CAAC;QACH,IAAI,SAAS,CAAC;QACd,IAAI,aAAwC,CAAC;QAE7C,wDAAwD;QACxD,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,SAAS,IAAI,YAAY,EAAE,CAAC;YAClE,SAAS,GAAG,IAAI,oBAAoB,CAAC,YAAY,CAAC,CAAC;QACrD,CAAC;aAAM,CAAC;YACN,8BAA8B;YAC9B,IAAI,SAAuB,CAAC;YAE5B,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,YAAY,GAAG,EAAE,CAAC;gBACpE,SAAS,GAAG,YAAY,CAAC;YAC3B,CAAC;iBAAM,CAAC;gBACN,SAAS,GAAI,YAA0C,CAAC,SAAS,CAAC;gBAClE,aAAa,GAAI,YAA0C;qBACxD,aAAa,CAAC;YACnB,CAAC;YAED,SAAS,GAAG,IAAI,6BAA6B,CAAC,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;QACpE,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC;YACxB,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,OAAO;YAChB,GAAG,aAAa;SACjB,CAAC,CAAC;QAEH,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAEhC,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACtB,CAAC;QAAC,OAAO,SAAS,EAAE,CAAC;YACnB,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YACrB,MAAM,IAAI,kBAAkB,CAAC,YAAY,CAAC,QAAQ,EAAE,EAAE,SAAS,CAAC,CAAC;QACnE,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,mEAAmE;QACnE,IAAI,KAAK,YAAY,kBAAkB,EAAE,CAAC;YACxC,MAAM,KAAK,CAAC,CAAC,4BAA4B;QAC3C,CAAC;QACD,MAAM,IAAI,kBAAkB,CAAC,YAAY,CAAC,QAAQ,EAAE,EAAE,KAAK,CAAC,CAAC;IAC/D,CAAC;AACH,CAAC,CAAC","sourcesContent":["import {\n  Client,\n  ClientOptions,\n} from \"@modelcontextprotocol/sdk/client/index.js\";\nimport { StreamableHTTPClientTransport } from \"@modelcontextprotocol/sdk/client/streamableHttp.js\";\nimport { StdioClientTransport } from \"@modelcontextprotocol/sdk/client/stdio.js\";\nimport { MCPConnectionError } from \"../types/public/sdkErrors.js\";\n\nexport interface ConnectToMCPServerOptions {\n  serverUrl: string | URL;\n  clientOptions?: ClientOptions;\n}\n\nexport interface StdioServerConfig {\n  command: string;\n  args?: string[];\n  env?: Record<string, string>;\n}\n\nexport const connectToMCPServer = async (\n  serverConfig: string | URL | StdioServerConfig | ConnectToMCPServerOptions,\n): Promise<Client> => {\n  try {\n    let transport;\n    let clientOptions: ClientOptions | undefined;\n\n    // Check if it's a stdio config (has 'command' property)\n    if (typeof serverConfig === \"object\" && \"command\" in serverConfig) {\n      transport = new StdioClientTransport(serverConfig);\n    } else {\n      // Handle URL-based connection\n      let serverUrl: string | URL;\n\n      if (typeof serverConfig === \"string\" || serverConfig instanceof URL) {\n        serverUrl = serverConfig;\n      } else {\n        serverUrl = (serverConfig as ConnectToMCPServerOptions).serverUrl;\n        clientOptions = (serverConfig as ConnectToMCPServerOptions)\n          .clientOptions;\n      }\n\n      transport = new StreamableHTTPClientTransport(new URL(serverUrl));\n    }\n\n    const client = new Client({\n      name: \"Stagehand\",\n      version: \"1.0.0\",\n      ...clientOptions,\n    });\n\n    await client.connect(transport);\n\n    try {\n      await client.ping();\n    } catch (pingError) {\n      await client.close();\n      throw new MCPConnectionError(serverConfig.toString(), pingError);\n    }\n\n    return client;\n  } catch (error) {\n    // Handle any errors during transport/client creation or connection\n    if (error instanceof MCPConnectionError) {\n      throw error; // Re-throw our custom error\n    }\n    throw new MCPConnectionError(serverConfig.toString(), error);\n  }\n};\n"]}
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../../../../lib/v3/mcp/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,GAEP,MAAM,2CAA2C,CAAC;AACnD,OAAO,EACL,6BAA6B,GAE9B,MAAM,oDAAoD,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAclE,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,EACrC,YAA0E,EACzD,EAAE;IACnB,IAAI,CAAC;QACH,IAAI,SAAS,CAAC;QACd,IAAI,aAAwC,CAAC;QAC7C,IAAI,cAAgE,CAAC;QAErE,wDAAwD;QACxD,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,SAAS,IAAI,YAAY,EAAE,CAAC;YAClE,SAAS,GAAG,IAAI,oBAAoB,CAAC,YAAY,CAAC,CAAC;QACrD,CAAC;aAAM,CAAC;YACN,8BAA8B;YAC9B,IAAI,SAAuB,CAAC;YAE5B,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,YAAY,GAAG,EAAE,CAAC;gBACpE,SAAS,GAAG,YAAY,CAAC;YAC3B,CAAC;iBAAM,CAAC;gBACN,SAAS,GAAI,YAA0C,CAAC,SAAS,CAAC;gBAClE,aAAa,GAAI,YAA0C;qBACxD,aAAa,CAAC;gBACjB,cAAc,GAAI,YAA0C;qBACzD,cAAc,CAAC;YACpB,CAAC;YAED,SAAS,GAAG,IAAI,6BAA6B,CAC3C,IAAI,GAAG,CAAC,SAAS,CAAC,EAClB,cAAc,CACf,CAAC;QACJ,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC;YACxB,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,OAAO;YAChB,GAAG,aAAa;SACjB,CAAC,CAAC;QAEH,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAEhC,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACtB,CAAC;QAAC,OAAO,SAAS,EAAE,CAAC;YACnB,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YACrB,MAAM,IAAI,kBAAkB,CAAC,YAAY,CAAC,QAAQ,EAAE,EAAE,SAAS,CAAC,CAAC;QACnE,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,mEAAmE;QACnE,IAAI,KAAK,YAAY,kBAAkB,EAAE,CAAC;YACxC,MAAM,KAAK,CAAC,CAAC,4BAA4B;QAC3C,CAAC;QACD,MAAM,IAAI,kBAAkB,CAAC,YAAY,CAAC,QAAQ,EAAE,EAAE,KAAK,CAAC,CAAC;IAC/D,CAAC;AACH,CAAC,CAAC","sourcesContent":["import {\n  Client,\n  ClientOptions,\n} from \"@modelcontextprotocol/sdk/client/index.js\";\nimport {\n  StreamableHTTPClientTransport,\n  type StreamableHTTPClientTransportOptions,\n} from \"@modelcontextprotocol/sdk/client/streamableHttp.js\";\nimport { StdioClientTransport } from \"@modelcontextprotocol/sdk/client/stdio.js\";\nimport { MCPConnectionError } from \"../types/public/sdkErrors.js\";\n\nexport interface ConnectToMCPServerOptions {\n  serverUrl: string | URL;\n  clientOptions?: ClientOptions;\n  requestOptions?: StreamableHTTPClientTransportOptions;\n}\n\nexport interface StdioServerConfig {\n  command: string;\n  args?: string[];\n  env?: Record<string, string>;\n}\n\nexport const connectToMCPServer = async (\n  serverConfig: string | URL | StdioServerConfig | ConnectToMCPServerOptions,\n): Promise<Client> => {\n  try {\n    let transport;\n    let clientOptions: ClientOptions | undefined;\n    let requestOptions: StreamableHTTPClientTransportOptions | undefined;\n\n    // Check if it's a stdio config (has 'command' property)\n    if (typeof serverConfig === \"object\" && \"command\" in serverConfig) {\n      transport = new StdioClientTransport(serverConfig);\n    } else {\n      // Handle URL-based connection\n      let serverUrl: string | URL;\n\n      if (typeof serverConfig === \"string\" || serverConfig instanceof URL) {\n        serverUrl = serverConfig;\n      } else {\n        serverUrl = (serverConfig as ConnectToMCPServerOptions).serverUrl;\n        clientOptions = (serverConfig as ConnectToMCPServerOptions)\n          .clientOptions;\n        requestOptions = (serverConfig as ConnectToMCPServerOptions)\n          .requestOptions;\n      }\n\n      transport = new StreamableHTTPClientTransport(\n        new URL(serverUrl),\n        requestOptions,\n      );\n    }\n\n    const client = new Client({\n      name: \"Stagehand\",\n      version: \"1.0.0\",\n      ...clientOptions,\n    });\n\n    await client.connect(transport);\n\n    try {\n      await client.ping();\n    } catch (pingError) {\n      await client.close();\n      throw new MCPConnectionError(serverConfig.toString(), pingError);\n    }\n\n    return client;\n  } catch (error) {\n    // Handle any errors during transport/client creation or connection\n    if (error instanceof MCPConnectionError) {\n      throw error; // Re-throw our custom error\n    }\n    throw new MCPConnectionError(serverConfig.toString(), error);\n  }\n};\n"]}

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/supervisor.js

@@ -104,7 +104,7 @@ const cleanupLocal = async (cfg, reason) => {
     });
 };
 const cleanupBrowserbase = async (cfg, reason) => {
-    if (!cfg.apiKey || !cfg.projectId || !cfg.sessionId)
+    if (!cfg.apiKey || !cfg.sessionId)
         return;
     try {
         console.error(`[shutdown-supervisor] Ending Browserbase session ${cfg.sessionId} ` +
@@ -112,7 +112,7 @@ const cleanupBrowserbase = async (cfg, reason) => {
         const bb = new Browserbase({ apiKey: cfg.apiKey });
         await bb.sessions.update(cfg.sessionId, {
             status: "REQUEST_RELEASE",
-            projectId: cfg.projectId,
+            ...(cfg.projectId ? { projectId: cfg.projectId } : {}),
         });
     }
     catch {

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

@@ -1 +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.projectId || !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      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 = (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"]}
+{"version":3,"file":"supervisor.js","sourceRoot":"","sources":["../../../../../lib/v3/shutdown/supervisor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,WAAW,MAAM,oBAAoB,CAAC;AAE7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAExD,MAAM,eAAe,GAAG,GAAG,CAAC;AAC5B,MAAM,kBAAkB,GAAG,KAAK,CAAC;AACjC,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAEjC,+DAA+D;AAC/D,IAAI,MAAM,GAAoC,IAAI,CAAC;AACnD,IAAI,cAAc,GAAyB,IAAI,CAAC;AAChD,IAAI,OAAO,GAAG,KAAK,CAAC;AACpB,IAAI,iBAAiB,GAAG,KAAK,CAAC;AAE9B,MAAM,IAAI,GAAG,CAAC,IAAI,GAAG,CAAC,EAAQ,EAAE;IAC9B,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,SAAS;IACX,CAAC;AACH,CAAC,CAAC;AAEF,yEAAyE;AACzE,0EAA0E;AAC1E,MAAM,UAAU,GAAG,KAAK,EAAE,GAAW,EAAiB,EAAE;IACtD,MAAM,OAAO,GAAG,GAAY,EAAE;QAC5B,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YACrB,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,GAAG,GAAG,KAA8B,CAAC;YAC3C,mDAAmD;YACnD,OAAO,GAAG,CAAC,IAAI,KAAK,OAAO,CAAC;QAC9B,CAAC;IACH,CAAC,CAAC;IAEF,IAAI,CAAC,OAAO,EAAE;QAAE,OAAO;IACvB,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,GAAG,GAAG,KAA8B,CAAC;QAC3C,4DAA4D;QAC5D,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO;YAAE,OAAO;IACnC,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,kBAAkB,CAAC;IACjD,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;QAC7B,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC;QACrE,IAAI,CAAC,OAAO,EAAE;YAAE,OAAO;IACzB,CAAC;IACD,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,cAAc;IAChB,CAAC;AACH,CAAC,CAAC;AAEF,IAAI,YAAY,GAA0B,IAAI,CAAC;AAE/C,sFAAsF;AACtF,MAAM,eAAe,GAAG,CAAC,GAAW,EAAQ,EAAE;IAC5C,IAAI,YAAY;QAAE,OAAO;IACzB,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE;QAC9B,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YACrB,OAAO;QACT,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,GAAG,GAAG,KAA8B,CAAC;YAC3C,mDAAmD;YACnD,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO;gBAAE,OAAO;QACnC,CAAC;QAED,iBAAiB,GAAG,IAAI,CAAC;QACzB,IAAI,YAAY,EAAE,CAAC;YACjB,aAAa,CAAC,YAAY,CAAC,CAAC;YAC5B,YAAY,GAAG,IAAI,CAAC;QACtB,CAAC;QACD,KAAK,UAAU,CAAC,wBAAwB,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACnE,CAAC,EAAE,oBAAoB,CAAC,CAAC;AAC3B,CAAC,CAAC;AAEF,MAAM,YAAY,GAAG,KAAK,EACxB,GAAyD,EACzD,MAAc,EACd,EAAE;IACF,MAAM,mBAAmB,GAAG,OAAO,CACjC,GAAG,CAAC,kBAAkB,IAAI,CAAC,GAAG,CAAC,mBAAmB,IAAI,GAAG,CAAC,WAAW,CACtE,CAAC;IACF,MAAM,mBAAmB,CAAC;QACxB,iEAAiE;QACjE,sEAAsE;QACtE,UAAU,EACR,GAAG,CAAC,GAAG,IAAI,CAAC,iBAAiB;YAC3B,CAAC,CAAC,GAAG,EAAE;gBACH,OAAO,CAAC,KAAK,CACX,kDAAkD,GAAG,CAAC,GAAG,GAAG;oBAC1D,WAAW,MAAM,yBAAyB,mBAAmB,GAAG,CACnE,CAAC;gBACF,OAAO,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC7B,CAAC;YACH,CAAC,CAAC,SAAS;QACf,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,kBAAkB,EAAE,GAAG,CAAC,kBAAkB;QAC1C,mBAAmB,EAAE,GAAG,CAAC,mBAAmB;KAC7C,CAAC,CAAC;AACL,CAAC,CAAC;AAEF,MAAM,kBAAkB,GAAG,KAAK,EAC9B,GAAiE,EACjE,MAAc,EACd,EAAE;IACF,IAAI,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS;QAAE,OAAO;IAC1C,IAAI,CAAC;QACH,OAAO,CAAC,KAAK,CACX,oDAAoD,GAAG,CAAC,SAAS,GAAG;YAClE,WAAW,MAAM,GAAG,CACvB,CAAC;QACF,MAAM,EAAE,GAAG,IAAI,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QACnD,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE;YACtC,MAAM,EAAE,iBAAiB;YACzB,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACX,CAAC,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,sBAAsB;IACxB,CAAC;AACH,CAAC,CAAC;AAEF,uEAAuE;AACvE,MAAM,UAAU,GAAG,CAAC,MAAc,EAAiB,EAAE;IACnD,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,cAAc,GAAG,CAAC,KAAK,IAAI,EAAE;YAC3B,MAAM,GAAG,GAAG,MAAM,CAAC;YACnB,IAAI,CAAC,GAAG;gBAAE,OAAO;YACjB,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;gBACzB,MAAM,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;gBAChC,OAAO;YACT,CAAC;YACD,IAAI,GAAG,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;gBACjC,MAAM,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YACxC,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;IACP,CAAC;IACD,OAAO,cAAc,CAAC;AACxB,CAAC,CAAC;AAEF,MAAM,WAAW,GAAG,CAAC,UAAoC,EAAQ,EAAE;IACjE,MAAM,GAAG,UAAU,CAAC;IACpB,iBAAiB,GAAG,KAAK,CAAC;IAC1B,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,IAAI,MAAM,CAAC,GAAG,EAAE,CAAC;QAC1C,eAAe,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,gBAAgB,GAAG,CAAC,MAAc,EAAE,EAAE;IAC1C,KAAK,UAAU,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC,CAAC;AAEF,MAAM,mBAAmB,GAAG,CAC1B,OAA0B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EACd,EAAE;IACnC,MAAM,MAAM,GAAG,sBAAsB,CAAC;IACtC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC7E,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACxD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAA6B,CAAC;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACnC,aAAuC,EACjC,EAAE;IACR,IAAI,OAAO;QAAE,OAAO;IACpB,OAAO,GAAG,IAAI,CAAC;IACf,WAAW,CAAC,aAAa,CAAC,CAAC;IAE3B,yDAAyD;IACzD,IAAI,CAAC;QACH,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QACvB,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAC3B,gBAAgB,CAAC,6BAA6B,CAAC,CAChD,CAAC;QACF,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAC7B,gBAAgB,CAAC,6BAA6B,CAAC,CAChD,CAAC;QACF,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAC7B,gBAAgB,CAAC,yCAAyC,CAAC,CAC5D,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,SAAS;IACX,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,kCAAkC,GAAG,CAChD,OAA0B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EACtC,EAAE;IACX,MAAM,MAAM,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;IACzC,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC9B,OAAO,IAAI,CAAC;AACd,CAAC,CAAC","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.js

@@ -6,22 +6,17 @@
  * 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 { 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);
+import { getCurrentFilePath } from "../runtimePaths.js";
+const moduleFilename = getCurrentFilePath();
+const moduleDir = path.dirname(moduleFilename);
+const nodeRequire = createRequire(moduleFilename);
 const isSeaRuntime = () => {
     try {
-        const sea = require("node:sea");
+        const sea = nodeRequire("node:sea");
         return Boolean(sea.isSea?.());
     }
     catch {
@@ -30,14 +25,14 @@ const isSeaRuntime = () => {
 };
 // 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 cliPathCandidates = [`${moduleDir}/../cli.js`, `${moduleDir}/cli.js`];
-    const cliPath = cliPathCandidates.find((candidate) => fs.existsSync(candidate)) ?? null;
-    if (!cliPath)
+    const cliPath = resolveCliPath();
+    if (!fs.existsSync(cliPath))
         return null;
     const needsTsxLoader = fs.existsSync(`${moduleDir}/supervisor.ts`) &&
         !fs.existsSync(`${moduleDir}/supervisor.js`);

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

@@ -1 +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    // 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"]}
+{"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

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

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

@@ -10,6 +10,11 @@ export function getEnvTimeoutMs(name) {
     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(() => {

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

@@ -1 +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,SAAiB,EACjB,SAAiB;IAEjB,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,\n  operation: string,\n): Promise<T> {\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"]}
+{"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/cache.d.ts

@@ -10,6 +10,9 @@ export type AgentCacheContext = {
     options: SanitizedAgentExecuteOptions;
     configSignature: string;
     cacheKey: string;
+    variableKeys: string[] /** Variable keys used in this execution (for cache key) */;
+    /** Variable values to substitute during replay */
+    variables?: Record<string, string>;
 };
 export type AgentCacheTransferPayload = {
     cacheKey: string;
@@ -75,7 +78,6 @@ export interface AgentReplayFillFormStep {
     type: "fillForm";
     fields?: Array<{
         action: string;
-        value: string;
     }>;
     observeResults?: Action[];
     actions?: Action[];

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

@@ -1 +1 @@
-{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/cache.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  ActOptions,\n  ActResult,\n  AvailableModel,\n  Logger,\n  AgentResult,\n  Action,\n  LoadState,\n} from \"../public/index.js\";\nimport { CacheStorage } from \"../../cache/CacheStorage.js\";\nimport type { ActHandler } from \"../../handlers/actHandler.js\";\nimport type { V3Context } from \"../../understudy/context.js\";\nimport type { LLMClient } from \"../../llm/LLMClient.js\";\n\nexport type ActFn = (\n  instruction: string,\n  options?: ActOptions,\n) => Promise<ActResult>;\n\nexport type AgentCacheContext = {\n  instruction: string;\n  startUrl: string;\n  options: SanitizedAgentExecuteOptions;\n  configSignature: string;\n  cacheKey: string;\n};\n\nexport type AgentCacheTransferPayload = {\n  cacheKey: string;\n  entry: CachedAgentEntry;\n};\n\nexport type AgentCacheDeps = {\n  storage: CacheStorage;\n  logger: Logger;\n  getActHandler: () => ActHandler | null;\n  getContext: () => V3Context | null;\n  getDefaultLlmClient: () => LLMClient;\n  getBaseModelName: () => AvailableModel;\n  getSystemPrompt: () => string | undefined;\n  domSettleTimeoutMs?: number;\n  act: ActFn;\n  bufferLatestEntry?: boolean;\n};\n\nexport type ActCacheContext = {\n  instruction: string;\n  cacheKey: string;\n  pageUrl: string;\n  variableKeys: string[];\n  variables?: Record<string, string>;\n};\n\nexport type ActCacheDeps = {\n  storage: CacheStorage;\n  logger: Logger;\n  getActHandler: () => ActHandler | null;\n  getDefaultLlmClient: () => LLMClient;\n  domSettleTimeoutMs?: number;\n};\n\nexport type ReadJsonResult<T> = {\n  value: T | null;\n  path?: string;\n  error?: unknown;\n};\n\nexport type WriteJsonResult = {\n  path?: string;\n  error?: unknown;\n};\n\nexport interface CachedActEntry {\n  version: 1;\n  instruction: string;\n  url: string;\n  variableKeys: string[];\n  actions: Action[];\n  actionDescription?: string;\n  message?: string;\n}\n\nexport type AgentReplayStep =\n  | AgentReplayActStep\n  | AgentReplayFillFormStep\n  | AgentReplayGotoStep\n  | AgentReplayScrollStep\n  | AgentReplayWaitStep\n  | AgentReplayNavBackStep\n  | AgentReplayKeysStep\n  | { type: string; [key: string]: unknown };\n\nexport interface AgentReplayActStep {\n  type: \"act\";\n  instruction: string;\n  actions?: Action[];\n  actionDescription?: string;\n  message?: string;\n  timeout?: number;\n}\n\nexport interface AgentReplayFillFormStep {\n  type: \"fillForm\";\n  fields?: Array<{ action: string; value: string }>;\n  observeResults?: Action[];\n  actions?: Action[];\n}\n\nexport interface AgentReplayGotoStep {\n  type: \"goto\";\n  url: string;\n  waitUntil?: LoadState;\n}\n\nexport interface AgentReplayScrollStep {\n  type: \"scroll\";\n  deltaX?: number;\n  deltaY?: number;\n  anchor?: { x: number; y: number };\n}\n\nexport interface AgentReplayWaitStep {\n  type: \"wait\";\n  timeMs: number;\n}\n\nexport interface AgentReplayNavBackStep {\n  type: \"navback\";\n  waitUntil?: LoadState;\n}\n\nexport interface AgentReplayKeysStep {\n  type: \"keys\";\n  instruction?: string;\n  playwrightArguments: {\n    method: \"type\" | \"press\";\n    text?: string;\n    keys?: string;\n    times?: number;\n  };\n}\n\nexport interface SanitizedAgentExecuteOptions {\n  maxSteps?: number;\n  highlightCursor?: boolean;\n}\n\nexport interface CachedAgentEntry {\n  version: 1;\n  instruction: string;\n  startUrl: string;\n  options: SanitizedAgentExecuteOptions;\n  configSignature: string;\n  steps: AgentReplayStep[];\n  result: AgentResult;\n  timestamp: string;\n}\n"]}
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/cache.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  ActOptions,\n  ActResult,\n  AvailableModel,\n  Logger,\n  AgentResult,\n  Action,\n  LoadState,\n} from \"../public/index.js\";\nimport { CacheStorage } from \"../../cache/CacheStorage.js\";\nimport type { ActHandler } from \"../../handlers/actHandler.js\";\nimport type { V3Context } from \"../../understudy/context.js\";\nimport type { LLMClient } from \"../../llm/LLMClient.js\";\n\nexport type ActFn = (\n  instruction: string,\n  options?: ActOptions,\n) => Promise<ActResult>;\n\nexport type AgentCacheContext = {\n  instruction: string;\n  startUrl: string;\n  options: SanitizedAgentExecuteOptions;\n  configSignature: string;\n  cacheKey: string;\n  variableKeys: string[] /** Variable keys used in this execution (for cache key) */;\n  /** Variable values to substitute during replay */\n  variables?: Record<string, string>;\n};\n\nexport type AgentCacheTransferPayload = {\n  cacheKey: string;\n  entry: CachedAgentEntry;\n};\n\nexport type AgentCacheDeps = {\n  storage: CacheStorage;\n  logger: Logger;\n  getActHandler: () => ActHandler | null;\n  getContext: () => V3Context | null;\n  getDefaultLlmClient: () => LLMClient;\n  getBaseModelName: () => AvailableModel;\n  getSystemPrompt: () => string | undefined;\n  domSettleTimeoutMs?: number;\n  act: ActFn;\n  bufferLatestEntry?: boolean;\n};\n\nexport type ActCacheContext = {\n  instruction: string;\n  cacheKey: string;\n  pageUrl: string;\n  variableKeys: string[];\n  variables?: Record<string, string>;\n};\n\nexport type ActCacheDeps = {\n  storage: CacheStorage;\n  logger: Logger;\n  getActHandler: () => ActHandler | null;\n  getDefaultLlmClient: () => LLMClient;\n  domSettleTimeoutMs?: number;\n};\n\nexport type ReadJsonResult<T> = {\n  value: T | null;\n  path?: string;\n  error?: unknown;\n};\n\nexport type WriteJsonResult = {\n  path?: string;\n  error?: unknown;\n};\n\nexport interface CachedActEntry {\n  version: 1;\n  instruction: string;\n  url: string;\n  variableKeys: string[];\n  actions: Action[];\n  actionDescription?: string;\n  message?: string;\n}\n\nexport type AgentReplayStep =\n  | AgentReplayActStep\n  | AgentReplayFillFormStep\n  | AgentReplayGotoStep\n  | AgentReplayScrollStep\n  | AgentReplayWaitStep\n  | AgentReplayNavBackStep\n  | AgentReplayKeysStep\n  | { type: string; [key: string]: unknown };\n\nexport interface AgentReplayActStep {\n  type: \"act\";\n  instruction: string;\n  actions?: Action[];\n  actionDescription?: string;\n  message?: string;\n  timeout?: number;\n}\n\nexport interface AgentReplayFillFormStep {\n  type: \"fillForm\";\n  fields?: Array<{ action: string }>;\n  observeResults?: Action[];\n  actions?: Action[];\n}\n\nexport interface AgentReplayGotoStep {\n  type: \"goto\";\n  url: string;\n  waitUntil?: LoadState;\n}\n\nexport interface AgentReplayScrollStep {\n  type: \"scroll\";\n  deltaX?: number;\n  deltaY?: number;\n  anchor?: { x: number; y: number };\n}\n\nexport interface AgentReplayWaitStep {\n  type: \"wait\";\n  timeMs: number;\n}\n\nexport interface AgentReplayNavBackStep {\n  type: \"navback\";\n  waitUntil?: LoadState;\n}\n\nexport interface AgentReplayKeysStep {\n  type: \"keys\";\n  instruction?: string;\n  playwrightArguments: {\n    method: \"type\" | \"press\";\n    text?: string;\n    keys?: string;\n    times?: number;\n  };\n}\n\nexport interface SanitizedAgentExecuteOptions {\n  maxSteps?: number;\n  highlightCursor?: boolean;\n}\n\nexport interface CachedAgentEntry {\n  version: 1;\n  instruction: string;\n  startUrl: string;\n  options: SanitizedAgentExecuteOptions;\n  configSignature: string;\n  steps: AgentReplayStep[];\n  result: AgentResult;\n  timestamp: string;\n}\n"]}

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

@@ -1,10 +1,11 @@
 import { Page } from "../../understudy/page.js";
 import { ModelConfiguration } from "../public/model.js";
 import type { StagehandZodSchema } from "../../zodCompat.js";
+import type { Variables } from "../public/agent.js";
 export interface ActHandlerParams {
     instruction: string;
     model?: ModelConfiguration;
-    variables?: Record<string, string>;
+    variables?: Variables;
     timeout?: number;
     page: Page;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/handlers.ts"],"names":[],"mappings":"AA6BA,gFAAgF;AAChF,MAAM,CAAN,IAAY,yBAYX;AAZD,WAAY,yBAAyB;IACnC,4CAAe,CAAA;IACf,0CAAa,CAAA;IACb,0CAAa,CAAA;IACb,4CAAe,CAAA;IACf,gDAAmB,CAAA;IACnB,qDAAwB,CAAA;IACxB,qDAAwB,CAAA;IACxB,qFAAwD,CAAA;IACxD,4CAAe,CAAA;IACf,yDAA4B,CAAA;IAC5B,0DAA6B,CAAA;AAC/B,CAAC,EAZW,yBAAyB,KAAzB,yBAAyB,QAYpC","sourcesContent":["import { Page } from \"../../understudy/page.js\";\nimport { ModelConfiguration } from \"../public/model.js\";\nimport type { StagehandZodSchema } from \"../../zodCompat.js\";\n\nexport interface ActHandlerParams {\n  instruction: string;\n  model?: ModelConfiguration;\n  variables?: Record<string, string>;\n  timeout?: number;\n  page: Page;\n}\n\nexport interface ExtractHandlerParams<T extends StagehandZodSchema> {\n  instruction?: string;\n  schema?: T;\n  model?: ModelConfiguration;\n  timeout?: number;\n  selector?: string;\n  page: Page;\n}\n\nexport interface ObserveHandlerParams {\n  instruction?: string;\n  model?: ModelConfiguration;\n  timeout?: number;\n  selector?: string;\n  page: Page;\n}\n\n// We can use this enum to list the actions supported in performUnderstudyMethod\nexport enum SupportedUnderstudyAction {\n  CLICK = \"click\",\n  FILL = \"fill\",\n  TYPE = \"type\",\n  PRESS = \"press\",\n  SCROLL = \"scrollTo\",\n  NEXT_CHUNK = \"nextChunk\",\n  PREV_CHUNK = \"prevChunk\",\n  SELECT_OPTION_FROM_DROPDOWN = \"selectOptionFromDropdown\",\n  HOVER = \"hover\",\n  DOUBLE_CLICK = \"doubleClick\",\n  DRAG_AND_DROP = \"dragAndDrop\",\n}\n"]}
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/handlers.ts"],"names":[],"mappings":"AA8BA,gFAAgF;AAChF,MAAM,CAAN,IAAY,yBAYX;AAZD,WAAY,yBAAyB;IACnC,4CAAe,CAAA;IACf,0CAAa,CAAA;IACb,0CAAa,CAAA;IACb,4CAAe,CAAA;IACf,gDAAmB,CAAA;IACnB,qDAAwB,CAAA;IACxB,qDAAwB,CAAA;IACxB,qFAAwD,CAAA;IACxD,4CAAe,CAAA;IACf,yDAA4B,CAAA;IAC5B,0DAA6B,CAAA;AAC/B,CAAC,EAZW,yBAAyB,KAAzB,yBAAyB,QAYpC","sourcesContent":["import { Page } from \"../../understudy/page.js\";\nimport { ModelConfiguration } from \"../public/model.js\";\nimport type { StagehandZodSchema } from \"../../zodCompat.js\";\nimport type { Variables } from \"../public/agent.js\";\n\nexport interface ActHandlerParams {\n  instruction: string;\n  model?: ModelConfiguration;\n  variables?: Variables;\n  timeout?: number;\n  page: Page;\n}\n\nexport interface ExtractHandlerParams<T extends StagehandZodSchema> {\n  instruction?: string;\n  schema?: T;\n  model?: ModelConfiguration;\n  timeout?: number;\n  selector?: string;\n  page: Page;\n}\n\nexport interface ObserveHandlerParams {\n  instruction?: string;\n  model?: ModelConfiguration;\n  timeout?: number;\n  selector?: string;\n  page: Page;\n}\n\n// We can use this enum to list the actions supported in performUnderstudyMethod\nexport enum SupportedUnderstudyAction {\n  CLICK = \"click\",\n  FILL = \"fill\",\n  TYPE = \"type\",\n  PRESS = \"press\",\n  SCROLL = \"scrollTo\",\n  NEXT_CHUNK = \"nextChunk\",\n  PREV_CHUNK = \"prevChunk\",\n  SELECT_OPTION_FROM_DROPDOWN = \"selectOptionFromDropdown\",\n  HOVER = \"hover\",\n  DOUBLE_CLICK = \"doubleClick\",\n  DRAG_AND_DROP = \"dragAndDrop\",\n}\n"]}

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

@@ -11,7 +11,7 @@ export type ShutdownSupervisorConfig = {
     kind: "STAGEHAND_API";
     sessionId: string;
     apiKey: string;
-    projectId: string;
+    projectId?: string;
 };
 export interface ShutdownSupervisorHandle {
     /** Best-effort signal to stop the supervisor process. */

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

@@ -1 +1 @@
-{"version":3,"file":"shutdown.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/shutdown.ts"],"names":[],"mappings":"AAAA;;GAEG","sourcesContent":["/**\n * Internal-only types for the shutdown supervisor process.\n */\n\nexport type ShutdownSupervisorConfig =\n  | {\n      kind: \"LOCAL\";\n      pid: number;\n      userDataDir?: string;\n      createdTempProfile?: boolean;\n      preserveUserDataDir?: boolean;\n    }\n  | {\n      kind: \"STAGEHAND_API\";\n      sessionId: string;\n      apiKey: string;\n      projectId: string;\n    };\n\nexport interface ShutdownSupervisorHandle {\n  /** Best-effort signal to stop the supervisor process. */\n  stop: () => void;\n}\n"]}
+{"version":3,"file":"shutdown.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/shutdown.ts"],"names":[],"mappings":"AAAA;;GAEG","sourcesContent":["/**\n * Internal-only types for the shutdown supervisor process.\n */\n\nexport type ShutdownSupervisorConfig =\n  | {\n      kind: \"LOCAL\";\n      pid: number;\n      userDataDir?: string;\n      createdTempProfile?: boolean;\n      preserveUserDataDir?: boolean;\n    }\n  | {\n      kind: \"STAGEHAND_API\";\n      sessionId: string;\n      apiKey: string;\n      projectId?: string;\n    };\n\nexport interface ShutdownSupervisorHandle {\n  /** Best-effort signal to stop the supervisor process. */\n  stop: () => void;\n}\n"]}

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

@@ -9,6 +9,30 @@ import { Page as PlaywrightPage } from "playwright-core";
 import { Page as PuppeteerPage } from "puppeteer-core";
 import { Page as PatchrightPage } from "patchright-core";
 import { Page } from "../../understudy/page.js";
+/**
+ * A variable value can be a simple primitive or a rich object with an optional description.
+ * This unified type is shared across `act`, `agent.execute`, and other methods.
+ *
+ * @example Simple (backward-compatible):
+ * ```typescript
+ * variables: { username: "john@example.com" }
+ * ```
+ *
+ * @example Rich with description (useful for agents):
+ * ```typescript
+ * variables: {
+ *   username: { value: "john@example.com", description: "The login email" }
+ * }
+ * ```
+ */
+export type VariableValue = string | number | boolean | {
+    value: string | number | boolean;
+    description?: string;
+};
+/**
+ * A collection of named variables for use in act, agent, and other methods.
+ */
+export type Variables = Record<string, VariableValue>;
 export interface AgentContext {
     options: AgentExecuteOptionsBase;
     maxSteps: number;
@@ -251,7 +275,7 @@ export interface AgentExecuteOptionsBase {
      * - `think` - Agent reasoning/planning step
      * - `wait` - Wait for time or condition
      * - `done` - Mark task as complete
-     * - `search` - Web search (requires BRAVE_API_KEY)
+     * - `search` - Web search (requires useSearch: true and BROWSERBASE_API_KEY)
      *
      * **Hybrid mode:**
      * - `click` - Click at specific coordinates
@@ -270,7 +294,7 @@ export interface AgentExecuteOptionsBase {
      * - `think` - Agent reasoning step
      * - `wait` - Wait for time/condition
      * - `done` - Mark task complete
-     * - `search` - Web search (requires BRAVE_API_KEY)
+     * - `search` - Web search (requires useSearch: true and BROWSERBASE_API_KEY)
      *
      * @experimental
      * @example
@@ -303,6 +327,52 @@ export interface AgentExecuteOptionsBase {
      * ```
      */
     output?: StagehandZodObject;
+    /**
+     * Variables that the agent can use when filling forms or typing text.
+     * The agent will see variable names and descriptions in the system prompt,
+     * and can use them via `%variableName%` syntax in act/type/fillForm tool calls.
+     *
+     * Accepts both simple values and rich objects with descriptions (same type as `act`).
+     *
+     * **Note:** Not supported in CUA mode (`mode: "cua"`). Requires `experimental: true`.
+     *
+     * @experimental
+     * @example
+     * ```typescript
+     * // Simple values
+     * variables: { username: "john@example.com", password: "secret123" }
+     *
+     * // Rich values with descriptions (helps the agent understand context)
+     * variables: {
+     *   username: { value: "john@example.com", description: "The login email" },
+     *   password: { value: "secret123", description: "The login password" },
+     * }
+     * ```
+     */
+    variables?: Variables;
+    /**
+     * Timeout in milliseconds for each agent tool call.
+     * If a tool call exceeds this duration, it will be aborted and
+     * reported back to the LLM as a timeout error so it can retry or adjust.
+     * For tools that call v3 methods (act, extract, fillForm, ariaTree), the
+     * timeout is also forwarded to the underlying v3 call for true cancellation.
+     * @default 45000 (45 seconds)
+     */
+    toolTimeout?: number;
+    /**
+     * Enable the web search tool powered by Browserbase Search API.
+     * Requires a valid Browserbase API key (BROWSERBASE_API_KEY).
+     * When set to true, the agent gains access to a `search` tool for web searches.
+     *
+     * @example
+     * ```typescript
+     * const result = await agent.execute({
+     *   instruction: "Find the latest news about AI",
+     *   useSearch: true,
+     * });
+     * ```
+     */
+    useSearch?: boolean;
 }
 /**
  * Options for non-streaming agent execution.
@@ -326,8 +396,8 @@ export interface AgentStreamExecuteOptions extends AgentExecuteOptionsBase {
      */
     callbacks?: AgentStreamCallbacks;
 }
-export type AgentType = "openai" | "anthropic" | "google" | "microsoft";
-export declare const AVAILABLE_CUA_MODELS: readonly ["openai/computer-use-preview", "openai/computer-use-preview-2025-03-11", "anthropic/claude-3-7-sonnet-latest", "anthropic/claude-opus-4-5-20251101", "anthropic/claude-opus-4-6", "anthropic/claude-haiku-4-5-20251001", "anthropic/claude-sonnet-4-20250514", "anthropic/claude-sonnet-4-5-20250929", "google/gemini-2.5-computer-use-preview-10-2025", "google/gemini-3-flash-preview", "google/gemini-3-pro-preview", "microsoft/fara-7b"];
+export type AgentType = "openai" | "anthropic" | "google" | "microsoft" | "bedrock";
+export declare const AVAILABLE_CUA_MODELS: readonly ["openai/computer-use-preview", "openai/computer-use-preview-2025-03-11", "anthropic/claude-opus-4-5-20251101", "anthropic/claude-opus-4-6", "anthropic/claude-sonnet-4-6", "anthropic/claude-haiku-4-5-20251001", "anthropic/claude-sonnet-4-20250514", "anthropic/claude-sonnet-4-5-20250929", "google/gemini-2.5-computer-use-preview-10-2025", "google/gemini-3-flash-preview", "google/gemini-3-pro-preview", "microsoft/fara-7b"];
 export type AvailableCuaModel = (typeof AVAILABLE_CUA_MODELS)[number];
 export interface AgentExecutionOptions<TOptions extends AgentExecuteOptions = AgentExecuteOptions> {
     options: TOptions;
@@ -584,6 +654,7 @@ export interface ScrollToolResult {
     success: boolean;
     message: string;
     scrolledPixels: number;
+    error?: string;
 }
 export interface ScrollVisionToolResult extends ScrollToolResult {
     screenshotBase64?: string;
@@ -592,4 +663,5 @@ export interface WaitToolResult {
     success: boolean;
     waited: number;
     screenshotBase64?: string;
+    error?: string;
 }

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

@@ -1,9 +1,9 @@
 export const AVAILABLE_CUA_MODELS = [
     "openai/computer-use-preview",
     "openai/computer-use-preview-2025-03-11",
-    "anthropic/claude-3-7-sonnet-latest",
     "anthropic/claude-opus-4-5-20251101",
     "anthropic/claude-opus-4-6",
+    "anthropic/claude-sonnet-4-6",
     "anthropic/claude-haiku-4-5-20251001",
     "anthropic/claude-sonnet-4-20250514",
     "anthropic/claude-sonnet-4-5-20250929",