rea-agents 6.3.0 → 6.5.0

package/dist/process/ProcessOwnershipObservation.js

@@ -3,47 +3,66 @@ import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.
 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 observeOwnedProcessGroup = async (ownership, host = systemProcessOwnershipHost, signal) => {
+import { createDarwinProcessRunTokenReader, } from "./DarwinProcessRunTokenReader.js";
+import { readProcessRunTokens } from "./ProcessRunTokenObservations.js";
+/** Observe multiple groups from one process snapshot and one token batch. */
+export const observeOwnedProcessGroups = async (runId, processGroupIds, host = systemProcessOwnershipHost, signal) => {
     signal?.throwIfAborted();
-    let members;
+    const groupIds = [...new Set(processGroupIds)];
+    if (groupIds.length === 0)
+        return new Map();
+    let processes;
     try {
-        members = (await host.listProcesses(signal)).filter(({ processGroupId }) => processGroupId === ownership.processGroupId);
+        processes = liveProcesses(await host.listProcesses(signal));
     }
     catch (cause) {
         signal?.throwIfAborted();
-        return {
+        const failure = {
             state: "unverifiable",
             reason: `process group could not be inspected: ${errorMessage(cause)}`,
         };
+        return new Map(groupIds.map((groupId) => [groupId, failure]));
     }
     signal?.throwIfAborted();
-    const liveMembers = liveProcesses(members);
-    if (liveMembers.length === 0)
-        return { state: "empty" };
-    for (const member of liveMembers) {
-        signal?.throwIfAborted();
-        try {
-            const runId = (await host.environment(member.pid)).REA_PROCESS_RUN_ID;
-            signal?.throwIfAborted();
-            if (runId !== ownership.runId)
-                return {
+    const membersByGroup = new Map(groupIds.map((groupId) => [groupId, []]));
+    for (const process of processes)
+        membersByGroup.get(process.processGroupId)?.push(process);
+    const observations = new Map(groupIds.map((groupId) => [
+        groupId,
+        (membersByGroup.get(groupId)?.length ?? 0) > 0
+            ? { state: "alive" }
+            : { state: "empty" },
+    ]));
+    const liveMembers = groupIds.flatMap((groupId) => membersByGroup.get(groupId) ?? []);
+    const pendingGroups = new Set(groupIds.filter((groupId) => (membersByGroup.get(groupId)?.length ?? 0) > 0));
+    for await (const { process: member, observation } of readProcessRunTokens(host, liveMembers, signal)) {
+        if (!pendingGroups.has(member.processGroupId))
+            continue;
+        if (observation.state === "readable") {
+            if (observation.runId !== runId) {
+                observations.set(member.processGroupId, {
                     state: "unverifiable",
                     reason: "process ownership did not match",
-                };
+                });
+                pendingGroups.delete(member.processGroupId);
+            }
         }
-        catch (cause) {
+        else {
+            const gone = await processIsGone(host, member.pid);
             signal?.throwIfAborted();
-            if (!(await processIsGone(host, member.pid))) {
-                return {
+            if (!gone) {
+                observations.set(member.processGroupId, {
                     state: "unverifiable",
-                    reason: `process ownership could not be revalidated for PID ${member.pid}: ${errorMessage(cause)}`,
-                };
+                    reason: `process ownership could not be revalidated for PID ${member.pid}: ${observation.reason}`,
+                });
+                pendingGroups.delete(member.processGroupId);
             }
         }
+        if (pendingGroups.size === 0)
+            break;
     }
-    return { state: "alive" };
+    signal?.throwIfAborted();
+    return observations;
 };
 /**
  * Record the live launcher and descendant lineage after run-token validation.
@@ -66,23 +85,22 @@ export const observeOwnedProcessLineage = async (ownership, host = systemProcess
     const identityFailure = launcherIdentityFailure(launcher, ownership);
     if (identityFailure !== null)
         return unavailableLineage(ownership, identityFailure);
-    const descendants = descendantsOf(launcher.pid, processes);
+    const descendants = descendantsOf([launcher.pid], processes);
     const verifiedDescendants = [];
-    for (const member of [launcher, ...descendants]) {
-        try {
-            if ((await host.environment(member.pid)).REA_PROCESS_RUN_ID !==
-                ownership.runId)
+    for await (const { process: member, observation } of readProcessRunTokens(host, [launcher, ...descendants])) {
+        if (observation.state === "readable") {
+            if (observation.runId !== ownership.runId)
                 return unavailableLineage(ownership, "process lineage contains an unowned or PID-reused process");
             if (member.pid !== launcher.pid)
                 verifiedDescendants.push(member);
         }
-        catch (cause) {
+        else {
             if (await processIsGone(host, member.pid)) {
                 if (member.pid === launcher.pid)
                     return unavailableLineage(ownership, "owned launcher exited during lineage validation");
                 continue;
             }
-            return unavailableLineage(ownership, `process ownership could not be revalidated for PID ${member.pid}: ${errorMessage(cause)}`);
+            return unavailableLineage(ownership, `process ownership could not be revalidated for PID ${member.pid}: ${observation.reason}`);
         }
     }
     return {
@@ -138,10 +156,27 @@ const isExpectedAbort = (cause, signal) => signal?.aborted === true &&
         (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, options = {}) => {
+    const darwinModuleCachePath = options.darwinModuleCachePath ??
+        hostEnvironment.REA_DARWIN_MODULE_CACHE_PATH;
+    const swiftcPath = hostEnvironment.REA_DARWIN_SWIFTC_PATH;
+    const darwinCompiler = options.darwinCompiler ??
+        (swiftcPath === undefined || swiftcPath === ""
+            ? undefined
+            : {
+                kind: "swiftc",
+                executable: swiftcPath,
+                sdkRoot: hostEnvironment.SDKROOT ?? "",
+            });
     const darwinTokens = platform === "darwin"
-        ? createDarwinProcessRunTokenReader(options.darwinXcrun === undefined
-            ? {}
-            : { xcrun: options.darwinXcrun })
+        ? createDarwinProcessRunTokenReader({
+            ...(darwinCompiler === undefined ? {} : { compiler: darwinCompiler }),
+            ...(darwinModuleCachePath === undefined
+                ? {}
+                : { moduleCachePath: darwinModuleCachePath }),
+            ...(options.compileTimeoutMs === undefined
+                ? { environment: hostEnvironment }
+                : { compileTimeoutMs: options.compileTimeoutMs }),
+        })
         : undefined;
     const listProcesses = async (signal) => {
         if (platform === "win32")
@@ -251,14 +286,15 @@ export const createSystemProcessOwnershipHost = (platform = process.platform, ho
             }
         },
         listProcesses,
-        async environment(pid) {
+        async environment(pid, signal) {
+            signal?.throwIfAborted();
             if (platform === "linux")
-                return parseProcessEnvironment(await readFile(`/proc/${pid}/environ`, "utf8"));
+                return parseProcessEnvironment(await readFile(`/proc/${pid}/environ`, { encoding: "utf8", signal }));
             if (platform === "darwin") {
-                const process = (await listProcesses()).find((entry) => entry.pid === pid);
+                const process = (await listProcesses(signal)).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);
+                const observation = (await darwinTokens?.read([process], signal))?.get(pid);
                 if (observation === undefined || observation.state === "unavailable")
                     throw new Error(observation?.reason ?? "process run token could not be read");
                 return observation.runId === undefined
@@ -267,6 +303,7 @@ export const createSystemProcessOwnershipHost = (platform = process.platform, ho
             }
             const { stdout } = await execFileOutput("ps", ["eww", "-p", String(pid)], {
                 env: hostEnvironment,
+                ...(signal === undefined ? {} : { signal }),
             });
             const observedEnvironment = {};
             for (const match of stdout.matchAll(/(?:^|\s)([A-Za-z_][A-Za-z0-9_]*)=([^\s]*)/gu)) {
@@ -276,13 +313,16 @@ export const createSystemProcessOwnershipHost = (platform = process.platform, ho
             }
             return observedEnvironment;
         },
-        async runTokens(processes) {
+        async runTokens(processes, signal) {
+            signal?.throwIfAborted();
             if (platform !== "darwin" || processes.length === 0)
                 return new Map();
             try {
-                return (await darwinTokens?.read(processes)) ?? new Map();
+                return (await darwinTokens?.read(processes, signal)) ?? new Map();
             }
             catch (cause) {
+                if (isExpectedAbort(cause, signal))
+                    throw cause;
                 void cause;
                 return new Map(processes.map(({ pid }) => [
                     pid,
@@ -303,17 +343,65 @@ export const createSystemProcessOwnershipHost = (platform = process.platform, ho
     };
 };
 export const systemProcessOwnershipHost = createSystemProcessOwnershipHost();
-/** Observe the current OS start identity for one live PID, when supported. */
-export const observeProcessStartIdentity = async (pid, host = systemProcessOwnershipHost) => {
+/**
+ * Observe a live PID's start identity, optionally binding it to an owned run.
+ * Token validation is bracketed by identity reads so PID reuse cannot supply
+ * the first identity of a different process for an owned launch.
+ */
+export const observeProcessStartIdentity = async (pid, host = systemProcessOwnershipHost, expectedRunId) => {
     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) ?? {
+    const identity = (await host.processIdentities([process])).get(pid) ?? {
         state: "unavailable",
         reason: "process identity was not returned",
-    });
+    };
+    if (expectedRunId === undefined || identity.state !== "readable")
+        return identity;
+    let owned = false;
+    for await (const { observation } of readProcessRunTokens(host, [process])) {
+        if (observation.state === "unavailable")
+            return {
+                state: "unavailable",
+                reason: `process ownership token could not be read for PID ${String(pid)}: ${observation.reason}`,
+            };
+        if (observation.runId !== expectedRunId)
+            return {
+                state: "unavailable",
+                reason: `process ownership token did not match the captured run for PID ${String(pid)}`,
+            };
+        owned = true;
+    }
+    if (!owned)
+        return {
+            state: "unavailable",
+            reason: `process ownership token was not returned for PID ${String(pid)}`,
+        };
+    const confirmed = await observeProcessStartIdentity(pid, host);
+    if (confirmed === undefined || confirmed.state !== "readable")
+        return confirmed;
+    return confirmed.identity === identity.identity
+        ? identity
+        : {
+            state: "unavailable",
+            reason: `process identity changed while validating the captured run token for PID ${String(pid)}`,
+        };
+};
+/** Confirm whether the process that held an authenticated bridge has exited. */
+export const observeProcessStartIdentityExit = async (pid, expectedIdentity, host = systemProcessOwnershipHost) => {
+    try {
+        const observed = await observeProcessStartIdentity(pid, host);
+        if (observed === undefined)
+            return "exited";
+        if (observed.state !== "readable")
+            return "unverified";
+        return observed.identity === expectedIdentity ? "present" : "exited";
+    }
+    catch {
+        return "unverified";
+    }
 };
 /** Revalidate a launch-time start identity immediately before signaling a PID. */
 export const signalProcessWithStartIdentity = async (pid, expectedIdentity, signal, options = {}) => {

package/dist/process/ProcessOwnershipProcessTree.js

@@ -1,7 +1,7 @@
 /** Exclude process-table entries that the operating system has already reaped. */
 export const liveProcesses = (members) => members.filter(({ state }) => !state.startsWith("Z"));
-/** Return every live-table descendant of a launcher in breadth-first order. */
-export const descendantsOf = (launcherPid, processes) => {
+/** Return every live-table descendant of the selected roots in breadth-first order. */
+export const descendantsOf = (rootPids, processes) => {
     const childrenByParent = new Map();
     for (const process of processes) {
         const siblings = childrenByParent.get(process.parentPid) ?? [];
@@ -9,8 +9,8 @@ export const descendantsOf = (launcherPid, processes) => {
         childrenByParent.set(process.parentPid, siblings);
     }
     const descendants = [];
-    const pending = [...(childrenByParent.get(launcherPid) ?? [])];
-    const visited = new Set([launcherPid]);
+    const pending = rootPids.flatMap((pid) => childrenByParent.get(pid) ?? []);
+    const visited = new Set(rootPids);
     for (const process of pending) {
         if (visited.has(process.pid))
             continue;

package/dist/process/ProcessRunTokenObservations.js

@@ -0,0 +1,48 @@
+const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
+/** Read only ownership tokens, using per-process fallback for missing batch rows. */
+export async function* readProcessRunTokens(host, processes, signal) {
+    signal?.throwIfAborted();
+    if (processes.length === 0)
+        return;
+    let batch;
+    let batchFailure;
+    if (host.runTokens !== undefined) {
+        try {
+            batch =
+                signal === undefined
+                    ? await host.runTokens(processes)
+                    : await host.runTokens(processes, signal);
+        }
+        catch (cause) {
+            signal?.throwIfAborted();
+            batchFailure = errorMessage(cause);
+        }
+    }
+    for (const process of processes) {
+        signal?.throwIfAborted();
+        let observation = batch?.get(process.pid);
+        if (observation === undefined) {
+            try {
+                const environment = signal === undefined
+                    ? await host.environment(process.pid)
+                    : await host.environment(process.pid, signal);
+                observation = {
+                    state: "readable",
+                    runId: environment.REA_PROCESS_RUN_ID,
+                };
+            }
+            catch (cause) {
+                signal?.throwIfAborted();
+                const reason = errorMessage(cause);
+                observation = {
+                    state: "unavailable",
+                    reason: batchFailure === undefined
+                        ? reason
+                        : `${reason}; run-token batch failed: ${batchFailure}`,
+                };
+            }
+        }
+        signal?.throwIfAborted();
+        yield { process, observation };
+    }
+}

package/dist/process/ProviderDeadline.js

@@ -31,12 +31,12 @@ export class ProviderStartupDeadline {
         this.timeoutMs = timeoutMs;
         if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
             throw new RangeError("Provider startup timeout must be positive");
-        this.#deadlineAt = Date.now() + timeoutMs;
+        this.#deadlineAt = performance.now() + timeoutMs;
         this.#externalSignal = signal;
         this.#onExternalAbort = () => {
             if (this.#controller.signal.aborted)
                 return;
-            if (Date.now() >= this.#deadlineAt) {
+            if (performance.now() >= this.#deadlineAt) {
                 this.#interruption = "timeout";
                 this.#abort(new DOMException("Provider startup deadline elapsed", "TimeoutError"));
                 return;
@@ -49,12 +49,7 @@ export class ProviderStartupDeadline {
             return;
         }
         signal?.addEventListener("abort", this.#onExternalAbort, { once: true });
-        this.#timer = setTimeout(() => {
-            if (this.#controller.signal.aborted)
-                return;
-            this.#interruption = "timeout";
-            this.#abort(new DOMException("Provider startup deadline elapsed", "TimeoutError"));
-        }, timeoutMs);
+        this.#armDeadlineTimer(timeoutMs);
     }
     /** Composite signal aborted by either the caller or the absolute deadline. */
     get signal() {
@@ -63,15 +58,47 @@ export class ProviderStartupDeadline {
     /** First control path that interrupted startup, if any. */
     get interruption() {
         return (this.#interruption ??
-            (Date.now() >= this.#deadlineAt ? "timeout" : undefined));
+            (performance.now() >= this.#deadlineAt ? "timeout" : undefined));
     }
     /** Milliseconds still available to the next startup phase. */
     remainingMs() {
-        return Math.max(0, this.#deadlineAt - Date.now());
+        // Node timers can fire a fraction of a millisecond before the monotonic
+        // deadline, so an elapsed timer must not report time left to spend. A
+        // terminal timeout also cannot regain budget after later clock queries.
+        if (this.#interruption === "timeout")
+            return 0;
+        return Math.max(0, Math.ceil(this.#deadlineAt - performance.now()));
     }
-    /** Wait for at most one polling interval under the shared deadline signal. */
+    /**
+     * Wait for at most one polling interval under the shared deadline signal.
+     *
+     * Both timers may fire before their monotonic targets. Retain the earlier
+     * of the polling target and deadline, and wait again for any residual time.
+     */
     wait(milliseconds) {
-        return waitForAbortableDelay(Math.min(milliseconds, this.remainingMs()), this.signal);
+        const startedAt = performance.now();
+        // Absolute target: the earlier of the requested polling interval and the
+        // absolute monotonic deadline.
+        const targetAt = Math.min(startedAt + milliseconds, this.#deadlineAt);
+        const poll = () => {
+            const budget = this.remainingMs();
+            const residual = Math.max(0, targetAt - performance.now());
+            return waitForAbortableDelay(Math.min(residual, budget), this.signal).then((result) => {
+                if (result === "aborted")
+                    return "aborted";
+                const now = performance.now();
+                // The monotonic deadline expired: a full-budget wait resolves as an
+                // abort so polling stops at the boundary.
+                if (now >= this.#deadlineAt)
+                    return "aborted";
+                // The polling interval elapsed without expiring the deadline.
+                if (now >= targetAt)
+                    return "elapsed";
+                // A timer fired before the absolute target; keep waiting.
+                return poll();
+            });
+        };
+        return poll();
     }
     /** Release the deadline timer and external abort listener. */
     dispose() {
@@ -88,4 +115,23 @@ export class ProviderStartupDeadline {
             clearTimeout(this.#timer);
         this.#timer = undefined;
     }
+    /**
+     * Arm (or re-arm) the timer that expires the absolute monotonic deadline.
+     *
+     * Re-check the clock before classifying expiry, and retain the residual
+     * budget when the timer arrives early.
+     */
+    #armDeadlineTimer(milliseconds) {
+        this.#timer = setTimeout(() => {
+            this.#timer = undefined;
+            if (this.#controller.signal.aborted)
+                return;
+            if (performance.now() >= this.#deadlineAt) {
+                this.#interruption = "timeout";
+                this.#abort(new DOMException("Provider startup deadline elapsed", "TimeoutError"));
+                return;
+            }
+            this.#armDeadlineTimer(this.remainingMs());
+        }, milliseconds);
+    }
 }

package/dist/process/ProviderDiagnosticRedaction.js

@@ -0,0 +1,17 @@
+/** Redact explicit transport credentials from complete and budget-cut output. */
+export const redactCapturedTransportCredential = (stream, token, replacement) => {
+    if (token === undefined || token.length === 0)
+        return stream.text;
+    const { text } = stream;
+    const cutOff = stream.observedBytes > stream.bytes;
+    if (cutOff && !text.endsWith(token)) {
+        const maximumPrefixLength = Math.min(text.length, token.length - 1);
+        for (let prefixLength = maximumPrefixLength; prefixLength > 0; prefixLength -= 1) {
+            if (text.endsWith(token.slice(0, prefixLength)))
+                return `${text
+                    .slice(0, text.length - prefixLength)
+                    .replaceAll(token, replacement)}${replacement}`;
+        }
+    }
+    return text.replaceAll(token, replacement);
+};