WeKnora/patches/browserskill/01-browser-read-reliability...

675 lines
27 KiB
Diff

diff --git a/apps/extension/src/browser-driver/__tests__/chromium-cdp.test.ts b/apps/extension/src/browser-driver/__tests__/chromium-cdp.test.ts
index c901e49..2368337 100644
--- a/apps/extension/src/browser-driver/__tests__/chromium-cdp.test.ts
+++ b/apps/extension/src/browser-driver/__tests__/chromium-cdp.test.ts
@@ -30,6 +30,103 @@ function fakeApi() {
}
describe("ChromiumCdp", () => {
+ it("configures frame auto-attach once per debugger session and reapplies after detach", async () => {
+ const { api, onDetach } = fakeApi();
+ vi.mocked(api.sendCommand).mockResolvedValue({ frameTree: { frame: { id: "main" } } });
+ const cdp = new ChromiumCdp(api);
+ const calls = () =>
+ vi.mocked(api.sendCommand).mock.calls.filter((c) => c[1] === "Target.setAutoAttach");
+ await cdp.ensureAttached(4);
+ await Promise.all([cdp.getFrameGraph(4), cdp.getFrameGraph(4)]);
+ await cdp.getFrameGraph(4);
+ expect(calls()).toHaveLength(1);
+ onDetach.fire({ tabId: 4 }, "canceled_by_user");
+ await cdp.getFrameGraph(4);
+ expect(calls()).toHaveLength(2);
+ await cdp.detachAll();
+ await cdp.getFrameGraph(4);
+ expect(calls()).toHaveLength(3);
+ cdp.dispose();
+ });
+
+ it("retries frame discovery after a failed configuration", async () => {
+ const { api } = fakeApi();
+ let attempts = 0;
+ vi.mocked(api.sendCommand).mockImplementation(async (_target, method) => {
+ if (method === "Target.setAutoAttach" && ++attempts === 1) throw new Error("transient");
+ return { frameTree: { frame: { id: "main" } } };
+ });
+ const cdp = new ChromiumCdp(api);
+ await cdp.ensureAttached(4);
+ await cdp.getFrameGraph(4);
+ await cdp.getFrameGraph(4);
+ expect(attempts).toBe(2);
+ cdp.dispose();
+ });
+
+ it("does not send another screenshot after a local timeout while Chrome is still working", async () => {
+ vi.useFakeTimers();
+ const warning = vi.spyOn(console, "warn").mockImplementation(() => {});
+ const { api } = fakeApi();
+ let finish!: (value: unknown) => void;
+ vi.mocked(api.sendCommand).mockImplementation(async (_target, method) => {
+ if (method === "Page.captureScreenshot")
+ return new Promise((resolve) => {
+ finish = resolve;
+ });
+ return {};
+ });
+ const cdp = new ChromiumCdp(api);
+ try {
+ await cdp.ensureAttached(4);
+ const first = expect(cdp.send(4, "Page.captureScreenshot")).rejects.toThrow("timed out");
+ await vi.advanceTimersByTimeAsync(3000);
+ await first;
+ expect(cdp.hasPendingScreenshot(4)).toBe(true);
+ await expect(cdp.send(4, "Page.captureScreenshot")).rejects.toThrow("still running");
+ expect(
+ vi.mocked(api.sendCommand).mock.calls.filter((c) => c[1] === "Page.captureScreenshot"),
+ ).toHaveLength(1);
+ finish({ data: "late" });
+ await vi.advanceTimersByTimeAsync(0);
+ expect(cdp.hasPendingScreenshot(4)).toBe(false);
+ const next = cdp.send(4, "Page.captureScreenshot");
+ await vi.advanceTimersByTimeAsync(0);
+ finish({ data: "new" });
+ await expect(next).resolves.toEqual({ data: "new" });
+ } finally {
+ cdp.dispose();
+ warning.mockRestore();
+ vi.useRealTimers();
+ }
+ });
+
+ it("emulates activity only for owned task tabs and reapplies after detach", async () => {
+ const { api, onDetach } = fakeApi();
+ const owned = new Set([4]);
+ const cdp = new ChromiumCdp(api, { shouldKeepTaskActive: (id) => owned.has(id) });
+ await Promise.all([cdp.ensureAttached(4), cdp.ensureAttached(4)]);
+ await cdp.ensureAttached(5);
+ const focusCalls = () =>
+ vi
+ .mocked(api.sendCommand)
+ .mock.calls.filter((call) => call[1] === "Emulation.setFocusEmulationEnabled");
+ expect(focusCalls()).toEqual([
+ [{ tabId: 4 }, "Emulation.setFocusEmulationEnabled", { enabled: true }],
+ ]);
+ // A previously observed user tab becomes eligible only once explicitly borrowed.
+ owned.add(5);
+ await cdp.send(5, "Page.getLayoutMetrics");
+ expect(focusCalls()).toHaveLength(2);
+ onDetach.fire({ tabId: 4 }, "canceled_by_user");
+ await cdp.ensureAttached(4);
+ expect(focusCalls()).toHaveLength(3);
+ await cdp.detach(4);
+ await cdp.ensureAttached(4);
+ expect(focusCalls()).toHaveLength(4);
+ cdp.dispose();
+ });
+
it("changes attachment identity only across real debugger attachments", async () => {
const { api, onEvent, onDetach } = fakeApi();
const cdp = new ChromiumCdp(api);
@@ -430,6 +527,7 @@ describe("ChromiumCdp", () => {
expect(api.sendCommand).toHaveBeenCalledWith({ tabId: 3 }, "Page.handleJavaScriptDialog", {
accept: true,
});
+ await vi.waitFor(() => expect(cdp.dialogsSince(3, cursor)).toHaveLength(1));
const dialogs = cdp.dialogsSince(3, cursor);
expect(dialogs).toHaveLength(1);
expect(dialogs[0]).toMatchObject({
@@ -479,7 +577,7 @@ describe("ChromiumCdp", () => {
url: "https://example.com/",
});
await Promise.resolve();
- expect(cdp.dialogsSince(11, 0)).toHaveLength(1);
+ await vi.waitFor(() => expect(cdp.dialogsSince(11, 0)).toHaveLength(1));
await cdp.detach(11);
expect(cdp.dialogsSince(11, 0)).toHaveLength(0);
});
diff --git a/apps/extension/src/browser-driver/__tests__/command-deadline.test.ts b/apps/extension/src/browser-driver/__tests__/command-deadline.test.ts
new file mode 100644
index 0000000..7c1dd61
--- /dev/null
+++ b/apps/extension/src/browser-driver/__tests__/command-deadline.test.ts
@@ -0,0 +1,76 @@
+import { afterEach, expect, it, vi } from "vitest";
+import { captureObservationFacts } from "@/tools/vom/capture-coordinator";
+import { CdpReadTimeoutError, runCdpCommand } from "../command-deadline";
+
+afterEach(() => {
+ vi.useRealTimers();
+ vi.restoreAllMocks();
+});
+it("times out stuck snapshots with the actual method and stops fallback reads", async () => {
+ vi.useFakeTimers();
+ vi.spyOn(console, "warn").mockImplementation(() => {});
+ vi.spyOn(console, "debug").mockImplementation(() => {});
+ const send = vi.fn(async (_tab: number, method: string) =>
+ runCdpCommand({ tabId: 4 }, method, () =>
+ method === "DOMSnapshot.captureSnapshot" ? new Promise<never>(() => {}) : Promise.resolve({}),
+ ),
+ );
+ const work = captureObservationFacts({ send: send as never }, 4);
+ const checked = expect(work).rejects.toThrow(
+ "DOMSnapshot.captureSnapshot timed out after 10000ms (tab 4)",
+ );
+ await vi.advanceTimersByTimeAsync(10_000);
+ await checked;
+ expect(send.mock.calls.map((call) => call[1])).toEqual([
+ "DOMSnapshot.enable",
+ "DOMSnapshot.captureSnapshot",
+ ]);
+ expect(vi.getTimerCount()).toBe(0);
+});
+it("bounds screenshots and ignores their late reply", async () => {
+ vi.useFakeTimers();
+ vi.spyOn(console, "warn").mockImplementation(() => {});
+ vi.spyOn(console, "debug").mockImplementation(() => {});
+ let finish!: (value: string) => void;
+ const work = runCdpCommand(
+ { tabId: 4 },
+ "Page.captureScreenshot",
+ () =>
+ new Promise<string>((resolve) => {
+ finish = resolve;
+ }),
+ );
+ const checked = expect(work).rejects.toBeInstanceOf(CdpReadTimeoutError);
+ await vi.advanceTimersByTimeAsync(3_000);
+ await checked;
+ finish("late image");
+ await Promise.resolve();
+ expect(vi.getTimerCount()).toBe(0);
+});
+
+it("distinguishes caller timeout from a late Chrome completion", async () => {
+ vi.useFakeTimers();
+ const warning = vi.spyOn(console, "warn").mockImplementation(() => {});
+ let finish!: (value: string) => void;
+ const work = runCdpCommand(
+ { tabId: 4 },
+ "Page.captureScreenshot",
+ () =>
+ new Promise<string>((resolve) => {
+ finish = resolve;
+ }),
+ );
+ const checked = expect(work).rejects.toBeInstanceOf(CdpReadTimeoutError);
+ await vi.advanceTimersByTimeAsync(3000);
+ await checked;
+ expect(warning.mock.calls.filter((c) => c[0] === "[bsk cdp] slow command settled")).toHaveLength(
+ 0,
+ );
+ await vi.advanceTimersByTimeAsync(5000);
+ finish("image");
+ await vi.advanceTimersByTimeAsync(0);
+ expect(warning).toHaveBeenCalledWith(
+ "[bsk cdp] slow command settled",
+ expect.objectContaining({ elapsedMs: 8000, outcome: "returned", late: true }),
+ );
+});
diff --git a/apps/extension/src/browser-driver/__tests__/task-focus.browser.test.ts b/apps/extension/src/browser-driver/__tests__/task-focus.browser.test.ts
new file mode 100644
index 0000000..deed38f
--- /dev/null
+++ b/apps/extension/src/browser-driver/__tests__/task-focus.browser.test.ts
@@ -0,0 +1,94 @@
+// @vitest-environment node
+import { describe, expect, it } from "vitest";
+import { captureVomObservation } from "@/tools/observation";
+import { type CdpDebuggerApi, ChromiumCdp } from "../chromium-cdp";
+
+describe.skipIf(!process.env.BSK_GEOMETRY_CHROME)("real background task rendering", () => {
+ it.each([
+ 0, 2000,
+ ])("renders a background page with %i repeated controls and restores visibility on detach", async (controlCount) => {
+ // Raw CDP deliberately avoids Playwright, which enables focus emulation by default
+ // and would mask this exact regression even when a Chrome tab is inactive.
+ const { withChrome } = await import(
+ new URL(
+ "../../../../../evals/browser/cases/regression/snapshot-coordinates/chrome.mjs",
+ import.meta.url,
+ ).href
+ );
+ await withChrome(
+ { executable: process.env.BSK_GEOMETRY_CHROME, deviceScale: 1, zoom: 1 },
+ async (send: any) => {
+ const foreground = (await send("Target.getTargets")).targetInfos.find(
+ (t: any) => t.type === "page",
+ );
+ const { sessionId: foregroundSession } = await send("Target.attachToTarget", {
+ targetId: foreground.targetId,
+ flatten: true,
+ });
+ const url =
+ "data:text/html," +
+ encodeURIComponent(
+ '<title>Background task</title><p>Loading</p><script>requestAnimationFrame(()=>document.querySelector("p").textContent="Rendered")</script>' +
+ "<section><h2>Entry</h2><button>Open</button><p>Sample page content</p></section>".repeat(
+ controlCount,
+ ),
+ );
+ const { targetId } = await send("Target.createTarget", { url, background: true });
+ let sessionId = (await send("Target.attachToTarget", { targetId, flatten: true }))
+ .sessionId;
+ const evaluate = async (expression: string, session = sessionId) =>
+ (
+ await send(
+ "Runtime.evaluate",
+ { expression, awaitPromise: true, returnByValue: true },
+ session,
+ )
+ ).result.value;
+ await expect.poll(() => evaluate("document.readyState")).toBe("complete");
+ expect(
+ await evaluate(
+ '({visibility:document.visibilityState,text:document.querySelector("p").textContent})',
+ ),
+ ).toEqual({ visibility: "hidden", text: "Loading" });
+ await send("Target.detachFromTarget", { sessionId });
+ const event = { addListener() {}, removeListener() {} };
+ const api = {
+ attach: async () => {
+ sessionId = (await send("Target.attachToTarget", { targetId, flatten: true }))
+ .sessionId;
+ },
+ detach: async () => {
+ await send("Target.detachFromTarget", { sessionId });
+ },
+ sendCommand: (_target: unknown, method: string, params: object) =>
+ send(method, params, sessionId),
+ onEvent: event,
+ onDetach: event,
+ } as unknown as CdpDebuggerApi;
+ const cdp = new ChromiumCdp(api, { shouldKeepTaskActive: () => true });
+ try {
+ await cdp.ensureAttached(4);
+ expect(
+ await evaluate(
+ 'new Promise(resolve=>requestAnimationFrame(()=>resolve(document.querySelector("p").textContent)))',
+ ),
+ ).toBe("Rendered");
+ const observation = await captureVomObservation(cdp, 4, url);
+ expect(observation.text).toContain("Rendered");
+ expect(observation.refs).toHaveLength(controlCount);
+ const image = await cdp.send<{ data: string }>(4, "Page.captureScreenshot", {
+ format: "jpeg",
+ fromSurface: true,
+ });
+ expect(image.data.length).toBeGreaterThan(100);
+ expect(await evaluate("document.visibilityState", foregroundSession)).toBe("visible");
+ await cdp.detach(4);
+ sessionId = (await send("Target.attachToTarget", { targetId, flatten: true })).sessionId;
+ expect(await evaluate("document.visibilityState")).toBe("hidden");
+ } finally {
+ cdp.dispose();
+ }
+ },
+ );
+ }, 20_000);
+});
diff --git a/apps/extension/src/browser-driver/chromium-cdp.ts b/apps/extension/src/browser-driver/chromium-cdp.ts
index d40325c..720f87a 100644
--- a/apps/extension/src/browser-driver/chromium-cdp.ts
+++ b/apps/extension/src/browser-driver/chromium-cdp.ts
@@ -31,6 +31,7 @@ import type {
NetworkEntryKind,
NetworkResult,
} from "@/transport/types";
+import { runCdpCommand } from "./command-deadline";
import {
buildFrameGraph,
type CdpFrameGraph,
@@ -140,6 +141,7 @@ interface FrameDiscoveryState {
sessions: Set<string>;
pending: Set<Promise<void>>;
generation: number;
+ enabled: Map<string, Promise<void>>;
}
async function settleBeforeDeadline(promises: Promise<void>[], deadline: number): Promise<boolean> {
@@ -164,6 +166,8 @@ async function settleBeforeDeadline(promises: Promise<void>[], deadline: number)
export class ChromiumCdp {
private readonly api: CdpDebuggerApi;
private readonly attachedTabs = new Set<number>();
+ private readonly pendingScreenshots = new Map<number, Promise<unknown>>();
+ private readonly taskFocus = new Map<number, Promise<void>>();
private readonly attachmentIds = new Map<number, string>();
private readonly attachInFlight = new Map<number, Promise<void>>();
private readonly detachInFlight = new Map<number, Promise<void>>();
@@ -191,6 +195,8 @@ export class ChromiumCdp {
shouldAutoAcceptDialog?: (tabId: number) => boolean | Promise<boolean>;
/** Invalidate tab refs when the root document or debugger attachment changes. */
onDocumentChanged?: (tabId: number) => void;
+ /** Only explicitly controlled task tabs may emulate foreground page activity. */
+ shouldKeepTaskActive?: (tabId: number) => boolean;
} = {},
) {
this.api = api;
@@ -212,7 +218,10 @@ export class ChromiumCdp {
// New observers must wait before opening the next connection to that tab.
const detaching = this.detachInFlight.get(tabId);
if (detaching) await detaching;
- if (this.attachedTabs.has(tabId)) return;
+ if (this.attachedTabs.has(tabId)) {
+ await this.keepTaskActive(tabId);
+ return;
+ }
const existing = this.attachInFlight.get(tabId);
if (existing) {
await existing;
@@ -221,6 +230,7 @@ export class ChromiumCdp {
const attach = (async () => {
await this.api.attach({ tabId }, CDP_PROTOCOL_VERSION);
try {
+ await this.keepTaskActive(tabId);
await this.enablePageDomain(tabId);
await this.enableConsoleDomains(tabId);
await this.enableNetworkDomainBestEffort(tabId);
@@ -242,6 +252,7 @@ export class ChromiumCdp {
await this.api.detach({ tabId }).catch((detachErr) => {
console.debug("[bsk cdp] rollback detach failed", { tabId, detachErr });
});
+ this.taskFocus.delete(tabId);
throw err;
}
})()
@@ -263,11 +274,16 @@ export class ChromiumCdp {
* `chrome.runtime.lastError`.
*/
async send<T = unknown>(tabId: number, method: string, params?: object): Promise<T> {
- if (!this.attachedTabs.has(tabId)) {
- await this.ensureAttached(tabId);
- }
+ await this.ensureAttached(tabId);
try {
- const result = await this.api.sendCommand({ tabId }, method, params ?? {});
+ const result = await this.command({ tabId }, method, params ?? {});
+ // Upstream input readiness temporarily restores focus emulation. Reapply
+ // the task policy on the next command instead of trusting a stale cache.
+ if (
+ method === "Emulation.setFocusEmulationEnabled" &&
+ (params as { enabled?: boolean } | undefined)?.enabled === false
+ )
+ this.taskFocus.delete(tabId);
return result as T;
} catch (err) {
throw normalizeError(err);
@@ -275,11 +291,9 @@ export class ChromiumCdp {
}
async sendToTarget<T = unknown>(target: CdpTarget, method: string, params?: object): Promise<T> {
- if (!this.attachedTabs.has(target.tabId)) {
- await this.ensureAttached(target.tabId);
- }
+ await this.ensureAttached(target.tabId);
try {
- return (await this.api.sendCommand(target, method, params ?? {})) as T;
+ return (await this.command(target, method, params ?? {})) as T;
} catch (err) {
throw normalizeError(err);
}
@@ -455,6 +469,7 @@ export class ChromiumCdp {
this.attachedTabs.delete(tabId);
this.attachmentIds.delete(tabId);
this.options.onDocumentChanged?.(tabId);
+ this.taskFocus.delete(tabId);
this.clearDialogState(tabId);
this.clearConsoleState(tabId);
this.clearNetworkState(tabId);
@@ -515,6 +530,7 @@ export class ChromiumCdp {
this.attachedTabs.clear();
this.attachmentIds.clear();
for (const tabId of tabs) this.options.onDocumentChanged?.(tabId);
+ this.taskFocus.clear();
this.dialogBuffers.clear();
this.dialogSequences.clear();
this.consoleBuffers.clear();
@@ -525,6 +541,7 @@ export class ChromiumCdp {
this.networkDomainsEnabledTabs.clear();
this.networkRequestMeta.clear();
this.frameDiscovery.clear();
+ this.pendingScreenshots.clear();
await Promise.all(
tabs.map(async (tabId) => {
try {
@@ -536,8 +553,48 @@ export class ChromiumCdp {
);
}
+ hasPendingScreenshot(tabId: number): boolean {
+ return this.pendingScreenshots.has(tabId);
+ }
+
+ private command(target: CdpDebuggee, method: string, params: object): Promise<unknown> {
+ return runCdpCommand(target, method, () => {
+ const tabId = target.tabId;
+ if (method !== "Page.captureScreenshot" || tabId === undefined)
+ return this.api.sendCommand(target, method, params);
+ // A local deadline cannot cancel a Chrome command. Keep this fence until
+ // Chrome actually replies (or detaches), so polling cannot pile up captures.
+ if (this.pendingScreenshots.has(tabId))
+ throw new Error("Previous screenshot is still running in Chrome");
+ const pending = this.api.sendCommand(target, method, params);
+ this.pendingScreenshots.set(tabId, pending);
+ const clear = () => {
+ if (this.pendingScreenshots.get(tabId) === pending) this.pendingScreenshots.delete(tabId);
+ };
+ void pending.then(clear, clear);
+ return pending;
+ });
+ }
+
+ private async keepTaskActive(tabId: number): Promise<void> {
+ if (!this.options.shouldKeepTaskActive?.(tabId)) return;
+ let work = this.taskFocus.get(tabId);
+ if (!work) {
+ // Emulate page visibility/focus without activating a Chrome tab or window.
+ // Chrome resets this per-debugger override when we detach at turn end.
+ work = this.command({ tabId }, "Emulation.setFocusEmulationEnabled", { enabled: true })
+ .then(() => {})
+ .catch((error) => {
+ this.taskFocus.delete(tabId);
+ throw error;
+ });
+ this.taskFocus.set(tabId, work);
+ }
+ await work;
+ }
+
private async enablePageDomain(tabId: number): Promise<void> {
- await this.api.sendCommand({ tabId }, "Page.enable", {});
+ await this.command({ tabId }, "Page.enable", {});
}
private async enableConsoleDomains(tabId: number): Promise<void> {
@@ -550,7 +607,7 @@ export class ChromiumCdp {
let failed = false;
for (const method of ["Runtime.enable", "Log.enable"]) {
try {
- await this.api.sendCommand({ tabId }, method, {});
+ await this.command({ tabId }, method, {});
} catch (err) {
failed = true;
console.debug("[bsk cdp] console domain enable failed", { tabId, method, err });
@@ -563,7 +620,7 @@ export class ChromiumCdp {
private async enableNetworkDomain(tabId: number): Promise<void> {
if (this.networkDomainsEnabledTabs.has(tabId)) return;
- await this.api.sendCommand({ tabId }, "Network.enable", {});
+ await this.command({ tabId }, "Network.enable", {});
this.networkDomainsEnabledTabs.add(tabId);
}
@@ -575,13 +632,27 @@ export class ChromiumCdp {
}
}
- private async enableFrameDiscovery(target: CdpTarget): Promise<void> {
- await this.api.sendCommand(target, "Target.setAutoAttach", {
+ private enableFrameDiscovery(target: CdpTarget): Promise<void> {
+ const state = this.frameDiscoveryState(target.tabId);
+ const key = target.sessionId ?? "root";
+ const existing = state.enabled.get(key);
+ if (existing) return existing;
+ // Auto-attach remains enabled for this debugger session, including later
+ // navigation and new iframes. Reconfiguring it on every observation adds a
+ // browser round trip and needlessly repeats child-target discovery.
+ const work = this.command(target, "Target.setAutoAttach", {
autoAttach: true,
waitForDebuggerOnStart: false,
flatten: true,
filter: [{ type: "iframe", exclude: false }],
- });
+ })
+ .then(() => {})
+ .catch((error) => {
+ if (state.enabled.get(key) === work) state.enabled.delete(key);
+ throw error;
+ });
+ state.enabled.set(key, work);
+ return work;
}
private bindFrameTargetHandler(): void {
@@ -608,6 +679,7 @@ export class ChromiumCdp {
if (method === "Target.detachedFromTarget") {
const state = this.frameDiscovery.get(tabId);
+ state?.enabled.delete(sessionId);
if (state?.sessions.delete(sessionId)) state.generation += 1;
return;
}
@@ -674,6 +746,7 @@ export class ChromiumCdp {
sessions: new Set(),
pending: new Set(),
generation: 0,
+ enabled: new Map(),
};
this.frameDiscovery.set(tabId, created);
return created;
@@ -681,6 +754,7 @@ export class ChromiumCdp {
private clearFrameState(tabId: number): void {
this.frameDiscovery.delete(tabId);
+ this.pendingScreenshots.delete(tabId);
}
private bindDialogHandler(): void {
@@ -713,7 +787,7 @@ export class ChromiumCdp {
if (parsed.type === "prompt") {
handleParams.promptText = parsed.defaultPrompt ?? "";
}
- await this.api.sendCommand({ tabId }, "Page.handleJavaScriptDialog", handleParams);
+ await this.command({ tabId }, "Page.handleJavaScriptDialog", handleParams);
if (!this.attachedTabs.has(tabId) && !this.attachInFlight.has(tabId)) return;
const sequence = (this.dialogSequences.get(tabId) ?? 0) + 1;
this.dialogSequences.set(tabId, sequence);
@@ -876,6 +950,7 @@ export class ChromiumCdp {
this.options.onDocumentChanged?.(source.tabId);
this.attachedTabs.delete(source.tabId);
this.attachmentIds.delete(source.tabId);
+ this.taskFocus.delete(source.tabId);
this.attachInFlight.delete(source.tabId);
this.tabOwners.delete(source.tabId);
this.clearDialogState(source.tabId);
diff --git a/apps/extension/src/browser-driver/command-deadline.ts b/apps/extension/src/browser-driver/command-deadline.ts
new file mode 100644
index 0000000..540d804
--- /dev/null
+++ b/apps/extension/src/browser-driver/command-deadline.ts
@@ -0,0 +1,78 @@
+import type { CdpDebuggee } from "./chromium-cdp";
+
+// Bound renderer reads, not user-requested waits or mutations. An expired
+// CDP read cannot be cancelled individually; its late reply is ignored and
+// observation must stop rather than issue fallback reads against the same page.
+const READ_COMMANDS = new Set([
+ "Target.setAutoAttach",
+ "DOMSnapshot.enable",
+ "DOMSnapshot.captureSnapshot",
+ "Accessibility.enable",
+ "Accessibility.getFullAXTree",
+ "Page.getLayoutMetrics",
+ "Page.getFrameTree",
+ "DOM.getFrameOwner",
+ "Page.captureScreenshot",
+ "Emulation.setFocusEmulationEnabled",
+]);
+export class CdpReadTimeoutError extends Error {
+ constructor(method: string, tabId: number | undefined, timeout: number) {
+ super(
+ `Browser read ${method} timed out after ${timeout}ms (tab ${tabId}). Do not repeat the same read in a loop; report the timeout and let the browser task release control before retrying.`,
+ );
+ this.name = "CdpReadTimeoutError";
+ }
+}
+
+export async function runCdpCommand<T>(
+ target: CdpDebuggee,
+ method: string,
+ run: () => Promise<T>,
+): Promise<T> {
+ const started = Date.now();
+ const details = () => ({
+ tabId: target.tabId,
+ frameSessionId: target.sessionId,
+ method,
+ elapsedMs: Date.now() - started,
+ });
+ const slow = setTimeout(() => console.warn("[bsk cdp] slow command", details()), 2_000);
+ let deadline: ReturnType<typeof setTimeout> | undefined;
+ let timedOut = false;
+ const settled = (outcome: "returned" | "failed") => {
+ if (Date.now() - started >= 2_000)
+ console.warn("[bsk cdp] slow command settled", { ...details(), outcome, late: timedOut });
+ };
+ try {
+ const pending = run().then(
+ (value) => {
+ settled("returned");
+ return value;
+ },
+ (error) => {
+ settled("failed");
+ throw error;
+ },
+ );
+ if (!READ_COMMANDS.has(method)) return await pending;
+ const timeout = method === "Page.captureScreenshot" ? 3_000 : 10_000;
+ return await Promise.race([
+ pending,
+ new Promise<never>((_, reject) => {
+ deadline = setTimeout(() => {
+ timedOut = true;
+ reject(new CdpReadTimeoutError(method, target.tabId, timeout));
+ }, timeout);
+ }),
+ ]);
+ } catch (error) {
+ console.warn("[bsk cdp] command failed", {
+ ...details(),
+ error: error instanceof Error ? error.message : String(error),
+ });
+ throw error;
+ } finally {
+ clearTimeout(slow);
+ clearTimeout(deadline);
+ }
+}
diff --git a/apps/extension/src/tools/vom/capture-abort.ts b/apps/extension/src/tools/vom/capture-abort.ts
index 7ca65bf..429c373 100644
--- a/apps/extension/src/tools/vom/capture-abort.ts
+++ b/apps/extension/src/tools/vom/capture-abort.ts
@@ -4,10 +4,12 @@ function captureAbortError(): Error {
return error;
}
+// Timed-out renderer reads are terminal too: AX/geometry fallback must not
+// keep issuing reads after the renderer has stopped answering.
export function isAbortError(error: unknown): boolean {
return (
typeof error === "object" &&
error !== null &&
- (error as { name?: string }).name === "AbortError"
+ ["AbortError", "CdpReadTimeoutError"].includes((error as { name?: string }).name ?? "")
);
}