rea-agents 3.1.0 → 3.2.1

package/dist/hopper/HopperRequestQueue.js

@@ -1,38 +1,27 @@
-import { performance } from "node:perf_hooks";
-import { HopperCancelledError, HopperProcessError, HopperProtocolError, HopperTimeoutError, } from "../domain/errors.js";
+import { HopperCancelledError, HopperProcessError, HopperProtocolError, HopperRemoteError, } from "../domain/errors.js";
 import { err } from "../domain/result.js";
-/** Bounded FIFO that keeps the wire serialized until Hopper actually replies. */
+/** FIFO that keeps the wire serialized until Hopper actually replies. */
 export class HopperRequestQueue {
-    maximum;
     send;
     #queue = [];
     #active;
-    constructor(maximum, send) {
-        this.maximum = maximum;
+    constructor(send) {
         this.send = send;
     }
-    /** Queue one request, counting queue wait against its caller deadline. */
+    /** Queue one request until Hopper replies or the caller cancels it. */
     run(id, method, params, options) {
         if (options.signal?.aborted === true)
             return Promise.resolve(err(new HopperCancelledError()));
-        if (options.timeoutMs <= 0)
-            return Promise.resolve(err(new HopperTimeoutError(options.timeoutMs)));
-        if (this.#size() >= this.maximum)
-            return Promise.resolve(err(new HopperProtocolError(`Hopper serial request queue reached its ${String(this.maximum)}-request limit`)));
         return new Promise((resolve) => {
             let entry;
             const onAbort = options.signal === undefined ? undefined : () => this.#cancel(entry);
-            const timer = setTimeout(() => this.#timeout(entry), options.timeoutMs);
             entry = {
                 id,
                 method,
                 params,
                 signal: options.signal,
-                timeoutMs: options.timeoutMs,
-                deadline: performance.now() + options.timeoutMs,
                 progress: options.progress,
                 resolve,
-                timer,
                 onAbort,
                 callerState: "waiting",
                 callerSettled: false,
@@ -53,8 +42,16 @@ export class HopperRequestQueue {
         if (entry === undefined || entry.id !== id)
             return false;
         this.#releaseWire(entry);
-        if (!entry.callerSettled)
-            this.#settleCaller(entry, result, "waiting");
+        if (!entry.callerSettled) {
+            const contextual = !result.ok && result.error instanceof HopperRemoteError
+                ? err(new HopperRemoteError(result.error.code, result.error.safeMessage, {
+                    diagnosticType: result.error.diagnosticType,
+                    operation: entry.method,
+                    requestId: entry.id,
+                }))
+                : result;
+            this.#settleCaller(entry, contextual, "waiting");
+        }
         this.#active = undefined;
         this.#drain();
         return true;
@@ -88,10 +85,10 @@ export class HopperRequestQueue {
         if (active !== undefined) {
             this.#releaseWire(active);
             if (!active.callerSettled)
-                this.#settleCaller(active, err(error), "waiting");
+                this.#settleCaller(active, err(withRequestContext(error, active)), "waiting");
         }
         for (const entry of this.#queue.splice(0))
-            this.#settleCaller(entry, err(error), "waiting");
+            this.#settleCaller(entry, err(withRequestContext(error, entry)), "waiting");
     }
     /** Snapshot the one request still occupying Hopper's serial Python thread. */
     activity() {
@@ -102,7 +99,6 @@ export class HopperRequestQueue {
             requestId: active.id,
             operation: active.method,
             elapsedMs: Math.max(0, Math.round(performance.now() - active.startedAt)),
-            timeoutMs: active.timeoutMs,
             callerState: active.callerState,
             queuedRequests: this.#queue.length,
         };
@@ -124,11 +120,8 @@ export class HopperRequestQueue {
         const entry = this.#queue.shift();
         if (entry === undefined)
             return;
-        const remaining = entry.deadline - performance.now();
-        if (entry.signal?.aborted === true || remaining <= 0) {
-            this.#settleCaller(entry, entry.signal?.aborted === true
-                ? err(new HopperCancelledError())
-                : err(new HopperTimeoutError(entry.timeoutMs)), entry.signal?.aborted === true ? "cancelled" : "timed_out");
+        if (entry.signal?.aborted === true) {
+            this.#settleCaller(entry, err(new HopperCancelledError()), "cancelled");
             this.#drain();
             return;
         }
@@ -148,19 +141,6 @@ export class HopperRequestQueue {
             this.accept(entry.id, err(new HopperProtocolError("Hopper socket write failed", { cause })));
         }
     }
-    #timeout(entry) {
-        if (entry.callerSettled)
-            return;
-        if (this.#active === entry) {
-            this.#settleCaller(entry, err(new HopperTimeoutError(entry.timeoutMs)), "timed_out");
-            return;
-        }
-        const index = this.#queue.indexOf(entry);
-        if (index < 0)
-            return;
-        this.#queue.splice(index, 1);
-        this.#settleCaller(entry, err(new HopperTimeoutError(entry.timeoutMs)), "timed_out");
-    }
     #cancel(entry) {
         if (entry.callerSettled)
             return;
@@ -183,7 +163,6 @@ export class HopperRequestQueue {
             clearInterval(entry.heartbeat);
             entry.heartbeat = undefined;
         }
-        clearTimeout(entry.timer);
         if (entry.signal !== undefined && entry.onAbort !== undefined)
             entry.signal.removeEventListener("abort", entry.onAbort);
         entry.resolve(result);
@@ -192,7 +171,6 @@ export class HopperRequestQueue {
         if (entry.heartbeat !== undefined)
             clearInterval(entry.heartbeat);
         entry.heartbeat = undefined;
-        clearTimeout(entry.timer);
         if (entry.signal !== undefined && entry.onAbort !== undefined)
             entry.signal.removeEventListener("abort", entry.onAbort);
     }
@@ -213,3 +191,6 @@ export class HopperRequestQueue {
         }
     }
 }
+const withRequestContext = (error, entry) => error instanceof HopperProcessError
+    ? new HopperProcessError(error.exitCode, error.diagnostic, entry.method, entry.id)
+    : error;

package/dist/hopper/HopperResponseStream.js

@@ -1,6 +1,5 @@
 import { parseBridgeMessageLine, } from "./protocol.js";
-const MAX_LINE_BYTES = 10 * 1024 * 1024;
-/** Incrementally validates bounded Hopper NDJSON response frames. */
+/** Incrementally validates Hopper NDJSON response frames. */
 export class HopperResponseStream {
     options;
     #buffer = "";
@@ -13,17 +12,10 @@ export class HopperResponseStream {
         while (newline >= 0) {
             const line = this.#buffer.slice(0, newline).trim();
             this.#buffer = this.#buffer.slice(newline + 1);
-            if (Buffer.byteLength(line) > MAX_LINE_BYTES) {
-                this.options.abort("Hopper response exceeded the maximum line size");
-                return;
-            }
             if (line.length > 0 && !this.#acceptLine(line))
                 return;
             newline = this.#buffer.indexOf("\n");
         }
-        if (Buffer.byteLength(this.#buffer) > MAX_LINE_BYTES) {
-            this.options.abort("Hopper response exceeded the maximum line size");
-        }
     }
     reset() {
         this.#buffer = "";

package/dist/hopper/HopperSessionValues.js

@@ -11,13 +11,14 @@ export const parseHopperServerInfo = (value, expectedRunId) => {
         return ok({ name: value.name, version: value.version });
     return err(new HopperProtocolError("Hopper bridge health result is invalid"));
 };
-/** Require Hopper to confirm both analysis and document shutdown. */
+/** Require confirmation that the REA bridge detached or its document closed. */
 export const isHopperShutdownAcknowledgement = (value) => {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return false;
     if (value.shutdown !== true)
         return false;
-    return value.analysis_stopped === true && value.document_closed === true;
+    return ((value.analysis_stopped === true && value.document_closed === true) ||
+        (value.document_closed === false && value.document_retained === true));
 };
 /** Detect the verified Linux bridge response that requires group cleanup. */
 export const isHopperCleanupRequired = (value) => typeof value === "object" &&

package/dist/hopper/HopperTargetLease.js

@@ -0,0 +1,119 @@
+import { createHash } from "node:crypto";
+import { chmod, lstat, mkdir, realpath, rm } from "node:fs/promises";
+import { createConnection, createServer, } from "node:net";
+import { join, resolve } from "node:path";
+const leaseDirectory = join("/tmp", `rea-hopper-${process.getuid?.() ?? 0}`);
+/** Keep two REA processes from opening duplicate Hopper documents for one target/profile. */
+export const acquireHopperTargetLease = async (input) => {
+    const directory = input.directory ?? leaseDirectory;
+    await ensureLeaseDirectory(directory);
+    const targetPath = await realpath(input.targetPath).catch(() => resolve(input.targetPath));
+    const key = createHash("sha256")
+        .update(JSON.stringify({
+        targetPath,
+        targetKind: input.targetKind,
+        loaderArgs: input.loaderArgs,
+    }))
+        .digest("hex")
+        .slice(0, 32);
+    const socketPath = join(directory, `${key}.sock`);
+    const owner = { runId: input.runId, processId: process.pid };
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const server = createServer((socket) => sendOwner(socket, owner));
+        const bound = await bind(server, socketPath);
+        if (bound) {
+            await chmod(socketPath, 0o600);
+            let released = false;
+            return {
+                acquired: true,
+                lease: {
+                    release: async () => {
+                        if (released)
+                            return;
+                        released = true;
+                        await closeServer(server);
+                        await rm(socketPath, { force: true });
+                    },
+                },
+            };
+        }
+        const existingOwner = await readOwner(socketPath);
+        if (existingOwner !== undefined)
+            return { acquired: false, owner: existingOwner };
+        await rm(socketPath, { force: true });
+    }
+    throw new Error("Could not acquire the Hopper target lease");
+};
+const ensureLeaseDirectory = async (directory) => {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const directoryStat = await lstat(directory);
+    if (directoryStat.isSymbolicLink() ||
+        directoryStat.isDirectory() === false ||
+        (process.getuid !== undefined && directoryStat.uid !== process.getuid()))
+        throw new Error("Hopper target lease directory is not private");
+    if ((directoryStat.mode & 0o077) !== 0)
+        await chmod(directory, 0o700);
+};
+const bind = (server, socketPath) => new Promise((resolveBind, reject) => {
+    const onError = (error) => {
+        server.removeListener("listening", onListening);
+        if (error.code === "EADDRINUSE")
+            resolveBind(false);
+        else
+            reject(error);
+    };
+    const onListening = () => {
+        server.removeListener("error", onError);
+        resolveBind(true);
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(socketPath);
+});
+const sendOwner = (socket, owner) => {
+    socket.end(`${JSON.stringify(owner)}\n`);
+};
+const readOwner = (socketPath) => new Promise((resolveOwner) => {
+    const socket = createConnection(socketPath);
+    let response = "";
+    const timer = setTimeout(() => {
+        socket.destroy();
+        resolveOwner(undefined);
+    }, 250);
+    const finish = (owner) => {
+        clearTimeout(timer);
+        socket.destroy();
+        resolveOwner(owner);
+    };
+    socket.on("data", (chunk) => {
+        response += chunk.toString("utf8");
+        const newline = response.indexOf("\n");
+        if (newline < 0)
+            return;
+        try {
+            const value = JSON.parse(response.slice(0, newline));
+            if (typeof value === "object" &&
+                value !== null &&
+                typeof Reflect.get(value, "runId") === "string" &&
+                typeof Reflect.get(value, "processId") === "number")
+                finish({
+                    runId: Reflect.get(value, "runId"),
+                    processId: Reflect.get(value, "processId"),
+                });
+            else
+                finish(undefined);
+        }
+        catch {
+            finish(undefined);
+        }
+    });
+    socket.on("error", () => finish(undefined));
+    socket.on("end", () => finish(undefined));
+});
+const closeServer = (server) => new Promise((resolveClose, reject) => {
+    if (!server.listening) {
+        resolveClose();
+        return;
+    }
+    server.close((error) => (error ? reject(error) : resolveClose()));
+});

package/dist/hopper/LinuxPrivateDisplayDiagnostic.js

@@ -1,17 +1,10 @@
 import { z } from "zod";
 import { isHopperStartupFailureCode, } from "../domain/hopperStartupFailure.js";
-export const LINUX_PRIVATE_DISPLAY_DIAGNOSTIC_PREFIX = "REA_X11_DIAGNOSTIC_V1=";
-const diagnosticSchema = z
-    .object({
-    schema_version: z.literal(1),
+export const LINUX_PRIVATE_DISPLAY_DIAGNOSTIC_PREFIX = "REA_X11_DIAGNOSTIC=";
+const diagnosticContextSchema = z.object({
     component: z.literal("hopper_private_display"),
     operation: z.enum(["probe", "launch"]),
-    status: z.enum(["ready", "error"]),
-    failure_code: z.string().max(64).nullable(),
-    reason: z
-        .string()
-        .regex(/^[a-z0-9_]+$/u)
-        .max(64),
+    reason: z.string().regex(/^[a-z0-9_]+$/u),
     socket_directory: z.literal("/tmp/.X11-unix"),
     socket_directory_mode: z
         .string()
@@ -28,16 +21,28 @@ const diagnosticSchema = z
     fallback_reason: z
         .string()
         .regex(/^[a-z0-9_]+$/u)
-        .max(64)
         .nullable(),
     xvfb_stderr_bytes: z.number().int().nonnegative().safe(),
-    xvfb_stderr_truncated: z.boolean(),
-})
-    .strict();
-/** Parse exactly one bounded, versioned helper diagnostic from stderr. */
-export const parseLinuxPrivateDisplayDiagnostic = (stderr, truncated) => {
-    if (truncated)
-        return { ok: false, reason: "diagnostic_truncated" };
+});
+const failureCodeSchema = z.string().transform((value, context) => {
+    if (isHopperStartupFailureCode(value))
+        return value;
+    context.addIssue({
+        code: "custom",
+        message: "Unknown startup failure code",
+    });
+    return z.NEVER;
+});
+const diagnosticSchema = z.discriminatedUnion("status", [
+    diagnosticContextSchema
+        .extend({ status: z.literal("ready"), failure_code: z.null() })
+        .strict(),
+    diagnosticContextSchema
+        .extend({ status: z.literal("error"), failure_code: failureCodeSchema })
+        .strict(),
+]);
+/** Parse exactly one helper diagnostic from stderr. */
+export const parseLinuxPrivateDisplayDiagnostic = (stderr) => {
     const records = stderr
         .split("\n")
         .filter((line) => line.startsWith(LINUX_PRIVATE_DISPLAY_DIAGNOSTIC_PREFIX));
@@ -52,19 +57,7 @@ export const parseLinuxPrivateDisplayDiagnostic = (stderr, truncated) => {
         const parsed = diagnosticSchema.safeParse(JSON.parse(record.slice(LINUX_PRIVATE_DISPLAY_DIAGNOSTIC_PREFIX.length)));
         if (!parsed.success)
             return { ok: false, reason: "diagnostic_malformed" };
-        const code = parsed.data.failure_code;
-        if (code !== null && !isHopperStartupFailureCode(code))
-            return { ok: false, reason: "diagnostic_malformed" };
-        if ((parsed.data.status === "ready" && code !== null) ||
-            (parsed.data.status === "error" && code === null))
-            return { ok: false, reason: "diagnostic_malformed" };
-        return {
-            ok: true,
-            value: {
-                ...parsed.data,
-                failure_code: code,
-            },
-        };
+        return { ok: true, value: parsed.data };
     }
     catch {
         return { ok: false, reason: "diagnostic_malformed" };

package/dist/hopper/LinuxPrivateDisplayProbe.js

@@ -6,7 +6,6 @@ import { parseLinuxPrivateDisplayDiagnostic } from "./LinuxPrivateDisplayDiagnos
 const PYTHON_PATH = "/usr/bin/python3";
 const UNSHARE_PATH = "/usr/bin/unshare";
 const DEFAULT_PROBE_TIMEOUT_MS = 5_000;
-const PROBE_OUTPUT_LIMIT_BYTES = 64 * 1024;
 /** Probe the exact Xvfb boundary and select the least-privileged viable strategy. */
 export const selectLinuxPrivateDisplayStrategy = async (options) => {
     const timeoutMs = options.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
@@ -26,7 +25,6 @@ export const selectLinuxPrivateDisplayStrategy = async (options) => {
             effective_socket_directory_mode: isolated.diagnostic.effective_socket_directory_mode,
             effective_mount_read_only: isolated.diagnostic.effective_mount_read_only,
             xvfb_stderr_bytes: isolated.diagnostic.xvfb_stderr_bytes,
-            xvfb_stderr_truncated: isolated.diagnostic.xvfb_stderr_truncated,
         });
     return {
         ok: true,
@@ -39,7 +37,7 @@ export const selectLinuxPrivateDisplayStrategy = async (options) => {
         },
     };
 };
-/** Run one helper probe in an owned process group with a hard output bound. */
+/** Run one helper probe in an owned process group and retain its full diagnostics. */
 export const runLinuxPrivateDisplayProbe = async (strategy, options) => {
     if (options.signal?.aborted === true)
         return emptyProcessResult("cancelled");
@@ -61,9 +59,7 @@ export const runLinuxPrivateDisplayProbe = async (strategy, options) => {
         ownsProcessLifetime: true,
         cleanup: () => cleanupOwnedProcessGroup(started.ownership),
     };
-    const supervisor = new ProviderProcessSupervisor(launch, {
-        maxOutputBytesPerStream: PROBE_OUTPUT_LIMIT_BYTES,
-    });
+    const supervisor = new ProviderProcessSupervisor(launch);
     const outcome = await waitForProbeExit(supervisor, options.timeoutMs, options.signal);
     let cleanupIncomplete = false;
     if (outcome !== "exit") {
@@ -82,7 +78,6 @@ export const runLinuxPrivateDisplayProbe = async (strategy, options) => {
         exitCode: snapshot.exitCode,
         stderr: snapshot.stderr.text,
         stderrBytes: snapshot.stderr.bytes,
-        stderrTruncated: snapshot.stderr.truncated,
         cleanupIncomplete,
     };
 };
@@ -142,7 +137,7 @@ const evaluatedProbe = async (strategy, options, timeoutMs, runner) => {
             ok: false,
             diagnostic: syntheticDiagnostic(strategy, "cleanup_incomplete"),
         };
-    const parsed = parseLinuxPrivateDisplayDiagnostic(processResult.stderr, processResult.stderrTruncated);
+    const parsed = parseLinuxPrivateDisplayDiagnostic(processResult.stderr);
     if (!parsed.ok)
         return {
             ok: false,
@@ -162,10 +157,8 @@ const evaluatedProbe = async (strategy, options, timeoutMs, runner) => {
 };
 const exitMatchesDiagnostic = (exitCode, diagnostic) => diagnostic.status === "ready"
     ? exitCode === 0
-    : diagnostic.failure_code !== null &&
-        hopperStartupExitCode(diagnostic.failure_code) === exitCode;
+    : hopperStartupExitCode(diagnostic.failure_code) === exitCode;
 const syntheticDiagnostic = (strategy, reason, failureCode = "private_display_unavailable") => ({
-    schema_version: 1,
     component: "hopper_private_display",
     operation: "probe",
     status: "error",
@@ -180,14 +173,11 @@ const syntheticDiagnostic = (strategy, reason, failureCode = "private_display_un
     strategy,
     fallback_reason: null,
     xvfb_stderr_bytes: 0,
-    xvfb_stderr_truncated: false,
 });
 const unavailable = (diagnostic) => ({
     ok: false,
     strategy: "unavailable",
-    exitCode: diagnostic.failure_code === null
-        ? 70
-        : (hopperStartupExitCode(diagnostic.failure_code) ?? 70),
+    exitCode: hopperStartupExitCode(diagnostic.failure_code) ?? 70,
     diagnostic: { ...diagnostic, strategy: "unavailable" },
 });
 const emptyProcessResult = (outcome) => ({
@@ -195,7 +185,6 @@ const emptyProcessResult = (outcome) => ({
     exitCode: undefined,
     stderr: "",
     stderrBytes: 0,
-    stderrTruncated: false,
     cleanupIncomplete: false,
 });
 const waitForProbeExit = async (supervisor, timeoutMs, signal) => {

package/dist/hopper/protocol.js

@@ -5,7 +5,7 @@ import { err, ok } from "../domain/result.js";
 const remoteErrorSchema = z
     .object({
     code: z.number().int(),
-    message: z.string().max(512),
+    message: z.string(),
     type: z
         .enum([
         "remote",
@@ -38,10 +38,10 @@ const eventSchema = z
         z
             .object({
             type: z.literal("progress"),
-            phase: z.string().min(1).max(64),
+            phase: z.string().min(1),
             completed: z.number().nonnegative().finite(),
             total: z.number().nonnegative().finite().nullable(),
-            message: z.string().min(1).max(512),
+            message: z.string().min(1),
             terminal: z.boolean().optional(),
         })
             .strict(),
@@ -82,5 +82,7 @@ export const parseBridgeMessageLine = (line) => {
 };
 /** Project a parsed response into its result or expected remote failure. */
 export const responseResult = (response) => "error" in response
-    ? err(new HopperRemoteError(response.error.code, response.error.message, response.error.type))
+    ? err(new HopperRemoteError(response.error.code, response.error.message, {
+        diagnosticType: response.error.type,
+    }))
     : ok(response.result);

package/dist/main/reload.js

@@ -33,9 +33,6 @@ export const registerConfigReload = (input) => {
                 return;
             }
             runtimeState.currentConfig = refreshed.value;
-            Object.assign(runtimeState.evidencePolicy, refreshed.value.evidenceFilePolicy);
-            Object.assign(runtimeState.snapshotPolicy, refreshed.value.analysisSnapshotFilePolicy);
-            runtimeState.investigationRoots.splice(0, runtimeState.investigationRoots.length, ...refreshed.value.investigationInputRoots);
         })
             .catch(() => {
             serverLogger.error(MCP_PERMISSION_RELOAD_FAILED);

package/dist/main/shutdown.js

@@ -8,7 +8,7 @@ export const createShutdown = (input) => {
             unregisterReload();
             unregisterShutdown();
             await handle.close();
-            await session.close();
+            await session.close({ retainProviderDocuments: true });
             permissionAuthority.clearSessionGrants();
         })();
         return shutdownPromise;

package/dist/main/state.js

@@ -1,12 +1,3 @@
 export const createRuntimeState = (config) => ({
     currentConfig: config,
-    evidencePolicy: {
-        ...config.evidenceFilePolicy,
-        roots: [...config.evidenceFilePolicy.roots],
-    },
-    snapshotPolicy: {
-        ...config.analysisSnapshotFilePolicy,
-        roots: [...config.analysisSnapshotFilePolicy.roots],
-    },
-    investigationRoots: [...config.investigationInputRoots],
 });

package/dist/main/transport.js

@@ -14,9 +14,6 @@ export const startMcpTransport = async (dependencies, session, serverContext) =>
         handle = dependencies.serve(() => (dependencies.createServer ?? createServer)(session, session, {
             logger: serverContext.logger,
             processPolicy: () => serverContext.runtimeState.currentConfig.processExecutionPolicy,
-            evidenceFilePolicy: serverContext.runtimeState.evidencePolicy,
-            investigationInputRoots: serverContext.runtimeState.investigationRoots,
-            analysisSnapshotFilePolicy: serverContext.runtimeState.snapshotPolicy,
             permissionAuthority: serverContext.permissionAuthority,
             ...optionalProviders,
             artifactIntegrityContinueEnabled: () => serverContext.runtimeState.currentConfig
@@ -41,8 +38,6 @@ export const startMcpTransport = async (dependencies, session, serverContext) =>
 };
 const runtimeAvailability = (state) => ({
     processCaptureEnabled: state.currentConfig.processExecutionPolicy.status === "enabled",
-    evidenceFileRoots: state.currentConfig.evidenceFilePolicy.roots.length,
-    investigationInputRoots: state.currentConfig.investigationInputRoots.length,
     browserObservationEnabled: state.currentConfig.browserObservationPolicy.status === "enabled",
     browserScenarioEnabled: state.currentConfig.browserScenarioPolicy.status === "enabled",
     electronObservationEnabled: state.currentConfig.electronObservationPolicy.status === "enabled",