rea-agents 2.4.0 → 2.5.0

package/dist/browser/PlaywrightExecutionBoundary.js

@@ -0,0 +1,42 @@
+import { AnalysisCancelledError, AnalysisTimeoutError, } from "../domain/errors.js";
+const OPERATION = "capture_browser_scenario";
+export const withPlaywrightExecutionBoundary = (work, maximumTimeoutMs, signal) => {
+    if (maximumTimeoutMs <= 0)
+        return Promise.reject(new AnalysisTimeoutError(OPERATION, maximumTimeoutMs));
+    if (signal?.aborted === true)
+        return Promise.reject(new AnalysisCancelledError(OPERATION));
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let timer;
+        const cleanup = () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        const succeed = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(value);
+        };
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error);
+        };
+        const onAbort = () => {
+            fail(new AnalysisCancelledError(OPERATION));
+        };
+        timer = setTimeout(() => fail(new AnalysisTimeoutError(OPERATION, maximumTimeoutMs)), maximumTimeoutMs);
+        timer.unref();
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted === true) {
+            onAbort();
+            return;
+        }
+        void work().then(succeed, fail);
+    });
+};

package/dist/browser/PlaywrightScenarioActions.js

@@ -0,0 +1,62 @@
+const resolveLocator = (page, locator) => {
+    switch (locator.kind) {
+        case "test_id":
+            return page.getByTestId(locator.value);
+        case "role":
+            return page.getByRole(locator.role, {
+                name: locator.name,
+                exact: locator.exact,
+            });
+        case "css":
+            return page.locator(locator.selector);
+    }
+};
+const resolveValue = (value, secrets) => secrets.value(value);
+/** Execute one admitted declarative action with no caller-supplied code. */
+export const performPlaywrightScenarioAction = async (input) => {
+    const { page, action, secrets, defaultTimeoutMs, maximumTimeoutMs } = input;
+    const timeout = "timeout_ms" in action ? action.timeout_ms : undefined;
+    const options = {
+        timeout: Math.min(timeout ?? defaultTimeoutMs, maximumTimeoutMs),
+    };
+    switch (action.action) {
+        case "goto":
+            await page.goto(secrets.url(action.destination), {
+                timeout: options.timeout,
+                waitUntil: action.wait_until,
+            });
+            return;
+        case "click":
+            await resolveLocator(page, action.locator).click({
+                ...options,
+                button: action.button,
+                clickCount: action.click_count,
+            });
+            return;
+        case "fill":
+            await resolveLocator(page, action.locator).fill(resolveValue(action.value, secrets), options);
+            return;
+        case "press":
+            await resolveLocator(page, action.locator).press(action.key, options);
+            return;
+        case "select_option":
+            await resolveLocator(page, action.locator).selectOption(resolveValue(action.value, secrets), options);
+            return;
+        case "check":
+            await resolveLocator(page, action.locator).check(options);
+            return;
+        case "uncheck":
+            await resolveLocator(page, action.locator).uncheck(options);
+            return;
+        case "wait_for":
+            await resolveLocator(page, action.locator).waitFor({
+                ...options,
+                state: action.state,
+            });
+            return;
+        case "wait_for_timeout":
+            if (action.duration_ms > maximumTimeoutMs)
+                throw new Error("Scenario duration limit reached");
+            await page.waitForTimeout(action.duration_ms);
+    }
+};

package/dist/browser/PlaywrightScenarioArtifacts.js

