rea-agents 6.2.0 → 6.4.0

package/dist/application/HermesClientHome.js

@@ -0,0 +1,115 @@
+import { lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep, } from "node:path";
+/** An unresolved Hermes profile must not be configured as the default home. */
+export class HermesClientPathError extends Error {
+    path;
+    constructor(path, message) {
+        super(message);
+        this.path = path;
+        this.name = "HermesClientPathError";
+    }
+}
+const defaultDirectory = (home, platform, env) => {
+    const suffix = env.HERMES_DATA_DIR_SUFFIX ?? "";
+    return platform === "win32"
+        ? join(env.LOCALAPPDATA?.trim() || join(home, "AppData", "Local"), `hermes${suffix}`)
+        : join(home, `.hermes${suffix}`);
+};
+const expandedDirectory = (home, platform, env) => {
+    const override = env.HERMES_HOME?.trim();
+    if (!override)
+        return undefined;
+    const variables = override.replace(/\$(\w+|\{[^}]*\})/gu, (match, variable) => {
+        const key = variable.startsWith("{") ? variable.slice(1, -1) : variable;
+        return env[key] ?? match;
+    });
+    const expanded = platform === "win32"
+        ? variables.replace(/%([^%]+)%/gu, (match, variable) => env[variable] ?? match)
+        : variables;
+    if (expanded === "~")
+        return home;
+    if (expanded.startsWith("~/") ||
+        (platform === "win32" && expanded.startsWith("~\\")))
+        return join(home, expanded.slice(2));
+    return resolve(expanded);
+};
+const physicalPath = (path) => {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+};
+const within = (root, path) => {
+    const difference = relative(physicalPath(root), physicalPath(path));
+    return (difference === "" ||
+        (!isAbsolute(difference) &&
+            difference !== ".." &&
+            !difference.startsWith(`..${sep}`)));
+};
+const PROFILE_MARKERS = [
+    "config.yaml",
+    ".env",
+    "SOUL.md",
+    "profile.yaml",
+    "auth.json",
+    "state.db",
+];
+const RESERVED_PROFILES = new Set(["hermes", "test", "tmp", "root", "sudo"]);
+const liveProfile = (path) => {
+    try {
+        if (!statSync(path).isDirectory())
+            return false;
+        try {
+            statSync(join(dirname(path), ".deleted", basename(path)));
+            return false;
+        }
+        catch {
+            /* No tombstone. */
+        }
+        return PROFILE_MARKERS.some((marker) => {
+            try {
+                const status = lstatSync(join(path, marker));
+                return status.isFile() || status.isSymbolicLink();
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        return false;
+    }
+};
+/** Match Hermes CLI sticky-profile selection while retaining the configured path spelling. */
+export const resolveHermesClientHome = (home, platform, env) => {
+    const native = defaultDirectory(home, platform, env);
+    const root = expandedDirectory(home, platform, env) ?? native;
+    // An explicit named profile bypasses the root's sticky selection in Hermes CLI.
+    if (basename(dirname(root)) === "profiles")
+        return root;
+    const stickyRoot = within(native, root) ? native : root;
+    let name;
+    try {
+        // Python uses utf-8-sig and ignores unreadable / invalid-UTF8 active_profile files.
+        name = new TextDecoder("utf-8", { fatal: true })
+            .decode(readFileSync(join(stickyRoot, "active_profile")))
+            .trim();
+    }
+    catch {
+        return root;
+    }
+    if (name === "" || name === "default")
+        return root;
+    const canonical = name.toLowerCase();
+    if (canonical === "default")
+        return root;
+    if (!/^[a-z0-9][a-z0-9_-]{0,63}$/u.test(canonical) ||
+        RESERVED_PROFILES.has(canonical))
+        throw new HermesClientPathError(join(stickyRoot, "active_profile"), `Invalid saved Hermes profile ${JSON.stringify(name)}. Run 'hermes profile use default' or repair active_profile.`);
+    const selected = join(root, "profiles", canonical);
+    if (!liveProfile(selected))
+        throw new HermesClientPathError(selected, `Saved Hermes profile ${JSON.stringify(name)} is missing, deleted, or has no profile identity. Run 'hermes profile use default' or restore that profile before configuring it.`);
+    return selected;
+};

package/dist/application/HopperDownload.js

@@ -0,0 +1,39 @@
+/** Maximum admitted vendor response bytes, shared by Hopper setup adapters. */
+export const HOPPER_DOWNLOAD_BYTES = 100_000_000;
+/** Bound observed response bytes before retaining them, including chunked bodies. */
+export const downloadHopperPackage = async (url, options = {}) => {
+    const deadline = AbortSignal.timeout(120_000);
+    const response = await fetch(url, {
+        headers: { accept: "application/json", "user-agent": "rea-installer" },
+        signal: options.signal === undefined
+            ? deadline
+            : AbortSignal.any([options.signal, deadline]),
+    });
+    const refused = { ok: false, bytes: new Uint8Array() };
+    if (!response.ok ||
+        Number(response.headers.get("content-length")) > HOPPER_DOWNLOAD_BYTES) {
+        await response.body?.cancel();
+        return refused;
+    }
+    if (response.body === null)
+        return { ok: true, bytes: new Uint8Array() };
+    const reader = response.body.getReader();
+    const chunks = [];
+    let bytes = 0;
+    try {
+        while (true) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                return { ok: true, bytes: Buffer.concat(chunks, bytes) };
+            if (chunk.value.byteLength > HOPPER_DOWNLOAD_BYTES - bytes) {
+                await reader.cancel();
+                return refused;
+            }
+            chunks.push(chunk.value);
+            bytes += chunk.value.byteLength;
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+};

package/dist/application/InvestigationProviders.js

@@ -13,17 +13,23 @@ export const workflowAnalysisProfile = (upstream, operation) => createAnalysisPr
         : {}),
 });
 /** Provider identity for deterministic artifact inventories. */
-export const ARTIFACT_GRAPH_PROVIDER = {
+export const ARTIFACT_GRAPH_PROVIDER = Object.freeze({
     id: "rea-artifact-graph",
     name: "REA safe artifact graph provider",
     version: "1",
-};
+});
 /** Provider identity for execution-free managed PE/CLI analysis. */
-export const MANAGED_STATIC_PROVIDER = {
+export const MANAGED_STATIC_PROVIDER = Object.freeze({
     id: "rea-dotnet-static",
     name: "REA managed static analysis provider",
     version: "1",
-};
+});
+/** Provider identity for portable, execution-free PE resource decoding. */
+export const PE_RESOURCES_PROVIDER = Object.freeze({
+    id: "rea-pe-resources",
+    name: "REA PE resource parser",
+    version: "1",
+});
 /** Provider identity for deterministic managed-code comparison workflows. */
 export const MANAGED_WORKFLOW_PROVIDER = {
     id: "rea-dotnet-workflows",

package/dist/application/JsonFiles.js

@@ -1,31 +1,32 @@
-import { link, lstat, mkdtemp, open, readFile, realpath, rename, rm, } from "node:fs/promises";
+import { link, lstat, mkdtemp, open, realpath, rename, rm, } from "node:fs/promises";
 import { basename, dirname, resolve } from "node:path";
 import { EvidenceFileError } from "../domain/evidenceErrors.js";
-import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisResourceConstraintError, } from "../domain/analysisErrorCore.js";
 import { err, ok } from "../domain/result.js";
+import { readJsonInputFile } from "./JsonInputFile.js";
+import { NonRegularFileReadError } from "../filesystem/RegularFile.js";
 /** Read JSON data from a regular file at the caller-supplied path. */
 export const readJsonFile = async (path) => {
     const requestedPath = resolve(path);
     try {
-        const canonicalPath = await realpath(requestedPath);
-        const stats = await lstat(canonicalPath);
-        if (!stats.isFile())
-            return err(new EvidenceFileError("read", "not-file", { path: requestedPath }));
-        const encoded = await readFile(canonicalPath);
-        let decoded;
-        try {
-            decoded = JSON.parse(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(encoded));
-        }
-        catch (cause) {
+        const decoded = await readJsonInputFile(requestedPath, "read_evidence_file");
+        if (!decoded.ok) {
+            if (decoded.error instanceof AnalysisResourceConstraintError)
+                return err(decoded.error);
             return err(new EvidenceFileError("read", "invalid-json", {
-                cause,
+                cause: decoded.error.cause ??
+                    new SyntaxError(decoded.error.issues[0]?.message ?? decoded.error.message),
                 path: requestedPath,
             }));
         }
-        return ok(decoded);
+        return ok(decoded.value);
     }
     catch (cause) {
-        return err(new EvidenceFileError("read", missingOrIo(cause), {
+        if (cause instanceof AnalysisResourceConstraintError)
+            return err(cause);
+        return err(new EvidenceFileError("read", cause instanceof NonRegularFileReadError
+            ? "not-file"
+            : missingOrIo(cause), {
             cause,
             path: requestedPath,
         }));

package/dist/application/JsonInputFile.js

@@ -0,0 +1,252 @@
+import { constants } from "node:buffer";
+import { pipeline } from "node:stream/promises";
+import { getHeapStatistics } from "node:v8";
+import parser from "stream-json/parser.js";
+import streamValues from "stream-json/streamers/stream-values.js";
+import { RegularFileChangedError } from "../filesystem/RegularFile.js";
+import { withRegularFile } from "./RegularFileRead.js";
+import { JSON_BYTE_ORDER_MARK_MESSAGE, JSON_INPUT_RESOURCE_REMEDIATION, parseUtf8Json, } from "./Utf8JsonInput.js";
+import { AnalysisInputError, AnalysisResourceConstraintError, } from "../domain/analysisErrorCore.js";
+import { err, ok } from "../domain/result.js";
+const READ_CHUNK_BYTES = 64 * 1024;
+const PACKED_TOKEN_PART_CODE_UNITS = 64 * 1024;
+// Retain native-parser speed for modest inputs while bounding its extra copies.
+// This selects an implementation; larger files remain accepted through streaming.
+const NATIVE_PARSE_READ_BUDGET = 8 * 1024 * 1024;
+/** Keep native parsing only when input copies and value expansion fit live headroom. */
+const nativeParseFits = (inputBytes) => inputBytes <= NATIVE_PARSE_READ_BUDGET &&
+    // The assembler estimate reserves up to 128 bytes per two-byte container.
+    // Allow that 64x expansion plus byte/text copies before native JSON.parse,
+    // whose individual container allocations cannot be intercepted.
+    inputBytes * 72 + READ_CHUNK_BYTES <=
+        getHeapStatistics().total_available_size;
+/** Parse strict UTF-8 JSON without requiring a whole-document string. */
+export const readJsonInputFile = (path, operation, signal) => withRegularFile(path, async (handle, stats) => {
+    let found = false;
+    let value;
+    try {
+        const prefix = nativeParseFits(stats.size)
+            ? await readPrefix(handle, stats.size + 1, signal)
+            : undefined;
+        if (prefix !== undefined) {
+            if (!prefix.complete || prefix.bytes.length !== stats.size)
+                throw new RegularFileChangedError(path);
+            const parsed = parseUtf8Json(prefix.bytes, operation, path, "json-file-input");
+            return parsed.ok
+                ? ok(parsed.value)
+                : err(invalidJson(operation, parsed.error, parsed.cause));
+        }
+        await pipeline(decodedChunks(handle, stats.size, path, signal), parser.asStream({
+            jsonStreaming: false,
+            streamValues: false,
+            packKeys: false,
+            packStrings: false,
+            packNumbers: false,
+        }), packJsonScalars(operation, stats.size, path), admitJsonAssembly(operation, stats.size, path), streamValues.asStream(), async (rows) => {
+            for await (const row of rows) {
+                if (found ||
+                    typeof row !== "object" ||
+                    row === null ||
+                    !("key" in row) ||
+                    row.key !== 0 ||
+                    !("value" in row))
+                    throw new Error("Unexpected JSON parser result");
+                found = true;
+                value = row.value;
+            }
+        }, signal === undefined ? {} : { signal });
+        return found
+            ? ok(value)
+            : err(invalidJson(operation, "JSON document is empty"));
+    }
+    catch (cause) {
+        if (cause instanceof AnalysisResourceConstraintError)
+            return err(cause);
+        if (cause instanceof TypeError &&
+            "code" in cause &&
+            cause.code === "ERR_ENCODING_INVALID_ENCODED_DATA")
+            return err(invalidJson(operation, "JSON input is not valid UTF-8", cause));
+        if (cause instanceof SyntaxError ||
+            (cause instanceof Error && cause.message.startsWith("Parser ")))
+            return err(invalidJson(operation, cause.message, cause));
+        if (cause instanceof Error &&
+            ((cause instanceof RangeError &&
+                cause.message === "Invalid string length") ||
+                ("code" in cause && cause.code === "ERR_STRING_TOO_LONG")))
+            return err(new AnalysisResourceConstraintError(operation, "memory", "An individual JSON string or number token exceeds the runtime string limit", {
+                input_path: path,
+                input_file_bytes: stats.size,
+                max_string_code_units: constants.MAX_STRING_LENGTH,
+            }, {
+                cause,
+                remediationAction: JSON_INPUT_RESOURCE_REMEDIATION,
+            }));
+        throw cause;
+    }
+}, { signal });
+const packJsonScalars = (operation, inputFileBytes, path) => async function* (tokens) {
+    let kind;
+    let length = 0;
+    let value = "";
+    let parts = [];
+    let partLength = 0;
+    for await (const token of tokens) {
+        if (typeof token !== "object" || token === null || !("name" in token))
+            throw new Error("Unexpected JSON parser token");
+        switch (token.name) {
+            case "startKey":
+            case "startString":
+                kind = token.name === "startKey" ? "keyValue" : "stringValue";
+                break;
+            case "startNumber":
+                kind = "numberValue";
+                break;
+            case "numberChunk":
+            case "stringChunk":
+                if (kind === undefined ||
+                    !("value" in token) ||
+                    typeof token.value !== "string")
+                    throw new Error("Unexpected JSON scalar fragment");
+                length += token.value.length;
+                if (length > constants.MAX_STRING_LENGTH)
+                    throw new RangeError("Invalid string length");
+                parts.push(token.value);
+                partLength += token.value.length;
+                if (partLength >= PACKED_TOKEN_PART_CODE_UNITS) {
+                    // The tokenizer emits short fragments. Coalesce them before retaining
+                    // a scalar so millions of substring/rope nodes cannot exhaust the heap
+                    // before the native string-length constraint can be reported.
+                    requireStringAssemblyHeadroom(operation, inputFileBytes, path, length);
+                    value += parts.join("");
+                    parts = [];
+                    partLength = 0;
+                }
+                break;
+            case "endKey":
+            case "endString":
+            case "endNumber":
+                if (kind === undefined)
+                    throw new Error("Unexpected JSON scalar end");
+                requireStringAssemblyHeadroom(operation, inputFileBytes, path, length);
+                yield { name: kind, value: value + parts.join("") };
+                kind = undefined;
+                length = 0;
+                value = "";
+                parts = [];
+                partLength = 0;
+                break;
+            default:
+                yield token;
+        }
+    }
+};
+/** Admit the retained value graph before the upstream assembler grows it. */
+const admitJsonAssembly = (operation, inputFileBytes, path) => async function* (tokens) {
+    let projectedBytes = 0;
+    let nextCheck = 0;
+    for await (const token of tokens) {
+        if (typeof token !== "object" || token === null || !("name" in token))
+            throw new Error("Unexpected JSON assembly token");
+        if (token.name === "startObject" || token.name === "startArray") {
+            projectedBytes += 128;
+        }
+        else if (token.name === "keyValue" || token.name === "stringValue") {
+            if (!("value" in token) || typeof token.value !== "string")
+                throw new Error("Unexpected packed JSON string");
+            projectedBytes += 64 + token.value.length * 2;
+        }
+        else if (token.name === "numberValue" ||
+            token.name === "nullValue" ||
+            token.name === "trueValue" ||
+            token.name === "falseValue") {
+            projectedBytes += 64;
+        }
+        if (projectedBytes >= nextCheck) {
+            const heap = getHeapStatistics();
+            // Conservative capacity for containers, property/array slots and UTF-16
+            // values. Keep another whole projection available for container growth,
+            // plus the next chunk of estimates between samples. This is admission
+            // against live runtime headroom, not a fixed document-size policy.
+            const requiredBytes = projectedBytes + READ_CHUNK_BYTES;
+            if (requiredBytes > heap.total_available_size)
+                throw new AnalysisResourceConstraintError(operation, "memory", "Insufficient heap headroom to materialize the complete JSON value", {
+                    input_path: path,
+                    input_file_bytes: inputFileBytes,
+                    projected_value_bytes: projectedBytes,
+                    assembly_headroom_bytes: requiredBytes,
+                    available_heap_bytes: heap.total_available_size,
+                    heap_size_limit_bytes: heap.heap_size_limit,
+                }, { remediationAction: JSON_INPUT_RESOURCE_REMEDIATION });
+            nextCheck = projectedBytes + READ_CHUNK_BYTES;
+        }
+        yield token;
+    }
+};
+const requireStringAssemblyHeadroom = (operation, inputFileBytes, path, stringCodeUnits) => {
+    if (stringCodeUnits < PACKED_TOKEN_PART_CODE_UNITS)
+        return;
+    const heap = getHeapStatistics();
+    // Concatenation or key interning may flatten the retained rope. Reserve its
+    // UTF-16 representation and the next coalesced part before that allocation.
+    const requiredBytes = 2 * (stringCodeUnits + PACKED_TOKEN_PART_CODE_UNITS);
+    if (requiredBytes > heap.total_available_size)
+        throw new AnalysisResourceConstraintError(operation, "memory", "Insufficient heap headroom to assemble a complete JSON string", {
+            input_path: path,
+            input_file_bytes: inputFileBytes,
+            string_code_units: stringCodeUnits,
+            string_assembly_headroom_bytes: requiredBytes,
+            available_heap_bytes: heap.total_available_size,
+            heap_size_limit_bytes: heap.heap_size_limit,
+        }, {
+            remediationAction: JSON_INPUT_RESOURCE_REMEDIATION,
+        });
+};
+async function* decodedChunks(handle, admittedBytes, path, signal) {
+    const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+    let leading = true;
+    const checked = (text) => {
+        if (leading && text.length > 0) {
+            leading = false;
+            if (text.startsWith("\uFEFF"))
+                throw new JsonByteOrderMarkError();
+        }
+        return text;
+    };
+    const bytes = Buffer.allocUnsafe(READ_CHUNK_BYTES);
+    let observedBytes = 0;
+    while (true) {
+        signal?.throwIfAborted();
+        const read = await handle.read(bytes, 0, Math.min(bytes.length, admittedBytes - observedBytes + 1), null);
+        signal?.throwIfAborted();
+        if (read.bytesRead === 0)
+            break;
+        observedBytes += read.bytesRead;
+        if (observedBytes > admittedBytes)
+            throw new RegularFileChangedError(path);
+        yield checked(decoder.decode(bytes.subarray(0, read.bytesRead), { stream: true }));
+    }
+    if (observedBytes !== admittedBytes)
+        throw new RegularFileChangedError(path);
+    yield checked(decoder.decode());
+}
+/** A streamed JSON file begins with a byte-order mark; reported as invalid JSON. */
+class JsonByteOrderMarkError extends SyntaxError {
+    constructor() {
+        super(JSON_BYTE_ORDER_MARK_MESSAGE);
+    }
+}
+const readPrefix = async (handle, size, signal) => {
+    const bytes = Buffer.allocUnsafe(size);
+    let offset = 0;
+    while (offset < bytes.length) {
+        signal?.throwIfAborted();
+        const read = await handle.read(bytes, offset, bytes.length - offset, null);
+        signal?.throwIfAborted();
+        if (read.bytesRead === 0)
+            return { bytes: bytes.subarray(0, offset), complete: true };
+        offset += read.bytesRead;
+    }
+    // One byte beyond the admitted extent proves the selected file changed.
+    return { bytes, complete: false };
+};
+const invalidJson = (operation, message, cause) => new AnalysisInputError(operation, cause === undefined ? undefined : { cause }, [{ path: [], reason: "invalid_format", expected: "JSON", message }]);

package/dist/application/LinuxHopper.js

@@ -6,9 +6,9 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { promisify } from "node:util";
 import { execFileOutput } from "../process/ExecFileOutput.js";
+import { downloadHopperPackage, HOPPER_DOWNLOAD_BYTES, } from "./HopperDownload.js";
 const execFileAsync = promisify(execFile);
 const DOWNLOAD_PREFIX = "https://www.hopperapp.com:443/downloader/public/";
-const MAX_PACKAGE_BYTES = 100_000_000;
 const SUPPORTED_HOPPER_SHA256 = new Set([
     "0294ced141cc373468ee22d8343e7dac41980cb05a937994ca81c9f09afe7ded",
     "1339f9e58377442b0c6fcb0dfc3cec20d593cc557408521fad9a00dbc6b8da13",
@@ -62,8 +62,10 @@ export const parseLinuxDistribution = (text) => {
     const supported = packageFamily !== undefined &&
         (id === "arch" ||
             id === "cachyos" ||
+            (id === "omarchy" && packageFamily === "arch") ||
             (id === "ubuntu" && versionAtLeast(versionId, 24)) ||
-            (id === "fedora" && versionAtLeast(versionId, 41)));
+            (id === "fedora" && versionAtLeast(versionId, 41)) ||
+            (id === "nobara" && versionAtLeast(versionId, 44)));
     const identity = {
         id,
         ...(versionId === undefined ? {} : { versionId }),
@@ -127,16 +129,7 @@ export const linuxHopperLauncherPath = (home) => join(home, ".local/share/rea/ho
 /** Compose package-manager and linker checks from the selected caller environment. */
 export const systemLinuxHopperInstallHost = (environment) => ({
     distribution: readLinuxDistribution,
-    async download(url, options) {
-        const response = await fetch(url, {
-            headers: { accept: "application/json", "user-agent": "rea-installer" },
-            ...(options.signal === undefined ? {} : { signal: options.signal }),
-        });
-        return {
-            ok: response.ok,
-            bytes: new Uint8Array(await response.arrayBuffer()),
-        };
-    },
+    download: downloadHopperPackage,
     createTemporaryDirectory: () => mkdtemp(join(tmpdir(), "rea-hopper-")),
     writeArchive: (path, bytes) => writeFile(path, bytes, { mode: 0o600 }),
     installPackage: (family, archive) => installSystemPackage(family, archive, environment),
@@ -219,7 +212,7 @@ export const linuxPackageManagerCommands = (family, archive, isRoot) => {
     });
 };
 const packageIntegrityMatches = (bytes, release) => bytes.byteLength === Number(release.file_length) &&
-    bytes.byteLength <= MAX_PACKAGE_BYTES &&
+    bytes.byteLength <= HOPPER_DOWNLOAD_BYTES &&
     createHash("sha1").update(bytes).digest("hex") === release.file_hash;
 const packageFamilyFor = (id, idLike) => {
     const identities = new Set([