rea-agents 4.1.0 → 6.0.0

package/dist/process/ProviderProcess.js

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { WindowsOwnedProcess } from "../windows/WindowsOwnedProcess.js";
+import { prepareProcessOwnershipInspection } from "./ProcessOwnershipObservation.js";
 const DEFAULT_TERMINATION_GRACE_MS = 250;
 const DEFAULT_KILL_GRACE_MS = 1_000;
 /**
@@ -9,6 +10,9 @@ const DEFAULT_KILL_GRACE_MS = 1_000;
  * selecting provider-specific command arguments or environment values.
  */
 export const spawnOwnedProviderProcess = async (options) => {
+    options.signal?.throwIfAborted();
+    await prepareProcessOwnershipInspection(options.signal);
+    options.signal?.throwIfAborted();
     const platform = options.platform ?? process.platform;
     const hostEnvironment = options.hostEnvironment ?? process.env;
     const environment = {
@@ -58,7 +62,7 @@ export const spawnOwnedProviderProcess = async (options) => {
 /**
  * Supervises only generic process resources; wire protocol remains adapter-owned.
  *
- * Output retention is bounded per stream while byte totals remain exact. Stop
+ * Output retention is complete per stream; adapters own resource budgets. Stop
  * first honors token-verified group cleanup when supplied, otherwise it uses a
  * bounded TERM-to-KILL escalation for a directly owned child.
  */
@@ -68,6 +72,11 @@ export class ProviderProcessSupervisor {
     #stdout = new ProcessOutputCapture();
     #stderr = new ProcessOutputCapture();
     #exit = deferred();
+    #outputClose = deferred();
+    #outputClosed = false;
+    #stdoutObservedBytes = 0;
+    #stderrObservedBytes = 0;
+    #diagnosticTruncated = false;
     #onStdout = (chunk) => {
         this.#capture("stdout", this.#stdout, chunk);
     };
@@ -79,6 +88,8 @@ export class ProviderProcessSupervisor {
     };
     #onClose = (code, signal) => {
         this.#recordExit(code, signal);
+        this.#outputClosed = true;
+        this.#outputClose.resolve(undefined);
     };
     #onError = (cause) => {
         this.#options.onDiagnostic?.({ type: "error", message: cause.message });
@@ -89,7 +100,8 @@ export class ProviderProcessSupervisor {
     constructor(launch, options = {}) {
         this.launch = launch;
         this.#options = options;
-        this.#attach(launch.process.stdout, "stdout");
+        if (options.captureStdout !== false)
+            this.#attach(launch.process.stdout, "stdout");
         this.#attach(launch.process.stderr, "stderr");
         launch.process.once("exit", this.#onExit);
         launch.process.once("close", this.#onClose);
@@ -97,32 +109,31 @@ export class ProviderProcessSupervisor {
         if (launch.process.exitCode !== null || launch.process.signalCode !== null)
             this.#recordExit(launch.process.exitCode, launch.process.signalCode);
     }
-    /** Latest complete output and exit observation. */
+    /** Latest retained output and exit observation, with explicit configured truncation. */
     snapshot() {
         return {
+            ...(this.#diagnosticTruncated ? { diagnosticTruncated: true } : {}),
             stdout: this.#stdout.snapshot(),
             stderr: this.#stderr.snapshot(),
             exitCode: this.#exitObservation?.code,
             signal: this.#exitObservation?.signal,
         };
     }
+    /** Begin a new observation on a retained process without retaining earlier output. */
+    resetOutput() {
+        this.#stdout.reset();
+        this.#stderr.reset();
+        this.#stdoutObservedBytes = 0;
+        this.#stderrObservedBytes = 0;
+        this.#diagnosticTruncated = false;
+    }
     /** 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);
-        }
+        return waitForProcessEvent(this.#exitObservation !== undefined, this.#exit.promise, timeoutMs);
+    }
+    /** Wait until the producer has closed its output streams; exit alone does not prove complete output. */
+    async waitForOutputClose(timeoutMs) {
+        return waitForProcessEvent(this.#outputClosed, this.#outputClose.promise, timeoutMs);
     }
     /** Stop an owned process once; concurrent callers share the same escalation. */
     stop(options = {}) {
@@ -210,12 +221,28 @@ export class ProviderProcessSupervisor {
     }
     #capture(stream, capture, chunk) {
         const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        capture.append(bytes);
+        if (stream === "stdout")
+            this.#stdoutObservedBytes += bytes.byteLength;
+        else
+            this.#stderrObservedBytes += bytes.byteLength;
+        const remaining = this.#options.maxDiagnosticBytes === undefined
+            ? bytes.byteLength
+            : Math.max(0, this.#options.maxDiagnosticBytes -
+                this.#stdout.bytes -
+                this.#stderr.bytes);
+        const retained = Math.min(bytes.byteLength, remaining);
+        if (retained < bytes.byteLength)
+            this.#diagnosticTruncated = true;
+        if (retained > 0)
+            capture.append(bytes.subarray(0, retained));
         this.#options.onDiagnostic?.({
             type: "output",
             stream,
             bytes: bytes.byteLength,
-            totalBytes: capture.bytes,
+            totalBytes: stream === "stdout"
+                ? this.#stdoutObservedBytes
+                : this.#stderrObservedBytes,
+            ...(retained < bytes.byteLength ? { truncated: true } : {}),
         });
     }
     #recordExit(code, signal) {
@@ -237,6 +264,10 @@ class ProcessOutputCapture {
     get bytes() {
         return this.#bytes;
     }
+    reset() {
+        this.#chunks.length = 0;
+        this.#bytes = 0;
+    }
     append(chunk) {
         this.#bytes += chunk.byteLength;
         this.#chunks.push(Buffer.from(chunk));
@@ -273,3 +304,20 @@ const waitForSpawn = (child) => new Promise((resolve, reject) => {
     child.once("spawn", onSpawn);
     child.once("error", onError);
 });
+const waitForProcessEvent = async (observed, event, timeoutMs) => {
+    if (observed)
+        return true;
+    let timer;
+    try {
+        return await Promise.race([
+            event.then(() => true),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(false), Math.max(0, timeoutMs));
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+};

package/dist/{application → process/capture}/FilesystemSnapshot.js

@@ -5,6 +5,14 @@ import { dirname, join, relative, resolve } from "node:path";
 const hasSameIdentity = (before, after, expected) => before.dev === after.dev &&
     before.ino === after.ino &&
     (expected === "directory" ? after.isDirectory() : after.isSymbolicLink());
+const hasSameFileState = (before, after) => before.dev === after.dev &&
+    before.ino === after.ino &&
+    before.isFile() &&
+    after.isFile() &&
+    before.mode === after.mode &&
+    before.size === after.size &&
+    before.mtimeMs === after.mtimeMs &&
+    before.ctimeMs === after.ctimeMs;
 const lstatIfPresent = async (path) => {
     try {
         return await lstat(path);
@@ -15,11 +23,17 @@ const lstatIfPresent = async (path) => {
         throw cause;
     }
 };
-const hashFile = async (path, maxBytes, signal) => {
-    const handle = await open(path, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
+/** Hash a file only when its opened descriptor still matches the captured path state. */
+export const hashFile = async (path, expected, maxBytes, signal) => {
+    signal?.throwIfAborted();
+    const handle = await open(path, fsConstants.O_RDONLY |
+        (fsConstants.O_NOFOLLOW ?? 0) |
+        (fsConstants.O_NONBLOCK ?? 0));
     try {
+        signal?.throwIfAborted();
         const stats = await handle.stat();
-        if (!stats.isFile() || stats.size > maxBytes)
+        signal?.throwIfAborted();
+        if (!hasSameFileState(expected, stats) || stats.size > maxBytes)
             return null;
         const hash = createHash("sha256");
         const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes));
@@ -33,7 +47,8 @@ const hashFile = async (path, maxBytes, signal) => {
             position += bytesRead;
         }
         const after = await handle.stat();
-        if (after.size !== stats.size || after.mtimeMs !== stats.mtimeMs)
+        signal?.throwIfAborted();
+        if (!hasSameFileState(stats, after))
             return null;
         return hash.digest("hex");
     }
@@ -76,7 +91,7 @@ export const snapshotRoots = async (scenario, signal) => {
         }
         if (stats.isFile()) {
             const sha256 = remainingBytes >= stats.size
-                ? await hashFile(path, remainingBytes, signal)
+                ? await hashFile(path, stats, remainingBytes, signal)
                 : null;
             remainingBytes -= sha256 === null ? 0 : stats.size;
             if (sha256 === null)

package/dist/{application → process/capture}/ProcessCaptureCapability.js

@@ -1,7 +1,8 @@
 import { tmpdir } from "node:os";
+import { prepareProcessOwnershipInspection } from "../ProcessOwnershipObservation.js";
 /** Explain why process capture cannot claim owned-process cleanup on a host. */
 export const processCaptureOwnershipUnavailableReason = (platform) => platform === "win32"
-    ? "Windows process-tree ownership and cleanup are unavailable; REA cannot verify that descendants have stopped."
+    ? "Windows PTY process capture is unavailable because this adapter does not yet verify descendant cleanup. Use Linux (including WSL for Linux commands) or macOS. Reinstalling the PTY backend does not enable native Windows capture."
     : undefined;
 /** Probe the native PTY seam and explain loader failures at their source. */
 export const processCaptureProbeFailureReason = (cause) => {
@@ -28,6 +29,20 @@ export const probeProcessCaptureCapability = async (options = {}) => {
             backend: "node-pty",
             reason: ownershipReason,
         };
+    if (platform === "darwin") {
+        try {
+            await (options.prepareOwnershipInspector ?? prepareProcessOwnershipInspection)();
+        }
+        catch (cause) {
+            return {
+                available: false,
+                backend: "node-pty",
+                reason: cause instanceof Error
+                    ? cause.message
+                    : "macOS process ownership inspection could not be prepared",
+            };
+        }
+    }
     try {
         const { spawn } = await (options.loadPty ?? (() => import("@lydell/node-pty")))();
         const terminal = spawn(platform === "win32" ? "cmd.exe" : "/bin/sh", platform === "win32" ? ["/c", "exit", "0"] : ["-c", "exit 0"], {

package/dist/{application → process/capture}/ProcessCaptureError.js

@@ -1,4 +1,4 @@
-import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { AnalysisError } from "../../domain/analysisErrorBase.js";
 /** Typed application failure produced by controlled process capture. */
 export class ProcessCaptureError extends AnalysisError {
     _tag = "ProcessCaptureError";
@@ -7,6 +7,9 @@ export class ProcessCaptureError extends AnalysisError {
     reason;
     cleanupIncomplete;
     cleanupResources;
+    executionFailure;
+    partialObservation;
+    cleanupReport;
     constructor(message, options) {
         super(message, options);
         this.userMessage = options?.userMessage;
@@ -16,8 +19,21 @@ export class ProcessCaptureError extends AnalysisError {
                 (options?.userCategory === "cancelled" ? "cancelled" : "capture_failed");
         this.cleanupIncomplete = this.reason === "cleanup_incomplete";
         this.cleanupResources = options?.cleanupResources ?? [];
+        this.executionFailure = options?.executionFailure;
+        this.partialObservation = options?.partialObservation;
+        this.cleanupReport = options?.cleanupReport;
     }
 }
+/** Return one non-recursive, domain-neutral summary of an execution failure. */
+export const describeProcessCaptureExecutionFailure = (failure) => {
+    if (failure instanceof Error)
+        return failure.message || failure.name;
+    if (typeof failure === "string")
+        return failure;
+    if (failure === undefined)
+        return undefined;
+    return "Process capture failed with a non-error rejection.";
+};
 /** Caller-visible cancellation without exposing capture implementation state. */
 export const processCaptureCancelled = () => new ProcessCaptureError("process capture was cancelled", {
     userCategory: "cancelled",