rea-agents 6.4.0 → 6.7.0

package/dist/browser/PlaywrightScenarioSession.js

@@ -1,4 +1,5 @@
-import {} from "playwright-core";
+import { AnalysisCleanupLease, AnalysisCleanupLeaseGroup, } from "../artifacts/AnalysisCleanupLease.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
 import { BrowserObservationError } from "../domain/browserObservationError.js";
 import { BrowserScenarioSecrets } from "./BrowserScenarioSecrets.js";
 import { failBrowserScenarioOperation, openPlaywrightScenarioBrowser, } from "./PlaywrightScenarioBrowser.js";
@@ -6,12 +7,15 @@ import { performPlaywrightScenarioAction } from "./PlaywrightScenarioActions.js"
 import { capturePlaywrightStepArtifacts } from "./PlaywrightScenarioArtifacts.js";
 import { PlaywrightScenarioEvents } from "./PlaywrightScenarioEvents.js";
 import { PlaywrightScenarioStorage } from "./PlaywrightScenarioStorage.js";
-import { withPlaywrightExecutionBoundary } from "./PlaywrightExecutionBoundary.js";
+import { PlaywrightScenarioServiceWorkers } from "./PlaywrightScenarioServiceWorkers.js";
+import { withPlaywrightExecutionBoundary, PLAYWRIGHT_CLEANUP_CONFIRMATION_TIMEOUT_MS, } from "./PlaywrightExecutionBoundary.js";
 import { browserScenarioCaptureData, browserScenarioOperationFailure, } from "./BrowserScenarioPartialObservation.js";
 const OPERATION = "capture_browser_scenario";
 const throwIfScenarioCancelled = (signal) => {
     if (signal?.aborted === true)
-        throw new BrowserObservationError(OPERATION, "cancelled");
+        throw new BrowserObservationError(OPERATION, "cancelled", {
+            cause: signal?.reason,
+        });
 };
 const throwCleanupFailures = (failures) => {
     if (failures.length === 1)
@@ -29,27 +33,9 @@ const installCookies = async (context, scenario, secrets) => {
         sameSite: cookie.same_site,
     })));
 };
