rea-agents 0.3.0 → 0.5.0

package/dist/application/Uninstall.js

@@ -0,0 +1,130 @@
+import { copyFile, lstat, readFile, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, isAbsolute, join } from "node:path";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+import writeFileAtomic from "write-file-atomic";
+import { z } from "zod";
+import { PRODUCT_IDENTITY } from "../identity.js";
+import { supportedClients } from "./Setup.js";
+/** Remove only REA-owned registrations and managed files, optionally including local state. */
+export const runUninstall = async (purgeData, host = systemUninstallHost()) => {
+    const items = [];
+    for (const client of await host.clients())
+        items.push(await host.removeClient(client));
+    items.push(await host.removeSkill());
+    if (purgeData)
+        items.push(...(await host.purgeData()));
+    items.push({
+        name: "analysis_engine",
+        status: "retained",
+        detail: "Hopper is not owned by REA uninstall.",
+    });
+    return {
+        status: items.some(({ status }) => status === "failed")
+            ? "failed"
+            : "complete",
+        items,
+    };
+};
+/** Create uninstall effects contained to detected client configs and REA-owned paths. */
+export const systemUninstallHost = (home = homedir()) => ({
+    clients: () => Promise.resolve(supportedClients(home)),
+    removeClient,
+    removeSkill: () => removeManagedPath(join(home, ".agents/skills", PRODUCT_IDENTITY.skillName), "skill"),
+    purgeData: async () => [
+        await removeManagedPath(join(home, ".rea/cache"), "cache"),
+        await removeManagedPath(join(home, ".rea/state"), "state"),
+    ],
+});
+const removeClient = async (client) => {
+    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");
+    }
+    catch (cause) {
+        return isMissing(cause)
+            ? item(client.name, "skipped", "Configuration does not exist.")
+            : item(client.name, "failed", "Configuration could not be read.");
+    }
+    let document;
+    let key;
+    let servers;
+    try {
+        document = objectSchema.parse(client.format === "toml" ? parseToml(original) : JSON.parse(original));
+        key = client.format === "toml" ? "mcp_servers" : "mcpServers";
+        servers = optionalObject(document[key]);
+    }
+    catch {
+        return item(client.name, "failed", "Malformed configuration was preserved without mutation.");
+    }
+    const registration = servers[PRODUCT_IDENTITY.mcpServerKey];
+    if (registration === undefined)
+        return item(client.name, "skipped", "REA registration is absent.");
+    if (!isOwnedRegistration(registration))
+        return item(client.name, "retained", "The rea-named registration is not REA-owned.");
+    const remaining = { ...servers };
+    delete remaining[PRODUCT_IDENTITY.mcpServerKey];
+    document[key] = remaining;
+    const backupPath = `${client.configPath}.rea.backup`;
+    try {
+        await copyFile(client.configPath, backupPath);
+    }
+    catch {
+        return item(client.name, "failed", "Configuration backup failed; no mutation was attempted.");
+    }
+    try {
+        const encoded = client.format === "toml"
+            ? stringifyToml(document)
+            : `${JSON.stringify(document, null, 2)}\n`;
+        await writeFileAtomic(client.configPath, encoded, { encoding: "utf8" });
+        const readback = objectSchema.parse(client.format === "toml"
+            ? parseToml(await readFile(client.configPath, "utf8"))
+            : JSON.parse(await readFile(client.configPath, "utf8")));
+        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.`);
+    }
+};
+/** Ownership rule for persistent MCP registrations created by REA setup. */
+const isOwnedRegistration = (value) => {
+    const parsed = registrationSchema.safeParse(value);
+    if (!parsed.success)
+        return false;
+    const { command, args } = parsed.data;
+    return (((command === "rea" ||
+        (isAbsolute(command) && basename(command) === "rea")) &&
+        args.length === 1 &&
+        args[0] === "mcp") ||
+        (command === "npx" &&
+            JSON.stringify(args) ===
+                JSON.stringify(["-y", PRODUCT_IDENTITY.packageName, "mcp"])));
+};
+const removeManagedPath = async (path, name) => {
+    try {
+        const stats = await lstat(path);
+        if (stats.isSymbolicLink())
+            return item(name, "retained", `Refused to follow symlink ${path}.`);
+        await rm(path, { recursive: true });
+        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.`);
+    }
+};
+const item = (name, status, detail) => ({ name, status, detail });
+const objectSchema = z.record(z.string(), z.unknown());
+const optionalObject = (value) => value === undefined ? {} : objectSchema.parse(value);
+const registrationSchema = z
+    .object({ command: z.string(), args: z.array(z.string()) })
+    .passthrough();
+const isMissing = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";

