rea-agents 1.6.0 → 2.0.0

package/dist/hopper/HopperSocketConnection.js

@@ -0,0 +1,31 @@
+import { createConnection } from "node:net";
+import { HopperCancelledError, HopperStartError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+/** Open one abort-aware Hopper Unix-socket connection attempt. */
+export const connectHopperSocketOnce = (socketPath, signal) => new Promise((resolve) => {
+    const socket = createConnection(socketPath);
+    const detach = () => {
+        socket.off("connect", onConnect);
+        socket.off("error", onError);
+        signal.removeEventListener("abort", onAbort);
+    };
+    const onConnect = () => {
+        detach();
+        resolve(ok(socket));
+    };
+    const onError = (cause) => {
+        detach();
+        socket.destroy();
+        resolve(err(new HopperStartError({ cause })));
+    };
+    const onAbort = () => {
+        detach();
+        socket.destroy();
+        resolve(err(new HopperCancelledError()));
+    };
+    socket.once("connect", onConnect);
+    socket.once("error", onError);
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted)
+        onAbort();
+});

package/dist/main.js

@@ -89,6 +89,14 @@ export const run = async (dependencies = runtimeDependencies()) => {
         roots: [...config.value.analysisSnapshotFilePolicy.roots],
     };
     const runtimeInvestigationRoots = [...config.value.investigationInputRoots];
+    const runtimeJavascriptReplayPolicy = {
+        ...config.value.javascriptReplayPolicy,
+        roots: [...config.value.javascriptReplayPolicy.roots],
+    };
+    const runtimeManagedRuntimePolicy = {
+        ...config.value.managedRuntimePolicy,
+        roots: [...config.value.managedRuntimePolicy.roots],
+    };
     const liveServers = new Set();
     let handle;
     try {
@@ -103,6 +111,8 @@ export const run = async (dependencies = runtimeDependencies()) => {
                 browserObservation,
                 electronObservation,
                 artifactIntegrityContinueEnabled: () => currentConfig.artifactIntegrityContinueEnabled,
+                javascriptReplayPolicy: runtimeJavascriptReplayPolicy,
+                managedRuntimePolicy: runtimeManagedRuntimePolicy,
                 availabilityPolicy: () => ({
                     processCaptureEnabled: currentConfig.processExecutionPolicy.enabled,
                     evidenceFileRoots: currentConfig.evidenceFilePolicy.roots.length,
@@ -112,6 +122,8 @@ export const run = async (dependencies = runtimeDependencies()) => {
                     electronObservationEnabled: currentConfig.electronObservationEnabled &&
                         currentConfig.electronCdpEndpoints.length > 0 &&
                         currentConfig.electronFileRoots.length > 0,
+                    javascriptReplayEnabled: currentConfig.javascriptReplayPolicy.enabled,
+                    managedRuntimeEnabled: currentConfig.managedRuntimePolicy.enabled,
                 }),
             });
             liveServers.add(server);
@@ -162,6 +174,8 @@ export const run = async (dependencies = runtimeDependencies()) => {
             Object.assign(runtimeEvidencePolicy, refreshed.value.evidenceFilePolicy);
             Object.assign(runtimeSnapshotPolicy, refreshed.value.analysisSnapshotFilePolicy);
             runtimeInvestigationRoots.splice(0, runtimeInvestigationRoots.length, ...refreshed.value.investigationInputRoots);
+            Object.assign(runtimeJavascriptReplayPolicy, refreshed.value.javascriptReplayPolicy);
+            Object.assign(runtimeManagedRuntimePolicy, refreshed.value.managedRuntimePolicy);
             for (const server of liveServers)
                 server.sendToolListChanged();
         });

package/dist/native/NativeMacOSProvider.js

@@ -14,11 +14,13 @@ import { parseDemangledSymbols } from "./parsers/demangle.js";
 import { parseLipoArchitectures } from "./parsers/lipo.js";
 import { parsePlistJson } from "./parsers/plist.js";
 import { architectureLocations, inspectNativeMacho, } from "./NativeMachoInspection.js";
