rea-agents 5.0.0 → 6.1.0

package/dist/process/ProcessOwnershipObservation.js

@@ -1,7 +1,9 @@
 import { readFile } from "node:fs/promises";
+import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
 import { launcherIdentityFailure } from "./ProcessOwnershipIdentity.js";
 import { descendantsOf, liveProcesses } from "./ProcessOwnershipProcessTree.js";
 import { execFileOutput } from "./ExecFileOutput.js";
+import { createDarwinProcessRunTokenReader } from "./DarwinProcessRunTokenReader.js";
 /** Observe one group without signaling it, failing closed on identity doubt. */
 export const observeOwnedProcessGroupWithHost = async (ownership, host) => {
     let members;
@@ -105,46 +107,226 @@ export const parseProcessEnvironment = (value) => Object.fromEntries(value
     const separator = entry.indexOf("=");
     return [entry.slice(0, separator), entry.slice(separator + 1)];
 }));
+/** Read Linux stat field 22, tolerating spaces and closing parentheses in comm. */
+export const parseLinuxProcessStartTime = (value) => {
+    const commandEnd = value.lastIndexOf(")");
+    if (commandEnd < 0)
+        return undefined;
+    const fields = value
+        .slice(commandEnd + 1)
+        .trim()
+        .split(/\s+/u);
+    const startTime = fields[19];
+    return startTime !== undefined && /^\d+$/u.test(startTime)
+        ? startTime
+        : undefined;
+};
+const isExpectedAbort = (cause, signal) => signal?.aborted === true &&
+    (cause === signal.reason ||
+        (cause instanceof Error && cause.name === "AbortError"));
 /** Create the operating-system process inspector for an explicit host context. */
