@browserbasehq/eve 0.2.2 → 0.2.3-alpha-99e855dc16394f85652b080eac74f1053cea05b4

package/dist/extension/lib/core/facade/batch-sources.d.ts

@@ -0,0 +1,56 @@
+import type { ExperimentalBatchCallback } from "@browserbasehq/stagehand";
+import type { RefAction } from "./contract.js";
+import { type PlaywrightCompatTelemetry } from "./runtime.js";
+/**
+ * The JavaScript the facade sends to `experimentalBatch`. The SDK sends a
+ * callback's source text, so the exported *_SOURCE / RUN_PRELUDE / RUN_EPILOGUE
+ * strings are exactly what reaches the executor and go into the facade bundle
+ * unchanged for other hosts.
+ */
+export type ActionInput = {
+    actions: RefAction[];
+    xpathById: Record<string, string>;
+};
+/** `staleId` is the first action ID that resolved to no XPath; no action ran. */
+export type ActionResult = {
+    completed: number;
+    staleId?: never;
+} | {
+    staleId: string;
+    completed?: never;
+};
+export type ScreenshotArtifact = {
+    path: string;
+    base64: string;
+};
+export type RunInput = {
+    hiddenPageIds?: string[];
+    quietWait?: boolean;
+};
+export type RunEnvelope = {
+    __stagehandPlaywrightCompat: true;
+    value: unknown;
+    executionError?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    telemetry: PlaywrightCompatTelemetry;
+    artifacts: ScreenshotArtifact[];
+    closeRequested: boolean;
+    batchRuntimeMs: number;
+};
+/** createPlaywrightCompatRuntime as one self-contained function source. */
+export declare const RUNTIME_SOURCE: string;
+/** Resolves snapshot IDs against the page's stored XPath map, then runs the actions. */
+export declare const actionRunner: ExperimentalBatchCallback<ActionInput, ActionResult>;
+export declare const ACTION_RUNNER_SOURCE: string;
+/** The source of `runCallback(code)` is `RUN_PRELUDE + code + RUN_EPILOGUE`. */
+export declare const RUN_PRELUDE: string;
+export declare const RUN_EPILOGUE: string;
+/**
+ * Agent code runs with Playwright-shaped page, context and browser in scope and
+ * resolves to a RunEnvelope. The AsyncFunction constructor parses `code` as a
+ * whole function body, so it cannot close the wrapper early.
+ */
+export declare function runCallback(code: string): ExperimentalBatchCallback<RunInput, RunEnvelope>;

package/dist/extension/lib/core/facade/batch-sources.mjs

@@ -0,0 +1,84 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import { createPlaywrightCompatRuntime } from "./runtime.mjs";
+const AsyncFunction = Object.getPrototypeOf(async function() {}).constructor;
+const dynamicFunctionHead = (params) => `async function anonymous(${params.join(",")}\n) {\n`;
+const DYNAMIC_FUNCTION_TAIL = "\n}";
+const RUNTIME_SOURCE = createPlaywrightCompatRuntime.toString();
+const ACTION_RUNNER_BODY = `"use strict";
+const resolveSnapshotXPath = (id) => {
+  const exact = input.xpathById[id];
+  if (exact !== undefined) return exact;
+  if (id.includes("-")) return undefined;
+  const suffix = "-" + id;
+  const matches = Object.keys(input.xpathById).filter((key) => key.endsWith(suffix));
+  return matches.length === 1 ? input.xpathById[matches[0]] : undefined;
+};
+const selectors = [];
+for (const action of input.actions) {
+  const xpath = resolveSnapshotXPath(action.id)?.replace(/\\/text\\(\\)(\\[\\d+\\])?$/iu, "");
+  if (!xpath) return { staleId: action.id };
+  selectors.push("xpath=" + xpath);
+}
+let completed = 0;
+for (const [index, action] of input.actions.entries()) {
+  const locator = stagehand.page.locator(selectors[index]);
+  switch (action.op) {
+    case "click": await locator.click(); break;
+    case "hover": await locator.hover(); break;
+    case "fill": await locator.fill(action.value); break;
+    case "type": await locator.type(action.text, action.delay === undefined ? undefined : { delay: action.delay }); break;
+    case "press": await locator.click(); await stagehand.page.keyPress(action.key); break;
+    case "select": await locator.selectOption(action.values); break;
+    default: throw new Error("Unsupported ref action: " + String(action.op));
+  }
+  completed += 1;
+}
+return { completed };`;
+const RUN_PARAMS = ["batchStagehand", "input"];
+const RUN_PRELUDE_BODY = `"use strict";
+const __stagehandCompatIdentity = (target) => target;
+for (let index = 0; index <= 32; index += 1) {
+  globalThis[index === 0 ? "__name" : "__name" + index] = __stagehandCompatIdentity;
+}
+const createRuntime = ${RUNTIME_SOURCE};
+const runtime = await createRuntime(batchStagehand, { hiddenPageIds: input.hiddenPageIds ?? [], quietWait: input.quietWait === true });
+const page = runtime.page;
+const context = runtime.context;
+const browser = runtime.browser;
+const console = globalThis.console;
+const __stagehandBatchStartedAt = performance.now();
+let value;
+let executionError;
+try {
+  value = await (async () => { `;
+const RUN_EPILOGUE_BODY = `
+  })();
+} catch (error) {
+  executionError = {
+    name: typeof error?.name === "string" ? error.name : "Error",
+    message: typeof error?.message === "string" ? error.message : String(error),
+    ...(typeof error?.stack === "string" ? { stack: error.stack } : {}),
+  };
+}
+return {
+  __stagehandPlaywrightCompat: true,
+  value,
+  executionError,
+  telemetry: runtime.telemetry(),
+  artifacts: runtime.artifacts(),
+  closeRequested: runtime.closeRequested(),
+  batchRuntimeMs: performance.now() - __stagehandBatchStartedAt,
+};`;
+const actionRunner = new AsyncFunction("stagehand", "input", ACTION_RUNNER_BODY);
+const ACTION_RUNNER_SOURCE = Function.prototype.toString.call(actionRunner);
+const RUN_PRELUDE = dynamicFunctionHead(RUN_PARAMS) + RUN_PRELUDE_BODY;
+const RUN_EPILOGUE = RUN_EPILOGUE_BODY + DYNAMIC_FUNCTION_TAIL;
+function runCallback(code) {
+	return new AsyncFunction(...RUN_PARAMS, RUN_PRELUDE_BODY + code + RUN_EPILOGUE_BODY);
+}
+export { ACTION_RUNNER_SOURCE, RUNTIME_SOURCE, RUN_EPILOGUE, RUN_PRELUDE, actionRunner, runCallback };

