rea-agents 3.2.1 → 4.0.1

package/dist/application/ProcessHarness.js

@@ -1,20 +1,19 @@
 import { parseProcessCapture } from "../domain/processCapture.js";
 import { err, ok } from "../domain/result.js";
+import { AnalysisCapabilityUnavailableError, } from "../domain/errors.js";
 import { ProcessCaptureError, processCaptureCancelled, } from "./ProcessCaptureError.js";
 export { ProcessCaptureError } from "./ProcessCaptureError.js";
-import { startLoopbackReplay } from "./LoopbackReplay.js";
 import { startProcessSampler } from "./ProcessSampling.js";
 import { snapshotRoots } from "./FilesystemSnapshot.js";
-import { ProcessCheckpoints } from "./ProcessCheckpoints.js";
 import { TerminalRenderer } from "./TerminalRenderer.js";
-import { startCommandShimReplay, } from "./CommandShimReplay.js";
-import { normalizeProcessShimEvent, normalizeProcessText, } from "./ProcessNormalization.js";
+import { normalizeProcessText } from "./ProcessNormalization.js";
 import { selectCapturedProcessGroupIds } from "../process/ProcessOwnership.js";
-import { awaitTerminalExit, buildCaptureResult, captureTerminalFrames, createRunManifest, observeSettlement, prepareProcessCapture, releaseProcessResources, resolveProcessResult, } from "./ProcessCaptureLifecycle.js";
-import { assertNotCancelled } from "./ProcessCaptureAuthority.js";
+import { awaitTerminalExit, buildCaptureResult, captureTerminalFrames, createRunManifest, observeSettlement, prepareProcessCapture, releaseProcessResources, resolveProcessResult, settleProcessCaptureJournal, } from "./ProcessCaptureLifecycle.js";
+import { assertNotCancelled, resolveProcessScenarioRuntimePaths, } from "./ProcessScenarioRuntimeValidation.js";
 import { createProcessCaptureJournal, scheduleScenarioInteractions, } from "./ProcessCaptureJournal.js";
-import { assertSupportedReactiveScenario, projectProcessReactiveRun, startProcessReactiveHarness, } from "./ProcessReactiveHarness.js";
 import { makeProcessCaptureEnvironment } from "./ProcessCaptureEnvironment.js";
+import { classifyFilesystemEffects } from "./ProcessFilesystemEffects.js";
+import { processCaptureOwnershipUnavailableReason } from "./ProcessCaptureCapability.js";
 export { probeProcessCaptureCapability } from "./ProcessCaptureCapability.js";
 const cleanupFailedStartup = async (options) => {
     options.terminal?.kill("SIGKILL");
@@ -37,59 +36,19 @@ const createTerminalRenderer = (scenario, temporaryRoot, terminalPid, recordEven
     normalize: (value) => normalizeProcessText(value, scenario, temporaryRoot, terminalPid()),
     recordEvent,
 });
