rea-agents 2.4.0 → 3.0.0

package/dist/browser/JavaScriptRuntimeScope.js

@@ -0,0 +1,38 @@
+import { browserOriginSchema, sanitizeBrowserUrl, } from "../domain/browserObservation.js";
+import { authorizedElectronFile, canonicalElectronRoots, } from "./ElectronFileScope.js";
+/** Canonicalize exact filesystem scopes before Inspector attachment. */
+export const canonicalRuntimeRoots = canonicalElectronRoots;
+/** Authorize one protocol URL without retaining an out-of-scope value. */
+export const authorizeRuntimeLocation = async (value, roots, origins) => {
+    if (value.startsWith("node:") && value.length <= 4_096)
+        return {
+            allowed: true,
+            location: { kind: "builtin", specifier: value },
+        };
+    if (value.startsWith("file:")) {
+        const filePath = await authorizedElectronFile(value, roots);
+        return filePath === undefined
+            ? { allowed: false, reason: "outside_file_roots" }
+            : { allowed: true, location: { kind: "file", file_path: filePath } };
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return { allowed: false, reason: "unsupported_location" };
+    }
+    if (!["http:", "https:"].includes(url.protocol))
+        return { allowed: false, reason: "unsupported_location" };
+    const parsedOrigin = browserOriginSchema.safeParse(url.origin);
+    if (!parsedOrigin.success || !origins.includes(parsedOrigin.data))
+        return { allowed: false, reason: "outside_origins" };
+    return {
+        allowed: true,
+        location: {
+            kind: "url",
+            origin: parsedOrigin.data,
+            sanitized_url: sanitizeBrowserUrl(value).url,
+        },
+    };
+};

package/dist/browser/PlaywrightBrowserScenarioProvider.js

