rea-agents 2.4.0 → 3.0.0

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,
+        });
+    }
+}

package/dist/browser/V8InspectorCaptureProjection.js

@@ -0,0 +1,110 @@
+import { createHash } from "node:crypto";
+import { authorizeRuntimeLocation } from "./JavaScriptRuntimeScope.js";
+/** Empty durable-location exclusion counters. */
+export const createInspectorExclusionCounts = () => ({
+    outside_file_roots: 0,
+    outside_origins: 0,
+    unsupported_location: 0,
+});
+/** Stable safety and protocol limitations shared by target-list Evidence. */
+export const describeInspectorTargetLimitations = () => [
+    "REA attaches to an already-running exact target and never launches, resumes, evaluates, pauses, or mutates it.",
+    "Only Runtime.enable and Debugger.enable are sent; source text, object values, EventEmitter activity, and Electron IPC are not inspected.",
+    "Target IDs and locations are authorized, but the Inspector protocol does not authenticate an operating-system process ID or Electron role.",
+    "No runtime graph depth is traversed because passive Inspector events do not establish require/import caller edges.",
+];
+/** Canonically authorize, deduplicate, and sort one bounded raw capture. */
+export const finalizeInspectorCapture = async ({ input, runtime, target, roots, state, }) => {
+    const exclusions = createInspectorExclusionCounts();
+    const scripts = new Map();
+    for (const draft of state.scripts) {
+        const decision = await authorizeRuntimeLocation(draft.rawUrl, roots, input.allowed_origins);
+        if (!decision.allowed) {
+            exclusions[decision.reason] += 1;
+            continue;
+        }
+        const script = scriptFromDraft(draft, decision.location);
+        scripts.set(script.script_key, script);
+    }
+    const items = [...scripts.values()].sort((left, right) => left.script_key < right.script_key
+        ? -1
+        : left.script_key > right.script_key
+            ? 1
+            : 0);
+    const contexts = [...state.contexts.values()]
+        .map((context) => ({
+        context_key: context.contextKey,
+        state: context.state,
+        name: null,
+        origin: context.origin,
+    }))
+        .sort((left, right) => left.context_key < right.context_key
+        ? -1
+        : left.context_key > right.context_key
+            ? 1
+            : 0);
+    return {
+        schema_version: 1,
+        runtime,
+        target: {
+            target_id: target.id,
+            protocol_type: target.type,
+            attached: target.attached,
+            location: target.location,
+            runtime_kind: input.runtime_kind,
+            runtime_kind_authority: "caller-declared-unverified",
+        },
+        capture: {
+            observation_ms: input.observation_ms,
+            events_observed: state.eventsObserved,
+            events_retained: state.eventsRetained,
+            events_dropped: state.eventsDropped,
+            metadata_bytes_retained: state.metadataBytes,
+            truncated: state.truncated,
+            truncation_reasons: [...state.truncationReasons].sort(),
+        },
+        scripts: {
+            items,
+            observed_total: state.scriptsObserved,
+            excluded: {
+                ...exclusions,
+                invalid_protocol_value: state.invalidScripts,
+            },
+        },
+        execution_contexts: contexts,
+        directly_observed: [
+            "Debugger.scriptParsed established script presence within the bounded capture window.",
+            "Runtime execution-context lifecycle events established context creation, destruction, or clearing.",
+        ],
+        unavailable_without_instrumentation: [
+            "require/import caller-to-callee edges",
+            "EventEmitter emissions and listener invocation",
+            "Electron IPC messages and handlers",
+            "script unload events",
+        ],
+        unknowns: [
+            "Scripts collected before attachment may have been garbage-collected and therefore omitted.",
+            "A bounded observation window cannot establish that an unobserved script or behavior never occurs.",
+            "The declared Node/Electron process role is not authenticated by the Inspector protocol.",
+        ],
+        limitations: describeInspectorTargetLimitations(),
+    };
+};
+const scriptFromDraft = (draft, location) => {
+    const stable = JSON.stringify({
+        location,
+        execution_context_key: draft.executionContextKey,
+        cdp_hash: draft.cdpHash,
+        length: draft.length,
+        is_module: draft.isModule,
+    });
+    return {
+        script_key: `v8_script_${createHash("sha256").update(stable).digest("hex")}`,
+        location,
+        execution_context_key: draft.executionContextKey,
+        cdp_hash: draft.cdpHash,
+        length: draft.length,
+        is_module: draft.isModule,
+        status: "observed-loaded",
+    };
+};

package/dist/browser/V8InspectorEndpoint.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { BrowserObservationError, } from "../domain/errors.js";
+import { parseCdpEndpointValue, readBoundedCdpJson } from "./CdpEndpoint.js";
+const MAX_VERSION_BYTES = 64 * 1_024;
+const MAX_TARGET_LIST_BYTES = 2 * 1_024 * 1_024;
+const versionSchema = z
+    .object({
+    Browser: z.string().min(1).max(1_024),
+    "Protocol-Version": z.string().min(1).max(100),
+    "V8-Version": z.string().max(1_024).optional(),
+})
+    .passthrough();
+const targetSchema = z
+    .object({
+    id: z.string().min(1).max(256),
+    type: z.string().min(1).max(100),
+    url: z.string().max(65_536),
+    attached: z.boolean().default(false),
+    webSocketDebuggerUrl: z.string().min(1).max(2_048),
+})
+    .passthrough();
+const targetsSchema = z.array(targetSchema).max(1_000);
+/** Discover bounded Node/Electron Inspector targets from one loopback endpoint. */
+export const discoverV8Inspector = async (endpoint, operation, signal) => {
+    const [versionInput, targetsInput] = await Promise.all([
+        readBoundedCdpJson(new URL("/json/version", endpoint), MAX_VERSION_BYTES, operation, signal),
+        readBoundedCdpJson(new URL("/json/list", endpoint), MAX_TARGET_LIST_BYTES, operation, signal),
+    ]);
+    const version = parseCdpEndpointValue(versionSchema, versionInput, operation);
+    const targets = parseCdpEndpointValue(targetsSchema, targetsInput, operation);
+    return {
+        runtime: {
+            product: version.Browser,
+            protocol_version: version["Protocol-Version"],
+            v8_version: version["V8-Version"] ?? null,
+        },
+        targets: targets.map((target) => ({
+            id: target.id,
+            type: target.type,
+            url: target.url,
+            attached: target.attached,
+            webSocketUrl: validatedInspectorWebSocket(endpoint, target.id, target.webSocketDebuggerUrl, operation),
+        })),
+    };
+};
+const validatedInspectorWebSocket = (endpoint, targetId, reported, operation) => {
+    let socket;
+    try {
+        socket = new URL(reported);
+    }
+    catch (cause) {
+        throw new BrowserObservationError(operation, "invalid_endpoint_response", {
+            cause,
+        });
+    }
+    const trusted = new URL(endpoint);
+    const allowedPaths = new Set([
+        `/${targetId}`,
+        `/devtools/node/${targetId}`,
+        `/devtools/page/${targetId}`,
+    ]);
+    if (socket.protocol !== "ws:" ||
+        socket.port !== trusted.port ||
+        socket.username !== "" ||
+        socket.password !== "" ||
+        socket.search !== "" ||
+        socket.hash !== "" ||
+        !allowedPaths.has(socket.pathname))
+        throw new BrowserObservationError(operation, "invalid_endpoint_response");
+    socket.hostname = trusted.hostname;
+    return socket.href;
+};