package/dist/application/runtime.js

@@ -1,5 +1,8 @@
 import { BinarySession } from "./BinarySession.js";
 import { HopperProvider } from "../hopper/HopperProvider.js";
+import { NativeMacOSProvider } from "../native/NativeMacOSProvider.js";
+import { ArtifactProvider } from "../artifacts/ArtifactProvider.js";
+import { CompositeProvider } from "./CompositeProvider.js";
 import { silentLogger } from "../logger.js";
 /**
  * Compose the target-switching runtime shared directly by CLI and MCP adapters.
@@ -7,5 +10,9 @@ import { silentLogger } from "../logger.js";
  * out to the other and both retain identical loader and bridge semantics.
  */
 export const createBinarySession = (config, logger = silentLogger) => {
-    return new BinarySession(new HopperProvider(config, logger));
+    return new BinarySession(new CompositeProvider([
+        new ArtifactProvider(),
+        new NativeMacOSProvider(),
+        new HopperProvider(config, logger),
+    ]));
 };

package/dist/artifacts/ArtifactPaths.js

@@ -0,0 +1,51 @@
+import { Buffer } from "node:buffer";
+import { posix } from "node:path";
+import { ArtifactReaderFailure, } from "./ArtifactReader.js";
+const DRIVE_OR_UNC = /^(?:[A-Za-z]:|\\|\/\/)/u;
+/** Normalize an untrusted logical archive path without touching filesystem. */
+export const normalizeArtifactPath = (input, limits) => {
+    if (input.includes("\0") ||
+        input.includes("\\") ||
+        input.startsWith("/") ||
+        DRIVE_OR_UNC.test(input))
+        throw new ArtifactReaderFailure("path", "Artifact path is absolute or unsafe");
+    const normalized = input.normalize("NFC").replace(/\/+$/u, "");
+    const parts = normalized.split("/");
+    if (normalized.length === 0 ||
+        parts.some((part) => part === "" || part === "." || part === "..") ||
+        parts.length > limits.maxDepth ||
+        Buffer.byteLength(normalized, "utf8") > limits.maxPathBytes ||
+        posix.normalize(normalized) !== normalized)
+        throw new ArtifactReaderFailure("path", "Artifact path is not normalized");
+    return normalized;
+};
+/** Reject exact, Unicode-normalized, case-folded, and prefix collisions. */
+export class ArtifactPathRegistry {
+    #root = { kind: undefined, children: new Map() };
+    #folded = new Set();
+    add(path, kind) {
+        const folded = path.toLocaleLowerCase("en-US");
+        if (this.#folded.has(folded))
+            throw new ArtifactReaderFailure("path", `Artifact path collision: ${path}`);
+        const parts = path.split("/");
+        let node = this.#root;
+        for (const [index, part] of parts.entries()) {
+            if (node.kind !== undefined && node.kind !== "directory")
+                throw new ArtifactReaderFailure("path", `Artifact prefix conflict: ${path}`);
+            let child = node.children.get(part);
+            if (child === undefined) {
+                child = { kind: undefined, children: new Map() };
+                node.children.set(part, child);
+            }
+            node = child;
+            if (index === parts.length - 1) {
+                if (node.kind !== undefined)
+                    throw new ArtifactReaderFailure("path", `Artifact path collision: ${path}`);
+                if (kind !== "directory" && node.children.size > 0)
+                    throw new ArtifactReaderFailure("path", `Artifact prefix conflict: ${path}`);
+            }
+        }
+        node.kind = kind;
+        this.#folded.add(folded);
+    }
+}

package/dist/artifacts/ArtifactProvider.js

@@ -0,0 +1,130 @@
+import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
+import { inventoryArtifact } from "../application/ArtifactInventory.js";
+import { extractArtifact } from "../application/ArtifactExtraction.js";
+import { ARTIFACT_TOOL_CONTRACTS, artifactInventoryInputSchema, artifactExtractionInputSchema, } from "../contracts/artifactToolContracts.js";
+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",
+});
+/** Read-only inventory and exclusively owned extraction provider. */
+export class ArtifactProvider {
+    #capabilities = Object.freeze(ARTIFACT_TOOL_CONTRACTS.map((contract) => Object.freeze({
+        provider: IDENTITY,
+        operation: contract.name,
+        inputContractVersion: 1,
+        outputContractVersion: 1,
+        available: true,
+        reason: null,
+        pagination: "offset",
+        exhaustive: false,
+        effects: Object.freeze({
+            mutatesArtifact: false,
+            launchesProcess: true,
+            mayShowUi: false,
+            mayAccessNetwork: false,
+            mayWriteFilesystem: contract.name === "extract_artifact",
+            changesPermissions: false,
+            requiresRoot: false,
+        }),
+        limits: Object.freeze({
+            maxResults: 500,
+            maxPayloadBytes: 4 * 1024 * 1024,
+            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.",
+        ]),
+    })));
+    identity() {
+        return IDENTITY;
+    }
+    capabilities() {
+        return this.#capabilities;
+    }
+    createClient(target) {
+        return new ArtifactClient(target);
+    }
+}
+class ArtifactClient {
+    target;
+    constructor(target) {
+        this.target = target;
+    }
+    async execute(operation, parameters, options) {
+        if (operation === "health")
+            return ok(createAnalysisExecution(null, IDENTITY));
+        if (!isArtifactOperation(operation))
+            return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, "Operation is not implemented by artifact graph provider."));
+        try {
+            if (operation === "extract_artifact") {
+                const parsed = artifactExtractionInputSchema.parse(parameters);
+                const result = await extractArtifact({
+                    inputPath: this.target.sourcePath ?? this.target.path,
+                    inputFormat: this.target.format,
+                    outputRoot: parsed.output_root,
+                    occurrenceIds: parsed.occurrence_ids,
+                    offset: parsed.offset,
+                    limit: parsed.limit,
+                    limits: limitsFrom(parsed),
+                }, options?.signal);
+                return ok(createAnalysisExecution(result, IDENTITY, {
+                    rawResult: null,
+                    limitations: result.limitations,
+                    subject: subjectFor(this.target.sourcePath ?? this.target.path, result.manifest),
+                    locations: result.artifacts.items.map(({ relative_path: path }) => ({
+                        kind: "artifact-path",
+                        path,
+                    })),
+                }));
+            }
+            const parsed = artifactInventoryInputSchema.parse(parameters);
+            const result = await inventoryArtifact(this.target.sourcePath ?? this.target.path, limitsFrom(parsed), {
+                nodeOffset: parsed.node_offset,
+                nodeLimit: parsed.node_limit,
+                occurrenceOffset: parsed.occurrence_offset,
+                occurrenceLimit: parsed.occurrence_limit,
+                edgeOffset: parsed.edge_offset,
+                edgeLimit: parsed.edge_limit,
+            }, options?.signal);
+            return ok(createAnalysisExecution(result, IDENTITY, {
+                rawResult: null,
+                limitations: result.limitations,
+                subject: subjectFor(this.target.sourcePath ?? this.target.path, result.manifest),
+                locations: result.occurrences.items.map(({ logical_path: path }) => ({
+                    kind: "artifact-path",
+                    path,
+                })),
+            }));
+        }
+        catch (cause) {
+            return err(translateFailure(operation, cause));
+        }
+    }
+    close() {
+        return Promise.resolve();
+    }
+}
+const limitsFrom = (input) => ({
+    maxEntries: input.max_entries,
+    maxTotalBytes: input.max_total_bytes,
+    maxEntryBytes: input.max_entry_bytes,
+    maxCompressionRatio: input.max_compression_ratio,
+    maxDepth: input.max_depth,
+    maxPathBytes: input.max_path_bytes,
+});
+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, "io");
+};
+const subjectFor = (path, manifest) => ({
+    path,
+    sha256: manifest.root_sha256,
+    format: manifest.root_format,
+});

