refactor(cli): restore Stagehand V4 command parity

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

@@ -1,10 +1,70 @@
+import { z } from "zod";
+
 import type { DriverCommandHandlers } from "./types.js";
-import { unavailableV4Command } from "./unavailable.js";
 
 export const elementsHandlers: DriverCommandHandlers = {
-  click: unavailableV4Command("click"),
-  fill: unavailableV4Command("fill"),
-  highlight: unavailableV4Command("highlight"),
-  select: unavailableV4Command("select"),
-  upload: unavailableV4Command("upload"),
+  async click(manager, params) {
+    const { selector } = z
+      .object({ selector: z.string().min(1) })
+      .parse(params);
+    const page = await manager.activePage();
+    await page.locator(manager.resolveSelector(selector)).click();
+    return { clicked: true };
+  },
+
+  async fill(manager, params) {
+    const { pressEnter, selector, value } = z
+      .object({
+        pressEnter: z.boolean().optional(),
+        selector: z.string().min(1),
+        value: z.string(),
+      })
+      .parse(params);
+    const page = await manager.activePage();
+    await page.locator(manager.resolveSelector(selector)).fill(value);
+    if (pressEnter) {
+      await page.keyPress("Enter");
+    }
+    return { filled: true, pressedEnter: pressEnter ?? false };
+  },
+
+  async select(manager, params) {
+    const { selector, values } = z
+      .object({
+        selector: z.string().min(1),
+        values: z.array(z.string()).min(1),
+      })
+      .parse(params);
+    const page = await manager.activePage();
+    const selected = await page
+      .locator(manager.resolveSelector(selector))
+      .selectOption(values);
+    return { selected };
+  },
+
+  async upload(manager, params) {
+    const { files, selector } = z
+      .object({
+        files: z.array(z.string()).min(1),
+        selector: z.string().min(1),
+      })
+      .parse(params);
+    const page = await manager.activePage();
+    await page.locator(manager.resolveSelector(selector)).setInputFiles(files);
+    return { files, uploaded: true };
+  },
+
+  async highlight(manager, params) {
+    const { durationMs, selector } = z
+      .object({
+        durationMs: z.number().int().positive().optional(),
+        selector: z.string().min(1),
+      })
+      .parse(params);
+    const page = await manager.activePage();
+    await page
+      .locator(manager.resolveSelector(selector))
+      .highlight({ durationMs: durationMs ?? 2000 });
+    return { highlighted: true };
+  },
 };

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

@@ -1,10 +1,27 @@
 import { z } from "zod";
 
 import type { DriverCommandHandlers } from "./types.js";
