fix(webAgent): refresh snapshot after a stale-ref tool error

On a recoverable "Invalid element reference" error the loop returned
needsPageSnapshot:false, so no fresh snapshot was ever added — the model was
stranded on a known-bad snapshot. The recovery prompt tells the model to "wait
for the next page snapshot (it will arrive automatically)"; it never did, so the
model confabulated refs off a frozen view until the consecutive-error budget
killed the run. Observed on Magento (Zoo onestopshop) guest checkout, but the
deadlock is general to any recoverable ref error on a client-rendered page.

Force a snapshot refresh on the retry only for stale/invalid-ref errors (the one
case where the model's view is known-bad and the prompt promised a refresh);
other recoverable errors keep prior behavior. The existing consecutive-error
budget bounds any refresh loop. Scoped via shouldRefreshSnapshotAfterError,
which keys on the same phrase prompts.ts uses.

Validated: with this refresh, checkout reps that threw 7-15 invalid-ref errors
recover and pass instead of deadlocking at 5 consecutive.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: lmorchard

packages/core/src/webAgent.ts

@@ -276,6 +276,24 @@ export function hasInteractiveRefs(tree: string): boolean {
   return INTERACTIVE_REF_RE.test(tree);
 }
 
+// A stale/invalid element ref means the DOM changed under the agent and its
+// cached refs are gone. This is the exact phrase the recovery prompt keys on
+// (see prompts.ts — "Invalid element reference … does not exist on the current
+// page"); keep the two in sync.
+const STALE_REF_ERROR_RE = /invalid element reference|does not exist on the current page/i;
+
+/**
+ * After a recoverable tool error, decide whether to force a page-snapshot
+ * refresh on the retry. Only a stale/invalid-ref error warrants it: that is the
+ * one case where the model's cached snapshot is known-bad, and the recovery
+ * prompt has already promised the model a fresh snapshot will arrive. Other
+ * recoverable errors keep the prior behavior (no forced refresh). The loop's
+ * consecutive-error budget bounds any refresh loop.
+ */
+export function shouldRefreshSnapshotAfterError(error: unknown): boolean {
+  return error instanceof Error && STALE_REF_ERROR_RE.test(error.message);
+}
+
 /**
  * Simplified WebAgent with core execution logic
  */
@@ -799,9 +817,18 @@ export class WebAgent {
               };
             }
 
-            // Add error feedback and retry
+            // Add error feedback and retry. On a stale/invalid-ref error the
+            // model's cached snapshot is known-bad and the recovery prompt has
+            // promised it a fresh one, so force a snapshot refresh; otherwise
+            // keep the prior no-refresh behavior. Without this, a recoverable
+            // ref error strands the agent on a frozen snapshot — it "waits" for
+            // a refresh that never comes and confabulates refs until the
+            // consecutive-error budget kills the run.
             this.addErrorFeedback(error);
-            return { flow: "next" as const, needsPageSnapshot: false };
+            return {
+              flow: "next" as const,
+              needsPageSnapshot: shouldRefreshSnapshotAfterError(error),
+            };
           }
         },
       );

packages/core/test/webAgent.test.ts

@@ -1,5 +1,10 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { WebAgent, WebAgentOptions, hasInteractiveRefs } from "../src/webAgent.js";
+import {
+  WebAgent,
+  WebAgentOptions,
+  hasInteractiveRefs,
+  shouldRefreshSnapshotAfterError,
+} from "../src/webAgent.js";
 import { InvalidHostnameError } from "../src/security/actionFirewall.js";
 import {
   AriaBrowser,
@@ -12,7 +17,12 @@ import { WebAgentEventEmitter, WebAgentEventType } from "../src/events.js";
 import { LanguageModel, streamText } from "ai";
 import { Logger } from "../src/loggers/types.js";
 import { generateTextWithRetry } from "../src/utils/retry.js";
-import { PlanningError, BrowserDisconnectedError } from "../src/errors.js";
+import {
+  PlanningError,
+  BrowserDisconnectedError,
+  ToolExecutionError,
+  InvalidRefException,
+} from "../src/errors.js";
 import {
   wrapExternalContentWithWarning,
   ExternalContentLabel,
@@ -5128,3 +5138,35 @@ describe("hasInteractiveRefs (SPA snapshot readiness guard)", () => {
     expect(hasInteractiveRefs(`- 'button "Save: now" [ref=E1]'`)).toBe(true);
   });
 });
+
+describe("shouldRefreshSnapshotAfterError (recover from stale refs)", () => {
+  it("refreshes on an InvalidRefException (the stale-ref signal)", () => {
+    expect(shouldRefreshSnapshotAfterError(new InvalidRefException("E44"))).toBe(true);
+  });
+
+  it("refreshes on a ToolExecutionError carrying the invalid-ref message", () => {
+    // This is the actual type on the recoverable-error retry path: webActionTools
+    // catches the BrowserException and re-throws it as a ToolExecutionError.
+    const err = new ToolExecutionError(
+      "Invalid element reference 'E44'. The element does not exist on the current page.",
+      { action: "fill", ref: "E44" },
+    );
+    expect(shouldRefreshSnapshotAfterError(err)).toBe(true);
+  });
+
+  it("matches the 'does not exist on the current page' phrasing", () => {
+    expect(
+      shouldRefreshSnapshotAfterError(new Error("Element does not exist on the current page")),
+    ).toBe(true);
+  });
+
+  it("does NOT refresh on an unrelated recoverable tool error", () => {
+    const err = new ToolExecutionError("Click timed out after 5000ms", { action: "click" });
+    expect(shouldRefreshSnapshotAfterError(err)).toBe(false);
+  });
+
+  it("does not throw on non-Error values", () => {
+    expect(shouldRefreshSnapshotAfterError(undefined)).toBe(false);
+    expect(shouldRefreshSnapshotAfterError("Invalid element reference 'E1'")).toBe(false);
+  });
+});