package/dist/artifacts/ArtifactReader.js

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

package/dist/artifacts/AsarArtifactReader.js

@@ -0,0 +1,62 @@
+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. */
+export class AsarArtifactReader {
+    path;
+    format = "asar";
+    constructor(path) {
+        this.path = path;
+    }
+    async *entries(signal) {
+        const paths = listPackage(this.path, { isPack: false }).sort((left, right) => left.localeCompare(right, "en"));
+        for (const listed of paths) {
+            abortIfNeeded(signal);
+            const path = listed.replace(/^\/+|\/+$/gu, "");
+            if (path.length === 0)
+                continue;
+            const metadata = statFile(this.path, path, false);
+            const kind = "files" in metadata
+                ? "directory"
+                : "link" in metadata
+                    ? "symlink"
+                    : "file";
+            yield {
+                path,
+                kind,
+                declaredSize: "size" in metadata ? metadata.size : null,
+                compressedSize: null,
+                executable: "executable" in metadata && metadata.executable,
+                encrypted: false,
+                byteOffset: null,
+                declaredSha256: "integrity" in metadata &&
+                    metadata.integrity.algorithm === "SHA256" &&
+                    /^[a-f0-9]{64}$/u.test(metadata.integrity.hash)
+                    ? metadata.integrity.hash
+                    : null,
+                limitations: kind === "symlink"
+                    ? ["ASAR symlink target was not followed or disclosed."]
+                    : [
+                        "Official ASAR extraction buffers each individually bounded file.",
+                    ],
+                adapterKey: path,
+            };
+        }
+    }
+    open(entry, signal) {
+        abortIfNeeded(signal);
+        if (entry.kind !== "file")
+            return Promise.reject(new ArtifactReaderFailure("format", "ASAR entry is not a regular file"));
+        return Promise.resolve(Readable.from(extractFile(this.path, entry.adapterKey, false)));
+    }
+    close() {
+        return Promise.resolve();
+    }
+    provenance() {
+        return [];
+    }
+}
+const abortIfNeeded = (signal) => {
+    if (signal?.aborted === true)
+        throw new ArtifactReaderFailure("cancelled", "ASAR operation cancelled");
+};