-/**
- * Wait until the capture journal stops growing.
- *
- * node-pty reports buffered output through `onData` callbacks rather than an
- * awaitable read, so chunks can still be in flight after the child exits. The
- * quiet interval is measured in elapsed time rather than scheduler turns:
- * consecutive `setImmediate` turns elapse in microseconds, so any fixed number
- * of them finishes long before a delayed pty callback under host contention,
- * which is exactly when the trailing chunk matters. `maxWaitMs` bounds the
- * total wait so a pathological stream cannot stall exit.
- */
-const settleTrailingJournal = async (journal, quietMs = 25, maxWaitMs = 500) => {
-    const deadline = Date.now() + maxWaitMs;
-    let observed = journal.length;
-    let lastChangeAt = Date.now();
-    while (Date.now() < deadline) {
-        await new Promise((resolve) => setTimeout(resolve, 4));
-        if (journal.length !== observed) {
-            observed = journal.length;
-            lastChangeAt = Date.now();
-        }
-        else if (Date.now() - lastChangeAt >= quietMs)
-            return;
-    }
-};
-const reactiveCapture = (options, protocolEvents) => ({
-    ...options,
-    processSamples: options.samples,
-    protocolEvents,
-});
 const startCaptureRuntime = async (options) => {
     const { scenario } = options;
-    let replay;
     let renderer;
-    let checkpoints;
-    let shimReplay;
     let terminal;
-    let reactive;
     try {
         const { spawn } = await import("@lydell/node-pty");
-        replay = await startLoopbackReplay(scenario, options.recordEvent);
         const startedAt = new Date();
         const started = Date.now();
         let lastOutput = started;
         renderer = createTerminalRenderer(scenario, options.temporaryRoot, () => terminal?.pid ?? -1, options.recordEvent);
-        checkpoints = new ProcessCheckpoints(scenario, started, options.before, {
-            signal: options.signal,
-            recordEvent: options.recordEvent,
-        });
-        shimReplay = await startCommandShimReplay(scenario, options.temporaryRoot, started, options.recordEvent);
         terminal = spawn(scenario.executable, [...scenario.arguments], {
             cwd: scenario.working_directory,
-            env: makeProcessCaptureEnvironment({ ...options, replay, shimReplay }),
+            env: makeProcessCaptureEnvironment(options),
             cols: scenario.terminal.columns,
             rows: scenario.terminal.rows,
             name: "xterm-256color",
@@ -100,16 +59,6 @@ const startCaptureRuntime = async (options) => {
             started,
             onOutput: () => (lastOutput = Date.now()),
             renderer,
-            checkpoints,
-        });
-        reactive = startProcessReactiveHarness({
-            capture: reactiveCapture(options, () => replay?.events ?? []),
-            scenario,
-            terminal: () => terminal,
-            renderer,
-            checkpoints,
-            shimReplay,
-            started,
         });
         scheduleScenarioInteractions({
             ...options,
@@ -126,57 +75,38 @@ const startCaptureRuntime = async (options) => {
             recordEvent: options.recordEvent,
         });
         return {
-            replay,
             renderer,
-            checkpoints,
-            shimReplay,
             terminal,
             started,
             startedAt,
             lastOutput: () => lastOutput,
             framesTruncated,
             stopSampler,
-            reactive,
         };
     }
     catch (cause) {
-        reactive?.unsubscribe();
-        await reactive?.coordinator.close();
         return cleanupFailedStartup({
             cause,
             timers: options.timers,
-            replay,
             terminal,
             renderer,
-            shimReplay,
-            checkpoints,
             runId: options.runId,
             temporaryRoot: options.temporaryRoot,
         });
     }
 };
-const normalizedShimEvents = (runtime, scenario, temporaryRoot) => runtime.shimReplay.events.map((event) => normalizeProcessShimEvent(event, scenario, temporaryRoot, runtime.terminal.pid));
 const finishProcessRun = async (options) => {
-    options.runtime?.reactive?.unsubscribe();
     await options.stopSampler();
     const cleanupFailure = await releaseProcessResources({
         timers: options.timers,
-        replay: options.runtime?.replay,
         terminal: options.runtime?.terminal,
         renderer: options.runtime?.renderer,
-        shimReplay: options.runtime?.shimReplay,
-        checkpoints: options.runtime?.checkpoints,
         runId: options.runId,
         temporaryRoot: options.temporaryRoot,
         capturedProcessGroupIds: options.runtime === undefined
             ? []
             : selectCapturedProcessGroupIds(options.runtime.terminal.pid, options.samples),
     });
-    if (cleanupFailure !== undefined)
-        await options.runtime?.reactive?.coordinator.submit({
-            kind: "cleanup_failed",
-        });
-    await options.runtime?.reactive?.coordinator.close();
     let { capture, executionFailure } = options;
     let verifiedCapture;
     if (capture !== undefined && cleanupFailure === undefined) {
@@ -185,7 +115,6 @@ const finishProcessRun = async (options) => {
             : { ...capture.settlement, cleanup_outcome: "cleaned" };
         const completedCapture = {
             ...capture,
-            reactive_run: projectProcessReactiveRun(options.runtime?.reactive),
             settlement,
             cleanup: {
                 owned_process_group: "verified",
@@ -203,45 +132,35 @@ const finishProcessRun = async (options) => {
 };
 const completeCapture = async (options) => {
     const { runtime, scenario } = options;
-    runtime.checkpoints.trigger("root_exit");
     const { reason } = options.exit;
-    if (reason === "cancelled") {
-        if (runtime.reactive !== undefined) {
-            await runtime.reactive.coordinator.submit({ kind: "cancelled" });
-            runtime.reactive.unsubscribe();
-        }
+    if (reason === "cancelled")
         throw processCaptureCancelled();
-    }
-    const settlement = await observeSettlement(options.runId, selectCapturedProcessGroupIds(runtime.terminal.pid, options.samples), scenario.settle_ms, options.recordEvent);
-    runtime.checkpoints.trigger("settled");
+    const settlement = await observeSettlement(options.runId, selectCapturedProcessGroupIds(runtime.terminal.pid, options.samples), scenario.settle_ms, options.recordEvent, options.hostPlatform);
     const samplingPartial = (await runtime.stopSampler()).partial;
-    if (runtime.reactive !== undefined) {
-        // Process, filesystem, shim, and protocol observations can be recorded
-        // during settlement after the PTY exits. Make target loss terminal only
-        // after that journal has drained, otherwise the coordinator's control
-        // priority discards a valid multi-source completion predicate.
-        //
-        // Draining the coordinator is not sufficient on its own: node-pty delivers
-        // buffered output through onData callbacks, which run outside the
-        // coordinator's queue. A trailing chunk that has not been delivered yet has
-        // produced no journal entry, so the drain has nothing to wait for and the
-        // target is declared lost while a terminal trigger is still satisfiable.
-        // Let any trailing chunks land first.
-        await settleTrailingJournal(options.eventJournal);
-        await runtime.reactive.coordinator.drain();
-        await runtime.reactive.coordinator.submit({ kind: "target_lost" });
-        runtime.reactive.unsubscribe();
-    }
+    await settleProcessCaptureJournal(options.eventJournal);
     assertNotCancelled(options.signal);
     const after = await snapshotRoots(scenario, options.signal);
+    options.recordEvent("filesystem_checkpoints", 1);
     const renderedFrames = await runtime.renderer.frames();
-    const checkpoints = await runtime.checkpoints.finish(after);
-    await runtime.replay.close();
-    const manifest = await createRunManifest(scenario, runtime.startedAt, new Date());
+    const checkpoints = [
+        {
+            name: "before",
+            at_ms: 0,
+            files: options.before.files,
+            effects: [],
+            truncated: options.before.truncated,
+        },
+        {
+            name: "after_settlement",
+            at_ms: Math.max(0, Date.now() - runtime.started),
+            files: after.files,
+            effects: classifyFilesystemEffects(options.before.files, after.files),
+            truncated: after.truncated,
+        },
+    ];
+    const manifest = await createRunManifest(scenario, runtime.startedAt, new Date(), { platform: options.hostPlatform, architecture: process.arch });
     const truncated = options.initiallyTruncated ||
         after.truncated ||
-        runtime.replay.truncated ||
-        runtime.shimReplay.truncated ||
         runtime.framesTruncated() ||
         checkpoints.some(({ truncated: partial }) => partial) ||
         samplingPartial ||
@@ -250,7 +169,6 @@ const completeCapture = async (options) => {
         frames: options.frames,
         exit: { ...options.exit, reason },
         samples: options.samples,
-        replay: runtime.replay,
         before: options.before,
         after,
         truncated,
@@ -260,20 +178,19 @@ const completeCapture = async (options) => {
         renderedFrames,
         interactions: options.interactions,
         checkpoints,
-        shimEvents: normalizedShimEvents(runtime, scenario, options.temporaryRoot),
         settlement,
         manifest,
         eventJournal: options.eventJournal,
     });
 };
-/** Execute one authorized scenario and return bounded observations. */
-const runProcessScenario = async (scenario, policy, signal) => {
-    assertSupportedReactiveScenario(scenario);
-    const { temporaryRoot, runId, home, before } = await prepareProcessCapture(scenario, policy, signal);
+/** Execute one caller-selected scenario and return bounded observations. */
+const runProcessScenario = async (scenario, signal, hostEnvironment = process.env, hostPlatform = process.platform) => {
+    const { temporaryRoot, runId, before } = await prepareProcessCapture(scenario, signal);
     const frames = [];
     const samples = [];
     const journal = createProcessCaptureJournal();
     const { entries: eventJournal, recordEvent } = journal;
+    recordEvent("filesystem_checkpoints", 0);
     let runtime;
     const timers = new Set();
     let capture;
@@ -284,17 +201,15 @@ const runProcessScenario = async (scenario, policy, signal) => {
     try {
         runtime = await startCaptureRuntime({
             scenario,
-            home,
+            hostEnvironment,
             temporaryRoot,
             runId,
-            before,
             frames,
             samples,
             interactions,
             timers,
             dispatchedEventIndexes,
             recordEvent,
-            journal,
             ...(signal === undefined ? {} : { signal }),
         });
         stopSampler = runtime.stopSampler;
@@ -311,6 +226,7 @@ const runProcessScenario = async (scenario, policy, signal) => {
         });
         capture = await completeCapture({
             scenario,
+            hostPlatform,
             runtime,
             runId,
             temporaryRoot,
@@ -341,9 +257,14 @@ const runProcessScenario = async (scenario, policy, signal) => {
     });
 };
 /** Execute one scenario through a typed expected-failure channel. */
-export const captureProcessScenario = async (scenario, policy, signal) => {
+export const captureProcessScenario = async (scenario, signal, platform = process.platform, environment = process.env) => {
+    const ownershipReason = processCaptureOwnershipUnavailableReason(platform);
+    if (ownershipReason !== undefined)
+        return err(new AnalysisCapabilityUnavailableError("rea-process", "capture_process_scenario", ownershipReason));
     try {
-        return ok(await runProcessScenario(scenario, policy, signal));
+        assertNotCancelled(signal);
+        const resolvedScenario = await resolveProcessScenarioRuntimePaths(scenario, environment);
+        return ok(await runProcessScenario(resolvedScenario, signal, environment, platform));
     }
     catch (cause) {
         return err(cause instanceof ProcessCaptureError

package/dist/application/ProcessNormalization.js

@@ -1,18 +1,13 @@
 /** Bucket one elapsed process-capture timestamp under scenario normalization. */
 export const normalizeProcessElapsedTime = (elapsedMs, timeBucketMs) => Math.floor(elapsedMs / timeBucketMs) * timeBucketMs;
-/** Normalize and redact one terminal/protocol payload under scenario rules. */
+/** Normalize one terminal/protocol payload under explicitly selected scenario rules. */
 export const normalizeProcessText = (value, scenario, temporaryRoot, pid) => {
     let normalized = value;
-    for (const alias of scenario.secret_aliases) {
-        const secret = scenario.environment[alias];
-        if (secret !== undefined && secret.length > 0)
-            normalized = normalized.replaceAll(secret, "<redacted>");
-    }
     if (scenario.normalization.paths) {
         normalized = normalized.replaceAll(temporaryRoot, "<temporary-root>");
         normalized = normalized.replaceAll(scenario.working_directory, "<working-directory>");
         normalized = normalized.replaceAll(scenario.executable, "<executable>");
-        for (const [index, root] of scenario.filesystem_roots.entries())
+        for (const [index, root] of scenario.filesystem_observation_paths.entries())
             normalized = normalized.replaceAll(root, `<filesystem-root-${String(index)}>`);
     }
     if (scenario.normalization.pids)
@@ -55,12 +50,6 @@ export const normalizeProcessSamples = (samples, scenario, rootPid) => {
         command: normalizeCommand(sample.command),
     }));
 };
-/** Normalize one shim observation identically for live matching and capture. */
-export const normalizeProcessShimEvent = (event, scenario, temporaryRoot, rootPid) => ({
-    ...event,
-    arguments: event.arguments.map((argument) => normalizeProcessText(argument, scenario, temporaryRoot, rootPid)),
-    working_directory: normalizeProcessText(event.working_directory, scenario, temporaryRoot, rootPid),
-});
 const normalizePidTokens = (value, identifiers) => {
     const tokens = [...new Set(identifiers)]
         .filter((identifier) => Number.isSafeInteger(identifier) && identifier > 0)
@@ -70,7 +59,3 @@ const normalizePidTokens = (value, identifiers) => {
         return value;
     return value.replace(new RegExp(`(?<!\\d)(?:${tokens.join("|")})(?!\\d)`, "gu"), "<pid>");
 };
-export const redactProtocolEvents = (events, scenario) => events.map((event) => ({
-    ...event,
-    data: normalizeProcessText(event.data, scenario, "<no-temporary-root>", -1),
-}));

package/dist/application/ProcessScenarioRuntimeValidation.js

@@ -0,0 +1,76 @@
+import { access, realpath, stat } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import { delimiter, isAbsolute, join, resolve } from "node:path";
+import { ProcessCaptureError, processCaptureCancelled, } from "./ProcessCaptureError.js";
+/** Resolve caller-selected executable and observation paths for this execution. */
+export const resolveProcessScenarioRuntimePaths = async (scenario, environment = process.env) => {
+    const selectedWorkingDirectory = resolve(scenario.working_directory);
+    let workingDirectory;
+    try {
+        workingDirectory = await realpath(selectedWorkingDirectory);
+    }
+    catch (cause) {
+        throw new ProcessCaptureError(`working directory could not be resolved: ${selectedWorkingDirectory}${osFailure(cause)}`, { cause });
+    }
+    let workingDirectoryStat;
+    try {
+        workingDirectoryStat = await stat(workingDirectory);
+    }
+    catch (cause) {
+        throw new ProcessCaptureError(`working directory could not be inspected: ${workingDirectory}${osFailure(cause)}`, { cause });
+    }
+    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 observationPaths = scenario.filesystem_observation_paths.map((path) => resolve(workingDirectory, path));
+    return {
+        ...scenario,
+        executable,
+        working_directory: workingDirectory,
+        filesystem_observation_paths: observationPaths,
+    };
+};
+/** Resolve a selected executable through the caller's effective PATH. */
+export const resolveExecutable = async (command, workingDirectory, searchPath) => {
+    const directories = searchPath
+        .split(delimiter)
+        .map((directory) => directory === ""
+        ? workingDirectory
+        : resolve(workingDirectory, directory));
+    const candidates = isAbsolute(command) || command.includes("/") || command.includes("\\")
+        ? [resolve(workingDirectory, command)]
+        : directories.map((directory) => join(directory, command));
+    const failures = [];
+    for (const candidate of candidates) {
+        try {
+            await access(candidate, fsConstants.X_OK);
+            if ((await stat(candidate)).isFile())
+                return candidate;
+            failures.push(`${candidate} (not a regular file)`);
+        }
+        catch (cause) {
+            const code = osErrorCode(cause);
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                failures.push(`${candidate}${osFailure(cause)}`);
+            continue;
+        }
+    }
+    throw new ProcessCaptureError(failures.length === 0
+        ? `executable could not be resolved: ${command}`
+        : `executable could not be resolved: ${command}; checked ${failures.join("; ")}`);
+};
+const osErrorCode = (cause) => typeof cause === "object" &&
+    cause !== null &&
+    "code" in cause &&
+    typeof cause.code === "string"
+    ? cause.code
+    : undefined;
+const osFailure = (cause) => {
+    const code = osErrorCode(cause);
+    return code === undefined ? "" : ` (${code})`;
+};
+/** Reject cancellation before a process capture operation begins. */
+export const assertNotCancelled = (signal) => {
+    if (signal?.aborted === true)
+        throw processCaptureCancelled();
+};

package/dist/application/ReferenceSourceImport.js

@@ -1,5 +1,4 @@
 import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
-import { isSecretLikePath } from "../domain/referenceSourceClassification.js";
 import { createHistoricalSourceGraph, historicalSourceLanguages, historicalSourceManifests, historicalSourceParseFailureKey, } from "../domain/referenceSourceGraph.js";
 import { err, ok } from "../domain/result.js";
 import { readReferenceSource } from "../reference/ReferenceSourceReader.js";
@@ -72,8 +71,8 @@ const sortExclusions = (exclusions) => [...exclusions].sort((left, right) => {
  * Import a reference source directory into a committed historical source graph.
  *
  * The import is deterministic, parallel-safe, and never executes source, hooks,
- * git subprocesses, or network requests. Secret-like paths are redacted before
- * they are committed to the graph.
+ * git subprocesses, or network requests. Paths explicitly excluded by the
+ * caller's reference-source policy are omitted from the graph.
  */
 export const importReferenceSource = async (options) => {
     if (isAborted(options.signal))
@@ -86,7 +85,7 @@ export const importReferenceSource = async (options) => {
         return err(cancelled());
     const exclusions = [];
     const shouldExclude = (path) => {
-        if (isSecretLikePath(path) || secrets.ignores(path)) {
+        if (secrets.ignores(path)) {
             exclusions.push({ path, reason: "configured-secret" });
             return true;
         }