rea-agents 5.0.0 → 6.1.0

package/dist/browser/PlaywrightElectronActiveProjection.js

@@ -0,0 +1,141 @@
+import { electronActiveObservationResultSchema, } from "../domain/javascript/electronActiveObservation.js";
+const observableEventFamilies = [
+    "app-lifecycle",
+    "window-lifecycle",
+    "web-contents-lifecycle",
+    "navigation",
+    "shell-attempt",
+    "process-lifecycle",
+    "permission",
+    "popup-attempt",
+    "download",
+    "protocol",
+    "preload",
+    "preload-configuration",
+    "renderer-ipc",
+    "native-addon",
+    "updater",
+    "error",
+    "ipc",
+];
+const ipcEventKinds = new Set([
+    "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",
+]);
+const eventFamily = (kind, processType) => {
+    if (kind === "preload" &&
+        (processType === "main" || processType === "browser"))
+        return "preload-configuration";
+    if (kind.startsWith("ipc-renderer"))
+        return processType === "renderer" ? "renderer-ipc" : "ipc";
+    return ipcEventKinds.has(kind) ? "ipc" : kind;
+};
+const createCoverage = (hookSnapshot) => {
+    const observedEventFamilies = [
+        ...new Set([
+            ...hookSnapshot.events.map(({ kind, process_type }) => eventFamily(kind, process_type)),
+            ...hookSnapshot.dropped_event_families.map(({ family }) => family),
+        ]),
+    ].sort();
+    const unavailableEventFamilies = new Set(observableEventFamilies.filter((family) => !observedEventFamilies.includes(family)));
+    const observedRoles = [
+        ...new Set([
+            ...hookSnapshot.events.flatMap(({ process_type, kind }) => [
+                ...(process_type === null ? [] : [process_type]),
+                ...(kind === "window-lifecycle" ? ["window"] : []),
+                ...(kind === "web-contents-lifecycle" || kind === "navigation"
+                    ? ["web_contents"]
+                    : []),
+                ...(kind === "preload" && process_type === "preload"
+                    ? ["preload"]
+                    : []),
+                ...(kind.startsWith("ipc-renderer") && process_type === "renderer"
+                    ? ["renderer"]
+                    : []),
+            ]),
+            ...hookSnapshot.dropped_event_roles.map(({ role }) => role),
+        ]),
+    ].sort();
+    if (!observedRoles.includes("preload"))
+        unavailableEventFamilies.add("preload");
+    if (!observedRoles.includes("renderer"))
+        unavailableEventFamilies.add("renderer-ipc");
+    return {
+        status: hookSnapshot.hook_error ? "hook_conflict" : "partial_attach",
+        observed_event_families: observedEventFamilies,
+        unavailable_event_families: [...unavailableEventFamilies].sort(),
+        observed_roles: observedRoles,
+        pre_capture_activity: "unavailable",
+    };
+};
+/** Project one provider hook snapshot into the canonical public result. */
+export const projectElectronActiveCapture = (paths, actions, state) => {
+    const { hookSnapshot } = state;
+    const ipcEvents = hookSnapshot.events.filter(({ kind }) => ipcEventKinds.has(kind));
+    return electronActiveObservationResultSchema.parse({
+        application: {
+            executable_path: paths.executable,
+            application_path: paths.application,
+            electron_version: state.electronVersion,
+            process_ownership: "provider-owned",
+            cleanup: "terminated-owned-process",
+        },
+        actions,
+        windows: state.windows,
+        processes: {
+            items: state.metrics,
+        },
+        ipc: {
+            events: ipcEvents,
+            observed: hookSnapshot.observed_ipc,
+            dropped: hookSnapshot.dropped_ipc,
+        },
+        timeline: {
+            events: hookSnapshot.events,
+            observed: hookSnapshot.observed,
+            dropped: hookSnapshot.dropped,
+        },
+        retention: {
+            budget_bytes: hookSnapshot.retention_budget_bytes,
+            estimated_retained_bytes: hookSnapshot.estimated_retained_bytes,
+            event_serialized_byte_upper_bound: hookSnapshot.event_serialized_byte_upper_bound,
+            retained: hookSnapshot.retained,
+            dropped: hookSnapshot.dropped,
+            dropped_event_families: hookSnapshot.dropped_event_families,
+            dropped_event_roles: hookSnapshot.dropped_event_roles,
+            observed_ipc: hookSnapshot.observed_ipc,
+            dropped_ipc: hookSnapshot.dropped_ipc,
+            observed_runtime: hookSnapshot.observed_runtime,
+            dropped_runtime: hookSnapshot.dropped_runtime,
+        },
+        coverage: createCoverage(hookSnapshot),
+        limitations: [
+            "IPC payloads are represented by value shapes; payload values are never retained.",
+            "IPC direction and sender/receiver identifiers are observed only where Electron exposes them at the hooked boundary.",
+            "The runtime timeline records lifecycle, navigation, shell, permission, popup, download, protocol, preload, native-addon, process, and IPC events; activity before hook installation is unavailable.",
+            "The preload and renderer process contexts are not instrumented by the main-process -r hook; preload configuration and contextBridge API-shape events are main-boundary observations, not proof of renderer-side execution.",
+            ...(!hookSnapshot.events.some(({ kind }) => kind === "preload")
+                ? [
+                    "Preload configuration was not exposed by the observed Electron window metadata. Preload paths and execution remain unavailable.",
+                ]
+                : []),
+            "Process metrics are an Electron API snapshot and do not prove hostile-local-user isolation.",
+            ...(hookSnapshot.dropped > 0
+                ? [
+                    `The active hook retained ${hookSnapshot.retained} of ${hookSnapshot.observed} observed events within a ${hookSnapshot.retention_budget_bytes}-byte retained-data budget; ${hookSnapshot.dropped} events were dropped (${hookSnapshot.dropped_ipc} IPC, ${hookSnapshot.dropped_runtime} runtime).`,
+                ]
+                : []),
+            "External shell opens, external navigation, permission grants, downloads, popup windows, updater relaunches, and OS integration are blocked and recorded by the active hook; other application filesystem and network behavior is not sandboxed by this provider.",
+            ...(hookSnapshot.hook_error
+                ? ["The active IPC hook could not be installed."]
+                : []),
+        ],
+    });
+};

