rea-agents 2.3.0 → 2.5.0

package/dist/browser/PlaywrightScenarioEvents.js

@@ -0,0 +1,301 @@
+import { sanitizeBrowserUrl } from "../domain/browserObservation.js";
+import { browserScenarioEventSchema, } from "../domain/browserScenarioCapture.js";
+/** Bounded, arrival-ordered Playwright event capture with current-step attribution. */
+export class PlaywrightScenarioEvents {
+    items = [];
+    truncated = new Set();
+    admitted = {
+        frames: new WeakSet(),
+        workers: new WeakSet(),
+        popups: new WeakSet(),
+        websockets: new WeakSet(),
+    };
+    rejected = {
+        frames: new WeakSet(),
+        workers: new WeakSet(),
+        popups: new WeakSet(),
+        websockets: new WeakSet(),
+    };
+    counts = {
+        frames: 0,
+        workers: 0,
+        popups: 0,
+        websockets: 0,
+    };
+    dropped = 0;
+    stepIndex = 0;
+    sequence = 0;
+    enabled;
+    limits;
+    secrets;
+    budget;
+    allowedOrigins;
+    constructor(options) {
+        this.enabled = options.enabled;
+        this.limits = options.limits;
+        this.secrets = options.secrets;
+        this.budget = options.budget;
+        this.allowedOrigins = new Set(options.allowedOrigins);
+        this.observePage(options.page);
+    }
+    setStep(index) {
+        this.stepIndex = index;
+    }
+    nextSequence() {
+        return this.sequence + 1;
+    }
+    lastSequence() {
+        return this.sequence;
+    }
+    result() {
+        return {
+            retained: this.items.length,
+            dropped: this.dropped,
+            items: this.items,
+        };
+    }
+    truncationSections() {
+        return [...this.truncated].sort();
+    }
+    push(event) {
+        this.sequence += 1;
+        if (this.items.length >= this.limits.max_events) {
+            this.dropped += 1;
+            this.truncated.add("events");
+            return;
+        }
+        const parsed = browserScenarioEventSchema.parse({
+            ...event,
+            sequence: this.sequence,
+            step_index: this.stepIndex,
+        });
+        if (!this.budget.claimMetadata(Buffer.byteLength(JSON.stringify(parsed)))) {
+            this.dropped += 1;
+            this.truncated.add("events");
+            return;
+        }
+        this.items.push(parsed);
+    }
+    admit(section, value, maximum) {
+        if (this.admitted[section].has(value))
+            return true;
+        if (this.rejected[section].has(value))
+            return false;
+        if (this.counts[section] >= maximum) {
+            this.rejected[section].add(value);
+            this.sequence += 1;
+            this.dropped += 1;
+            this.truncated.add("events");
+            this.truncated.add(section);
+            return false;
+        }
+        this.admitted[section].add(value);
+        this.counts[section] += 1;
+        return true;
+    }
+    observePage(page) {
+        if (this.enabled.has("console"))
+            page.on("console", (message) => {
+                if (this.pageInScope(page))
+                    this.console(message);
+            });
+        if (this.enabled.has("page-errors"))
+            page.on("pageerror", (error) => {
+                if (this.pageInScope(page))
+                    this.push({
+                        kind: "page-error",
+                        message: this.secrets.redact(error.message).slice(0, 65_536),
+                        stack: error.stack === undefined
+                            ? null
+                            : this.secrets.redact(error.stack).slice(0, 262_144),
+                    });
+            });
+        if (this.enabled.has("network")) {
+            page.on("request", (request) => {
+                if (this.pageInScope(page))
+                    this.request("request", request);
+            });
+            page.on("response", (response) => {
+                if (this.pageInScope(page))
+                    this.response(response);
+            });
+            page.on("requestfailed", (request) => {
+                if (this.pageInScope(page))
+                    this.request("request-failed", request);
+            });
+        }
+        if (this.enabled.has("websockets"))
+            page.on("websocket", (socket) => {
+                if (this.pageInScope(page))
+                    this.webSocket(page, socket);
+            });
+        if (this.enabled.has("frames")) {
+            page.on("frameattached", (frame) => {
+                if (this.pageInScope(page))
+                    this.frame("frame-attached", frame);
+            });
+            page.on("framedetached", (frame) => {
+                if (this.pageInScope(page))
+                    this.frame("frame-detached", frame);
+            });
+            page.on("framenavigated", (frame) => {
+                if (this.pageInScope(page))
+                    this.frame("frame-navigated", frame);
+            });
+        }
+        if (this.enabled.has("workers"))
+            page.on("worker", (worker) => {
+                if (this.pageInScope(page))
+                    this.worker(page, worker);
+            });
+        if (this.enabled.has("popups"))
+            page.on("popup", (popup) => {
+                if (this.pageInScope(page))
+                    this.popup(popup);
+            });
+        if (this.enabled.has("downloads"))
+            page.on("download", (download) => {
+                if (this.pageInScope(page))
+                    this.download(download);
+            });
+    }
+    pageInScope(page) {
+        try {
+            return this.allowedOrigins.has(new URL(page.url()).origin);
+        }
+        catch {
+            return false;
+        }
+    }
+    safeUrl(value) {
+        return sanitizeBrowserUrl(this.secrets.redact(value));
+    }
+    console(message) {
+        const location = message.location();
+        this.push({
+            kind: "console",
+            level: this.secrets.redact(message.type()).slice(0, 64),
+            text: this.secrets.redact(message.text()).slice(0, 65_536),
+            url: location.url === "" ? null : this.safeUrl(location.url),
+        });
+    }
+    request(kind, request) {
+        this.push({
+            kind,
+            method: this.secrets.redact(request.method()).slice(0, 32),
+            url: this.safeUrl(request.url()),
+            resource_type: this.secrets.redact(request.resourceType()).slice(0, 64),
+            status: null,
+            header_names: Object.keys(request.headers())
+                .map((name) => this.secrets.redact(name).slice(0, 256))
+                .sort()
+                .slice(0, 256),
+            failure: kind === "request-failed"
+                ? this.secrets
+                    .redact(request.failure()?.errorText ?? "unknown")
+                    .slice(0, 1_024)
+                : null,
+        });
+    }
+    response(response) {
+        const request = response.request();
+        this.push({
+            kind: "response",
+            method: this.secrets.redact(request.method()).slice(0, 32),
+            url: this.safeUrl(response.url()),
+            resource_type: this.secrets.redact(request.resourceType()).slice(0, 64),
+            status: response.status(),
+            header_names: Object.keys(response.headers())
+                .map((name) => this.secrets.redact(name).slice(0, 256))
+                .sort()
+                .slice(0, 256),
+            failure: null,
+        });
+    }
+    webSocket(page, socket) {
+        if (!this.admit("websockets", socket, this.limits.max_websockets))
+            return;
+        const url = this.safeUrl(socket.url());
+        this.push({ kind: "websocket-opened", url });
+        socket.on("framesent", ({ payload }) => {
+            if (this.pageInScope(page))
+                this.webSocketFrame("websocket-frame-sent", url, payload);
+        });
+        socket.on("framereceived", ({ payload }) => {
+            if (this.pageInScope(page))
+                this.webSocketFrame("websocket-frame-received", url, payload);
+        });
+        socket.on("close", () => {
+            if (this.pageInScope(page))
+                this.push({ kind: "websocket-closed", url });
+        });
+    }
+    webSocketFrame(kind, url, payload) {
+        const bytes = Buffer.byteLength(payload);
+        const isText = typeof payload === "string";
+        const text = isText ? this.secrets.redact(payload).slice(0, 65_536) : null;
+        this.push({
+            kind,
+            url,
+            payload_type: isText ? "text" : "binary",
+            payload_bytes: bytes,
+            payload_text: text,
+            truncated: isText && text !== null && text.length < payload.length,
+        });
+    }
+    frame(kind, frame) {
+        if (!this.admit("frames", frame, this.limits.max_frames))
+            return;
+        this.push({
+            kind,
+            url: frame.url() === "" ? null : this.safeUrl(frame.url()),
+            name: frame.name() === ""
+                ? null
+                : this.secrets.redact(frame.name()).slice(0, 1_024),
+        });
+    }
+    worker(page, worker) {
+        if (!this.admit("workers", worker, this.limits.max_workers))
+            return;
+        const details = {
+            url: this.safeUrl(worker.url()),
+            name: null,
+        };
+        this.push({ kind: "worker-created", ...details });
+        worker.on("close", () => {
+            if (this.pageInScope(page))
+                this.push({ kind: "worker-closed", ...details });
+        });
+    }
+    popup(page) {
+        if (!this.pageInScope(page)) {
+            void page.close().catch(() => undefined);
+            return;
+        }
+        if (!this.admit("popups", page, this.limits.max_popups))
+            return;
+        const opened = {
+            url: page.url() === "" ? null : this.safeUrl(page.url()),
+            name: null,
+        };
+        this.push({ kind: "popup-opened", ...opened });
+        page.on("close", () => this.pageInScope(page)
+            ? this.push({
+                kind: "popup-closed",
+                url: page.url() === "" ? null : this.safeUrl(page.url()),
+                name: null,
+            })
+            : undefined);
+        this.observePage(page);
+    }
+    download(download) {
+        this.push({
+            kind: "download-cancelled",
+            suggested_filename: this.secrets
+                .redact(download.suggestedFilename())
+                .slice(0, 1_024),
+            url: this.safeUrl(download.url()),
+        });
+        void download.cancel().catch(() => undefined);
+    }
+}

