rea-agents 6.3.0 → 6.5.0

package/dist/windows/WindowsNativeLoader.js

@@ -32,9 +32,12 @@ const inspectionSchema = z.strictObject({
     architecture: z.literal("x64"),
     filesystem: windowsFileIdentitySchema,
     privateDacl: z.literal(true),
+    privateBridgeDescriptorAccess: z.literal(true),
     atomicJobAssignment: z.literal(true),
     killOnOwnerClose: z.literal(true),
     protocolStdin: z.boolean().optional(),
+    /** Absent from artifacts built before owned Job Object commit limits. */
+    jobMemoryLimit: z.literal(true).optional(),
 });
 const bindingSchema = z.strictObject({
     call: z.custom((value) => typeof value === "function"),
@@ -44,44 +47,71 @@ export const loadWindowsNativeAuthority = (host) => {
     if (host.platform !== "win32" || host.architecture !== "x64")
         return {
             available: false,
+            failureStage: "host",
             reason: "REA Windows native controls require a Windows x64 host.",
         };
+    const nodeApiVersion = Number(host.nodeApiVersion);
+    if (!Number.isSafeInteger(nodeApiVersion) || nodeApiVersion < 8)
+        return {
+            available: false,
+            failureStage: "host",
+            reason: "REA Windows native controls require Node-API 8 or newer.",
+        };
     try {
         const manifest = windowsNativeManifestSchema.parse(host.readManifest());
         if (manifest.packageVersion !== host.packageVersion)
             throw new Error("Windows native artifact belongs to another REA version");
-        const nodeApiVersion = Number(host.nodeApiVersion);
-        if (!Number.isSafeInteger(nodeApiVersion) || nodeApiVersion < 8)
-            throw new Error("Windows native artifact requires Node-API 8 or newer");
         const artifact = host.readArtifact();
         if (createHash("sha256").update(artifact).digest("hex") !==
             manifest.artifactSha256)
             throw new Error("Windows native artifact SHA-256 does not match package metadata");
         assertWindowsX64Artifact(artifact);
         const binding = bindingSchema.parse(host.loadArtifact());
-        const inspection = inspectionSchema.parse(binding.call("inspect", []));
+        let observed;
+        try {
+            observed = binding.call("inspect", []);
+        }
+        catch (cause) {
+            return {
+                available: false,
+                failureStage: "self-test",
+                retryable: true,
+                reason: `REA Windows native self-test failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+            };
+        }
+        const parsed = inspectionSchema.safeParse(observed);
+        if (!parsed.success)
+            return {
+                available: false,
+                failureStage: "inspection",
+                reason: `REA Windows native inspection is invalid: ${parsed.error.message}`,
+            };
+        const inspection = parsed.data;
         return { available: true, authority: { call: binding.call, inspection } };
     }
     catch (cause) {
         return {
             available: false,
+            failureStage: "artifact",
             reason: `REA Windows native controls are unavailable: ${cause instanceof Error ? cause.message : String(cause)}`,
         };
     }
 };
 const assertWindowsX64Artifact = (bytes) => {
-    if (bytes.length < 64 || bytes.toString("ascii", 0, 2) !== "MZ")
+    if (bytes.length < 64 || bytes.toString("latin1", 0, 2) !== "MZ")
         throw new Error("Windows native artifact is not a PE image");
     const offset = bytes.readUInt32LE(0x3c);
     if (offset > bytes.length - 26 ||
-        bytes.toString("ascii", offset, offset + 4) !== "PE\0\0" ||
+        bytes.toString("latin1", offset, offset + 4) !== "PE\0\0" ||
         bytes.readUInt16LE(offset + 4) !== 0x8664 ||
         bytes.readUInt16LE(offset + 24) !== 0x20b)
         throw new Error("Windows native artifact is not a Windows x64 PE32+ image");
 };
 let cached;
-/** Load only the package-owned artifact, lazily and once per process. */
+/** Cache stable admission; let a later query retry failed owned inspection. */
 export const systemWindowsNativeAuthority = () => {
+    if (cached?.available === false && cached.retryable === true)
+        cached = undefined;
     cached ??= loadWindowsNativeAuthority({
         platform: process.platform,
         architecture: process.arch,

package/dist/windows/WindowsOwnedProcess.js

@@ -16,6 +16,16 @@ const pollSchema = z.strictObject({
     exitCode: z.number().int().nonnegative().max(0xffff_ffff).nullable(),
     activeProcesses: z.number().int().nonnegative(),
 });
+// A commit-limited job reports its applied limit at launch and its
+// notification state on every poll; an unlimited job reports neither.
+const limitedPollSchema = pollSchema.extend({
+    memoryLimitReached: z.boolean(),
+    peakJobMemoryBytes: z
+        .number()
+        .int()
+        .nonnegative()
+        .max(Number.MAX_SAFE_INTEGER),
+});
 /** Encode one ordinary Windows argv token using the CRT backslash rules. */
 export const quoteWindowsProcessArgument = (value) => {
     if (value.includes("\0"))
@@ -37,12 +47,26 @@ export class WindowsOwnedProcess extends EventEmitter {
     #closed = false;
     #failure;
     #timer;
+    #blockedWake;
+    #blockedOutput = new Set();
+    #unreferenced = false;
     #cleanup;
-    constructor(command, arguments_, cwd, environment, verbatim, protocolStdin = false) {
+    #memoryLimitBytes;
+    #memoryLimitReached = false;
+    #peakJobMemoryBytes;
+    #outputIncomplete = false;
+    constructor(command, arguments_, cwd, environment, verbatim, options = {}) {
         super();
-        this.#authority = requireWindowsNativeAuthority();
+        const protocolStdin = options.protocolStdin === true;
+        this.#memoryLimitBytes = options.memoryLimitBytes;
+        this.#authority = options.authority ?? requireWindowsNativeAuthority();
         if (protocolStdin && this.#authority.inspection.protocolStdin !== true)
             throw new Error("The bundled Windows native artifact does not support owned protocol stdin; use a matching current Windows x64 REA package.");
+        // A requested limit is never dropped: an artifact without the control
+        // refuses the launch instead of starting an unlimited process.
+        if (this.#memoryLimitBytes !== undefined &&
+            this.#authority.inspection.jobMemoryLimit !== true)
+            throw new Error("The bundled Windows native artifact does not support Job Object memory limits; use a matching current Windows x64 REA package.");
         const entries = Object.entries(environment)
             .filter((entry) => entry[1] !== undefined)
             .map(([key, value]) => `${key}=${value}`);
@@ -52,13 +76,23 @@ export class WindowsOwnedProcess extends EventEmitter {
             quoteWindowsProcessArgument(command.replaceAll("/", "\\")),
             ...arguments_.map((value) => verbatim ? value : quoteWindowsProcessArgument(value)),
         ].join(" ");
-        const launched = launchSchema.parse(this.#authority.call("process_spawn", [
+        // Earlier artifacts accept only 4 or 5 arguments; keep that shape unless
+        // a commit limit is requested.
+        let controls = protocolStdin ? [true] : [];
+        if (this.#memoryLimitBytes !== undefined)
+            controls = [protocolStdin, this.#memoryLimitBytes];
+        const spawned = this.#authority.call("process_spawn", [
             command,
             line,
             cwd ?? "",
             entries,
-            ...(protocolStdin ? [true] : []),
-        ]));
+            ...controls,
+        ]);
+        const launched = this.#memoryLimitBytes === undefined
+            ? launchSchema.parse(spawned)
+            : launchSchema
+                .extend({ jobMemoryLimitBytes: z.literal(this.#memoryLimitBytes) })
+                .parse(spawned);
         this.pid = launched.pid;
         this.#handle = launched.handle;
         this.stdin = protocolStdin
@@ -92,6 +126,18 @@ export class WindowsOwnedProcess extends EventEmitter {
         });
         this.#schedule();
     }
+    /** Whether the job reported reaching its commit limit; sticky once observed. */
+    get memoryLimitReached() {
+        return this.#memoryLimitReached;
+    }
+    /** Latest observed peak job commit; undefined for an unlimited job. */
+    get peakJobMemoryBytes() {
+        return this.#peakJobMemoryBytes;
+    }
+    /** True when cleanup destroyed a backpressured stream before all output was observed. */
+    get outputIncomplete() {
+        return this.#outputIncomplete;
+    }
     async #writeInput(chunk) {
         const bytes = z.instanceof(Buffer).parse(chunk);
         const written = z
@@ -128,12 +174,25 @@ export class WindowsOwnedProcess extends EventEmitter {
         });
         return this.#cleanup;
     }
+    /** Release event-loop references so unsettled jobs do not prevent host exit. */
+    unref() {
+        this.#unreferenced = true;
+        this.#timer?.unref();
+        this.#blockedWake?.unref();
+    }
+    /** Restore event-loop references when retrying process lifecycle observation. */
+    ref() {
+        this.#unreferenced = false;
+        this.#timer?.ref();
+        this.#blockedWake?.ref();
+    }
     async #stop() {
         if (this.#closed)
             return { cleaned: true, signaled: false };
         let timer;
         try {
             const signaled = this.kill();
+            this.#discardBlockedOutput();
             this.#schedule();
             const settled = await Promise.race([
                 this.#settled.then(() => true),
@@ -160,22 +219,72 @@ export class WindowsOwnedProcess extends EventEmitter {
                 clearTimeout(timer);
         }
     }
-    #schedule() {
-        if (this.#closed || this.#timer !== undefined)
+    #schedule(delay = 25) {
+        if (this.#closed ||
+            this.#timer !== undefined ||
+            this.#blockedOutput.size > 0)
+            return;
+        this.#timer = setTimeout(() => this.#poll(), delay);
+        if (this.#unreferenced)
+            this.#timer.unref();
+    }
+    #scheduleBlockedWake() {
+        if (this.#closed ||
+            this.#blockedOutput.size === 0 ||
+            this.#blockedWake !== undefined)
             return;
-        this.#timer = setTimeout(() => this.#poll(), 25);
+        this.#blockedWake = setTimeout(() => {
+            this.#blockedWake = undefined;
+            this.#scheduleBlockedWake();
+        }, 1_000);
+        if (this.#unreferenced)
+            this.#blockedWake.unref();
+    }
+    #clearBlockedWake() {
+        if (this.#blockedWake !== undefined)
+            clearTimeout(this.#blockedWake);
+        this.#blockedWake = undefined;
+    }
+    #unblockOutput(stream) {
+        if (stream.destroyed)
+            this.#outputIncomplete = true;
+        this.#blockedOutput.delete(stream);
+        if (this.#blockedOutput.size === 0)
+            this.#clearBlockedWake();
+        this.#schedule(0);
+    }
+    #discardBlockedOutput() {
+        if (this.#blockedOutput.size > 0)
+            this.#outputIncomplete = true;
+        for (const stream of this.#blockedOutput)
+            stream.destroy();
+        this.#blockedOutput.clear();
+        this.#clearBlockedWake();
     }
     #poll() {
         this.#timer = undefined;
         if (this.#closed)
             return;
         try {
-            const state = pollSchema.parse(this.#authority.call("process_poll", [this.#handle]));
+            const observed = this.#authority.call("process_poll", [
+                this.#handle,
+            ]);
+            let state;
+            if (this.#memoryLimitBytes === undefined)
+                state = pollSchema.parse(observed);
+            else {
+                const limited = limitedPollSchema.parse(observed);
+                // Recorded before exit is emitted, so exit listeners observe it.
+                this.#memoryLimitReached ||= limited.memoryLimitReached;
+                this.#peakJobMemoryBytes = limited.peakJobMemoryBytes;
+                state = limited;
+            }
             this.#failure = undefined;
-            if (state.stdout.length > 0)
-                this.stdout.write(state.stdout);
-            if (state.stderr.length > 0)
-                this.stderr.write(state.stderr);
+            // Stop native reads while either consumer is backpressured. A slower
+            // cadence still accumulates unbounded unread output in the parent heap.
+            const idle = state.stdout.length === 0 && state.stderr.length === 0;
+            this.#writeOutput(this.stdout, state.stdout);
+            this.#writeOutput(this.stderr, state.stderr);
             if (state.exitCode !== null && this.exitCode === null) {
                 this.exitCode = state.exitCode;
                 this.emit("exit", state.exitCode, null);
@@ -187,7 +296,7 @@ export class WindowsOwnedProcess extends EventEmitter {
                 this.#release();
             }
             else
-                this.#schedule();
+                this.#schedule(idle ? 25 : 0);
         }
         catch (cause) {
             const failure = cause instanceof Error ? cause : new Error(String(cause));
@@ -199,16 +308,40 @@ export class WindowsOwnedProcess extends EventEmitter {
             // Retain the original job so explicit cleanup can retry its observation.
         }
     }
+    #writeOutput(stream, bytes) {
+        if (bytes.length === 0 || stream.writableEnded)
+            return;
+        if (stream.destroyed) {
+            this.#outputIncomplete = true;
+            return;
+        }
+        if (stream.write(bytes))
+            return;
+        this.#blockedOutput.add(stream);
+        const unblock = () => {
+            stream.off("drain", unblock);
+            stream.off("close", unblock);
+            this.#unblockOutput(stream);
+        };
+        stream.once("drain", unblock);
+        stream.once("close", unblock);
+        this.#scheduleBlockedWake();
+    }
     #release() {
         if (this.#closed)
             return;
         if (this.#timer !== undefined)
             clearTimeout(this.#timer);
+        this.#clearBlockedWake();
+        this.stdin?.destroy();
+        if (!this.stdout.destroyed)
+            this.stdout.end();
+        if (!this.stderr.destroyed)
+            this.stderr.end();
+        // End local streams before releasing the native handle. If release fails,
+        // the retained job can be retried without leaving output streams open.
         this.#authority.call("process_close", [this.#handle]);
         this.#closed = true;
-        this.stdin?.destroy();
-        this.stdout.end();
-        this.stderr.end();
         this.#settle?.();
         this.emit("close", this.exitCode, null);
     }

package/dist/windows/WindowsPrivateRuntime.js

@@ -1,5 +1,6 @@
 import { win32 } from "node:path";
 import { z } from "zod";
+import { PrivateRuntimeRootUnavailableError } from "../process/PrivateRuntimeRootUnavailableError.js";
 import { requireWindowsNativeAuthority, windowsFileIdentitySchema, windowsHandleSchema, } from "./WindowsNativeLoader.js";
 const runtimeSchema = windowsFileIdentitySchema.extend({
     path: z.string(),
@@ -15,6 +16,13 @@ const fileSchema = windowsFileIdentitySchema.extend({
     handle: windowsHandleSchema,
 });
 const runtimes = new Map();
+// Retry only a proven pre-allocation sharing/lock conflict, never opaque text
+// or an operation that may already own an unpublished runtime directory.
+const transientRuntimeAdmissionSchema = z.object({
+    code: z.literal("ERR_REA_WINDOWS_NATIVE"),
+    win32Code: z.union([z.literal(32), z.literal(33)]),
+    runtimeAllocation: z.literal("not-started"),
+});
 /** Retain private DACL and path handles until native recursive cleanup settles. */
 export class WindowsPrivateRuntime {
     observation;
@@ -32,9 +40,22 @@ export class WindowsPrivateRuntime {
     /** Create a new directory with its private DACL installed at creation. */
     static create(parent, prefix) {
         const authority = requireWindowsNativeAuthority();
-        const observation = runtimeSchema.parse(authority.call("runtime_create", [parent, prefix]));
+        let observed;
+        try {
+            observed = authority.call("runtime_create", [parent, prefix]);
+        }
+        catch (cause) {
+            if (cause instanceof Error &&
+                transientRuntimeAdmissionSchema.safeParse(cause).success)
+                throw new PrivateRuntimeRootUnavailableError(cause.message, {
+                    cause,
+                    retryable: true,
+                });
+            throw cause;
+        }
+        const observation = runtimeSchema.parse(observed);
         const runtime = new WindowsPrivateRuntime(observation, authority);
-        runtimes.set(observation.path.toLowerCase(), runtime);
+        runtimes.set(windowsRuntimeIdentityKey(observation), runtime);
         return runtime;
     }
     /** Open a private child directory through retained, verified parent handles. */
@@ -119,13 +140,20 @@ export class WindowsPrivateRuntime {
         await this.#pending?.catch(() => undefined);
         this.authority.call("runtime_close", [this.observation.handle]);
         this.#closed = true;
-        runtimes.delete(this.observation.path.toLowerCase());
+        runtimes.delete(windowsRuntimeIdentityKey(this.observation));
     }
 }
-/** Select an already-owned runtime; an arbitrary pathname cannot grant authority. */
+/** File id returned by the OS. Path spelling is not part of the lease key. */
+const windowsRuntimeIdentityKey = (identity) => `${identity.volumeSerial}:${identity.fileId}`;
+/**
+ * Select an already-owned runtime. Only the observed `path` or `finalPath`
+ * matches, character for character. A case variant fails closed.
+ */
 export const windowsPrivateRuntime = (rootPath) => {
-    const runtime = runtimes.get(rootPath.toLowerCase());
-    if (runtime === undefined)
+    const matches = [...runtimes.values()].filter((runtime) => runtime.observation.finalPath === rootPath ||
+        runtime.observation.path === rootPath);
+    const runtime = matches[0];
+    if (matches.length !== 1 || runtime === undefined)
         throw new Error(`No native private runtime owns ${rootPath}`);
     return runtime;
 };