rea-agents 6.5.0 → 6.7.0

package/dist/browser/PlaywrightElectronActiveFuses.js

@@ -0,0 +1,86 @@
+import { assertArtifactReadActive } from "../artifacts/ArtifactFileOperation.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { electronFuseFailure } from "../electron/ElectronFuseFailures.js";
+import { basename, dirname } from "node:path";
+import { AnalysisUnsupportedTargetError } from "../domain/analysisErrorCore.js";
+import { resolveElectronFuseTarget } from "../electron/ElectronFusePath.js";
+import { readElectronFuseImage } from "../electron/ElectronFuseReader.js";
+const OPERATION = "capture_electron_scenario";
+const NODE_CLI_INSPECT_ARGUMENTS_FUSE_INDEX = 3;
+const appBundleDirectoryOf = (executablePath) => {
+    let current = dirname(executablePath);
+    while (true) {
+        if (basename(current).endsWith(".app"))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+};
+/**
+ * Pre-flight verification for active Electron scenario capture.
+ *
+ * Playwright attaches to Electron processes using Node CLI inspect arguments
+ * (--inspect=0 or --remote-debugging-port=0). When an Electron executable disables
+ * the EnableNodeCliInspectArguments fuse, the runtime silently ignores inspect
+ * flags and Playwright hangs until the 60-second startup deadline expires.
+ *
+ * When the fuse wire is present and index 3 is explicitly disabled or removed,
+ * this check fast-fails with an AnalysisUnsupportedTargetError before any child
+ * process is launched. When the fuse state is unknown (missing sentinel, wire
+ * version != 1, or unsupported container format), launch proceeds normally.
+ */
+export const assertNodeCliInspectArgumentsSupported = async (executablePath, options) => {
+    assertArtifactReadActive(options?.signal);
+    const reader = options?.readFuseImage ?? readElectronFuseImage;
+    const resolver = options?.resolveFuseTarget ?? resolveElectronFuseTarget;
+    try {
+        let targetPath = executablePath;
+        const bundleDir = appBundleDirectoryOf(executablePath);
+        if (bundleDir !== null) {
+            try {
+                const resolved = await resolver(bundleDir, options?.signal);
+                targetPath = resolved.file.path;
+            }
+            catch (cause) {
+                if (options?.signal?.aborted)
+                    throw cause;
+                targetPath = executablePath;
+            }
+        }
+        const image = await reader(targetPath, {
+            ...(options?.signal === undefined ? {} : { signal: options.signal }),
+            ...(options?.resources === undefined
+                ? {}
+                : { resources: options.resources }),
+        });
+        if (image.slices.length === 0)
+            return;
+        const hostArchitecture = process.arch === "x64" ? "x86_64" : process.arch;
+        const targetSlice = image.slices.find((slice) => slice.architecture === hostArchitecture) ??
+            image.slices[0];
+        if (targetSlice === undefined)
+            return;
+        for (const sentinel of targetSlice.sentinels) {
+            if (sentinel.wire_version !== 1)
+                continue;
+            const fuse = sentinel.fuses.find((entry) => entry.index === NODE_CLI_INSPECT_ARGUMENTS_FUSE_INDEX ||
+                entry.name === "EnableNodeCliInspectArguments");
+            if (fuse?.state === "disabled" || fuse?.state === "removed") {
+                throw new AnalysisUnsupportedTargetError(OPERATION, executablePath, "Target binary disables the EnableNodeCliInspectArguments fuse; Node CLI inspector arguments are ignored and active scenario capture cannot attach.", {
+                    remediationAction: "Use passive CDP observation tools (inspect_electron_page), or launch active capture against an Electron development build or a stock Electron runtime with the extracted app.",
+                });
+            }
+        }
+    }
+    catch (cause) {
+        if (cause instanceof AnalysisUnsupportedTargetError)
+            throw cause;
+        if (cause instanceof ArtifactReaderFailure &&
+            (cause.cleanup !== undefined || cause.reason === "cancelled"))
+            throw electronFuseFailure(cause, executablePath, OPERATION);
+        assertArtifactReadActive(options?.signal);
+        // Missing sentinels, format failures, or unreadable fuses leave inspection capability unknown; proceed with launch.
+    }
+};

package/dist/browser/PlaywrightElectronActiveProjection.js

@@ -125,6 +125,11 @@ export const projectElectronActiveCapture = (paths, actions, state) => {
         coverage: createCoverage(hookSnapshot, observations),
         limitations: [
             "IPC payloads are represented by value shapes; payload values are never retained.",
+            ...(observations.observedEventFamilies.includes("ipc-observation-gap")
+                ? [
+                    "IPC observation gaps have unobserved callback arguments and execution. Available ipc-observation-gap timeline records identify the custom-apply or listener-chain boundary and registered channel; dropped gap records are counted by retention. Listener-chain gaps describe registration uncertainty, not proof of IPC delivery.",
+                ]
+                : []),
             "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.",

package/dist/browser/PlaywrightElectronActiveProvider.js

@@ -1,14 +1,22 @@
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { bindArtifactFileCleanup } from "../artifacts/ArtifactFileOperation.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { ElectronCaptureCleanup } from "./ElectronCaptureCleanup.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
+import { electronFuseFailure } from "../electron/ElectronFuseFailures.js";
 import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.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, prepareProcessOwnershipInspection, systemProcessOwnershipHost, } from "../process/ProcessOwnershipObservation.js";
-import { selectCapturedProcessGroupIds } from "../process/ProcessOwnershipProcessTree.js";
-import { runElectronActions, readApplicationState, runWithExecutionLimits, } from "./PlaywrightElectronActiveActions.js";
+import { runElectronActions, readApplicationState, readFinalApplicationState, runWithExecutionLimits, } from "./PlaywrightElectronActiveActions.js";
 import { projectElectronActiveCapture } from "./PlaywrightElectronActiveProjection.js";
+import { readElectronFuseImage } from "../electron/ElectronFuseReader.js";
+import { assertNodeCliInspectArgumentsSupported } from "./PlaywrightElectronActiveFuses.js";
 const OPERATION = "capture_electron_scenario";
 const STARTUP_TIMEOUT_MS = 60_000;
 import { PLAYWRIGHT_ELECTRON_ACTIVE_PROVIDER_IDENTITY } from "./providerIdentities.js";
@@ -17,16 +25,42 @@ const hookPath = fileURLToPath(new URL("../../scripts/electron-active-hook.cjs",
 export class PlaywrightElectronActiveProvider {
     environment;
     launch;
+    readFuseImage;
+    #resources = new ArtifactResourceScope();
+    #shutdown = new AbortController();
+    /** Stop admitting work, cancel and join captures, then retry exact retained resource owners. */
+    async close() {
+        this.#shutdown.abort(new Error("Electron active provider is closing"));
+        try {
+            await this.#resources.close();
+        }
+        catch (cause) {
+            throw providerError(cause);
+        }
+    }
     constructor(environment, 
     // Load Playwright only when a capture launches; MCP startup stays off its module graph.
-    launch = async (options) => (await import("playwright-core"))._electron.launch(options)) {
+    launch = async (options) => (await import("playwright-core"))._electron.launch(options), readFuseImage = readElectronFuseImage) {
         this.environment = environment;
         this.launch = launch;
+        this.readFuseImage = readFuseImage;
     }
     identity() {
         return PLAYWRIGHT_ELECTRON_ACTIVE_PROVIDER_IDENTITY;
     }
     async capture(input, options = {}) {
+        const signal = AbortSignal.any([
+            this.#shutdown.signal,
+            ...(options.signal === undefined ? [] : [options.signal]),
+        ]);
+        try {
+            return await this.#resources.run(() => this.#capture(input, { ...options, signal }));
+        }
+        catch (cause) {
+            return err(providerError(cause));
+        }
+    }
+    async #capture(input, options) {
         let application;
         let ownership;
         let lineage;
@@ -46,6 +80,22 @@ export class PlaywrightElectronActiveProvider {
                 application: input.application_path,
                 root: input.application_root,
             };
+            const preflight = assertNodeCliInspectArgumentsSupported(input.executable_path, {
+                resources: this.#resources,
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
+                readFuseImage: this.readFuseImage,
+            }).catch((cause) => {
+                throw electronFuseFailure(cause, input.executable_path, OPERATION);
+            });
+            try {
+                await runWithExecutionLimits(preflight, options.signal, startupDeadline);
+            }
+            catch (interruption) {
+                // A startup interruption cannot abandon an admitted descriptor's final
+                // close. Its physical/cleanup failure takes precedence over the race.
+                await preflight;
+                throw interruption;
+            }
             const captureBaseline = await systemProcessOwnershipHost.captureBaseline?.(options.signal);
             if (options.signal?.aborted)
                 throw new BrowserObservationError(OPERATION, "cancelled");
@@ -56,7 +106,10 @@ export class PlaywrightElectronActiveProvider {
                 args: ["-r", hookPath, paths.application, ...input.args],
                 timeout: Math.max(1, startupDeadline - performance.now()),
             };
-            application = await containLaunchRejections(() => this.launch(launchOptions));
+            application = await containLaunchRejections(() => {
+                options.signal?.throwIfAborted();
+                return this.launch(launchOptions);
+            });
             const leaderPid = application.process().pid;
             if (typeof leaderPid !== "number" ||
                 !Number.isSafeInteger(leaderPid) ||
@@ -72,17 +125,14 @@ export class PlaywrightElectronActiveProvider {
                 ...(captureBaseline === undefined ? {} : { captureBaseline }),
             };
             lineage = await observeOwnedProcessLineage(ownership);
-            initialState = await readApplicationState(application);
+            initialState = await runWithExecutionLimits(readApplicationState(application), options.signal, startupDeadline);
             actions = await runElectronActions(application, input, options);
-            const state = await runWithExecutionLimits(readApplicationState(application), undefined, options.signal?.aborted ? performance.now() + 5_000 : undefined);
+            const state = await readFinalApplicationState(application, options.signal);
             capture = projectElectronActiveCapture(paths, actions, state);
+            // Preserve a cancellation already observed before finalization so a
+            // later cleanup failure keeps its cause. Late cancellation is checked below.
             outcome = options.signal?.aborted
-                ? err(new BrowserObservationError(OPERATION, "cancelled", {
-                    partialObservation: {
-                        kind: "electron-active-observation",
-                        capture,
-                    },
-                }))
+                ? err(cancelledCapture(capture, options.signal.reason))
                 : ok(capture);
         }
         catch (cause) {
@@ -96,9 +146,11 @@ export class PlaywrightElectronActiveProvider {
                     ],
                 };
             }
-            if (options.signal?.aborted === true)
+            if (cause instanceof AnalysisError && cause.cleanupIncomplete)
+                outcome = err(cause);
+            else if (options.signal?.aborted === true)
                 outcome = err(new BrowserObservationError(OPERATION, "cancelled", {
-                    cause,
+                    ...cancellationCause(cause, options.signal),
                     ...(capture === undefined
                         ? {}
                         : {
@@ -119,67 +171,51 @@ export class PlaywrightElectronActiveProvider {
             }
         }
         if (application !== undefined) {
-            if (ownership !== undefined) {
-                const currentLineage = await observeOwnedProcessLineage(ownership);
-                if (currentLineage.status === "verified" || lineage === undefined)
-                    lineage = currentLineage;
-            }
-            let closeError;
-            try {
-                await runWithExecutionLimits(application.close(), undefined, performance.now() + 5_000);
-            }
-            catch (cause) {
-                closeError = cause;
-            }
-            const cleanup = ownership === undefined
-                ? {
-                    cleaned: false,
-                    reason: "owned Electron process identity was unavailable",
-                }
-                : await cleanupElectronProcesses(ownership, lineage);
-            if (!cleanup.cleaned)
-                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(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
-                        ? {
+            const owner = new ElectronCaptureCleanup(application, ownership, lineage);
+            const released = await owner.release(this.#resources);
+            const cleanup = owner.processResult;
+            if (outcome.ok && options.signal?.aborted === true)
+                outcome = err(cancelledCapture(outcome.value, options.signal.reason));
+            if (released.processes.kind === "failed" ||
+                released.transport.kind === "failed") {
+                const processFailure = released.processes.kind === "failed";
+                const failures = [released.processes, released.transport].flatMap((attempt) => (attempt.kind === "failed" ? [attempt.cause] : []));
+                const cause = failures.length === 1
+                    ? failures[0]
+                    : new AggregateError(failures, "Electron process and transport cleanup failed");
+                const reason = failures
+                    .map((failure) => failure instanceof Error ? failure.message : String(failure))
+                    .join("; ");
+                const failure = new BrowserObservationError(OPERATION, "cleanup_failed", {
+                    cause,
+                    detail: `${processFailure ? "Electron process cleanup could not be verified" : "Electron transport teardown failed after process cleanup"}: ${reason}. Collected observations are retained when available.`,
+                    cleanup: { reason, resources: owner.pendingResources },
+                    ...(capture === undefined
+                        ? {}
+                        : {
                             partialObservation: {
                                 kind: "electron-active-observation",
-                                capture,
+                                capture: processFailure
+                                    ? {
+                                        ...capture,
+                                        application: {
+                                            ...capture.application,
+                                            cleanup: "unverified",
+                                        },
+                                    }
+                                    : capture,
                             },
-                        }
-                        : {}),
-                }));
-            if (outcome.ok && cleanup.unverified !== undefined)
+                        }),
+                });
+                owner.bind(failure);
+                if (outcome.ok)
+                    return err(failure);
+                const composed = analysisErrorWithCleanupFailure(outcome.error, failure, OPERATION).bindCleanupDependencies([outcome.error, failure]);
+                if (failure.partialObservation !== undefined)
+                    composed.partialObservation = failure.partialObservation;
+                return err(composed);
+            }
+            if (outcome.ok && cleanup?.cleaned && cleanup.unverified !== undefined)
                 outcome = ok({
                     ...outcome.value,
                     limitations: [
@@ -188,85 +224,31 @@ export class PlaywrightElectronActiveProvider {
                     ],
                 });
         }
+        // Cleanup failures returned above keep precedence; a completed capture
+        // observed under late cancellation is retained as partial Evidence.
+        if (outcome.ok && options.signal?.aborted === true)
+            return err(cancelledCapture(outcome.value, options.signal.reason));
         return outcome;
     }
 }
-/** Clean up an Electron launch. Windows signals a process only after lineage is verified. */
-export const cleanupElectronProcesses = async (ownership, lineage, host = {
-    platform: process.platform,
-    terminateTree: cleanupWindowsProcessTree,
-}) => {
-    if (host.platform === "win32") {
-        // An empty Windows process table is not ownership proof for this PID.
-        if (lineage?.status !== "verified")
-            return {
-                cleaned: false,
-                reason: "owned Electron lineage was unavailable; helper cleanup was not proven",
-            };
-        const root = await host.terminateTree(ownership.leaderPid);
-        if (!root.cleaned)
-            return root;
-        for (const descendant of lineage.lineage.descendants) {
-            const result = await host.terminateTree(descendant.pid);
-            if (!result.cleaned)
-                return result;
-        }
-        return root;
-    }
-    if (lineage?.status !== "verified") {
-        const root = await cleanupOwnedProcessGroup(ownership);
-        return root.cleaned
-            ? {
-                cleaned: false,
-                reason: "owned Electron lineage was unavailable; helper cleanup was not proven",
-            }
-            : root;
-    }
-    const groupIds = selectCapturedProcessGroupIds(ownership.leaderPid, lineage.lineage.descendants.map(({ pid, processGroupId }) => ({
-        pid,
-        process_group_id: processGroupId,
-    })));
-    let signaled = false;
-    const unverified = [];
-    for (const processGroupId of groupIds) {
-        const cleanupOwnership = processGroupId === ownership.processGroupId
-            ? { ...ownership, leaderPid: processGroupId, processGroupId }
-            : {
-                runId: ownership.runId,
-                leaderPid: processGroupId,
-                processGroupId,
-            };
-        const result = await cleanupOwnedProcessGroup(cleanupOwnership);
-        if (!result.cleaned)
-            return result;
-        signaled ||= result.signaled;
-        unverified.push(...(result.unverified ?? []));
-    }
-    const remaining = await verifyNoTokenOwnedProcesses(ownership.runId, undefined, ownership.captureBaseline, {
-        leaderPid: ownership.leaderPid,
-        processGroupId: ownership.processGroupId,
-        ...(ownership.sampledProcessGroupIds === undefined
+const cancelledCapture = (capture, reason) => new BrowserObservationError(OPERATION, "cancelled", {
+    cause: reason,
+    partialObservation: { kind: "electron-active-observation", capture },
+});
+/**
+ * A cancellation wrapper stands in for the caller's abort reason and keeps its
+ * producer diagnostics; any other failure observed with cancellation stays the
+ * primary cause.
+ */
+const cancellationCause = (cause, signal) => cause instanceof AnalysisCancelledError ||
+    (cause instanceof AnalysisError && cause.userCategory === "cancelled")
+    ? {
+        cause: signal.reason,
+        ...(cause.diagnostics === undefined
             ? {}
-            : { sampledProcessGroupIds: ownership.sampledProcessGroupIds }),
-    });
-    if (!remaining.cleaned)
-        return remaining;
-    unverified.push(...(remaining.unverified ?? []));
-    return {
-        cleaned: true,
-        signaled,
-        ...(unverified.length === 0
-            ? {}
-            : {
-                unverified: [
-                    ...new Map(unverified.map((item) => [
-                        `${String(item.pid)}:${item.diagnostic}`,
-                        item,
-                    ])).values(),
-                ],
-            }),
-    };
-};
+            : { diagnostics: cause.diagnostics }),
+    }
+    : { cause };
 export const safeElectronEnvironment = (environment, runId, platform = process.platform) => Object.fromEntries([
     ...[
         "HOME",
@@ -355,11 +337,18 @@ const containLaunchRejections = async (launch) => {
         }
     }
 };
-const providerError = (cause) => cause instanceof AnalysisError
-    ? cause
-    : new ProviderAdapterError(PLAYWRIGHT_ELECTRON_ACTIVE_PROVIDER_IDENTITY.id, OPERATION, {
+const providerError = (cause) => {
+    if (cause instanceof AnalysisError)
+        return cause;
+    if (cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined) {
+        const failure = new ProviderCleanupError(PLAYWRIGHT_ELECTRON_ACTIVE_PROVIDER_IDENTITY.id, cause.cleanup.resources, { reason: cause.cleanup.reason }, { operation: OPERATION, cause });
+        bindArtifactFileCleanup(cause, failure);
+        return failure;
+    }
+    return new ProviderAdapterError(PLAYWRIGHT_ELECTRON_ACTIVE_PROVIDER_IDENTITY.id, OPERATION, {
         cause,
         diagnostics: {
             message: cause instanceof Error ? cause.message : String(cause),
         },
     });
+};

package/dist/browser/PlaywrightExecutionBoundary.js

@@ -1,10 +1,12 @@
 import { AnalysisCancelledError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
 const OPERATION = "capture_browser_scenario";
+// Chrome shutdown can take several seconds; expiry bounds the response, not ownership.
+export const PLAYWRIGHT_CLEANUP_CONFIRMATION_TIMEOUT_MS = 30_000;
 export const withPlaywrightExecutionBoundary = (work, timeoutMs, signal) => {
     if (timeoutMs !== undefined && timeoutMs <= 0)
         return Promise.reject(new AnalysisTimeoutError(OPERATION, timeoutMs));
     if (signal?.aborted === true)
-        return Promise.reject(new AnalysisCancelledError(OPERATION));
+        return Promise.reject(new AnalysisCancelledError(OPERATION, { cause: signal.reason }));
     return new Promise((resolve, reject) => {
         let settled = false;
         let timer;
@@ -40,7 +42,7 @@ export const withPlaywrightExecutionBoundary = (work, timeoutMs, signal) => {
             reject(error);
         };
         const onAbort = () => {
-            fail(new AnalysisCancelledError(OPERATION));
+            fail(new AnalysisCancelledError(OPERATION, { cause: signal?.reason }));
         };
         scheduleTimeout();
         signal?.addEventListener("abort", onAbort, { once: true });