rea-agents 6.3.0 → 6.4.0

package/dist/process/capture/ProcessHarness.js

@@ -8,12 +8,57 @@ import { snapshotRoots } from "./FilesystemSnapshot.js";
 import { TerminalRenderer } from "./TerminalRenderer.js";
 import { normalizeProcessText } from "./ProcessNormalization.js";
 import { selectCapturedProcessGroupIds } from "../ProcessOwnershipProcessTree.js";
-import { awaitTerminalExit, buildCaptureResult, cleanupReportFailure, captureTerminalFrames, createProcessCaptureObservationBuffer, createRunManifest, observeLaunchedExecutable, observeSelectedExecutable, observeSettlement, prepareProcessCapture, releaseProcessResources, resolveProcessResult, settleProcessCaptureJournal, } from "./ProcessCaptureLifecycle.js";
+import { awaitTerminalExit, buildCaptureResult, cleanupReportFailure, captureTerminalFrames, createProcessCaptureObservationBuffer, createRunManifest, observeLaunchedExecutable, observeSelectedExecutable, observeSettlement, prepareProcessCapture, releaseProcessResources, resolveProcessResult, settleProcessCaptureJournal, describeUnverifiedCause, ProcessCaptureResourceScope, } from "./ProcessCaptureLifecycle.js";
 import { assertNotCancelled, resolveProcessScenarioRuntimePaths, } from "./ProcessScenarioRuntimeValidation.js";
 import { createProcessCaptureJournal, scheduleScenarioInteractions, } from "./ProcessCaptureJournal.js";
 import { makeProcessCaptureEnvironment } from "./ProcessCaptureEnvironment.js";
 import { classifyFilesystemEffects } from "./ProcessFilesystemEffects.js";
 import { processCaptureOwnershipUnavailableReason } from "./ProcessCaptureCapability.js";
+import { createProcessCaptureProgressTracker, } from "./ProcessCaptureProgress.js";
+import { observeProcessStartIdentity, signalProcessWithStartIdentity, } from "../ProcessOwnershipObservation.js";
+/** Bind the captured root's initial identity to its run token before retaining it. */
+export const retainRootSignaller = (pid, finalizationMs, runId, host = {
+    observe: (rootPid) => observeProcessStartIdentity(rootPid, undefined, runId),
+    signal: signalProcessWithStartIdentity,
+}) => {
+    const retained = finalizationMs > 0
+        ? host.observe(pid).then((observation) => observation === undefined
+            ? { state: "gone" }
+            : observation.state === "readable"
+                ? {
+                    state: "identity",
+                    identity: observation.identity,
+                }
+                : {
+                    state: "unverified",
+                    reason: observation.reason.trim() === ""
+                        ? "start identity is unavailable without a diagnostic"
+                        : observation.reason,
+                }, (cause) => ({
+            state: "unverified",
+            reason: describeUnverifiedCause(cause, "start identity inspection failed without a message"),
+        }))
+        : undefined;
+    return async (signal) => {
+        const identity = await retained;
+        if (identity === undefined)
+            return {
+                delivery: "unverified",
+                reason: "root identity was not retained",
+            };
+        if (identity.state === "unverified")
+            return { delivery: "unverified", reason: identity.reason };
+        if (identity.state === "gone")
+            return { delivery: "gone" };
+        const delivery = await host.signal(pid, identity.identity, signal);
+        return delivery === "unverified"
+            ? {
+                delivery,
+                reason: "start identity could not be verified or the signal call failed",
+            }
+            : { delivery };
+    };
+};
 const cleanupFailedStartup = async (options) => {
     const sampledProcessGroupIds = options.terminal !== undefined &&
         options.observations?.process_samples.state === "available"
@@ -33,7 +78,7 @@ const cleanupFailedStartup = async (options) => {
             };
         }
     }
