rea-agents 1.1.0 → 1.3.0

package/dist/application/TerminalRenderer.js

@@ -0,0 +1,92 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+// SAFETY: both pinned xterm packages publish CommonJS at runtime and matching declarations.
+const HeadlessPackage = require("@xterm/headless");
+// SAFETY: the addon package is pinned with the compatible headless xterm release.
+const SerializePackage = require("@xterm/addon-serialize");
+/** Owns one headless terminal and serializes writes into deterministic frames. */
+/**
+ * Reconstructs bounded terminal states while raw PTY chunks remain authoritative.
+ *
+ * Rendered frames answer what an operator saw after control-sequence handling;
+ * raw frames preserve byte/chunk differences that can render identically.
+ * Comparisons retain both because neither representation subsumes the other.
+ */
+export class TerminalRenderer {
+    options;
+    #terminal;
+    #serializeAddon = new SerializePackage.SerializeAddon();
+    #frames = [];
+    #pending = Promise.resolve();
+    #capturedBytes = 0;
+    #truncated = false;
+    constructor(options) {
+        this.options = options;
+        this.#terminal = new HeadlessPackage.Terminal({
+            allowProposedApi: true,
+            cols: options.columns,
+            rows: options.rows,
+            scrollback: options.scrollback,
+        });
+        this.#terminal.loadAddon(this.#serializeAddon);
+    }
+    /** Queue one PTY chunk and capture state only after xterm has parsed it. */
+    write(data, atMs) {
+        this.#pending = this.#pending.then(() => new Promise((resolveWrite) => {
+            this.#terminal.write(data, () => {
+                this.#capture(atMs);
+                resolveWrite();
+            });
+        }));
+    }
+    /** Queue a terminal resize after every preceding write. */
+    resize(columns, rows, atMs) {
+        this.#pending = this.#pending.then(() => {
+            this.#terminal.resize(columns, rows);
+            this.#capture(atMs);
+        });
+    }
+    /** Await all queued parsing and return immutable rendered observations. */
+    async frames() {
+        await this.#pending;
+        return this.#frames;
+    }
+    /** Whether a rendered observation exceeded its independent capture budget. */
+    truncated() {
+        return this.#truncated;
+    }
+    /** Release addon and terminal resources after all writes settle. */
+    async dispose() {
+        await this.#pending;
+        this.#serializeAddon.dispose();
+        this.#terminal.dispose();
+    }
+    #capture(atMs) {
+        const buffer = this.#terminal.buffer.active;
+        const lines = [];
+        for (let row = 0; row < this.#terminal.rows; row += 1) {
+            const line = buffer.getLine(buffer.viewportY + row);
+            lines.push(this.options.normalize((line?.translateToString(false, 0, this.#terminal.cols) ?? "").padEnd(this.#terminal.cols, " ")));
+        }
+        const serializedState = this.options.normalize(this.#serializeAddon.serialize());
+        const bytes = Buffer.byteLength(serializedState) +
+            lines.reduce((total, line) => total + Buffer.byteLength(line), 0);
+        if (this.#frames.length >= this.options.maxFrames ||
+            this.#capturedBytes + bytes > this.options.maxBytes) {
+            this.#truncated = true;
+            return;
+        }
+        this.#capturedBytes += bytes;
+        this.#frames.push({
+            sequence: this.#frames.length,
+            at_ms: atMs,
+            columns: this.#terminal.cols,
+            rows: this.#terminal.rows,
+            cursor_x: buffer.cursorX,
+            cursor_y: buffer.cursorY,
+            active_buffer: buffer.type,
+            lines,
+            serialized_state: serializedState,
+        });
+    }
+}

package/dist/application/Uninstall.js

@@ -6,6 +6,13 @@ import writeFileAtomic from "write-file-atomic";
 import { z } from "zod";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { supportedClients } from "./Setup.js";
+const systemFileSystem = {
+    readText: (path) => readFile(path, "utf8"),
+    copy: (source, destination) => copyFile(source, destination),
+    writeText: (path, contents) => writeFileAtomic(path, contents, { encoding: "utf8" }),
+    stat: (path) => lstat(path),
+    remove: (path) => rm(path, { recursive: true }),
+};
 /** Remove only REA-owned registrations and managed files, optionally including local state. */
 export const runUninstall = async (purgeData, host = systemUninstallHost()) => {
     const items = [];
@@ -27,26 +34,26 @@ export const runUninstall = async (purgeData, host = systemUninstallHost()) => {
     };
 };
 /** Create uninstall effects contained to detected client configs and REA-owned paths. */
-export const systemUninstallHost = (home = homedir()) => ({
+export const systemUninstallHost = (home = homedir(), fileSystem = systemFileSystem) => ({
     clients: () => Promise.resolve(supportedClients(home)),
-    removeClient,
-    removeSkill: () => removeManagedPath(join(home, ".agents/skills", PRODUCT_IDENTITY.skillName), "skill"),
+    removeClient: (client) => removeClient(client, fileSystem),
+    removeSkill: () => removeManagedPath(join(home, ".agents/skills", PRODUCT_IDENTITY.skillName), "skill", fileSystem),
     purgeData: async () => [
-        await removeManagedPath(join(home, ".rea/cache"), "cache"),
-        await removeManagedPath(join(home, ".rea/state"), "state"),
+        await removeManagedPath(join(home, ".rea/cache"), "cache", fileSystem),
+        await removeManagedPath(join(home, ".rea/state"), "state", fileSystem),
     ],
 });
-const removeClient = async (client) => {
+const removeClient = async (client, fileSystem) => {
     if (client.format === "unsupported")
         return item(client.name, "skipped", "This client has no documented local MCP configuration boundary.");
     let original;
     try {
-        original = await readFile(client.configPath, "utf8");
+        original = await fileSystem.readText(client.configPath);
     }
     catch (cause) {
         return isMissing(cause)
             ? item(client.name, "skipped", "Configuration does not exist.")
-            : item(client.name, "failed", "Configuration could not be read.");
+            : item(client.name, "failed", "Configuration could not be read. Check file permissions, then rerun uninstall.");
     }
     let document;
     let key;
@@ -57,7 +64,7 @@ const removeClient = async (client) => {
         servers = optionalObject(document[key]);
     }
     catch {
-        return item(client.name, "failed", "Malformed configuration was preserved without mutation.");
+        return item(client.name, "failed", `Configuration is not valid ${client.format === "toml" ? "TOML" : "JSON"} and was not changed. Repair it, then rerun uninstall.`);
     }
     const registration = servers[PRODUCT_IDENTITY.mcpServerKey];
     if (registration === undefined)
@@ -69,28 +76,31 @@ const removeClient = async (client) => {
     document[key] = remaining;
     const backupPath = `${client.configPath}.rea.backup`;
     try {
-        await copyFile(client.configPath, backupPath);
+        await fileSystem.copy(client.configPath, backupPath);
     }
     catch {
-        return item(client.name, "failed", "Configuration backup failed; no mutation was attempted.");
+        return item(client.name, "failed", "Configuration could not be backed up, so no change was made. Check file permissions, then rerun uninstall.");
     }
     try {
         const encoded = client.format === "toml"
             ? stringifyToml(document)
             : `${JSON.stringify(document, null, 2)}\n`;
-        await writeFileAtomic(client.configPath, encoded, { encoding: "utf8" });
+        await fileSystem.writeText(client.configPath, encoded);
         const readback = objectSchema.parse(client.format === "toml"
-            ? parseToml(await readFile(client.configPath, "utf8"))
-            : JSON.parse(await readFile(client.configPath, "utf8")));
+            ? parseToml(await fileSystem.readText(client.configPath))
+            : JSON.parse(await fileSystem.readText(client.configPath)));
         if (PRODUCT_IDENTITY.mcpServerKey in optionalObject(readback[key]))
             throw new Error("registration readback mismatch");
         return item(client.name, "removed", `Removed registration from ${client.configPath}.`);
     }
     catch {
-        await writeFileAtomic(client.configPath, original, {
-            encoding: "utf8",
-        }).catch(() => undefined);
-        return item(client.name, "failed", `Configuration update failed; the original was restored and ${backupPath} was retained.`);
+        try {
+            await fileSystem.writeText(client.configPath, original);
+        }
+        catch {
+            return item(client.name, "failed", "Configuration could not be updated or restored. Restore its `.rea.backup` manually, then rerun uninstall.");
+        }
+        return item(client.name, "failed", "Configuration could not be updated. The original was restored and its `.rea.backup` was retained. Repair the configuration or restore the backup, then rerun uninstall.");
     }
 };
 /** Ownership rule for persistent MCP registrations created by REA setup. */
@@ -107,18 +117,18 @@ const isOwnedRegistration = (value) => {
             JSON.stringify(args) ===
                 JSON.stringify(["-y", PRODUCT_IDENTITY.packageName, "mcp"])));
 };
-const removeManagedPath = async (path, name) => {
+const removeManagedPath = async (path, name, fileSystem) => {
     try {
-        const stats = await lstat(path);
+        const stats = await fileSystem.stat(path);
         if (stats.isSymbolicLink())
-            return item(name, "retained", `Refused to follow symlink ${path}.`);
-        await rm(path, { recursive: true });
+            return item(name, "retained", "REA did not remove this item because its managed path is a symbolic link. Verify the link target before removing it manually.");
+        await fileSystem.remove(path);
         return item(name, "removed", `Removed ${path}.`);
     }
     catch (cause) {
         return isMissing(cause)
             ? item(name, "skipped", `${path} does not exist.`)
-            : item(name, "failed", `${path} could not be removed.`);
+            : item(name, "failed", "This item could not be removed. Check file permissions, then rerun uninstall.");
     }
 };
 const item = (name, status, detail) => ({ name, status, detail });

package/dist/application/UnknownEvidence.js

@@ -0,0 +1,33 @@
+import { createEvidence } from "../domain/evidence.js";
+/** Provider identity for analyst-authored residual-unknown mutations. */
+export const UNKNOWN_REGISTRY_PROVIDER = {
+    id: "rea-unknown-registry",
+    name: "REA residual unknown registry",
+    version: "1",
+};
+/** Create immutable evidence for one approved residual-unknown mutation. */
+export const unknownMutationEvidence = (target, input) => createEvidence(target, UNKNOWN_REGISTRY_PROVIDER, {
+    predicateType: "rea.residual-unknown-mutation/v1",
+    operation: "record_unknown",
+    parameters: { domain: input.domain, severity: input.severity },
+    result: {
+        action: "record",
+        question: input.question,
+        required_authority: input.required_authority,
+        required_confidence: input.required_confidence,
+    },
+    confidence: "derived",
+    authority: "analyst-inference",
+    evidenceLinks: unknownEvidenceLinks(input),
+    limitations: [
+        "Registry mutation evidence records analyst intent, not proof of the answer.",
+    ],
+});
+/** Deduplicate evidence links carried by an unknown mutation. */
+export const unknownEvidenceLinks = (input) => [
+    ...input.supporting_evidence_ids,
+    ...input.contradicting_evidence_ids,
+    ...("resolution" in input && input.resolution !== null
+        ? input.resolution.evidence_ids
+        : []),
+].filter((id, index, values) => values.indexOf(id) === index);

package/dist/application/Upgrade.js

@@ -33,7 +33,7 @@ export const runUpgrade = async (currentVersion, host = systemUpgradeHost(), out
             currentVersion,
             latestVersion: latestVersion ?? null,
             reason: "install",
-            remediation: `${UPGRADE_COMMAND} failed.`,
+            remediation: `REA could not update through npm. Check npm registry access and global install permissions, then run: ${UPGRADE_COMMAND}`,
         };
     return {
         status: "upgraded",

package/dist/application/runtime.js

@@ -11,8 +11,8 @@ import { silentLogger } from "../logger.js";
  */
 export const createBinarySession = (config, logger = silentLogger) => {
     return new BinarySession(new CompositeProvider([
-        new ArtifactProvider(),
+        new ArtifactProvider(config.artifactNativeMountEnabled),
         new NativeMacOSProvider(),
         new HopperProvider(config, logger),
-    ]));
+    ]), { snapshotsEnabled: config.hopperLoaderArgs.length === 0 });
 };

package/dist/artifacts/ArtifactProvider.js

@@ -5,13 +5,14 @@ import { ARTIFACT_TOOL_CONTRACTS, artifactInventoryInputSchema, artifactExtracti
 import { AnalysisCapabilityUnavailableError, ArtifactOperationError, } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
 import { ArtifactReaderFailure, } from "./ArtifactReader.js";
-const IDENTITY = Object.freeze({
-    id: "rea-artifact-graph",
-    name: "REA safe artifact graph provider",
-    version: "1",
-});
+import { ARTIFACT_GRAPH_PROVIDER } from "../application/InvestigationProviders.js";
+const IDENTITY = Object.freeze(ARTIFACT_GRAPH_PROVIDER);
 /** Read-only inventory and exclusively owned extraction provider. */
 export class ArtifactProvider {
+    nativeMountEnabled;
+    constructor(nativeMountEnabled = false) {
+        this.nativeMountEnabled = nativeMountEnabled;
+    }
     #capabilities = Object.freeze(ARTIFACT_TOOL_CONTRACTS.map((contract) => Object.freeze({
         provider: IDENTITY,
         operation: contract.name,
@@ -36,8 +37,8 @@ export class ArtifactProvider {
             timeoutMs: 120_000,
         }),
         limitations: Object.freeze([
-            "DMG and PKG child inventory requires a future native read-only adapter.",
-            "Nested containers are recorded but not recursively expanded implicitly.",
+            "DMG child inventory is macOS-only and requires per-call approval plus operator policy; PKG remains root-hash-only.",
+            "ASAR files discovered in filesystem-backed inventories are expanded without bulk extraction; other nested containers remain recorded only.",
         ]),
     })));
     identity() {
@@ -47,13 +48,15 @@ export class ArtifactProvider {
         return this.#capabilities;
     }
     createClient(target) {
-        return new ArtifactClient(target);
+        return new ArtifactClient(target, this.nativeMountEnabled);
     }
 }
 class ArtifactClient {
     target;
-    constructor(target) {
+    nativeMountEnabled;
+    constructor(target, nativeMountEnabled) {
         this.target = target;
+        this.nativeMountEnabled = nativeMountEnabled;
     }
     async execute(operation, parameters, options) {
         if (operation === "health")
@@ -90,7 +93,13 @@ class ArtifactClient {
                 occurrenceLimit: parsed.occurrence_limit,
                 edgeOffset: parsed.edge_offset,
                 edgeLimit: parsed.edge_limit,
-            }, options?.signal);
+            }, {
+                ...(options?.signal === undefined ? {} : { signal: options.signal }),
+                nativeMount: {
+                    nativeMountApproved: parsed.native_mount_approved === true,
+                    nativeMountEnabled: this.nativeMountEnabled,
+                },
+            });
             return ok(createAnalysisExecution(result, IDENTITY, {
                 rawResult: null,
                 limitations: result.limitations,
@@ -120,7 +129,7 @@ const limitsFrom = (input) => ({
 const isArtifactOperation = (operation) => ARTIFACT_TOOL_CONTRACTS.some(({ name }) => name === operation);
 const translateFailure = (operation, cause) => {
     if (cause instanceof ArtifactReaderFailure)
-        return new ArtifactOperationError(operation, cause.reason);
+        return new ArtifactOperationError(operation, cause.reason, cause.details);
     return new ArtifactOperationError(operation, "io");
 };
 const subjectFor = (path, manifest) => ({

package/dist/artifacts/ArtifactReader.js

@@ -1,9 +1,11 @@
 /** Typed adapter failure translated at provider boundary. */
 export class ArtifactReaderFailure extends Error {
     reason;
-    constructor(reason, message, options) {
+    details;
+    constructor(reason, message, options, details) {
         super(message, options);
         this.reason = reason;
+        this.details = details;
         this.name = "ArtifactReaderFailure";
     }
 }

package/dist/artifacts/AsarArtifactReader.js

@@ -1,7 +1,13 @@
 import { Readable } from "node:stream";
 import { extractFile, listPackage, statFile } from "@electron/asar";
 import { ArtifactReaderFailure, } from "./ArtifactReader.js";
-/** Official Electron ASAR adapter. Individual files remain caller-bounded. */
+/**
+ * Official Electron ASAR adapter. Individual files remain caller-bounded.
+ *
+ * An entry marked `unpacked` is metadata, not an integrity exemption: Electron
+ * stores its bytes beside the archive in `<archive>.unpacked`, and callers must
+ * hash those companion bytes against the archive's declared integrity value.
+ */
 export class AsarArtifactReader {
     path;
     format = "asar";
@@ -34,6 +40,7 @@ export class AsarArtifactReader {
                     /^[a-f0-9]{64}$/u.test(metadata.integrity.hash)
                     ? metadata.integrity.hash
                     : null,
+                unpacked: "unpacked" in metadata && metadata.unpacked === true,
                 limitations: kind === "symlink"
                     ? ["ASAR symlink target was not followed or disclosed."]
                     : [

package/dist/artifacts/DirectoryArtifactReader.js

@@ -55,6 +55,7 @@ export class DirectoryArtifactReader {
                     encrypted: false,
                     byteOffset: null,
                     declaredSha256: null,
+                    unpacked: false,
                     limitations: kind === "symlink"
                         ? ["Symlink target was not followed or disclosed."]
                         : [],

package/dist/artifacts/MachOSliceArtifactReader.js

@@ -40,6 +40,7 @@ export class MachOSliceArtifactReader {
                 encrypted: false,
                 byteOffset: architecture.file_offset,
                 declaredSha256: null,
+                unpacked: false,
                 limitations: [],
                 adapterKey: `${String(architecture.file_offset)}:${String(architecture.size)}`,
             };

package/dist/artifacts/NativeDmgArtifactReader.js

@@ -0,0 +1,151 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { promisify } from "node:util";
+import { parse } from "plist";
+import { z } from "zod";
+import { ArtifactReaderFailure, } from "./ArtifactReader.js";
+import { DirectoryArtifactReader } from "./DirectoryArtifactReader.js";
+const execFileAsync = promisify(execFile);
+const attachOutputSchema = z.object({
+    "system-entities": z.array(z.object({
+        "dev-entry": z.string().startsWith("/dev/"),
+        "mount-point": z.string().optional(),
+    })),
+});
+const systemHost = {
+    async run(arguments_, signal) {
+        try {
+            const { stdout } = await execFileAsync("/usr/bin/hdiutil", [...arguments_], {
+                encoding: "utf8",
+                timeout: 120_000,
+                ...(signal === undefined ? {} : { signal }),
+            });
+            return { stdout, exitCode: 0 };
+        }
+        catch (cause) {
+            if (cause instanceof Error && cause.name === "AbortError")
+                throw new ArtifactReaderFailure("cancelled", "DMG operation cancelled");
+            throw new ArtifactReaderFailure("format", "hdiutil rejected the DMG", {
+                cause,
+            });
+        }
+    },
+};
+/** Read-only macOS DMG adapter that owns attachment and reverse-order detach. */
+export class NativeDmgArtifactReader {
+    path;
+    host;
+    format = "file";
+    #provenance = [];
+    #directory;
+    #devices = [];
+    #mountRoot;
+    constructor(path, host) {
+        this.path = path;
+        this.host = host;
+    }
+    /** Verify and attach one image beneath an exclusively owned temporary root. */
+    static async create(path, signal, host = systemHost) {
+        if (process.platform !== "darwin")
+            throw new ArtifactReaderFailure("unavailable", "Native DMG traversal is available only on macOS");
+        const reader = new NativeDmgArtifactReader(path, host);
+        await reader.attach(signal);
+        return reader;
+    }
+    async *entries(signal) {
+        if (this.#directory === undefined)
+            throw new ArtifactReaderFailure("unavailable", "DMG is not attached");
+        const prefix = basename(this.path);
+        for await (const entry of this.#directory.entries(signal))
+            yield { ...entry, path: `${prefix}/${entry.path}` };
+    }
+    open(entry, signal) {
+        if (this.#directory === undefined)
+            return Promise.reject(new ArtifactReaderFailure("unavailable", "DMG is not attached"));
+        return this.#directory.open(entry, signal);
+    }
+    provenance() {
+        return this.#provenance;
+    }
+    async close() {
+        let detachFailure;
+        for (const device of [...this.#devices].reverse()) {
+            try {
+                await runChecked(this.host, ["detach", device]);
+                this.#provenance.push(command(["detach", device], ["mount"]));
+            }
+            catch (cause) {
+                detachFailure ??= cause;
+            }
+        }
+        this.#devices = [];
+        if (this.#mountRoot !== undefined)
+            await rm(this.#mountRoot, { recursive: true, force: true }).catch((cause) => {
+                detachFailure ??= cause;
+            });
+        if (detachFailure !== undefined)
+            throw new ArtifactReaderFailure("unavailable", "DMG detach or mount-root cleanup failed", { cause: detachFailure });
+    }
+    async attach(signal) {
+        await runChecked(this.host, ["verify", this.path], signal);
+        this.#provenance.push(command(["verify", this.path], ["read"]));
+        this.#mountRoot = await mkdtemp(join(tmpdir(), "rea-dmg-"));
+        try {
+            const attached = await runChecked(this.host, [
+                "attach",
+                "-readonly",
+                "-nobrowse",
+                "-plist",
+                "-mountroot",
+                this.#mountRoot,
+                this.path,
+            ], signal);
+            const parsed = attachOutputSchema.parse(parse(attached.stdout));
+            this.#devices = parsed["system-entities"].map((entity) => entity["dev-entry"]);
+            if (this.#devices.length === 0)
+                throw new ArtifactReaderFailure("format", "hdiutil returned no attached devices");
+            for (const entity of parsed["system-entities"])
+                if (entity["mount-point"] !== undefined &&
+                    !entity["mount-point"].startsWith(`${this.#mountRoot}/`))
+                    throw new ArtifactReaderFailure("path", "hdiutil mounted outside the owned root");
+            this.#provenance.push(command([
+                "attach",
+                "-readonly",
+                "-nobrowse",
+                "-plist",
+                "-mountroot",
+                this.#mountRoot,
+                this.path,
+            ], ["read", "mount"]));
+            this.#directory = new DirectoryArtifactReader(this.#mountRoot);
+        }
+        catch (cause) {
+            let cleanupFailure;
+            try {
+                await this.close();
+            }
+            catch (cleanupCause) {
+                cleanupFailure = cleanupCause;
+            }
+            if (cleanupFailure !== undefined)
+                throw new ArtifactReaderFailure("unavailable", "DMG attach failed and cleanup could not detach every device", { cause: new AggregateError([cause, cleanupFailure]) });
+            throw cause;
+        }
+    }
+}
+const runChecked = async (host, arguments_, signal) => {
+    const result = await host.run(arguments_, signal);
+    if (result.exitCode !== 0)
+        throw new ArtifactReaderFailure("unavailable", `hdiutil ${arguments_[0] ?? "operation"} failed with a non-zero exit code`);
+    return { stdout: result.stdout, exitCode: 0 };
+};
+const command = (arguments_, effects) => ({
+    tool: "/usr/bin/hdiutil",
+    arguments: [...arguments_],
+    tool_version: null,
+    executable_sha256: null,
+    exit_code: 0,
+    effects,
+});

package/dist/artifacts/ZipArtifactReader.js

@@ -55,6 +55,7 @@ export class ZipArtifactReader {
                 encrypted: entry.encrypted,
                 byteOffset: null,
                 declaredSha256: null,
+                unpacked: false,
                 limitations: symlink ? ["Archive symlink target was not read."] : [],
                 adapterKey: entry.filename,
             };