rea-agents 5.0.0 → 6.1.0

package/dist/process/DarwinProcessRunTokenReader.js

@@ -0,0 +1,293 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { safeParseJson } from "../domain/safeJson.js";
+import { execFileOutput } from "./ExecFileOutput.js";
+const responseSchema = z.strictObject({
+    results: z.array(z.discriminatedUnion("state", [
+        z.strictObject({
+            pid: z.number().int().positive(),
+            state: z.literal("readable"),
+            run_id: z.string().optional(),
+            reason: z.null().optional(),
+        }),
+        z.strictObject({
+            pid: z.number().int().positive(),
+            state: z.literal("unavailable"),
+            run_id: z.union([z.string(), z.null()]).optional(),
+            reason: z.string().min(1),
+        }),
+    ])),
+});
+const identityResponseSchema = z.strictObject({
+    results: z.array(z.discriminatedUnion("state", [
+        z.strictObject({
+            pid: z.number().int().positive(),
+            state: z.literal("readable"),
+            identity: z.string().min(1),
+            reason: z.null().optional(),
+        }),
+        z.strictObject({
+            pid: z.number().int().positive(),
+            state: z.literal("unavailable"),
+            identity: z.null().optional(),
+            reason: z.string().min(1),
+        }),
+    ])),
+});
+const sourceFiles = [
+    fileURLToPath(new URL("../../bridge/process/ProcessRunTokenReader.swift", import.meta.url)),
+    fileURLToPath(new URL("../../bridge/process/ProcessRunTokenReaderMain.swift", import.meta.url)),
+];
+/** The native Darwin process-ownership reader could not be prepared. */
+export class DarwinProcessOwnershipInspectionError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "DarwinProcessOwnershipInspectionError";
+    }
+}
+const abortReason = (signal) => {
+    if (signal.reason !== undefined)
+        return signal.reason;
+    const error = new Error("The operation was aborted");
+    error.name = "AbortError";
+    return error;
+};
+const isExpectedAbort = (cause, signal) => signal.aborted &&
+    (cause === signal.reason ||
+        (cause instanceof Error && cause.name === "AbortError"));
+const waitForCompilation = async (promise, signal) => {
+    if (signal === undefined)
+        return promise;
+    if (signal.aborted)
+        throw abortReason(signal);
+    return new Promise((resolve, reject) => {
+        let completed = false;
+        const finish = (callback) => {
+            if (completed)
+                return;
+            completed = true;
+            signal.removeEventListener("abort", onAbort);
+            callback();
+        };
+        const onAbort = () => finish(() => reject(abortReason(signal)));
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => finish(() => resolve(value)), (cause) => finish(() => reject(cause)));
+        if (signal.aborted)
+            onAbort();
+    });
+};
+/** Compile and retain the narrow Darwin sysctl reader for this REA process. */
+export const createDarwinProcessRunTokenReader = (options = {}) => {
+    let root;
+    let executable;
+    let compilation;
+    let closePromise;
+    let closed = false;
+    let exitCleanupInstalled = false;
+    const cleanupAtExit = () => {
+        if (root !== undefined)
+            rmSync(root, { recursive: true, force: true });
+    };
+    const cleanupRoot = async (target = root) => {
+        if (target === undefined)
+            return;
+        await rm(target, { recursive: true, force: true });
+        if (root !== target)
+            return;
+        root = undefined;
+        executable = undefined;
+        if (exitCleanupInstalled)
+            process.removeListener("exit", cleanupAtExit);
+        exitCleanupInstalled = false;
+    };
+    const runCompilation = async (signal) => {
+        let operationRoot;
+        try {
+            operationRoot = await mkdtemp(join(tmpdir(), "rea-process-token-"));
+            root = operationRoot;
+            process.once("exit", cleanupAtExit);
+            exitCleanupInstalled = true;
+            if (signal.aborted || closed)
+                throw abortReason(signal);
+            const output = join(operationRoot, "reader");
+            const compilerEnvironment = { ...process.env };
+            // Use Swift's reusable default cache for REA's internal helper compilation.
+            delete compilerEnvironment.CLANG_MODULE_CACHE_PATH;
+            try {
+                await execFileOutput(options.xcrun ?? "/usr/bin/xcrun", ["swiftc", ...sourceFiles, "-o", output], {
+                    timeout: 60_000,
+                    maxBuffer: 1024 * 1024,
+                    signal,
+                    env: compilerEnvironment,
+                });
+            }
+            catch (cause) {
+                if (isExpectedAbort(cause, signal))
+                    throw cause;
+                const code = cause instanceof Error && "code" in cause
+                    ? String(cause.code)
+                    : "unknown";
+                throw new DarwinProcessOwnershipInspectionError(code === "ENOENT"
+                    ? `macOS process ownership inspection requires the Apple Swift compiler via xcrun (compiler result: ${code})`
+                    : `macOS process ownership helper compilation failed via xcrun (compiler result: ${code}): ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+            }
+            if (signal.aborted || closed)
+                throw abortReason(signal);
+            executable = output;
+            return output;
+        }
+        catch (cause) {
+            const ownsRoot = operationRoot !== undefined && root === operationRoot;
+            if (operationRoot !== undefined) {
+                if (ownsRoot)
+                    await cleanupRoot(operationRoot);
+                else
+                    await rm(operationRoot, { recursive: true, force: true });
+            }
+            throw cause;
+        }
+    };
+    const beginCompilation = () => {
+        const controller = new AbortController();
+        const operation = {
+            controller,
+            promise: runCompilation(controller.signal).finally(() => {
+                operation.settled = true;
+                if (compilation === operation)
+                    compilation = undefined;
+            }),
+            waiters: 0,
+            aborting: false,
+            settled: false,
+        };
+        compilation = operation;
+        return operation;
+    };
+    const compile = async (signal) => {
+        if (closed)
+            throw new Error("Darwin process token reader is closed");
+        signal?.throwIfAborted();
+        while (true) {
+            if (closed)
+                throw new Error("Darwin process token reader is closed");
+            signal?.throwIfAborted();
+            if (executable !== undefined)
+                return executable;
+            if (compilation === undefined && root !== undefined) {
+                await cleanupRoot();
+                continue;
+            }
+            let operation = compilation;
+            if (operation?.aborting === true) {
+                try {
+                    await waitForCompilation(operation.promise, signal);
+                }
+                catch (cause) {
+                    if (signal !== undefined && isExpectedAbort(cause, signal))
+                        throw cause;
+                }
+                continue;
+            }
+            operation ??= beginCompilation();
+            operation.waiters += 1;
+            try {
+                return await waitForCompilation(operation.promise, signal);
+            }
+            finally {
+                operation.waiters -= 1;
+                if (operation.waiters === 0 &&
+                    !operation.settled &&
+                    !operation.aborting) {
+                    operation.aborting = true;
+                    operation.controller.abort();
+                    await operation.promise.catch(() => undefined);
+                }
+            }
+        }
+    };
+    const read = async (processes) => {
+        if (processes.length === 0)
+            return new Map();
+        const binary = await compile();
+        const pids = processes.map(({ pid }) => String(pid));
+        const { stdout } = await execFileOutput(binary, pids, { timeout: 15_000 });
+        const decoded = safeParseJson(stdout);
+        if (!decoded.ok)
+            throw new Error(`macOS process token helper returned invalid JSON: ${decoded.error}`, { cause: decoded.cause });
+        const parsed = responseSchema.safeParse(decoded.value);
+        if (!parsed.success)
+            throw new Error("macOS process token helper returned an invalid response", {
+                cause: parsed.error,
+            });
+        const requested = new Set(processes.map(({ pid }) => pid));
+        const observations = new Map();
+        for (const result of parsed.data.results) {
+            if (!requested.has(result.pid) || observations.has(result.pid))
+                throw new Error("macOS process token helper returned an unexpected PID set");
+            observations.set(result.pid, result.state === "readable"
+                ? { state: "readable", runId: result.run_id }
+                : {
+                    state: "unavailable",
+                    reason: result.reason ?? "process token observation is unavailable",
+                });
+        }
+        if (observations.size !== requested.size)
+            throw new Error("macOS process token helper returned an incomplete PID set");
+        return observations;
+    };
+    const identities = async (processes, signal) => {
+        if (processes.length === 0)
+            return new Map();
+        const binary = await compile(signal);
+        const pids = processes.map(({ pid }) => String(pid));
+        const { stdout } = await execFileOutput(binary, ["--identities", ...pids], {
+            timeout: 15_000,
+            ...(signal === undefined ? {} : { signal }),
+        });
+        const decoded = safeParseJson(stdout);
+        if (!decoded.ok)
+            throw new Error(`macOS process identity helper returned invalid JSON: ${decoded.error}`, { cause: decoded.cause });
+        const parsed = identityResponseSchema.safeParse(decoded.value);
+        if (!parsed.success)
+            throw new Error("macOS process identity helper returned an invalid response", {
+                cause: parsed.error,
+            });
+        const requested = new Set(processes.map(({ pid }) => pid));
+        const observations = new Map();
+        for (const result of parsed.data.results) {
+            if (!requested.has(result.pid) || observations.has(result.pid))
+                throw new Error("macOS process identity helper returned an unexpected PID set");
+            observations.set(result.pid, result.state === "readable"
+                ? { state: "readable", identity: result.identity }
+                : { state: "unavailable", reason: result.reason });
+        }
+        if (observations.size !== requested.size)
+            throw new Error("macOS process identity helper returned an incomplete PID set");
+        return observations;
+    };
+    const close = () => {
+        if (closePromise !== undefined)
+            return closePromise;
+        closed = true;
+        const pendingClose = (async () => {
+            const operation = compilation;
+            if (operation !== undefined && !operation.settled) {
+                operation.aborting = true;
+                operation.controller.abort();
+                await operation.promise.catch(() => undefined);
+            }
+            await cleanupRoot();
+        })().catch((cause) => {
+            if (closePromise === pendingClose)
+                closePromise = undefined;
+            throw cause;
+        });
+        closePromise = pendingClose;
+        return closePromise;
+    };
+    return { read, identities, prepare: compile, close };
+};

package/dist/process/ExecFileOutput.js

@@ -1,4 +1,24 @@
 import { execFile, } from "node:child_process";
+/** Read captured output metadata from a failed execFileOutput invocation. */
+export const execFileOutputFailure = (cause) => {
+    if (!(cause instanceof Error))
+        return undefined;
+    const stdout = Reflect.get(cause, "stdout");
+    const stderr = Reflect.get(cause, "stderr");
+    const code = Reflect.get(cause, "code");
+    const signal = Reflect.get(cause, "signal");
+    const killed = Reflect.get(cause, "killed");
+    if (typeof stdout !== "string" || typeof stderr !== "string")
+        return undefined;
+    return {
+        stdout,
+        stderr,
+        code: typeof code === "string" || typeof code === "number" ? code : null,
+        signal: typeof signal === "string" ? signal : null,
+        killed: killed === true,
+        outputTruncated: code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER",
+    };
+};
 /** Run a shell-free command while capturing its complete UTF-8 output. */
 export const execFileOutput = (command, arguments_, options = {}) => new Promise((resolve, reject) => {
     execFile(command, [...arguments_], {

package/dist/process/OwnedCommand.js

@@ -0,0 +1,118 @@
+import { ProviderProcessSupervisor, spawnOwnedProviderProcess, } from "./ProviderProcess.js";
+import { cleanupOwnedProcessGroup } from "./ProcessOwnership.js";
+import { ProviderStartupDeadline, waitForAbortableDelay, } from "./ProviderDeadline.js";
+/** A short-lived command failed its lifecycle or complete-output contract. */
+export class OwnedCommandFailure extends Error {
+    reason;
+    snapshot;
+    cleanupFailure;
+    resources;
+    constructor(reason, message, snapshot = null, cleanupFailure = null, options, resources = []) {
+        super(message, options);
+        this.reason = reason;
+        this.snapshot = snapshot;
+        this.cleanupFailure = cleanupFailure;
+        this.resources = resources;
+    }
+}
+/** Execute a single owned process with independent cleanup and bounded diagnostic retention. */
+export const runOwnedCommand = async (spawn, limits, options = {}) => {
+    const callerSignal = options.signal ?? spawn.signal;
+    if (callerSignal?.aborted)
+        throw new OwnedCommandFailure("cancelled", "Command cancelled before launch.");
+    const deadline = new ProviderStartupDeadline(limits.timeoutMs, callerSignal);
+    try {
+        return await collectOwnedCommand(spawn, limits, options.launcher ?? spawnOwnedProviderProcess, deadline, callerSignal);
+    }
+    finally {
+        deadline.dispose();
+    }
+};
+const collectOwnedCommand = async (spawn, limits, launcher, deadline, callerSignal) => {
+    const signal = deadline.signal;
+    let launched;
+    try {
+        launched = await launcher({
+            ...spawn,
+            signal,
+        });
+    }
+    catch (cause) {
+        const interruption = deadline.interruption;
+        if (interruption !== undefined)
+            throw new OwnedCommandFailure(interruption, interruption === "cancelled"
+                ? "Command cancelled during ownership preparation."
+                : "Command deadline elapsed during ownership preparation.", null, null, { cause });
+        throw cause;
+    }
+    let exceeded = false;
+    let processFailure;
+    const supervisor = new ProviderProcessSupervisor({
+        ...launched,
+        ownsProcessLifetime: true,
+        cleanup: launched.cleanup ??
+            (() => cleanupOwnedProcessGroup(launched.ownership)),
+    }, {
+        maxDiagnosticBytes: limits.diagnosticBytes,
+        onDiagnostic: (event) => {
+            if (event.type === "output" && event.truncated === true)
+                exceeded = true;
+            if (event.type === "error")
+                processFailure = event.message;
+        },
+    });
+    let failure;
+    try {
+        while (!(await supervisor.waitForOutputClose(10))) {
+            const interruption = deadline.interruption;
+            if (interruption !== undefined)
+                throw new OwnedCommandFailure(interruption, interruption === "cancelled"
+                    ? "Command cancelled."
+                    : "Command deadline elapsed.");
+            if (exceeded)
+                throw new OwnedCommandFailure("output-limit", "Command diagnostic output exceeded its complete-output budget.");
+            if (processFailure !== undefined)
+                throw new OwnedCommandFailure("process", processFailure);
+            await waitForAbortableDelay(25, signal);
+        }
+        const snapshot = supervisor.snapshot();
+        const interruption = deadline.interruption;
+        if (interruption !== undefined)
+            throw new OwnedCommandFailure(interruption, interruption === "cancelled"
+                ? "Command cancelled."
+                : "Command deadline elapsed.", snapshot);
+        if (exceeded)
+            throw new OwnedCommandFailure("output-limit", "Command diagnostic output exceeded its complete-output budget.", snapshot);
+        const acceptedNonzeroExit = limits.acceptNonZeroExit === true &&
+            snapshot.exitCode !== null &&
+            snapshot.exitCode !== undefined &&
+            snapshot.exitCode !== 0 &&
+            snapshot.signal === null;
+        if (processFailure !== undefined ||
+            ((snapshot.exitCode !== 0 || snapshot.signal !== null) &&
+                !acceptedNonzeroExit))
+            throw new OwnedCommandFailure("process", processFailure ??
+                "Command failed; inspect its exit status and diagnostics.", snapshot);
+    }
+    catch (cause) {
+        failure =
+            cause instanceof OwnedCommandFailure
+                ? cause
+                : new OwnedCommandFailure("process", "Command collection failed.", null, null, { cause });
+    }
+    const stopped = await supervisor.stop();
+    const snapshot = supervisor.snapshot();
+    supervisor.dispose();
+    if (stopped.status === "incomplete")
+        throw new OwnedCommandFailure(failure?.reason ?? "process", failure?.message ?? "Command cleanup failed.", snapshot, stopped.reason, failure === undefined ? undefined : { cause: failure }, [
+            spawn.runId,
+            ...(spawn.cwd === undefined ? [] : [spawn.cwd]),
+            `pid:${launched.ownership.leaderPid}`,
+            `process-group:${launched.ownership.processGroupId}`,
+        ]);
+    if (failure !== undefined)
+        throw new OwnedCommandFailure(failure.reason, failure.message, snapshot, failure.cleanupFailure, { cause: failure }, failure.resources);
+    if (callerSignal?.aborted)
+        throw new OwnedCommandFailure("cancelled", "Command cancelled.", snapshot);
+    return snapshot;
+};