rea-agents 3.0.0 → 3.1.0

package/dist/application/ManagedRuntimeCorrelationService.js

@@ -6,6 +6,10 @@ import { err, ok } from "../domain/result.js";
 import { MANAGED_WORKFLOW_PROVIDER } from "./InvestigationProviders.js";
 import { digestJson } from "./JavaScriptReplayPlanning.js";
 const OPERATION = "plan_managed_runtime_correlation";
+/** A managed-runtime policy that grants no runtime-correlation authority. */
+export const MANAGED_RUNTIME_DISABLED = {
+    status: "disabled",
+};
 /** Create a separately authorized, non-executing managed runtime plan Evidence. */
 export const planManagedRuntimeCorrelationEvidence = async (dependencies, rawInput) => {
     const parsed = managedRuntimeCorrelationInputSchema.safeParse(rawInput);
@@ -15,12 +19,12 @@ export const planManagedRuntimeCorrelationEvidence = async (dependencies, rawInp
 };
 /** Plan runtime correlation from input parsed by a trusted adapter. */
 export const planManagedRuntimeCorrelationEvidenceValidated = async (dependencies, input) => {
-    if (!dependencies.policy.enabled)
+    const policy = dependencies.policy();
+    if (policy.status === "disabled")
         return err(new AnalysisCapabilityUnavailableError(MANAGED_WORKFLOW_PROVIDER.id, OPERATION, "managed runtime correlation is disabled; configure exact roots and runtime executable before enabling it"));
     if (dependencies.authority === undefined)
         return err(new AnalysisCapabilityUnavailableError(MANAGED_WORKFLOW_PROVIDER.id, OPERATION, "managed runtime permission policy is not configured"));
-    let staticEvidence;
-    let artifactPath;
+    let staticEvidence, artifactPath;
     try {
         staticEvidence = parseEvidence(input.static_members);
         artifactPath = artifactPathFor(staticEvidence);
@@ -31,7 +35,7 @@ export const planManagedRuntimeCorrelationEvidenceValidated = async (dependencie
     const authorized = await dependencies.authority.explain({
         capability: "managed_runtime",
         roots: [artifactPath],
-        executables: [dependencies.policy.executablePath],
+        executables: [policy.executablePath],
         environment_names: [],
         network: "none",
         mount: false,
@@ -44,7 +48,7 @@ export const planManagedRuntimeCorrelationEvidenceValidated = async (dependencie
                 cause: authorized.error,
             }));
     try {
-        const result = planManagedRuntimeCorrelation(input, dependencies.policy.executablePath, authorized.value.grant_id);
+        const result = planManagedRuntimeCorrelation(input, policy.executablePath, authorized.value.grant_id);
         return ok(createEvidence({
             path: result.static_observation.artifact_path,
             sha256: result.static_observation.artifact_sha256,

package/dist/application/NodeRuntimeCharacterizationService.js

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { nodeCharacterizationExecutionInputSchema, nodeCharacterizationExecutionOutputSchema, nodeCharacterizationPreparationInputSchema, nodeCharacterizationPreparationOutputSchema, } from "../domain/nodeRuntimeCharacterization.js";
 import { AnalysisInputError, AnalysisProtocolError, ReplayPlanStaleError, } from "../domain/errors.js";
 import { createEvidence } from "../domain/evidence.js";
-import { controlledReplayOutputSchema } from "../domain/javascriptReplay.js";
+import { controlledReplayOutputSchema, } from "../domain/javascriptReplay.js";
 import { createRuntimeCharacterizationPlan, } from "../domain/runtimeCharacterization.js";
 import { err, ok } from "../domain/result.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
@@ -37,7 +37,7 @@ export const executeNodeCharacterization = async (dependencies, rawInput, option
     if (prepared.value.plan.plan_sha256 !== parsed.data.approved_plan_sha256)
         return err(new ReplayPlanStaleError(parsed.data.approved_plan_sha256, prepared.value.plan.plan_sha256));
     const plannedReplay = controlledReplayOutputSchema.parse(prepared.value.replay);
-    if (plannedReplay.phase !== "plan" || plannedReplay.plan === null)
+    if (plannedReplay.phase !== "plan")
         return err(new AnalysisProtocolError("Node characterization preparation did not produce a replay plan"));
     const host = new InstrumentedJavaScriptReplayHost(dependencies.host, parsed.data.preparation.instrumentation);
     const executed = await runControlledReplayValidated({ ...dependencies, host }, {
@@ -48,6 +48,9 @@ export const executeNodeCharacterization = async (dependencies, rawInput, option
     }, options);
     if (!executed.ok)
         return executed;
+    const replayOutput = controlledReplayOutputSchema.parse(executed.value);
+    if (replayOutput.phase !== "execute")
+        return err(new AnalysisProtocolError("Node characterization execution omitted replay Evidence"));
     if (host.instrumentation === null)
         return err(new AnalysisProtocolError("Node characterization execution omitted instrumentation evidence"));
     return ok(jsonValueSchema.parse(nodeCharacterizationExecutionOutputSchema.parse({
@@ -56,8 +59,8 @@ export const executeNodeCharacterization = async (dependencies, rawInput, option
         plan: prepared.value.plan,
         transformation: host.instrumentation.manifest,
         transformation_evidence: prepared.value.transformation_evidence,
-        evidence: createCharacterizationEvidence(prepared.value, controlledReplayOutputSchema.parse(executed.value)),
-        replay: controlledReplayOutputSchema.parse(executed.value),
+        evidence: createCharacterizationEvidence(prepared.value, replayOutput),
+        replay: replayOutput,
     })));
 };
 const prepareValidated = async (dependencies, input, options) => {
@@ -66,9 +69,7 @@ const prepareValidated = async (dependencies, input, options) => {
     if (!replay.ok)
         return replay;
     const output = controlledReplayOutputSchema.parse(replay.value);
-    if (output.phase !== "plan" ||
-        output.plan === null ||
-        host.instrumentation === null)
+    if (output.phase !== "plan" || host.instrumentation === null)
         return err(new AnalysisProtocolError("Node characterization preparation omitted committed plan evidence"));
     const module = output.plan.left.modules.find(({ alias }) => alias === input.selected_alias);
     if (module === undefined)
@@ -109,8 +110,6 @@ const createTransformationEvidence = (input, instrumentation) => createEvidence(
     ],
 });
 const createCharacterizationEvidence = (prepared, replay) => {
-    if (replay.phase !== "execute" || replay.evidence === null)
-        throw new AnalysisProtocolError("Node characterization execution omitted replay Evidence");
     return createEvidence({
         path: prepared.plan.artifact.path,
         sha256: prepared.plan.artifact.sha256,

package/dist/application/ProcessCaptureLifecycle.js

@@ -264,6 +264,11 @@ export const resolveProcessResult = (capture, executionFailure, cleanupFailure)
     return capture;
 };
 export const prepareProcessCapture = async (scenario, policy, signal, host = systemProcessPreparationHost) => {
+    if (policy.status === "disabled")
+        throw new ProcessCaptureError("process capture is disabled", {
+            userCategory: "permission_required",
+            userMessage: processPolicyMessage("process capture is disabled"),
+        });
     const decision = authorizeProcessScenario(scenario, policy);
     if (!decision.allowed)
         throw new ProcessCaptureError(decision.reason, {

package/dist/application/ProcessCli.js

@@ -128,7 +128,8 @@ const readJson = async (path) => {
     if (bytes.length > MAX_INPUT_BYTES)
         throw new ProcessCliFailure("truncated", "Process input file is too large. Reduce it below 64 MiB, then try again.");
     try {
-        return JSON.parse(bytes.toString("utf8"));
+        const parsed = JSON.parse(bytes.toString("utf8"));
+        return parsed;
     }
     catch {
         throw new ProcessCliFailure("invalid_input", "Process input file is not valid JSON. Repair the file, then try again.");

package/dist/application/ProcessHarness.js

@@ -184,13 +184,18 @@ const completeCapture = async (options) => {
         }
         throw processCaptureCancelled();
     }
+    const settlement = await observeSettlement(options.runId, selectCapturedProcessGroupIds(runtime.terminal.pid, options.samples), scenario.settle_ms, options.recordEvent);
+    runtime.checkpoints.trigger("settled");
+    const samplingPartial = (await runtime.stopSampler()).partial;
     if (runtime.reactive !== undefined) {
+        // Process, filesystem, shim, and protocol observations can be recorded
+        // during settlement after the PTY exits. Make target loss terminal only
+        // after that journal has drained, otherwise the coordinator's control
+        // priority discards a valid multi-source completion predicate.
+        await runtime.reactive.coordinator.drain();
         await runtime.reactive.coordinator.submit({ kind: "target_lost" });
         runtime.reactive.unsubscribe();
     }
-    const settlement = await observeSettlement(options.runId, selectCapturedProcessGroupIds(runtime.terminal.pid, options.samples), scenario.settle_ms, options.recordEvent);
-    runtime.checkpoints.trigger("settled");
-    const samplingPartial = (await runtime.stopSampler()).partial;
     assertNotCancelled(options.signal);
     const after = await snapshotRoots(scenario, options.signal);
     const renderedFrames = await runtime.renderer.frames();

package/dist/application/ProcessNormalization.js

@@ -39,9 +39,10 @@ export const normalizeProcessSamples = (samples, scenario, rootPid) => {
             mapping.set(identifier, mapping.size + 1);
     const normalizeCommand = (command) => {
         const normalized = normalizeProcessText(command, scenario, "<no-temporary-root>", rootPid);
-        return scenario.normalization.pids
+        const withNormalizedPids = scenario.normalization.pids
             ? normalizePidTokens(normalized, identifiers)
             : normalized;
+        return withNormalizedPids.trim();
     };
     return samples.map((sample) => ({
         at_ms: normalizeProcessElapsedTime(sample.at_ms, scenario.normalization.time_bucket_ms),

package/dist/application/ProjectPermissionStore.js

@@ -13,6 +13,7 @@ const grantSchema = z.object({
         "browser_observe",
         "browser_automate",
         "electron_observe",
+        "electron_automate",
         "evidence_read",
         "evidence_write",
         "investigation_input",

package/dist/application/ReferenceSourceImport.js

@@ -173,7 +173,7 @@ export const importReferenceSource = async (options) => {
     try {
         return ok(createHistoricalSourceGraph(input));
     }
-    catch (error) {
-        return err(failure("parse", error instanceof Error ? error.message : "Graph failed validation"));
+    catch (cause) {
+        return err(failure("parse", cause instanceof Error ? cause.message : "Graph failed validation"));
     }
 };

package/dist/application/SetupClientConfiguration.js

@@ -1,6 +1,7 @@
 import { constants as fsConstants } from "node:fs";
 import { copyFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
+import canonicalize from "canonicalize";
 import { z } from "zod";
 import writeFileAtomic from "write-file-atomic";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
@@ -187,7 +188,11 @@ const objectSchema = z.record(z.string(), z.unknown());
 const parseOptionalObject = (value) => value === undefined ? {} : objectSchema.parse(value);
 const parseObject = (text) => objectSchema.parse(JSON.parse(text));
 const isMissing = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";
-const sameConfiguration = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const sameConfiguration = (left, right) => {
+    const encodedLeft = canonicalize(left);
+    const encodedRight = canonicalize(right);
+    return encodedLeft !== undefined && encodedLeft === encodedRight;
+};
 const preserveConfigBackup = async (source, destination) => {
     try {
         await copyFile(source, destination, fsConstants.COPYFILE_EXCL);

package/dist/application/WindowsCapabilities.js

@@ -2,6 +2,7 @@ import { constants } from "node:fs";
 import { mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { windowsNativeCapabilities, } from "../process/WindowsAuthority.js";
 import { probeProcessCaptureCapability, } from "./ProcessCaptureCapability.js";
 /** Probe named prerequisites without converting missing controls into support. */
 export const probeWindowsCapabilities = async (dependencies = systemDependencies()) => {
@@ -17,11 +18,11 @@ export const probeWindowsCapabilities = async (dependencies = systemDependencies
             no_follow_open: dependencies.probeNoFollowOpen(),
             private_acl: dependencies.probePrivateAcl(),
             unix_domain_socket: dependencies.probeUnixDomainSocket(),
-            pty: {
-                available: pty.available,
-                reason: pty.available ? null : pty.reason,
-            },
+            pty: pty.available
+                ? { available: true, reason: null }
+                : { available: false, reason: pty.reason },
         },
+        security: windowsNativeCapabilities(dependencies.platform),
     };
 };
 const systemDependencies = () => ({

package/dist/artifacts/ArtifactProvider.js

@@ -8,6 +8,7 @@ import { ArtifactReaderFailure, } from "./ArtifactReader.js";
 import { ARTIFACT_GRAPH_PROVIDER } from "../application/InvestigationProviders.js";
 import { createEvidence } from "../domain/evidence.js";
 import { createArtifactInspection } from "../domain/artifactInspection.js";
+import { resolveArtifactIntegrityPolicy, resolveNativeMountPolicy, } from "../application/ArtifactInventory/policy.js";
 const IDENTITY = Object.freeze(ARTIFACT_GRAPH_PROVIDER);
 /** Read-only inventory and exclusively owned extraction provider. */
 export class ArtifactProvider {
@@ -180,16 +181,13 @@ class ArtifactClient {
             edgeLimit: parsed.edge_limit,
         }, {
             ...(options?.signal === undefined ? {} : { signal: options.signal }),
-            nativeMount: {
-                nativeMountApproved: parsed.native_mount_approved === true,
-                nativeMountEnabled: this.nativeMountEnabled,
-            },
-            integrity: {
-                mode: parsed.integrity_policy,
-                approved: parsed.integrity_continue_approved === true,
-                enabled: this.integrityContinueEnabled,
-                maxMismatches: parsed.max_integrity_mismatches,
-            },
+            nativeMount: resolveNativeMountPolicy(parsed.native_mount_approved === true, this.nativeMountEnabled),
+            integrity: resolveArtifactIntegrityPolicy(parsed.integrity_policy === "fail"
+                ? { mode: "fail" }
+                : {
+                    mode: parsed.integrity_policy,
+                    maxMismatches: parsed.max_integrity_mismatches,
+                }, this.integrityContinueEnabled),
         });
     }
 }

package/dist/artifacts/SafeOutputTree.js

@@ -14,9 +14,7 @@ export class SafeOutputTree {
     #totalBytes = 0;
     #published = false;
     #cleanup = {
-        attempted: false,
-        verified: false,
-        residualPaths: [],
+        status: "not-required",
     };
     constructor(outputRoot, stagingRoot, limits) {
         this.#outputRoot = outputRoot;
@@ -126,11 +124,12 @@ export class SafeOutputTree {
             return structuredClone(this.#cleanup);
         await rm(this.#stagingRoot, { recursive: true, force: true });
         const absent = await isAbsent(this.#stagingRoot);
-        this.#cleanup = {
-            attempted: true,
-            verified: absent,
-            residualPaths: absent ? [] : [basename(this.#stagingRoot)],
-        };
+        this.#cleanup = absent
+            ? { status: "complete", residualPaths: [] }
+            : {
+                status: "incomplete",
+                residualPaths: [basename(this.#stagingRoot)],
+            };
         if (!absent)
             throw new ArtifactReaderFailure("integrity", "Extraction output cleanup could not be verified");
         return structuredClone(this.#cleanup);

package/dist/browser/CdpCaptureStorageFingerprints.js

@@ -19,13 +19,16 @@ export const captureStorageFingerprints = async ({ context, origin, local, sessi
     await addIndexedDb(run, origin, indexedDbNames);
     await addCaches(run, caches);
     state.items.sort((left, right) => compareCodePoints(`${left.scope}:${left.identity_sha256}`, `${right.scope}:${right.identity_sha256}`));
-    return {
-        items: state.items,
-        complete: state.complete &&
-            !state.truncated &&
-            state.items.every(({ complete }) => complete),
-        truncated: state.truncated,
-    };
+    const complete = state.complete &&
+        !state.truncated &&
+        state.items.every(({ complete }) => complete);
+    return complete
+        ? { items: state.items, complete: true, truncated: false }
+        : {
+            items: state.items,
+            complete: false,
+            truncated: state.truncated,
+        };
 };
 const addStorageItems = (state, scope, items) => {
     for (const item of items)

package/dist/browser/CdpElectronInspection.js

@@ -44,7 +44,9 @@ export const inspectCdpElectronPage = async (context) => {
 };
 const runElectronInspection = async (context, state, startedAt) => {
     const frames = await authorizeInitialFrames(context, state);
-    const main = frames[0];
+    const main = frames.at(0);
+    if (main === undefined)
+        throw new BrowserObservationError("inspect_web_page", "target_not_allowed");
     state.mainFrameId = main.frame_id;
     await enableElectronCapture(context);
     await delayWithCancellation(context.input.observation_ms, "inspect_electron_page", context.signal);

package/dist/browser/JavaScriptRuntimeScope.js

@@ -36,3 +36,8 @@ export const authorizeRuntimeLocation = async (value, roots, origins) => {
         },
     };
 };
+/** Authorize a target whose Node Inspector URL omits its main entry path. */
+export const authorizeRuntimeTargetLocation = async (value, targetType, roots, origins) => 
+// A bare file:// URL contains no source identity. Do not attach to the
+// first configured root merely because the target happens to be Node.
+authorizeRuntimeLocation(value, roots, origins);

package/dist/browser/PlaywrightElectronActiveActions.js

@@ -0,0 +1,324 @@
+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().max(256).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().max(128).nullable(),
+    phase: z.enum(["attempted", "completed", "blocked", "failed", "observed"]),
+    channel: z.string().max(1_024).nullable(),
+    channel_truncated: z.boolean().default(false),
+    direction: z
+        .enum([
+        "renderer-to-main",
+        "main-to-renderer",
+        "main-to-utility",
+        "utility-to-main",
+    ])
+        .nullable(),
+    sender: z.string().max(256).nullable(),
+    receiver: z.string().max(256).nullable(),
+    frame: z.string().max(256).nullable(),
+    target: z.string().max(256).nullable(),
+    argument_shapes: z.array(z.string().max(64)).max(32),
+    argument_shapes_truncated: z.boolean().default(false),
+    result_shape: z.string().max(64).nullable(),
+    process_type: z.string().max(128).nullable(),
+    source: z.string().max(64),
+    capture_method: z.enum(["api-wrapper", "event-emitter", "process-hook"]),
+    artifact_path: z.string().max(16_384).nullable(),
+    artifact_sha256: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .nullable(),
+    error: z.boolean(),
+});
+const hookSnapshotSchema = z.strictObject({
+    events: z.array(hookEventSchema).max(20_000),
+    observed: z.number().int().min(0),
+    observed_ipc: z.number().int().min(0),
+    observed_runtime: z.number().int().min(0),
+    truncated: z.boolean(),
+    hook_error: z.boolean(),
+});
+const metricSchema = z.strictObject({
+    pid: z.number().int().min(1),
+    type: z.string().min(1).max(128),
+    name: z.string().max(256).nullable(),
+    service_name: z.string().max(256).nullable(),
+});
+const windowMetadataSchema = z.strictObject({
+    window_id: z.string().max(256),
+    web_contents_id: z.string().max(256),
+    visible: z.boolean().nullable(),
+    destroyed: z.boolean(),
+});
+/** Run bounded, explicit actions against provider-owned Electron windows. */
+export const runElectronActions = async (application, input, options, deadline) => {
+    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 {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                throw new BrowserObservationError(OPERATION, "timeout");
+            selectedWindow =
+                windowIndex === null
+                    ? undefined
+                    : await waitForWindow({
+                        application,
+                        windowIndex,
+                        timeout: input.limits.action_timeout_ms,
+                        signal: options.signal,
+                        deadline,
+                    });
+            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,
+                remaining,
+                actionTimeoutMs: input.limits.action_timeout_ms,
+                options,
+                deadline,
+            });
+            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, remaining, actionTimeoutMs, options, deadline, }) => {
+    switch (action.kind) {
+        case "click":
+            if (selectedWindow === undefined)
+                throw new BrowserObservationError(OPERATION, "window_not_found");
+            await runWithExecutionLimits(selectedWindow.locator(action.selector).click({
+                timeout: Math.min(actionTimeoutMs, remaining),
+            }), options.signal, deadline);
+            return;
+        case "wait": {
+            const page = selectedWindow ??
+                (await application.firstWindow({
+                    timeout: Math.min(actionTimeoutMs, remaining),
+                }));
+            await runWithExecutionLimits(page.waitForTimeout(Math.min(action.duration_ms, remaining)), options.signal, deadline);
+            if (action.duration_ms > remaining)
+                throw new BrowserObservationError(OPERATION, "timeout");
+            return;
+        }
+        case "renderer-reload":
+            if (selectedWindow === undefined)
+                throw new BrowserObservationError(OPERATION, "window_not_found");
+            await runWithExecutionLimits(selectedWindow.reload({
+                timeout: Math.min(actionTimeoutMs, remaining),
+            }), options.signal, deadline);
+            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, deadline);
+            if (!crashed)
+                throw new BrowserObservationError(OPERATION, "window_not_found");
+            return;
+        }
+        case "deep-link":
+            await runWithExecutionLimits(emitDeepLink(application, action), options.signal, deadline);
+            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, timeout, signal, deadline, }) => {
+    const stopAt = Math.min(deadline, Date.now() + timeout);
+    while (Date.now() < stopAt) {
+        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, stopAt);
+    }
+    throw new BrowserObservationError(OPERATION, "window_not_found");
+};
+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 bounded hook snapshot. */
+// oxlint-disable-next-line max-lines-per-function -- one state read must share one capture boundary.
+export const readApplicationState = async (application, maxWindows) => {
+    const pages = application.windows();
+    const pageSnapshotsPromise = Promise.all(pages.slice(0, maxWindows).map(async (page, index) => ({
+        index,
+        url: page.url().slice(0, 65_536),
+        title: (await page.title()).slice(0, 16_384),
+    })));
+    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,
+                truncated: false,
+                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,
+            };
+        }),
+        windowsTruncated: pages.length > maxWindows,
+        metrics: processMetrics,
+        electronVersion,
+        hookSnapshot,
+    };
+};
+/** Apply a deadline and caller cancellation to one Playwright operation. */
+export const runWithExecutionLimits = async (operation, signal, deadline) => {
+    if (signal?.aborted === true)
+        throw new BrowserObservationError(OPERATION, "cancelled");
+    let timer;
+    let abortListener;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new BrowserObservationError(OPERATION, "timeout")), Math.max(1, deadline - Date.now()));
+    });
+    const cancellation = signal === undefined
+        ? timeout
+        : Promise.race([
+            timeout,
+            new Promise((_, reject) => {
+                abortListener = () => reject(new BrowserObservationError(OPERATION, "cancelled"));
+                signal.addEventListener("abort", abortListener, { once: true });
+            }),
+        ]);
+    try {
+        return await Promise.race([operation, cancellation]);
+    }
+    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).slice(0, 1_024);
+};