rea-agents 6.3.0 → 6.5.0

package/dist/process/capture/ProcessCaptureProgress.js

@@ -0,0 +1,63 @@
+import { monotonicProcessCaptureClock } from "./ProcessCaptureClock.js";
+const formatProgressMessage = (elapsedMs, counts, disposition, cleanup) => {
+    const status = `elapsed_ms=${String(elapsedMs)} frames=${String(counts.frames)} samples=${String(counts.samples)} interactions=${String(counts.interactions)}`;
+    const dispositionText = disposition === undefined ? "" : ` disposition=${disposition}`;
+    const cleanupText = cleanup === undefined
+        ? ""
+        : ` owned_process_group=${cleanup.owned_process_group.state} terminal_renderer=${cleanup.terminal_renderer.state} temporary_root=${cleanup.temporary_root.state}`;
+    return `${status}${dispositionText}${cleanupText}`;
+};
+/** Serialize observed capture status through one rate-limited reporter. */
+export const createProcessCaptureProgressTracker = (progress, now = monotonicProcessCaptureClock) => {
+    const started = now();
+    let completed = 0;
+    let live = true;
+    let next;
+    let pending;
+    const flush = async () => {
+        try {
+            while (next !== undefined) {
+                const update = next;
+                next = undefined;
+                try {
+                    await progress?.report(update);
+                }
+                catch {
+                    // Progress delivery is observational; capture and cleanup still finish.
+                    continue;
+                }
+            }
+        }
+        finally {
+            pending = undefined;
+        }
+    };
+    return {
+        closeLive() {
+            live = false;
+            if (next?.terminal !== true)
+                next = undefined;
+        },
+        report(update) {
+            if (progress === undefined)
+                return Promise.resolve();
+            if (update.terminal !== true && !live)
+                return Promise.resolve();
+            const units = update.counts.frames +
+                update.counts.samples +
+                update.counts.interactions;
+            if (units > completed)
+                completed = units;
+            // A slow observer needs the latest observation, not a queue of old states.
+            next = {
+                phase: update.phase,
+                completed,
+                total: null,
+                message: formatProgressMessage(Math.max(0, now() - started), update.counts, update.disposition, update.cleanup),
+                ...(update.terminal === true ? { terminal: true } : {}),
+            };
+            pending ??= Promise.resolve().then(flush);
+            return pending;
+        },
+    };
+};

package/dist/process/capture/ProcessHarness.js

@@ -1,19 +1,65 @@
 import { parseProcessCapture } from "../../domain/process/processCaptureParsing.js";
 import { err, ok } from "../../domain/result.js";
 import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
-import {} from "../../domain/analysisErrorBase.js";
+import { AnalysisError } from "../../domain/analysisErrorBase.js";
 import { describeProcessCaptureExecutionFailure, ProcessCaptureError, normalizeCaptureFailure, processCaptureCancelled, } from "./ProcessCaptureError.js";
 import { startProcessSampler } from "./ProcessSampling.js";
 import { snapshotRoots } from "./FilesystemSnapshot.js";
 import { TerminalRenderer } from "./TerminalRenderer.js";
-import { normalizeProcessText } from "./ProcessNormalization.js";
+import { createBoundedProcessTextNormalizer, } 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";
+import { monotonicProcessCaptureClock } from "./ProcessCaptureClock.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 +79,7 @@ const cleanupFailedStartup = async (options) => {
             };
         }
     }