-export const createSystemProcessOwnershipHost = (platform = process.platform, hostEnvironment = process.env) => ({
-    platform,
-    async listProcesses() {
+export const createSystemProcessOwnershipHost = (platform = process.platform, hostEnvironment = process.env, options = {}) => {
+    const darwinTokens = platform === "darwin"
+        ? createDarwinProcessRunTokenReader(options.darwinXcrun === undefined
+            ? {}
+            : { xcrun: options.darwinXcrun })
+        : undefined;
+    const listProcesses = async (signal) => {
         if (platform === "win32")
             return [];
-        const { stdout } = await execFileOutput("ps", ["-axo", "pid=,ppid=,pgid=,stat=,command="], { env: hostEnvironment });
+        const { stdout } = await execFileOutput("ps", ["-axo", "pid=,ppid=,pgid=,uid=,stat=,command="], { env: hostEnvironment, ...(signal === undefined ? {} : { signal }) });
         return stdout
             .split("\n")
-            .map((line) => /\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(.*)/u.exec(line))
+            .map((line) => /\s*(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(.*)/u.exec(line))
             .filter((match) => match !== null)
             .map((match) => ({
             pid: Number(match[1]),
             parentPid: Number(match[2]),
             processGroupId: Number(match[3]),
-            state: match[4] ?? "",
-            command: match[5] ?? "",
+            uid: Number(match[4]),
+            state: match[5] ?? "",
+            command: match[6] ?? "",
         }));
-    },
-    async environment(pid) {
+    };
+    const processIdentities = async (processes, signal) => {
+        if (processes.length === 0)
+            return new Map();
         if (platform === "linux")
-            return parseProcessEnvironment(await readFile(`/proc/${pid}/environ`, "utf8"));
-        const { stdout } = await execFileOutput("ps", ["eww", "-p", String(pid)], {
-            env: hostEnvironment,
-        });
-        const observedEnvironment = {};
-        for (const match of stdout.matchAll(/(?:^|\s)([A-Za-z_][A-Za-z0-9_]*)=([^\s]*)/gu)) {
-            const name = match[1];
-            if (name !== undefined)
-                observedEnvironment[name] = match[2] ?? "";
+            return new Map(await Promise.all(processes.map(async ({ pid }) => {
+                try {
+                    const stat = await readFile(`/proc/${String(pid)}/stat`, {
+                        encoding: "utf8",
+                        ...(signal === undefined ? {} : { signal }),
+                    });
+                    const identity = parseLinuxProcessStartTime(stat);
+                    return [
+                        pid,
+                        identity === undefined
+                            ? {
+                                state: "unavailable",
+                                reason: "malformed_proc_stat",
+                            }
+                            : {
+                                state: "readable",
+                                identity: `linux-starttime:${identity}`,
+                            },
+                    ];
+                }
+                catch (cause) {
+                    if (isExpectedAbort(cause, signal))
+                        throw cause;
+                    return [
+                        pid,
+                        { state: "unavailable", reason: errorMessage(cause) },
+                    ];
+                }
+            })));
+        if (darwinTokens === undefined)
+            return new Map();
+        try {
+            return await darwinTokens.identities(processes, signal);
         }
-        return observedEnvironment;
-    },
-    signalGroup(processGroupId, signal) {
-        process.kill(-processGroupId, signal);
-    },
-});
-const systemHost = createSystemProcessOwnershipHost();
+        catch (cause) {
+            if (isExpectedAbort(cause, signal))
+                throw cause;
+            const reason = errorMessage(cause);
+            return new Map(processes.map(({ pid }) => [
+                pid,
+                { state: "unavailable", reason },
+            ]));
+        }
+    };
+    const captureBaseline = async (signal) => {
+        if (platform !== "linux" && darwinTokens === undefined)
+            return [];
+        const processes = liveProcesses(await listProcesses(signal));
+        let identities = await processIdentities(processes, signal);
+        const unreadable = processes.filter(({ pid }) => identities.get(pid)?.state !== "readable");
+        if (unreadable.length > 0) {
+            const stillLive = liveProcesses(await listProcesses(signal)).filter(({ pid }) => unreadable.some((entry) => entry.pid === pid));
+            const retried = await processIdentities(stillLive, signal);
+            identities = new Map([...identities, ...retried]);
+            const unresolved = stillLive.filter(({ pid }) => identities.get(pid)?.state !== "readable");
+            const liveAfterRetry = liveProcesses(await listProcesses(signal));
+            const stillUnresolved = unresolved.filter(({ pid }) => liveAfterRetry.some((entry) => entry.pid === pid));
+            if (stillUnresolved.length > 0)
+                throw new Error(`process identity snapshot is unavailable for ${String(stillUnresolved.length)} live processes`);
+        }
+        return processes.map(({ pid }) => {
+            const observation = identities.get(pid);
+            return {
+                pid,
+                identity: observation?.state === "readable" ? observation.identity : null,
+            };
+        });
+    };
+    return {
+        platform,
+        prepare: async (signal) => {
+            await darwinTokens?.prepare(signal);
+            if (platform === "linux") {
+                try {
+                    const processes = await listProcesses(signal);
+                    if (!processes.some(({ pid }) => pid === process.pid))
+                        throw new Error("ps did not report REA's current process");
+                }
+                catch (cause) {
+                    if (isExpectedAbort(cause, signal))
+                        throw cause;
+                    const reason = `Linux process ownership inspection requires a procps-compatible ps on REA's PATH before launching a child: ${errorMessage(cause)}`;
+                    throw new AnalysisCapabilityUnavailableError("process-ownership", "prepare_owned_process", reason, { cause, userMessage: reason });
+                }
+            }
+        },
+        listProcesses,
+        async environment(pid) {
+            if (platform === "linux")
+                return parseProcessEnvironment(await readFile(`/proc/${pid}/environ`, "utf8"));
+            if (platform === "darwin") {
+                const process = (await listProcesses()).find((entry) => entry.pid === pid);
+                if (process === undefined)
+                    throw new Error(`process ${String(pid)} is not live`);
+                const observation = (await darwinTokens?.read([process]))?.get(pid);
+                if (observation === undefined || observation.state === "unavailable")
+                    throw new Error(observation?.reason ?? "process run token could not be read");
+                return observation.runId === undefined
+                    ? {}
+                    : { REA_PROCESS_RUN_ID: observation.runId };
+            }
+            const { stdout } = await execFileOutput("ps", ["eww", "-p", String(pid)], {
+                env: hostEnvironment,
+            });
+            const observedEnvironment = {};
+            for (const match of stdout.matchAll(/(?:^|\s)([A-Za-z_][A-Za-z0-9_]*)=([^\s]*)/gu)) {
+                const name = match[1];
+                if (name !== undefined)
+                    observedEnvironment[name] = match[2] ?? "";
+            }
+            return observedEnvironment;
+        },
+        async runTokens(processes) {
+            if (platform !== "darwin" || processes.length === 0)
+                return new Map();
+            try {
+                return (await darwinTokens?.read(processes)) ?? new Map();
+            }
+            catch (cause) {
+                void cause;
+                return new Map(processes.map(({ pid }) => [
+                    pid,
+                    { state: "unavailable", reason: "reader_failure" },
+                ]));
+            }
+        },
+        ...(platform !== "linux" && darwinTokens === undefined
+            ? {}
+            : {
+                processIdentities,
+                captureBaseline,
+                ...(darwinTokens === undefined ? {} : { close: darwinTokens.close }),
+            }),
+        signalGroup(processGroupId, signal) {
+            process.kill(-processGroupId, signal);
+        },
+    };
+};
+export const systemProcessOwnershipHost = createSystemProcessOwnershipHost();
+/** Observe the current OS start identity for one live PID, when supported. */
+export const observeProcessStartIdentity = async (pid, host = systemProcessOwnershipHost) => {
+    const process = (await host.listProcesses()).find((entry) => entry.pid === pid);
+    if (process === undefined || liveProcesses([process]).length === 0)
+        return undefined;
+    if (host.processIdentities === undefined)
+        return { state: "unavailable", reason: "process identity is unsupported" };
+    return ((await host.processIdentities([process])).get(pid) ?? {
+        state: "unavailable",
+        reason: "process identity was not returned",
+    });
+};
+/** Revalidate a launch-time start identity immediately before signaling a PID. */
+export const signalProcessWithStartIdentity = async (pid, expectedIdentity, signal, options = {}) => {
+    const host = options.host ?? systemProcessOwnershipHost;
+    try {
+        const observed = await observeProcessStartIdentity(pid, host);
+        if (observed === undefined)
+            return "gone";
+        if (observed.state !== "readable")
+            return "unverified";
+        if (observed.identity !== expectedIdentity)
+            return "identity-changed";
+        (options.sendSignal ?? process.kill)(pid, signal);
+        return "signaled";
+    }
+    catch {
+        return "unverified";
+    }
+};
+/** Prepare native token inspection before REA launches a captured child. */
+export const prepareProcessOwnershipInspection = async (signal) => {
+    await systemProcessOwnershipHost.prepare?.(signal);
+};
 /** Observe one group without signaling it, failing closed on identity doubt. */
-export const observeOwnedProcessGroup = async (ownership, host = systemHost) => observeOwnedProcessGroupWithHost(ownership, host);
+export const observeOwnedProcessGroup = async (ownership, host = systemProcessOwnershipHost) => observeOwnedProcessGroupWithHost(ownership, host);
 /**
  * Record the live launcher and descendant lineage after run-token validation.
  *
@@ -152,7 +334,7 @@ export const observeOwnedProcessGroup = async (ownership, host = systemHost) =>
  * list means no descendants were live during this observation, not that the
  * run never created a short-lived child.
  */
-export const observeOwnedProcessLineage = async (ownership, host = systemHost) => observeOwnedProcessLineageWithHost(ownership, host);
+export const observeOwnedProcessLineage = async (ownership, host = systemProcessOwnershipHost) => observeOwnedProcessLineageWithHost(ownership, host);
 const processIsGone = async (host, pid) => {
     try {
         return !liveProcesses(await host.listProcesses()).some((process) => process.pid === pid);

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 = {
@@ -70,12 +74,21 @@ export class ProviderProcessSupervisor {
     #exit = deferred();
     #outputClose = deferred();
     #outputClosed = false;
+    #stdoutObservedBytes = 0;
+    #stderrObservedBytes = 0;
+    #diagnosticTruncated = false;
     #onStdout = (chunk) => {
         this.#capture("stdout", this.#stdout, chunk);
     };
     #onStderr = (chunk) => {
         this.#capture("stderr", this.#stderr, chunk);
     };
+    #onStdoutError = (cause) => {
+        this.#recordStreamError("stdout", cause);
+    };
+    #onStderrError = (cause) => {
+        this.#recordStreamError("stderr", cause);
+    };
     #onExit = (code, signal) => {
         this.#recordExit(code, signal);
     };
@@ -102,9 +115,10 @@ 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,
@@ -115,6 +129,9 @@ export class ProviderProcessSupervisor {
     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) {
@@ -124,9 +141,13 @@ export class ProviderProcessSupervisor {
     async waitForOutputClose(timeoutMs) {
         return waitForProcessEvent(this.#outputClosed, this.#outputClose.promise, timeoutMs);
     }
-    /** Stop an owned process once; concurrent callers share the same escalation. */
+    /** Share each stop attempt; incomplete cleanup retains ownership and permits retry. */
     stop(options = {}) {
-        this.#stopPromise ??= this.#stop(options);
+        this.#stopPromise ??= this.#stop(options).then((result) => {
+            if (result.status === "incomplete")
+                this.#stopPromise = undefined;
+            return result;
+        });
         return this.#stopPromise;
     }
     /** Detach capture and process listeners after an adapter releases ownership. */
@@ -135,12 +156,26 @@ export class ProviderProcessSupervisor {
             return;
         this.#disposed = true;
         this.launch.process.stdout?.off("data", this.#onStdout);
+        this.launch.process.stdout?.off("error", this.#onStdoutError);
         this.launch.process.stderr?.off("data", this.#onStderr);
+        this.launch.process.stderr?.off("error", this.#onStderrError);
         this.launch.process.off("exit", this.#onExit);
         this.launch.process.off("close", this.#onClose);
         this.launch.process.off("error", this.#onError);
     }
     async #stop(options) {
+        let completed = false;
+        try {
+            const result = await this.#stopWithin(options);
+            completed = result.status !== "incomplete";
+            return result;
+        }
+        finally {
+            if (completed)
+                this.dispose();
+        }
+    }
+    async #stopWithin(options) {
         try {
             if (!this.launch.ownsProcessLifetime)
                 return { status: "not-owned" };
@@ -182,9 +217,6 @@ export class ProviderProcessSupervisor {
                     : "owned provider process cleanup failed",
             };
         }
-        finally {
-            this.dispose();
-        }
     }
     #ownedCleanup(supplied) {
         if (supplied !== undefined)
@@ -203,19 +235,45 @@ export class ProviderProcessSupervisor {
         this.launch.process.kill(signal);
     }
     #attach(stream, name) {
-        if (name === "stdout")
+        if (name === "stdout") {
             stream?.on("data", this.#onStdout);
-        else
+            stream?.on("error", this.#onStdoutError);
+        }
+        else {
             stream?.on("data", this.#onStderr);
+            stream?.on("error", this.#onStderrError);
+        }
+    }
+    #recordStreamError(stream, cause) {
+        this.#options.onDiagnostic?.({
+            type: "error",
+            message: `${stream} stream failed: ${cause.message}`,
+        });
     }
     #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) {

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

@@ -1,4 +1,5 @@
 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 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."
@@ -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,17 +7,33 @@ export class ProcessCaptureError extends AnalysisError {
     reason;
     cleanupIncomplete;
     cleanupResources;
+    executionFailure;
+    partialObservation;
+    cleanupReport;
     constructor(message, options) {
         super(message, options);
-        this.userMessage = options?.userMessage;
+        this.userMessage = options?.userMessage ?? message;
         this.userCategory = options?.userCategory;
         this.reason =
             options?.reason ??
                 (options?.userCategory === "cancelled" ? "cancelled" : "capture_failed");
         this.cleanupIncomplete = this.reason === "cleanup_incomplete";
         this.cleanupResources = options?.cleanupResources ?? [];
+        this.executionFailure = options?.executionFailure ?? message;
+        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",