rea-agents 2.2.0 → 2.4.0

package/dist/application/LoopbackReplayRecorder.js

@@ -0,0 +1,101 @@
+import { ReplayMachineRuntime, } from "../domain/replayMachineRuntime.js";
+/** Bounded protocol and replay-machine observations for one process run. */
+export class ReplayRecorder {
+    scenario;
+    recordEvent;
+    events = [];
+    started = Date.now();
+    machine;
+    #machineQueue = Promise.resolve();
+    #machineAdmissionOpen = true;
+    truncated = false;
+    constructor(scenario, recordEvent = () => undefined) {
+        this.scenario = scenario;
+        this.recordEvent = recordEvent;
+        this.machine =
+            scenario.replay.machine === null
+                ? undefined
+                : new ReplayMachineRuntime(scenario.replay.machine);
+    }
+    get transitions() {
+        return this.machine?.timeline ?? [];
+    }
+    atMs() {
+        return (Math.floor((Date.now() - this.started) /
+            this.scenario.normalization.time_bucket_ms) * this.scenario.normalization.time_bucket_ms);
+    }
+    rawAtMs() {
+        return Date.now() - this.started;
+    }
+    enqueueMachine(operation) {
+        if (!this.#machineAdmissionOpen)
+            return Promise.reject(new Error("replay machine is closing"));
+        const result = this.#machineQueue.then(operation);
+        this.#machineQueue = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    stopMachineAdmission() {
+        this.#machineAdmissionOpen = false;
+    }
+    async drainMachine() {
+        await this.#machineQueue;
+    }
+    dispatchMachine(event) {
+        if (this.machine === undefined)
+            throw new Error("replay machine is not configured");
+        return this.machine.dispatch(event);
+    }
+    recordTransition(decision) {
+        if (decision.transition !== null)
+            this.recordEvent("replay_transitions", decision.transition.sequence);
+    }
+    record(event) {
+        if (this.events.length >= this.scenario.limits.protocol_events) {
+            this.truncated = true;
+            return;
+        }
+        const sequence = this.events.length;
+        this.events.push({ sequence, ...event });
+        this.recordEvent("protocol_events", sequence);
+    }
+}
+export const requestHeaders = (request) => Object.fromEntries(Object.entries(request.headers).flatMap(([name, value]) => value === undefined
+    ? []
+    : [[name, Array.isArray(value) ? value.join(", ") : value]]));
+export const readReplayRequestBody = async (request, limit) => {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of request) {
+        const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += value.byteLength;
+        if (bytes > limit)
+            return undefined;
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+};
+export const recordMachineEvent = (recorder, event, decision) => {
+    recorder.record({
+        ...event,
+        data: recorder.machine?.redact(event.data) ?? event.data,
+        outcome: decision.outcome,
+    });
+    recorder.recordTransition(decision);
+};
+export const waitForReplayDelay = (durationMs) => new Promise((resolveDelay) => setTimeout(resolveDelay, durationMs));
+export const listenOnLoopback = async (server) => {
+    await new Promise((resolveListen, rejectListen) => {
+        server.once("error", rejectListen);
+        server.listen(0, "127.0.0.1", () => {
+            server.off("error", rejectListen);
+            resolveListen();
+        });
+    });
+    const address = server.address();
+    if (address === null || typeof address === "string")
+        throw new Error("loopback replay did not acquire a TCP port");
+    return address.port;
+};
+export const closeReplayServer = (server) => new Promise((resolveClose, rejectClose) => {
+    server.close((error) => error === undefined ? resolveClose() : rejectClose(error));
+});

package/dist/application/PermissionAuthority.js

@@ -74,13 +74,15 @@ const errorReason = (error) => isNotFound(error) ? "not_found" : "io";
 export class PermissionAuthority {
     policy;
     configuredAuthority;
-    constructor(policy, configuredAuthority) {
+    outsideCeilingRestartRequired;
+    constructor(policy, configuredAuthority, outsideCeilingRestartRequired = false) {
         this.policy = policy;
         this.configuredAuthority = configuredAuthority;
+        this.outsideCeilingRestartRequired = outsideCeilingRestartRequired;
     }
     /** Create a connection-owned overlay for once and session grants. */
     createConnectionAuthority() {
-        return new PermissionAuthority(createPermissionPolicy([]), this.configuredAuthority ?? this);
+        return new PermissionAuthority(createPermissionPolicy([]), this.configuredAuthority ?? this, true);
     }
     /** Canonicalize and authorize one exact operation before its side effect. */
     async authorize(request, access, options = {}) {
@@ -165,7 +167,9 @@ export class PermissionAuthority {
         const denied = evaluatePermission(effective, request);
         if (denied.allowed)
             return ok({ decision: denied, owner: this });
-        return err(new PermissionRequiredError(request, denied.missing, ceilingFor(effective, request.capability), options.elicitationSupported ?? false, options.restartRequired ?? false));
+        const outsideAdministratorCeiling = denied.reason === "outside_administrator_ceiling";
+        return err(new PermissionRequiredError(request, denied.missing, ceilingFor(effective, request.capability), !outsideAdministratorCeiling && (options.elicitationSupported ?? false), options.restartRequired ??
+            (outsideAdministratorCeiling && this.outsideCeilingRestartRequired)));
     }
     /** Atomically replace optional persisted project grants. */
     async replaceProjectGrants(grants) {

package/dist/application/ProcessCaptureEnvironment.js

@@ -0,0 +1,26 @@
+/** Build the explicitly admitted environment for a captured process. */
+export const makeProcessCaptureEnvironment = (options) => {
+    const { scenario, home, replay, shimReplay, runId } = options;
+    const environment = {
+        ...scenario.environment,
+        HOME: home,
+        TERM: "xterm-256color",
+        REA_PROCESS_RUN_ID: runId,
+    };
+    for (const name of scenario.inherit_environment) {
+        const value = process.env[name];
+        if (value !== undefined)
+            environment[name] = value;
+    }
+    environment.REA_REPLAY_HTTP_URL = replay.httpUrl;
+    environment.REA_REPLAY_WEBSOCKET_URL = replay.websocketUrl;
+    environment.REA_SHIM_LEDGER_URL = shimReplay.url;
+    // PATH is evidence-producing input. Inheriting the host PATH here would let
+    // the authority and reconstruction probe different tools without recording
+    // that difference. Scenarios must opt in through environment or
+    // inherit_environment; deterministic shims always take precedence.
+    environment.PATH = [shimReplay.binPath, environment.PATH ?? ""]
+        .filter((part) => part.length > 0)
+        .join(":");
+    return environment;
+};

package/dist/application/ProcessCaptureJournal.js

@@ -0,0 +1,95 @@
+import { normalizeProcessElapsedTime, normalizeProcessText, } from "./ProcessNormalization.js";
+/** Create one monotonic event journal for a process capture. */
+export const createProcessCaptureJournal = () => {
+    const entries = [];
+    const listeners = new Set();
+    const notifications = [];
+    let delivering = false;
+    const deliverNotifications = () => {
+        if (delivering)
+            return;
+        delivering = true;
+        const failures = [];
+        try {
+            for (;;) {
+                const notification = notifications.shift();
+                if (notification === undefined)
+                    break;
+                for (const listener of Array.from(listeners))
+                    try {
+                        listener(notification);
+                    }
+                    catch (cause) {
+                        failures.push(cause);
+                    }
+            }
+        }
+        finally {
+            delivering = false;
+        }
+        if (failures.length > 0)
+            throw new AggregateError(failures, "process capture journal subscriber failed");
+    };
+    const record = (collection, index) => {
+        const entry = { capture_order: entries.length, collection, index };
+        entries.push(entry);
+        notifications.push(entry);
+        deliverNotifications();
+        return entry;
+    };
+    return {
+        entries,
+        record,
+        recordEvent: (collection, index) => void record(collection, index),
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+};
+/** Schedule scenario interactions and record each observed dispatch atomically. */
+export const scheduleScenarioInteractions = (options) => {
+    const { scenario, getTerminal, timers, interactions, renderer, started } = options;
+    for (const [eventIndex, event] of scenario.events.entries()) {
+        const timer = setTimeout(() => {
+            options.dispatchedEventIndexes.add(eventIndex);
+            const terminal = getTerminal();
+            const dispatchedAt = Math.max(0, Date.now() - started);
+            let outcome = "dispatched";
+            if (terminal === undefined)
+                outcome = "target_exited";
+            else {
+                try {
+                    if (event.type === "input")
+                        terminal.write(event.data);
+                    else if (event.type === "resize") {
+                        terminal.resize(event.columns, event.rows);
+                        renderer.resize(event.columns, event.rows, normalizeProcessElapsedTime(dispatchedAt, scenario.normalization.time_bucket_ms));
+                    }
+                    else
+                        terminal.kill(event.signal);
+                }
+                catch {
+                    outcome = "failed";
+                }
+            }
+            const sequence = interactions.length;
+            interactions.push({
+                sequence,
+                scheduled_at_ms: event.at_ms,
+                dispatched_at_ms: dispatchedAt,
+                type: event.type,
+                data: event.type === "input"
+                    ? event.sensitive
+                        ? `<redacted-input:${String(Buffer.byteLength(event.data))}-bytes>`
+                        : normalizeProcessText(event.data, scenario, "<no-temporary-root>", -1)
+                    : event.type === "resize"
+                        ? `${String(event.columns)}x${String(event.rows)}`
+                        : event.signal,
+                outcome,
+            });
+            options.recordEvent("interaction_events", sequence);
+        }, event.at_ms);
+        timers.add(timer);
+    }
+};

package/dist/application/ProcessCaptureLifecycle.js

@@ -10,7 +10,7 @@ import { cleanupOwnedProcessGroup, observeOwnedProcessGroup, } from "../process/
 import { classifyFilesystemEffects, ProcessCheckpoints, } from "./ProcessCheckpoints.js";
 import { ProcessCaptureError } from "./ProcessCaptureError.js";
 import { assertNotCancelled, assertRealPathAuthority, } from "./ProcessCaptureAuthority.js";
-import { normalizeProcessSamples, normalizeProcessText, redactProtocolEvents, } from "./ProcessNormalization.js";
+import { normalizeProcessElapsedTime, normalizeProcessSamples, normalizeProcessText, redactProtocolEvents, } from "./ProcessNormalization.js";
 import { PROCESS_PROVIDER } from "./ProcessEvidence.js";
 import { TerminalRenderer } from "./TerminalRenderer.js";
 export const buildCaptureResult = (options) => ({
@@ -18,9 +18,7 @@ export const buildCaptureResult = (options) => ({
     manifest: options.manifest,
     normalization: options.scenario.normalization,
     frames: options.frames,
-    rendered_frames: [...options.renderedFrames]
-        .sort((left, right) => left.at_ms - right.at_ms || left.sequence - right.sequence)
-        .map((frame, sequence) => ({ ...frame, sequence })),
+    rendered_frames: options.renderedFrames,
     interaction_events: options.interactions,
     exit: {
         code: options.exit.reason === "exited" && options.exit.exitCode >= 0
@@ -34,6 +32,9 @@ export const buildCaptureResult = (options) => ({
     filesystem_checkpoints: options.checkpoints,
     shim_events: options.shimEvents,
     protocol_events: redactProtocolEvents(options.replay.events, options.scenario),
+    replay_transitions: options.replay.transitions,
+    reactive_run: options.reactiveRun,
+    event_journal: options.eventJournal,
     files_before: options.before.files,
     files_after: options.after.files,
     filesystem_effects: classifyFilesystemEffects(options.before.files, options.after.files),
@@ -91,9 +92,11 @@ export const createRunManifest = async (scenario, startedAt, completedAt) => {
         replay_plan_sha256: digestProcessCommitment(scenario.replay),
     };
 };
-export const observeSettlement = async (runId, processGroupIds, settleMs) => {
-    if (process.platform === "win32")
+export const observeSettlement = async (runId, processGroupIds, settleMs, recordEvent = () => undefined) => {
+    if (process.platform === "win32") {
+        recordEvent("lifecycle", 1);
         return { state: "unverifiable", elapsed_ms: 0 };
+    }
     const started = Date.now();
     let consecutiveEmpty = 0;
     let deadlineReached = false;
@@ -103,12 +106,16 @@ export const observeSettlement = async (runId, processGroupIds, settleMs) => {
             leaderPid: processGroupId,
             processGroupId,
         })));
-        if (observations.some(({ state }) => state === "unverifiable"))
+        if (observations.some(({ state }) => state === "unverifiable")) {
+            recordEvent("lifecycle", 1);
             return { state: "unverifiable", elapsed_ms: Date.now() - started };
+        }
         if (observations.every(({ state }) => state === "empty")) {
             consecutiveEmpty += 1;
-            if (consecutiveEmpty >= 2)
+            if (consecutiveEmpty >= 2) {
+                recordEvent("lifecycle", 1);
                 return { state: "quiesced", elapsed_ms: Date.now() - started };
+            }
         }
         else
             consecutiveEmpty = 0;
@@ -117,19 +124,22 @@ export const observeSettlement = async (runId, processGroupIds, settleMs) => {
             break;
         await new Promise((resolve) => setTimeout(resolve, 50));
     }
+    recordEvent("lifecycle", 1);
     return { state: "alive_at_deadline", elapsed_ms: Date.now() - started };
 };
-export const awaitTerminalExit = async ({ terminal, scenario, started, lastOutput, signal, timers, interactions, dispatchedEventIndexes, }) => new Promise((resolveExit) => {
+export const awaitTerminalExit = async ({ terminal, scenario, started, lastOutput, signal, timers, interactions, dispatchedEventIndexes, recordEvent, }) => new Promise((resolveExit) => {
     // The kill caused by a deadline is observed later as an ordinary PTY exit.
     // Keep the initiating lifecycle reason so comparisons distinguish a target
     // exit from harness-owned timeout, idle-timeout, and cancellation cleanup.
     let reason = "exited";
     terminal.onExit((exit) => {
+        recordEvent("lifecycle", 0);
         for (const [eventIndex, event] of scenario.events.entries()) {
             if (dispatchedEventIndexes.has(eventIndex))
                 continue;
+            const sequence = interactions.length;
             interactions.push({
-                sequence: interactions.length,
+                sequence,
                 scheduled_at_ms: event.at_ms,
                 dispatched_at_ms: Math.max(0, Date.now() - started),
                 type: event.type,
@@ -140,6 +150,7 @@ export const awaitTerminalExit = async ({ terminal, scenario, started, lastOutpu
                         : event.signal,
                 outcome: "target_exited",
             });
+            recordEvent("interaction_events", sequence);
         }
         for (const timer of timers) {
             clearTimeout(timer);
@@ -223,14 +234,15 @@ export const captureTerminalFrames = (options) => {
             return;
         }
         outputBytes += bytes;
-        const atMs = Math.floor((Date.now() - options.started) /
-            options.scenario.normalization.time_bucket_ms) * options.scenario.normalization.time_bucket_ms;
+        const atMs = normalizeProcessElapsedTime(Date.now() - options.started, options.scenario.normalization.time_bucket_ms);
         const normalized = normalizeProcessText(data, options.scenario, options.temporaryRoot, options.terminal.pid);
+        const sequence = options.frames.length;
         options.frames.push({
-            sequence: options.frames.length,
+            sequence,
             at_ms: atMs,
             data: normalized,
         });
+        options.recordEvent("frames", sequence);
         options.renderer.write(data, atMs);
         options.checkpoints.observeTerminal(normalized);
     });

package/dist/application/ProcessCheckpoints.js

@@ -22,17 +22,19 @@ export const classifyFilesystemEffects = (before, after) => {
 export class ProcessCheckpoints {
     scenario;
     started;
-    signal;
     #captures = [];
     #captured = new Set();
     #terminalCounts = new Map();
     #terminalTails = new Map();
     #timers = new Set();
+    #signal;
+    #recordEvent;
     #pending = Promise.resolve();
-    constructor(scenario, started, before, signal) {
+    constructor(scenario, started, before, options = { signal: undefined }) {
         this.scenario = scenario;
         this.started = started;
-        this.signal = signal;
+        this.#signal = options.signal;
+        this.#recordEvent = options.recordEvent ?? (() => undefined);
         this.#captures.push({
             name: "before",
             at_ms: 0,
@@ -40,6 +42,7 @@ export class ProcessCheckpoints {
             effects: [],
             truncated: before.truncated,
         });
+        this.#recordEvent("filesystem_checkpoints", 0);
         this.#captured.add("before");
         for (const checkpoint of scenario.checkpoints) {
             if (checkpoint.trigger.type !== "time")
@@ -74,6 +77,14 @@ export class ProcessCheckpoints {
     }
     /** Queue one idempotent named snapshot. */
     capture(name) {
+        this.#scheduleCapture(name, this.#signal);
+    }
+    /** Read one committed checkpoint for synchronous journal projection. */
+    at(index) {
+        const checkpoint = this.#captures[index];
+        return checkpoint === undefined ? undefined : structuredClone(checkpoint);
+    }
+    #scheduleCapture(name, signal) {
         if (this.#captured.has(name))
             return;
         this.#captured.add(name);
@@ -81,8 +92,9 @@ export class ProcessCheckpoints {
         // together. Each effect set is intentionally relative to the immediately
         // preceding checkpoint, which preserves transient create/delete behavior.
         this.#pending = this.#pending.then(async () => {
-            const snapshot = await snapshotRoots(this.scenario, this.signal);
+            const snapshot = await snapshotRoots(this.scenario, signal);
             const previous = this.#captures.at(-1)?.files ?? [];
+            const index = this.#captures.length;
             this.#captures.push({
                 name,
                 at_ms: Math.max(0, Date.now() - this.started),
@@ -90,14 +102,32 @@ export class ProcessCheckpoints {
                 effects: classifyFilesystemEffects(previous, snapshot.files),
                 truncated: snapshot.truncated,
             });
+            this.#recordEvent("filesystem_checkpoints", index);
         });
     }
+    /** Queue one named snapshot and return its exact captured record. */
+    async captureAndRead(name, signal) {
+        const captureSignal = signal === undefined
+            ? this.#signal
+            : this.#signal === undefined
+                ? signal
+                : AbortSignal.any([this.#signal, signal]);
+        this.#scheduleCapture(name, captureSignal);
+        const scheduled = this.#pending;
+        await scheduled;
+        const index = this.#captures.findIndex(({ name: capturedName }) => capturedName === name);
+        const checkpoint = this.#captures[index];
+        if (index < 0 || checkpoint === undefined)
+            throw new Error(`filesystem checkpoint was not captured: ${name}`);
+        return { index, checkpoint: structuredClone(checkpoint) };
+    }
     /** Finish pending snapshots and return them in observation order. */
     async finish(after) {
         for (const timer of this.#timers)
             clearTimeout(timer);
         await this.#pending;
         const previous = this.#captures.at(-1)?.files ?? [];
+        const index = this.#captures.length;
         this.#captures.push({
             name: "after_settlement",
             at_ms: Math.max(0, Date.now() - this.started),
@@ -105,6 +135,7 @@ export class ProcessCheckpoints {
             effects: classifyFilesystemEffects(previous, after.files),
             truncated: after.truncated,
         });
+        this.#recordEvent("filesystem_checkpoints", index);
         return structuredClone(this.#captures);
     }
     /** Cancel scheduled captures and await any snapshot already in progress. */

package/dist/application/ProcessCli.js

@@ -1,8 +1,10 @@
 import { readFile } from "node:fs/promises";
 import { parseConfig } from "../config.js";
-import { AnalysisError, AnalysisProtocolError, PermissionRequiredError, projectAnalysisError, } from "../domain/errors.js";
+import { AnalysisError, AnalysisInputError, AnalysisProtocolError, PermissionRequiredError, projectAnalysisError, } from "../domain/errors.js";
 import { createEvidence, parseEvidence } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
+import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { processTraceSpecificationSchema } from "../domain/processTraceComparison.js";
 import { compareProcessCaptures, LEGACY_PROCESS_CAPTURE_MESSAGE, parseProcessScenario, parseProcessCapture, } from "../domain/processCapture.js";
 import { captureProcessScenario } from "./ProcessHarness.js";
 import { processCapturePermissionRequest } from "./ProcessCapturePermission.js";
@@ -43,24 +45,37 @@ export const captureProcessScenarioFile = async (path) => {
     }
 };
 /** Compare two capture Evidence files and emit derived comparison Evidence. */
-export const compareProcessEvidenceFiles = async (leftPath, rightPath) => {
+export const compareProcessEvidenceFiles = async (leftPath, rightPath, traceSpecPath) => {
     try {
         const left = parseCaptureEvidence(await readJson(leftPath));
         const right = parseCaptureEvidence(await readJson(rightPath));
-        const comparison = compareProcessCaptures(left.capture, right.capture);
+        const traceSpecification = traceSpecPath === undefined
+            ? undefined
+            : parseTraceSpecification(await readJson(traceSpecPath));
+        const comparison = traceSpecification === undefined
+            ? compareProcessCaptures(left.capture, right.capture)
+            : compareProcessCaptures(left.capture, right.capture, {
+                traceSpecification,
+            });
         return createEvidence(undefined, PROCESS_PROVIDER, {
-            predicateType: "rea.process-comparison/v3",
+            predicateType: traceSpecification === undefined
+                ? "rea.process-comparison/v3"
+                : "rea.process-comparison/v4",
             operation: "compare_process_captures",
             parameters: {
                 left_evidence_id: left.id,
                 right_evidence_id: right.id,
                 left_normalization: left.capture.normalization,
                 right_normalization: right.capture.normalization,
+                ...(traceSpecification === undefined
+                    ? {}
+                    : { trace_spec: jsonValueSchema.parse(traceSpecification) }),
             },
             result: jsonValueSchema.parse(comparison),
             confidence: "derived",
             authority: "analyst-inference",
             limitations: comparison.limitations,
+            locations: [...left.locations, ...right.locations],
             evidenceLinks: [left.id, right.id],
         });
     }
@@ -88,12 +103,19 @@ const parseCaptureEvidence = (input) => {
         return {
             id: evidence.evidence_id,
             capture: parseProcessCapture(evidence.normalized_result),
+            locations: evidence.locations,
         };
     }
     catch {
         throw invalidCaptureEvidence();
     }
 };
+const parseTraceSpecification = (input) => {
+    const parsed = processTraceSpecificationSchema.safeParse(input);
+    if (parsed.success)
+        return parsed.data;
+    throw new AnalysisInputError("compare-process-captures", { cause: parsed.error }, projectInputIssues(parsed.error.issues, input));
+};
 const invalidCaptureEvidence = () => new ProcessCliFailure("invalid_input", "Capture evidence is malformed. Create new capture evidence, then try again.");
 const readJson = async (path) => {
     let bytes;