Share perform helper dispatch across replay paths

Co-authored-by: Shri Sukhani <shrisukhani@users.noreply.github.com>

Author: cursoragent

src/agent/index.ts

@@ -60,7 +60,11 @@ import { setDebugOptions } from "@/debug/options";
 import { initializeRuntimeContext } from "./shared/runtime-context";
 import { performAction } from "./actions/shared/perform-action";
 import { createScriptFromActionCache } from "./shared/action-cache-script";
-import { attachCachedActionHelpers } from "./shared/action-cache-exec";
+import {
+  attachCachedActionHelpers,
+  dispatchPerformHelper,
+  isPageActionMethod,
+} from "./shared/action-cache-exec";
 import { AgentDeps } from "@/types/agent/types";
 import { parseExtractOutput } from "./shared/parse-extract-output";
 import { executeReplaySpecialAction } from "./shared/replay-special-actions";
@@ -603,66 +607,6 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
       return finalSuccess;
     };
 
-    /**
-     * Type-safe dispatch for HyperPage perform* methods.
-     * Explicitly routes to the correct method with proper typing.
-     *
-     * Methods that require a value argument (second param): type, fill, press, selectOptionFromDropdown, scrollToPercentage
-     * Methods with only xpath and options: click, hover, check, uncheck, scrollToElement, nextChunk, prevChunk
-     */
-    const dispatchPerformHelper = (
-      hp: HyperPage,
-      method: string,
-      xpath: string,
-      value: string | undefined,
-      options: PerformOptions
-    ): Promise<TaskOutput> => {
-      switch (method) {
-        case "click":
-          return hp.performClick(xpath, options);
-        case "hover":
-          return hp.performHover(xpath, options);
-        case "type":
-          return hp.performType(xpath, value ?? "", options);
-        case "fill":
-          return hp.performFill(xpath, value ?? "", options);
-        case "press":
-          return hp.performPress(xpath, value ?? "", options);
-        case "selectOptionFromDropdown":
-          return hp.performSelectOption(xpath, value ?? "", options);
-        case "check":
-          return hp.performCheck(xpath, options);
-        case "uncheck":
-          return hp.performUncheck(xpath, options);
-        case "scrollToElement":
-          return hp.performScrollToElement(xpath, options);
-        case "scrollToPercentage":
-          return hp.performScrollToPercentage(xpath, value ?? "", options);
-        case "nextChunk":
-          return hp.performNextChunk(xpath, options);
-        case "prevChunk":
-          return hp.performPrevChunk(xpath, options);
-        default:
-          throw new Error(`Unknown perform helper method: ${method}`);
-      }
-    };
-
-    /** Set of valid method names that can be dispatched */
-    const validHelperMethods = new Set([
-      "click",
-      "fill",
-      "type",
-      "press",
-      "selectOptionFromDropdown",
-      "check",
-      "uncheck",
-      "hover",
-      "scrollToElement",
-      "scrollToPercentage",
-      "nextChunk",
-      "prevChunk",
-    ]);
-
     for (const step of [...cache.steps].sort(
       (a, b) => a.stepIndex - b.stepIndex
     )) {
@@ -682,7 +626,7 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
         result = replaySpecialResult;
       } else {
         const method = step.method;
-        if (method && validHelperMethods.has(method)) {
+        if (method && isPageActionMethod(method)) {
           const xpath = step.xpath;
           const hasXPath =
             typeof xpath === "string" && xpath.trim().length > 0;

src/agent/shared/action-cache-exec.test.ts

@@ -0,0 +1,57 @@
+import {
+  dispatchPerformHelper,
+  isPageActionMethod,
+} from "@/agent/shared/action-cache-exec";
+import type { HyperPage } from "@/types/agent/types";
+
+function createMockHyperPage(): HyperPage {
+  const ok = Promise.resolve({
+    taskId: "task-id",
+    status: "completed",
+    steps: [],
+    output: "ok",
+  });
+  return {
+    performClick: jest.fn().mockReturnValue(ok),
+    performHover: jest.fn().mockReturnValue(ok),
+    performType: jest.fn().mockReturnValue(ok),
+    performFill: jest.fn().mockReturnValue(ok),
+    performPress: jest.fn().mockReturnValue(ok),
+    performSelectOption: jest.fn().mockReturnValue(ok),
+    performCheck: jest.fn().mockReturnValue(ok),
+    performUncheck: jest.fn().mockReturnValue(ok),
+    performScrollToElement: jest.fn().mockReturnValue(ok),
+    performScrollToPercentage: jest.fn().mockReturnValue(ok),
+    performNextChunk: jest.fn().mockReturnValue(ok),
+    performPrevChunk: jest.fn().mockReturnValue(ok),
+  } as unknown as HyperPage;
+}
+
+describe("action-cache perform helper dispatch", () => {
+  it("validates known page action methods", () => {
+    expect(isPageActionMethod("click")).toBe(true);
+    expect(isPageActionMethod("not-a-method")).toBe(false);
+  });
+
+  it("dispatches fill with value argument", async () => {
+    const page = createMockHyperPage();
+    const options = { maxSteps: 2 };
+
+    await dispatchPerformHelper(page, "fill", "//input[1]", "hello", options);
+
+    expect(page.performFill).toHaveBeenCalledWith("//input[1]", "hello", {
+      maxSteps: 2,
+    });
+  });
+
+  it("dispatches click without value argument", async () => {
+    const page = createMockHyperPage();
+    const options = { maxSteps: 1 };
+
+    await dispatchPerformHelper(page, "click", "//button[1]", undefined, options);
+
+    expect(page.performClick).toHaveBeenCalledWith("//button[1]", {
+      maxSteps: 1,
+    });
+  });
+});

src/agent/shared/action-cache-exec.ts

@@ -1,26 +1,77 @@
-import { AgentDeps, HyperPage, TaskOutput } from "@/types/agent/types";
+import {
+  AgentDeps,
+  HyperPage,
+  PerformOptions,
+  TaskOutput,
+} from "@/types/agent/types";
 import * as cachedRunner from "./run-cached-action";
 
 const DEFAULT_MAX_STEPS = 3;
 
-type PageAction =
-  | "click"
-  | "fill"
-  | "type"
-  | "press"
-  | "selectOptionFromDropdown"
-  | "check"
-  | "uncheck"
-  | "hover"
-  | "scrollToElement"
-  | "scrollToPercentage"
-  | "nextChunk"
-  | "prevChunk";
-
-interface PerformOptions {
-  frameIndex?: number | null;
-  performInstruction?: string | null;
-  maxSteps?: number;
+export const PAGE_ACTION_METHODS = [
+  "click",
+  "fill",
+  "type",
+  "press",
+  "selectOptionFromDropdown",
+  "check",
+  "uncheck",
+  "hover",
+  "scrollToElement",
+  "scrollToPercentage",
+  "nextChunk",
+  "prevChunk",
+] as const;
+
+type Includes<T extends readonly string[]> = (
+  haystack: readonly string[],
+  needle: string
+) => needle is T[number];
+
+const includes = ((haystack: readonly string[], needle: string): boolean =>
+  haystack.includes(needle)) as Includes<typeof PAGE_ACTION_METHODS>;
+
+export type PageAction = (typeof PAGE_ACTION_METHODS)[number];
+
+export function isPageActionMethod(method: string): method is PageAction {
+  return includes(PAGE_ACTION_METHODS, method);
+}
+
+export function dispatchPerformHelper(
+  hp: HyperPage,
+  method: PageAction,
+  xpath: string,
+  value: string | undefined,
+  options: PerformOptions
+): Promise<TaskOutput> {
+  switch (method) {
+    case "click":
+      return hp.performClick(xpath, options);
+    case "hover":
+      return hp.performHover(xpath, options);
+    case "type":
+      return hp.performType(xpath, value ?? "", options);
+    case "fill":
+      return hp.performFill(xpath, value ?? "", options);
+    case "press":
+      return hp.performPress(xpath, value ?? "", options);
+    case "selectOptionFromDropdown":
+      return hp.performSelectOption(xpath, value ?? "", options);
+    case "check":
+      return hp.performCheck(xpath, options);
+    case "uncheck":
+      return hp.performUncheck(xpath, options);
+    case "scrollToElement":
+      return hp.performScrollToElement(xpath, options);
+    case "scrollToPercentage":
+      return hp.performScrollToPercentage(xpath, value ?? "", options);
+    case "nextChunk":
+      return hp.performNextChunk(xpath, options);
+    case "prevChunk":
+      return hp.performPrevChunk(xpath, options);
+    default:
+      throw new Error(`Unknown perform helper method: ${method}`);
+  }
 }
 
 function runCachedAction(