rea-agents 3.0.0 → 3.2.0

package/dist/browser/PlaywrightBrowserScenarioProvider.js

@@ -1,8 +1,7 @@
 import { sanitizeBrowserUrl } from "../domain/browserObservation.js";
-import { browserScenarioCaptureSchema, browserScenarioCompletenessSchema, browserScenarioStepSchema, browserStepArtifactsSchema, } from "../domain/browserScenarioCapture.js";
+import { browserScenarioCaptureSchema, classifyBrowserScenarioCompleteness, 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 = {
@@ -16,6 +15,14 @@ export const PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY = Object.freeze({
     name: "REA Playwright browser scenario capture provider",
     version: "1",
 });
+const SNAPSHOT_KINDS = [
+    "screenshot",
+    "dom",
+    "accessibility",
+    "url",
+    "history",
+    "storage",
+];
 const requestedForStep = (scenario, stepIndex) => new Set([
     ...scenario.capture.after_each_step,
     ...(stepIndex === scenario.actions.length ? scenario.capture.at_end : []),
@@ -34,25 +41,11 @@ const unavailableArtifacts = (requested, reason) => {
     });
 };
 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);
+    const missing = SNAPSHOT_KINDS.filter((section) => artifacts[section].state === "missing");
+    const truncated = SNAPSHOT_KINDS.filter((section) => artifacts[section].state === "truncated");
     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(),
-    });
+    return classifyBrowserScenarioCompleteness(missing, truncated);
 };
 const createStep = (input) => browserScenarioStepSchema.parse({
     step_index: input.stepIndex,
@@ -69,8 +62,8 @@ const createStep = (input) => browserScenarioStepSchema.parse({
     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);
+    const { session, scenario, elapsedMs, signal } = input;
+    const artifacts = await session.capture(requestedForStep(scenario, 0), signal);
     return createStep({
         stepIndex: 0,
         stepId: "scenario_start",
@@ -86,7 +79,7 @@ const initialStep = async (input) => {
     });
 };
 const executeStep = async (input) => {
-    const { session, scenario, budget, action, stepIndex, startedAt, priorFailure, signal, } = input;
+    const { session, scenario, action, stepIndex, priorFailure, signal } = input;
     const beforeUrl = session.currentUrl();
     const eventStart = session.nextEventSequence();
     const requested = requestedForStep(scenario, stepIndex);
@@ -107,40 +100,35 @@ const executeStep = async (input) => {
     const actionStartedAt = Date.now();
     session.setStep(stepIndex);
     const requestCancelled = () => signal?.aborted === true;
-    let status = "completed";
-    let error = null;
+    let outcome = {
+        status: "completed",
+        error: null,
+    };
     if (requestCancelled()) {
-        status = "cancelled";
-        error = "scenario request cancelled";
+        outcome = { 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);
+            await session.perform(action, signal);
         }
         catch (cause) {
-            status = requestCancelled() ? "cancelled" : "failed";
-            error = session.redactError(cause);
+            outcome = {
+                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);
+    const artifacts = outcome.status === "cancelled"
+        ? unavailableArtifacts(requested, "scenario request cancelled")
+        : await session.capture(requested, signal);
     return createStep({
         stepIndex,
         stepId: action.step_id,
         action: action.action,
-        status,
+        ...outcome,
         elapsedMs: Date.now() - actionStartedAt,
         beforeUrl,
         afterUrl: session.currentUrl(),
-        error,
         eventStart,
         eventEnd: session.lastEventSequence(),
         artifacts,
@@ -149,40 +137,22 @@ const executeStep = async (input) => {
 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(),
-    });
+    return classifyBrowserScenarioCompleteness(missing, truncated);
 };
 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 session = await factory.open(scenario, options.signal === undefined ? {} : { signal: options.signal });
     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;
@@ -190,10 +160,8 @@ const runScenario = async (factory, scenario, options) => {
             const step = await executeStep({
                 session,
                 scenario,
-                budget,
                 action,
                 stepIndex: offset + 1,
-                startedAt,
                 priorFailure: failed,
                 signal: options.signal,
             });
@@ -207,7 +175,6 @@ const runScenario = async (factory, scenario, options) => {
     const events = session.events();
     const completeness = globalCompleteness(scenario, session, steps);
     return browserScenarioCaptureSchema.parse({
-        schema_version: 1,
         browser: {
             mode: session.mode,
             process_ownership: session.processOwnership,

package/dist/browser/PlaywrightElectronActiveActions.js

@@ -0,0 +1,309 @@
+import { z } from "zod";
+import { BrowserObservationError } from "../domain/errors.js";
+import { redactSensitiveText } from "./SensitiveTextCapture.js";
+const OPERATION = "capture_electron_scenario";
+const hookEventSchema = z.strictObject({
+    sequence: z.number().int().min(1),
+    correlation_id: z.string().nullable(),
+    kind: z.enum([
+        "main-handler-invocation",
+        "main-event-invocation",
+        "utility-process-fork",
+        "utility-process-message",
+        "ipc-main-to-renderer",
+        "ipc-utility-to-main",
+        "ipc-renderer-send",
+        "ipc-renderer-invoke",
+        "ipc-renderer-post-message",
+        "app-lifecycle",
+        "window-lifecycle",
+        "web-contents-lifecycle",
+        "navigation",
+        "shell-attempt",
+        "process-lifecycle",
+        "permission",
+        "popup-attempt",
+        "download",
+        "protocol",
+        "preload",
+        "native-addon",
+        "updater",
+        "error",
+    ]),
+    event: z.string().nullable(),
+    phase: z.enum(["attempted", "completed", "blocked", "failed", "observed"]),
+    channel: z.string().nullable(),
+    direction: z
+        .enum([
+        "renderer-to-main",
+        "main-to-renderer",
+        "main-to-utility",
+        "utility-to-main",
+    ])
+        .nullable(),
+    sender: z.string().nullable(),
+    receiver: z.string().nullable(),
+    frame: z.string().nullable(),
+    target: z.string().nullable(),
+    argument_shapes: z.array(z.string()),
+    result_shape: z.string().nullable(),
+    process_type: z.string().nullable(),
+    source: z.string(),
+    capture_method: z.enum(["api-wrapper", "event-emitter", "process-hook"]),
+    artifact_path: z.string().nullable(),
+    artifact_sha256: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .nullable(),
+    error: z.boolean(),
+});
+const hookSnapshotSchema = z.strictObject({
+    events: z.array(hookEventSchema),
+    observed: z.number().int().min(0),
+    observed_ipc: z.number().int().min(0),
+    observed_runtime: z.number().int().min(0),
+    hook_error: z.boolean(),
+});
+const metricSchema = z.strictObject({
+    pid: z.number().int().min(1),
+    type: z.string().min(1),
+    name: z.string().nullable(),
+    service_name: z.string().nullable(),
+});
+const windowMetadataSchema = z.strictObject({
+    window_id: z.string(),
+    web_contents_id: z.string(),
+    visible: z.boolean().nullable(),
+    destroyed: z.boolean(),
+});
+/** Run explicit actions against provider-owned Electron windows. */
+export const runElectronActions = async (application, input, options) => {
+    const actions = [];
+    for (const action of input.actions) {
+        if (options.signal?.aborted === true)
+            throw new BrowserObservationError(OPERATION, "cancelled");
+        const actionStartedAt = Date.now();
+        const windowIndex = actionWindowIndex(action);
+        let selectedWindow;
+        try {
+            selectedWindow =
+                windowIndex === null
+                    ? undefined
+                    : await waitForWindow({
+                        application,
+                        windowIndex,
+                        signal: options.signal,
+                    });
+            if ((action.kind === "click" ||
+                action.kind === "renderer-reload" ||
+                action.kind === "renderer-crash") &&
+                selectedWindow === undefined)
+                throw new BrowserObservationError(OPERATION, "window_not_found");
+            await runAction({
+                application,
+                action,
+                selectedWindow,
+                options,
+            });
+            actions.push({
+                step_id: action.step_id,
+                kind: action.kind,
+                window_index: windowIndex,
+                target: selectedWindow === undefined ? null : `window:${String(windowIndex)}`,
+                status: "completed",
+                elapsed_ms: Date.now() - actionStartedAt,
+                error: null,
+            });
+        }
+        catch (cause) {
+            actions.push({
+                step_id: action.step_id,
+                kind: action.kind,
+                window_index: windowIndex,
+                target: selectedWindow === undefined ? null : `window:${String(windowIndex)}`,
+                status: options.signal?.aborted ? "cancelled" : "failed",
+                elapsed_ms: Date.now() - actionStartedAt,
+                error: safeActionErrorMessage(cause, action),
+            });
+            break;
+        }
+    }
+    return actions;
+};
+const runAction = async ({ application, action, selectedWindow, options, }) => {
+    switch (action.kind) {
+        case "click":
+            if (selectedWindow === undefined)
+                throw new BrowserObservationError(OPERATION, "window_not_found");
+            await runWithExecutionLimits(selectedWindow.locator(action.selector).click({
+                timeout: 0,
+            }), options.signal);
+            return;
+        case "wait": {
+            const page = selectedWindow ??
+                (await application.firstWindow({
+                    timeout: 0,
+                }));
+            await runWithExecutionLimits(page.waitForTimeout(action.duration_ms), options.signal);
+            return;
+        }
+        case "renderer-reload":
+            if (selectedWindow === undefined)
+                throw new BrowserObservationError(OPERATION, "window_not_found");
+            await runWithExecutionLimits(selectedWindow.reload({
+                timeout: 0,
+            }), options.signal);
+            return;
+        case "renderer-crash": {
+            const crashed = await runWithExecutionLimits(application.evaluate(({ BrowserWindow }, index) => {
+                const candidate = BrowserWindow.getAllWindows()[index];
+                if (candidate === undefined || candidate.isDestroyed())
+                    return false;
+                candidate.webContents.forcefullyCrashRenderer();
+                return true;
+            }, action.window_index), options.signal);
+            if (!crashed)
+                throw new BrowserObservationError(OPERATION, "window_not_found");
+            return;
+        }
+        case "deep-link":
+            await runWithExecutionLimits(emitDeepLink(application, action), options.signal);
+            return;
+    }
+};
+const actionWindowIndex = (action) => {
+    switch (action.kind) {
+        case "click":
+        case "renderer-reload":
+        case "renderer-crash":
+            return action.window_index;
+        case "wait":
+            return action.window_index ?? null;
+        case "deep-link":
+            return null;
+    }
+};
+const waitForWindow = async ({ application, windowIndex, signal, }) => {
+    while (true) {
+        if (signal?.aborted === true)
+            throw new BrowserObservationError(OPERATION, "cancelled");
+        const window = application.windows()[windowIndex];
+        if (window !== undefined)
+            return window;
+        await runWithExecutionLimits(new Promise((resolve) => setTimeout(resolve, 25)), signal);
+    }
+};
+const emitDeepLink = (application, action) => application.evaluate(({ app }, payload) => {
+    if (payload.delivery === "open-url")
+        return app.emit("open-url", { preventDefault: () => undefined }, payload.url);
+    return app.emit("second-instance", {}, [payload.url], "", {});
+}, { delivery: action.delivery, url: action.url });
+/** Read the current Electron windows, metrics, and hook snapshot. */
+// oxlint-disable-next-line max-lines-per-function -- one state read must share one capture boundary.
+export const readApplicationState = async (application) => {
+    const pages = application.windows();
+    const pageSnapshotsPromise = Promise.all(pages.map(async (page, index) => ({
+        index,
+        url: page.url(),
+        title: await page.title(),
+    })));
+    const windowMetadataPromise = application
+        .evaluate(({ BrowserWindow }) => BrowserWindow.getAllWindows().map((window) => ({
+        window_id: `window:${String(window.id)}`,
+        web_contents_id: `webContents:${String(window.webContents.id)}`,
+        visible: window.isDestroyed() ? null : window.isVisible(),
+        destroyed: window.isDestroyed(),
+    })))
+        .then((value) => z.array(windowMetadataSchema).parse(value));
+    const processMetricsPromise = application
+        .evaluate(({ app }) => app
+        .getAppMetrics()
+        .map((metric) => ({
+        pid: metric.pid,
+        type: metric.type,
+        name: metric.name ?? null,
+        service_name: metric.serviceName ?? null,
+    })))
+        .then((value) => z.array(metricSchema).parse(value));
+    const electronVersionPromise = application
+        .evaluate(() => process.versions.electron)
+        .then((value) => z.string().parse(value));
+    const hookSnapshotPromise = application
+        .evaluate(() => {
+        const candidate = Reflect.get(globalThis, "__reaElectronActiveSnapshot");
+        return typeof candidate === "function"
+            ? candidate()
+            : {
+                events: [],
+                observed: 0,
+                observed_ipc: 0,
+                observed_runtime: 0,
+                hook_error: true,
+            };
+    })
+        .then((value) => hookSnapshotSchema.parse(value));
+    const [pageSnapshots, windowMetadata, processMetrics, electronVersion, hookSnapshot,] = await Promise.all([
+        pageSnapshotsPromise,
+        windowMetadataPromise,
+        processMetricsPromise,
+        electronVersionPromise,
+        hookSnapshotPromise,
+    ]);
+    return {
+        windows: pageSnapshots.map((page) => {
+            const metadata = windowMetadata[page.index];
+            if (metadata === undefined)
+                throw new BrowserObservationError(OPERATION, "window_metadata_missing");
+            return {
+                window_id: metadata.window_id,
+                web_contents_id: metadata.web_contents_id,
+                url: page.url,
+                title: page.title,
+                visible: metadata.visible,
+                destroyed: metadata.destroyed,
+            };
+        }),
+        metrics: processMetrics,
+        electronVersion,
+        hookSnapshot,
+    };
+};
+/** Apply an optional lifecycle deadline and caller cancellation to an operation. */
+export const runWithExecutionLimits = async (operation, signal, deadline) => {
+    if (signal?.aborted === true)
+        throw new BrowserObservationError(OPERATION, "cancelled");
+    if (signal === undefined && deadline === undefined)
+        return operation;
+    let timer;
+    let abortListener;
+    const interruptions = [];
+    if (deadline !== undefined)
+        interruptions.push(new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new BrowserObservationError(OPERATION, "timeout")), Math.max(1, deadline - Date.now()));
+        }));
+    if (signal !== undefined)
+        interruptions.push(new Promise((_, reject) => {
+            abortListener = () => reject(new BrowserObservationError(OPERATION, "cancelled"));
+            signal.addEventListener("abort", abortListener, { once: true });
+        }));
+    try {
+        return interruptions.length === 0
+            ? await operation
+            : await Promise.race([operation, ...interruptions]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        if (abortListener !== undefined)
+            signal?.removeEventListener("abort", abortListener);
+    }
+};
+const safeActionErrorMessage = (cause, action) => {
+    let message = cause instanceof Error ? cause.message : "Electron action failed";
+    const inputValues = Object.values(action)
+        .filter((value) => typeof value === "string" && value.length > 0)
+        .sort((left, right) => right.length - left.length);
+    for (const value of inputValues)
+        message = message.split(value).join("<redacted-input>");
+    return redactSensitiveText(message);
+};