rea-agents 6.0.0 → 6.2.0

package/dist/browser/PlaywrightScenarioBrowser.js

@@ -2,9 +2,90 @@ import { chmod, mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { chromium, } from "playwright-core";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
 import { BrowserObservationError } from "../domain/browserObservationError.js";
 import { withPlaywrightExecutionBoundary } from "./PlaywrightExecutionBoundary.js";
 const OPERATION = "capture_browser_scenario";
+/** Owns one browser connection and optional private profile through cleanup retries. */
+export class PlaywrightScenarioBrowserCleanupOwner {
+    resources;
+    #browserClosed = false;
+    #profileRemoved;
+    #closePromise;
+    #eventFinalizationPromise;
+    /** Keep the narrow provider actions needed to release one opened browser. */
+    constructor(resources) {
+        this.resources = resources;
+        this.#profileRemoved = resources.removeProfile === undefined;
+    }
+    close(finishEvents, signal) {
+        const cleanup = this.#closePromise ?? this.#closeResources(finishEvents);
+        if (this.#closePromise === undefined) {
+            this.#closePromise = cleanup;
+            void cleanup.catch(() => {
+                if (this.#closePromise === cleanup)
+                    this.#closePromise = undefined;
+            });
+        }
+        return this.#awaitCleanup(cleanup, signal);
+    }
+    async #awaitCleanup(cleanup, signal) {
+        try {
+            await withPlaywrightExecutionBoundary(() => cleanup, 1_000, signal);
+        }
+        catch (cause) {
+            throw new BrowserObservationError(OPERATION, "cleanup_failed", {
+                cause,
+                cleanup: {
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                    resources: [
+                        "browser_transport",
+                        ...(this.resources.removeProfile === undefined
+                            ? []
+                            : ["browser_profile"]),
+                    ],
+                },
+            });
+        }
+    }
+    async #closeResources(finishEvents) {
+        const failures = [];
+        const eventFinalization = (this.#eventFinalizationPromise ??=
+            Promise.resolve().then(async () => {
+                await finishEvents?.();
+            }));
+        try {
+            await eventFinalization;
+        }
+        catch (cause) {
+            failures.push(cause);
+        }
+        if (!this.#browserClosed) {
+            try {
+                await this.resources.closeBrowser();
+                this.#browserClosed = true;
+            }
+            catch (cause) {
+                failures.push(cause);
+            }
+        }
+        if (this.#browserClosed &&
+            !this.#profileRemoved &&
+            this.resources.removeProfile !== undefined) {
+            try {
+                await this.resources.removeProfile();
+                this.#profileRemoved = true;
+            }
+            catch (cause) {
+                failures.push(cause);
+            }
+        }
+        if (failures.length === 1)
+            throw failures[0];
+        if (failures.length > 1)
+            throw new AggregateError(failures, "Browser session cleanup failed");
+    }
+}
 const allowedBrowserEnvironment = (environment) => {
     const allowed = [
         "DBUS_SESSION_BUS_ADDRESS",
@@ -69,23 +150,57 @@ const configureAttachedEnvironment = async (context, page, scenario) => {
         await session.detach();
     }
 };
-export const openPlaywrightScenarioBrowser = async (scenario, environment) => {
+/** Preserve an operation failure while reporting any incomplete cleanup. */
+export const failBrowserScenarioOperation = async (cleanup, primaryFailure, fallbackCleanupResources = ["browser_transport"]) => {
+    try {
+        await cleanup();
+    }
+    catch (cleanupFailure) {
+        const cleanupDetails = cleanupFailure instanceof AnalysisError &&
+            cleanupFailure.cleanup !== undefined
+            ? cleanupFailure.cleanup
+            : {
+                reason: cleanupFailure instanceof Error
+                    ? cleanupFailure.message
+                    : String(cleanupFailure),
+                resources: cleanupFailure instanceof AnalysisError
+                    ? cleanupFailure.cleanupResources
+                    : fallbackCleanupResources,
+            };
+        throw new BrowserObservationError(OPERATION, "cleanup_failed", {
+            cause: new AggregateError([primaryFailure, cleanupFailure], "Browser scenario operation and cleanup both failed", { cause: primaryFailure }),
+            cleanup: cleanupDetails,
+        });
+    }
+    throw primaryFailure;
+};
+/** Launch or attach using the caller-selected environment and browser engine. */
+export const openPlaywrightScenarioBrowser = async (scenario, environment, launcher = chromium) => {
     if (scenario.browser.mode === "connect") {
-        const browser = await chromium.connectOverCDP(scenario.browser.cdp_endpoint, { timeout: 0 });
+        const browser = await launcher.connectOverCDP(scenario.browser.cdp_endpoint, { timeout: 0 });
+        const cleanup = new PlaywrightScenarioBrowserCleanupOwner({
+            closeBrowser: () => browser.close(),
+            removeProfile: undefined,
+        });
         try {
             const target = await findConnectedPage(browser, scenario.browser.target_id);
             await configureAttachedEnvironment(target.context, target.page, scenario);
-            return { ...target, browser, profilePath: undefined };
+            return {
+                ...target,
+                browser,
+                profilePath: undefined,
+                cleanup,
+            };
         }
         catch (cause) {
-            await browser.close();
-            throw cause;
+            return failBrowserScenarioOperation(() => cleanup.close(), cause);
         }
     }
     const profilePath = await mkdtemp(join(tmpdir(), "rea-browser-scenario-"));
-    await chmod(profilePath, 0o700);
+    let context;
     try {
-        const context = await chromium.launchPersistentContext(profilePath, {
+        await chmod(profilePath, 0o700);
+        context = await launcher.launchPersistentContext(profilePath, {
             executablePath: resolve(scenario.browser.executable_path),
             headless: scenario.browser.headless,
             acceptDownloads: false,
@@ -105,43 +220,28 @@ export const openPlaywrightScenarioBrowser = async (scenario, environment) => {
             handleSIGTERM: false,
             timeout: 0,
         });
-        const browser = context.browser();
-        if (browser === null) {
-            await context.close();
-            throw new BrowserObservationError(OPERATION, "protocol_error");
-        }
-        const page = context.pages()[0] ?? (await context.newPage());
-        return { context, page, browser, profilePath };
     }
     catch (cause) {
-        await rm(profilePath, { recursive: true, force: true, maxRetries: 3 });
-        throw cause;
+        return failBrowserScenarioOperation(() => rm(profilePath, { recursive: true, force: true, maxRetries: 3 }), cause, ["browser_profile"]);
     }
-};
-export const closePlaywrightScenarioBrowser = async ({ context, browser, profilePath }, signal) => {
-    const cleanup = (async () => {
-        try {
-            // In connect mode Playwright's Browser.close disconnects its CDP client;
-            // it does not close the externally owned browser process.
-            if (profilePath === undefined)
-                await browser.close();
-            else
-                await context.close();
-        }
-        finally {
-            if (profilePath !== undefined)
-                await rm(profilePath, { recursive: true, force: true, maxRetries: 3 });
-        }
-    })();
-    // best-effort cleanup: the bounded execution boundary below observes the
-    // same cleanup promise; this early attachment only prevents unhandled rejection.
-    void cleanup.catch(() => undefined);
-    // The shared execution boundary rejects cancellation/timeouts instead of
-    // returning a successful capture whose browser or profile may still exist.
+    const cleanup = new PlaywrightScenarioBrowserCleanupOwner({
+        closeBrowser: () => context.close(),
+        removeProfile: () => rm(profilePath, { recursive: true, force: true, maxRetries: 3 }),
+    });
     try {
-        await withPlaywrightExecutionBoundary(() => cleanup, 1_000, signal);
+        const browser = context.browser();
+        if (browser === null)
+            throw new BrowserObservationError(OPERATION, "protocol_error");
+        const page = context.pages()[0] ?? (await context.newPage());
+        return {
+            context,
+            page,
+            browser,
+            profilePath,
+            cleanup,
+        };
     }
     catch (cause) {
-        throw new BrowserObservationError(OPERATION, "cleanup_failed", { cause });
+        return failBrowserScenarioOperation(() => cleanup.close(), cause);
     }
 };

package/dist/browser/PlaywrightScenarioEvents.js

@@ -1,4 +1,4 @@
-import { browserScenarioEventSchema, } from "../domain/browserScenarioCapture.js";
+import { browserScenarioEventSchema, } from "../domain/browserScenarioCaptureValues.js";
 import { PlaywrightScenarioNetwork } from "./network/PlaywrightScenarioNetwork.js";
 /** Arrival-ordered Playwright event capture with current-step attribution. */
 export class PlaywrightScenarioEvents {

package/dist/browser/PlaywrightScenarioSession.js

@@ -1,11 +1,12 @@
 import {} from "playwright-core";
 import { BrowserObservationError } from "../domain/browserObservationError.js";
 import { BrowserScenarioSecrets } from "./BrowserScenarioSecrets.js";
-import { closePlaywrightScenarioBrowser, openPlaywrightScenarioBrowser, } from "./PlaywrightScenarioBrowser.js";
+import { failBrowserScenarioOperation, openPlaywrightScenarioBrowser, } from "./PlaywrightScenarioBrowser.js";
 import { performPlaywrightScenarioAction } from "./PlaywrightScenarioActions.js";
 import { capturePlaywrightStepArtifacts } from "./PlaywrightScenarioArtifacts.js";
 import { PlaywrightScenarioEvents } from "./PlaywrightScenarioEvents.js";
 import { withPlaywrightExecutionBoundary } from "./PlaywrightExecutionBoundary.js";
+import { browserScenarioCaptureData, browserScenarioOperationFailure, } from "./BrowserScenarioPartialObservation.js";
 const OPERATION = "capture_browser_scenario";
 const storageSeeds = (blocks, secrets) => {
     const seeds = {};
@@ -66,10 +67,8 @@ export class PlaywrightScenarioSession {
     product = "Chromium";
     version;
     initialUrl;
-    closed = false;
     secrets;
     eventCapture;
-    signal;
     constructor(opened, options) {
         this.opened = opened;
         this.mode = options.mode;
@@ -77,7 +76,6 @@ export class PlaywrightScenarioSession {
             options.mode === "launch" ? "provider-owned" : "external";
         this.secrets = options.secrets;
         this.eventCapture = options.eventCapture;
-        this.signal = options.signal;
         this.version = opened.browser.version();
         this.initialUrl = opened.page.url();
     }
@@ -87,23 +85,26 @@ export class PlaywrightScenarioSession {
         const secrets = BrowserScenarioSecrets.resolve(scenario, environment);
         if (secrets === undefined)
             throw new BrowserObservationError(OPERATION, "secret_unavailable");
+        const startedAt = Date.now();
         const opening = openPlaywrightScenarioBrowser(scenario, environment);
         let opened;
+        let events;
         try {
             opened = await withPlaywrightExecutionBoundary(() => opening, undefined, options.signal);
         }
         catch (cause) {
             void opening
-                .then((lateOpened) => closePlaywrightScenarioBrowser(lateOpened, options.signal))
+                .then((lateOpened) => lateOpened.cleanup.close(undefined, options.signal))
                 .catch((cause) => {
                 // best-effort cleanup: late-open cleanup must not mask the boundary failure.
                 void cause;
             });
             throw cause;
         }
+        let session;
         try {
             await withPlaywrightExecutionBoundary(() => initializePage(opened.context, opened.page, scenario, secrets), undefined, options.signal);
-            const events = new PlaywrightScenarioEvents({
+            events = new PlaywrightScenarioEvents({
                 page: opened.page,
                 context: opened.context,
                 ownsContext: scenario.browser.mode === "launch",
@@ -112,12 +113,18 @@ export class PlaywrightScenarioSession {
                 network: scenario.capture.network,
                 ...(options.signal === undefined ? {} : { signal: options.signal }),
             });
-            const session = new PlaywrightScenarioSession(opened, {
+            session = new PlaywrightScenarioSession(opened, {
                 mode: scenario.browser.mode,
                 secrets,
                 eventCapture: events,
-                ...(options.signal === undefined ? {} : { signal: options.signal }),
             });
+        }
+        catch (cause) {
+            return failBrowserScenarioOperation(() => opened.cleanup.close(events === undefined
+                ? undefined
+                : () => events?.finish() ?? Promise.resolve(), options.signal), cause);
+        }
+        try {
             await withPlaywrightExecutionBoundary(() => opened.page.goto(secrets.url(scenario.start_url), {
                 waitUntil: "load",
                 timeout: 0,
@@ -125,8 +132,28 @@ export class PlaywrightScenarioSession {
             return session;
         }
         catch (cause) {
-            await closePlaywrightScenarioBrowser(opened, options.signal);
-            throw cause;
+            let cleanup;
+            let cleanupFailure;
+            try {
+                cleanup = await session.close();
+            }
+            catch (failure) {
+                cleanup = "incomplete";
+                cleanupFailure = { cause: failure };
+            }
+            throw browserScenarioOperationFailure(cause, {
+                kind: "browser-scenario-observation",
+                capture: browserScenarioCaptureData({
+                    session,
+                    scenario,
+                    startedAt,
+                    steps: [],
+                    cleanup,
+                    limitations: [
+                        "Scenario navigation failed before the initial state was captured.",
+                    ],
+                }),
+            }, cleanupFailure);
         }
     }
     currentUrl() {
@@ -167,17 +194,7 @@ export class PlaywrightScenarioSession {
         }), undefined, signal);
     }
     async close() {
-        if (this.closed)
-            return this.mode === "launch"
-                ? "terminated-owned-process"
-                : "disconnected-external";
-        this.closed = true;
-        try {
-            await this.eventCapture.finish();
-        }
-        finally {
-            await closePlaywrightScenarioBrowser(this.opened, this.signal);
-        }
+        await this.opened.cleanup.close(() => this.eventCapture.finish());
         return this.mode === "launch"
             ? "terminated-owned-process"
             : "disconnected-external";
@@ -189,7 +206,7 @@ export class PlaywrightScenarioSession {
 /** Production Playwright/CDP session factory. */
 export class PlaywrightScenarioSessionFactory {
     environment;
-    constructor(environment = process.env) {
+    constructor(environment) {
         this.environment = environment;
     }
     open(scenario, options = {}) {