Guard frame-graph debug setter in agent loop

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

Author: cursoragent

currentState.md

@@ -203,6 +203,9 @@ HyperAgent exposes a TypeScript SDK for browser automation with three primary pa
   - `syncFrameContextManager()` now guards trap-prone frame-manager `setDebug` calls, preserving sync flow with sanitized debug warnings.
 - Hardened cache-hydration debug handling in a11y context provider:
   - `hydrateFrameContextFromSnapshot()` now guards trap-prone frame-manager `setDebug` calls so cache hydration continues instead of aborting early.
+- Hardened frame-graph debug artifact capture in agent loop:
+  - `writeFrameGraphSnapshot()` now guards trap-prone frame-manager `setDebug` calls and still proceeds with frame graph serialization.
+  - Added regression coverage to ensure debug-setter traps do not downgrade into "Failed to write frame graph" failures.
 - Refreshed remaining staged-flow wording in the CDP deep dive around OOPIF discovery to describe current execution-context sync progression without stale "Need Phase 4" phrasing.
 - Hardened CDP command dispatch in Playwright session adapter:
   - `PlaywrightSessionAdapter.send()` now guards trap-prone `session.send` method reads and wraps sync send failures with sanitized/diagnostic context.

src/agent/tools/agent.test.ts

@@ -1201,6 +1201,54 @@ describe("runAgentTask completion behavior", () => {
     }
   });
 
+  it("continues frame-graph snapshot writing when frame-manager debug setter throws", async () => {
+    const page = createMockPage();
+    const getCDPClientSpy = jest
+      .spyOn(cdp, "getCDPClient")
+      .mockResolvedValue({} as Awaited<ReturnType<typeof cdp.getCDPClient>>);
+    const getOrCreateFrameContextManagerSpy = jest
+      .spyOn(cdp, "getOrCreateFrameContextManager")
+      .mockReturnValue({
+        setDebug: () => {
+          throw new Error(`frame-debug\u0000\n${"x".repeat(10_000)}`);
+        },
+        toJSON: () => ({ frames: [] }),
+      } as unknown as ReturnType<typeof cdp.getOrCreateFrameContextManager>);
+    const writeSpy = jest.spyOn(fs, "writeFileSync").mockImplementation(() => {
+      return undefined;
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const ctx = createRepeatedActionThenCompleteCtx(1);
+    ctx.debug = true;
+
+    try {
+      const result = await runAgentTask(ctx, createTaskState(page), {
+        debugDir: "debug/test",
+      });
+      expect(result.status).toBe(TaskStatus.COMPLETED);
+      expect(getCDPClientSpy).toHaveBeenCalled();
+      expect(getOrCreateFrameContextManagerSpy).toHaveBeenCalled();
+      const warning = String(
+        warnSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("Failed to configure frame graph debug mode")
+        )?.[0] ?? ""
+      );
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+      expect(
+        warnSpy.mock.calls.some((call) =>
+          String(call[0] ?? "").includes("Failed to write frame graph")
+        )
+      ).toBe(false);
+    } finally {
+      getCDPClientSpy.mockRestore();
+      getOrCreateFrameContextManagerSpy.mockRestore();
+      writeSpy.mockRestore();
+      warnSpy.mockRestore();
+    }
+  });
+
   it("truncates oversized structured-output diagnostics", async () => {
     const page = createMockPage();
     const hugeRaw = "x".repeat(120_000);

src/agent/tools/agent.ts

@@ -332,7 +332,21 @@ const writeFrameGraphSnapshot = async (
   try {
     const cdpClient = await getCDPClient(page);
     const frameManager = getOrCreateFrameContextManager(cdpClient);
-    frameManager.setDebug(debug);
+    if (typeof frameManager.setDebug === "function") {
+      try {
+        frameManager.setDebug(debug);
+      } catch (error) {
+        if (debug) {
+          console.warn(
+            `[FrameContext] Failed to configure frame graph debug mode: ${formatDiagnosticText(
+              error,
+              MAX_RUNTIME_ACTION_MESSAGE_CHARS,
+              "unknown error"
+            )}`
+          );
+        }
+      }
+    }
     const data = frameManager.toJSON();
     fs.writeFileSync(`${dir}/frames.json`, safeJsonStringify(data));
   } catch (error) {