refactor(cli): migrate Browse runtime and commands to Stagehand V4

packages/cli/src/lib/driver/commands/elements.ts

@@ -7,13 +7,8 @@ export const elementsHandlers: DriverCommandHandlers = {
     const { selector } = z
       .object({ selector: z.string().min(1) })
       .parse(params);
-    const stagehand = await manager.stagehandInstance();
-    await stagehand.act({
-      arguments: [],
-      description: "click element",
-      method: "click",
-      selector: manager.resolveSelector(selector),
-    } as never);
+    const page = await manager.activePage();
+    await page.locator(manager.resolveSelector(selector)).click();
     return { clicked: true };
   },
 
@@ -25,15 +20,9 @@ export const elementsHandlers: DriverCommandHandlers = {
         value: z.string(),
       })
       .parse(params);
-    const stagehand = await manager.stagehandInstance();
-    await stagehand.act({
-      arguments: [value],
-      description: "fill element",
-      method: "fill",
-      selector: manager.resolveSelector(selector),
-    } as never);
+    const page = await manager.activePage();
+    await page.locator(manager.resolveSelector(selector)).fill(value);
     if (pressEnter) {
-      const page = await manager.activePage();
       await page.keyPress("Enter");
     }
     return { filled: true, pressedEnter: pressEnter ?? false };
@@ -48,7 +37,7 @@ export const elementsHandlers: DriverCommandHandlers = {
       .parse(params);
     const page = await manager.activePage();
     const selected = await page
-      .deepLocator(manager.resolveSelector(selector))
+      .locator(manager.resolveSelector(selector))
       .selectOption(values);
     return { selected };
   },
@@ -61,9 +50,7 @@ export const elementsHandlers: DriverCommandHandlers = {
       })
       .parse(params);
     const page = await manager.activePage();
-    await page
-      .deepLocator(manager.resolveSelector(selector))
-      .setInputFiles(files.length === 1 ? files[0]! : files);
+    await page.locator(manager.resolveSelector(selector)).setInputFiles(files);
     return { files, uploaded: true };
   },
 
@@ -76,7 +63,7 @@ export const elementsHandlers: DriverCommandHandlers = {
       .parse(params);
     const page = await manager.activePage();
     await page
-      .deepLocator(manager.resolveSelector(selector))
+      .locator(manager.resolveSelector(selector))
       .highlight({ durationMs: durationMs ?? 2000 });
     return { highlighted: true };
   },

packages/cli/src/lib/driver/commands/keyboard.ts

@@ -12,7 +12,14 @@ export const keyboardHandlers: DriverCommandHandlers = {
       })
       .parse(params);
     const page = await manager.activePage();
-    await page.type(text, { delay, withMistakes: mistakes });
+    const options = {
+      ...(delay === undefined ? {} : { delay }),
+      ...(mistakes === undefined ? {} : { withMistakes: mistakes }),
+    };
+    await page.type(
+      text,
+      Object.keys(options).length === 0 ? undefined : options,
+    );
     return { typed: true };
   },
 

packages/cli/src/lib/driver/commands/mouse.ts

@@ -15,13 +15,13 @@ export const mouseHandlers: DriverCommandHandlers = {
         y: z.number(),
       })
       .parse(params);
+    assertXPathUnavailable(returnXPath);
     const page = await manager.activePage();
-    const xpath = await page.click(x, y, {
-      button,
-      clickCount,
-      returnXpath: returnXPath,
+    await page.click(x, y, {
+      ...(button === undefined ? {} : { button }),
+      ...(clickCount === undefined ? {} : { clickCount }),
     });
-    return returnXPath ? { clicked: true, xpath } : { clicked: true };
+    return { clicked: true };
   },
 
   async "mouse.hover"(manager, params) {
@@ -32,9 +32,10 @@ export const mouseHandlers: DriverCommandHandlers = {
         y: z.number(),
       })
       .parse(params);
+    assertXPathUnavailable(returnXPath);
     const page = await manager.activePage();
-    const xpath = await page.hover(x, y, { returnXpath: returnXPath });
-    return returnXPath ? { hovered: true, xpath } : { hovered: true };
+    await page.hover(x, y);
+    return { hovered: true };
   },
 
   async "mouse.scroll"(manager, params) {
@@ -47,11 +48,10 @@ export const mouseHandlers: DriverCommandHandlers = {
         y: z.number(),
       })
       .parse(params);
+    assertXPathUnavailable(returnXPath);
     const page = await manager.activePage();
-    const xpath = await page.scroll(x, y, deltaX, deltaY, {
-      returnXpath: returnXPath,
-    });
-    return returnXPath ? { scrolled: true, xpath } : { scrolled: true };
+    await page.scroll(x, y, deltaX, deltaY);
+    return { scrolled: true };
   },
 
   async "mouse.drag"(manager, params) {
@@ -67,21 +67,19 @@ export const mouseHandlers: DriverCommandHandlers = {
         toY: z.number(),
       })
       .parse(params);
+    assertXPathUnavailable(returnXPath);
     const page = await manager.activePage();
