@@ -0,0 +1,5 @@
+---
+"@browserbasehq/eve": minor
+---
+
+Replace the Eve extension's browser and web tools with Stagehand V4 `run`, `snapshot`, and `screenshot`.
@@ -99,6 +99,7 @@ _preview commit:
 
 _publish-typescript:
     pnpm --filter ./packages/sdk-ts build
+    pnpm --filter @browserbasehq/eve build
     pnpm exec tsx scripts/release/scoped-release.ts publish sdk
 
 # Publishes a commit-addressed alpha of the TypeScript SDK (`<next>-alpha-<sha>`)
 
@@ -36,6 +36,9 @@ export {
   type CodeModeRunInput,
 } from "./contract.js";
 export {
+  StagehandFacadeCleanupError,
+  StagehandFacadeExecutionError,
+  StagehandFacadeInputError,
   StagehandFacadeTools,
   type StagehandFacadeRunReport,
   type StagehandFacadeToolsOptions,
 
@@ -35,7 +35,36 @@ export type StagehandFacadeRunReport = {
   closeRequested: boolean;
 };
 
+export class StagehandFacadeCleanupError extends Error {
+  override readonly name = "StagehandFacadeCleanupError";
+
+  constructor() {
+    super("Failed to close the Stagehand browser session.");
+  }
+}
+
+export class StagehandFacadeInputError extends Error {
+  override readonly name = "StagehandFacadeInputError";
+
+  constructor(message: string) {
+    super(sanitizeErrorMessage(message));
+  }
+}
+
+export class StagehandFacadeExecutionError extends Error {
+  readonly facadeExecutionError = true;
+
+  constructor(error: { name: string; message: string }) {
+    super(sanitizeErrorMessage(error.message));
+    const name = sanitizeErrorMessage(error.name);
+    this.name = /^[A-Za-z][A-Za-z0-9]*Error$/u.test(name) ? name : "Error";
+    this.stack = undefined;
+  }
+}
+
 export type StagehandFacadeToolsOptions = {
+  /** Replaces default cleanup when the host owns session release and replacement. */
+  onCloseRequested?: () => Promise<void>;
   /** Owned directory for screenshot artifacts; paths must stay within it. Defaults to process.cwd(). */
   artifactRoot?: string;
   /** Observes every completed `run` batch (including ones whose code threw). */
@@ -142,19 +171,23 @@ export class StagehandFacadeTools {
   close(): Promise<void> {
     this.closed = true;
     return (this.closePromise ??= (async () => {
-      const failures: unknown[] = [];
+      if (this.options.onCloseRequested) {
+        try {
+          await this.options.onCloseRequested();
+        } catch {
+          throw new StagehandFacadeCleanupError();
+        }
+        return;
+      }
+      let failed = false;
       for (const close of [() => this.stagehand.close(), () => this.stagehand.browser.close()]) {
         try {
           await close();
-        } catch (error) {
-          failures.push(error);
+        } catch {
+          failed = true;
         }
       }
-      if (failures.length) {
-        throw new Error("Failed to close the Stagehand facade browser.", {
-          cause: new AggregateError(failures, "Facade browser cleanup failures"),
-        });
-      }
+      if (failed) throw new StagehandFacadeCleanupError();
     })());
   }
 
@@ -211,16 +244,16 @@ export class StagehandFacadeTools {
     const parsed = RefActionSchema.array().min(1).parse(actions);
     const page = await this.activePage();
     const snapshot = this.snapshotsByPage.get(page.pageId);
-    if (!snapshot) throw new Error(NO_HYDRATED_SNAPSHOT_ERROR);
+    if (!snapshot) throw new StagehandFacadeInputError(NO_HYDRATED_SNAPSHOT_ERROR);
 
     if ((await page.url()) !== snapshot.url) {
       this.snapshotsByPage.delete(page.pageId);
-      throw new Error(NAVIGATED_SNAPSHOT_ERROR);
+      throw new StagehandFacadeInputError(NAVIGATED_SNAPSHOT_ERROR);
     }
 
     const hydrated = parsed.map((action) => {
       const xpath = trimTrailingTextNode(resolveSnapshotXPath(snapshot.xpathById, action.id));
-      if (!xpath) throw new Error(staleSnapshotIdError(action.id));
+      if (!xpath) throw new StagehandFacadeInputError(staleSnapshotIdError(action.id));
       return { ...action, selector: `xpath=${xpath}` };
     });
     const result = await this.stagehand.experimentalBatch(
@@ -242,6 +275,8 @@ export class StagehandFacadeTools {
     const keeperPageId = await this.keeper;
     const input: RunInput = keeperPageId ? { hiddenPageIds: [keeperPageId] } : {};
     const envelope = await this.runBatchWithActivePageFallback(callback, input, page);
+    let runError: unknown;
+    let runFailed = false;
     try {
       this.options.onRunReport?.({
         telemetry: envelope.telemetry,
@@ -253,20 +288,26 @@ export class StagehandFacadeTools {
       if (envelope.executionError) {
         // Thrown by the agent's own code inside the browser, so its message can
         // never be evidence about this process's connection to the browser.
-        const error = new Error(envelope.executionError.message) as Error & {
-          facadeExecutionError: true;
-        };
-        error.name = envelope.executionError.name;
-        if (envelope.executionError.stack) error.stack = envelope.executionError.stack;
-        error.facadeExecutionError = true;
-        throw error;
+        throw new StagehandFacadeExecutionError(envelope.executionError);
+      }
+    } catch (error) {
+      runError = error;
+      runFailed = true;
+    }
+    // Wait until the batch finishes before closing its transport, even when
+    // agent code, telemetry, or artifact persistence failed.
+    if (envelope.closeRequested) {
+      try {
+        await this.close();
+      } catch (closeError) {
+        if (runFailed) {
+          throw new AggregateError([runError, closeError], "Run failed and cleanup also failed.");
+        }
+        throw closeError;
       }
-      return envelope.value;
-    } finally {
-      // The batch must finish before closing its own transport. This also
-      // honors close requests when agent code or artifact persistence failed.
-      if (envelope.closeRequested) await this.close();
     }
+    if (runFailed) throw runError;
+    return envelope.value;
   }
 
   /**
@@ -311,7 +352,9 @@ export class StagehandFacadeTools {
         relative.startsWith(`..${path.sep}`) ||
         path.isAbsolute(relative)
       ) {
-        throw new Error("Screenshot artifact path must stay within artifactRoot.");
+        throw new StagehandFacadeInputError(
+          "Screenshot artifact path must stay within artifactRoot.",
+        );
       }
       // Reject symlink traversal before creating nested directories or opening
       // the output. O_NOFOLLOW also refuses an existing symlink at the file.
@@ -323,7 +366,9 @@ export class StagehandFacadeTools {
           if (error.code !== "EEXIST") throw error;
         });
         if (!(await fsp.lstat(directory)).isDirectory()) {
-          throw new Error("Screenshot artifact directory must not be a symlink.");
+          throw new StagehandFacadeInputError(
+            "Screenshot artifact directory must not be a symlink.",
+          );
         }
       }
       const file = await fsp.open(
@@ -384,7 +429,7 @@ export class StagehandFacadeTools {
 
   private enqueue<Result>(_tool: string, operation: () => Promise<Result>): Promise<Result> {
     const execute = async (): Promise<Result> => {
-      if (this.closed) throw new Error("Stagehand facade browser is closed.");
+      if (this.closed) throw new StagehandFacadeInputError("Stagehand facade browser is closed.");
       await this.ensureKeeperPage();
       return operation();
     };
 
@@ -3,7 +3,11 @@ import os from "node:os";
 import path from "node:path";
 import { type Stagehand } from "@browserbasehq/stagehand";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { StagehandFacadeTools, type StagehandFacadeRunReport } from "../src/facade/tools.js";
+import {
+  StagehandFacadeCleanupError,
+  StagehandFacadeTools,
+  type StagehandFacadeRunReport,
+} from "../src/facade/tools.js";
 
 type FakePage = ReturnType<typeof createFakePage>;
 
@@ -253,9 +257,10 @@ describe("StagehandFacadeTools.run (Playwright batch surface)", () => {
     const { stagehand } = createFakeStagehand(createFakePage());
     vi.mocked(stagehand.close).mockRejectedValue(new Error("apiKey=private-key"));
     const tools = new StagehandFacadeTools(stagehand);
-    await expect(tools.run(`await browser.close();`)).rejects.toThrow(
-      "Failed to close the Stagehand facade browser.",
-    );
+    const error = await tools.run(`await browser.close();`).catch((error: unknown) => error);
+    expect(error).toBeInstanceOf(StagehandFacadeCleanupError);
+    expect((error as Error).cause).toBeUndefined();
+    expect(String(error)).not.toContain("private-key");
     expect(stagehand.browser.close).toHaveBeenCalledOnce();
     await expect(tools.run("return 1")).rejects.toThrow("browser is closed");
   });
@@ -269,6 +274,26 @@ describe("StagehandFacadeTools.run (Playwright batch surface)", () => {
     expect(stagehand.browser.close).toHaveBeenCalledOnce();
   });
 
+  it.each([false, true])(
+    "sanitizes default browser cleanup errors (execution failure: %s)",
+    async (executionFails) => {
+      const { stagehand } = createFakeStagehand(createFakePage());
+      vi.mocked(stagehand.browser.close).mockRejectedValue(new Error("provider-private-detail"));
+      const tools = new StagehandFacadeTools(stagehand);
+      const code = `await browser.close(); ${executionFails ? 'throw new Error("agent failure");' : ""}`;
+      const error = await tools.run(code).catch((error: unknown) => error);
+      const cleanupError = error instanceof AggregateError ? error.errors[1] : error;
+
+      expect(cleanupError).toBeInstanceOf(StagehandFacadeCleanupError);
+      expect(cleanupError.cause).toBeUndefined();
+      expect(String(cleanupError)).not.toContain("provider-private-detail");
+      if (executionFails) {
+        expect(error).toBeInstanceOf(AggregateError);
+        expect((error as AggregateError).errors[0]).toMatchObject({ message: "agent failure" });
+      }
+    },
+  );
+
   it("confines artifacts across traversal, absolute paths, and symlinks", async () => {
     const root = await fsp.mkdtemp(path.join(os.tmpdir(), "facade-paths-"));
     tempDirs.push(root);
@@ -640,3 +665,62 @@ describe("StagehandFacadeTools.run frameLocator", () => {
     );
   });
 });
+
+describe("host-owned facade cleanup", () => {
+  it("awaits the host once and leaves browser ownership with it", async () => {
+    const { stagehand } = createFakeStagehand(createFakePage());
+    let finishCleanup!: () => void;
+    const cleanup = new Promise<void>((resolve) => {
+      finishCleanup = resolve;
+    });
+    const onCloseRequested = vi.fn(() => cleanup);
+    const tools = new StagehandFacadeTools(stagehand, { onCloseRequested });
+    let finished = false;
+    const run = tools.run('await browser.close(); return "closed";').then((result) => {
+      finished = true;
+      return result;
+    });
+    await vi.waitFor(() => expect(onCloseRequested).toHaveBeenCalledOnce());
+    expect(finished).toBe(false);
+    expect(stagehand.close).not.toHaveBeenCalled();
+    expect(stagehand.browser.close).not.toHaveBeenCalled();
+    finishCleanup();
+    await expect(run).resolves.toBe("closed");
+    await tools.close();
+    expect(onCloseRequested).toHaveBeenCalledOnce();
+  });
+
+  it("preserves the model error and a sanitized cleanup failure", async () => {
+    const { stagehand } = createFakeStagehand(createFakePage());
+    const tools = new StagehandFacadeTools(stagehand, {
+      onCloseRequested: async () => {
+        throw new Error("release bb_live_1234secret failed");
+      },
+    });
+    const error = await tools
+      .run('await browser.close(); throw new TypeError("model sk-123456secret failed");')
+      .catch((error: unknown) => error);
+    expect(error).toBeInstanceOf(AggregateError);
+    if (!(error instanceof AggregateError)) throw new Error("Expected aggregate failure");
+    expect(error.errors[0]).toMatchObject({
+      name: "TypeError",
+      message: "model sk-123456[redacted] failed",
+      facadeExecutionError: true,
+      stack: undefined,
+    });
+    expect(error.errors[1]).toBeInstanceOf(StagehandFacadeCleanupError);
+    expect(error.errors.map(String).join(" ")).not.toContain("secret");
+  });
+
+  it("sanitizes a model-authored error name without treating it as session loss", async () => {
+    const { stagehand } = createFakeStagehand(createFakePage());
+    const tools = new StagehandFacadeTools(stagehand);
+    const error = await tools
+      .run(
+        'const error = new Error("model failure"); error.name = "Bearer abcdefghijkl"; throw error;',
+      )
+      .catch((error: unknown) => error);
+    expect(error).toMatchObject({ name: "Error", facadeExecutionError: true, stack: undefined });
+    expect(stagehand.browser.close).not.toHaveBeenCalled();
+  });
+});
@@ -3,7 +3,9 @@ import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { createPlaywrightCompatRuntime } from "../src/facade/runtime.js";
 
-const playwrightRequire = createRequire(import.meta.url);
+const playwrightRequire = createRequire(
+  createRequire(import.meta.url).resolve("playwright/package.json"),
+);
 const playwrightCore = path.dirname(playwrightRequire.resolve("playwright-core/package.json"));
 const { urlMatches } = playwrightRequire(
   path.join(playwrightCore, "lib/utils/isomorphic/urlMatch.js"),
 
@@ -1,2 +1,12 @@
-.eve/
-.output/
+node_modules
+.env
+.env.*
+!.env.example
+.eve
+.vercel
+.output
+.nitro
+dist
+extension/lib/core
+.DS_Store
+*.tsbuildinfo
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@browserbasehq/eve": minor
 +---
++
 +Replace the Eve extension's browser and web tools with Stagehand V4 `run`, `snapshot`, and `screenshot`.