package/dist/extension/lib/core/facade/contract.d.ts

@@ -716,9 +716,11 @@ export declare const SNAPSHOT_ACTIONS_WORKFLOW = "Workflow: after navigating or
 export declare const SNAPSHOT_TOOL_DESCRIPTION_EXPLICIT = "Capture the active page's Stagehand accessibility tree and hydrate its displayed IDs for subsequent run actions. Every call replaces the active page's ID map. Call it after every navigation or page change and before acting by ID.";
 export declare const SCREENSHOT_TOOL_DESCRIPTION_EXPLICIT = "Capture a screenshot of the active page. For size-constrained MCP clients, prefer a viewport JPEG: {\"type\":\"jpeg\",\"quality\":40,\"fullPage\":false}. Use it to verify the visible state before reporting done, on visual or canvas content, and when text evidence is ambiguous.";
 export declare const RUN_TOOL_DESCRIPTION_EXPLICIT = "Browse and automate websites in the persistent browser by executing JavaScript against a Playwright-shaped API. The code runs inside an async function with page, context, and browser in scope (Playwright Page, BrowserContext, and Browser); use await directly and return a JSON-serializable value when useful. Navigate with await page.goto(\"https://example.com\"); there is no separate navigate or start tool. Alternatively, provide a batch of actions using IDs from the latest snapshot. Provide exactly one of code or actions. Each action must use \"op\" (never \"kind\") and \"id\" (never \"ref\"). Copy the bracketed snapshot ID as a string. Examples: {\"actions\":[{\"op\":\"click\",\"id\":\"1-42\"}]}, {\"actions\":[{\"op\":\"fill\",\"id\":\"2-14\",\"value\":\"Miami\"}]}, {\"actions\":[{\"op\":\"select\",\"id\":\"3-9\",\"values\":\"Lowest price\"}]}. Prefer \"actions\" with snapshot IDs for simple clicks/fills/selects on visible elements; use \"code\" for multi-step logic and extraction.";
-export declare function explicitSnapshotActionsEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** Environment variables as read by the facade; `process.env` satisfies it. */
+export type FacadeEnv = Readonly<Record<string, string | undefined>>;
+export declare function explicitSnapshotActionsEnabled(env?: FacadeEnv): boolean;
 export declare const FACADE_TOOLS_EXPLICIT_SNAPSHOT: typeof FACADE_TOOLS;