package/dist/browser/PlaywrightElectronActiveProvider.js

@@ -3,90 +3,21 @@ import { dirname } from "node:path";
 import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { _electron as electron } from "playwright-core";
-import { electronActiveObservationResultSchema, } from "../domain/javascript/electronActiveObservation.js";
 import { AnalysisError } from "../domain/analysisErrorBase.js";
 import { BrowserObservationError } from "../domain/browserObservationError.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { err, ok } from "../domain/result.js";
 import { cleanupOwnedProcessGroup, cleanupWindowsProcessTree, verifyNoTokenOwnedProcesses, } from "../process/ProcessOwnership.js";
-import { observeOwnedProcessLineage } from "../process/ProcessOwnershipObservation.js";
+import { observeOwnedProcessLineage, prepareProcessOwnershipInspection, systemProcessOwnershipHost, } from "../process/ProcessOwnershipObservation.js";
 import { selectCapturedProcessGroupIds } from "../process/ProcessOwnershipProcessTree.js";
 import { runElectronActions, readApplicationState, runWithExecutionLimits, } from "./PlaywrightElectronActiveActions.js";
+import { projectElectronActiveCapture } from "./PlaywrightElectronActiveProjection.js";
 const OPERATION = "capture_electron_scenario";
 const STARTUP_TIMEOUT_MS = 60_000;
 /** Public identity for provider-owned Electron runtime experiments. */
 export { PLAYWRIGHT_ELECTRON_ACTIVE_PROVIDER_IDENTITY } from "./providerIdentities.js";
 import { PLAYWRIGHT_ELECTRON_ACTIVE_PROVIDER_IDENTITY } from "./providerIdentities.js";
 const hookPath = fileURLToPath(new URL("../../scripts/electron-active-hook.cjs", import.meta.url));