-const blockAttachedServiceWorkers = async (page) => {
-    const controller = await page.evaluate("Boolean(navigator.serviceWorker?.controller)");
-    if (controller)
-        throw new BrowserObservationError(OPERATION, "target_not_allowed");
-    const blockRegistration = `(() => {
-    if (!("serviceWorker" in navigator)) return;
-    void navigator.serviceWorker.getRegistrations()
-      .then((registrations) => Promise.all(registrations.map((item) => item.unregister())));
-    Object.defineProperty(ServiceWorkerContainer.prototype, "register", {
-      configurable: false,
-      value: () => Promise.reject(new Error("service workers are blocked by scenario policy"))
-    });
-  })()`;
-    await page.addInitScript(blockRegistration);
-    await page.evaluate(blockRegistration);
-};
-const initializePage = async (context, page, scenario, secrets) => {
+const initializePage = async (context, scenario, secrets) => {
     context.setDefaultTimeout(0);
     context.setDefaultNavigationTimeout(0);
-    if (scenario.browser.mode === "connect")
-        await blockAttachedServiceWorkers(page);
     await installCookies(context, scenario, secrets);
 };
 export class PlaywrightScenarioSession {
@@ -62,8 +48,12 @@ export class PlaywrightScenarioSession {
     secrets;
     eventCapture;
     storage;
+    serviceWorkers;
     signal;
     #storageReleased = false;
+    #stopLoading = false;
+    cleanupLease;
+    #policyStopsLoading = false;
     constructor(opened, options) {
         this.opened = opened;
         this.mode = options.mode;
@@ -72,33 +62,66 @@ export class PlaywrightScenarioSession {
         this.secrets = options.secrets;
         this.eventCapture = options.eventCapture;
         this.storage = options.storage;
+        this.serviceWorkers = options.serviceWorkers;
         this.signal = options.signal;
         this.version = opened.browser.version();
         this.initialUrl = opened.page.url();
+        this.cleanupLease = new AnalysisCleanupLease(async () => {
+            await this.#closeResources();
+        }, {
+            get cleanupResources() {
+                return opened.cleanup.cleanupResources;
+            },
+        });
     }
     static async open(scenario, environment, options) {
         throwIfScenarioCancelled(options.signal);
         const secrets = BrowserScenarioSecrets.resolve(scenario, environment);
         if (secrets === undefined)
             throw new BrowserObservationError(OPERATION, "secret_unavailable");
-        const startedAt = Date.now();
+        const startedAt = performance.now();
+        const openingCleanup = new Set();
         const opening = openPlaywrightScenarioBrowser(scenario, environment, {
             signal: options.signal,
-            ...(options.retainCleanup === undefined
-                ? {}
-                : { retainCleanup: options.retainCleanup }),
+            retainCleanup: (lease) => {
+                openingCleanup.add(lease);
+                options.retainCleanup?.(lease);
+            },
         });
         let opened;
         try {
             opened = await withPlaywrightExecutionBoundary(() => opening, undefined, options.signal);
         }
         catch (cause) {
-            const lateCleanup = () => opening.then((lateOpened) => lateOpened.cleanup.close(undefined, options.signal), () => undefined);
-            options.retainCleanup?.(() => withPlaywrightExecutionBoundary(lateCleanup, 1_000));
-            void lateCleanup().catch((cleanupCause) => {
-                // best-effort cleanup: retainCleanup keeps the retry capability.
-                void cleanupCause;
+            let lateOpened;
+            let openingFailure;
+            const cleanup = new AnalysisCleanupLease(async () => {
+                try {
+                    lateOpened = await opening;
+                }
+                catch (cause) {
+                    openingFailure =
+                        cause instanceof AnalysisError &&
+                            !(options.signal?.aborted === true &&
+                                cause === options.signal.reason)
+                            ? cause
+                            : undefined;
+                    const results = await Promise.allSettled([...openingCleanup].map((lease) => lease.release()));
+                    const failures = results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+                    throwCleanupFailures(failures);
+                    if (openingFailure?.cleanupIncomplete === true)
+                        throw openingFailure;
+                    return;
+                }
+                await lateOpened.cleanup.release();
+            }, {
+                get cleanupResources() {
+                    return (lateOpened?.cleanup.cleanupResources ??
+                        openingFailure?.cleanupResources);
+                },
             });
+            options.retainCleanup?.(cleanup);
+            void withPlaywrightExecutionBoundary(() => cleanup.release(), 1_000).catch(() => undefined);
             throw cause;
         }
         const session = await this.initializeSession(opened, scenario, secrets, options);
@@ -107,6 +130,7 @@ export class PlaywrightScenarioSession {
                 waitUntil: "load",
                 timeout: 0,
             }), undefined, options.signal);
+            await withPlaywrightExecutionBoundary(() => session.serviceWorkers?.assertBlocked() ?? Promise.resolve(), undefined, options.signal);
             await withPlaywrightExecutionBoundary(() => session.storage?.settle() ?? Promise.resolve(), undefined, options.signal);
             return session;
         }
@@ -119,7 +143,7 @@ export class PlaywrightScenarioSession {
             catch (failure) {
                 cleanup = "incomplete";
                 cleanupFailure = { cause: failure };
-                options.retainCleanup?.(() => session.close());
+                options.retainCleanup?.(session.cleanupLease);
             }
             throw browserScenarioOperationFailure(cause, {
                 kind: "browser-scenario-observation",
@@ -139,8 +163,15 @@ export class PlaywrightScenarioSession {
     static async initializeSession(opened, scenario, secrets, options) {
         let events;
         let storage;
+        const serviceWorkers = scenario.browser.mode === "connect" &&
+            scenario.environment.service_workers === "block"
+            ? new PlaywrightScenarioServiceWorkers(opened.page, scenario.browser.cdp_endpoint, scenario.browser.target_id)
+            : undefined;
         try {
-            await withPlaywrightExecutionBoundary(() => initializePage(opened.context, opened.page, scenario, secrets), undefined, options.signal);
+            await withPlaywrightExecutionBoundary(async () => {
+                await serviceWorkers?.initialize();
+                await initializePage(opened.context, scenario, secrets);
+            }, undefined, options.signal);
             storage = await PlaywrightScenarioStorage.create(opened, scenario, secrets, {
                 ...(options.signal === undefined ? {} : { signal: options.signal }),
                 ...(options.retainCleanup === undefined
@@ -156,6 +187,7 @@ export class PlaywrightScenarioSession {
                 enabled: new Set(scenario.capture.events),
                 secrets,
                 network: scenario.capture.network,
+                limits: scenario.capture.limits,
                 ...(options.signal === undefined ? {} : { signal: options.signal }),
             });
             return new PlaywrightScenarioSession(opened, {
@@ -163,45 +195,74 @@ export class PlaywrightScenarioSession {
                 secrets,
                 eventCapture: events,
                 storage,
+                serviceWorkers,
                 signal: options.signal,
             });
         }
         catch (cause) {
             let storageReleased = false;
+            const storageStopsLoading = storage !== undefined && options.signal?.aborted === true;
+            let policyStopsLoading = !storageStopsLoading;
             const cleanup = async () => {
                 let storageFailure;
+                let policyFailure;
                 let browserFailure;
                 if (!storageReleased) {
                     try {
-                        await storage?.close(options.signal?.aborted === true);
+                        const result = await storage?.close(storageStopsLoading);
+                        if (storageStopsLoading && result?.loadingStopped !== true)
+                            policyStopsLoading = true;
                     }
                     catch (failure) {
                         storageFailure = { cause: failure };
+                        // Ownership transfers only after the storage attempt is no longer
+                        // in flight. Its failure does not establish that navigation stop
+                        // succeeded, so the policy owner must confirm it before release.
+                        policyStopsLoading = true;
                     }
                 }
                 try {
-                    await opened.cleanup.close(events === undefined
-                        ? undefined
-                        : () => events?.finish() ?? Promise.resolve(), options.signal);
+                    if (!opened.cleanup.browserClosed)
+                        await serviceWorkers?.close(policyStopsLoading);
                 }
                 catch (failure) {
-                    browserFailure = { cause: failure };
+                    policyFailure = { cause: failure };
+                }
+                if (policyFailure === undefined) {
+                    try {
+                        await opened.cleanup.release(events === undefined
+                            ? undefined
+                            : () => events?.finish() ?? Promise.resolve());
+                    }
+                    catch (failure) {
+                        browserFailure = { cause: failure };
+                    }
+                }
+                else {
+                    try {
+                        await events?.finish();
+                    }
+                    catch (failure) {
+                        browserFailure = { cause: failure };
+                    }
                 }
                 if (opened.cleanup.browserClosed)
                     storageReleased = true;
                 throwCleanupFailures([
+                    ...(policyFailure === undefined ? [] : [policyFailure.cause]),
                     ...(storageReleased || storageFailure === undefined
                         ? []
                         : [storageFailure.cause]),
                     ...(browserFailure === undefined ? [] : [browserFailure.cause]),
                 ]);
             };
+            const recovery = new AnalysisCleanupLease(cleanup, opened.cleanup);
             try {
-                return await failBrowserScenarioOperation(cleanup, cause);
+                return await failBrowserScenarioOperation(recovery, cause);
             }
             catch (failure) {
                 if (failure !== cause)
-                    options.retainCleanup?.(cleanup);
+                    options.retainCleanup?.(recovery);
                 throw failure;
             }
         }
@@ -237,6 +298,7 @@ export class PlaywrightScenarioSession {
         await withPlaywrightExecutionBoundary(() => this.storage?.settle() ?? Promise.resolve(), undefined, signal);
     }
     async capture(requested, signal) {
+        await withPlaywrightExecutionBoundary(() => this.serviceWorkers?.assertBlocked() ?? Promise.resolve(), undefined, signal);
         await withPlaywrightExecutionBoundary(() => this.storage?.settle() ?? Promise.resolve(), undefined, signal);
         return withPlaywrightExecutionBoundary(() => capturePlaywrightStepArtifacts({
             context: this.opened.context,
@@ -246,33 +308,76 @@ export class PlaywrightScenarioSession {
         }), undefined, signal);
     }
     async close(stopLoading = this.signal?.aborted === true) {
+        this.#stopLoading ||= stopLoading;
+        try {
+            await withPlaywrightExecutionBoundary(() => this.cleanupLease.release(), PLAYWRIGHT_CLEANUP_CONFIRMATION_TIMEOUT_MS);
+        }
+        catch (cause) {
+            const error = new BrowserObservationError(OPERATION, "cleanup_failed", {
+                cause,
+                cleanup: {
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                    resources: this.cleanupLease.cleanupResources ?? [],
+                },
+            });
+            new AnalysisCleanupLeaseGroup(error, [this.cleanupLease]);
+            throw error;
+        }
+        return this.mode === "launch"
+            ? "terminated-owned-process"
+            : "disconnected-external";
+    }
+    async #closeResources() {
+        const stopLoading = this.#stopLoading || this.signal?.aborted === true;
         let storageFailure;
+        let policyFailure;
         let browserFailure;
+        if (stopLoading && this.storage === undefined)
+            this.#policyStopsLoading = true;
         if (!this.#storageReleased) {
             try {
-                await this.storage?.close(stopLoading);
+                const result = await this.storage?.close(stopLoading);
+                if (stopLoading && result?.loadingStopped !== true)
+                    this.#policyStopsLoading = true;
             }
             catch (failure) {
                 storageFailure = { cause: failure };
+                if (stopLoading)
+                    this.#policyStopsLoading = true;
             }
         }
         try {
-            await this.opened.cleanup.close(() => this.eventCapture.finish());
+            if (!this.opened.cleanup.browserClosed)
+                await this.serviceWorkers?.close(this.#policyStopsLoading);
         }
         catch (failure) {
-            browserFailure = { cause: failure };
+            policyFailure = { cause: failure };
+        }
+        if (policyFailure === undefined) {
+            try {
+                await this.opened.cleanup.release(() => this.eventCapture.finish());
+            }
+            catch (failure) {
+                browserFailure = { cause: failure };
+            }
+        }
+        else {
+            try {
+                await this.eventCapture.finish();
+            }
+            catch (failure) {
+                browserFailure = { cause: failure };
+            }
         }
         if (this.opened.cleanup.browserClosed)
             this.#storageReleased = true;
         throwCleanupFailures([
+            ...(policyFailure === undefined ? [] : [policyFailure.cause]),
             ...(this.#storageReleased || storageFailure === undefined
                 ? []
                 : [storageFailure.cause]),
             ...(browserFailure === undefined ? [] : [browserFailure.cause]),
         ]);
-        return this.mode === "launch"
-            ? "terminated-owned-process"
-            : "disconnected-external";
     }
     redactError(error) {
         return this.secrets.redact(error instanceof Error ? error.message : "browser action failed");

package/dist/browser/PlaywrightScenarioStorage.js

@@ -1,3 +1,4 @@
+import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import { BrowserObservationError } from "../domain/browserObservationError.js";
@@ -72,6 +73,7 @@ export class PlaywrightScenarioStorage {
     #generation = 0;
     #closed = false;
     #cleanupCompleted = false;
+    #loadingStopped = false;
     #failure;
     #closePromise;
     #detachPromise;
@@ -109,8 +111,11 @@ export class PlaywrightScenarioStorage {
                         detached = true;
                     }
                 };
-                retainCleanup?.(lateCleanup);
-                void withPlaywrightExecutionBoundary(lateCleanup, STORAGE_CLEANUP_TIMEOUT_MS).catch(() => undefined);
+                const cleanup = new AnalysisCleanupLease(lateCleanup, [
+                    "browser_storage_transport",
+                ]);
+                retainCleanup?.(cleanup);
+                void withPlaywrightExecutionBoundary(() => cleanup.release(), STORAGE_CLEANUP_TIMEOUT_MS).catch(() => undefined);
             }
             throw cause;
         }
@@ -126,10 +131,10 @@ export class PlaywrightScenarioStorage {
     }
     async initializeRoot(page, context) {
         const rootInfo = targetInfoResponse.parse(await this.cdp.send("Target.getTargetInfo"));
-        const root = this.createTarget(undefined, rootInfo.targetInfo.targetId, (method, params) => this.cdp.send(method, params));
-        this.#targets.set("", root);
         if (this.#closed)
             return;
+        const root = this.createTarget(undefined, rootInfo.targetInfo.targetId, (method, params) => this.cdp.send(method, params));
+        this.#targets.set("", root);
         this.listen(page, context);
         const ready = this.initializeTarget(root);
         root.ready = ready;
@@ -435,7 +440,7 @@ export class PlaywrightScenarioStorage {
     }
     close(stopLoading = false) {
         if (this.#cleanupCompleted)
-            return Promise.resolve();
+            return Promise.resolve({ loadingStopped: this.#loadingStopped });
         if (this.#closePromise !== undefined)
             return this.#closePromise;
         const closing = this.closeResources(stopLoading).catch((cause) => {
@@ -457,11 +462,13 @@ export class PlaywrightScenarioStorage {
     async closeResources(stopLoading) {
         this.#closed = true;
         let stopLoadingFailure;
-        if (stopLoading) {
+        if (stopLoading && !this.#loadingStopped) {
             try {
                 const root = this.#targets.get("");
-                if (root !== undefined)
+                if (root !== undefined) {
                     await withPlaywrightExecutionBoundary(() => root.send("Page.stopLoading"), STORAGE_CLEANUP_TIMEOUT_MS);
+                    this.#loadingStopped = true;
+                }
             }
             catch (cause) {
                 stopLoadingFailure = { cause };
@@ -503,5 +510,6 @@ export class PlaywrightScenarioStorage {
         this.#cleanupCompleted = true;
         if (stopLoadingFailure !== undefined)
             throw stopLoadingFailure.cause;
+        return { loadingStopped: this.#loadingStopped };
     }
 }

package/dist/browser/StructuredFieldToken.js

@@ -0,0 +1,53 @@
+// RFC 9651 sections 4.2.3–4.2.10. Consume complete items, without retaining
+// parameter values that the response-declaration projection does not expose.
+const token = /[A-Za-z*][A-Za-z0-9!#$%&'*+.^_`|~:/\x2d]*/uy;
+const key = /[a-z*][a-z0-9_.*\x2d]*/uy;
+const bareItem = /(?:[A-Za-z*][A-Za-z0-9!#$%&'*+.^_`|~:/\x2d]*|"(?:[\x20-\x21\x23-\x5b\x5d-\x7e]|\\["\\])*"|-?[0-9]{1,12}\.[0-9]{1,3}|-?[0-9]{1,15}|\?[01]|@-?[0-9]{1,15}|:(?<bytes>[A-Za-z0-9+/]*={0,2}):|%"(?<display>(?:[\x20-\x21\x23-\x24\x26-\x7e]|%[0-9a-f]{2})*)")/uy;
+/** Return the exact declared token only if the entire Structured Field Item is valid. */
+export const structuredFieldToken = (value) => {
+    if (value === undefined)
+        return null;
+    let cursor = 0;
+    while (value[cursor] === " ")
+        cursor += 1;
+    token.lastIndex = cursor;
+    const declared = token.exec(value)?.[0];
+    if (declared === undefined)
+        return null;
+    cursor = token.lastIndex;
+    while (value[cursor] === ";") {
+        cursor += 1;
+        while (value[cursor] === " ")
+            cursor += 1;
+        key.lastIndex = cursor;
+        if (key.exec(value) === null)
+            return null;
+        cursor = key.lastIndex;
+        if (value[cursor] !== "=")
+            continue;
+        bareItem.lastIndex = cursor + 1;
+        const parameter = bareItem.exec(value);
+        if (parameter === null)
+            return null;
+        cursor = bareItem.lastIndex;
+        const bytes = parameter.groups?.bytes;
+        if (bytes !== undefined) {
+            const padded = bytes.endsWith("=");
+            if (padded ? bytes.length % 4 !== 0 : bytes.length % 4 === 1)
+                return null;
+        }
+        const display = parameter.groups?.display;
+        if (display !== undefined) {
+            try {
+                // Percent syntax was checked above; this rejects invalid UTF-8 octets.
+                decodeURIComponent(display);
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    while (value[cursor] === " ")
+        cursor += 1;
+    return cursor === value.length ? declared : null;
+};

package/dist/browser/WebArtifactCleanup.js

@@ -0,0 +1,53 @@
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+export const webArtifactCleanupFailures = (owner, operation, failures) => {
+    if (failures.length === 0)
+        return undefined;
+    const normalized = failures.map(({ resource, cause }) => {
+        if (cause instanceof AnalysisError) {
+            const projection = projectAnalysisError(cause);
+            return {
+                cause,
+                projection,
+                observation: {
+                    reason: projection.message,
+                    resources: cause.cleanupResources.length === 0
+                        ? [resource]
+                        : cause.cleanupResources,
+                },
+            };
+        }
+        return {
+            cause,
+            projection: undefined,
+            observation: ArtifactReaderFailure.cleanupObservation(cause, resource),
+        };
+    });
+    const recoveryActions = [
+        ...new Set(normalized.flatMap(({ projection }) => projection === undefined ? [] : [projection.remediation.action])),
+    ];
+    return new ProviderCleanupError(owner, [
+        ...new Set(normalized.flatMap(({ observation }) => observation.resources)),
+    ], {
+        reason: normalized
+            .map(({ observation }) => observation.reason)
+            .join("; "),
+        failures: normalized.map(({ cause, projection, observation }) => projection !== undefined
+            ? projection
+            : {
+                name: cause instanceof Error ? cause.name : "UnknownError",
+                message: cause instanceof Error ? cause.message : String(cause),
+                resource: [...observation.resources],
+            }),
+    }, {
+        cause: normalized.length === 1
+            ? normalized[0].cause
+            : new AggregateError(normalized.map(({ cause }) => cause), `${owner} cleanup failed`),
+        operation,
+        ...(recoveryActions.length === 0
+            ? {}
+            : { remediationAction: recoveryActions.join("; ") }),
+    });
+};