Bound incomplete frame metadata

Author: rgarcia

packages/agent/src/translator/browser.ts

@@ -28,6 +28,7 @@ const SNAPSHOT_CHAR_LIMIT = 50_000;
 const DEFAULT_SNAPSHOT_DEPTH = 15;
 const FIND_MATCH_LIMIT = 20;
 const REF_LIMIT_PER_TARGET = 1000;
+const FRAME_STATE_LIMIT = 1000;
 const SCROLL_NOTCH_PX = 120;
 const EXPECTATION_TIMEOUT_MS = 2_000;
 const EXPECTATION_POLL_MS = 50;
@@ -414,7 +415,9 @@ export class BrowserExecutor {
 		if ([...generations].some(([frameKey, generation]) => this.generation(frameKey) !== generation)) {
 			throw new ObservationChangedError();
 		}
-		this.pruneFrameState(targetId, new Set(generations.keys()));
+		const observedFrames = new Set(generations.keys());
+		if (complete) this.pruneFrameState(targetId, observedFrames);
+		else this.boundFrameState(observedFrames);
 		return {
 			targetId,
 			tree,
@@ -1346,6 +1349,36 @@ export class BrowserExecutor {
 		}
 	}
 
+	private boundFrameState(observed: ReadonlySet<string>): void {
+		const protectedFrames = new Set(observed);
+		for (const frameId of this.frameSessions.keys()) protectedFrames.add(frameId);
+		for (const entry of this.refs.values()) {
+			protectedFrames.add(entry.frameId);
+			if (entry.sessionTargetId) protectedFrames.add(entry.sessionTargetId);
+		}
+		let added = true;
+		while (added) {
+			added = false;
+			for (const [child, parent] of this.frameParents) {
+				if (protectedFrames.has(child) && !protectedFrames.has(parent)) {
+					protectedFrames.add(parent);
+					added = true;
+				}
+			}
+		}
+		for (const frameId of this.frameParents.keys()) {
+			if (this.frameParents.size <= FRAME_STATE_LIMIT) break;
+			if (!protectedFrames.has(frameId)) {
+				this.frameParents.delete(frameId);
+				this.generations.delete(frameId);
+			}
+		}
+		for (const frameId of this.generations.keys()) {
+			if (this.generations.size <= FRAME_STATE_LIMIT) break;
+			if (!protectedFrames.has(frameId)) this.generations.delete(frameId);
+		}
+	}
+
 	private pruneFrameState(targetId: string, observed: ReadonlySet<string>): void {
 		const stale = new Set<string>();
 		for (const frameId of this.frameParents.keys()) {

packages/agent/test/translator-browser.test.ts

@@ -368,7 +368,7 @@ describe("BrowserExecutor ref lifecycle", () => {
 		await expect(executor.execute({ type: "browser_click", ref: "e1" } as CuaBrowserAction)).rejects.toThrow(/stale/);
 	});
 
-	it("prunes rotated iframe state when another iframe is incomplete", async () => {
+	it("preserves incomplete frame state while bounding stale metadata", async () => {
 		const fake = createFakeCdp([
 			ax({ nodeId: "1", role: "RootWebArea", name: "Page", childIds: ["2", "3"] }),
 			ax({ nodeId: "2", role: "Iframe", backendDOMNodeId: 50, parentId: "1" }),
@@ -385,10 +385,26 @@ describe("BrowserExecutor ref lifecycle", () => {
 			}
 		}
 
-		const generations = (executor as unknown as { generations: Map<string, number> }).generations;
-		const frameParents = (executor as unknown as { frameParents: Map<string, string> }).frameParents;
-		expect([...generations.keys()].filter((key) => key.startsWith("FRAME-"))).toEqual(["FRAME-4"]);
-		expect([...frameParents.keys()]).toEqual(["FRAME-4"]);
+		const internal = executor as unknown as {
+			generations: Map<string, number>;
+			frameParents: Map<string, string>;
+			boundFrameState: (observed: ReadonlySet<string>) => void;
+		};
+		expect([...internal.generations.keys()].filter((key) => key.startsWith("FRAME-"))).toEqual([
+			"FRAME-0",
+			"FRAME-1",
+			"FRAME-2",
+			"FRAME-3",
+			"FRAME-4",
+		]);
+		for (let index = 0; index < 1100; index += 1) {
+			internal.frameParents.set(`STALE-${index}`, "TARGET-1");
+			internal.generations.set(`STALE-${index}`, 0);
+		}
+		internal.boundFrameState(new Set(["TARGET-1", "FRAME-4"]));
+		expect(internal.frameParents.size).toBeLessThanOrEqual(1000);
+		expect(internal.generations.size).toBeLessThanOrEqual(1000);
+		expect(internal.frameParents.has("FRAME-4")).toBe(true);
 	});
 
 	it("drops generation state when a target detaches", async () => {