-const observableEventFamilies = [
-    "app-lifecycle",
-    "window-lifecycle",
-    "web-contents-lifecycle",
-    "navigation",
-    "shell-attempt",
-    "process-lifecycle",
-    "permission",
-    "popup-attempt",
-    "download",
-    "protocol",
-    "preload",
-    "preload-configuration",
-    "renderer-ipc",
-    "native-addon",
-    "updater",
-    "error",
-    "ipc",
-];
-const ipcEventKinds = new Set([
-    "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",
-]);
-const createCoverage = (hookSnapshot) => {
-    const observedEventFamilies = [
-        ...new Set(hookSnapshot.events.map(({ kind, process_type }) => {
-            if (kind === "preload" && process_type === "main")
-                return "preload-configuration";
-            if (kind.startsWith("ipc-renderer") && process_type !== "renderer")
-                return "ipc";
-            return ipcEventKinds.has(kind) ? "ipc" : kind;
-        })),
-    ].sort();
-    const unavailableEventFamilies = new Set(observableEventFamilies.filter((family) => !observedEventFamilies.includes(family)));
-    const observedRoles = [
-        ...new Set(hookSnapshot.events.flatMap(({ process_type, kind }) => [
-            ...(process_type === null ? [] : [process_type]),
-            ...(kind === "window-lifecycle" ? ["window"] : []),
-            ...(kind === "web-contents-lifecycle" || kind === "navigation"
-                ? ["web_contents"]
-                : []),
-            ...(kind === "preload" && process_type === "preload"
-                ? ["preload"]
-                : []),
-            ...(kind.startsWith("ipc-renderer") && process_type === "renderer"
-                ? ["renderer"]
-                : []),
-        ])),
-    ].sort();
-    const rendererContextObserved = hookSnapshot.events.some(({ process_type }) => process_type === "renderer" || process_type === "preload");
-    if (!rendererContextObserved) {
-        unavailableEventFamilies.add("preload");
-        unavailableEventFamilies.add("renderer-ipc");
-    }
-    return {
-        status: hookSnapshot.hook_error ? "hook_conflict" : "partial_attach",
-        observed_event_families: observedEventFamilies,
-        unavailable_event_families: [...unavailableEventFamilies].sort(),
-        observed_roles: observedRoles,
-        pre_capture_activity: "unavailable",
-    };
-};
 /** Launch an owned Electron application through the official Playwright API. */
 export class PlaywrightElectronActiveProvider {
     identity() {
@@ -96,13 +27,21 @@ export class PlaywrightElectronActiveProvider {
         let application;
         let ownership;
         let lineage;
+        let capture;
+        let paths;
+        let initialState;
+        let actions = [];
         let outcome;
         const runId = randomUUID();
         try {
             if (options.signal?.aborted === true)
                 throw new BrowserObservationError(OPERATION, "cancelled");
+            await prepareProcessOwnershipInspection(options.signal);
             const startupDeadline = Date.now() + STARTUP_TIMEOUT_MS;
-            const paths = await canonicalPaths(input);
+            paths = await canonicalPaths(input);
+            const captureBaseline = await systemProcessOwnershipHost.captureBaseline?.(options.signal);
+            if (options.signal?.aborted)
+                throw new BrowserObservationError(OPERATION, "cancelled");
             application = await electron.launch({
                 executablePath: paths.executable,
                 cwd: paths.root,
@@ -122,17 +61,55 @@ export class PlaywrightElectronActiveProvider {
                 expectedParentPid: process.pid,
                 expectedCommand: paths.executable,
                 sweepTokenOwnedProcesses: true,
+                ...(captureBaseline === undefined ? {} : { captureBaseline }),
             };
-            const actions = await runElectronActions(application, input, options);
-            const state = await runWithExecutionLimits(readApplicationState(application), options.signal);
-            outcome = ok(createResult(paths, input, actions, state));
+            lineage = await observeOwnedProcessLineage(ownership);
+            initialState = await readApplicationState(application);
+            actions = await runElectronActions(application, input, options);
+            const state = await runWithExecutionLimits(readApplicationState(application), undefined, options.signal?.aborted ? Date.now() + 5_000 : undefined);
+            capture = projectElectronActiveCapture(paths, actions, state);
+            outcome = options.signal?.aborted
+                ? err(new BrowserObservationError(OPERATION, "cancelled", {
+                    partialObservation: {
+                        kind: "electron-active-observation",
+                        capture,
+                    },
+                }))
+                : ok(capture);
         }
         catch (cause) {
-            outcome = err(providerError(cause));
+            if (options.signal?.aborted &&
+                paths !== undefined &&
+                initialState !== undefined) {
+                const retainedCapture = projectElectronActiveCapture(paths, actions, initialState);
+                capture = {
+                    ...retainedCapture,
+                    limitations: [
+                        ...retainedCapture.limitations,
+                        `Final Electron state was unavailable after cancellation: ${cause instanceof Error ? cause.message : String(cause)}. Windows, metrics, IPC, and timeline are the snapshot collected before actions and may omit their effects.`,
+                    ],
+                };
+            }
+            outcome = err(options.signal?.aborted === true
+                ? new BrowserObservationError(OPERATION, "cancelled", {
+                    cause,
+                    ...(capture === undefined
+                        ? {}
+                        : {
+                            partialObservation: {
+                                kind: "electron-active-observation",
+                                capture,
+                            },
+                        }),
+                })
+                : providerError(cause));
         }
         if (application !== undefined) {
-            if (ownership !== undefined)
-                lineage = await observeOwnedProcessLineage(ownership);
+            if (ownership !== undefined) {
+                const currentLineage = await observeOwnedProcessLineage(ownership);
+                if (currentLineage.status === "verified" || lineage === undefined)
+                    lineage = currentLineage;
+            }
             let closeError;
             try {
                 await runWithExecutionLimits(application.close(), undefined, Date.now() + 5_000);
@@ -147,11 +124,55 @@ export class PlaywrightElectronActiveProvider {
                 }
                 : await cleanupElectronProcesses(ownership, lineage);
             if (!cleanup.cleaned)
-                return err(providerError(new BrowserObservationError(OPERATION, "cleanup_failed", {
-                    cause: new Error(cleanup.reason),
-                })));
+                return err(new BrowserObservationError(OPERATION, "cleanup_failed", {
+                    cause: outcome.ok ? new Error(cleanup.reason) : outcome.error,
+                    detail: `Electron cleanup could not be verified: ${cleanup.reason}.${capture !== undefined ? " Collected observations are retained in partial_observation." : ""}${outcome.ok ? "" : ` Capture also failed: ${outcome.error.message}.`} Inspect the reported process resources before launching another capture.`,
+                    cleanup: {
+                        reason: cleanup.reason,
+                        resources: ownership === undefined
+                            ? ["owned_process_group"]
+                            : [
+                                "owned_process_group",
+                                `run:${ownership.runId}`,
+                                `process-group:${String(ownership.processGroupId)}`,
+                            ],
+                    },
+                    ...(capture !== undefined
+                        ? {
+                            partialObservation: {
+                                kind: "electron-active-observation",
+                                capture: {
+                                    ...capture,
+                                    application: {
+                                        ...capture.application,
+                                        cleanup: "unverified",
+                                    },
+                                },
+                            },
+                        }
+                        : {}),
+                }));
             if (closeError !== undefined)
-                return err(providerError(closeError));
+                return err(new BrowserObservationError(OPERATION, "cleanup_failed", {
+                    cause: outcome.ok ? closeError : outcome.error,
+                    detail: `Electron transport teardown failed after process cleanup: ${closeError instanceof Error ? closeError.message : String(closeError)}.${capture !== undefined ? " Collected observations are retained in partial_observation." : ""}${outcome.ok ? "" : ` Capture also failed: ${outcome.error.message}.`}`,
+                    ...(capture !== undefined
+                        ? {
+                            partialObservation: {
+                                kind: "electron-active-observation",
+                                capture,
+                            },
+                        }
+                        : {}),
+                }));
+            if (outcome.ok && cleanup.unverified !== undefined)
+                outcome = ok({
+                    ...outcome.value,
+                    limitations: [
+                        ...outcome.value.limitations,
+                        ...cleanup.unverified.map(({ pid, diagnostic }) => `Ownership of unrelated process ${String(pid)} could not be verified; it was left untouched: ${diagnostic}`),
+                    ],
+                });
         }
         return outcome;
     }
@@ -187,6 +208,7 @@ const cleanupElectronProcesses = async (ownership, lineage) => {
         process_group_id: processGroupId,
     })));
     let signaled = false;
+    const unverified = [];
     for (const processGroupId of groupIds) {
         const cleanupOwnership = processGroupId === ownership.processGroupId
             ? { ...ownership, leaderPid: processGroupId, processGroupId }
@@ -199,49 +221,32 @@ const cleanupElectronProcesses = async (ownership, lineage) => {
         if (!result.cleaned)
             return result;
         signaled ||= result.signaled;
+        unverified.push(...(result.unverified ?? []));
     }
-    const remaining = await verifyNoTokenOwnedProcesses(ownership.runId);
+    const remaining = await verifyNoTokenOwnedProcesses(ownership.runId, undefined, ownership.captureBaseline, {
+        leaderPid: ownership.leaderPid,
+        processGroupId: ownership.processGroupId,
+        ...(ownership.sampledProcessGroupIds === undefined
+            ? {}
+            : { sampledProcessGroupIds: ownership.sampledProcessGroupIds }),
+    });
     if (!remaining.cleaned)
         return remaining;
-    return { cleaned: true, signaled };
-};
-const createResult = (paths, input, actions, state) => {
-    const { hookSnapshot } = state;
-    const ipcEvents = hookSnapshot.events.filter(({ kind }) => ipcEventKinds.has(kind));
-    return electronActiveObservationResultSchema.parse({
-        application: {
-            executable_path: paths.executable,
-            application_path: paths.application,
-            electron_version: state.electronVersion,
-            process_ownership: "provider-owned",
-            cleanup: "terminated-owned-process",
-        },
-        actions,
-        windows: state.windows,
-        processes: {
-            items: state.metrics,
-        },
-        ipc: {
-            events: ipcEvents,
-            observed: hookSnapshot.observed_ipc,
-        },
-        timeline: {
-            events: hookSnapshot.events,
-            observed: hookSnapshot.observed,
-        },
-        coverage: createCoverage(hookSnapshot),
-        limitations: [
-            "IPC payloads are represented by value shapes; payload values are never retained.",
-            "IPC direction and sender/receiver identifiers are observed only where Electron exposes them at the hooked boundary.",
-            "The runtime timeline records lifecycle, navigation, shell, permission, popup, download, protocol, preload, native-addon, process, and IPC events; activity before hook installation is unavailable.",
-            "The preload and renderer process contexts are not instrumented by the main-process -r hook; preload configuration and contextBridge API-shape events are main-boundary observations, not proof of renderer-side execution.",
-            "Process metrics are an Electron API snapshot and do not prove hostile-local-user isolation.",
-            "External shell opens, external navigation, permission grants, downloads, popup windows, updater relaunches, and OS integration are blocked and recorded by the active hook; other application filesystem and network behavior is not sandboxed by this provider.",
-            ...(hookSnapshot.hook_error
-                ? ["The active IPC hook could not be installed."]
-                : []),
-        ],
-    });
+    unverified.push(...(remaining.unverified ?? []));
+    return {
+        cleaned: true,
+        signaled,
+        ...(unverified.length === 0
+            ? {}
+            : {
+                unverified: [
+                    ...new Map(unverified.map((item) => [
+                        `${String(item.pid)}:${item.diagnostic}`,
+                        item,
+                    ])).values(),
+                ],
+            }),
+    };
 };
 const canonicalPaths = async (input) => {
     const [executable, application] = await Promise.all([
@@ -272,4 +277,7 @@ const providerError = (cause) => cause instanceof AnalysisError
     ? cause
     : new ProviderAdapterError(PLAYWRIGHT_ELECTRON_ACTIVE_PROVIDER_IDENTITY.id, OPERATION, {
         cause,
+        diagnostics: {
+            message: cause instanceof Error ? cause.message : String(cause),
+        },
     });