rea-agents 6.5.0 → 6.7.0

package/dist/browser/PlaywrightScenarioEvents.js

@@ -1,10 +1,8 @@
 import { browserScenarioEventSchema, } from "../domain/browserScenarioCaptureValues.js";
+import { DEFAULT_BROWSER_SCENARIO_CAPTURE_LIMITS } from "../domain/browserScenarioCaptureLimits.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;
+// JSON escaping. Check before schema cloning; never serialize to measure.
 const MAX_LISTENER_OWNERS = 2048;
 const allocationCost = (value, remaining) => {
     if (typeof value === "string")
@@ -27,10 +25,13 @@ export class PlaywrightScenarioEvents {
     items = [];
     retainedCost = 0;
     dropped = 0;
+    omittedKinds = new Map();
+    omittedNetwork = new Map();
     stepIndex = 0;
     sequence = 0;
     enabled;
     secrets;
+    limits;
     ownsContext;
     pages = new WeakSet();
     incompleteFamilies = new Set();
@@ -48,6 +49,7 @@ export class PlaywrightScenarioEvents {
         if (network.request_body || network.response_body || network.header_values)
             this.enabled = new Set([...this.enabled, "network"]);
         this.secrets = options.secrets;
+        this.limits = options.limits ?? DEFAULT_BROWSER_SCENARIO_CAPTURE_LIMITS;
         this.ownsContext = options.ownsContext === true;
         this.pages.add(options.page);
         if (this.ownsContext && this.enabled.size > 0) {
@@ -60,9 +62,13 @@ export class PlaywrightScenarioEvents {
             const context = options.context ?? options.page.context();
             const collector = new PlaywrightScenarioNetwork({
                 selection: network,
+                limits: this.limits,
                 secrets: options.secrets,
                 emit: (event) => this.push(event),
-                admitText: (values) => this.admitProducerText(values),
+                admitText: (kind, values) => this.admitProducerText(kind, values, true),
+                admitContentBody: (input) => this.admitContentBody(input),
+                omitNetwork: (id, kind, reason) => this.omitNetwork(id, kind, reason),
+                omitEvent: (kind, reason) => this.omitEvent(kind, reason),
                 ...(options.signal === undefined ? {} : { signal: options.signal }),
             });
             this.network = collector;
@@ -136,7 +142,7 @@ export class PlaywrightScenarioEvents {
         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.");
+            gaps.push("Browser event collection reached a selected resource budget; per-kind omissions and affected network transaction IDs are listed in events.omissions, and event coverage is incomplete.");
         return this.enabled.has("network") && !this.ownsContext
             ? [
                 "Shared-context network capture excludes requests without a known root or descendant Page frame.",
@@ -145,24 +151,45 @@ export class PlaywrightScenarioEvents {
             : gaps;
     }
     result() {
+        const omittedKinds = new Map([...this.omittedKinds].map(([kind, omission]) => [
+            kind,
+            { count: omission.count, reasons: new Set(omission.reasons) },
+        ]));
         return {
             retained: this.items.length,
             dropped: this.dropped,
             items: this.items,
+            omissions: {
+                by_kind: [...omittedKinds]
+                    .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+                    .map(([kind, omission]) => ({
+                    kind,
+                    count: omission.count,
+                    reasons: [...omission.reasons].sort(),
+                })),
+                network_transactions: [...this.omittedNetwork]
+                    .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+                    .map(([transaction_id, omission]) => ({
+                    transaction_id,
+                    omitted_kinds: [...omission.kinds].sort(),
+                    reasons: [...omission.reasons].sort(),
+                })),
+                network_transaction_range: this.network?.omittedTransactionRange() ?? null,
+            },
         };
     }
     push(event) {
-        if (this.sealed)
-            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;
+        const cost = allocationCost(event, this.limits.max_event_allocation_bytes) + 128;
+        const reason = this.admissionReason(cost);
+        if (this.sealed || reason !== undefined) {
+            const finalReason = reason ?? "max-events";
+            this.omitEvent(event.kind, finalReason);
+            return {
+                status: "omitted",
+                sequence: this.sequence,
+                reason: finalReason,
+            };
         }
         this.retainedCost += cost;
         const parsed = browserScenarioEventSchema.parse({
@@ -171,40 +198,98 @@ export class PlaywrightScenarioEvents {
             step_index: this.stepIndex,
         });
         this.items.push(parsed);
-        return this.sequence;
+        return { status: "retained", sequence: this.sequence };
     }
-    admitText(...values) {
-        return this.admitProducerText(values);
+    admitText(kind, ...values) {
+        return this.admitProducerText(kind, values, false).status === "retained";
     }
     /** Admit conservative output cost before running redaction or cloning. */
-    admitProducerText(values) {
-        if (this.sealed)
-            return false;
+    admitProducerText(kind, values, networkMetadata) {
         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) {
+        const reason = networkMetadata &&
+            cost > this.limits.max_network_metadata_allocation_bytes
+            ? "max-network-metadata-allocation-bytes"
+            : this.admissionReason(cost);
+        if (reason !== undefined) {
             this.sequence += 1;
-            this.dropped += 1;
-            return false;
+            this.omitEvent(kind, reason);
+            return { status: "omitted", sequence: this.sequence, reason };
         }
-        return true;
+        return { status: "retained", sequence: this.sequence + 1 };
+    }
+    admissionReason(cost) {
+        if (this.sealed || this.items.length >= this.limits.max_events)
+            return "max-events";
+        if (cost > this.limits.max_event_allocation_bytes)
+            return "max-event-allocation-bytes";
+        if (cost > this.limits.max_total_event_allocation_bytes - this.retainedCost)
+            return "max-total-event-allocation-bytes";
+        return undefined;
     }
-    admitOwner() {
-        if (this.sealed)
-            return false;
+    admitContentBody(input) {
+        const kind = "network-content";
+        const eventCost = allocationCost({
+            kind,
+            sequence: this.sequence + 1,
+            step_index: this.stepIndex,
+            transaction_id: input.transactionId,
+            source_event_sequence: input.sourceEventSequence,
+            phase: input.phase,
+            headers: input.headers,
+            body: {
+                state: "captured",
+                representation: input.phase === "request"
+                    ? "browser-exposed-request-bytes"
+                    : "playwright-response-body-bytes",
+                encoding: "base64",
+                content: null,
+                bytes: input.observedBytes,
+                sha256: "0".repeat(64),
+                media_type: null,
+                redacted: false,
+            },
+        }, this.limits.max_event_allocation_bytes) -
+            64 +
+            input.allocationBytes +
+            (input.mediaType === undefined
+                ? 0
+                : Math.max(input.mediaType.length * 8 + 2, this.secrets.redactionAllocationCost(input.mediaType.length))) +
+            128;
+        const reason = this.admissionReason(eventCost);
+        if (reason !== undefined) {
+            this.sequence += 1;
+            this.omitEvent(kind, reason);
+            return { status: "omitted", sequence: this.sequence, reason };
+        }
+        return { status: "retained", sequence: this.sequence + 1 };
+    }
+    omitEvent(kind, reason) {
+        this.dropped += 1;
+        let omission = this.omittedKinds.get(kind);
+        if (omission === undefined) {
+            omission = { count: 0, reasons: new Set() };
+            this.omittedKinds.set(kind, omission);
+        }
+        omission.count += 1;
+        omission.reasons.add(reason);
+    }
+    omitNetwork(transactionId, kind, reason) {
+        let omission = this.omittedNetwork.get(transactionId);
+        if (omission === undefined) {
+            omission = { kinds: new Set(), reasons: new Set() };
+            this.omittedNetwork.set(transactionId, omission);
+        }
+        omission.kinds.add(kind);
+        omission.reasons.add(reason);
+    }
+    admitOwner(kind) {
         if (this.stopListeners.size < MAX_LISTENER_OWNERS)
             return true;
-        this.dropped += 1;
+        this.sequence += 1;
+        this.omitEvent(kind, "max-listener-owners");
         return false;
     }
     retainListener(owner, stop) {
@@ -236,7 +321,7 @@ export class PlaywrightScenarioEvents {
         }
         if (this.enabled.has("page-errors")) {
             const onError = (error) => {
-                if (!this.admitText(error.message, error.stack ?? ""))
+                if (!this.admitText("page-error", error.message, error.stack ?? ""))
                     return;
                 this.push({
                     kind: "page-error",
@@ -287,7 +372,7 @@ export class PlaywrightScenarioEvents {
     console(message) {
         const rawText = message.text();
         const location = message.location();
-        if (!this.admitText(rawText, location.url, message.type()))
+        if (!this.admitText("console", rawText, location.url, message.type()))
             return;
         this.push({
             kind: "console",
@@ -297,9 +382,9 @@ export class PlaywrightScenarioEvents {
         });
     }
     webSocket(socket) {
-        if (!this.admitOwner())
+        if (!this.admitOwner("websocket-opened"))
             return;
-        if (!this.admitText(socket.url()))
+        if (!this.admitText("websocket-opened", socket.url()))
             return;
         const url = this.safeUrl(socket.url());
         this.push({ kind: "websocket-opened", url });
@@ -330,7 +415,7 @@ export class PlaywrightScenarioEvents {
             });
             return;
         }
-        if (!this.admitText(payload))
+        if (!this.admitText(kind, payload))
             return;
         const text = this.secrets.redact(payload);
         this.push({
@@ -343,7 +428,7 @@ export class PlaywrightScenarioEvents {
         });
     }
     frame(kind, frame) {
-        if (!this.admitText(frame.url(), frame.name()))
+        if (!this.admitText(kind, frame.url(), frame.name()))
             return;
         this.push({
             kind,
@@ -352,7 +437,8 @@ export class PlaywrightScenarioEvents {
         });
     }
     worker(worker) {
-        if (!this.admitOwner() || !this.admitText(worker.url()))
+        if (!this.admitOwner("worker-created") ||
+            !this.admitText("worker-created", worker.url()))
             return;
         const details = {
             url: this.safeUrl(worker.url()),
@@ -369,7 +455,8 @@ export class PlaywrightScenarioEvents {
     popup(page) {
         if (this.pages.has(page))
             return;
-        if (!this.admitOwner() || !this.admitText(page.url()))
+        if (!this.admitOwner("popup-opened") ||
+            !this.admitText("popup-opened", page.url()))
             return;
         this.pages.add(page);
         for (const family of [
@@ -387,7 +474,7 @@ export class PlaywrightScenarioEvents {
         if (this.enabled.has("popups")) {
             this.push({ kind: "popup-opened", ...opened });
             const onClose = () => {
-                if (!this.admitText(page.url()))
+                if (!this.admitText("popup-closed", page.url()))
                     return;
                 this.push({
                     kind: "popup-closed",
@@ -401,7 +488,7 @@ export class PlaywrightScenarioEvents {
         this.observePage(page);
     }
     download(download) {
-        if (this.admitText(download.suggestedFilename(), download.url()))
+        if (this.admitText("download-cancelled", download.suggestedFilename(), download.url()))
             this.push({
                 kind: "download-cancelled",
                 suggested_filename: this.secrets.redact(download.suggestedFilename()),

package/dist/browser/PlaywrightScenarioServiceWorkers.js

@@ -7,7 +7,14 @@ import { withCdpDiscoveryDeadline } from "./CdpEndpoint.js";
 import { attachCdpTargetSession, openCdpEndpoint, } from "./CdpTargetSession.js";
 import { withPlaywrightExecutionBoundary } from "./PlaywrightExecutionBoundary.js";
 const OPERATION = "capture_browser_scenario";
+// Restoration performs several sequential CDP mutations before the transport's
+// own bounded close. A single round-trip deadline is too short for the complete
+// chain on a loaded Windows browser, while retries must still stay bounded.
+const POLICY_CLEANUP_CONFIRMATION_TIMEOUT_MS = 5_000;
 const scriptResponse = z.object({ identifier: z.string() });
+const restorationResponse = z.object({
+    result: z.object({ value: z.literal("policy_owned").nullable() }),
+});
 const attachedEvent = z.object({
     sessionId: z.string(),
     targetInfo: z.object({ type: z.string() }),
@@ -28,6 +35,7 @@ export class PlaywrightScenarioServiceWorkers {
     #closed = false;
     #released = false;
     #detached = false;
+    #loadingStopped = false;
     #removeListener;
     #setup = new AbortController();
     constructor(page, endpoint, targetId) {
@@ -61,6 +69,7 @@ export class PlaywrightScenarioServiceWorkers {
             }
             else if (event.method === "Target.detachedFromTarget") {
                 const id = detachedEvent.parse(event.params).sessionId;
+                this.#targets.get(id)?.markDetached();
                 this.#targets.delete(id);
                 if (id === this.#session?.sessionId)
                     this.#detached = true;
@@ -75,7 +84,17 @@ export class PlaywrightScenarioServiceWorkers {
         await withPlaywrightExecutionBoundary(() => this.assertBlocked(), undefined, this.#setup.signal);
     }
     addTarget(id) {
-        const target = { id, ready: Promise.resolve() };
+        this.#targets.get(id)?.markDetached();
+        let markDetached = () => undefined;
+        const detached = new Promise((resolve) => {
+            markDetached = resolve;
+        });
+        const target = {
+            id,
+            detached,
+            markDetached,
+            ready: Promise.resolve(),
+        };
         this.#targets.set(id, target);
         const ready = this.initializeTarget(target);
         target.ready = ready;
@@ -135,34 +154,88 @@ export class PlaywrightScenarioServiceWorkers {
     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;
-                }
-            }));
+            await Promise.all(targets.map((target) => this.settleTarget(target)));
             if (targets.length === this.#targets.size &&
                 targets.every((target) => this.#targets.get(target.id) === target))
                 return;
         }
     }
+    async settleTarget(target) {
+        try {
+            await Promise.race([target.ready, target.detached]);
+        }
+        catch (cause) {
+            if (this.#targets.get(target.id) === target)
+                throw cause;
+        }
+    }
+    async settleTargetForRestore(target) {
+        try {
+            await Promise.race([target.ready, target.detached]);
+        }
+        catch {
+            // Setup already reports its own failure. Cleanup must continue from the
+            // side effects that were acquired before it failed, such as an init
+            // script whose identifier was returned before auto-attach was rejected.
+        }
+    }
+    restorationScript() {
+        return `(() => {
+      const restore = globalThis[${this.restoreKey}];
+      if (typeof restore === "function" && restore(${this.secret}) === true) return null;
+      const register = globalThis.ServiceWorkerContainer?.prototype.register;
+      return typeof register === "function" && Object.hasOwn(register, Symbol.for(${this.marker}))
+        ? "policy_owned"
+        : null;
+    })()`;
+    }
+    async restoreMainFrame(id) {
+        const { result } = restorationResponse.parse(await this.send(id, "Runtime.evaluate", {
+            expression: this.restorationScript(),
+            returnByValue: true,
+        }));
+        if (result.value === "policy_owned")
+            throw new Error("service-worker policy restoration could not be confirmed");
+    }
+    async restorePlaywrightFrame(frame) {
+        try {
+            const failure = await frame.evaluate(this.restorationScript());
+            if (failure === "policy_owned")
+                throw new Error("service-worker policy restoration could not be confirmed");
+            if (failure !== null)
+                throw new BrowserObservationError(OPERATION, "protocol_error");
+        }
+        catch (cause) {
+            if (!this.page.isClosed() && !frame.isDetached())
+                throw cause;
+        }
+    }
+    async stopMainFrame(frame) {
+        try {
+            await frame.evaluate("globalThis.stop()");
+            this.#loadingStopped = true;
+        }
+        catch (cause) {
+            if (!this.page.isClosed() && !frame.isDetached())
+                throw cause;
+        }
+    }
     async assertBlocked() {
         if (this.#session !== undefined)
             await this.settle();
         for (const frame of this.page.frames()) {
-            let violatesPolicy;
+            let failure;
             try {
-                violatesPolicy = await frame.evaluate(`(async () => {
-          if (!("serviceWorker" in navigator)) return false;
+                failure = await frame.evaluate(`(async () => {
+          if (!("serviceWorker" in navigator)) return null;
           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;
+               typeof globalThis[${this.restoreKey}] !== "function")) return "policy_unprotected";
+          if (serviceWorker.controller !== null) return "service_worker_blocked";
+          return (await serviceWorker.getRegistrations()).length > 0
+            ? "service_worker_blocked"
+            : null;
         })()`);
             }
             catch (cause) {
@@ -170,8 +243,12 @@ export class PlaywrightScenarioServiceWorkers {
                     continue;
                 throw cause;
             }
-            if (violatesPolicy)
+            if (failure === "policy_unprotected")
                 throw new BrowserObservationError(OPERATION, "target_not_allowed");
+            if (failure === "service_worker_blocked")
+                throw new BrowserObservationError(OPERATION, "service_worker_blocked");
+            if (failure !== null)
+                throw new BrowserObservationError(OPERATION, "protocol_error");
         }
     }
     close(stopLoading = false) {
@@ -186,7 +263,7 @@ export class PlaywrightScenarioServiceWorkers {
             if (this.#restoration === restoration)
                 this.#restoration = undefined;
         });
-        return withPlaywrightExecutionBoundary(() => restoration, 1_000);
+        return withPlaywrightExecutionBoundary(() => restoration, POLICY_CLEANUP_CONFIRMATION_TIMEOUT_MS);
     }
     async restore(stopLoading) {
         await this.#initialization?.catch(() => undefined);
@@ -196,11 +273,19 @@ export class PlaywrightScenarioServiceWorkers {
         if (session === undefined)
             return;
         if (!this.page.isClosed()) {
+            const mainFrame = this.page.mainFrame();
             // 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)));
+            if (stopLoading && !this.#loadingStopped) {
+                if (!this.#detached && session.sessionId !== undefined) {
+                    await this.send(session.sessionId, "Page.stopLoading");
+                    this.#loadingStopped = true;
+                }
+                else {
+                    await this.stopMainFrame(mainFrame);
+                }
+            }
+            await Promise.all([...this.#targets.values()].map((target) => this.settleTargetForRestore(target)));
             for (const target of this.#targets.values()) {
                 if (!this.#detached && target.identifier !== undefined) {
                     try {
@@ -215,22 +300,24 @@ export class PlaywrightScenarioServiceWorkers {
             }
             // Future documents cannot install our wrapper after the removals above.
             // A realm lost to navigation is not assumed restored: retain and retry.
+            if (!this.#detached && session.sessionId !== undefined) {
+                await this.restoreMainFrame(session.sessionId);
+            }
+            else {
+                await this.restorePlaywrightFrame(mainFrame);
+            }
             for (const frame of this.page.frames()) {
+                // The owned CDP session evaluates the selected main realm directly,
+                // without Playwright waiting on an in-flight document transition.
+                if (frame === mainFrame)
+                    continue;
                 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;
-                }
+                // An empty URL has no committed document realm to restore. Future
+                // documents cannot install the wrapper after the script removals.
+                if (frame.url().length === 0)
+                    continue;
+                await this.restorePlaywrightFrame(frame);
             }
         }
         // Detaching the exact owned session also releases its iframe auto-attach.