-    const cleanupFailure = await releaseProcessResources({
+    const cleanupOptions = {
         timers: options.timers,
         terminal: options.terminal,
         renderer: options.renderer,
@@ -42,9 +87,13 @@ const cleanupFailedStartup = async (options) => {
         ...(sampledProcessGroupIds === undefined ? {} : { sampledProcessGroupIds }),
         temporaryRoot: options.temporaryRoot,
         ...(options.cleanupHost === undefined ? {} : { host: options.cleanupHost }),
-    });
-    if (cleanupReportFailure(cleanupFailure) !== undefined) {
-        resolveProcessResult(undefined, options.cause, cleanupFailure, options.observations, {
+    };
+    const cleanup = options.resourceScope === undefined
+        ? await releaseProcessResources(cleanupOptions)
+        : await options.resourceScope.release(cleanupOptions);
+    const cleanupFailure = cleanupReportFailure(cleanup);
+    if (cleanupFailure !== undefined) {
+        resolveProcessResult(undefined, options.cause, cleanup, options.observations, {
             scenario: options.scenario,
             ...(options.terminal === undefined
                 ? {}
@@ -115,6 +164,7 @@ const startCaptureRuntime = async (options) => {
             lastOutput: () => lastOutput,
             rawTerminalRetention,
             stopSampler,
+            signalRoot: retainRootSignaller(terminal.pid, scenario.finalization_ms, options.runId, options.finalizationHost),
         };
     }
     catch (cause) {
@@ -131,15 +181,19 @@ const startCaptureRuntime = async (options) => {
                 : { cleanupHost: options.cleanupHost }),
             observations: options.observationBuffer,
             temporaryRoot: options.temporaryRoot,
+            ...(options.resourceScope === undefined
+                ? {}
+                : { resourceScope: options.resourceScope }),
         });
     }
 };
 const finishProcessRun = async (options) => {
+    options.progress.closeLive();
     await options.stopSampler();
     const sampledProcessGroupIds = options.runtime === undefined
         ? undefined
         : selectCapturedProcessGroupIds(options.runtime.terminal.pid, options.samples).filter((groupId) => groupId !== options.runtime?.terminal.pid);
-    const cleanup = await releaseProcessResources({
+    const cleanupOptions = {
         timers: options.timers,
         terminal: options.runtime?.terminal,
         renderer: options.runtime?.renderer,
@@ -148,6 +202,19 @@ const finishProcessRun = async (options) => {
         ...(sampledProcessGroupIds === undefined ? {} : { sampledProcessGroupIds }),
         temporaryRoot: options.temporaryRoot,
         ...(options.cleanupHost === undefined ? {} : { host: options.cleanupHost }),
+    };
+    const cleanup = options.resourceScope === undefined
+        ? await releaseProcessResources(cleanupOptions)
+        : await options.resourceScope.release(cleanupOptions);
+    const observedExit = options.observations?.exit.state === "available"
+        ? options.observations.exit.value.reason
+        : options.capture?.exit.reason;
+    await options.progress.report({
+        phase: "cleanup",
+        counts: options.progressCounts(),
+        terminal: true,
+        disposition: captureProgressDisposition(observedExit, options.executionFailure),
+        cleanup,
     });
     const cleanupFailure = cleanupReportFailure(cleanup);
     let { capture, executionFailure } = options;
@@ -185,7 +252,7 @@ const completeCapture = async (options) => {
         throw processCaptureCancelled();
     let settlement;
     try {
-        settlement = await observeSettlement(options.runId, selectCapturedProcessGroupIds(runtime.terminal.pid, options.samples), scenario.settle_ms, options.recordEvent, options.hostPlatform, options.signal);
+        settlement = await observeSettlement(options.runId, selectCapturedProcessGroupIds(runtime.terminal.pid, options.samples), scenario.settle_ms, options.recordEvent, options.hostPlatform, options.signal, options.onLiveProgress);
     }
     catch (cause) {
         options.observationBuffer.settlement = {
@@ -291,12 +358,56 @@ const completeCapture = async (options) => {
         eventJournal: options.eventJournal,
     });
 };
+const captureProgressDisposition = (exitReason, executionFailure) => {
+    if (exitReason === "exited" ||
+        exitReason === "timeout" ||
+        exitReason === "idle_timeout" ||
+        exitReason === "cancelled")
+        return exitReason;
+    if (executionFailure instanceof ProcessCaptureError &&
+        executionFailure.reason === "cancelled")
+        return "cancelled";
+    return "failed";
+};
 /** Execute one caller-selected scenario and return bounded observations. */
-const runProcessScenario = async (scenario, signal, hostEnvironment = process.env, hostPlatform = process.platform, captureSnapshot = snapshotRoots, cleanupHost) => {
-    const { temporaryRoot, runId, ownershipBaseline, before } = await prepareProcessCapture(scenario, signal, captureSnapshot);
+const runProcessScenario = async (scenario, signal, hostEnvironment = process.env, hostPlatform = process.platform, captureSnapshot = snapshotRoots, cleanupHost, progress, resourceScope, finalizationHost) => {
+    const progressTracker = createProcessCaptureProgressTracker(progress);
     const frames = [];
     const samples = [];
     const interactions = [];
+    const progressCounts = () => ({
+        frames: frames.length,
+        samples: samples.length,
+        interactions: interactions.length,
+    });
+    const reportRunning = () => {
+        void progressTracker.report({ phase: "running", counts: progressCounts() });
+    };
+    const reportSettling = () => {
+        void progressTracker.report({
+            phase: "settling",
+            counts: progressCounts(),
+        });
+    };
+    let prepared;
+    try {
+        await progressTracker.report({
+            phase: "prepare",
+            counts: progressCounts(),
+        });
+        prepared = await prepareProcessCapture(scenario, signal, captureSnapshot, undefined, resourceScope);
+    }
+    catch (cause) {
+        progressTracker.closeLive();
+        await progressTracker.report({
+            phase: "cleanup",
+            counts: progressCounts(),
+            terminal: true,
+            disposition: signal?.aborted === true ? "cancelled" : "failed",
+        });
+        throw cause;
+    }
+    const { temporaryRoot, runId, ownershipBaseline, before } = prepared;
     const journal = createProcessCaptureJournal();
     const { entries: eventJournal, recordEvent } = journal;
     recordEvent("filesystem_checkpoints", 0);
@@ -306,6 +417,7 @@ const runProcessScenario = async (scenario, signal, hostEnvironment = process.en
         samples,
         eventJournal,
         before,
+        finalizationEnabled: scenario.finalization_ms > 0,
     });
     let runtime;
     let actualRootPid;
@@ -322,6 +434,7 @@ const runProcessScenario = async (scenario, signal, hostEnvironment = process.en
             runId,
             ownershipBaseline,
             ...(cleanupHost === undefined ? {} : { cleanupHost }),
+            ...(resourceScope === undefined ? {} : { resourceScope }),
             observationBuffer: observations,
             onSpawn: (pid) => {
                 actualRootPid = pid;
@@ -333,6 +446,7 @@ const runProcessScenario = async (scenario, signal, hostEnvironment = process.en
             dispatchedEventIndexes,
             recordEvent,
             ...(signal === undefined ? {} : { signal }),
+            ...(finalizationHost === undefined ? {} : { finalizationHost }),
         });
         stopSampler = runtime.stopSampler;
         const exit = await awaitTerminalExit({
@@ -341,17 +455,43 @@ const runProcessScenario = async (scenario, signal, hostEnvironment = process.en
             started: runtime.started,
             lastOutput: runtime.lastOutput,
             signal,
+            signalTarget: runtime.signalRoot,
+            recordFinalization: (finalization) => {
+                observations.finalization = { state: "available", value: finalization };
+            },
             timers,
             interactions,
             dispatchedEventIndexes,
             recordEvent,
+            ...(progress === undefined ? {} : { onLiveProgress: reportRunning }),
         });
+        if (exit.unobserved === true) {
+            observations.finalization = {
+                state: "available",
+                value: exit.finalization,
+            };
+            observations.exit = {
+                state: "unavailable",
+                reason: `The captured process exit was not observed because the finalization SIGKILL could not be delivered (initiating reason: ${exit.reason}).`,
+            };
+            if (exit.reason === "cancelled")
+                throw processCaptureCancelled();
+            throw new Error("The captured process exit was not observed because the finalization SIGKILL could not be delivered.");
+        }
+        if (exit.finalization !== undefined)
+            observations.finalization = {
+                state: "available",
+                value: exit.finalization,
+            };
         observations.exit = {
             state: "available",
             value: {
                 code: exit.reason === "exited" && exit.exitCode >= 0 ? exit.exitCode : null,
                 signal: exit.signal ?? null,
                 reason: exit.reason,
+                ...(exit.finalization === undefined
+                    ? {}
+                    : { finalization: exit.finalization }),
             },
         };
         capture = await completeCapture({
@@ -370,6 +510,7 @@ const runProcessScenario = async (scenario, signal, hostEnvironment = process.en
             recordEvent,
             captureSnapshot,
             ...(signal === undefined ? {} : { signal }),
+            ...(progress === undefined ? {} : { onLiveProgress: reportSettling }),
         });
     }
     catch (cause) {
@@ -408,28 +549,55 @@ const runProcessScenario = async (scenario, signal, hostEnvironment = process.en
         executionFailure,
         observations,
         ...(actualRootPid === undefined ? {} : { rootPid: actualRootPid }),
+        progress: progressTracker,
+        progressCounts,
+        ...(resourceScope === undefined ? {} : { resourceScope }),
     });
 };
 /** Execute one scenario through a typed expected-failure channel. */
-export const captureProcessScenario = async (scenario, signal, platform = process.platform, environment = process.env, captureSnapshot = snapshotRoots, cleanupHost) => {
+export const captureProcessScenario = async (scenario, signal, platform = process.platform, environment = process.env, captureSnapshot, cleanupHost, progress, resourceScope, finalizationHost) => {
     const ownershipReason = processCaptureOwnershipUnavailableReason(platform);
     if (ownershipReason !== undefined)
         return err(new AnalysisCapabilityUnavailableError("rea-process", "capture_process_scenario", ownershipReason, { userMessage: ownershipReason }));
-    try {
-        assertNotCancelled(signal);
-        const resolvedScenario = await resolveProcessScenarioRuntimePaths(scenario, environment);
-        return ok(await runProcessScenario(resolvedScenario, signal, environment, platform, captureSnapshot, cleanupHost));
-    }
-    catch (cause) {
-        const failure = normalizeCaptureFailure(cause, signal);
-        const executionFailureReason = describeProcessCaptureExecutionFailure(cause);
-        return err(failure instanceof ProcessCaptureError
-            ? failure
-            : new ProcessCaptureError("process capture failed", {
-                cause,
-                ...(executionFailureReason === undefined
-                    ? {}
-                    : { executionFailure: executionFailureReason }),
-            }));
+    const runResourceScope = resourceScope ?? new ProcessCaptureResourceScope();
+    const execute = async () => {
+        try {
+            assertNotCancelled(signal);
+            const resolvedScenario = await resolveProcessScenarioRuntimePaths(scenario, environment);
+            const capture = await runProcessScenario(resolvedScenario, signal, environment, platform, captureSnapshot ?? snapshotRoots, cleanupHost, progress, runResourceScope, finalizationHost);
+            return ok(capture);
+        }
+        catch (cause) {
+            const failure = normalizeCaptureFailure(cause, signal);
+            const executionFailureReason = describeProcessCaptureExecutionFailure(cause);
+            return err(failure instanceof ProcessCaptureError
+                ? failure
+                : new ProcessCaptureError("process capture failed", {
+                    cause,
+                    ...(executionFailureReason === undefined
+                        ? {}
+                        : { executionFailure: executionFailureReason }),
+                }));
+        }
+    };
+    if (resourceScope !== undefined) {
+        try {
+            return await resourceScope.run(execute);
+        }
+        catch (cause) {
+            const failure = normalizeCaptureFailure(cause, signal);
+            const executionFailure = describeProcessCaptureExecutionFailure(cause);
+            return err(failure instanceof ProcessCaptureError
+                ? failure
+                : new ProcessCaptureError("process capture lifecycle failed", {
+                    cause,
+                    reason: "cleanup_incomplete",
+                    cleanupResources: ["process_capture_lifecycle"],
+                    ...(executionFailure === undefined ? {} : { executionFailure }),
+                }));
+        }
     }
+    const capture = await runResourceScope.run(execute);
+    await runResourceScope.close().catch(() => undefined);
+    return capture;
 };

package/dist/process/capture/ProcessNormalization.js

@@ -15,8 +15,10 @@ export const normalizeProcessText = (value, scenario, temporaryRoot, pid) => {
         normalized = normalizePortTokens(normalized);
     if (scenario.normalization.pids)
         normalized = normalizePidTokens(normalized, [pid]);
+    // A callback keeps replacement text literal while preserving replaceAll's
+    // empty-pattern boundaries, which the process scenario contract permits.
     for (const pattern of scenario.normalization.patterns)
-        normalized = normalized.replaceAll(pattern.pattern, pattern.replacement);
+        normalized = normalized.replaceAll(pattern.pattern, () => pattern.replacement);
     return normalized;
 };
 // A port may end a sentence, but a period followed by a letter, digit, or

package/dist/process/capture/ProcessScenarioRuntimeValidation.js

@@ -1,9 +1,10 @@
 import { access, realpath, stat } from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
 import { delimiter, isAbsolute, join, resolve } from "node:path";
+import { snapshotEnvironment } from "../snapshotEnvironment.js";
 import { ProcessCaptureError, processCaptureCancelled, } from "./ProcessCaptureError.js";
 /** Resolve caller-selected executable and observation paths for this execution. */
-export const resolveProcessScenarioRuntimePaths = async (scenario, environment = process.env) => {
+export const resolveProcessScenarioRuntimePaths = async (scenario, environment = process.env, platform = process.platform) => {
     const selectedWorkingDirectory = resolve(scenario.working_directory);
     let workingDirectory;
     try {
@@ -21,7 +22,9 @@ export const resolveProcessScenarioRuntimePaths = async (scenario, environment =
     }
     if (!workingDirectoryStat.isDirectory())
         throw new ProcessCaptureError(`working directory is not a directory: ${workingDirectory}`);
-    const executable = await resolveExecutable(scenario.executable, workingDirectory, scenario.environment.PATH ?? environment.PATH ?? "");
+    const executable = await resolveExecutable(scenario.executable, workingDirectory, snapshotEnvironment(scenario.environment, platform).PATH ??
+        snapshotEnvironment(environment, platform).PATH ??
+        "");
     const observationPaths = scenario.filesystem_observation_paths.map((path) => resolve(workingDirectory, path));
     return {
         ...scenario,

package/dist/process/capture/TerminalRenderer.js

@@ -4,6 +4,7 @@ const require = createRequire(import.meta.url);
 const HeadlessPackage = require("@xterm/headless");
 // SAFETY: the addon package is pinned with the compatible headless xterm release.
 const SerializePackage = require("@xterm/addon-serialize");
+const TRAILING_SPACES = / +$/u;
 /**
  * Owns one headless terminal and serializes writes into deterministic frames.
  * Reconstructs bounded terminal states while raw PTY chunks remain authoritative.
@@ -34,16 +35,21 @@ export class TerminalRenderer {
     }
     /** Queue one PTY chunk and capture state only after xterm has parsed it. */
     write(data, atMs) {
-        this.#pending = this.#pending.then(() => new Promise((resolveWrite) => {
+        this.#queue(() => new Promise((resolveWrite, rejectWrite) => {
             this.#terminal.write(data, () => {
-                this.#capture(atMs);
-                resolveWrite();
+                try {
+                    this.#capture(atMs);
+                    resolveWrite();
+                }
+                catch (error) {
+                    rejectWrite(error);
+                }
             });
         }));
     }
     /** Queue a terminal resize after every preceding write. */
     resize(columns, rows, atMs) {
-        this.#pending = this.#pending.then(() => {
+        this.#queue(() => {
             this.#terminal.resize(columns, rows);
             this.#capture(atMs);
         });
@@ -69,16 +75,27 @@ export class TerminalRenderer {
     }
     /** Release addon and terminal resources after all writes settle. */
     async dispose() {
-        await this.#pending;
-        this.#serializeAddon.dispose();
+        // frames() owns observation failures; cleanup reports only disposal failures.
+        await this.#pending.catch(() => undefined);
+        // xterm owns and disposes every addon loaded through loadAddon().
         this.#terminal.dispose();
     }
+    #queue(operation) {
+        this.#pending = this.#pending.then(operation);
+        // PTY callbacks can fail before capture completion awaits frames(). Keep
+        // the original rejection observable there without an unhandled rejection.
+        void this.#pending.catch(() => undefined);
+    }
     #capture(atMs) {
         const buffer = this.#terminal.buffer.active;
         const lines = [];
         for (let row = 0; row < this.#terminal.rows; row += 1) {
             const line = buffer.getLine(buffer.viewportY + row);
-            lines.push(this.options.normalize((line?.translateToString(false, 0, this.#terminal.cols) ?? "").padEnd(this.#terminal.cols, " ")));
+            // Trailing blank cells carry no information beyond `columns`; dropping
+            // them keeps sparse screens from costing a full row per blank line.
+            lines.push(this.options
+                .normalize((line?.translateToString(false, 0, this.#terminal.cols) ?? "").padEnd(this.#terminal.cols, " "))
+                .replace(TRAILING_SPACES, ""));
         }
         const serializedState = this.options.normalize(this.#serializeAddon.serialize());
         const bytes = Buffer.byteLength(serializedState) +

package/dist/reference/ReferenceSourceReader.js

@@ -1,11 +1,28 @@
 import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
 import { err, ok } from "../domain/result.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
 import { traverseDirectory } from "./ReferenceSourceReaderEntries.js";
 import {} from "./ReferenceSourceReaderTypes.js";
 import { isAborted, noFollowOpenSupported, prepareRoot, } from "./ReferenceSourceReaderValidate.js";
 const PATH_RACE_LIMITATION = "Path identity is revalidated around operations; Node lacks portable descriptor-relative openat traversal, so a syscall-boundary pathname race remains.";
 /** Read a source tree without intentionally following symbolic links. */
-export const readReferenceSource = async (root, options = {}) => {
+export const readReferenceSource = async (root, resources, options = {}) => {
+    try {
+        return await resources.run(() => readSource(root, resources, options));
+    }
+    catch (cause) {
+        if (!(cause instanceof ArtifactReaderFailure))
+            throw cause;
+        return err({
+            tag: "reference-source-reader",
+            code: cause.reason === "cancelled" ? "cancelled" : "io",
+            message: cause.message,
+            ...(cause.cleanup === undefined ? {} : { cleanup: cause.cleanup }),
+            cause,
+        });
+    }
+};
+const readSource = async (root, resources, options) => {
     if (!noFollowOpenSupported())
         return err({
             tag: "reference-source-reader",
@@ -17,6 +34,7 @@ export const readReferenceSource = async (root, options = {}) => {
         return prepared;
     const { canonicalRoot, rootIdentity } = prepared.value;
     const state = {
+        resources,
         root: canonicalRoot,
         rootIdentity,
         ...(options.signal === undefined ? {} : { signal: options.signal }),
@@ -28,15 +46,14 @@ export const readReferenceSource = async (root, options = {}) => {
         bytesRead: 0,
     };
     const traversal = await traverse(state);
-    if (!traversal.ok)
-        return traversal;
     state.entries.sort((left, right) => compareUnicodeCodePoints(left.path, right.path));
-    return ok({
+    const read = {
         root: canonicalRoot,
         entries: state.entries,
         bytesRead: state.bytesRead,
         limitations: [PATH_RACE_LIMITATION],
-    });
+    };
+    return traversal.ok ? ok(read) : err({ ...traversal.error, partial: read });
 };
 const traverse = async (state) => {
     while (state.pending.length > 0) {