rea-agents 6.3.0 → 6.5.0

package/dist/browser/PlaywrightScenarioEvents.js

@@ -1,17 +1,42 @@
 import { browserScenarioEventSchema, } from "../domain/browserScenarioCaptureValues.js";
 import { PlaywrightScenarioNetwork } from "./network/PlaywrightScenarioNetwork.js";
+// Conservative allocation accounting includes UTF-16 storage and worst-case
+// JSON escaping. Reserve before schema cloning; never serialize to measure.
+const MAX_EVENT_COST = 4 * 1024 * 1024;
+const MAX_CAPTURE_COST = 16 * 1024 * 1024;
+const MAX_EVENTS = 10_000;
+const MAX_LISTENER_OWNERS = 2048;
+const allocationCost = (value, remaining) => {
+    if (typeof value === "string")
+        return value.length * 8 + 2;
+    if (value === null || typeof value !== "object")
+        return 32;
+    let cost = 2;
+    for (const key in value) {
+        if (!Object.hasOwn(value, key))
+            continue;
+        const item = value[key];
+        cost += key.length * 8 + 4 + allocationCost(item, remaining - cost);
+        if (cost > remaining)
+            break;
+    }
+    return cost;
+};
 /** Arrival-ordered Playwright event capture with current-step attribution. */
 export class PlaywrightScenarioEvents {
     items = [];
+    retainedCost = 0;
+    dropped = 0;
     stepIndex = 0;
     sequence = 0;
     enabled;
     secrets;
     ownsContext;
-    pages = new Set();
+    pages = new WeakSet();
     incompleteFamilies = new Set();
     network;
     stopNetwork;
+    stopListeners = new Map();
     sealed = false;
     constructor(options) {
         const network = options.network ?? {
@@ -25,14 +50,19 @@ export class PlaywrightScenarioEvents {
         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.ownsContext && this.enabled.size > 0) {
+            const context = options.context ?? options.page.context();
+            const onPage = (page) => this.popup(page);
+            context.on("page", onPage);
+            this.retainListener(context, () => context.off("page", onPage));
+        }
         if (this.enabled.has("network")) {
             const context = options.context ?? options.page.context();
             const collector = new PlaywrightScenarioNetwork({
                 selection: network,
                 secrets: options.secrets,
                 emit: (event) => this.push(event),
+                admitText: (values) => this.admitProducerText(values),
                 ...(options.signal === undefined ? {} : { signal: options.signal }),
             });
             this.network = collector;
@@ -91,6 +121,9 @@ export class PlaywrightScenarioEvents {
     async finish() {
         this.stopNetwork?.();
         this.stopNetwork = undefined;
+        for (const owner of this.stopListeners.keys())
+            this.releaseListeners(owner);
+        this.pages = new WeakSet();
         try {
             await this.network?.finish();
         }
@@ -102,6 +135,8 @@ export class PlaywrightScenarioEvents {
     limitations() {
         const popupGaps = [...this.incompleteFamilies].map((family) => `Popup ${family} events before Page discovery are unavailable; later events are retained.`);
         const gaps = [...popupGaps, ...(this.network?.limitations() ?? [])];
+        if (this.dropped > 0)
+            gaps.push("Browser event collection reached its resource budget; omitted events and descendant observations are unknown.");
         return this.enabled.has("network") && !this.ownsContext
             ? [
                 "Shared-context network capture excludes requests without a known root or descendant Page frame.",
@@ -112,14 +147,24 @@ export class PlaywrightScenarioEvents {
     result() {
         return {
             retained: this.items.length,
-            dropped: 0,
+            dropped: this.dropped,
             items: this.items,
         };
     }
     push(event) {
         if (this.sealed)
-            return this.sequence;
+            return 0;
         this.sequence += 1;
+        if (this.items.length >= MAX_EVENTS) {
+            this.dropped += 1;
+            return 0;
+        }
+        const cost = allocationCost(event, MAX_EVENT_COST) + 128;
+        if (cost > MAX_EVENT_COST || this.retainedCost + cost > MAX_CAPTURE_COST) {
+            this.dropped += 1;
+            return 0;
+        }
+        this.retainedCost += cost;
         const parsed = browserScenarioEventSchema.parse({
             ...event,
             sequence: this.sequence,
@@ -128,51 +173,148 @@ export class PlaywrightScenarioEvents {
         this.items.push(parsed);
         return this.sequence;
     }
+    admitText(...values) {
+        return this.admitProducerText(values);
+    }
+    /** Admit conservative output cost before running redaction or cloning. */
+    admitProducerText(values) {
+        if (this.sealed)
+            return false;
+        let cost = 4096;
+        for (const value of values) {
+            cost += this.secrets.redactionAllocationCost(value.length);
+            if (cost > MAX_EVENT_COST ||
+                cost > MAX_CAPTURE_COST - this.retainedCost) {
+                this.sequence += 1;
+                this.dropped += 1;
+                return false;
+            }
+        }
+        if (this.items.length >= MAX_EVENTS ||
+            cost > MAX_EVENT_COST ||
+            cost > MAX_CAPTURE_COST - this.retainedCost) {
+            this.sequence += 1;
+            this.dropped += 1;
+            return false;
+        }
+        return true;
+    }
+    admitOwner() {
+        if (this.sealed)
+            return false;
+        if (this.stopListeners.size < MAX_LISTENER_OWNERS)
+            return true;
+        this.dropped += 1;
+        return false;
+    }
+    retainListener(owner, stop) {
+        let stops = this.stopListeners.get(owner);
+        if (stops === undefined) {
+            stops = new Set();
+            this.stopListeners.set(owner, stops);
+        }
+        stops.add(stop);
+    }
+    releaseListeners(owner) {
+        const stops = this.stopListeners.get(owner);
+        this.stopListeners.delete(owner);
+        for (const stop of stops ?? [])
+            stop();
+    }
     observePage(page) {
-        if (this.enabled.has("console"))
-            page.on("console", (message) => this.console(message));
-        if (this.enabled.has("page-errors"))
-            page.on("pageerror", (error) => {
+        if (this.enabled.size > 0) {
+            const onClose = () => {
+                this.releaseListeners(page);
+            };
+            page.on("close", onClose);
+            this.retainListener(page, () => page.off("close", onClose));
+        }
+        if (this.enabled.has("console")) {
+            const onConsole = (message) => this.console(message);
+            page.on("console", onConsole);
+            this.retainListener(page, () => page.off("console", onConsole));
+        }
+        if (this.enabled.has("page-errors")) {
+            const onError = (error) => {
+                if (!this.admitText(error.message, error.stack ?? ""))
+                    return;
                 this.push({
                     kind: "page-error",
                     message: this.secrets.redact(error.message),
                     stack: error.stack === undefined ? null : this.secrets.redact(error.stack),
                 });
-            });
-        if (this.enabled.has("websockets"))
-            page.on("websocket", (socket) => this.webSocket(socket));
+            };
+            page.on("pageerror", onError);
+            this.retainListener(page, () => page.off("pageerror", onError));
+        }
+        if (this.enabled.has("websockets")) {
+            const onWebSocket = (socket) => this.webSocket(socket);
+            page.on("websocket", onWebSocket);
+            this.retainListener(page, () => page.off("websocket", onWebSocket));
+        }
         if (this.enabled.has("frames")) {
-            page.on("frameattached", (frame) => this.frame("frame-attached", frame));
-            page.on("framedetached", (frame) => this.frame("frame-detached", frame));
-            page.on("framenavigated", (frame) => this.frame("frame-navigated", frame));
+            const onAttached = (frame) => this.frame("frame-attached", frame);
+            const onDetached = (frame) => this.frame("frame-detached", frame);
+            const onNavigated = (frame) => this.frame("frame-navigated", frame);
+            page.on("frameattached", onAttached);
+            page.on("framedetached", onDetached);
+            page.on("framenavigated", onNavigated);
+            this.retainListener(page, () => page.off("frameattached", onAttached));
+            this.retainListener(page, () => page.off("framedetached", onDetached));
+            this.retainListener(page, () => page.off("framenavigated", onNavigated));
+        }
+        if (this.enabled.has("workers")) {
+            const onWorker = (worker) => this.worker(worker);
+            page.on("worker", onWorker);
+            this.retainListener(page, () => page.off("worker", onWorker));
         }
-        if (this.enabled.has("workers"))
-            page.on("worker", (worker) => this.worker(worker));
         // 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));
+        if (this.enabled.size > 0) {
+            const onPopup = (popup) => this.popup(popup);
+            page.on("popup", onPopup);
+            this.retainListener(page, () => page.off("popup", onPopup));
+        }
+        if (this.enabled.has("downloads")) {
+            const onDownload = (download) => this.download(download);
+            page.on("download", onDownload);
+            this.retainListener(page, () => page.off("download", onDownload));
+        }
     }
     safeUrl(value) {
         return this.secrets.sanitizeUrl(value);
     }
     console(message) {
+        const rawText = message.text();
         const location = message.location();
+        if (!this.admitText(rawText, location.url, message.type()))
+            return;
         this.push({
             kind: "console",
             level: this.secrets.redact(message.type()),
-            text: this.secrets.redact(message.text()),
+            text: this.secrets.redact(rawText),
             url: location.url === "" ? null : this.safeUrl(location.url),
         });
     }
     webSocket(socket) {
+        if (!this.admitOwner())
+            return;
+        if (!this.admitText(socket.url()))
+            return;
         const url = this.safeUrl(socket.url());
         this.push({ kind: "websocket-opened", url });
-        socket.on("framesent", ({ payload }) => this.webSocketFrame("websocket-frame-sent", url, payload));
-        socket.on("framereceived", ({ payload }) => this.webSocketFrame("websocket-frame-received", url, payload));
-        socket.on("close", () => this.push({ kind: "websocket-closed", url }));
+        const onSent = ({ payload }) => this.webSocketFrame("websocket-frame-sent", url, payload);
+        const onReceived = ({ payload }) => this.webSocketFrame("websocket-frame-received", url, payload);
+        const onClose = () => {
+            this.push({ kind: "websocket-closed", url });
+            this.releaseListeners(socket);
+        };
+        socket.on("framesent", onSent);
+        socket.on("framereceived", onReceived);
+        socket.on("close", onClose);
+        this.retainListener(socket, () => socket.off("framesent", onSent));
+        this.retainListener(socket, () => socket.off("framereceived", onReceived));
+        this.retainListener(socket, () => socket.off("close", onClose));
     }
     webSocketFrame(kind, url, payload) {
         const bytes = Buffer.byteLength(payload);
@@ -188,6 +330,8 @@ export class PlaywrightScenarioEvents {
             });
             return;
         }
+        if (!this.admitText(payload))
+            return;
         const text = this.secrets.redact(payload);
         this.push({
             kind,
@@ -199,6 +343,8 @@ export class PlaywrightScenarioEvents {
         });
     }
     frame(kind, frame) {
+        if (!this.admitText(frame.url(), frame.name()))
+            return;
         this.push({
             kind,
             url: frame.url() === "" ? null : this.safeUrl(frame.url()),
@@ -206,16 +352,25 @@ export class PlaywrightScenarioEvents {
         });
     }
     worker(worker) {
+        if (!this.admitOwner() || !this.admitText(worker.url()))
+            return;
         const details = {
             url: this.safeUrl(worker.url()),
             name: null,
         };
         this.push({ kind: "worker-created", ...details });
-        worker.on("close", () => this.push({ kind: "worker-closed", ...details }));
+        const onClose = () => {
+            this.push({ kind: "worker-closed", ...details });
+            this.releaseListeners(worker);
+        };
+        worker.on("close", onClose);
+        this.retainListener(worker, () => worker.off("close", onClose));
     }
     popup(page) {
         if (this.pages.has(page))
             return;
+        if (!this.admitOwner() || !this.admitText(page.url()))
+            return;
         this.pages.add(page);
         for (const family of [
             "frames",
@@ -231,20 +386,27 @@ export class PlaywrightScenarioEvents {
         };
         if (this.enabled.has("popups")) {
             this.push({ kind: "popup-opened", ...opened });
-            page.on("close", () => this.push({
-                kind: "popup-closed",
-                url: page.url() === "" ? null : this.safeUrl(page.url()),
-                name: null,
-            }));
+            const onClose = () => {
+                if (!this.admitText(page.url()))
+                    return;
+                this.push({
+                    kind: "popup-closed",
+                    url: page.url() === "" ? null : this.safeUrl(page.url()),
+                    name: null,
+                });
+            };
+            page.on("close", onClose);
+            this.retainListener(page, () => page.off("close", onClose));
         }
         this.observePage(page);
     }
     download(download) {
-        this.push({
-            kind: "download-cancelled",
-            suggested_filename: this.secrets.redact(download.suggestedFilename()),
-            url: this.safeUrl(download.url()),
-        });
+        if (this.admitText(download.suggestedFilename(), download.url()))
+            this.push({
+                kind: "download-cancelled",
+                suggested_filename: this.secrets.redact(download.suggestedFilename()),
+                url: this.safeUrl(download.url()),
+            });
         void download.cancel().catch((cause) => {
             // best-effort cleanup: download cancellation must not reject unhandled.
             void cause;

package/dist/browser/PlaywrightScenarioServiceWorkers.js

@@ -0,0 +1,249 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { browserObservationEndpointSchema } from "../domain/browserObservation.js";
+import { BrowserObservationError } from "../domain/browserObservationError.js";
+import { CdpConnection } from "./CdpConnection.js";
+import { withCdpDiscoveryDeadline } from "./CdpEndpoint.js";
+import { attachCdpTargetSession, openCdpEndpoint, } from "./CdpTargetSession.js";
+import { withPlaywrightExecutionBoundary } from "./PlaywrightExecutionBoundary.js";
+const OPERATION = "capture_browser_scenario";
+const scriptResponse = z.object({ identifier: z.string() });
+const attachedEvent = z.object({
+    sessionId: z.string(),
+    targetInfo: z.object({ type: z.string() }),
+});
+const detachedEvent = z.object({ sessionId: z.string() });
+/** Owns only its frame scripts and registration wrappers, never caller-owned workers. */
+export class PlaywrightScenarioServiceWorkers {
+    page;
+    endpoint;
+    targetId;
+    marker = JSON.stringify(`rea-service-workers-${randomUUID()}`);
+    restoreKey = JSON.stringify(`rea-restore-${randomUUID()}`);
+    secret = JSON.stringify(randomUUID());
+    #initialization;
+    #restoration;
+    #session;
+    #targets = new Map();
+    #closed = false;
+    #released = false;
+    #detached = false;
+    #removeListener;
+    #setup = new AbortController();
+    constructor(page, endpoint, targetId) {
+        this.page = page;
+        this.endpoint = endpoint;
+        this.targetId = targetId;
+    }
+    initialize() {
+        return (this.#initialization ??= this.install());
+    }
+    async install() {
+        this.#session = await withCdpDiscoveryDeadline(OPERATION, this.#setup.signal, async (signal) => {
+            await withPlaywrightExecutionBoundary(() => this.assertBlocked(), undefined, signal);
+            const opened = await openCdpEndpoint(browserObservationEndpointSchema.parse(this.endpoint), OPERATION, signal);
+            const target = opened.discovery.targets.find(({ id }) => id === this.targetId);
+            if (target === undefined) {
+                await opened.connection?.close();
+                throw new BrowserObservationError(OPERATION, "target_not_found");
+            }
+            const connection = opened.connection ??
+                (await CdpConnection.connect(opened.discovery.webSocket.url, OPERATION, signal));
+            return await attachCdpTargetSession(connection, target, OPERATION, signal);
+        });
+        const connection = this.#session.connection;
+        this.#removeListener = connection.onEvent((event) => {
+            if (event.method === "Target.attachedToTarget" &&
+                this.#targets.has(event.sessionId ?? "")) {
+                const { sessionId, targetInfo } = attachedEvent.parse(event.params);
+                if (targetInfo.type === "iframe")
+                    this.addTarget(sessionId);
+            }
+            else if (event.method === "Target.detachedFromTarget") {
+                const id = detachedEvent.parse(event.params).sessionId;
+                this.#targets.delete(id);
+                if (id === this.#session?.sessionId)
+                    this.#detached = true;
+            }
+        });
+        const id = this.#session.sessionId;
+        if (id === undefined)
+            throw new BrowserObservationError(OPERATION, "protocol_error");
+        this.addTarget(id);
+        await this.settle();
+        // CDP returns an identifier even when an init script throws in a realm.
+        await withPlaywrightExecutionBoundary(() => this.assertBlocked(), undefined, this.#setup.signal);
+    }
+    addTarget(id) {
+        const target = { id, ready: Promise.resolve() };
+        this.#targets.set(id, target);
+        const ready = this.initializeTarget(target);
+        target.ready = ready;
+        void ready.catch(() => undefined);
+    }
+    async initializeTarget(target) {
+        try {
+            if (this.#closed)
+                return;
+            await this.send(target.id, "Page.enable");
+            if (this.#closed)
+                return;
+            const added = scriptResponse.parse(await this.send(target.id, "Page.addScriptToEvaluateOnNewDocument", {
+                runImmediately: true,
+                source: `(() => {
+          if (!("serviceWorker" in navigator)) return;
+          const prototype = ServiceWorkerContainer.prototype;
+          const descriptor = Object.getOwnPropertyDescriptor(prototype, "register");
+          if (typeof descriptor?.value === "function" && Object.hasOwn(descriptor.value, Symbol.for(${this.marker}))) return;
+          const register = () => Promise.reject(new Error("service workers are blocked by scenario policy"));
+          Object.defineProperty(register, Symbol.for(${this.marker}), { value: true });
+          const secret = ${this.secret};
+          Object.defineProperty(globalThis, ${this.restoreKey}, { configurable: true, value: (provided) => {
+            if (provided !== secret) return false;
+            if (Object.getOwnPropertyDescriptor(prototype, "register")?.value === register) {
+              if (descriptor === undefined) delete prototype.register;
+              else Object.defineProperty(prototype, "register", descriptor);
+            }
+            delete globalThis[${this.restoreKey}];
+            return true;
+          }});
+          Object.defineProperty(prototype, "register", { ...descriptor, configurable: true, value: register });
+        })()`,
+            }));
+            target.identifier = added.identifier;
+            if (!this.#closed)
+                await this.send(target.id, "Target.setAutoAttach", {
+                    autoAttach: true,
+                    waitForDebuggerOnStart: true,
+                    flatten: true,
+                    filter: [{ type: "iframe", exclude: false }, { exclude: true }],
+                });
+        }
+        finally {
+            // Only this page's iframe targets are attached; unrelated workers/popups
+            // are not acquired. Resume a child even if installation or cleanup fails.
+            if (this.#targets.has(target.id) &&
+                target.id !== this.#session?.sessionId)
+                await this.send(target.id, "Runtime.runIfWaitingForDebugger");
+        }
+    }
+    send(id, method, params = {}) {
+        if (this.#session === undefined)
+            throw new BrowserObservationError(OPERATION, "disconnected");
+        return this.#session.connection.send(method, params, id);
+    }
+    async settle() {
+        for (;;) {
+            const targets = [...this.#targets.values()];
+            await Promise.all(targets.map(async (target) => {
+                try {
+                    await target.ready;
+                }
+                catch (cause) {
+                    if (this.#targets.get(target.id) === target)
+                        throw cause;
+                }
+            }));
+            if (targets.length === this.#targets.size &&
+                targets.every((target) => this.#targets.get(target.id) === target))
+                return;
+        }
+    }
+    async assertBlocked() {
+        if (this.#session !== undefined)
+            await this.settle();
+        for (const frame of this.page.frames()) {
+            let violatesPolicy;
+            try {
+                violatesPolicy = await frame.evaluate(`(async () => {
+          if (!("serviceWorker" in navigator)) return false;
+          const serviceWorker = navigator.serviceWorker;
+          if (${this.#session !== undefined} &&
+              (!Object.hasOwn(serviceWorker.register, Symbol.for(${this.marker})) ||
+               typeof globalThis[${this.restoreKey}] !== "function")) return true;
+          if (serviceWorker.controller !== null) return true;
+          return (await serviceWorker.getRegistrations()).length > 0;
+        })()`);
+            }
+            catch (cause) {
+                if (frame.isDetached())
+                    continue;
+                throw cause;
+            }
+            if (violatesPolicy)
+                throw new BrowserObservationError(OPERATION, "target_not_allowed");
+        }
+    }
+    close(stopLoading = false) {
+        this.#closed = true;
+        // Abort discovery/handshakes and reads, never an already-sent page mutation.
+        this.#setup.abort();
+        const restoration = (this.#restoration ??= this.restore(stopLoading));
+        void restoration.then(() => {
+            if (this.#restoration === restoration)
+                this.#restoration = undefined;
+        }, () => {
+            if (this.#restoration === restoration)
+                this.#restoration = undefined;
+        });
+        return withPlaywrightExecutionBoundary(() => restoration, 1_000);
+    }
+    async restore(stopLoading) {
+        await this.#initialization?.catch(() => undefined);
+        if (this.#released)
+            return;
+        const session = this.#session;
+        if (session === undefined)
+            return;
+        if (!this.page.isClosed()) {
+            // This owner exists even with empty storage seeds. Stopped navigation is
+            // independent of storage and restoration never waits for a load event.
+            if (stopLoading && !this.#detached && session.sessionId !== undefined)
+                await this.send(session.sessionId, "Page.stopLoading");
+            await Promise.all([...this.#targets.values()].map(({ ready }) => ready.catch(() => undefined)));
+            for (const target of this.#targets.values()) {
+                if (!this.#detached && target.identifier !== undefined) {
+                    try {
+                        await this.send(target.id, "Page.removeScriptToEvaluateOnNewDocument", { identifier: target.identifier });
+                    }
+                    catch (cause) {
+                        if (this.#targets.get(target.id) === target)
+                            throw cause;
+                    }
+                    delete target.identifier;
+                }
+            }
+            // Future documents cannot install our wrapper after the removals above.
+            // A realm lost to navigation is not assumed restored: retain and retry.
+            for (const frame of this.page.frames()) {
+                if (frame.isDetached())
+                    continue;
+                try {
+                    await frame.evaluate(`(() => {
+            const restore = globalThis[${this.restoreKey}];
+            if (typeof restore === "function" && restore(${this.secret}) === true) return;
+            const register = globalThis.ServiceWorkerContainer?.prototype.register;
+            if (typeof register === "function" && Object.hasOwn(register, Symbol.for(${this.marker})))
+              throw new Error("service-worker policy restoration could not be confirmed");
+          })()`);
+                }
+                catch (cause) {
+                    if (!frame.isDetached())
+                        throw cause;
+                }
+            }
+        }
+        // Detaching the exact owned session also releases its iframe auto-attach.
+        if (!this.page.isClosed() &&
+            !this.#detached &&
+            session.sessionId !== undefined) {
+            await session.connection.send("Target.detachFromTarget", {
+                sessionId: session.sessionId,
+            });
+            this.#detached = true;
+        }
+        this.#removeListener?.();
+        await session.connection.close();
+        this.#released = true;
+    }
+}