package/dist/artifacts/DirectoryArtifactReader.js

@@ -0,0 +1,107 @@
+import { constants } from "node:fs";
+import { lstat, open, opendir, realpath } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { ArtifactReaderFailure, } from "./ArtifactReader.js";
+/** Deterministic, non-symlink-following directory reader. */
+export class DirectoryArtifactReader {
+    format = "directory";
+    #rootPromise;
+    constructor(root) {
+        this.#rootPromise = realpath(root);
+    }
+    async *entries(signal) {
+        const root = await this.#rootPromise;
+        const pending = [root];
+        while (pending.length > 0) {
+            abortIfNeeded(signal);
+            const directory = pending.pop();
+            if (directory === undefined)
+                break;
+            await assertContainedDirectory(root, directory);
+            const children = [];
+            const handle = await opendir(directory);
+            try {
+                for await (const child of handle)
+                    children.push(child.name);
+            }
+            finally {
+                await handle.close().catch(() => undefined);
+            }
+            await assertContainedDirectory(root, directory);
+            children.sort((left, right) => left.localeCompare(right, "en"));
+            const directories = [];
+            for (const name of children) {
+                abortIfNeeded(signal);
+                const absolute = join(directory, name);
+                const metadata = await lstat(absolute);
+                const path = relative(root, absolute).split(sep).join("/");
+                const kind = metadata.isSymbolicLink()
+                    ? "symlink"
+                    : metadata.isDirectory()
+                        ? "directory"
+                        : metadata.isFile()
+                            ? "file"
+                            : undefined;
+                if (kind === undefined)
+                    continue;
+                if (kind === "directory")
+                    directories.push(absolute);
+                yield {
+                    path,
+                    kind,
+                    declaredSize: kind === "file" ? metadata.size : null,
+                    compressedSize: null,
+                    executable: (metadata.mode & 0o111) !== 0,
+                    encrypted: false,
+                    byteOffset: null,
+                    declaredSha256: null,
+                    limitations: kind === "symlink"
+                        ? ["Symlink target was not followed or disclosed."]
+                        : [],
+                    adapterKey: absolute,
+                    ...(kind === "file"
+                        ? { sourceIdentity: { device: metadata.dev, inode: metadata.ino } }
+                        : {}),
+                };
+            }
+            directories.reverse();
+            pending.push(...directories);
+        }
+    }
+    async open(entry, signal) {
+        abortIfNeeded(signal);
+        if (entry.kind !== "file")
+            throw new ArtifactReaderFailure("format", "Only regular files can be opened");
+        const handle = await open(entry.adapterKey, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const observed = await handle.stat();
+        if (!observed.isFile() ||
+            entry.sourceIdentity === undefined ||
+            observed.dev !== entry.sourceIdentity.device ||
+            observed.ino !== entry.sourceIdentity.inode) {
+            await handle.close();
+            throw new ArtifactReaderFailure("integrity", `Directory entry changed before open: ${entry.path}`);
+        }
+        return handle.createReadStream({ autoClose: true });
+    }
+    close() {
+        return Promise.resolve();
+    }
+    provenance() {
+        return [];
+    }
+}
+const abortIfNeeded = (signal) => {
+    if (signal?.aborted === true)
+        throw new ArtifactReaderFailure("cancelled", "Artifact traversal cancelled");
+};
+const assertContainedDirectory = async (root, directory) => {
+    const canonical = await realpath(directory);
+    const fromRoot = relative(root, canonical);
+    const metadata = await lstat(directory);
+    if (metadata.isSymbolicLink() ||
+        !metadata.isDirectory() ||
+        fromRoot === ".." ||
+        fromRoot.startsWith(`..${sep}`) ||
+        isAbsolute(fromRoot))
+        throw new ArtifactReaderFailure("path", "Directory traversal escaped or changed its artifact root");
+};

package/dist/artifacts/MachOSliceArtifactReader.js

@@ -0,0 +1,66 @@
+import { createReadStream } from "node:fs";
+import { XcrunCommandRunner, } from "../native/CommandRunner.js";
+import { parseLipoArchitectures } from "../native/parsers/lipo.js";
+import { ArtifactReaderFailure, } from "./ArtifactReader.js";
+/** Read-only universal Mach-O slice reader backed by native lipo metadata. */
+export class MachOSliceArtifactReader {
+    path;
+    runner;
+    format = "file";
+    #command;
+    constructor(path, runner = new XcrunCommandRunner()) {
+        this.path = path;
+        this.runner = runner;
+    }
+    async *entries(signal) {
+        const captured = await this.runner.run("lipo", ["-detailed_info", this.path], {
+            ...(signal === undefined ? {} : { signal }),
+            timeoutMs: 30_000,
+            maxOutputBytes: 4 * 1024 * 1024,
+        });
+        if (!captured.ok)
+            throw new ArtifactReaderFailure(captured.error.reason === "cancelled" ? "cancelled" : "unavailable", "lipo could not enumerate universal Mach-O slices", { cause: captured.error });
+        this.#command = {
+            tool: captured.value.tool,
+            arguments: ["-detailed_info", "$ARTIFACT"],
+            tool_version: captured.value.toolVersion,
+            executable_sha256: captured.value.executableSha256,
+            exit_code: captured.value.exitCode,
+            effects: ["read"],
+        };
+        for (const architecture of parseLipoArchitectures(captured.value.stdout)) {
+            if (architecture.file_offset === null || architecture.size === null)
+                throw new ArtifactReaderFailure("integrity", "lipo omitted a universal slice byte range");
+            yield {
+                path: `slices/${architecture.name}`,
+                kind: "slice",
+                declaredSize: architecture.size,
+                compressedSize: null,
+                executable: true,
+                encrypted: false,
+                byteOffset: architecture.file_offset,
+                declaredSha256: null,
+                limitations: [],
+                adapterKey: `${String(architecture.file_offset)}:${String(architecture.size)}`,
+            };
+        }
+    }
+    open(entry, signal) {
+        if (signal?.aborted === true)
+            return Promise.reject(new ArtifactReaderFailure("cancelled", "Mach-O slice read cancelled"));
+        const [offsetText, sizeText] = entry.adapterKey.split(":");
+        const offset = Number(offsetText);
+        const size = Number(sizeText);
+        if (!Number.isSafeInteger(offset) ||
+            !Number.isSafeInteger(size) ||
+            size <= 0)
+            return Promise.reject(new ArtifactReaderFailure("integrity", "Invalid Mach-O slice byte range"));
+        return Promise.resolve(createReadStream(this.path, { start: offset, end: offset + size - 1 }));
+    }
+    provenance() {
+        return this.#command === undefined ? [] : [this.#command];
+    }
+    close() {
+        return Promise.resolve();
+    }
+}