Add per-call frame filter overrides across task and replay APIs

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

Author: cursoragent

README.md

@@ -200,6 +200,7 @@ await page.perform("click the login button", {
 - `retryDelayMs`: delay between element-refetch retries.
 - `maxContextSwitchRetries`: retries when a tab/context switch interrupts an in-flight action.
 - `contextSwitchRetryDelayMs`: delay between context-switch retries (defaults to 500ms, capped for safety).
+- `filterAdTrackingFrames`: override iframe filtering for this action (`true` by default). Set to `false` when you intentionally need ad/tracking iframes in scope.
 - `maxSteps` (**deprecated**): compatibility alias for `maxElementRetries`.
   - Using `maxSteps` emits a one-time deprecation warning per agent instance.
 
@@ -218,6 +219,7 @@ await page.perform("click the login button", {
 
 - `useDomCache` (boolean): Reuse DOM snapshots for speed
 - `enableVisualMode` (boolean): Enable screenshots and overlays (default: false)
+- `filterAdTrackingFrames` (boolean): override ad/tracking iframe filtering for this task (inherits agent-level default when omitted)
 
 **Example**:
 
@@ -573,6 +575,7 @@ HyperAgent integrates seamlessly with Playwright, so you can still use familiar
 
 Keep in mind that CDP is still experimental, and stability is not guaranteed. If you'd like the agent to use Playwright's native locators/actions instead, set `cdpActions: false` when you create the agent and it will fall back automatically.
 If you need to inspect ad/tracking iframes for a specific workflow, keep CDP enabled and set `filterAdTrackingFrames: false` in `new HyperAgent({ ... })`.
+You can also override this per invocation using `page.ai(..., { filterAdTrackingFrames: false })` or `page.perform(..., { filterAdTrackingFrames: false })`.
 
 The CDP layer is still evolving—expect rapid polish (and the occasional sharp edge). If you hit something quirky you can toggle CDP off for that workflow and drop us a bug report.
 

currentState.md

@@ -118,6 +118,7 @@ HyperAgent exposes a TypeScript SDK for browser automation with three primary pa
 - Removed direct `as any` casts in OpenAI/Anthropic/DeepSeek/Gemini provider request payload assembly in favor of SDK-derived parameter field typing.
 - Added `filterAdTrackingFrames` configuration in `HyperAgent` so CDP frame discovery can optionally include ad/tracking iframes for workflows that require them.
 - Propagated frame-filter policy through DOM-settle/replay/wait paths so `waitForSettledDOM` and special replay actions honor per-agent ad/tracking frame filtering settings.
+- 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.
 - 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.

docs/cdp-overview.md

@@ -26,6 +26,12 @@ const agent = new HyperAgent({
 - `true` (default): skip likely ad/tracking frames during OOPIF/session discovery.
 - `false`: include those frames, which is useful for workflows that intentionally interact with ad-tech, analytics tags, or embedded consent/tracking widgets.
 
+Override scopes:
+- agent-level default via `new HyperAgent({ filterAdTrackingFrames: ... })`,
+- per-task override via `page.ai(task, { filterAdTrackingFrames: ... })`,
+- per-single-action override via `page.perform(instruction, { filterAdTrackingFrames: ... })`,
+- replay override via `runFromActionCache(..., { filterAdTrackingFrames: ... })`.
+
 The same setting is propagated through:
 - task loop runtime context initialization (`page.ai()` flow),
 - single-action execution (`page.perform()` flow),

src/__tests__/public-api.test.ts

@@ -63,9 +63,11 @@ describe("public API exports", () => {
       retryDelayMs: 250,
       maxContextSwitchRetries: 4,
       contextSwitchRetryDelayMs: 500,
+      filterAdTrackingFrames: false,
     };
 
     expect(performParams.contextSwitchRetryDelayMs).toBe(500);
+    expect(performParams.filterAdTrackingFrames).toBe(false);
   });
 
   it("exposes frame-filter configuration on public HyperAgentConfig", () => {
@@ -75,4 +77,16 @@ describe("public API exports", () => {
 
     expect(config.filterAdTrackingFrames).toBe(false);
   });
+
+  it("exposes frame-filter overrides on task and replay params", () => {
+    const taskParams: TaskParams = {
+      filterAdTrackingFrames: false,
+    };
+    const replayParams: RunFromActionCacheParams = {
+      filterAdTrackingFrames: false,
+    };
+
+    expect(taskParams.filterAdTrackingFrames).toBe(false);
+    expect(replayParams.filterAdTrackingFrames).toBe(false);
+  });
 });

src/agent/__tests__/execute-single-action.test.ts

@@ -167,6 +167,31 @@ describe("HyperAgent.executeSingleAction retry options", () => {
     );
   });
 
+  it("prefers per-call filterAdTrackingFrames override over agent default", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: false,
+      cdpActions: false,
+      filterAdTrackingFrames: true,
+    });
+    const page = {
+      url: () => "https://example.com",
+    } as unknown as Page;
+
+    await agent.executeSingleAction("click login", page, {
+      filterAdTrackingFrames: false,
+    });
+
+    expect(findElementWithInstruction).toHaveBeenCalledWith(
+      "click login",
+      page,
+      expect.any(Object),
+      expect.objectContaining({
+        filterAdTrackingFrames: false,
+      })
+    );
+  });
+
   it("uses deprecated maxSteps as fallback for single-action retries", async () => {
     const agent = new HyperAgent({
       llm: createMockLLM(),

src/agent/__tests__/hyperagent-constructor.test.ts

@@ -146,6 +146,39 @@ describe("HyperAgent constructor and task controls", () => {
     expect(runtimeCtx?.filterAdTrackingFrames).toBe(false);
   });
 
+  it("prefers per-task filterAdTrackingFrames override over agent default", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id-filter-override",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id-filter-override",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      filterAdTrackingFrames: true,
+    });
+    const fakePage = {} as unknown as Page;
+
+    await agent.executeTask(
+      "test task",
+      { filterAdTrackingFrames: false },
+      fakePage
+    );
+
+    const runtimeCtx = mockedRunAgentTask.mock.calls[0]?.[0] as {
+      filterAdTrackingFrames?: boolean;
+    };
+    expect(runtimeCtx?.filterAdTrackingFrames).toBe(false);
+  });
+
   it("executeTaskAsync cleans up state when setup throws before run starts", async () => {
     const agent = new HyperAgent({
       llm: createMockLLM(),

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

@@ -66,7 +66,12 @@ describe("runFromActionCache hardening", () => {
 
     const replay = await agent.runFromActionCache(cache, page);
 
-    expect(perform).toHaveBeenCalledWith("click login");
+    expect(perform).toHaveBeenCalledWith(
+      "click login",
+      expect.objectContaining({
+        filterAdTrackingFrames: true,
+      })
+    );
     expect(performClick).not.toHaveBeenCalled();
     expect(replay.status).toBe(TaskStatus.COMPLETED);
     expect(replay.steps[0]?.usedXPath).toBe(false);
@@ -1218,8 +1223,20 @@ describe("runFromActionCache hardening", () => {
     const replay = await agent.runFromActionCache(cache, page);
 
     expect(replay.status).toBe(TaskStatus.COMPLETED);
-    expect(perform).toHaveBeenNthCalledWith(1, "normal step");
-    expect(perform).toHaveBeenNthCalledWith(2, "nan index step");
+    expect(perform).toHaveBeenNthCalledWith(
+      1,
+      "normal step",
+      expect.objectContaining({
+        filterAdTrackingFrames: true,
+      })
+    );
+    expect(perform).toHaveBeenNthCalledWith(
+      2,
+      "nan index step",
+      expect.objectContaining({
+        filterAdTrackingFrames: true,
+      })
+    );
     expect(replay.steps[0]?.stepIndex).toBe(0);
     expect(replay.steps[1]?.stepIndex).toBe(-1);
   });
@@ -1291,7 +1308,63 @@ describe("runFromActionCache hardening", () => {
 
     expect(replay.sourceTaskId).toBe("unknown-task");
     expect(replay.status).toBe(TaskStatus.COMPLETED);
-    expect(perform).toHaveBeenCalledWith("fallback source id");
+    expect(perform).toHaveBeenCalledWith(
+      "fallback source id",
+      expect.objectContaining({
+        filterAdTrackingFrames: true,
+      })
+    );
+  });
+
+  it("applies runFromActionCache filter override to perform fallback calls", 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,
+      },
+    });
+    const page = {
+      perform,
+    } 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 ad iframe CTA",
+          elementId: "0-1",
+          method: "click",
+          arguments: [],
+          frameIndex: 0,
+          xpath: null,
+          actionType: "actElement",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    await agent.runFromActionCache(cache, page, {
+      filterAdTrackingFrames: false,
+    });
+
+    expect(perform).toHaveBeenCalledWith(
+      "click ad iframe CTA",
+      expect.objectContaining({
+        filterAdTrackingFrames: false,
+      })
+    );
   });
 
   it("truncates oversized cached-step read diagnostics", async () => {