rea-agents 0.2.1

package/dist/application/EvidenceLedger.js

@@ -0,0 +1,65 @@
+import { createEvidenceBundle, evidenceBundleSchema, } from "../domain/evidenceBundle.js";
+import { parseEvidence } from "../domain/evidence.js";
+/** Bounded, session-owned set of immutable evidence records. */
+export class EvidenceLedger {
+    limits;
+    #records = new Map();
+    constructor(limits) {
+        this.limits = limits;
+        if (!Number.isSafeInteger(limits.maxRecords) || limits.maxRecords < 1)
+            throw new RangeError("maxRecords must be a positive safe integer");
+    }
+    /** Record evidence idempotently; conflicting content is rejected. */
+    record(input) {
+        const evidence = parseEvidence(input);
+        const existing = this.#records.get(evidence.evidence_id);
+        if (existing !== undefined) {
+            if (!recordsAgree(existing, evidence))
+                throw new Error(`Conflicting evidence record: ${evidence.evidence_id}`);
+            return "duplicate";
+        }
+        if (this.#records.size >= this.limits.maxRecords)
+            throw new RangeError("Evidence ledger record limit exceeded");
+        this.#records.set(evidence.evidence_id, evidence);
+        return "added";
+    }
+    /** Validate an entire bundle before atomically merging its records. */
+    import(input) {
+        const bundle = evidenceBundleSchema.parse(input);
+        const pending = new Map(this.#records);
+        for (const unparsed of bundle.records) {
+            const evidence = parseEvidence(unparsed);
+            const existing = pending.get(evidence.evidence_id);
+            if (existing !== undefined && !recordsAgree(existing, evidence))
+                throw new Error(`Conflicting evidence record: ${evidence.evidence_id}`);
+            pending.set(evidence.evidence_id, evidence);
+        }
+        if (pending.size > this.limits.maxRecords)
+            throw new RangeError("Evidence ledger record limit exceeded");
+        const added = pending.size - this.#records.size;
+        this.#records.clear();
+        for (const [id, evidence] of pending)
+            this.#records.set(id, evidence);
+        return added;
+    }
+    /** Export records in deterministic, semantically irrelevant ID order. */
+    export() {
+        return createEvidenceBundle([...this.#records.values()]);
+    }
+    /** Clear records when the owning session closes. */
+    clear() {
+        this.#records.clear();
+    }
+}
+const recordsAgree = (left, right) => JSON.stringify(withoutLocalPath(left)) ===
+    JSON.stringify(withoutLocalPath(right));
+const withoutLocalPath = (evidence) => ({
+    ...evidence,
+    subject: evidence.subject === null
+        ? null
+        : {
+            ...evidence.subject,
+            name: "<non-identity-name>",
+            local_path: "<non-identity-local-path>",
+        },
+});

package/dist/application/HopperToolPort.js

@@ -0,0 +1 @@
+export {};

package/dist/application/LoopbackReplay.js

@@ -0,0 +1,84 @@
+import { createServer } from "node:http";
+import { WebSocketServer } from "ws";
+const closeServer = async (server) => new Promise((resolveClose, rejectClose) => {
+    server.close((error) => error === undefined ? resolveClose() : rejectClose(error));
+});
+/** Start bounded HTTP and WebSocket replay endpoints bound only to IPv4 loopback. */
+export const startLoopbackReplay = async (scenario) => {
+    const events = [];
+    const record = (event) => {
+        if (events.length < 10_000)
+            events.push({ sequence: events.length, ...event });
+    };
+    const server = createServer((request, response) => {
+        const method = request.method ?? "GET";
+        const path = new URL(request.url ?? "/", "http://127.0.0.1").pathname;
+        record({ protocol: "http", direction: "request", method, path, data: "" });
+        const route = scenario.replay.http.find((candidate) => candidate.method === method && candidate.path === path);
+        response.statusCode = route?.status ?? 404;
+        const body = route?.body ?? "";
+        response.end(body);
+        record({
+            protocol: "http",
+            direction: "response",
+            method,
+            path,
+            data: body,
+        });
+    });
+    const websocket = new WebSocketServer({
+        noServer: true,
+        maxPayload: 1_000_000,
+        clientTracking: true,
+    });
+    server.on("upgrade", (request, socket, head) => {
+        if (new URL(request.url ?? "/", "http://127.0.0.1").pathname !== "/ws") {
+            socket.destroy();
+            return;
+        }
+        websocket.handleUpgrade(request, socket, head, (client) => websocket.emit("connection", client, request));
+    });
+    websocket.on("connection", (client) => {
+        client.on("error", () => undefined);
+        client.on("message", (value) => record({
+            protocol: "websocket",
+            direction: "received",
+            method: null,
+            path: "/ws",
+            data: value.toString(),
+        }));
+        for (const message of scenario.replay.websocket_messages) {
+            client.send(message);
+            record({
+                protocol: "websocket",
+                direction: "sent",
+                method: null,
+                path: "/ws",
+                data: message,
+            });
+        }
+    });
+    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") {
+        await closeServer(server);
+        throw new Error("loopback replay did not acquire a TCP port");
+    }
+    return {
+        httpUrl: `http://127.0.0.1:${String(address.port)}`,
+        websocketUrl: `ws://127.0.0.1:${String(address.port)}/ws`,
+        events,
+        async close() {
+            for (const client of websocket.clients)
+                client.terminate();
+            await new Promise((resolveClose) => websocket.close(() => resolveClose()));
+            await closeServer(server);
+        },
+    };
+};

package/dist/application/ProcessHarness.js

@@ -0,0 +1,347 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdtemp, readdir, readFile, readlink, realpath, rm, } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, relative } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { spawn } from "node-pty";
+import { authorizeProcessScenario } from "../domain/processCapture.js";
+import { err, ok } from "../domain/result.js";
+import { AnalysisError } from "../domain/errors.js";
+import { startLoopbackReplay } from "./LoopbackReplay.js";
+const execFileAsync = promisify(execFile);
+const isWithin = (candidate, root) => candidate === root ||
+    candidate.startsWith(`${root.endsWith("/") ? root.slice(0, -1) : root}/`);
+const assertRealPathAuthority = async (scenario, policy) => {
+    const executable = await realpath(scenario.executable);
+    const executableRoots = await Promise.all(policy.executableRoots.map((root) => realpath(root)));
+    if (!executableRoots.some((root) => isWithin(executable, root)))
+        throw new ProcessCaptureError("resolved executable is outside approved roots");
+    const workingDirectory = await realpath(scenario.working_directory);
+    const workingRoots = await Promise.all(policy.workingRoots.map((root) => realpath(root)));
+    if (!workingRoots.some((root) => isWithin(workingDirectory, root)))
+        throw new ProcessCaptureError("resolved working directory is outside approved roots");
+    for (const root of scenario.filesystem_roots) {
+        const resolvedRoot = await realpath(root);
+        if (!workingRoots.some((approved) => isWithin(resolvedRoot, approved)))
+            throw new ProcessCaptureError("resolved filesystem root is outside approved roots");
+    }
+};
+/** Expected refusal or runtime failure from the process capture adapter. */
+export class ProcessCaptureError extends AnalysisError {
+    _tag = "ProcessCaptureError";
+}
+/** Probe the actual native PTY seam instead of inferring support from the OS name. */
+export const probeProcessCaptureCapability = async () => {
+    try {
+        const terminal = spawn(process.platform === "win32" ? "cmd.exe" : "/bin/sh", process.platform === "win32" ? ["/c", "exit", "0"] : ["-c", "exit 0"], {
+            cwd: tmpdir(),
+            env: { HOME: tmpdir(), TERM: "xterm-256color" },
+            cols: 80,
+            rows: 24,
+            name: "xterm-256color",
+        });
+        await new Promise((resolveExit) => terminal.onExit(() => resolveExit()));
+        return { available: true, backend: "node-pty" };
+    }
+    catch {
+        return {
+            available: false,
+            backend: "node-pty",
+            reason: "the native PTY backend could not start a probe process",
+        };
+    }
+};
+const hashFile = async (path, maxBytes) => {
+    const value = await readFile(path);
+    if (value.byteLength > maxBytes)
+        return null;
+    return createHash("sha256").update(value).digest("hex");
+};
+const snapshotRoots = async (scenario) => {
+    const entries = [];
+    let remainingBytes = scenario.limits.file_bytes;
+    let truncated = false;
+    const visit = async (root, path) => {
+        if (entries.length >= scenario.limits.files) {
+            truncated = true;
+            return;
+        }
+        let stats;
+        try {
+            stats = await lstat(path);
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                return;
+            throw error;
+        }
+        const relativePath = relative(root, path) || ".";
+        if (stats.isSymbolicLink()) {
+            entries.push({
+                path: `${root}:${relativePath}`,
+                type: "symlink",
+                mode: stats.mode,
+                size: stats.size,
+                sha256: null,
+                symlink_target: await readlink(path),
+            });
+            return;
+        }
+        if (stats.isFile()) {
+            const allowedBytes = Math.max(0, Math.min(remainingBytes, scenario.limits.file_bytes));
+            const sha256 = allowedBytes >= stats.size ? await hashFile(path, allowedBytes) : null;
+            remainingBytes -= sha256 === null ? 0 : stats.size;
+            if (sha256 === null)
+                truncated = true;
+            entries.push({
+                path: `${root}:${relativePath}`,
+                type: "file",
+                mode: stats.mode,
+                size: stats.size,
+                sha256,
+                symlink_target: null,
+            });
+            return;
+        }
+        const type = stats.isDirectory() ? "directory" : "other";
+        entries.push({
+            path: `${root}:${relativePath}`,
+            type,
+            mode: stats.mode,
+            size: stats.size,
+            sha256: null,
+            symlink_target: null,
+        });
+        if (type !== "directory")
+            return;
+        for (const child of (await readdir(path)).sort())
+            await visit(root, join(path, child));
+    };
+    for (const root of scenario.filesystem_roots)
+        await visit(root, root);
+    return { files: entries, truncated };
+};
+const sampleProcesses = async (rootPid, elapsedMs, limit) => {
+    if (process.platform === "win32")
+        return [];
+    const { stdout } = await execFileAsync("ps", ["-axo", "pid=,ppid=,command="]);
+    const rows = stdout
+        .split("\n")
+        .map((line) => /\s*(\d+)\s+(\d+)\s+(.*)/.exec(line))
+        .filter((match) => match !== null)
+        .map((match) => ({
+        pid: Number(match[1]),
+        parent_pid: Number(match[2]),
+        command: match[3] ?? "",
+    }));
+    const owned = new Set([rootPid]);
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const row of rows) {
+            if (owned.has(row.parent_pid) && !owned.has(row.pid)) {
+                owned.add(row.pid);
+                changed = true;
+            }
+        }
+    }
+    return rows
+        .filter((row) => owned.has(row.pid))
+        .slice(0, limit)
+        .map((row) => ({ at_ms: elapsedMs, ...row }));
+};
+const makeEnvironment = (scenario, home, replay) => {
+    const environment = {
+        HOME: home,
+        TERM: "xterm-256color",
+        ...scenario.environment,
+    };
+    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;
+    return environment;
+};
+const normalizeTerminalData = (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>");
+    if (scenario.normalization.pids)
+        normalized = normalized.replaceAll(String(pid), "<pid>");
+    if (scenario.normalization.ports)
+        normalized = normalized.replaceAll(/(?<=[:=])\d{2,5}\b/g, "<port>");
+    for (const pattern of scenario.normalization.patterns)
+        normalized = normalized.replaceAll(pattern.pattern, pattern.replacement);
+    return normalized;
+};
+const scheduleScenarioEvents = (scenario, getTerminal, timers) => {
+    for (const event of scenario.events) {
+        const timer = setTimeout(() => {
+            const terminal = getTerminal();
+            if (event.type === "input")
+                terminal?.write(event.data);
+            else if (event.type === "resize")
+                terminal?.resize(event.columns, event.rows);
+            else
+                terminal?.kill(event.signal);
+        }, event.at_ms);
+        timers.add(timer);
+    }
+};
+const normalizeSamples = (samples, scenario, rootPid) => {
+    const identifiers = [
+        rootPid,
+        ...samples.flatMap((sample) => [sample.pid, sample.parent_pid]),
+    ];
+    const mapping = new Map();
+    for (const identifier of identifiers)
+        if (identifier > 0 && !mapping.has(identifier))
+            mapping.set(identifier, mapping.size + 1);
+    return samples.map((sample) => ({
+        at_ms: Math.floor(sample.at_ms / scenario.normalization.time_bucket_ms) *
+            scenario.normalization.time_bucket_ms,
+        pid: mapping.get(sample.pid) ?? 1,
+        parent_pid: mapping.get(sample.parent_pid) ?? 0,
+        command: normalizeTerminalData(sample.command, scenario, "<no-temporary-root>", rootPid),
+    }));
+};
+const redactProtocolEvents = (events, scenario) => events.map((event) => ({
+    ...event,
+    data: normalizeTerminalData(event.data, scenario, "<no-temporary-root>", -1),
+}));
+const buildCaptureResult = (options) => ({
+    schema_version: 1,
+    frames: options.frames,
+    exit: {
+        code: options.exit.exitCode < 0 ? null : options.exit.exitCode,
+        signal: options.exit.signal ?? null,
+    },
+    process_samples: normalizeSamples(options.samples, options.scenario, options.rootPid),
+    protocol_events: redactProtocolEvents(options.replay.events, options.scenario),
+    files_before: options.before.files,
+    files_after: options.after.files,
+    truncated: options.truncated,
+    limitations: [
+        "Process trees are sampled and may omit short-lived descendants.",
+        "Filesystem observations are before/after snapshots, not syscall traces.",
+        "The harness does not enforce external network isolation.",
+    ],
+});
+const awaitTerminalExit = async ({ terminal, scenario, started, lastOutput, signal, timers, }) => new Promise((resolveExit) => {
+    terminal.onExit(resolveExit);
+    const timeout = setInterval(() => {
+        if (Date.now() - started >= scenario.timeout_ms ||
+            Date.now() - lastOutput() >= scenario.idle_timeout_ms ||
+            signal?.aborted === true) {
+            terminal.kill("SIGKILL");
+        }
+    }, 20);
+    timers.add(timeout);
+});
+/** Execute one authorized scenario and return bounded observations. */
+const runProcessScenario = async (scenario, policy, signal) => {
+    const decision = authorizeProcessScenario(scenario, policy);
+    if (!decision.allowed)
+        throw new ProcessCaptureError(decision.reason);
+    await assertRealPathAuthority(scenario, policy);
+    if (signal?.aborted === true)
+        throw new ProcessCaptureError("process capture was cancelled");
+    const temporaryRoot = await mkdtemp(join(tmpdir(), "rea-process-"));
+    const home = join(temporaryRoot, "home");
+    await import("node:fs/promises").then(({ mkdir }) => mkdir(home));
+    const before = await snapshotRoots(scenario);
+    const frames = [];
+    const samples = [];
+    let outputBytes = 0;
+    let truncated = before.truncated;
+    let terminal;
+    let replay;
+    const started = Date.now();
+    let lastOutput = started;
+    const timers = new Set();
+    try {
+        replay = await startLoopbackReplay(scenario);
+        terminal = spawn(scenario.executable, [...scenario.arguments], {
+            cwd: scenario.working_directory,
+            env: makeEnvironment(scenario, home, replay),
+            cols: 80,
+            rows: 24,
+            name: "xterm-256color",
+        });
+        terminal.onData((data) => {
+            lastOutput = Date.now();
+            const bytes = Buffer.byteLength(data);
+            if (frames.length >= scenario.limits.frames ||
+                outputBytes + bytes > scenario.limits.output_bytes) {
+                truncated = true;
+                return;
+            }
+            outputBytes += bytes;
+            frames.push({
+                sequence: frames.length,
+                at_ms: Math.floor((Date.now() - started) / scenario.normalization.time_bucket_ms) * scenario.normalization.time_bucket_ms,
+                data: normalizeTerminalData(data, scenario, temporaryRoot, terminal?.pid ?? -1),
+            });
+        });
+        scheduleScenarioEvents(scenario, () => terminal, timers);
+        const sampler = setInterval(() => {
+            void sampleProcesses(terminal?.pid ?? -1, Date.now() - started, scenario.limits.processes - samples.length)
+                .then((values) => samples.push(...values))
+                .catch(() => undefined);
+        }, 50);
+        timers.add(sampler);
+        const exit = await awaitTerminalExit({
+            terminal,
+            scenario,
+            started,
+            lastOutput: () => lastOutput,
+            signal,
+            timers,
+        });
+        await new Promise((resolveSettle) => setTimeout(resolveSettle, scenario.settle_ms));
+        const after = await snapshotRoots(scenario);
+        truncated ||=
+            after.truncated || samples.length >= scenario.limits.processes;
+        return buildCaptureResult({
+            frames,
+            exit,
+            samples,
+            replay,
+            before,
+            after,
+            truncated,
+            scenario,
+            rootPid: terminal.pid,
+        });
+    }
+    catch (cause) {
+        terminal?.kill("SIGKILL");
+        throw new ProcessCaptureError("process capture failed", { cause });
+    }
+    finally {
+        for (const timer of timers)
+            clearTimeout(timer);
+        await replay?.close();
+        await rm(temporaryRoot, { recursive: true, force: true });
+    }
+};
+/** Execute one scenario through a typed expected-failure channel. */
+export const captureProcessScenario = async (scenario, policy, signal) => {
+    try {
+        return ok(await runProcessScenario(scenario, policy, signal));
+    }
+    catch (cause) {
+        return err(cause instanceof ProcessCaptureError
+            ? cause
+            : new ProcessCaptureError("process capture failed", { cause }));
+    }
+};