@@ -0,0 +1,259 @@
+import { sanitizeBrowserUrl } from "../domain/browserObservation.js";
+import { browserScenarioCaptureSchema, browserScenarioCompletenessSchema, browserScenarioStepSchema, browserStepArtifactsSchema, } from "../domain/browserScenarioCapture.js";
+import { AnalysisError, BrowserObservationError, ProviderAdapterError, } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { BrowserScenarioCaptureBudget } from "./PlaywrightScenarioArtifacts.js";
+const OPERATION = "capture_browser_scenario";
+let defaultFactory;
+const lazyPlaywrightFactory = {
+    async open(scenario, options) {
+        defaultFactory ??= import("./PlaywrightScenarioSession.js").then(({ PlaywrightScenarioSessionFactory }) => new PlaywrightScenarioSessionFactory());
+        return (await defaultFactory).open(scenario, options);
+    },
+};
+export const PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY = Object.freeze({
+    id: "rea-playwright-browser-scenario",
+    name: "REA Playwright browser scenario capture provider",
+    version: "1",
+});
+const requestedForStep = (scenario, stepIndex) => new Set([
+    ...scenario.capture.after_each_step,
+    ...(stepIndex === scenario.actions.length ? scenario.capture.at_end : []),
+]);
+const unavailableArtifacts = (requested, reason) => {
+    const state = (kind) => requested.has(kind)
+        ? { state: "missing", reason }
+        : { state: "not_requested" };
+    return browserStepArtifactsSchema.parse({
+        screenshot: state("screenshot"),
+        dom: state("dom"),
+        accessibility: state("accessibility"),
+        url: state("url"),
+        history: state("history"),
+        storage: state("storage"),
+    });
+};
+const stepCompleteness = (artifacts, status) => {
+    const missing = Object.entries(artifacts)
+        .filter(([, state]) => state.state === "missing")
+        .map(([section]) => section);
+    const truncated = Object.entries(artifacts)
+        .filter(([, state]) => state.state === "truncated")
+        .map(([section]) => section);
+    if (status !== "completed")
+        missing.push("action");
+    const condition = truncated.length > 0
+        ? "truncated"
+        : missing.length > 0
+            ? "incomplete"
+            : "complete";
+    return browserScenarioCompletenessSchema.parse({
+        status: condition,
+        equality_eligible: condition === "complete",
+        missing_sections: [...new Set(missing)].sort(),
+        truncated_sections: [...new Set(truncated)].sort(),
+    });
+};
+const createStep = (input) => browserScenarioStepSchema.parse({
+    step_index: input.stepIndex,
+    step_id: input.stepId,
+    action: input.action,
+    status: input.status,
+    elapsed_ms: input.elapsedMs,
+    before_url: sanitizeBrowserUrl(input.beforeUrl),
+    after_url: sanitizeBrowserUrl(input.afterUrl),
+    error: input.error,
+    event_sequence_start: input.eventStart,
+    event_sequence_end: input.eventEnd,
+    artifacts: input.artifacts,
+    completeness: stepCompleteness(input.artifacts, input.status),
+});
+const initialStep = async (input) => {
+    const { session, scenario, budget, elapsedMs, maximumTimeoutMs, signal } = input;
+    const artifacts = await session.capture(requestedForStep(scenario, 0), budget, maximumTimeoutMs, signal);
+    return createStep({
+        stepIndex: 0,
+        stepId: "scenario_start",
+        action: "goto_start",
+        status: "completed",
+        elapsedMs,
+        beforeUrl: session.initialUrl,
+        afterUrl: session.currentUrl(),
+        error: null,
+        eventStart: 1,
+        eventEnd: session.lastEventSequence(),
+        artifacts,
+    });
+};
+const executeStep = async (input) => {
+    const { session, scenario, budget, action, stepIndex, startedAt, priorFailure, signal, } = input;
+    const beforeUrl = session.currentUrl();
+    const eventStart = session.nextEventSequence();
+    const requested = requestedForStep(scenario, stepIndex);
+    if (priorFailure)
+        return createStep({
+            stepIndex,
+            stepId: action.step_id,
+            action: action.action,
+            status: "cancelled",
+            elapsedMs: 0,
+            beforeUrl,
+            afterUrl: beforeUrl,
+            error: "not executed after an earlier action failure",
+            eventStart,
+            eventEnd: session.lastEventSequence(),
+            artifacts: unavailableArtifacts(requested, "action was not executed after an earlier failure"),
+        });
+    const actionStartedAt = Date.now();
+    session.setStep(stepIndex);
+    const requestCancelled = () => signal?.aborted === true;
+    let status = "completed";
+    let error = null;
+    if (requestCancelled()) {
+        status = "cancelled";
+        error = "scenario request cancelled";
+    }
+    else {
+        try {
+            const elapsed = Date.now() - startedAt;
+            const remaining = scenario.limits.max_duration_ms - elapsed;
+            if (remaining <= 0)
+                throw new Error("Scenario duration limit reached");
+            await session.perform(action, remaining, signal);
+        }
+        catch (cause) {
+            status = requestCancelled() ? "cancelled" : "failed";
+            error = session.redactError(cause);
+        }
+    }
+    const remaining = scenario.limits.max_duration_ms - (Date.now() - startedAt);
+    const artifacts = status === "cancelled" || remaining <= 0
+        ? unavailableArtifacts(requested, status === "cancelled"
+            ? "scenario request cancelled"
+            : "scenario duration limit reached")
+        : await session.capture(requested, budget, remaining, signal);
+    return createStep({
+        stepIndex,
+        stepId: action.step_id,
+        action: action.action,
+        status,
+        elapsedMs: Date.now() - actionStartedAt,
+        beforeUrl,
+        afterUrl: session.currentUrl(),
+        error,
+        eventStart,
+        eventEnd: session.lastEventSequence(),
+        artifacts,
+    });
+};
+const globalCompleteness = (scenario, session, steps) => {
+    const missing = steps.flatMap(({ completeness }) => completeness.missing_sections);
+    const truncated = steps.flatMap(({ completeness }) => completeness.truncated_sections);
+    truncated.push(...session.eventTruncationSections());
+    if (session.mode === "connect")
+        missing.push("events");
+    const status = truncated.length > 0
+        ? "truncated"
+        : missing.length > 0
+            ? "incomplete"
+            : "complete";
+    return browserScenarioCompletenessSchema.parse({
+        status,
+        equality_eligible: status === "complete",
+        missing_sections: [...new Set(missing)].sort(),
+        truncated_sections: [...new Set(truncated)].sort(),
+    });
+};
+const runScenario = async (factory, scenario, options) => {
+    if (options.signal?.aborted === true)
+        throw new BrowserObservationError(OPERATION, "cancelled");
+    const startedAt = Date.now();
+    const budget = new BrowserScenarioCaptureBudget(scenario.limits.max_screenshots, scenario.limits.max_total_metadata_bytes);
+    const session = await factory.open(scenario, {
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+        budget,
+        deadlineAt: startedAt + scenario.limits.max_duration_ms,
+    });
+    const steps = [];
+    let cleanup;
+    try {
+        steps.push(await initialStep({
+            session,
+            scenario,
+            budget,
+            elapsedMs: Date.now() - startedAt,
+            maximumTimeoutMs: scenario.limits.max_duration_ms - (Date.now() - startedAt),
+            signal: options.signal,
+        }));
+        let failed = false;
+        for (const [offset, action] of scenario.actions.entries()) {
+            const step = await executeStep({
+                session,
+                scenario,
+                budget,
+                action,
+                stepIndex: offset + 1,
+                startedAt,
+                priorFailure: failed,
+                signal: options.signal,
+            });
+            steps.push(step);
+            failed ||= step.status !== "completed";
+        }
+    }
+    finally {
+        cleanup = await session.close();
+    }
+    const events = session.events();
+    const completeness = globalCompleteness(scenario, session, steps);
+    return browserScenarioCaptureSchema.parse({
+        schema_version: 1,
+        browser: {
+            mode: session.mode,
+            process_ownership: session.processOwnership,
+            cleanup,
+            product: session.product,
+            version: session.version,
+        },
+        scenario: {
+            start_origin: new URL(scenario.start_url.url).origin,
+            allowed_origins: scenario.allowed_origins,
+            action_count: scenario.actions.length,
+            secret_references: scenario.secrets.map(({ secret_id: id }) => id).sort(),
+        },
+        duration_ms: Date.now() - startedAt,
+        steps,
+        events,
+        completeness,
+        limitations: [
+            "Event sequence records provider receipt order; simultaneous browser causality is not inferred.",
+            "Response bodies are not retained.",
+            "Storage values are hashed only after declared-secret redaction.",
+            ...(session.mode === "connect"
+                ? [
+                    "CDP attachment cannot recover pre-attach events or guarantee launch-time context options.",
+                ]
+                : []),
+        ],
+    });
+};
+/** Controlled Playwright/CDP scenario driver with exact process ownership. */
+export class PlaywrightBrowserScenarioProvider {
+    factory;
+    constructor(factory = lazyPlaywrightFactory) {
+        this.factory = factory;
+    }
+    identity() {
+        return PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY;
+    }
+    async captureScenario(scenario, options = {}) {
+        try {
+            return ok(await runScenario(this.factory, scenario, options));
+        }
+        catch (cause) {
+            if (cause instanceof AnalysisError)
+                return err(cause);
+            return err(new ProviderAdapterError(PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY.id, OPERATION, { cause }));
+        }
+    }
+}

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