-    const cleanupFailure = await releaseProcessResources({
+    const cleanupOptions = {
         timers: options.timers,
         terminal: options.terminal,
         renderer: options.renderer,
@@ -42,9 +88,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
                 ? {}
@@ -53,12 +103,12 @@ const cleanupFailedStartup = async (options) => {
     }
     throw options.cause;
 };
-const createTerminalRenderer = (scenario, temporaryRoot, terminalPid, recordEvent) => new TerminalRenderer({
+const createTerminalRenderer = (scenario, normalizeText, recordEvent) => new TerminalRenderer({
     columns: scenario.terminal.columns,
     rows: scenario.terminal.rows,
     scrollback: scenario.terminal.scrollback,
     maxBytes: scenario.limits.output_bytes,
-    normalize: (value) => normalizeProcessText(value, scenario, temporaryRoot, terminalPid()),
+    normalize: normalizeText,
     recordEvent,
 });
 const startCaptureRuntime = async (options) => {
@@ -69,9 +119,10 @@ const startCaptureRuntime = async (options) => {
         const { spawn } = await import("@lydell/node-pty");
         const selectedExecutable = await observeSelectedExecutable(scenario.executable, options.signal);
         const startedAt = new Date();
-        const started = Date.now();
+        const started = monotonicProcessCaptureClock();
         let lastOutput = started;
-        renderer = createTerminalRenderer(scenario, options.temporaryRoot, () => terminal?.pid ?? -1, options.recordEvent);
+        const normalizeText = createBoundedProcessTextNormalizer(scenario, options.temporaryRoot, () => terminal?.pid ?? -1);
+        renderer = createTerminalRenderer(scenario, normalizeText, options.recordEvent);
         terminal = spawn(scenario.executable, [...scenario.arguments], {
             cwd: scenario.working_directory,
             env: makeProcessCaptureEnvironment(options),
@@ -85,12 +136,13 @@ const startCaptureRuntime = async (options) => {
             value: scenario.normalization.pids ? 1 : terminal.pid,
         };
         const executableIdentity = observeLaunchedExecutable(scenario.executable, selectedExecutable);
-        const rawTerminalRetention = captureTerminalFrames({
+        const terminalRetention = captureTerminalFrames({
             ...options,
             terminal,
             started,
-            onOutput: () => (lastOutput = Date.now()),
+            onOutput: () => (lastOutput = monotonicProcessCaptureClock()),
             renderer,
+            normalizeText,
         });
         scheduleScenarioInteractions({
             ...options,
@@ -113,8 +165,9 @@ const startCaptureRuntime = async (options) => {
             startedAt,
             executableIdentity,
             lastOutput: () => lastOutput,
-            rawTerminalRetention,
+            terminalRetention,
             stopSampler,
+            signalRoot: retainRootSignaller(terminal.pid, scenario.finalization_ms, options.runId, options.finalizationHost),
         };
     }
     catch (cause) {
@@ -131,15 +184,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 +205,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 +255,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 = {
@@ -204,7 +274,7 @@ const completeCapture = async (options) => {
     assertNotCancelled(options.signal);
     let after;
     try {
-        after = await options.captureSnapshot(scenario, options.signal);
+        after = await options.captureSnapshot(scenario, options.signal, options.before);
     }
     catch (cause) {
         options.observationBuffer.filesystem_snapshots = {
@@ -249,7 +319,7 @@ const completeCapture = async (options) => {
         },
         {
             name: "after_settlement",
-            at_ms: Math.max(0, Date.now() - runtime.started),
+            at_ms: Math.max(0, monotonicProcessCaptureClock() - runtime.started),
             files: after.files,
             effects: classifyFilesystemEffects(options.before, after),
             truncated: after.truncated,
@@ -274,7 +344,7 @@ const completeCapture = async (options) => {
         before: options.before,
         after,
         truncationDetails: {
-            raw_terminal: runtime.rawTerminalRetention(),
+            ...runtime.terminalRetention(),
             rendered_terminal: runtime.renderer.retention(),
             filesystem_before: options.before.coverage,
             filesystem_after: after.coverage,
@@ -291,12 +361,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 +420,7 @@ const runProcessScenario = async (scenario, signal, hostEnvironment = process.en
         samples,
         eventJournal,
         before,
+        finalizationEnabled: scenario.finalization_ms > 0,
     });
     let runtime;
     let actualRootPid;
@@ -322,6 +437,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 +449,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 +458,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 +513,7 @@ const runProcessScenario = async (scenario, signal, hostEnvironment = process.en
             recordEvent,
             captureSnapshot,
             ...(signal === undefined ? {} : { signal }),
+            ...(progress === undefined ? {} : { onLiveProgress: reportSettling }),
         });
     }
     catch (cause) {
@@ -408,28 +552,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 AnalysisError
+                ? 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 AnalysisError
+                ? 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;
 };