rea-agents 3.0.0 → 3.2.0

package/dist/hopper/HopperCleanup.js

@@ -10,9 +10,10 @@ export const cleanupHopperSession = async (input) => {
         resources: new Set(),
         cleanupResult: undefined,
         shutdownConfirmed: false,
-        ownedProcessStopped: false,
     };
-    await report(input.progress, 0, "requesting Hopper document shutdown");
+    await report(input.progress, 0, input.retainDocument
+        ? "detaching REA from the Hopper document"
+        : "requesting Hopper document shutdown");
     await requestShutdown(input, state);
     await report(input.progress, 0.35, "releasing Hopper bridge transport");
     input.releaseTransport(input.socket);
@@ -34,12 +35,13 @@ const requestShutdown = async (input, state) => {
         return;
     }
     const shutdown = await input
-        .request("shutdown")
+        .request(input.retainDocument || input.launch?.shutdownMode === "process-cleanup"
+        ? "shutdown"
+        : "shutdown_document")
         .catch(() => err(new HopperProcessError(null)));
     if (shutdown.ok &&
         isHopperCleanupRequired(shutdown.value) &&
-        input.launch?.shutdownByCleanup === true &&
-        input.launch.cleanup !== undefined) {
+        input.launch?.shutdownMode === "process-cleanup") {
         state.cleanupResult = await input.launch
             .cleanup()
             .catch(providerCleanupFailure);
@@ -82,7 +84,9 @@ const stopProcess = async (input, state) => {
     }
     input.logger.info(diagnostic, "Owned Hopper launcher shutdown completed");
     if (stopped.status !== "incomplete") {
-        state.ownedProcessStopped = stopped.status !== "not-owned";
+        if (input.launch?.shutdownMode === "process-cleanup" &&
+            stopped.status !== "not-owned")
+            state.shutdownConfirmed = true;
         return;
     }
     const processGroupId = supervisor.launch.ownership?.processGroupId;
@@ -95,8 +99,7 @@ const stopProcess = async (input, state) => {
 };
 const recordUnconfirmedDocument = (input, state) => {
     if ((input.socket === undefined && input.launch === undefined) ||
-        state.shutdownConfirmed ||
-        state.ownedProcessStopped)
+        state.shutdownConfirmed)
         return;
     state.resources.add("hopper-document");
     state.issues.push({
@@ -142,7 +145,6 @@ const activityDetails = (activity) => ({
     request_id: activity.requestId,
     operation: activity.operation,
     elapsed_ms: activity.elapsedMs,
-    timeout_ms: activity.timeoutMs,
     caller_state: activity.callerState,
     queued_requests: activity.queuedRequests,
 });

package/dist/hopper/HopperClient.js

@@ -17,7 +17,6 @@ import { HopperRequestQueue, } from "./HopperRequestQueue.js";
 import { HopperResponseStream } from "./HopperResponseStream.js";
 import { responseResult, } from "./protocol.js";
 const SHUTDOWN_TIMEOUT_MS = 30_000;
-const MAX_QUEUED_REQUESTS = 64;
 const SESSION_ROOT = process.platform === "darwin" ? "/tmp" : tmpdir();
 /** Safe launcher telemetry; stderr content is intentionally never exposed. */
 /**
@@ -60,10 +59,9 @@ export class HopperClient {
         this.#logger = options.logger ?? silentLogger;
         this.#options = {
             ...options,
-            requestTimeoutMs: options.requestTimeoutMs ?? 30_000,
             startupTimeoutMs: options.startupTimeoutMs ?? 120_000,
         };
-        this.#requests = new HopperRequestQueue(MAX_QUEUED_REQUESTS, ({ id, method, params }, failed) => {
+        this.#requests = new HopperRequestQueue(({ id, method, params }, failed) => {
             const socket = this.#socket;
             const token = this.#token;
             if (socket === undefined || socket.destroyed || token === undefined) {
@@ -255,6 +253,7 @@ export class HopperClient {
                 logger: this.#logger,
                 onDiagnostic: this.#options.onDiagnostic,
                 request: (method) => this.#request(method, {}, { timeoutMs: SHUTDOWN_TIMEOUT_MS }),
+                retainDocument: options.retainDocument === true,
                 releaseTransport: (socket) => {
                     this.#failAll(new HopperProcessError(null));
                     if (socket !== undefined)
@@ -304,18 +303,16 @@ export class HopperClient {
         return err(new HopperTimeoutError(this.#options.startupTimeoutMs));
     }
     async #request(method, params, options) {
+        const id = this.#nextId++;
         const socket = this.#socket;
         const token = this.#token;
         if (socket === undefined || socket.destroyed || token === undefined) {
-            return err(new HopperProcessError(null));
+            return err(new HopperProcessError(null, undefined, method, id));
         }
         if (options.signal?.aborted === true)
             return err(new HopperCancelledError());
-        const id = this.#nextId++;
         const startedAt = performance.now();
-        const timeoutMs = options.timeoutMs ?? this.#options.requestTimeoutMs;
         const result = await this.#requests.run(id, method, params, {
-            timeoutMs,
             ...(options.signal === undefined ? {} : { signal: options.signal }),
             ...(options.progress !== undefined ? { progress: options.progress } : {}),
         });
@@ -399,6 +396,6 @@ export class HopperClient {
     }
 }
 const isAborted = (signal) => signal?.aborted === true;
-const startupInterruption = (deadline) => deadline.cancelled
+const startupInterruption = (deadline) => deadline.interruption === "cancelled"
     ? new HopperCancelledError()
     : new HopperTimeoutError(deadline.timeoutMs);

package/dist/hopper/HopperProcessDiagnostic.js

@@ -1,8 +1,8 @@
 import { hopperStartupFailure, } from "../domain/errors.js";
 import { parseLinuxPrivateDisplayDiagnostic } from "./LinuxPrivateDisplayDiagnostic.js";
-/** Extract only a matching, versioned Linux adapter failure record. */
+/** Extract only a matching Linux adapter failure record. */
 export const hopperLauncherFailureDiagnostic = (event) => {
-    const parsed = parseLinuxPrivateDisplayDiagnostic(event.snapshot.stderr.text, event.snapshot.stderr.truncated);
+    const parsed = parseLinuxPrivateDisplayDiagnostic(event.snapshot.stderr.text);
     if (!parsed.ok)
         return undefined;
     const expected = hopperStartupFailure(event.code)?.code;

package/dist/hopper/HopperProvider.js

@@ -34,15 +34,8 @@ const CAPABILITIES = Object.freeze(HOPPER_PROVIDER_TOOL_CONTRACTS.map((contract)
     return Object.freeze({
         provider: IDENTITY,
         operation,
-        inputContractVersion: 1,
-        outputContractVersion: 1,
         available: true,
         reason: null,
-        pagination: isRecord(contract.inputSchema.properties) &&
-            "offset" in contract.inputSchema.properties
-            ? "offset"
-            : "none",
-        exhaustive: false,
         effects: Object.freeze({
             mutatesArtifact: MUTATING_OPERATIONS.has(contract.name),
             launchesProcess: true,
@@ -52,19 +45,11 @@ const CAPABILITIES = Object.freeze(HOPPER_PROVIDER_TOOL_CONTRACTS.map((contract)
             changesPermissions: false,
             requiresRoot: false,
         }),
-        limits: Object.freeze({
-            maxResults: null,
-            maxPayloadBytes: contract.name === "read_bytes" ? 4_096 : null,
-            timeoutMs: null,
-        }),
         limitations: Object.freeze([
             "Results depend on Hopper's completed static analysis.",
         ]),
     });
 }));
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 /** Concrete analysis provider backed by REA's private Hopper bridge. */
 export class HopperProvider {
     config;
@@ -129,20 +114,6 @@ export class HopperProvider {
                 reason: null,
                 diagnostics,
             };
-        if (!["mach-o", "elf", "pe"].includes(target.format))
-            return {
-                status: "unsupported",
-                code: "target_format_unsupported",
-                reason: `Hopper cannot open ${target.format} through this adapter.`,
-                diagnostics,
-            };
-        if (target.architecture === undefined)
-            return {
-                status: "unsupported",
-                code: "architecture_unsupported",
-                reason: "Hopper requires a supported concrete target architecture.",
-                diagnostics,
-            };
         return {
             status: "supported",
             code: null,
@@ -223,7 +194,6 @@ export class HopperProvider {
                                 requestId: activity.requestId,
                                 operation: activity.operation,
                                 elapsedMs: activity.elapsedMs,
-                                timeoutMs: activity.timeoutMs,
                                 callerState: activity.callerState,
                             },
                         queuedRequests: activity?.queuedRequests ?? 0,

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" };