-export declare function facadeToolsFor(surface: FacadeSurface, env?: NodeJS.ProcessEnv): readonly [{
+export declare function facadeToolsFor(surface: FacadeSurface, env?: FacadeEnv): readonly [{
     readonly name: "run";
     readonly description: "Browse and automate websites in the persistent browser by executing JavaScript against a Playwright-shaped API. The code runs inside an async function with page, context, and browser in scope (Playwright Page, BrowserContext, and Browser); use await directly and return a JSON-serializable value when useful. Navigate with await page.goto(\"https://example.com\"); there is no separate navigate or start tool. Alternatively, provide a batch of actions using IDs from the latest snapshot. Provide exactly one of code or actions. Each action must use \"op\" (never \"kind\") and \"id\" (never \"ref\"). Copy the bracketed snapshot ID as a string. Examples: {\"actions\":[{\"op\":\"click\",\"id\":\"1-42\"}]}, {\"actions\":[{\"op\":\"fill\",\"id\":\"2-14\",\"value\":\"Miami\"}]}, {\"actions\":[{\"op\":\"select\",\"id\":\"3-9\",\"values\":\"Lowest price\"}]}.";
     readonly inputSchema: {
@@ -997,7 +999,7 @@ export declare function facadeToolsFor(surface: FacadeSurface, env?: NodeJS.Proc
         readonly additionalProperties: false;
     };
 }];
-export declare function facadeAgentInstructions(env?: NodeJS.ProcessEnv): string;
+export declare function facadeAgentInstructions(env?: FacadeEnv): string;
 /**
  * Canonical agent system prompt for the facade tool surface. Host examples
  * (Eve, Vercel AI SDK, deepagents) should use this text rather than authoring
@@ -1013,6 +1015,50 @@ export declare const NO_HYDRATED_SNAPSHOT_ERROR = "No hydrated snapshot exists f
 export declare const NAVIGATED_SNAPSHOT_ERROR = "The active page navigated after its snapshot; call snapshot again.";
 export declare const STALE_SNAPSHOT_ID_ERROR = "Snapshot ID \"${id}\" is stale or not actionable; call snapshot again.";
 export declare function staleSnapshotIdError(id: string): string;
+export declare const SCREENSHOT_ARTIFACT_PATH_ERROR = "Screenshot artifact path must stay within artifactRoot.";
+export declare const SCREENSHOT_ARTIFACT_SYMLINK_ERROR = "Screenshot artifact directory must not be a symlink.";
+export declare const SCREENSHOT_ARTIFACT_FILE_SYMLINK_ERROR = "Screenshot artifact file must not be a symlink.";
+export declare const FACADE_BROWSER_CLOSED_ERROR = "Stagehand facade browser is closed.";
+/**
+ * Part of the error a Stagehand SDK raises from `context.activePage()` when the
+ * focused window's active tab is not one Stagehand registered (another window
+ * has focus). Hosts then act on the newest registered tab instead of failing.
+ */
+export declare const UNMANAGED_ACTIVE_PAGE_ERROR_MARKER = "active target not registered";
+/**
+ * Caps on what one `run` batch may hand back to its host. They bound memory and
+ * disk use against a runaway or hostile batch, and sit far above any real agent
+ * run: a full-page PNG is a few MB, and a 10 MB value is already far more than a
+ * model can read. Value size is the UTF-8 length of the value's compact JSON.
+ */
+export declare const RUN_RESULT_LIMITS: Readonly<{
+    readonly maxArtifacts: 32;
+    readonly maxArtifactBytes: number;
+    readonly maxTotalArtifactBytes: number;
+    readonly maxValueBytes: number;
+}>;
+/**
+ * Run options a host passes in the `run` batch input; all are off unless the
+ * host turns them on. `quietWait`: page.waitForTimeout(ms) returns once the
+ * page is quiet (readyState past "loading", no mutation in the main document
+ * for `windowMs`; shadow roots and iframes are not observed), checked in the
+ * page every `pollMs` through page.waitForFunction, never later than ms; at or
+ * below `windowMs` it just sleeps, as it does on pages without waitForFunction. The runtime (src/facade/runtime.ts) holds the same numbers.
+ */
+export declare const RUN_OPTIONS: {
+    readonly quietWait: {
+        readonly default: false;
+        readonly windowMs: 400;
+        readonly pollMs: 100;
+    };
+};
+export declare const RUN_RESULT_MALFORMED_ERROR = "The run batch returned a malformed result.";
+export declare const SCREENSHOT_ARTIFACT_COUNT_ERROR: string;
+export declare const SCREENSHOT_ARTIFACT_SIZE_ERROR: string;
+export declare const SCREENSHOT_ARTIFACT_TOTAL_SIZE_ERROR: string;
+export declare const RUN_VALUE_SIZE_ERROR: string;
+export declare const SCREENSHOT_CAPTURED_MESSAGE = "Screenshot captured.";
+export declare const SCREENSHOT_COMPRESSED_MESSAGE = "Screenshot captured with transport-safe compression.";
 /**
  * Prefix of the terminal error every facade tool returns once the browser
  * session is gone. Harnesses match on it to tell consequences from agent errors.

package/dist/extension/lib/core/facade/contract.mjs

@@ -162,6 +162,30 @@ const STALE_SNAPSHOT_ID_ERROR = "Snapshot ID \"${id}\" is stale or not actionabl
 function staleSnapshotIdError(id) {
 	return STALE_SNAPSHOT_ID_ERROR.replace("${id}", id);
 }
+const SCREENSHOT_ARTIFACT_PATH_ERROR = "Screenshot artifact path must stay within artifactRoot.";
+const SCREENSHOT_ARTIFACT_SYMLINK_ERROR = "Screenshot artifact directory must not be a symlink.";
+const SCREENSHOT_ARTIFACT_FILE_SYMLINK_ERROR = "Screenshot artifact file must not be a symlink.";
+const FACADE_BROWSER_CLOSED_ERROR = "Stagehand facade browser is closed.";
+const UNMANAGED_ACTIVE_PAGE_ERROR_MARKER = "active target not registered";
+const MB = 1048576;
+const RUN_RESULT_LIMITS = Object.freeze({
+	maxArtifacts: 32,
+	maxArtifactBytes: 25 * MB,
+	maxTotalArtifactBytes: 100 * MB,
+	maxValueBytes: 10 * MB
+});
+const RUN_OPTIONS = { quietWait: {
+	default: false,
+	windowMs: 400,
+	pollMs: 100
+} };
+const RUN_RESULT_MALFORMED_ERROR = "The run batch returned a malformed result.";
+const SCREENSHOT_ARTIFACT_COUNT_ERROR = `A run can save at most ${RUN_RESULT_LIMITS.maxArtifacts} screenshot artifacts.`;
+const SCREENSHOT_ARTIFACT_SIZE_ERROR = `A screenshot artifact can be at most ${RUN_RESULT_LIMITS.maxArtifactBytes / MB} MB.`;
+const SCREENSHOT_ARTIFACT_TOTAL_SIZE_ERROR = `A run's screenshot artifacts can total at most ${RUN_RESULT_LIMITS.maxTotalArtifactBytes / MB} MB.`;
+const RUN_VALUE_SIZE_ERROR = `A run can return at most ${RUN_RESULT_LIMITS.maxValueBytes / MB} MB of JSON; return less data.`;
+const SCREENSHOT_CAPTURED_MESSAGE = "Screenshot captured.";
+const SCREENSHOT_COMPRESSED_MESSAGE = "Screenshot captured with transport-safe compression.";
 const BROWSER_SESSION_LOST_ERROR_PREFIX = "Browser session lost (";
 const BROWSER_SESSION_LOST_ERROR = "Browser session lost (${cause}). The task cannot continue; report your final result now.";
 const SESSION_LOST_TELEMETRY_PREFIX = "stagehand_facade_session_lost ";
@@ -212,4 +236,4 @@ const ScreenshotInputSchema = z.strictObject({
 	type: z.enum(["png", "jpeg"]).optional(),
 	quality: z.number().min(0).max(100).optional()
 });
-export { BROWSER_SESSION_LOST_ERROR, BROWSER_SESSION_LOST_ERROR_PREFIX, CodeModeRunInputSchema, FACADE_AGENT_INSTRUCTIONS, FACADE_LEGACY_TOOLS, FACADE_TOOLS, FACADE_TOOLS_EXPLICIT_SNAPSHOT, LEGACY_FACADE_AGENT_INSTRUCTIONS, LEGACY_RUN_TOOL_DESCRIPTION, NAVIGATED_SNAPSHOT_ERROR, NO_HYDRATED_SNAPSHOT_ERROR, RUN_INPUT_SCHEMA, RUN_TOOL_DESCRIPTION, RUN_TOOL_DESCRIPTION_EXPLICIT, RefActionSchema, SCREENSHOT_INPUT_SCHEMA, SCREENSHOT_TOOL_DESCRIPTION, SCREENSHOT_TOOL_DESCRIPTION_EXPLICIT, SESSION_INFO_TOOL_NAME, SESSION_LOST_TELEMETRY_PREFIX, SNAPSHOT_ACTIONS_WORKFLOW, SNAPSHOT_INPUT_SCHEMA, SNAPSHOT_TOOL_DESCRIPTION, SNAPSHOT_TOOL_DESCRIPTION_EXPLICIT, STALE_SNAPSHOT_ID_ERROR, ScreenshotInputSchema, SnapshotInputSchema, browserSessionLostError, explicitSnapshotActionsEnabled, facadeAgentInstructions, facadeSurfaceFromArgs, facadeToolsFor, facadeToolsForSurface, isBrowserSessionLostError, staleSnapshotIdError };
+export { BROWSER_SESSION_LOST_ERROR, BROWSER_SESSION_LOST_ERROR_PREFIX, CodeModeRunInputSchema, FACADE_AGENT_INSTRUCTIONS, FACADE_BROWSER_CLOSED_ERROR, FACADE_LEGACY_TOOLS, FACADE_TOOLS, FACADE_TOOLS_EXPLICIT_SNAPSHOT, LEGACY_FACADE_AGENT_INSTRUCTIONS, LEGACY_RUN_TOOL_DESCRIPTION, NAVIGATED_SNAPSHOT_ERROR, NO_HYDRATED_SNAPSHOT_ERROR, RUN_INPUT_SCHEMA, RUN_OPTIONS, RUN_RESULT_LIMITS, RUN_RESULT_MALFORMED_ERROR, RUN_TOOL_DESCRIPTION, RUN_TOOL_DESCRIPTION_EXPLICIT, RUN_VALUE_SIZE_ERROR, RefActionSchema, SCREENSHOT_ARTIFACT_COUNT_ERROR, SCREENSHOT_ARTIFACT_FILE_SYMLINK_ERROR, SCREENSHOT_ARTIFACT_PATH_ERROR, SCREENSHOT_ARTIFACT_SIZE_ERROR, SCREENSHOT_ARTIFACT_SYMLINK_ERROR, SCREENSHOT_ARTIFACT_TOTAL_SIZE_ERROR, SCREENSHOT_CAPTURED_MESSAGE, SCREENSHOT_COMPRESSED_MESSAGE, SCREENSHOT_INPUT_SCHEMA, SCREENSHOT_TOOL_DESCRIPTION, SCREENSHOT_TOOL_DESCRIPTION_EXPLICIT, SESSION_INFO_TOOL_NAME, SESSION_LOST_TELEMETRY_PREFIX, SNAPSHOT_ACTIONS_WORKFLOW, SNAPSHOT_INPUT_SCHEMA, SNAPSHOT_TOOL_DESCRIPTION, SNAPSHOT_TOOL_DESCRIPTION_EXPLICIT, STALE_SNAPSHOT_ID_ERROR, ScreenshotInputSchema, SnapshotInputSchema, UNMANAGED_ACTIVE_PAGE_ERROR_MARKER, browserSessionLostError, explicitSnapshotActionsEnabled, facadeAgentInstructions, facadeSurfaceFromArgs, facadeToolsFor, facadeToolsForSurface, isBrowserSessionLostError, staleSnapshotIdError };

package/dist/extension/lib/core/facade/runtime.d.ts

@@ -41,6 +41,10 @@ type RawPage = {
     waitForLoadState(state: string, timeout?: number): Promise<void>;
     waitForTimeout(ms: number): Promise<void>;
     waitForSelector(selector: string, options?: Record<string, unknown>): Promise<boolean>;
+    waitForFunction?(expression: string, arg?: undefined, options?: {
+        polling?: "raf" | number;
+        timeout?: number;
+    }): Promise<unknown>;
     url(): Promise<string>;
     title(): Promise<string>;
     close(): Promise<void>;
@@ -88,6 +92,17 @@ type BatchStagehandRuntime = {
 export type PlaywrightCompatTelemetry = {
     calls: Record<string, number>;
     misses: Record<string, number>;
+    /**
+     * page.waitForTimeout calls: the time agent code asked for and the time it
+     * waited (capped at the request). They differ only with `quietWait`, where
+     * earlyReturns counts the waits that ended because the page was quiet.
+     */
+    waits: {
+        count: number;
+        requestedMs: number;
+        waitedMs: number;
+        earlyReturns: number;
+    };
 };
 export type PlaywrightCompatRuntime = {
     page: unknown;
@@ -108,6 +123,13 @@ export type PlaywrightCompatRuntime = {
 export type PlaywrightCompatRuntimeOptions = {
     /** Pages the host keeps for itself (the facade's keeper tab); never surfaced to agent code. */
     hiddenPageIds?: string[];
+    /**
+     * page.waitForTimeout(ms) returns once the page is quiet (DOM content loaded
+     * and no mutation in the main document for 400 ms; shadow roots and iframes
+     * are not observed), never later than ms. Waits of 400 ms or less always
+     * sleep in full. Off by default: the wait then sleeps exactly ms.
+     */
+    quietWait?: boolean;
 };
 export declare function createPlaywrightCompatRuntime(stagehand: BatchStagehandRuntime, options?: PlaywrightCompatRuntimeOptions): Promise<PlaywrightCompatRuntime>;
 export {};

package/dist/extension/lib/core/facade/runtime.mjs

@@ -13,7 +13,13 @@ async function createPlaywrightCompatRuntime(stagehand, options = {}) {
 	};
 	const stats = {
 		calls: {},
-		misses: {}
+		misses: {},
+		waits: {
+			count: 0,
+			requestedMs: 0,
+			waitedMs: 0,
+			earlyReturns: 0
+		}
 	};
 	const record = (bucket, method) => {
 		stats[bucket][method] = (stats[bucket][method] ?? 0) + 1;
@@ -634,6 +640,55 @@ async function createPlaywrightCompatRuntime(stagehand, options = {}) {
 	const pageKey = (page) => page.pageId ?? page;
 	const hiddenPageIds = new Set(options.hiddenPageIds ?? []);
 	const visibleRawPages = async () => (await rawContext.pages()).filter((page) => page.pageId === void 0 || !hiddenPageIds.has(page.pageId));
+	const QUIET_WAIT_WINDOW_MS = 400;
+	const QUIET_WAIT_POLL_MS = 100;
+	const quietWaitPredicate = (key) => `(() => {
+    const key = ${JSON.stringify(key)};
+    let state = document[key];
+    if (!state) {
+      state = { lastMutation: performance.now() };
+      state.observer = new MutationObserver(() => {
+        state.lastMutation = performance.now();
+      });
+      Object.defineProperty(document, key, { value: state, configurable: true });
+      state.observer.observe(document, { subtree: true, childList: true, attributes: true, characterData: true });
+    }
+    return document.readyState !== "loading" && performance.now() - state.lastMutation >= ${QUIET_WAIT_WINDOW_MS};
+  })()`;
+	const quietWaitCleanup = (key) => `(() => {
+    const key = ${JSON.stringify(key)};
+    const state = document[key];
+    if (state) {
+      state.observer.disconnect();
+      delete document[key];
+    }
+  })()`;
+	const waitForTimeoutOrQuiet = async (page, ms) => {
+		const requestedMs = Number.isFinite(ms) && ms > 0 ? ms : 0;
+		stats.waits.count += 1;
+		stats.waits.requestedMs += requestedMs;
+		const waitForFunction = page.waitForFunction;
+		if (!options.quietWait || !(requestedMs > QUIET_WAIT_WINDOW_MS) || typeof waitForFunction !== "function") {
+			await page.waitForTimeout(ms);
+			stats.waits.waitedMs += requestedMs;
+			return;
+		}
+		const key = `_${crypto.randomUUID()}`;
+		const startedAt = Date.now();
+		let timer;
+		const early = await Promise.race([waitForFunction.call(page, quietWaitPredicate(key), void 0, {
+			polling: QUIET_WAIT_POLL_MS,
+			timeout: requestedMs
+		}).then(() => true, () => false), new Promise((resolve) => {
+			timer = setTimeout(() => resolve(false), requestedMs);
+		})]);
+		clearTimeout(timer);
+		const left = startedAt + requestedMs - Date.now();
+		if (!early && left > 0) await page.waitForTimeout(left);
+		stats.waits.waitedMs += Math.min(Date.now() - startedAt, requestedMs);
+		if (early) stats.waits.earlyReturns += 1;
+		Promise.resolve().then(() => page.evaluate(quietWaitCleanup(key))).catch(() => void 0);
+	};
 	const compatPages = new Map();
 	const closedPages = new Set();
 	let closeRequested = false;
@@ -2068,7 +2123,7 @@ async function createPlaywrightCompatRuntime(stagehand, options = {}) {
 			},
 			waitForTimeout: async (ms) => {
 				record("calls", "page.waitForTimeout");
-				await page.waitForTimeout(ms);
+				await waitForTimeoutOrQuiet(page, ms);
 				for (const candidate of await visibleRawPages()) await createPage(candidate);
 			},
 			waitForLoadState: (state = "load", options = {}) => {
@@ -2428,7 +2483,8 @@ async function createPlaywrightCompatRuntime(stagehand, options = {}) {
 		}),
 		telemetry: () => ({
 			calls: { ...stats.calls },
-			misses: { ...stats.misses }
+			misses: { ...stats.misses },
+			waits: { ...stats.waits }
 		}),
 		artifacts: () => screenshotArtifacts.map((artifact) => ({ ...artifact })),
 		closeRequested: () => closeRequested

package/dist/extension/lib/core/facade/tools.d.ts

@@ -1,8 +1,10 @@
 import type { Stagehand } from "@browserbasehq/stagehand";
 import { type FacadeSessionLoss, type RefAction } from "./contract.js";
-import { type PlaywrightCompatTelemetry } from "./runtime.js";
+import type { PlaywrightCompatTelemetry } from "./runtime.js";
 export type StagehandFacadeRunReport = {
     telemetry: PlaywrightCompatTelemetry;
+    /** Whether the run used StagehandFacadeToolsOptions.quietWait. */
+    quietWait: boolean;
     /** Wall-clock time of the whole experimentalBatch round trip. */
     batchRoundTripMs: number;
     /** Time the agent's code spent executing inside the batch. */
@@ -43,6 +45,13 @@ export type StagehandFacadeToolsOptions = {
      * (`context.pages()` / `waitForEvent("page")` never list it).
      */
     keeperPage?: boolean;
+    /**
+     * Experimental, off by default: page.waitForTimeout(ms) longer than 400 ms
+     * in run code returns once the main document is quiet, capped at ms (see
+     * RUN_OPTIONS.quietWait). The run
+     * report's telemetry.waits shows requested against waited time.
+     */
+    quietWait?: boolean;
 };
 /** Every facade tool returns this once the browser session is gone. */
 export declare class StagehandFacadeSessionLostError extends Error {
@@ -101,6 +110,9 @@ export declare class StagehandFacadeTools {
      * The page the agent is working on. A closed or crashed tab leaves the
      * context without an active page (or with only the keeper); the agent then
      * gets a fresh blank page rather than a dead end, and the keeper stays hidden.
+     * When another window has focus on a tab Stagehand does not manage, the agent
+     * keeps working on the newest tab Stagehand registered; nothing is reordered,
+     * since activating a tab does not move window focus.
      */
     private activePage;
     /**

package/dist/extension/lib/core/facade/tools.mjs

@@ -4,8 +4,8 @@ import { createRequire as __eveCreateRequire } from "node:module";
 const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
-import { NAVIGATED_SNAPSHOT_ERROR, NO_HYDRATED_SNAPSHOT_ERROR, RefActionSchema, browserSessionLostError, staleSnapshotIdError } from "./contract.mjs";
-import { createPlaywrightCompatRuntime } from "./runtime.mjs";
+import { actionRunner, runCallback } from "./batch-sources.mjs";
+import { FACADE_BROWSER_CLOSED_ERROR, NAVIGATED_SNAPSHOT_ERROR, NO_HYDRATED_SNAPSHOT_ERROR, RUN_OPTIONS, RUN_RESULT_LIMITS, RUN_RESULT_MALFORMED_ERROR, RUN_VALUE_SIZE_ERROR, RefActionSchema, SCREENSHOT_ARTIFACT_COUNT_ERROR, SCREENSHOT_ARTIFACT_FILE_SYMLINK_ERROR, SCREENSHOT_ARTIFACT_PATH_ERROR, SCREENSHOT_ARTIFACT_SIZE_ERROR, SCREENSHOT_ARTIFACT_SYMLINK_ERROR, SCREENSHOT_ARTIFACT_TOTAL_SIZE_ERROR, browserSessionLostError, staleSnapshotIdError } from "./contract.mjs";
 import { sanitizeErrorMessage } from "../harness/redact.mjs";
 import fsp from "node:fs/promises";
 import { constants } from "node:fs";
@@ -41,58 +41,7 @@ var StagehandFacadeSessionLostError = class extends Error {
 };
 const RUN_BATCH_TIMEOUT_MS = 6e4;
 const PAGE_CAPTURE_DEADLINE_MS = 12e4;
-const AsyncFunction = Object.getPrototypeOf(async function() {}).constructor;
-const actionRunner = new AsyncFunction("stagehand", "input", `"use strict";
-let completed = 0;
-for (const action of input.actions) {
-  const locator = stagehand.page.locator(action.selector);
-  switch (action.op) {
-    case "click": await locator.click(); break;
-    case "hover": await locator.hover(); break;
-    case "fill": await locator.fill(action.value); break;
-    case "type": await locator.type(action.text, action.delay === undefined ? undefined : { delay: action.delay }); break;
-    case "press": await locator.click(); await stagehand.page.keyPress(action.key); break;
-    case "select": await locator.selectOption(action.values); break;
-    default: throw new Error("Unsupported ref action: " + String(action.op));
-  }
-  completed += 1;
-}
-return { completed };`);
 const FACADE_KEEPER_PAGE_URL = "about:blank";
-const FACADE_PRELUDE = `"use strict";
-const __stagehandCompatIdentity = (target) => target;
-for (let index = 0; index <= 32; index += 1) {
-  globalThis[index === 0 ? "__name" : "__name" + index] = __stagehandCompatIdentity;
-}
-const createRuntime = ${createPlaywrightCompatRuntime.toString()};
-const runtime = await createRuntime(batchStagehand, { hiddenPageIds: input.hiddenPageIds ?? [] });
-const page = runtime.page;
-const context = runtime.context;
-const browser = runtime.browser;
-const console = globalThis.console;
-const __stagehandBatchStartedAt = performance.now();
-let value;
-let executionError;
-try {
-  value = await (async () => { `;
-const FACADE_EPILOGUE = `
-  })();
-} catch (error) {
-  executionError = {
-    name: typeof error?.name === "string" ? error.name : "Error",
-    message: typeof error?.message === "string" ? error.message : String(error),
-    ...(typeof error?.stack === "string" ? { stack: error.stack } : {}),
-  };
-}
-return {
-  __stagehandPlaywrightCompat: true,
-  value,
-  executionError,
-  telemetry: runtime.telemetry(),
-  artifacts: runtime.artifacts(),
-  closeRequested: runtime.closeRequested(),
-  batchRuntimeMs: performance.now() - __stagehandBatchStartedAt,
-};`;
 var StagehandFacadeTools = class StagehandFacadeTools {
 	stagehand;
 	options;
@@ -184,40 +133,44 @@ var StagehandFacadeTools = class StagehandFacadeTools {
 			this.snapshotsByPage.delete(page.pageId);
 			throw new StagehandFacadeInputError(NAVIGATED_SNAPSHOT_ERROR);
 		}
-		const hydrated = parsed.map((action) => {
-			const xpath = trimTrailingTextNode(resolveSnapshotXPath(snapshot.xpathById, action.id));
-			if (!xpath) throw new StagehandFacadeInputError(staleSnapshotIdError(action.id));
-			return {
-				...action,
-				selector: `xpath=${xpath}`
-			};
+		const result = await this.stagehand.experimentalBatch(actionRunner, {
+			actions: parsed,
+			xpathById: snapshot.xpathById
+		}, {
+			page,
+			timeout: RUN_BATCH_TIMEOUT_MS
 		});
+		if (result?.staleId !== void 0) throw new StagehandFacadeInputError(staleSnapshotIdError(result.staleId));
 		return {
-			completed: (await this.stagehand.experimentalBatch(actionRunner, { actions: hydrated }, {
-				page,
-				timeout: RUN_BATCH_TIMEOUT_MS
-			}))?.completed ?? hydrated.length,
+			completed: result?.completed ?? parsed.length,
 			url: await page.url()
 		};
 	}
 	async runNow(code) {
 		const page = await this.activePage();
-		const callback = new AsyncFunction("batchStagehand", "input", FACADE_PRELUDE + code + FACADE_EPILOGUE);
+		const callback = runCallback(code);
 		const startedAt = performance.now();
 		const keeperPageId = await this.keeper;
-		const input = keeperPageId ? { hiddenPageIds: [keeperPageId] } : {};
+		const quietWait = this.options.quietWait ?? RUN_OPTIONS.quietWait.default;
+		const input = {
+			...keeperPageId && { hiddenPageIds: [keeperPageId] },
+			...quietWait && { quietWait: true }
+		};
 		const envelope = await this.runBatchWithActivePageFallback(callback, input, page);
+		if (!isRunEnvelope(envelope)) throw new StagehandFacadeInputError(RUN_RESULT_MALFORMED_ERROR);
 		let runError;
 		let runFailed = false;
 		try {
 			this.options.onRunReport?.({
 				telemetry: envelope.telemetry,
+				quietWait,
 				batchRoundTripMs: performance.now() - startedAt,
 				batchRuntimeMs: envelope.batchRuntimeMs,
 				closeRequested: envelope.closeRequested
 			});
 			await this.writeScreenshotArtifacts(envelope.artifacts);
 			if (envelope.executionError) throw new StagehandFacadeExecutionError(envelope.executionError);
+			if (Buffer.byteLength(JSON.stringify(envelope.value) ?? "") > RUN_RESULT_LIMITS.maxValueBytes) throw new StagehandFacadeInputError(RUN_VALUE_SIZE_ERROR);
 		} catch (error) {
 			runError = error;
 			runFailed = true;
@@ -248,13 +201,25 @@ var StagehandFacadeTools = class StagehandFacadeTools {
 	}
 	async writeScreenshotArtifacts(artifacts) {
 		if (artifacts.length === 0) return;
+		if (artifacts.length > RUN_RESULT_LIMITS.maxArtifacts) throw new StagehandFacadeInputError(SCREENSHOT_ARTIFACT_COUNT_ERROR);
+		let totalBytes = 0;
+		for (const artifact of artifacts) {
+			const size = decodedBase64Length(artifact.base64);
+			if (size > RUN_RESULT_LIMITS.maxArtifactBytes) throw new StagehandFacadeInputError(SCREENSHOT_ARTIFACT_SIZE_ERROR);
+			totalBytes += size;
+			if (totalBytes > RUN_RESULT_LIMITS.maxTotalArtifactBytes) throw new StagehandFacadeInputError(SCREENSHOT_ARTIFACT_TOTAL_SIZE_ERROR);
+		}
+		const decoded = artifacts.map((artifact) => ({
+			path: artifact.path,
+			bytes: Buffer.from(artifact.base64, "base64")
+		}));
 		const configuredRoot = path.resolve(this.options.artifactRoot ?? process.cwd());
 		await fsp.mkdir(configuredRoot, { recursive: true });
 		const root = await fsp.realpath(configuredRoot);
-		for (const artifact of artifacts) {
+		for (const artifact of decoded) {
 			const target = path.resolve(configuredRoot, artifact.path);
 			const relative = path.relative(configuredRoot, target);
-			if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new StagehandFacadeInputError("Screenshot artifact path must stay within artifactRoot.");
+			if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new StagehandFacadeInputError(SCREENSHOT_ARTIFACT_PATH_ERROR);
 			let directory = root;
 			const components = relative.split(path.sep);
 			for (const component of components.slice(0, -1)) {
@@ -262,11 +227,14 @@ var StagehandFacadeTools = class StagehandFacadeTools {
 				await fsp.mkdir(directory).catch((error) => {
 					if (error.code !== "EEXIST") throw error;
 				});
-				if (!(await fsp.lstat(directory)).isDirectory()) throw new StagehandFacadeInputError("Screenshot artifact directory must not be a symlink.");
+				if (!(await fsp.lstat(directory)).isDirectory()) throw new StagehandFacadeInputError(SCREENSHOT_ARTIFACT_SYMLINK_ERROR);
 			}
-			const file = await fsp.open(path.join(directory, components.at(-1)), constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW, 384);
+			const file = await fsp.open(path.join(directory, components.at(-1)), constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW, 384).catch((error) => {
+				if (error.code === "ELOOP") throw new StagehandFacadeInputError(SCREENSHOT_ARTIFACT_FILE_SYMLINK_ERROR);
+				throw error;
+			});
 			try {
-				await file.writeFile(Buffer.from(artifact.base64, "base64"));
+				await file.writeFile(artifact.bytes);
 			} finally {
 				await file.close();
 			}
@@ -275,7 +243,13 @@ var StagehandFacadeTools = class StagehandFacadeTools {
 	async activePage() {
 		const context = this.stagehand.browser.context;
 		const keeperPageId = await this.keeper;
-		const active = await context.activePage();
+		let active;
+		try {
+			active = await context.activePage();
+		} catch (error) {
+			if (!(error instanceof Error) || !error.message.includes("active target not registered")) throw error;
+			return (await context.pages()).filter((page) => page.pageId !== keeperPageId).at(-1) ?? await context.newPage();
+		}
 		if (active && active.pageId !== keeperPageId) return active;
 		const page = (await context.pages()).filter((page) => page.pageId !== keeperPageId)[0] ?? await context.newPage();
 		await context.setActivePage(page);
@@ -303,7 +277,7 @@ var StagehandFacadeTools = class StagehandFacadeTools {
 	enqueue(tool, operation) {
 		const guarded = async () => {
 			if (this.loss) throw new StagehandFacadeSessionLostError(this.loss);
-			if (this.closed) throw new StagehandFacadeInputError("Stagehand facade browser is closed.");
+			if (this.closed) throw new StagehandFacadeInputError(FACADE_BROWSER_CLOSED_ERROR);
 			try {
 				await this.ensureKeeperPage();
 				const value = await operation();
@@ -343,6 +317,21 @@ var StagehandFacadeTools = class StagehandFacadeTools {
 		} catch {}
 	}
 };
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isRunEnvelope(value) {
+	if (!isRecord(value) || value.__stagehandPlaywrightCompat !== true) return false;
+	const { executionError, artifacts } = value;
+	return typeof value.closeRequested === "boolean" && typeof value.batchRuntimeMs === "number" && isRecord(value.telemetry) && Array.isArray(artifacts) && artifacts.every((artifact) => isRecord(artifact) && typeof artifact.path === "string" && isCanonicalBase64(artifact.base64)) && (executionError === void 0 || executionError === null || isRecord(executionError) && typeof executionError.name === "string" && typeof executionError.message === "string" && (executionError.stack === void 0 || typeof executionError.stack === "string"));
+}
+function isCanonicalBase64(value) {
+	return typeof value === "string" && value.length % 4 === 0 && /^[A-Za-z0-9+/]*={0,2}$/.test(value);
+}
+function decodedBase64Length(value) {
+	const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
+	return value.length / 4 * 3 - padding;
+}
 var FacadeDeadlineError = class extends Error {
 	name = "FacadeDeadlineError";
 	constructor(operation, timeoutMs) {
@@ -387,15 +376,4 @@ function cdpSessionLossCause(error) {
 	}
 	return sanitizeErrorMessage(messages.join("; caused by "));
 }
-function trimTrailingTextNode(path) {
-	return path?.replace(/\/text\(\)(\[\d+\])?$/iu, "");
-}
-function resolveSnapshotXPath(xpathById, id) {
-	const exact = xpathById[id];
-	if (exact !== void 0) return exact;
-	if (id.includes("-")) return void 0;
-	const suffix = `-${id}`;
-	const matches = Object.keys(xpathById).filter((key) => key.endsWith(suffix));
-	return matches.length === 1 ? xpathById[matches[0]] : void 0;
-}
 export { FACADE_KEEPER_PAGE_URL, StagehandFacadeCleanupError, StagehandFacadeExecutionError, StagehandFacadeInputError, StagehandFacadeSessionLostError, StagehandFacadeTools };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbasehq/eve",
-  "version": "0.2.2",
+  "version": "0.2.3-alpha-99e855dc16394f85652b080eac74f1053cea05b4",
   "description": "Browserbase for Eve, powered by Stagehand V4 Code Mode.",
   "keywords": [
     "ai-agents",
@@ -40,8 +40,8 @@
   },
   "dependencies": {
     "@browserbasehq/sdk": "^2.16.0",
-    "zod": "4.4.3",
-    "@browserbasehq/stagehand": "4.3.0"
+    "zod": "4.6.6",
+    "@browserbasehq/stagehand": "4.3.1-alpha-99e855dc16394f85652b080eac74f1053cea05b4"
   },
   "devDependencies": {
     "@types/node": "^24",