Harden action-cache replay when cached XPath is missing

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

Author: cursoragent

src/agent/__tests__/run-from-action-cache.test.ts

@@ -0,0 +1,105 @@
+import { HyperAgent } from "@/agent";
+import { TaskStatus, type ActionCacheOutput } from "@/types/agent/types";
+import type { HyperAgentLLM } from "@/llm/types";
+
+function createMockLLM(): HyperAgentLLM {
+  return {
+    invoke: async () => ({ role: "assistant", content: "ok" }),
+    invokeStructured: async () => ({ rawText: "{}", parsed: null }),
+    getProviderId: () => "mock",
+    getModelId: () => "mock-model",
+    getCapabilities: () => ({
+      multimodal: false,
+      toolCalling: true,
+      jsonMode: true,
+    }),
+  };
+}
+
+describe("runFromActionCache hardening", () => {
+  it("falls back to instruction perform when helper method cache lacks xpath", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const perform = jest.fn().mockResolvedValue({
+      taskId: "perform-task",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "performed via instruction",
+      replayStepMeta: {
+        usedCachedAction: false,
+        fallbackUsed: true,
+        retries: 1,
+        cachedXPath: null,
+        fallbackXPath: "/html/body/button[1]",
+        fallbackElementId: "0-1",
+      },
+    });
+    const performClick = jest.fn();
+
+    const page = {
+      perform,
+      performClick,
+    } as unknown as import("@/types/agent/types").HyperPage;
+
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "click login",
+          elementId: "0-1",
+          method: "click",
+          arguments: [],
+          frameIndex: 0,
+          xpath: null,
+          actionType: "actElement",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(perform).toHaveBeenCalledWith("click login");
+    expect(performClick).not.toHaveBeenCalled();
+    expect(replay.status).toBe(TaskStatus.COMPLETED);
+    expect(replay.steps[0]?.usedXPath).toBe(false);
+  });
+
+  it("fails fast when method cache lacks both xpath and instruction", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const page = {} as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: undefined,
+          elementId: "0-1",
+          method: "click",
+          arguments: [],
+          frameIndex: 0,
+          xpath: null,
+          actionType: "actElement",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(replay.status).toBe(TaskStatus.FAILED);
+    expect(replay.steps[0]?.message).toContain("without XPath or instruction");
+  });
+});

src/agent/index.ts

@@ -777,6 +777,54 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
       } else {
         const method = step.method;
         if (method && validHelperMethods.has(method)) {
+          const xpath = step.xpath;
+          const hasXPath =
+            typeof xpath === "string" && xpath.trim().length > 0;
+          if (!hasXPath) {
+            if (step.instruction) {
+              result = await hyperPage.perform(step.instruction);
+            } else {
+              result = {
+                taskId: cache.taskId,
+                status: TaskStatus.FAILED,
+                steps: [],
+                output: `Cannot replay action type "${step.actionType}" with method "${method}" without XPath or instruction`,
+                replayStepMeta: {
+                  usedCachedAction: false,
+                  fallbackUsed: false,
+                  retries: 0,
+                  cachedXPath: null,
+                  fallbackXPath: null,
+                  fallbackElementId: null,
+                },
+              };
+            }
+            const finalMeta = result.replayStepMeta;
+            const finalSuccess = result.status === TaskStatus.COMPLETED;
+
+            stepsResult.push({
+              stepIndex: step.stepIndex,
+              actionType: step.actionType,
+              usedXPath: finalMeta?.usedCachedAction ?? false,
+              fallbackUsed: finalMeta?.fallbackUsed ?? false,
+              cachedXPath: finalMeta?.cachedXPath ?? null,
+              fallbackXPath: finalMeta?.fallbackXPath ?? null,
+              fallbackElementId: finalMeta?.fallbackElementId ?? null,
+              retries: finalMeta?.retries ?? 0,
+              success: finalSuccess,
+              message:
+                result.output ||
+                (finalSuccess
+                  ? "Completed"
+                  : "Failed to execute cached action"),
+            });
+
+            if (!finalSuccess) {
+              replayStatus = TaskStatus.FAILED;
+              break;
+            }
+            continue;
+          }
           const options: PerformOptions = {
             performInstruction: step.instruction ?? null,
             maxSteps: maxXPathRetries,
@@ -788,7 +836,7 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
           result = await dispatchPerformHelper(
             hyperPage,
             method,
-            step.xpath ?? "",
+            xpath,
             valueArg,
             options
           );