package/dist/browser/PlaywrightScenarioSession.js

@@ -0,0 +1,300 @@
+import {} from "playwright-core";
+import { BrowserObservationError } from "../domain/errors.js";
+import { BrowserScenarioSecrets } from "./BrowserScenarioSecrets.js";
+import { closePlaywrightScenarioBrowser, openPlaywrightScenarioBrowser, } from "./PlaywrightScenarioBrowser.js";
+import { performPlaywrightScenarioAction } from "./PlaywrightScenarioActions.js";
+import { BrowserScenarioCaptureBudget, capturePlaywrightStepArtifacts, } from "./PlaywrightScenarioArtifacts.js";
+import { PlaywrightScenarioEvents } from "./PlaywrightScenarioEvents.js";
+import { withPlaywrightExecutionBoundary } from "./PlaywrightExecutionBoundary.js";
+const OPERATION = "capture_browser_scenario";
+const originAllowed = (value, allowedOrigins) => {
+    try {
+        return allowedOrigins.has(new URL(value).origin);
+    }
+    catch {
+        return false;
+    }
+};
+const storageSeeds = (blocks, secrets) => {
+    const seeds = {};
+    for (const { origin, entries } of blocks)
+        (seeds[origin] ??= []).push(...entries.map(({ name, value }) => [name, secrets.value(value)]));
+    return seeds;
+};
+const installStorageSeeds = async (context, page, scenario, secrets) => {
+    await context.addCookies(scenario.storage.cookies.map((cookie) => ({
+        name: cookie.name,
+        value: secrets.value(cookie.value),
+        url: secrets.url(cookie.destination),
+        httpOnly: cookie.http_only,
+        secure: cookie.secure,
+        sameSite: cookie.same_site,
+    })));
+    const storage = {
+        local: storageSeeds(scenario.storage.local_storage, secrets),
+        session: storageSeeds(scenario.storage.session_storage, secrets),
+    };
+    const payload = JSON.stringify(storage).replaceAll("<", "\\u003c");
+    await page.addInitScript(`(() => {
+    const seeds = ${payload};
+    const local = seeds.local[window.location.origin] ?? [];
+    const session = seeds.session[window.location.origin] ?? [];
+    for (const [name, value] of local) window.localStorage.setItem(name, value);
+    for (const [name, value] of session)
+      window.sessionStorage.setItem(name, value);
+  })()`);
+};
+const installHttpPolicy = async (input) => {
+    const { context, scenario, secrets, ownedPages, claimOwnedPage } = input;
+    const routes = scenario.request_replay.mode === "exact"
+        ? new Map(scenario.request_replay.routes.map((route) => [
+            `${route.method} ${secrets.url(route.request)}`,
+            route,
+        ]))
+        : new Map();
+    await context.route("**/*", async (route, request) => {
+        let requestPage;
+        try {
+            requestPage = request.frame().page();
+        }
+        catch {
+            requestPage = undefined;
+        }
+        if (scenario.browser.mode === "connect" &&
+            requestPage !== undefined &&
+            !ownedPages.has(requestPage))
+            await claimOwnedPage(requestPage);
+        if (scenario.browser.mode === "connect" &&
+            (requestPage === undefined || !ownedPages.has(requestPage))) {
+            await route.continue();
+            return;
+        }
+        if (!originAllowed(request.url(), new Set(scenario.allowed_origins))) {
+            await route.abort("blockedbyclient");
+            return;
+        }
+        const replay = routes.get(`${request.method()} ${request.url()}`);
+        if (replay !== undefined) {
+            await fulfillReplayRoute(route, replay.response, secrets);
+            return;
+        }
+        if (scenario.request_replay.mode === "exact" &&
+            scenario.request_replay.unmatched === "abort") {
+            await route.abort("blockedbyclient");
+            return;
+        }
+        await route.continue();
+    });
+};
+const fulfillReplayRoute = async (route, response, secrets) => {
+    if (response.kind === "redirect") {
+        await route.fulfill({
+            status: response.status,
+            headers: { location: secrets.url(response.destination) },
+        });
+        return;
+    }
+    await route.fulfill({
+        status: response.status,
+        headers: Object.fromEntries(response.headers.map(({ name, value }) => [name, secrets.value(value)])),
+        ...(response.body === undefined
+            ? {}
+            : { body: secrets.value(response.body) }),
+    });
+};
+const installWebSocketPolicy = async (owner, scenario) => {
+    const allowed = new Set(scenario.allowed_origins);
+    await owner.routeWebSocket("**/*", async (route) => {
+        const url = new URL(route.url());
+        const httpOrigin = `${url.protocol === "wss:" ? "https:" : "http:"}//${url.host}`;
+        if (!allowed.has(httpOrigin) ||
+            (scenario.request_replay.mode === "exact" &&
+                scenario.request_replay.unmatched === "abort")) {
+            await route.close({ code: 1008, reason: "outside scenario policy" });
+            return;
+        }
+        route.connectToServer();
+    });
+};
+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) => {
+    context.setDefaultTimeout(scenario.limits.action_timeout_ms);
+    context.setDefaultNavigationTimeout(scenario.limits.navigation_timeout_ms);
+    const ownedPages = new Set([page]);
+    if (scenario.browser.mode === "connect")
+        await blockAttachedServiceWorkers(page);
+    await installWebSocketPolicy(scenario.browser.mode === "launch" ? context : page, scenario);
+    const claimOwnedPage = async (candidate) => {
+        if (ownedPages.has(candidate))
+            return true;
+        const opener = await candidate.opener();
+        if (opener === null || !ownedPages.has(opener))
+            return false;
+        await installWebSocketPolicy(candidate, scenario);
+        ownedPages.add(candidate);
+        return true;
+    };
+    await installHttpPolicy({
+        context,
+        scenario,
+        secrets,
+        ownedPages,
+        claimOwnedPage,
+    });
+    page.on("popup", (popup) => {
+        if (scenario.browser.mode === "connect")
+            void claimOwnedPage(popup).catch(async () => {
+                await popup.close().catch(() => undefined);
+            });
+        else
+            ownedPages.add(popup);
+    });
+    await installStorageSeeds(context, page, scenario, secrets);
+    return ownedPages;
+};
+export class PlaywrightScenarioSession {
+    opened;
+    scenario;
+    secrets;
+    eventCapture;
+    mode;
+    processOwnership;
+    product = "Chromium";
+    version;
+    initialUrl;
+    closed = false;
+    constructor(opened, scenario, secrets, eventCapture) {
+        this.opened = opened;
+        this.scenario = scenario;
+        this.secrets = secrets;
+        this.eventCapture = eventCapture;
+        this.mode = scenario.browser.mode;
+        this.processOwnership =
+            scenario.browser.mode === "launch" ? "provider-owned" : "external";
+        this.version = opened.browser.version();
+        this.initialUrl = opened.page.url();
+    }
+    static async open(scenario, environment, options) {
+        const remaining = () => options.deadlineAt - Date.now();
+        if (options.signal?.aborted === true)
+            throw new BrowserObservationError(OPERATION, "cancelled");
+        const secrets = BrowserScenarioSecrets.resolve(scenario, environment);
+        if (secrets === undefined)
+            throw new BrowserObservationError(OPERATION, "secret_unavailable");
+        const opening = openPlaywrightScenarioBrowser(scenario, environment, remaining());
+        let opened;
+        try {
+            opened = await withPlaywrightExecutionBoundary(() => opening, remaining(), options.signal);
+        }
+        catch (error) {
+            void opening
+                .then((lateOpened) => closePlaywrightScenarioBrowser(lateOpened))
+                .catch(() => undefined);
+            throw error;
+        }
+        try {
+            await withPlaywrightExecutionBoundary(() => initializePage(opened.context, opened.page, scenario, secrets), remaining(), options.signal);
+            const events = new PlaywrightScenarioEvents({
+                page: opened.page,
+                enabled: new Set(scenario.capture.events),
+                limits: scenario.limits,
+                secrets,
+                budget: options.budget,
+                allowedOrigins: scenario.allowed_origins,
+            });
+            const session = new PlaywrightScenarioSession(opened, scenario, secrets, events);
+            await withPlaywrightExecutionBoundary(() => opened.page.goto(secrets.url(scenario.start_url), {
+                waitUntil: "load",
+                timeout: Math.min(scenario.limits.navigation_timeout_ms, remaining()),
+            }), remaining(), options.signal);
+            return session;
+        }
+        catch (error) {
+            await closePlaywrightScenarioBrowser(opened);
+            throw error;
+        }
+    }
+    currentUrl() {
+        return this.opened.page.url();
+    }
+    setStep(index) {
+        this.eventCapture.setStep(index);
+    }
+    nextEventSequence() {
+        return this.eventCapture.nextSequence();
+    }
+    lastEventSequence() {
+        return this.eventCapture.lastSequence();
+    }
+    events() {
+        return this.eventCapture.result();
+    }
+    eventTruncationSections() {
+        return this.eventCapture.truncationSections();
+    }
+    async perform(action, maximumTimeoutMs, signal) {
+        await withPlaywrightExecutionBoundary(() => performPlaywrightScenarioAction({
+            page: this.opened.page,
+            action,
+            secrets: this.secrets,
+            defaultTimeoutMs: this.scenario.limits.action_timeout_ms,
+            maximumTimeoutMs,
+        }), maximumTimeoutMs, signal);
+    }
+    async capture(requested, budget, maximumTimeoutMs, signal) {
+        return withPlaywrightExecutionBoundary(() => capturePlaywrightStepArtifacts({
+            context: this.opened.context,
+            page: this.opened.page,
+            scenario: this.scenario,
+            secrets: this.secrets,
+            requested,
+            budget,
+        }), maximumTimeoutMs, signal);
+    }
+    async close() {
+        if (this.closed)
+            return this.mode === "launch"
+                ? "terminated-owned-process"
+                : "disconnected-external";
+        this.closed = true;
+        await closePlaywrightScenarioBrowser(this.opened);
+        return this.mode === "launch"
+            ? "terminated-owned-process"
+            : "disconnected-external";
+    }
+    redactError(error) {
+        return this.secrets
+            .redact(error instanceof Error ? error.message : "browser action failed")
+            .slice(0, 4_096);
+    }
+}
+/** Production Playwright/CDP session factory. */
+export class PlaywrightScenarioSessionFactory {
+    environment;
+    constructor(environment = process.env) {
+        this.environment = environment;
+    }
+    open(scenario, options = {}) {
+        return PlaywrightScenarioSession.open(scenario, this.environment, {
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            budget: options.budget ??
+                new BrowserScenarioCaptureBudget(scenario.limits.max_screenshots, scenario.limits.max_total_metadata_bytes),
+            deadlineAt: options.deadlineAt ?? Date.now() + scenario.limits.max_duration_ms,
+        });
+    }
+}