-import { unavailableV4Command } from "./unavailable.js";
 
 export const keyboardHandlers: DriverCommandHandlers = {
-  type: unavailableV4Command("type"),
+  async type(manager, params) {
+    const { delay, mistakes, text } = z
+      .object({
+        delay: z.number().int().nonnegative().optional(),
+        mistakes: z.boolean().optional(),
+        text: z.string(),
+      })
+      .parse(params);
+    const page = await manager.activePage();
+    const options = {
+      ...(delay === undefined ? {} : { delay }),
+      ...(mistakes === undefined ? {} : { withMistakes: mistakes }),
+    };
+    await page.type(
+      text,
+      Object.keys(options).length === 0 ? undefined : options,
+    );
+    return { typed: true };
+  },
 
   async key(manager, params) {
     const { key } = z.object({ key: z.string().min(1) }).parse(params);

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

@@ -1,9 +1,85 @@
+import { z } from "zod";
+
 import type { DriverCommandHandlers } from "./types.js";
-import { unavailableV4Command } from "./unavailable.js";
+
+const ButtonSchema = z.enum(["left", "right", "middle"]).optional();
 
 export const mouseHandlers: DriverCommandHandlers = {
-  "mouse.click": unavailableV4Command("mouse.click"),
-  "mouse.drag": unavailableV4Command("mouse.drag"),
-  "mouse.hover": unavailableV4Command("mouse.hover"),
-  "mouse.scroll": unavailableV4Command("mouse.scroll"),
+  async "mouse.click"(manager, params) {
+    const { button, clickCount, returnXPath, x, y } = z
+      .object({
+        button: ButtonSchema,
+        clickCount: z.number().int().positive().optional(),
+        returnXPath: z.boolean().optional(),
+        x: z.number(),
+        y: z.number(),
+      })
+      .parse(params);
+    assertXPathUnavailable(returnXPath);
+    const page = await manager.activePage();
+    await page.click(x, y, {
+      ...(button === undefined ? {} : { button }),
+      ...(clickCount === undefined ? {} : { clickCount }),
+    });
+    return { clicked: true };
+  },
+
+  async "mouse.hover"(manager, params) {
+    const { returnXPath, x, y } = z
+      .object({
+        returnXPath: z.boolean().optional(),
+        x: z.number(),
+        y: z.number(),
+      })
+      .parse(params);
+    assertXPathUnavailable(returnXPath);
+    const page = await manager.activePage();
+    await page.hover(x, y);
+    return { hovered: true };
+  },
+
+  async "mouse.scroll"(manager, params) {
+    const { deltaX, deltaY, returnXPath, x, y } = z
+      .object({
+        deltaX: z.number(),
+        deltaY: z.number(),
+        returnXPath: z.boolean().optional(),
+        x: z.number(),
+        y: z.number(),
+      })
+      .parse(params);
+    assertXPathUnavailable(returnXPath);
+    const page = await manager.activePage();
+    await page.scroll(x, y, deltaX, deltaY);
+    return { scrolled: true };
+  },
+
+  async "mouse.drag"(manager, params) {
+    const { button, delay, fromX, fromY, returnXPath, steps, toX, toY } = z
+      .object({
+        button: ButtonSchema,
+        delay: z.number().int().nonnegative().optional(),
+        fromX: z.number(),
+        fromY: z.number(),
+        returnXPath: z.boolean().optional(),
+        steps: z.number().int().positive().optional(),
+        toX: z.number(),
+        toY: z.number(),
+      })
+      .parse(params);
+    assertXPathUnavailable(returnXPath);
+    const page = await manager.activePage();
+    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

@@ -1,7 +1,6 @@
 import { z } from "zod";
 
 import type { DriverCommandHandlers } from "./types.js";
-import { unavailableV4Command } from "./unavailable.js";
 
 const LoadStateSchema = z
   .enum(["load", "domcontentloaded", "networkidle"])
@@ -22,9 +21,27 @@ export const navigationHandlers: DriverCommandHandlers = {
     await page.goto(url, pageNavigationOptions({ timeoutMs, waitUntil }));
     return manager.openResult(page);
   },
-  back: unavailableV4Command("back"),
-  forward: unavailableV4Command("forward"),
-  reload: unavailableV4Command("reload"),
+
+  async reload(manager, params) {
+    const options = NavigationOptionsSchema.parse(params);
+    const page = await manager.activePage();
+    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(pageNavigationOptions(options));
+    return manager.openResult(page);
+  },
+
+  async forward(manager, params) {
+    const options = NavigationOptionsSchema.parse(params);
+    const page = await manager.activePage();
+    await page.goForward(pageNavigationOptions(options));
+    return manager.openResult(page);
+  },
 };
 
 function pageNavigationOptions({

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

@@ -1,11 +1,63 @@
+import { NodeHtmlMarkdown } from "node-html-markdown";
 import { z } from "zod";
 
 import type { DriverCommandHandlers } from "./types.js";
-import { unavailableV4Command } from "./unavailable.js";
+
+const GetWhatSchema = z.enum([
+  "box",
+  "checked",
+  "html",
+  "markdown",
+  "text",
+  "title",
+  "url",
+  "value",
+  "visible",
+]);
 
 export const pageInfoHandlers: DriverCommandHandlers = {
-  get: unavailableV4Command("get"),
-  is: unavailableV4Command("is"),
+  async get(manager, params) {
+    const { selector, what } = z
+      .object({
+        selector: z.string().optional(),
+        what: GetWhatSchema,
+      })
+      .parse(params);
+    const page = await manager.activePage();
+
+    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.locator(target);
+
+    if (what === "text") return { text: await locator.textContent() };
+    if (what === "html") return { html: await locator.innerHtml() };
+    if (what === "value") return { value: await locator.inputValue() };
+    if (what === "visible") return { visible: await locator.isVisible() };
+    if (what === "checked") return { checked: await locator.isChecked() };
+    if (what === "markdown")
+      return {
+        markdown: NodeHtmlMarkdown.translate(await locator.innerHtml()),
+      };
+
+    const { x, y } = await locator.centroid();
+    return { x: Math.round(x), y: Math.round(y) };
+  },
+
+  async is(manager, params) {
+    const { check, selector } = z
+      .object({
+        check: z.enum(["checked", "visible"]),
+        selector: z.string().min(1),
+      })
+      .parse(params);
+    const page = await manager.activePage();
+    const locator = page.locator(manager.resolveSelector(selector));
+    return check === "visible"
+      ? { visible: await locator.isVisible() }
+      : { checked: await locator.isChecked() };
+  },
 
   async eval(manager, params) {
     const { expression } = z

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

@@ -1,13 +1,48 @@
+import { promises as fs } from "node:fs";
+
 import { z } from "zod";
 
 import type { DriverCommandHandlers } from "./types.js";
-import {
-  unavailableCursorOverlay,
-  unavailableV4Command,
-} from "./unavailable.js";
+import { unavailableCursorOverlay } from "./unavailable.js";
 
 export const runtimeHandlers: DriverCommandHandlers = {
-  screenshot: unavailableV4Command("screenshot"),
+  async screenshot(manager, params) {
+    const options = z
+      .object({
+        animations: z.enum(["allow", "disabled"]).optional(),
+        caret: z.enum(["hide", "initial"]).optional(),
+        clip: z
+          .object({
+            height: z.number().positive(),
+            width: z.number().positive(),
+            x: z.number(),
+            y: z.number(),
+          })
+          .optional(),
+        fullPage: z.boolean().optional(),
+        path: z.string().optional(),
+        quality: z.number().int().min(0).max(100).optional(),
+        type: z.enum(["jpeg", "png"]).optional(),
+      })
+      .parse(params);
+    const page = await manager.activePage();
+    const buffer = await page.screenshot({
+      ...(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,
+      ...(options.type === undefined ? {} : { type: options.type }),
+    });
+    if (options.path) {
+      await fs.writeFile(options.path, buffer);
+      return { saved: options.path };
+    }
+    return { base64: Buffer.from(buffer).toString("base64") };
+  },
 
   async viewport(manager, params) {
     const { height, scale, width } = z