Guard waitForSettledDOM frame-manager option setup

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

Author: cursoragent

currentState.md

@@ -121,6 +121,7 @@ HyperAgent exposes a TypeScript SDK for browser automation with three primary pa
 - Added per-invocation frame-filter overrides on `page.ai`, `page.perform`, and replay params so workflows can opt in/out of ad/tracking iframe filtering without constructing a new agent.
 - Synced frame-filter policy into a11y DOM capture setup (`getA11yDOM`/`captureDOMState`) so first-attempt frame discovery uses the active task/action override instead of stale manager state.
 - Hardened per-call frame-filter option reads against trap-prone parameter objects in `executeTask`, `executeTaskAsync`, and `executeSingleAction` (falls back to agent default instead of throwing).
+- Hardened `waitForSettledDOM` frame-manager option setup so debug/filter configuration setter failures are isolated to sanitized warnings instead of aborting settle behavior.
 - Expanded top-level package exports for key workflow/config types at `@hyperbrowser/agent`.
 - Removed stale script entry (`build-dom-tree-script`) and improved README usage docs.
 - Added canonical single-action debug writer helper (`writePerformDebug`) while preserving deprecated alias compatibility.

src/utils/waitForSettledDOM.test.ts

@@ -249,6 +249,54 @@ describe("waitForSettledDOM diagnostics", () => {
     expect(setFrameFilteringEnabled).toHaveBeenCalledWith(false);
   });
 
+  it("continues when frame-filter configuration throws", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const { session } = createSessionWithEvents();
+    const cdpClient: CDPClient = {
+      rootSession: session,
+      createSession: async () => session,
+      acquireSession: async () => session,
+      dispose: async () => undefined,
+    };
+    getCDPClient.mockResolvedValue(cdpClient);
+    getOrCreateFrameContextManager.mockReturnValue({
+      setDebug: jest.fn(),
+      setFrameFilteringEnabled: jest.fn(() => {
+        throw new Error(`filter\u0000\n${"x".repeat(2_000)}`);
+      }),
+    });
+    getDebugOptions.mockReturnValue({
+      enabled: false,
+      traceWait: false,
+    });
+
+    const page = {
+      context: () => ({}),
+    } as never;
+
+    try {
+      const waitPromise = waitForSettledDOM(page, 600, {
+        filterAdTrackingFrames: false,
+      });
+      await Promise.resolve();
+      await Promise.resolve();
+      await jest.advanceTimersByTimeAsync(700);
+      const stats = await waitPromise;
+
+      expect(stats.resolvedByTimeout).toBe(false);
+      const warning = String(
+        warnSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("configure frame filtering")
+        )?.[0] ?? ""
+      );
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
   it("falls back to timeout when network listener registration fails", async () => {
     const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
     const { session } = createSessionWithEvents({

src/utils/waitForSettledDOM.ts

@@ -172,12 +172,28 @@ export async function waitForSettledDOM(
 
   const cdpClient = await getCDPClient(page);
   const manager = getOrCreateFrameContextManager(cdpClient);
-  manager.setDebug(traceWait);
+  try {
+    manager.setDebug(traceWait);
+  } catch (error) {
+    console.warn(
+      `[waitForSettledDOM] Failed to configure frame manager debug flag: ${formatWaitDiagnostic(
+        error
+      )}`
+    );
+  }
   if (
     typeof manager.setFrameFilteringEnabled === "function" &&
     typeof options.filterAdTrackingFrames === "boolean"
   ) {
-    manager.setFrameFilteringEnabled(options.filterAdTrackingFrames);
+    try {
+      manager.setFrameFilteringEnabled(options.filterAdTrackingFrames);
+    } catch (error) {
+      console.warn(
+        `[waitForSettledDOM] Failed to configure frame filtering: ${formatWaitDiagnostic(
+          error
+        )}`
+      );
+    }
   }
 
   const lifecycleSession = await cdpClient.acquireSession("lifecycle");