-const IDENTITY = Object.freeze({
+/** Public identity committed by macOS-native inspection observations. */
+export const NATIVE_MACOS_PROVIDER_IDENTITY = Object.freeze({
     id: "native-macos",
     name: "macOS native inspection utilities",
     version: null,
 });
+const IDENTITY = NATIVE_MACOS_PROVIDER_IDENTITY;
 const TIMEOUT_MS = 30_000;
 const OUTPUT_LIMIT = 4 * 1024 * 1024;
 /** Read-only semantic provider composed from Xcode command-line utilities. */

package/dist/process/PendingOperations.js

@@ -0,0 +1,59 @@
+/**
+ * Correlates event-driven provider replies with bounded waits.
+ *
+ * The registry owns every request timer and abort listener. Settling, timing
+ * out, cancelling, or failing an operation removes both before resolution, so
+ * late protocol replies can be ignored without retaining request resources.
+ */
+export class PendingOperations {
+    #pending = new Map();
+    /** Number of currently correlated operations. */
+    get size() {
+        return this.#pending.size;
+    }
+    /** Return whether an operation key is awaiting a protocol reply. */
+    has(key) {
+        return this.#pending.has(key);
+    }
+    /** Register one unique operation key and start its bounded wait. */
+    wait(key, options) {
+        if (this.#pending.has(key))
+            throw new Error("Pending operation key is already registered");
+        if (options.signal?.aborted === true)
+            return Promise.resolve(options.cancelledValue());
+        return new Promise((resolve) => {
+            const onAbort = options.signal === undefined
+                ? undefined
+                : () => this.#finish(key, options.cancelledValue());
+            const timer = setTimeout(() => this.#finish(key, options.timeoutValue()), options.timeoutMs);
+            this.#pending.set(key, {
+                resolve,
+                timer,
+                signal: options.signal,
+                onAbort,
+            });
+            if (onAbort !== undefined)
+                options.signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+    /** Settle one correlated reply; returns false for late or unknown keys. */
+    settle(key, value) {
+        return this.#finish(key, value);
+    }
+    /** Fail every active operation while releasing all timers and listeners. */
+    failAll(valueFor) {
+        for (const key of this.#pending.keys())
+            this.#finish(key, valueFor(key));
+    }
+    #finish(key, value) {
+        const pending = this.#pending.get(key);
+        if (pending === undefined)
+            return false;
+        this.#pending.delete(key);
+        clearTimeout(pending.timer);
+        if (pending.signal !== undefined && pending.onAbort !== undefined)
+            pending.signal.removeEventListener("abort", pending.onAbort);
+        pending.resolve(value);
+        return true;
+    }
+}

package/dist/process/PrivateRuntimeRoot.js

@@ -0,0 +1,33 @@
+import { chmod, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/**
+ * Owns one mode-0700 temporary runtime root and removes it idempotently.
+ *
+ * Protocol adapters decide what belongs inside the directory; this primitive
+ * only establishes a private filesystem boundary and deterministic cleanup.
+ */
+export class PrivateRuntimeRoot {
+    path;
+    #closePromise;
+    constructor(path) {
+        this.path = path;
+    }
+    /** Allocate a new private runtime root without performing protocol work. */
+    static async create(options = {}) {
+        const path = await mkdtemp(join(options.parent ?? tmpdir(), options.prefix ?? "rea-provider-"));
+        try {
+            await chmod(path, 0o700);
+            return new PrivateRuntimeRoot(path);
+        }
+        catch (cause) {
+            await rm(path, { recursive: true, force: true });
+            throw cause;
+        }
+    }
+    /** Remove the runtime root; concurrent and repeated callers share cleanup. */
+    close() {
+        this.#closePromise ??= rm(this.path, { recursive: true, force: true });
+        return this.#closePromise;
+    }
+}

package/dist/process/ProviderDeadline.js

@@ -0,0 +1,95 @@
+/** Wait for an interval while removing the supplied abort listener on settle. */
+export const waitForAbortableDelay = (milliseconds, signal) => {
+    if (signal?.aborted === true)
+        return Promise.resolve("aborted");
+    return new Promise((resolve) => {
+        const settle = (result) => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            resolve(result);
+        };
+        const onAbort = () => settle("aborted");
+        const timer = setTimeout(() => settle("elapsed"), Math.max(0, milliseconds));
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+};
+/**
+ * One absolute deadline shared by every phase of a provider startup handshake.
+ *
+ * The deadline owns its timer and the listener attached to an optional caller
+ * signal. Adapters must dispose it after startup succeeds or fails.
+ */
+export class ProviderStartupDeadline {
+    timeoutMs;
+    #controller = new AbortController();
+    #deadlineAt;
+    #externalSignal;
+    #onExternalAbort;
+    #timer;
+    #timedOut = false;
+    #cancelled = false;
+    constructor(timeoutMs, signal) {
+        this.timeoutMs = timeoutMs;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+            throw new RangeError("Provider startup timeout must be positive");
+        this.#deadlineAt = Date.now() + timeoutMs;
+        this.#externalSignal = signal;
+        this.#onExternalAbort = () => {
+            if (this.#controller.signal.aborted)
+                return;
+            if (Date.now() >= this.#deadlineAt) {
+                this.#timedOut = true;
+                this.#abort(new DOMException("Provider startup deadline elapsed", "TimeoutError"));
+                return;
+            }
+            this.#cancelled = true;
+            this.#abort(signal?.reason);
+        };
+        if (signal?.aborted === true) {
+            this.#onExternalAbort();
+            return;
+        }
+        signal?.addEventListener("abort", this.#onExternalAbort, { once: true });
+        this.#timer = setTimeout(() => {
+            if (this.#controller.signal.aborted)
+                return;
+            this.#timedOut = true;
+            this.#abort(new DOMException("Provider startup deadline elapsed", "TimeoutError"));
+        }, timeoutMs);
+    }
+    /** Composite signal aborted by either the caller or the absolute deadline. */
+    get signal() {
+        return this.#controller.signal;
+    }
+    /** True only when the external caller signal initiated cancellation. */
+    get cancelled() {
+        return this.#cancelled;
+    }
+    /** True when the absolute startup deadline has elapsed. */
+    get timedOut() {
+        return (this.#timedOut || (!this.#cancelled && Date.now() >= this.#deadlineAt));
+    }
+    /** Milliseconds still available to the next startup phase. */
+    remainingMs() {
+        return Math.max(0, this.#deadlineAt - Date.now());
+    }
+    /** Wait for at most one polling interval under the shared deadline signal. */
+    wait(milliseconds) {
+        return waitForAbortableDelay(Math.min(milliseconds, this.remainingMs()), this.signal);
+    }
+    /** Release the deadline timer and external abort listener. */
+    dispose() {
+        this.#clearTimer();
+        this.#externalSignal?.removeEventListener("abort", this.#onExternalAbort);
+    }
+    #abort(reason) {
+        this.#clearTimer();
+        this.#externalSignal?.removeEventListener("abort", this.#onExternalAbort);
+        this.#controller.abort(reason);
+    }
+    #clearTimer() {
+        if (this.#timer !== undefined)
+            clearTimeout(this.#timer);
+        this.#timer = undefined;
+    }
+}

package/dist/process/ProviderProcess.js

@@ -0,0 +1,275 @@
+import { spawn } from "node:child_process";
+const DEFAULT_OUTPUT_BYTES = 64 * 1024;
+const DEFAULT_TERMINATION_GRACE_MS = 250;
+const DEFAULT_KILL_GRACE_MS = 1_000;
+/**
+ * Spawn a provider in a dedicated POSIX process group with an ownership token.
+ *
+ * The caller remains responsible for persisting any ownership manifest and for
+ * selecting provider-specific command arguments or environment values.
+ */
+export const spawnOwnedProviderProcess = async (options) => {
+    const child = spawn(options.command, [...options.arguments], {
+        shell: false,
+        stdio: ["ignore", "pipe", "pipe"],
+        detached: process.platform !== "win32",
+        env: {
+            ...process.env,
+            ...options.env,
+            REA_PROCESS_RUN_ID: options.runId,
+        },
+        ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+    });
+    await waitForSpawn(child);
+    const pid = child.pid;
+    if (pid === undefined)
+        throw new Error("Provider launcher has no process ID");
+    const ownership = {
+        runId: options.runId,
+        leaderPid: pid,
+        processGroupId: pid,
+        expectedParentPid: process.pid,
+        ...(options.expectedCommand === null
+            ? {}
+            : { expectedCommand: options.expectedCommand ?? options.command }),
+    };
+    return { process: child, ownership };
+};
+/**
+ * Supervises only generic process resources; wire protocol remains adapter-owned.
+ *
+ * Output retention is bounded per stream while byte totals remain exact. Stop
+ * first honors token-verified group cleanup when supplied, otherwise it uses a
+ * bounded TERM-to-KILL escalation for a directly owned child.
+ */
+export class ProviderProcessSupervisor {
+    launch;
+    #options;
+    #stdout;
+    #stderr;
+    #exit = deferred();
+    #onStdout = (chunk) => {
+        this.#capture("stdout", this.#stdout, chunk);
+    };
+    #onStderr = (chunk) => {
+        this.#capture("stderr", this.#stderr, chunk);
+    };
+    #onExit = (code, signal) => {
+        this.#recordExit(code, signal);
+    };
+    #onClose = (code, signal) => {
+        this.#recordExit(code, signal);
+    };
+    #onError = (cause) => {
+        this.#options.onDiagnostic?.({ type: "error", message: cause.message });
+    };
+    #exitObservation;
+    #stopPromise;
+    #disposed = false;
+    constructor(launch, options = {}) {
+        this.launch = launch;
+        this.#options = options;
+        const limit = options.maxOutputBytesPerStream ?? DEFAULT_OUTPUT_BYTES;
+        if (!Number.isSafeInteger(limit) || limit <= 0)
+            throw new RangeError("Provider output limit must be a positive integer");
+        this.#stdout = new BoundedByteCapture(limit);
+        this.#stderr = new BoundedByteCapture(limit);
+        this.#attach(launch.process.stdout, "stdout");
+        this.#attach(launch.process.stderr, "stderr");
+        launch.process.once("exit", this.#onExit);
+        launch.process.once("close", this.#onClose);
+        launch.process.on("error", this.#onError);
+        if (launch.process.exitCode !== null || launch.process.signalCode !== null)
+            this.#recordExit(launch.process.exitCode, launch.process.signalCode);
+    }
+    /** Latest bounded output and exit observation. */
+    snapshot() {
+        return {
+            stdout: this.#stdout.snapshot(),
+            stderr: this.#stderr.snapshot(),
+            exitCode: this.#exitObservation?.code,
+            signal: this.#exitObservation?.signal,
+        };
+    }
+    /** Wait for process exit up to a caller-owned bounded interval. */
+    async waitForExit(timeoutMs) {
+        if (this.#exitObservation !== undefined)
+            return true;
+        let timer;
+        try {
+            return await Promise.race([
+                this.#exit.promise.then(() => true),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(false), Math.max(0, timeoutMs));
+                }),
+            ]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    /** Stop an owned process once; concurrent callers share the same escalation. */
+    stop(options = {}) {
+        this.#stopPromise ??= this.#stop(options);
+        return this.#stopPromise;
+    }
+    /** Detach capture and process listeners after an adapter releases ownership. */
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.launch.process.stdout?.off("data", this.#onStdout);
+        this.launch.process.stderr?.off("data", this.#onStderr);
+        this.launch.process.off("exit", this.#onExit);
+        this.launch.process.off("close", this.#onClose);
+        this.launch.process.off("error", this.#onError);
+    }
+    async #stop(options) {
+        try {
+            if (!this.launch.ownsProcessLifetime)
+                return { status: "not-owned" };
+            if (this.launch.cleanup !== undefined) {
+                const cleanup = await this.#ownedCleanup(options.cleanupResult);
+                if (!cleanup.cleaned)
+                    return { status: "incomplete", reason: cleanup.reason };
+                const graceMs = options.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+                if (await this.waitForExit(graceMs))
+                    return { status: "verified-cleanup" };
+                const retried = await this.launch.cleanup();
+                if (!retried.cleaned)
+                    return { status: "incomplete", reason: retried.reason };
+                if (await this.waitForExit(graceMs))
+                    return { status: "verified-cleanup" };
+                return {
+                    status: "incomplete",
+                    reason: "verified process-group cleanup did not stop the launcher",
+                };
+            }
+            if (this.#exitObservation !== undefined)
+                return { status: "already-exited" };
+            this.#signal("SIGTERM");
+            if (await this.waitForExit(options.terminationGraceMs ?? DEFAULT_TERMINATION_GRACE_MS))
+                return { status: "terminated" };
+            this.#signal("SIGKILL");
+            if (await this.waitForExit(options.killGraceMs ?? DEFAULT_KILL_GRACE_MS))
+                return { status: "killed" };
+            return {
+                status: "incomplete",
+                reason: "owned provider process did not exit after SIGKILL",
+            };
+        }
+        catch (cause) {
+            return {
+                status: "incomplete",
+                reason: cause instanceof Error
+                    ? cause.message
+                    : "owned provider process cleanup failed",
+            };
+        }
+        finally {
+            this.dispose();
+        }
+    }
+    #ownedCleanup(supplied) {
+        if (supplied !== undefined)
+            return Promise.resolve(supplied);
+        const cleanup = this.launch.cleanup;
+        return cleanup === undefined
+            ? Promise.resolve({
+                cleaned: false,
+                reason: "owned provider process has no cleanup capability",
+            })
+            : cleanup();
+    }
+    #signal(signal) {
+        if (this.#exitObservation !== undefined)
+            return;
+        this.launch.process.kill(signal);
+    }
+    #attach(stream, name) {
+        if (name === "stdout")
+            stream?.on("data", this.#onStdout);
+        else
+            stream?.on("data", this.#onStderr);
+    }
+    #capture(stream, capture, chunk) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        capture.append(bytes);
+        this.#options.onDiagnostic?.({
+            type: "output",
+            stream,
+            bytes: bytes.byteLength,
+            totalBytes: capture.bytes,
+            truncated: capture.truncated,
+        });
+    }
+    #recordExit(code, signal) {
+        if (this.#exitObservation !== undefined)
+            return;
+        this.#exitObservation = { code, signal };
+        this.#exit.resolve(this.#exitObservation);
+        this.#options.onDiagnostic?.({
+            type: "exit",
+            code,
+            signal,
+            snapshot: this.snapshot(),
+        });
+    }
+}
+class BoundedByteCapture {
+    limit;
+    #chunks = [];
+    #bytes = 0;
+    #retainedBytes = 0;
+    constructor(limit) {
+        this.limit = limit;
+    }
+    get bytes() {
+        return this.#bytes;
+    }
+    get truncated() {
+        return this.#bytes > this.#retainedBytes;
+    }
+    append(chunk) {
+        this.#bytes += chunk.byteLength;
+        const remaining = this.limit - this.#retainedBytes;
+        if (remaining <= 0)
+            return;
+        const retained = Buffer.from(chunk.subarray(0, remaining));
+        this.#chunks.push(retained);
+        this.#retainedBytes += retained.byteLength;
+    }
+    snapshot() {
+        return {
+            text: Buffer.concat(this.#chunks, this.#retainedBytes).toString("utf8"),
+            bytes: this.#bytes,
+            retainedBytes: this.#retainedBytes,
+            truncated: this.truncated,
+        };
+    }
+}
+const deferred = () => {
+    let resolver;
+    const promise = new Promise((resolve) => {
+        resolver = resolve;
+    });
+    return {
+        promise,
+        resolve: (value) => {
+            resolver?.(value);
+        },
+    };
+};
+const waitForSpawn = (child) => new Promise((resolve, reject) => {
+    const onSpawn = () => {
+        child.off("error", onError);
+        resolve();
+    };
+    const onError = (cause) => {
+        child.off("spawn", onSpawn);
+        reject(cause);
+    };
+    child.once("spawn", onSpawn);
+    child.once("error", onError);
+});