-    const [fromXpath, toXpath] = await page.dragAndDrop(
-      fromX,
-      fromY,
-      toX,
-      toY,
-      {
-        button,
-        delay,
-        returnXpath: returnXPath,
-        steps,
-      },
-    );
-    return returnXPath
-      ? { dragged: true, fromXpath, toXpath, xpath: fromXpath }
-      : { dragged: true };
+    await page.dragAndDrop(fromX, fromY, toX, toY, {
+      ...(button === undefined ? {} : { button }),
+      ...(delay === undefined ? {} : { delay }),
+      ...(steps === undefined ? {} : { steps }),
+    });
+    return { dragged: true };
   },
 };
+
+function assertXPathUnavailable(returnXPath: boolean | undefined): void {
+  if (returnXPath) {
+    throw new Error("Coordinate XPath lookup is not exposed by Stagehand V4");
+  }
+}

packages/cli/src/lib/driver/commands/navigation.ts

@@ -18,28 +18,38 @@ export const navigationHandlers: DriverCommandHandlers = {
   async open(manager, params) {
     const { timeoutMs, url, waitUntil } = OpenSchema.parse(params);
     const page = await manager.pageForOpen();
-    await page.goto(url, { timeoutMs, waitUntil });
+    await page.goto(url, pageNavigationOptions({ timeoutMs, waitUntil }));
     return manager.openResult(page);
   },
 
   async reload(manager, params) {
     const options = NavigationOptionsSchema.parse(params);
     const page = await manager.activePage();
-    await page.reload(options);
+    await page.reload(pageNavigationOptions(options));
     return manager.openResult(page);
   },
 
   async back(manager, params) {
     const options = NavigationOptionsSchema.parse(params);
     const page = await manager.activePage();
-    await page.goBack(options);
+    await page.goBack(pageNavigationOptions(options));
     return manager.openResult(page);
   },
 
   async forward(manager, params) {
     const options = NavigationOptionsSchema.parse(params);
     const page = await manager.activePage();
-    await page.goForward(options);
+    await page.goForward(pageNavigationOptions(options));
     return manager.openResult(page);
   },
 };
+
+function pageNavigationOptions({
+  timeoutMs,
+  waitUntil,
+}: z.infer<typeof NavigationOptionsSchema>) {
+  return {
+    ...(timeoutMs === undefined ? {} : { timeout: timeoutMs }),
+    ...(waitUntil === undefined ? {} : { waitUntil }),
+  };
+}

packages/cli/src/lib/driver/commands/page-info.ts

@@ -25,11 +25,11 @@ export const pageInfoHandlers: DriverCommandHandlers = {
       .parse(params);
     const page = await manager.activePage();
 
-    if (what === "url") return { url: page.url() };
+    if (what === "url") return { url: await page.url() };
     if (what === "title") return { title: await page.title() };
 
     const target = manager.resolveSelector(selector ?? "body");
-    const locator = page.deepLocator(target);
+    const locator = page.locator(target);
 
     if (what === "text") return { text: await locator.textContent() };
     if (what === "html") return { html: await locator.innerHtml() };
@@ -53,7 +53,7 @@ export const pageInfoHandlers: DriverCommandHandlers = {
       })
       .parse(params);
     const page = await manager.activePage();
-    const locator = page.deepLocator(manager.resolveSelector(selector));
+    const locator = page.locator(manager.resolveSelector(selector));
     return check === "visible"
       ? { visible: await locator.isVisible() }
       : { checked: await locator.isChecked() };

packages/cli/src/lib/driver/commands/runtime.ts

@@ -3,6 +3,7 @@ import { promises as fs } from "node:fs";
 import { z } from "zod";
 
 import type { DriverCommandHandlers } from "./types.js";
+import { unavailableCursorOverlay } from "./unavailable.js";
 
 export const runtimeHandlers: DriverCommandHandlers = {
   async screenshot(manager, params) {
@@ -26,19 +27,21 @@ export const runtimeHandlers: DriverCommandHandlers = {
       .parse(params);
     const page = await manager.activePage();
     const buffer = await page.screenshot({
-      animations: options.animations,
-      caret: options.caret,
-      clip: options.clip,
-      fullPage: options.fullPage,
-      quality: options.quality,
+      ...(options.animations === undefined
+        ? {}
+        : { animations: options.animations }),
+      ...(options.caret === undefined ? {} : { caret: options.caret }),
+      ...(options.clip === undefined ? {} : { clip: options.clip }),
+      ...(options.fullPage === undefined ? {} : { fullPage: options.fullPage }),
+      ...(options.quality === undefined ? {} : { quality: options.quality }),
       timeout: 10_000,
-      type: options.type,
+      ...(options.type === undefined ? {} : { type: options.type }),
     });
     if (options.path) {
       await fs.writeFile(options.path, buffer);
       return { saved: options.path };
     }
-    return { base64: buffer.toString("base64") };
+    return { base64: Buffer.from(buffer).toString("base64") };
   },
 
   async viewport(manager, params) {
@@ -86,11 +89,7 @@ export const runtimeHandlers: DriverCommandHandlers = {
     return { waited: true };
   },
 
-  async cursor(manager) {
-    const page = await manager.activePage();
-    await page.enableCursorOverlay();
-    return { cursor: "enabled" };
-  },
+  cursor: unavailableCursorOverlay,
 };
 
 function parseTimeoutMs(value: string | undefined): number {