Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(browser): capture popup network and report early event gaps (#614)
N0zoM1z0f557207887ca
diff --git a/docs/browser-scenario-contract.md b/docs/browser-scenario-contract.mdindex cdd61588d..768ab65ef 100644--- a/docs/browser-scenario-contract.md+++ b/docs/browser-scenario-contract.md@@ -60,6 +60,23 @@ inline without application-defined size ceilings. Other missing sectionsremain explicit and make the capture ineligible for equality claims.Attach-mode captures also declare the unavoidable pre-attach event gap.+Selected event families are observed on the root page and discovered descendant+popups, including nested popups. Popup lifecycle records are emitted only when+`popups` is selected. Launch-mode network observation starts at the owned+context before navigation, so popup document requests, redirects, and responses+are included once. Connected contexts can contain unrelated tabs: only network+events with a frame belonging to the root or a discovered popup are retained.+Initial popup requests without a frame cannot be attributed in shared contexts+and are omitted; attach coverage remains incomplete.++Playwright reports new popup Pages after their first navigation has committed.+It buffers early console messages and page errors, but the pinned API cannot+recover every earlier frame, worker, WebSocket, or download event. If one of+those families is selected and a popup is discovered, REA reports the family gap+in `limitations`, marks `events` missing, and disables equality eligibility.+Later events remain available; no initial navigation is synthesized from the+popup's current URL.+Each request names the exact launch executable or loopback CDP endpoint, target,actions, and capture behavior. Origin filters and environment-variable namesare included when the scenario needs them.diff --git a/scripts/lib/browser-popup-e2e.mjs b/scripts/lib/browser-popup-e2e.mjsnew file mode 100644index 000000000..bf46d2ffc--- /dev/null+++ b/scripts/lib/browser-popup-e2e.mjs@@ -0,0 +1,252 @@+import assert from "node:assert/strict";+import { execFile } from "node:child_process";+import { once } from "node:events";+import { createServer } from "node:http";+import { fileURLToPath } from "node:url";+import { promisify } from "node:util";+import { chromium } from "playwright-core";+import { Client } from "@modelcontextprotocol/client";+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";++import { PlaywrightBrowserScenarioProvider } from "../../dist/browser/PlaywrightBrowserScenarioProvider.js";+import { PlaywrightScenarioEvents } from "../../dist/browser/PlaywrightScenarioEvents.js";+import { BrowserScenarioSecrets } from "../../dist/browser/BrowserScenarioSecrets.js";+import { browserScenarioSchema } from "../../dist/domain/browserScenario.js";+import { compareBrowserScenarios } from "../../dist/domain/browserScenarioDiff.js";+import { browserScenarioCaptureSchema } from "../../dist/domain/browserScenarioCapture.js";+import { parseEvidence } from "../../dist/domain/evidence.js";++const document = (path) => {+ if (path.startsWith("/nested"))+ return `<script>throw new Error("nested popup failure")</script>+ <script>opener.postMessage("nested-ready", "*")</script>`;+ if (path.startsWith("/popup"))+ return `<script>throw new Error("popup failure")</script>+ <script>onmessage = e => {+ if (e.data === "nested-ready") opener.postMessage("popup-ready", "*");+ }; window.open("/nested");</script><iframe src="/child"></iframe>`;+ if (path.startsWith("/child")) return "child frame";+ return `<script>onmessage = e => {+ if (e.data === "popup-ready") document.body.dataset.ready = "true";+ }</script><button onclick="window.open('/redirect')">Open popup</button>`;+};++const scenarioFor = (executable, origin, events) =>+ browserScenarioSchema.parse({+ browser: { mode: "launch", executable_path: executable },+ start_url: { url: origin },+ actions: [+ {+ step_id: "open",+ action: "click",+ locator: { kind: "role", role: "button", name: "Open popup" },+ },+ {+ step_id: "ready",+ action: "wait_for",+ locator: { kind: "css", selector: "body[data-ready=true]" },+ state: "attached",+ timeout_ms: 10_000,+ },+ ],+ capture: { events, after_each_step: [], at_end: [] },+ });++const capture = async (scenario) => {+ const result = await new PlaywrightBrowserScenarioProvider().captureScenario(+ scenario,+ );+ if (!result.ok) throw result.error;+ assert.ok(+ result.value.steps.every((step) => step.status === "completed"),+ JSON.stringify(result.value.steps),+ );+ return result.value;+};++const assertNetwork = (result, origin) => {+ for (const path of ["/redirect", "/popup", "/nested"])+ for (const kind of ["request", "response"])+ assert.equal(+ result.events.items.filter(+ (event) => event.kind === kind && event.url?.url === origin + path,+ ).length,+ 1,+ `${kind} ${path} must be captured exactly once`,+ );+ assert.equal(result.completeness.equality_eligible, true);+ assert.equal(compareWithSelf(result).overall_status, "unchanged");+};++const compareWithSelf = (capture) =>+ compareBrowserScenarios({+ before_scenario: capture,+ after_scenario: capture,+ normalization: { rules: [] },+ });++const verifySharedContext = async (executable, origin) => {+ const browser = await chromium.launch({+ executablePath: executable,+ headless: true,+ });+ try {+ const context = await browser.newContext();+ const page = await context.newPage();+ const foreign = await context.newPage();+ const secrets = BrowserScenarioSecrets.resolve(+ scenarioFor(executable, origin, ["network"]),+ {},+ );+ assert.ok(secrets);+ const events = new PlaywrightScenarioEvents({+ page,+ context,+ ownsContext: false,+ enabled: new Set(["network"]),+ secrets,+ });+ await Promise.all([+ page.goto(origin),+ foreign.goto(origin + "/popup?unrelated-tab"),+ ]);+ await page.getByRole("button", { name: "Open popup", exact: true }).click();+ await page.locator("body[data-ready=true]").waitFor({ timeout: 10_000 });+ const retained = events.result().items;+ assert.ok(+ events+ .limitations()+ .some((value) => value.includes("Shared-context network")),+ );+ assert.ok(retained.some((event) => event.url?.url === origin + "/"));+ assert.ok(!JSON.stringify(retained).includes("unrelated-tab"));+ } finally {+ await browser.close();+ }+};++const verifyTransports = async (executable, origin) => {+ const scenario = scenarioFor(executable, origin, ["network"]);+ const entrypoint = fileURLToPath(new URL("../rea.mjs", import.meta.url));+ const env = {+ PATH: process.env.PATH ?? "/usr/bin:/bin",+ REA_LOG_LEVEL: "silent",+ HOPPER_LAUNCHER_PATH: "/rea-unconfigured-deep-provider/hopper",+ };+ const { stdout } = await promisify(execFile)(+ process.execPath,+ [+ entrypoint,+ "capture-browser-scenario",+ JSON.stringify(scenario),+ "--json",+ ],+ { env, timeout: 60_000, maxBuffer: 16 * 1024 * 1024 },+ );+ assertNetwork(+ browserScenarioCaptureSchema.parse(+ parseEvidence(JSON.parse(stdout)).normalized_result,+ ),+ origin,+ );+ const transport = new StdioClientTransport({+ command: process.execPath,+ args: [entrypoint, "mcp"],+ env,+ stderr: "pipe",+ });+ const client = new Client({ name: "popup-real-e2e", version: "1" });+ try {+ await client.connect(transport);+ const captured = await client.callTool(+ { name: "capture_browser_scenario", arguments: scenario },+ { timeout: 60_000 },+ );+ assert.notEqual(captured.isError, true, JSON.stringify(captured));+ const evidence = parseEvidence({+ ...captured.structuredContent?.evidence,+ normalized_result: captured.structuredContent?.result,+ });+ assertNetwork(+ browserScenarioCaptureSchema.parse(evidence.normalized_result),+ origin,+ );+ } finally {+ try {+ await client.close();+ } finally {+ await transport.close();+ }+ }+};++/** Verify popup timing, selection, coverage, and shared-context isolation on Chromium. */+export async function verifyPopupEventCoverage(executable) {+ const server = createServer((request, response) => {+ if (request.url === "/redirect") {+ response.writeHead(302, { Location: "/popup" });+ response.end();+ } else {+ response.setHeader("Content-Type", "text/html");+ response.end(document(request.url ?? "/"));+ }+ });+ server.listen(0, "127.0.0.1");+ await once(server, "listening");+ try {+ const address = server.address();+ assert.ok(address !== null && typeof address === "object");+ const origin = `http://127.0.0.1:${address.port}`;+ assertNetwork(+ await capture(scenarioFor(executable, origin, ["network"])),+ origin,+ );+ const errors = await capture(+ scenarioFor(executable, origin, ["page-errors"]),+ );+ assert.deepEqual(+ errors.events.items.map((event) => event.kind),+ ["page-error", "page-error"],+ );+ assert.ok(+ errors.events.items.some((event) => event.message === "popup failure"),+ );+ assert.ok(+ errors.events.items.some(+ (event) => event.message === "nested popup failure",+ ),+ );+ for (const family of ["frames", "workers", "websockets", "downloads"]) {+ const result = await capture(scenarioFor(executable, origin, [family]));+ assert.equal(result.completeness.equality_eligible, false);+ assert.ok(result.completeness.missing_sections.includes("events"));+ assert.equal(compareWithSelf(result).overall_status, "unknown");+ assert.ok(+ result.limitations.some((limitation) =>+ limitation.includes(`Popup ${family}`),+ ),+ );+ }+ await verifySharedContext(executable, origin);+ await verifyTransports(executable, origin);+ return {+ mocked: false,+ initial_network: true,+ redirects: true,+ nested_popups: true,+ unselected_lifecycle_absent: true,+ popup_event_gaps_explicit: true,+ incomplete_comparison_unknown: true,+ shared_context_isolation: true,+ cli: true,+ stdio_mcp: true,+ };+ } finally {+ server.closeAllConnections();+ await new Promise((resolve, reject) =>+ server.close((error) =>+ error === undefined ? resolve() : reject(error),+ ),+ );+ }+}diff --git a/scripts/verify-real-browser.mjs b/scripts/verify-real-browser.mjsindex 8abb6534e..21cfee8f9 100644--- a/scripts/verify-real-browser.mjs+++ b/scripts/verify-real-browser.mjs@@ -34,6 +34,7 @@ import {} from "./lib/browser-scenario-verifier.mjs";import { completeVerifierRun, createVerifierRun } from "./lib/verifier-run.mjs";import { verifyLargeScreenshotE2e } from "./lib/browser-screenshot-e2e.mjs";+import { verifyPopupEventCoverage } from "./lib/browser-popup-e2e.mjs";const REAL_BROWSER_STARTUP_TIMEOUT_MS = 30_000;const SCENARIO_SECRET_VALUE = "rea-browser-verifier-secret";@@ -318,6 +319,7 @@ try {);const largeScreenshot = await verifyLargeScreenshotE2e(endpoint, site.origin);+ const popupEvents = await verifyPopupEventCoverage(executable);process.stdout.write(`${JSON.stringify({verifier_run: await completeVerifierRun(verifierRun),@@ -336,6 +338,7 @@ try {pageScopedTransport: true,screenshotBytes: screenshot.value.artifact.bytes,largeScreenshot,+ popupEvents,browserScenarioCli: true,browserScenarioAttachCleanup: "disconnected-external",browserScenarioLaunchCleanup: "terminated-owned-process",diff --git a/src/browser/BrowserScenarioSessionPort.ts b/src/browser/BrowserScenarioSessionPort.tsindex 0ccdf684d..f3120cba8 100644--- a/src/browser/BrowserScenarioSessionPort.ts+++ b/src/browser/BrowserScenarioSessionPort.ts@@ -26,6 +26,8 @@ export interface BrowserScenarioSessionPort {readonly dropped: number;readonly items: readonly BrowserScenarioEvent[];};+ /** Gaps in selected event families that prevent complete capture claims. */+ eventLimitations?(): readonly string[];perform(action: BrowserScenarioAction, signal?: AbortSignal): Promise<void>;capture(requested: ReadonlySet<SnapshotKind>,diff --git a/src/browser/PlaywrightBrowserScenarioProvider.test.ts b/src/browser/PlaywrightBrowserScenarioProvider.test.tsindex 167c71b92..e97aac402 100644--- a/src/browser/PlaywrightBrowserScenarioProvider.test.ts+++ b/src/browser/PlaywrightBrowserScenarioProvider.test.ts@@ -99,6 +99,7 @@ class FakeSession implements BrowserScenarioSessionPort {performCalls = 0;captureCalls = 0;onPerform: (() => void) | undefined;+ eventGaps: readonly string[] = [];private step = 0;constructor(@@ -138,6 +139,10 @@ class FakeSession implements BrowserScenarioSessionPort {return { retained: 0, dropped: 0, items: [] };}+ eventLimitations(): readonly string[] {+ return this.eventGaps;+ }+async perform(_action: BrowserScenarioAction, signal?: AbortSignal) {this.performCalls += 1;this.onPerform?.();@@ -184,6 +189,24 @@ class FakeSession implements BrowserScenarioSessionPort {}describe("PlaywrightBrowserScenarioProvider", () => {+ it("makes reported event gaps ineligible for equality even in launch mode", async () => {+ const session = new FakeSession("launch");+ session.eventGaps = ["Popup frames before discovery are unavailable"];+ const provider = new PlaywrightBrowserScenarioProvider({+ open: () => Promise.resolve(session),+ });+ const result = await provider.captureScenario(+ scenario({ events: ["frames"] }),+ );+ expect(result.ok).toBe(true);+ if (!result.ok) throw result.error;+ expect(result.value.completeness).toMatchObject({+ status: "incomplete",+ equality_eligible: false,+ missing_sections: ["events"],+ });+ expect(result.value.limitations).toContain(session.eventGaps[0]);+ });it("returns an initial state and every step beyond the former action ceiling", async () => {const session = new FakeSession("launch");const provider = new PlaywrightBrowserScenarioProvider({diff --git a/src/browser/PlaywrightBrowserScenarioProvider.ts b/src/browser/PlaywrightBrowserScenarioProvider.tsindex 89e917c9a..54142a9da 100644--- a/src/browser/PlaywrightBrowserScenarioProvider.ts+++ b/src/browser/PlaywrightBrowserScenarioProvider.ts@@ -234,6 +234,7 @@ const globalCompleteness = (({ completeness }) => completeness.truncated_sections,);if (session.mode === "connect") missing.push("events");+ if ((session.eventLimitations?.().length ?? 0) > 0) missing.push("events");return classifyBrowserScenarioCompleteness(missing, truncated);};@@ -299,6 +300,7 @@ const runScenario = async ("Event sequence records provider receipt order; simultaneous browser causality is not inferred.","Response bodies are not retained.","Storage values are hashed only after declared-secret redaction.",+ ...(session.eventLimitations?.() ?? []),...(session.mode === "connect"? ["CDP attachment cannot recover pre-attach events or guarantee launch-time context options.",diff --git a/src/browser/PlaywrightScenarioEvents.ts b/src/browser/PlaywrightScenarioEvents.tsindex 2b355c586..4fa6237ca 100644--- a/src/browser/PlaywrightScenarioEvents.ts+++ b/src/browser/PlaywrightScenarioEvents.ts@@ -1,4 +1,5 @@import type {+ BrowserContext,ConsoleMessage,Download,Frame,@@ -34,6 +35,9 @@ type UnindexedEvent = BrowserScenarioEvent extends infer Eventinterface EventCaptureOptions {readonly page: Page;+ readonly context?: BrowserContext;+ /** A fresh launch context is wholly owned; connected contexts can contain other tabs. */+ readonly ownsContext?: boolean;readonly enabled: ReadonlySet<EventName>;readonly secrets: BrowserScenarioSecrets;}@@ -45,10 +49,41 @@ export class PlaywrightScenarioEvents {private sequence = 0;private readonly enabled: ReadonlySet<EventName>;private readonly secrets: BrowserScenarioSecrets;+ private readonly ownsContext: boolean;+ private readonly pages = new Set<Page>();+ private readonly incompleteFamilies = new Set<EventName>();constructor(options: EventCaptureOptions) {this.enabled = options.enabled;this.secrets = options.secrets;+ this.ownsContext = options.ownsContext === true;+ this.pages.add(options.page);+ if (this.ownsContext && this.enabled.size > 0)+ (options.context ?? options.page.context()).on("page", (page) =>+ this.popup(page),+ );+ if (this.enabled.has("network")) {+ const context = options.context ?? options.page.context();+ const inScope = (request: Request): boolean => {+ if (this.ownsContext) return true;+ try {+ return this.pages.has(request.frame().page());+ } catch {+ // Initial popup navigations can lack a frame. Never guess ownership+ // from a URL in a shared context; connect captures are attach-limited.+ return false;+ }+ };+ context.on("request", (request) => {+ if (inScope(request)) this.request("request", request);+ });+ context.on("response", (response) => {+ if (inScope(response.request())) this.response(response);+ });+ context.on("requestfailed", (request) => {+ if (inScope(request)) this.request("request-failed", request);+ });+ }this.observePage(options.page);}@@ -64,6 +99,20 @@ export class PlaywrightScenarioEvents {return this.sequence;}+ /** Report selected popup event families with unrecoverable pre-discovery gaps. */+ limitations(): readonly string[] {+ const popupGaps = [...this.incompleteFamilies].map(+ (family) =>+ `Popup ${family} events before Page discovery are unavailable; later events are retained.`,+ );+ return this.enabled.has("network") && !this.ownsContext+ ? [+ "Shared-context network capture excludes requests without a known root or descendant Page frame.",+ ...popupGaps,+ ]+ : popupGaps;+ }+result(): {readonly retained: number;readonly dropped: number;@@ -98,13 +147,6 @@ export class PlaywrightScenarioEvents {error.stack === undefined ? null : this.secrets.redact(error.stack),});});- if (this.enabled.has("network")) {- page.on("request", (request) => this.request("request", request));- page.on("response", (response) => this.response(response));- page.on("requestfailed", (request) =>- this.request("request-failed", request),- );- }if (this.enabled.has("websockets"))page.on("websocket", (socket) => this.webSocket(socket));if (this.enabled.has("frames")) {@@ -116,9 +158,8 @@ export class PlaywrightScenarioEvents {}if (this.enabled.has("workers"))page.on("worker", (worker) => this.worker(worker));- // Every selectable event can also be emitted by a child popup page, and a- // popup is only reachable through this one subscription, so any selection at- // all must observe popups. Lifecycle events stay gated on `popups` below.+ // Any selected family needs descendant discovery in shared contexts.+ // Popup lifecycle records remain gated on their own selector below.if (this.enabled.size > 0) page.on("popup", (popup) => this.popup(popup));if (this.enabled.has("downloads"))page.on("download", (download) => this.download(download));@@ -241,6 +282,15 @@ export class PlaywrightScenarioEvents {}private popup(page: Page): void {+ if (this.pages.has(page)) return;+ this.pages.add(page);+ for (const family of [+ "frames",+ "workers",+ "websockets",+ "downloads",+ ] as const)+ if (this.enabled.has(family)) this.incompleteFamilies.add(family);const opened = {url: page.url() === "" ? null : this.safeUrl(page.url()),name: null,diff --git a/src/browser/PlaywrightScenarioSession.ts b/src/browser/PlaywrightScenarioSession.tsindex 43c81eb16..c71022f0c 100644--- a/src/browser/PlaywrightScenarioSession.ts+++ b/src/browser/PlaywrightScenarioSession.ts@@ -163,6 +163,8 @@ export class PlaywrightScenarioSession implements BrowserScenarioSessionPort {);const events = new PlaywrightScenarioEvents({page: opened.page,+ context: opened.context,+ ownsContext: scenario.browser.mode === "launch",enabled: new Set(scenario.capture.events),secrets,});@@ -212,6 +214,11 @@ export class PlaywrightScenarioSession implements BrowserScenarioSessionPort {return this.eventCapture.result();}+ /** Preserve event coverage gaps for the aggregate capture's completeness. */+ eventLimitations(): readonly string[] {+ return this.eventCapture.limitations();+ }+async perform(action: BrowserScenarioAction,signal?: AbortSignal,