@@ -0,0 +1,238 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { sanitizeBrowserUrl } from "../domain/browserObservation.js";
+import { browserStepArtifactsSchema, } from "../domain/browserScenarioCapture.js";
+const TEXT_ARTIFACT_MAX_BYTES = 1_048_576;
+const historyValueSchema = z.strictObject({
+    length: z.number().int().min(0),
+    navigation_entries: z
+        .array(z.strictObject({
+        type: z.string(),
+        name: z.string(),
+    }))
+        .max(10_000),
+});
+const storageValueSchema = z.strictObject({
+    local_storage: z.array(z.tuple([z.string(), z.string()])).max(10_000),
+    session_storage: z.array(z.tuple([z.string(), z.string()])).max(10_000),
+});
+/** Shared retained-count budget for one scenario's screenshot artifacts. */
+export class BrowserScenarioCaptureBudget {
+    maximumScreenshots;
+    maximumMetadataBytes;
+    screenshotCount = 0;
+    metadataBytes = 0;
+    constructor(maximumScreenshots, maximumMetadataBytes) {
+        this.maximumScreenshots = maximumScreenshots;
+        this.maximumMetadataBytes = maximumMetadataBytes;
+    }
+    claimScreenshot() {
+        if (this.screenshotCount >= this.maximumScreenshots)
+            return false;
+        this.screenshotCount += 1;
+        return true;
+    }
+    claimMetadata(bytes) {
+        if (this.metadataBytes + bytes > this.maximumMetadataBytes)
+            return false;
+        this.metadataBytes += bytes;
+        return true;
+    }
+}
+const notRequested = () => ({ state: "not_requested" });
+const missing = (reason) => ({ state: "missing", reason });
+const truncated = (observed, retained, reason) => ({
+    state: "truncated",
+    observed,
+    retained,
+    reason,
+});
+const textArtifact = (text, maximumBytes, budget) => {
+    const bytes = Buffer.from(text);
+    if (bytes.byteLength > maximumBytes)
+        return truncated(bytes.byteLength, 0, `artifact exceeds ${maximumBytes} bytes`);
+    if (!budget.claimMetadata(bytes.byteLength))
+        return truncated(bytes.byteLength, 0, "scenario metadata byte limit reached");
+    return {
+        state: "captured",
+        value: {
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+            bytes: bytes.byteLength,
+            text,
+        },
+    };
+};
+const metadataArtifact = (value, budget) => {
+    const bytes = Buffer.byteLength(JSON.stringify(value));
+    return budget.claimMetadata(bytes)
+        ? { state: "captured", value }
+        : truncated(bytes, 0, "scenario metadata byte limit reached");
+};
+const captureScreenshot = async (page, scenario, budget) => {
+    if (!budget.claimScreenshot())
+        return truncated(1, 0, "scenario screenshot count limit reached");
+    try {
+        const bytes = await page.screenshot({
+            type: "png",
+            fullPage: false,
+            animations: "disabled",
+            caret: "hide",
+        });
+        if (bytes.byteLength > scenario.limits.max_screenshot_bytes)
+            return truncated(bytes.byteLength, 0, "screenshot byte limit reached");
+        const sha256 = createHash("sha256").update(bytes).digest("hex");
+        return {
+            state: "captured",
+            value: {
+                uri: `rea://web-screenshot/sha256/${sha256}`,
+                sha256,
+                bytes: bytes.byteLength,
+                media_type: "image/png",
+                data_base64: bytes.toString("base64"),
+            },
+        };
+    }
+    catch {
+        return missing("screenshot capture failed");
+    }
+};
+const captureDom = async (input) => {
+    const { page, secrets, maximumBytes, maximumNodes, budget } = input;
+    try {
+        const nodes = await page.locator("*").count();
+        if (nodes > maximumNodes)
+            return truncated(nodes, 0, "DOM node limit reached");
+        return textArtifact(secrets.redact(await page.content()), Math.min(maximumBytes, TEXT_ARTIFACT_MAX_BYTES), budget);
+    }
+    catch {
+        return missing("DOM capture failed");
+    }
+};
+const captureAccessibility = async (input) => {
+    const { page, secrets, maximumBytes, maximumNodes, budget } = input;
+    try {
+        const text = await page.locator("html").ariaSnapshot();
+        const nodes = text.split("\n").filter((line) => line.trim() !== "").length;
+        if (nodes > maximumNodes)
+            return truncated(nodes, 0, "accessibility node limit reached");
+        return textArtifact(secrets.redact(text), Math.min(maximumBytes, TEXT_ARTIFACT_MAX_BYTES), budget);
+    }
+    catch {
+        return missing("accessibility capture failed");
+    }
+};
+const navigationType = (value) => {
+    switch (value) {
+        case "navigate":
+        case "reload":
+        case "back_forward":
+        case "prerender":
+            return value;
+        default:
+            return "unknown";
+    }
+};
+const captureHistory = async (page, budget) => {
+    try {
+        const raw = historyValueSchema.parse(await page.evaluate(`(() => ({
+        length: window.history.length,
+        navigation_entries: performance.getEntriesByType("navigation").map(
+          entry => ({
+            type: typeof entry.type === "string" ? entry.type : "unknown",
+            name: entry.name
+          })
+        )
+      }))()`));
+        if (raw.navigation_entries.length > 256)
+            return truncated(raw.navigation_entries.length, 0, "navigation history entry limit reached");
+        const value = {
+            length: raw.length,
+            current_url: sanitizeBrowserUrl(page.url()),
+            navigation_entries: raw.navigation_entries.map(({ type, name }) => ({
+                type: navigationType(type),
+                name: sanitizeBrowserUrl(name),
+            })),
+        };
+        return metadataArtifact(value, budget);
+    }
+    catch {
+        return missing("history capture failed");
+    }
+};
+const captureStorage = async (input) => {
+    const { context, page, scenario, secrets, budget } = input;
+    try {
+        const cookies = await context.cookies(scenario.allowed_origins);
+        const pageStorage = storageValueSchema.parse(await page.evaluate(`(() => ({
+        local_storage: Object.entries(window.localStorage),
+        session_storage: Object.entries(window.sessionStorage)
+      }))()`));
+        const observed = cookies.length +
+            pageStorage.local_storage.length +
+            pageStorage.session_storage.length;
+        if (observed > scenario.limits.max_storage_entries)
+            return truncated(observed, 0, "storage entry limit reached");
+        const value = {
+            cookies: cookies.map((cookie) => ({
+                name: cookie.name,
+                domain: cookie.domain,
+                path: cookie.path,
+                secure: cookie.secure,
+                http_only: cookie.httpOnly,
+                same_site: cookie.sameSite,
+                ...secrets.fingerprint(cookie.value),
+            })),
+            local_storage: pageStorage.local_storage.map(([name, value]) => ({
+                name,
+                ...secrets.fingerprint(value),
+            })),
+            session_storage: pageStorage.session_storage.map(([name, value]) => ({
+                name,
+                ...secrets.fingerprint(value),
+            })),
+        };
+        return metadataArtifact(value, budget);
+    }
+    catch {
+        return missing("storage capture failed");
+    }
+};
+const isAllowedPage = (page, allowedOrigins) => {
+    try {
+        return allowedOrigins.has(new URL(page.url()).origin);
+    }
+    catch {
+        return false;
+    }
+};
+/** Capture selected step artifacts without retaining data after scope loss. */
+export const capturePlaywrightStepArtifacts = async (input) => {
+    const { context, page, scenario, secrets, requested, budget } = input;
+    const allowed = isAllowedPage(page, new Set(scenario.allowed_origins));
+    const denied = () => missing("current page is outside approved origins");
+    const state = (kind, capture) => !requested.has(kind)
+        ? Promise.resolve(notRequested())
+        : allowed || kind === "url"
+            ? capture()
+            : Promise.resolve(denied());
+    return browserStepArtifactsSchema.parse({
+        screenshot: await state("screenshot", () => captureScreenshot(page, scenario, budget)),
+        dom: await state("dom", () => captureDom({
+            page,
+            secrets,
+            maximumBytes: scenario.limits.max_total_metadata_bytes,
+            maximumNodes: scenario.limits.max_dom_nodes,
+            budget,
+        })),
+        accessibility: await state("accessibility", () => captureAccessibility({
+            page,
+            secrets,
+            maximumBytes: scenario.limits.max_total_metadata_bytes,
+            maximumNodes: scenario.limits.max_accessibility_nodes,
+            budget,
+        })),
+        url: await state("url", async () => metadataArtifact(sanitizeBrowserUrl(page.url()), budget)),
+        history: await state("history", () => captureHistory(page, budget)),
+        storage: await state("storage", () => captureStorage({ context, page, scenario, secrets, budget })),
+    });
+};

