rea-agents 5.0.0 → 6.0.0

package/dist/application/ProcessCaptureLifecycle.js

@@ -1,299 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-import { createReadStream } from "node:fs";
-import { mkdtemp, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { digestProcessCommitment, processComparisonContract, processScenarioCommitment, } from "../domain/processCapture.js";
-import { PRODUCT_IDENTITY } from "../identity.js";
-import { snapshotRoots } from "./FilesystemSnapshot.js";
-import { classifyFilesystemEffects } from "./ProcessFilesystemEffects.js";
-import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js";
-import { observeOwnedProcessGroup } from "../process/ProcessOwnershipObservation.js";
-import { ProcessCaptureError } from "./ProcessCaptureError.js";
-import { assertNotCancelled } from "./ProcessScenarioRuntimeValidation.js";
-import { normalizeProcessElapsedTime, normalizeProcessSamples, normalizeProcessText, } from "./ProcessNormalization.js";
-import { PROCESS_PROVIDER } from "./ProcessEvidence.js";
-import { TerminalRenderer } from "./TerminalRenderer.js";
-import { scheduleProcessInterval } from "./ProcessTimer.js";
-/** Wait for trailing PTY callbacks before the capture becomes immutable. */
-export const settleProcessCaptureJournal = 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;
-    }
-};
-export const buildCaptureResult = (options) => {
-    const hasSensitiveScriptedInput = options.scenario.events.some((event) => event.type === "input" && event.sensitive);
-    const sensitiveInputUnknown = "Sensitive scripted input values are redacted from process capture Evidence.";
-    const filesystemObservationUnknown = "No filesystem observation paths were selected; filesystem effects remain unknown.";
-    const hasFilesystemObservations = options.scenario.filesystem_observation_paths.length > 0;
-    return {
-        manifest: options.manifest,
-        normalization: options.scenario.normalization,
-        frames: options.frames,
-        rendered_frames: options.renderedFrames,
-        interaction_events: options.interactions,
-        exit: {
-            code: options.exit.reason === "exited" && options.exit.exitCode >= 0
-                ? options.exit.exitCode
-                : null,
-            signal: options.exit.signal ?? null,
-            reason: options.exit.reason,
-        },
-        settlement: options.settlement,
-        process_samples: normalizeProcessSamples(options.samples, options.scenario, options.rootPid),
-        filesystem_checkpoints: options.checkpoints,
-        event_journal: options.eventJournal,
-        files_before: options.before.files,
-        files_after: options.after.files,
-        filesystem_effects: classifyFilesystemEffects(options.before.files, options.after.files),
-        truncated: options.truncated,
-        limitations: [
-            "Process trees are sampled and may omit short-lived descendants.",
-            ...(options.samplingPartial
-                ? ["Process-tree sampling ended with an incomplete observation."]
-                : []),
-            "Filesystem observations are before/after snapshots, not syscall traces.",
-            "Inherited host environment variables are not recorded and may affect results.",
-            ...(!hasFilesystemObservations ? [filesystemObservationUnknown] : []),
-            ...(hasSensitiveScriptedInput ? [sensitiveInputUnknown] : []),
-        ],
-        residual_unknowns: [
-            {
-                scope: "process",
-                reason: "Process trees are sampled and may omit short-lived descendants.",
-            },
-            {
-                scope: "environment",
-                reason: "Inherited host environment variables are not recorded.",
-            },
-            {
-                scope: "network",
-                reason: "Network activity is not observed by this capture.",
-            },
-            ...(!hasFilesystemObservations
-                ? [
-                    {
-                        scope: "filesystem",
-                        reason: filesystemObservationUnknown,
-                    },
-                ]
-                : []),
-            ...(hasSensitiveScriptedInput
-                ? [{ scope: "interaction", reason: sensitiveInputUnknown }]
-                : []),
-        ],
-    };
-};
-const hashFile = async (path) => {
-    const hash = createHash("sha256");
-    for await (const chunk of createReadStream(path))
-        hash.update(chunk);
-    return hash.digest("hex");
-};
-export const createRunManifest = async (scenario, startedAt, completedAt, host = {
-    platform: process.platform,
-    architecture: process.arch,
-}) => {
-    const executableSha256 = await hashFile(scenario.executable);
-    const scenarioCommitment = processScenarioCommitment(scenario, executableSha256);
-    const comparisonContract = processComparisonContract(scenario);
-    return {
-        rea_version: PRODUCT_IDENTITY.packageVersion,
-        provider_version: PROCESS_PROVIDER.version,
-        platform: host.platform,
-        architecture: host.architecture,
-        pty_backend: "node-pty",
-        started_at: startedAt.toISOString(),
-        completed_at: completedAt.toISOString(),
-        scenario: scenarioCommitment,
-        comparison_contract: comparisonContract,
-        full_scenario_sha256: digestProcessCommitment(scenarioCommitment),
-        comparison_contract_sha256: digestProcessCommitment(comparisonContract),
-        executable_sha256: executableSha256,
-        normalization_sha256: digestProcessCommitment(scenario.normalization),
-    };
-};
-export const observeSettlement = async (runId, processGroupIds, settleMs, recordEvent = () => undefined, platform = process.platform) => {
-    if (platform === "win32") {
-        recordEvent("lifecycle", 1);
-        return { state: "unverifiable", elapsed_ms: 0 };
-    }
-    const started = Date.now();
-    let consecutiveEmpty = 0;
-    let deadlineReached = false;
-    while (!deadlineReached) {
-        const observations = await Promise.all([...new Set(processGroupIds)].map((processGroupId) => observeOwnedProcessGroup({
-            runId,
-            leaderPid: processGroupId,
-            processGroupId,
-        })));
-        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) {
-                recordEvent("lifecycle", 1);
-                return { state: "quiesced", elapsed_ms: Date.now() - started };
-            }
-        }
-        else
-            consecutiveEmpty = 0;
-        deadlineReached = Date.now() - started >= settleMs;
-        if (deadlineReached)
-            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, 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,
-                scheduled_at_ms: event.at_ms,
-                dispatched_at_ms: Math.max(0, Date.now() - started),
-                type: event.type,
-                data: event.type === "input"
-                    ? "<not-dispatched>"
-                    : event.type === "resize"
-                        ? `${String(event.columns)}x${String(event.rows)}`
-                        : event.signal,
-                outcome: "target_exited",
-            });
-            recordEvent("interaction_events", sequence);
-        }
-        for (const timer of timers) {
-            timer.cancel();
-        }
-        timers.clear();
-        resolveExit({ ...exit, reason });
-    });
-    const timeout = scheduleProcessInterval(() => {
-        if (signal?.aborted === true) {
-            reason = "cancelled";
-            terminal.kill("SIGKILL");
-        }
-        else if (Date.now() - started >= scenario.timeout_ms) {
-            reason = "timeout";
-            terminal.kill("SIGKILL");
-        }
-        else if (Date.now() - lastOutput() >= scenario.idle_timeout_ms) {
-            reason = "idle_timeout";
-            terminal.kill("SIGKILL");
-        }
-    }, 20);
-    timers.add(timeout);
-});
-const processCaptureCleanupHost = {
-    platform: process.platform,
-    cleanupProcessGroup: cleanupOwnedProcessGroup,
-    removeTemporaryRoot: (path) => rm(path, { recursive: true, force: true }),
-};
-export const releaseProcessResources = async (options) => {
-    const host = options.host ?? processCaptureCleanupHost;
-    for (const timer of options.timers)
-        timer.cancel();
-    let failure;
-    try {
-        await options.renderer?.dispose();
-    }
-    catch (cause) {
-        void cause;
-        failure ??= "terminal renderer cleanup failed";
-    }
-    if (options.terminal !== undefined && host.platform !== "win32") {
-        for (const processGroupId of new Set(options.capturedProcessGroupIds)) {
-            const cleaned = await host.cleanupProcessGroup({
-                runId: options.runId,
-                leaderPid: processGroupId,
-                processGroupId,
-            });
-            if (!cleaned.cleaned)
-                failure ??= cleaned.reason;
-        }
-    }
-    try {
-        await host.removeTemporaryRoot(options.temporaryRoot);
-    }
-    catch (cause) {
-        void cause;
-        failure ??= "temporary process root cleanup failed";
-    }
-    return failure;
-};
-export const captureTerminalFrames = (options) => {
-    let outputBytes = 0;
-    let truncated = false;
-    options.terminal.onData((data) => {
-        options.onOutput();
-        const bytes = Buffer.byteLength(data);
-        if (outputBytes + bytes > options.scenario.limits.output_bytes) {
-            truncated = true;
-            return;
-        }
-        outputBytes += bytes;
-        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,
-            at_ms: atMs,
-            data: normalized,
-        });
-        options.renderer.write(data, atMs);
-        options.recordEvent("frames", sequence);
-    });
-    return () => truncated;
-};
-export const resolveProcessResult = (capture, executionFailure, cleanupFailure) => {
-    if (executionFailure instanceof ProcessCaptureError)
-        throw executionFailure;
-    if (executionFailure !== undefined)
-        throw new ProcessCaptureError("process capture failed", {
-            cause: executionFailure,
-        });
-    if (cleanupFailure !== undefined)
-        throw new ProcessCaptureError(cleanupFailure, {
-            reason: "cleanup_incomplete",
-        });
-    if (capture === undefined)
-        throw new ProcessCaptureError("process capture produced no result");
-    return capture;
-};
-export const prepareProcessCapture = async (scenario, signal, captureSnapshot = snapshotRoots, host = systemProcessPreparationHost) => {
-    assertNotCancelled(signal);
-    const before = await captureSnapshot(scenario, signal);
-    const temporaryRoot = await host.createTemporaryRoot();
-    try {
-        const runId = randomUUID();
-        return { temporaryRoot, runId, before };
-    }
-    catch (cause) {
-        await host.cleanup(temporaryRoot);
-        throw cause;
-    }
-};
-const systemProcessPreparationHost = {
-    createTemporaryRoot: () => mkdtemp(join(tmpdir(), "rea-process-")),
-    cleanup: (path) => rm(path, { recursive: true, force: true }),
-};