package/dist/browser/PlaywrightScenarioBrowser.js

@@ -0,0 +1,144 @@
+import { chmod, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { chromium, } from "playwright-core";
+import { BrowserObservationError } from "../domain/errors.js";
+const OPERATION = "capture_browser_scenario";
+const allowedBrowserEnvironment = (environment) => {
+    const allowed = [
+        "DBUS_SESSION_BUS_ADDRESS",
+        "DISPLAY",
+        "HOME",
+        "LANG",
+        "LD_LIBRARY_PATH",
+        "PATH",
+        "SystemRoot",
+        "TEMP",
+        "TMP",
+        "TMPDIR",
+        "WAYLAND_DISPLAY",
+        "XAUTHORITY",
+        "XDG_RUNTIME_DIR",
+    ];
+    return Object.fromEntries(allowed
+        .map((name) => [name, environment[name]])
+        .filter((entry) => entry[1] !== undefined));
+};
+const originAllowed = (value, allowedOrigins) => {
+    try {
+        return allowedOrigins.has(new URL(value).origin);
+    }
+    catch {
+        return false;
+    }
+};
+const findConnectedPage = async (browser, targetId, allowedOrigins) => {
+    for (const context of browser.contexts())
+        for (const page of context.pages()) {
+            const session = await context.newCDPSession(page);
+            try {
+                const { targetInfo } = await session.send("Target.getTargetInfo");
+                if (targetInfo.targetId !== targetId)
+                    continue;
+                if (page.url() !== "about:blank" &&
+                    !originAllowed(page.url(), allowedOrigins))
+                    throw new BrowserObservationError(OPERATION, "target_not_allowed");
+                return { context, page };
+            }
+            finally {
+                await session.detach();
+            }
+        }
+    throw new BrowserObservationError(OPERATION, "target_not_found");
+};
+const configureAttachedEnvironment = async (context, page, scenario) => {
+    await page.setViewportSize({
+        width: scenario.environment.viewport.width,
+        height: scenario.environment.viewport.height,
+    });
+    await page.emulateMedia({
+        colorScheme: scenario.environment.color_scheme,
+        reducedMotion: scenario.environment.reduced_motion,
+    });
+    const session = await context.newCDPSession(page);
+    try {
+        await session.send("Emulation.setDeviceMetricsOverride", {
+            width: scenario.environment.viewport.width,
+            height: scenario.environment.viewport.height,
+            deviceScaleFactor: scenario.environment.viewport.device_scale_factor,
+            mobile: false,
+        });
+        await session.send("Emulation.setLocaleOverride", {
+            locale: scenario.environment.locale,
+        });
+        await session.send("Emulation.setTimezoneOverride", {
+            timezoneId: scenario.environment.timezone,
+        });
+    }
+    finally {
+        await session.detach();
+    }
+};
+export const openPlaywrightScenarioBrowser = async (scenario, environment, maximumTimeoutMs) => {
+    if (scenario.browser.mode === "connect") {
+        const browser = await chromium.connectOverCDP(scenario.browser.cdp_endpoint, {
+            timeout: Math.min(scenario.limits.navigation_timeout_ms, maximumTimeoutMs),
+        });
+        try {
+            const target = await findConnectedPage(browser, scenario.browser.target_id, new Set(scenario.allowed_origins));
+            await configureAttachedEnvironment(target.context, target.page, scenario);
+            return { ...target, browser, profilePath: undefined };
+        }
+        catch (error) {
+            await browser.close();
+            throw error;
+        }
+    }
+    const profilePath = await mkdtemp(join(tmpdir(), "rea-browser-scenario-"));
+    await chmod(profilePath, 0o700);
+    try {
+        const context = await chromium.launchPersistentContext(profilePath, {
+            executablePath: scenario.browser.executable_path,
+            headless: true,
+            acceptDownloads: false,
+            viewport: {
+                width: scenario.environment.viewport.width,
+                height: scenario.environment.viewport.height,
+            },
+            deviceScaleFactor: scenario.environment.viewport.device_scale_factor,
+            locale: scenario.environment.locale,
+            timezoneId: scenario.environment.timezone,
+            colorScheme: scenario.environment.color_scheme,
+            reducedMotion: scenario.environment.reduced_motion,
+            serviceWorkers: "block",
+            env: allowedBrowserEnvironment(environment),
+            handleSIGHUP: false,
+            handleSIGINT: false,
+            handleSIGTERM: false,
+            timeout: maximumTimeoutMs,
+        });
+        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 (error) {
+        await rm(profilePath, { recursive: true, force: true, maxRetries: 3 });
+        throw error;
+    }
+};
+export const closePlaywrightScenarioBrowser = async ({ context, browser, profilePath, }) => {
+    try {
+        if (profilePath === undefined)
+            await browser.close();
+        else
+            await context.close();
+    }
+    finally {
+        if (profilePath !== undefined)
+            await rm(profilePath, { recursive: true, force: true, maxRetries: 3 });
+    }
+};