package/dist/application/StoreFileLock.js

@@ -1,124 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { lstat, mkdtemp, open, readdir, rename, rm, rmdir, unlink, } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";
-class StoreFileLockOccupied extends Error {
-    code = "EEXIST";
-    constructor(cause) {
-        super("Store transaction lock is occupied", { cause });
-    }
-}
-/** Atomically publish a populated directory so another owner cannot replace a live lock. */
-export const createStoreFileLock = async (path) => {
-    if (await exists(path))
-        throw new StoreFileLockOccupied();
-    const staged = await mkdtemp(join(dirname(path), ".rea-store-lock-"));
-    const owner = `owner-${randomUUID()}`;
-    try {
-        const handle = await open(join(staged, owner), "wx", 0o600);
-        try {
-            await handle.writeFile(`${String(process.pid)}\n`, "utf8");
-            await handle.sync();
-        }
-        finally {
-            await handle.close();
-        }
-        try {
-            // Rename cannot replace a nonempty directory: the owner entry is present before publication.
-            await rename(staged, path);
-        }
-        catch (cause) {
-            if (await exists(path))
-                throw new StoreFileLockOccupied(cause);
-            throw cause;
-        }
-        return {
-            release: async () => {
-                await removeOwner(path, owner).catch((cause) => {
-                    // best-effort cleanup: lock release must not reject unhandled.
-                    void cause;
-                });
-            },
-        };
-    }
-    finally {
-        await rm(staged, { recursive: true, force: true });
-    }
-};
-/** Recover a dead owner's directory lock or a legacy PID file; leave live and unknown owners intact. */
-export const removeStaleStoreFileLock = async (path) => {
-    try {
-        const stats = await lstat(path);
-        if (stats.isFile()) {
-            if (!(await ownerIsDead(path)))
-                return false;
-            await unlink(path);
-            return true;
-        }
-        if (!stats.isDirectory())
-            return false;
-        const entries = await readdir(path);
-        if (entries.length === 0) {
-            await rmdir(path);
-            return true;
-        }
-        const owner = entries[0];
-        if (entries.length !== 1 ||
-            owner === undefined ||
-            !/^owner-[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/u.test(owner) ||
-            !(await ownerIsDead(join(path, owner))))
-            return false;
-        await removeOwner(path, owner);
-        return true;
-    }
-    catch (cause) {
-        // best-effort cleanup: stale lock probing; failure means the lock stands.
-        void cause;
-        return false;
-    }
-};
-const removeOwner = async (path, owner) => {
-    // A successor has a different entry, so stale cleanup cannot make its directory empty.
-    await unlink(join(path, owner));
-    await rmdir(path);
-};
-const ownerIsDead = async (path) => {
-    const stats = await lstat(path);
-    if (!stats.isFile() || stats.size > 32)
-        return false;
-    const handle = await open(path, "r");
-    let bytes;
-    try {
-        bytes = await readBoundedFileBytes(handle, 32);
-    }
-    finally {
-        await handle.close();
-    }
-    const encoded = bytes?.toString("utf8").trim();
-    return (encoded !== undefined &&
-        /^[1-9][0-9]{0,9}$/u.test(encoded) &&
-        !processIsAlive(Number(encoded)));
-};
-const exists = async (path) => {
-    try {
-        await lstat(path);
-        return true;
-    }
-    catch (cause) {
-        if (errorCode(cause) === "ENOENT")
-            return false;
-        throw cause;
-    }
-};
-const processIsAlive = (pid) => {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (cause) {
-        return errorCode(cause) !== "ESRCH";
-    }
-};
-const errorCode = (cause) => typeof cause === "object" && cause !== null && "code" in cause
-    ? cause.code
-    : undefined;

package/dist/contracts/processCaptureExample.js

@@ -1,2 +0,0 @@
-/** Minimal valid process capture retained as a public contract example. */
-export { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "../domain/processCaptureExample.js";

package/dist/domain/bytecodeProvider.js

@@ -1,178 +0,0 @@
-import { z } from "zod";
-/** Supported managed-runtime bytecode families. */
-export const bytecodeFamilySchema = z.enum(["jvm", "python"]);
-/** Classification of bytecode provenance. */
-export const bytecodeProvenanceSchema = z.enum([
-    "application",
-    "generated",
-    "vendored",
-    "bundled",
-    "standard_library",
-]);
-/** A bytecode symbol discovered through static analysis. */
-export const bytecodeSymbolSchema = z.strictObject({
-    /** Fully qualified name. */
-    name: z.string().min(1),
-    /** Raw bytecode location or offset. */
-    raw_location: z.string().min(1),
-    /** Normalized symbol type. */
-    kind: z.enum([
-        "class",
-        "interface",
-        "method",
-        "field",
-        "function",
-        "module",
-        "variable",
-    ]),
-    /** Bytecode version if known. */
-    bytecode_version: z.number().int().nullable(),
-    /** Provenance classification. */
-    provenance: bytecodeProvenanceSchema,
-    /** Whether the symbol is accessible (public). */
-    is_public: z.boolean().default(false),
-});
-/** A discovered bytecode artifact (class file, wheel, etc). */
-export const bytecodeArtifactSchema = z.strictObject({
-    /** Artifact path relative to the analysis root. */
-    path: z.string().min(1),
-    /** Bytecode family. */
-    family: bytecodeFamilySchema,
-    /** Artifact format. */
-    format: z.enum(["class", "jar", "war", "ear", "pyc", "pyo", "whl", "zipapp"]),
-    /** Size in bytes. */
-    size: z.number().int().nonnegative(),
-    /** SHA-256 digest. */
-    digest: z.string().regex(/^[a-f0-9]{64}$/u),
-    /** Discovered symbols. */
-    symbols: z.array(bytecodeSymbolSchema).default([]),
-    /** Whether this is a standard library artifact. */
-    is_standard_library: z.boolean().default(false),
-    /** Whether this is a generated artifact. */
-    is_generated: z.boolean().default(false),
-    /** Whether this is a vendored artifact. */
-    is_vendored: z.boolean().default(false),
-});
-/** Static bytecode analysis result. */
-export const bytecodeAnalysisSchema = z.strictObject({
-    /** Bytecode family. */
-    family: bytecodeFamilySchema,
-    /** All discovered artifacts. */
-    artifacts: z.array(bytecodeArtifactSchema),
-    /** Total symbols across all artifacts. */
-    total_symbols: z.number().int().nonnegative(),
-    /** Symbols classified as application code. */
-    application_symbols: z.number().int().nonnegative(),
-    /** Symbols classified as generated code. */
-    generated_symbols: z.number().int().nonnegative(),
-    /** Symbols classified as vendored code. */
-    vendored_symbols: z.number().int().nonnegative(),
-    /** Symbols classified as standard library. */
-    standard_library_symbols: z.number().int().nonnegative(),
-});
-/** Detect bytecode family from file extension. */
-export function detectBytecodeFamily(path) {
-    const lower = path.toLowerCase();
-    if (lower.endsWith(".class") ||
-        lower.endsWith(".jar") ||
-        lower.endsWith(".war") ||
-        lower.endsWith(".ear")) {
-        return "jvm";
-    }
-    if (lower.endsWith(".pyc") ||
-        lower.endsWith(".pyo") ||
-        lower.endsWith(".whl") ||
-        lower.endsWith(".pyz") ||
-        lower.endsWith(".zipapp")) {
-        return "python";
-    }
-    return null;
-}
-/** Detect artifact format from file path. */
-export function detectArtifactFormat(path) {
-    const lower = path.toLowerCase();
-    if (lower.endsWith(".class"))
-        return "class";
-    if (lower.endsWith(".jar"))
-        return "jar";
-    if (lower.endsWith(".war"))
-        return "war";
-    if (lower.endsWith(".ear"))
-        return "ear";
-    if (lower.endsWith(".pyc"))
-        return "pyc";
-    if (lower.endsWith(".pyo"))
-        return "pyo";
-    if (lower.endsWith(".whl"))
-        return "whl";
-    if (lower.endsWith(".pyz") || lower.endsWith(".zipapp"))
-        return "zipapp";
-    return null;
-}
-const STANDARD_LIBRARY_PATH_MARKERS = [
-    "/stdlib/",
-    "/site-packages/",
-    "java/",
-    "javax/",
-    "sun/",
-];
-const STANDARD_LIBRARY_SYMBOL_MARKERS = ["java.", "javax.", "sun.", "__"];
-const GENERATED_PATH_MARKERS = [
-    "/generated/",
-    "_generated",
-    "/build/",
-    "/target/",
-    "/dist-packages/",
-    "/__pycache__/",
-];
-const GENERATED_SYMBOL_MARKERS = ["Generated", "_generated"];
-const VENDORED_PATH_MARKERS = [
-    "/vendor/",
-    "/vendored/",
-    "/third_party/",
-    "/3rdparty/",
-    "/node_modules/",
-];
-const BUNDLED_PATH_MARKERS = ["/bundle/", "/bundled/", ".jar!", ".war!"];
-const includesAny = (value, markers) => markers.some((marker) => value.includes(marker));
-const startsWithAny = (value, markers) => markers.some((marker) => value.startsWith(marker));
-/** Classify bytecode symbol provenance. */
-export function classifyProvenance(path, symbolName) {
-    const lower = path.toLowerCase();
-    if (includesAny(lower, STANDARD_LIBRARY_PATH_MARKERS) ||
-        startsWithAny(symbolName, STANDARD_LIBRARY_SYMBOL_MARKERS))
-        return "standard_library";
-    if (includesAny(lower, GENERATED_PATH_MARKERS) ||
-        includesAny(symbolName, GENERATED_SYMBOL_MARKERS))
-        return "generated";
-    if (includesAny(lower, VENDORED_PATH_MARKERS))
-        return "vendored";
-    if (includesAny(lower, BUNDLED_PATH_MARKERS))
-        return "bundled";
-    return "application";
-}
-/** Analyze a set of bytecode artifacts and produce a summary. */
-export function analyzeBytecodeArtifacts(artifacts, family) {
-    const totals = artifacts.reduce((counts, artifact) => {
-        counts.total += artifact.symbols.length;
-        for (const symbol of artifact.symbols)
-            counts[symbol.provenance] += 1;
-        return counts;
-    }, {
-        total: 0,
-        application: 0,
-        generated: 0,
-        vendored: 0,
-        standard_library: 0,
-        bundled: 0,
-    });
-    return {
-        family,
-        artifacts: [...artifacts],
-        total_symbols: totals.total,
-        application_symbols: totals.application,
-        generated_symbols: totals.generated,
-        vendored_symbols: totals.vendored,
-        standard_library_symbols: totals.standard_library,
-    };
-}