rea-agents 1.2.0 → 1.3.0

package/dist/application/ProcessCli.js

@@ -1,42 +1,69 @@
 import { readFile } from "node:fs/promises";
 import { parseConfig } from "../config.js";
+import { AnalysisError, projectAnalysisError } from "../domain/errors.js";
 import { createEvidence, parseEvidence } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { compareProcessCaptures, LEGACY_PROCESS_CAPTURE_MESSAGE, parseProcessScenario, parseProcessCapture, } from "../domain/processCapture.js";
 import { captureProcessScenario } from "./ProcessHarness.js";
 import { PROCESS_PROVIDER, createProcessCaptureEvidence, } from "./ProcessEvidence.js";
 const MAX_INPUT_BYTES = 64 * 1024 * 1024;
+/** Distinguish a safe process-command failure from successful Evidence. */
+export const isProcessCliErrorOutput = (value) => typeof value === "object" &&
+    value !== null &&
+    "error" in value &&
+    value.error === "Process command failed" &&
+    "category" in value &&
+    typeof value.category === "string" &&
+    "message" in value &&
+    typeof value.message === "string";
 /** Capture one JSON scenario through the same policy and evidence contract as MCP. */
 export const captureProcessScenarioFile = async (path) => {
-    const scenario = parseProcessScenario(await readJson(path));
-    const config = parseConfig(process.env);
-    if (!config.ok)
-        throw config.error;
-    const captured = await captureProcessScenario(scenario, config.value.processExecutionPolicy);
-    if (!captured.ok)
-        throw captured.error;
-    return createProcessCaptureEvidence(scenario, captured.value);
+    try {
+        const input = await readJson(path);
+        let scenario;
+        try {
+            scenario = parseProcessScenario(input);
+        }
+        catch {
+            throw new ProcessCliFailure("invalid_input", "Process scenario is invalid. Check its required fields and limits, then try again.");
+        }
+        const config = parseConfig(process.env);
+        if (!config.ok)
+            return cliAnalysisError(config.error);
+        const captured = await captureProcessScenario(scenario, config.value.processExecutionPolicy);
+        if (!captured.ok)
+            return cliAnalysisError(captured.error);
+        return createProcessCaptureEvidence(scenario, captured.value);
+    }
+    catch (cause) {
+        return projectProcessCliError(cause);
+    }
 };
 /** Compare two capture Evidence files and emit derived comparison Evidence. */
 export const compareProcessEvidenceFiles = async (leftPath, rightPath) => {
-    const left = parseCaptureEvidence(await readJson(leftPath));
-    const right = parseCaptureEvidence(await readJson(rightPath));
-    const comparison = compareProcessCaptures(left.capture, right.capture);
-    return createEvidence(undefined, PROCESS_PROVIDER, {
-        predicateType: "rea.process-comparison/v3",
-        operation: "compare_process_captures",
-        parameters: {
-            left_evidence_id: left.id,
-            right_evidence_id: right.id,
-            left_normalization: left.capture.normalization,
-            right_normalization: right.capture.normalization,
-        },
-        result: jsonValueSchema.parse(comparison),
-        confidence: "derived",
-        authority: "analyst-inference",
-        limitations: comparison.limitations,
-        evidenceLinks: [left.id, right.id],
-    });
+    try {
+        const left = parseCaptureEvidence(await readJson(leftPath));
+        const right = parseCaptureEvidence(await readJson(rightPath));
+        const comparison = compareProcessCaptures(left.capture, right.capture);
+        return createEvidence(undefined, PROCESS_PROVIDER, {
+            predicateType: "rea.process-comparison/v3",
+            operation: "compare_process_captures",
+            parameters: {
+                left_evidence_id: left.id,
+                right_evidence_id: right.id,
+                left_normalization: left.capture.normalization,
+                right_normalization: right.capture.normalization,
+            },
+            result: jsonValueSchema.parse(comparison),
+            confidence: "derived",
+            authority: "analyst-inference",
+            limitations: comparison.limitations,
+            evidenceLinks: [left.id, right.id],
+        });
+    }
+    catch (cause) {
+        return projectProcessCliError(cause);
+    }
 };
 const parseCaptureEvidence = (input) => {
     const evidence = parseEvidence(input);
@@ -45,8 +72,8 @@ const parseCaptureEvidence = (input) => {
         evidence.provider.id !== PROCESS_PROVIDER.id ||
         evidence.provider.version !== PROCESS_PROVIDER.version) {
         if (evidence.predicate_type === "rea.process-capture/v3")
-            throw new TypeError(LEGACY_PROCESS_CAPTURE_MESSAGE);
-        throw new TypeError("Expected REA Process Capture v4 Evidence");
+            throw new ProcessCliFailure("invalid_input", LEGACY_PROCESS_CAPTURE_MESSAGE);
+        throw new ProcessCliFailure("invalid_input", "Capture evidence is not from the current process-capture workflow. Create new capture evidence, then try again.");
     }
     return {
         id: evidence.evidence_id,
@@ -54,8 +81,48 @@ const parseCaptureEvidence = (input) => {
     };
 };
 const readJson = async (path) => {
-    const bytes = await readFile(path);
+    let bytes;
+    try {
+        bytes = await readFile(path);
+    }
+    catch {
+        throw new ProcessCliFailure("invalid_input", "Process input file could not be read. Check that the path exists and is readable.");
+    }
     if (bytes.length > MAX_INPUT_BYTES)
-        throw new TypeError("Process JSON input exceeds byte limit");
-    return JSON.parse(bytes.toString("utf8"));
+        throw new ProcessCliFailure("truncated", "Process input file is too large. Reduce it below 64 MiB, then try again.");
+    try {
+        return JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        throw new ProcessCliFailure("invalid_input", "Process input file is not valid JSON. Repair the file, then try again.");
+    }
+};
+class ProcessCliFailure extends Error {
+    category;
+    userMessage;
+    constructor(category, userMessage) {
+        super(userMessage);
+        this.category = category;
+        this.userMessage = userMessage;
+    }
+}
+const cliAnalysisError = (error) => ({
+    error: "Process command failed",
+    ...projectAnalysisError(error),
+});
+/** Project any process CLI failure without exposing its cause. */
+export const projectProcessCliError = (cause) => {
+    if (cause instanceof ProcessCliFailure)
+        return {
+            error: "Process command failed",
+            category: cause.category,
+            message: cause.userMessage,
+        };
+    if (cause instanceof AnalysisError)
+        return cliAnalysisError(cause);
+    return {
+        error: "Process command failed",
+        category: "execution_failure",
+        message: "Process command could not complete. Check the input files and run `rea doctor`, then try again.",
+    };
 };

package/dist/application/ProcessHarness.js

@@ -1,7 +1,7 @@
 import { spawn } from "node-pty";
 import { validateProcessCapture } from "../domain/processCapture.js";
 import { err, ok } from "../domain/result.js";
-import { ProcessCaptureError } from "./ProcessCaptureError.js";
+import { ProcessCaptureError, processCaptureCancelled, } from "./ProcessCaptureError.js";
 export { ProcessCaptureError } from "./ProcessCaptureError.js";
 import { startLoopbackReplay } from "./LoopbackReplay.js";
 import { startProcessSampler } from "./ProcessSampling.js";
@@ -218,7 +218,7 @@ const completeCapture = async (options) => {
     runtime.checkpoints.trigger("root_exit");
     const { reason } = options.exit;
     if (reason === "cancelled")
-        throw new ProcessCaptureError("process capture was cancelled");
+        throw processCaptureCancelled();
     const settlement = await observeSettlement(options.runId, [
         runtime.terminal.pid,
         ...options.samples.flatMap(({ process_group_id }) => process_group_id === null ? [] : [process_group_id]),

package/dist/application/ReferenceSourceImportEntries.js

@@ -3,16 +3,31 @@ import { posix } from "node:path";
 import { classifyReferenceSourcePath, detectReferenceSourceLanguage, } from "../domain/referenceSourceClassification.js";
 import { parseReferenceSourceImports } from "../domain/referenceSourceImportParsing.js";
 import { PARSEABLE_REFERENCE_SOURCE_LANGUAGES } from "./ReferenceSourceImportTypes.js";
+/** Project a low-level entry failure into safe import guidance. */
+export const projectReferenceSourceEntryFailure = (entry) => {
+    if (entry.code === "cancelled")
+        return "This entry was not read because the import was cancelled. Start the import again when ready.";
+    if (entry.code === "limit")
+        return "This entry was not read because an import limit was reached. Import a smaller directory or raise the configured limits.";
+    if (entry.code === "unsupported")
+        return "This entry cannot be read safely on this system. Exclude it or import the directory on a supported system.";
+    if (entry.kind === "directory")
+        return "This directory could not be read. Check its permissions, then try again.";
+    if (entry.kind === "symlink")
+        return "This symbolic link could not be read safely. Check the link and its permissions, then try again.";
+    return "This file could not be read. Check its permissions, then try again.";
+};
 const hashBytes = (bytes) => createHash("sha256").update(bytes).digest("hex");
 const failedEntry = (entry) => {
     const classifications = classifyReferenceSourcePath(entry.path);
+    const limitation = projectReferenceSourceEntryFailure(entry);
     if (entry.kind === "directory")
         return {
             path: entry.path,
             kind: "directory",
             classifications,
             tree_state: entry.code === "limit" ? "partial" : "unreadable",
-            limitations: [entry.message],
+            limitations: [limitation],
         };
     if (entry.kind === "symlink")
         return {
@@ -21,7 +36,7 @@ const failedEntry = (entry) => {
             target: "<unreadable>",
             target_state: "unreadable",
             classifications,
-            limitations: [entry.message],
+            limitations: [limitation],
         };
     return {
         path: entry.path,
@@ -31,7 +46,7 @@ const failedEntry = (entry) => {
         language: null,
         classifications: entry.kind === "file" ? classifications : ["unknown"],
         content_state: entry.code === "limit" ? "too-large" : "unreadable",
-        limitations: [entry.message],
+        limitations: [limitation],
     };
 };
 const resolveInternalSpecifier = (fromPath, specifier, filePaths) => {

package/dist/application/ReferenceSourceImportTypes.js

@@ -1,3 +1,35 @@
+/** Safe CLI projection for a historical-source import failure. */
+export const projectReferenceSourceImportError = (error) => {
+    if (error.code === "cancelled")
+        return {
+            category: "cancelled",
+            message: "Reference source import was cancelled. Start it again when ready.",
+        };
+    if (error.code === "invalid-limits")
+        return {
+            category: "invalid_input",
+            message: "Reference source limits are invalid. Use positive integer limits, then try again.",
+        };
+    if (error.code === "invalid-root")
+        return {
+            category: "invalid_input",
+            message: "Reference source directory could not be opened. Check that the path exists, is readable, and points to a directory.",
+        };
+    if (error.code === "policy")
+        return {
+            category: "permission_required",
+            message: "Reference source directory is not approved. Add its directory to `REA_REFERENCE_ROOTS_JSON`, restart REA, then try again.",
+        };
+    if (error.code === "io")
+        return {
+            category: "execution_failure",
+            message: "Reference source files could not be read. Check directory permissions and try again.",
+        };
+    return {
+        category: "execution_failure",
+        message: "Reference source could not be indexed. Check that the source tree is readable, then try again.",
+    };
+};
 export const DEFAULT_REFERENCE_SOURCE_IGNORE_PATTERNS = [
     ".git/",
     ".git/hooks/",

package/dist/application/Setup.js

@@ -9,50 +9,14 @@ import { supportsNodeVersion } from "../domain/runtimeVersion.js";
 import { runDoctor, systemDoctorHost } from "./Doctor.js";
 import { installLinuxHopper, readLinuxDistribution, } from "./LinuxHopper.js";
 import { installMacHopper } from "./MacHopper.js";
+import { configureDetectedClients } from "./SetupClients.js";
 import { installCanonicalSkill } from "./SetupSkill.js";
+import { setupPlan } from "./SetupPlan.js";
+import { setupInstallFailure, } from "./SetupInstallFailure.js";
 export { installCanonicalSkill } from "./SetupSkill.js";
 const registrationCommand = () => process.env.npm_command === "exec"
     ? ["npx", "-y", PRODUCT_IDENTITY.packageName, "mcp"]
     : [resolve(process.argv[1] ?? PRODUCT_IDENTITY.cliBinary), "mcp"];
-const setupPlan = (platform, hopperPath, clients) => [
-    ...(hopperPath === undefined
-        ? [
-            {
-                kind: "install_hopper",
-                target: platform === "darwin"
-                    ? "~/Applications/Hopper Disassembler.app"
-                    : "system package manager",
-                detail: "Download the official Hopper package, verify it, install it, and open Hopper for activation.",
-                external: true,
-            },
-        ]
-        : []),
-    ...clients
-        .filter(({ format }) => format !== "unsupported")
-        .map((client) => ({
-        kind: "configure_client",
-        target: client.configPath,
-        detail: `Add the REA MCP registration for ${client.name}; preserve unrelated configuration.`,
-        external: false,
-    })),
-    {
-        kind: "install_skill",
-        target: "~/.agents/skills/rea-analysis/SKILL.md",
-        detail: "Install or update the bundled REA analysis skill.",
-        external: false,
-    },
-];
-const configureDetectedClients = async (options) => {
-    for (const client of options.detectedClients) {
-        const result = await options.host.configureClient(client, options.hopperPath, registrationCommand());
-        options.clients[client.name] = result;
-        if (result.status === "failed")
-            return `${client.name} configuration ${result.reason} verification failed; no successful configuration was reported.`;
-        if (result.status === "configured")
-            options.appliedActions.push(`configured_${client.name}`);
-    }
-    return undefined;
-};
 /**
  * Install prerequisites and configure detected clients idempotently.
  * Discovery always precedes mutation. Interactive confirmation or explicit
@@ -74,8 +38,13 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
     if (unsupported !== undefined)
         return fail(unsupported);
     let hopperPath = await host.hopperPath();
+    const initialDoctor = await host.doctor();
+    const linuxHopperRepairNeeded = initialDoctor.checks.some(({ name, ok, detail }) => !ok &&
+        (name === "hopper-demo-runtime" ||
+            (name === "hopper-version" && detail === "/opt/hopper/bin/Hopper")));
+    const installHopper = hopperPath === undefined || linuxHopperRepairNeeded;
     const detectedClients = await host.detectedClients();
-    plannedActions = setupPlan(host.platform, hopperPath, detectedClients);
+    plannedActions = setupPlan(host.platform, installHopper, detectedClients);
     let approved = options.approved;
     let interactiveApproval = false;
     if (!approved && confirm !== undefined && !options.structured) {
@@ -91,24 +60,26 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
             doctor: await host.doctor(),
             remediation: "Review the setup plan, then rerun interactively or with --yes.",
         };
-    if (hopperPath === undefined &&
-        (interactiveApproval || options.installHopper)) {
-        hopperPath = await host.installHopper();
-        if (hopperPath === undefined)
+    if (installHopper && (interactiveApproval || options.installHopper)) {
+        const installed = await host.installHopper();
+        if (installed.status === "failed")
             return {
                 status: "needs_human",
                 plannedActions,
                 appliedActions,
                 clients,
                 doctor: await host.doctor(),
-                remediation: "Hopper installation failed; install Hopper manually or rerun setup after resolving the reported system error.",
+                code: installed.code,
+                remediation: installed.remediation,
             };
+        hopperPath = installed.launcherPath;
         appliedActions.push("installed_hopper");
     }
     const clientFailure = await configureDetectedClients({
         host,
         detectedClients,
         hopperPath,
+        command: registrationCommand(),
         clients,
         appliedActions,
     });
@@ -116,29 +87,29 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
         return fail(clientFailure);
     const skill = await host.installSkill();
     if (skill === "failed")
-        return fail("Agent skill installation or readback failed.");
+        return fail("REA analysis skill could not be installed or verified. Check permissions for `~/.agents/skills`, then rerun setup.");
     if (skill === "installed")
         appliedActions.push("installed_skill");
     const doctor = await host.doctor();
-    const activationRequired = appliedActions.includes("installed_hopper");
-    const ready = doctor.healthy && !activationRequired;
+    const remediation = finalSetupRemediation(host.platform, appliedActions.includes("installed_hopper"), doctor.healthy, hopperPath);
     return {
-        status: ready ? "ready" : "needs_human",
+        status: remediation === undefined ? "ready" : "needs_human",
         plannedActions,
         appliedActions,
         clients,
         doctor,
-        ...(ready
-            ? {}
-            : {
-                remediation: activationRequired
-                    ? "Open Hopper, complete its one-time activation, then rerun rea doctor --json."
-                    : hopperPath === undefined
-                        ? "Hopper is optional for non-Hopper providers. Rerun with --yes --install-hopper for deep native analysis."
-                        : "Run rea doctor and apply each reported remediation.",
-            }),
+        ...(remediation === undefined ? {} : { remediation }),
     };
 };
+const finalSetupRemediation = (platform, installedHopper, healthy, hopperPath) => {
+    if (platform === "darwin" && installedHopper)
+        return "Open Hopper, choose its demo mode or activate a license, then rerun rea doctor --json.";
+    if (healthy)
+        return undefined;
+    return hopperPath === undefined
+        ? "Hopper is optional for non-Hopper providers. Rerun with --yes --install-hopper for deep native analysis."
+        : "Run rea doctor and apply each reported remediation.";
+};
 const hostRemediation = async (host) => {
     if (host.platform !== "darwin" && host.platform !== "linux")
         return "REA supports Hopper on macOS and selected 64-bit Linux distributions.";
@@ -167,7 +138,9 @@ const systemSetupHost = () => {
             const result = process.platform === "linux"
                 ? await installLinuxHopper()
                 : await installMacHopper();
-            return result.status === "installed" ? result.launcherPath : undefined;
+            if (result.status === "installed")
+                return result;
+            return setupInstallFailure(result.reason);
         },
         detectedClients: () => detectClients(homedir()),
         configureClient: (client, hopperPath, command) => client.format === "unsupported"
@@ -179,7 +152,7 @@ const systemSetupHost = () => {
         doctor: () => runDoctor(undefined, doctorHost),
     };
 };
-/** Detect supported coding agents from stable per-user installation markers. */
+/** Detect supported agents from stable per-user installation markers. */
 export const detectClients = async (home) => {
     const detected = [];
     for (const candidate of supportedClients(home))

package/dist/application/SetupClients.js

@@ -0,0 +1,19 @@
+const failedConfigurationMessage = (reason) => {
+    if (reason === "backup")
+        return "Agent configuration could not be backed up, so no change was made. Check file permissions, then rerun setup.";
+    if (reason === "write")
+        return "Agent configuration could not be updated. Check file permissions, then rerun setup.";
+    return "Agent configuration could not be verified after writing. Repair the configuration file or restore its `.rea.backup`, then rerun setup.";
+};
+/** Configure each detected agent, stopping after the first failed transaction. */
+export const configureDetectedClients = async (options) => {
+    for (const client of options.detectedClients) {
+        const result = await options.host.configureClient(client, options.hopperPath, options.command);
+        options.clients[client.name] = result;
+        if (result.status === "failed")
+            return failedConfigurationMessage(result.reason);
+        if (result.status === "configured")
+            options.appliedActions.push(`configured_${client.name}`);
+    }
+    return undefined;
+};

package/dist/application/SetupInstallFailure.js

@@ -0,0 +1,53 @@
+/** Map provider installer failures to stable setup codes and safe recovery. */
+export const setupInstallFailure = (reason) => {
+    switch (reason) {
+        case "unsupported_host":
+            return {
+                status: "failed",
+                code: "unsupported_host",
+                remediation: "Use a supported host, then rerun rea setup.",
+            };
+        case "integrity":
+            return {
+                status: "failed",
+                code: "integrity_mismatch",
+                remediation: "The Hopper download failed integrity verification. Retry setup; if it repeats, update REA before installing.",
+            };
+        case "authorization_or_package_manager":
+            return {
+                status: "failed",
+                code: "authorization_or_package_manager_failed",
+                remediation: "Allow the system package-manager operation or install the planned Hopper package and Linux runtime dependencies, then rerun rea setup.",
+            };
+        case "launcher_missing":
+            return {
+                status: "failed",
+                code: "launcher_missing",
+                remediation: "The package operation completed but Hopper is not runnable. Run rea doctor and repair the reported launcher issue.",
+            };
+        case "runtime_dependencies":
+            return {
+                status: "failed",
+                code: "runtime_dependency_unavailable",
+                remediation: "Hopper was installed but required shared libraries are missing. Rerun rea setup, then apply the hopper-demo-runtime remediation from rea doctor.",
+            };
+        case "unsupported_hopper_build":
+            return {
+                status: "failed",
+                code: "unsupported_hopper_build",
+                remediation: "The installed Hopper launcher does not match the build supported by this REA release. Unset HOPPER_LAUNCHER_PATH, reinstall through rea setup, or update REA.",
+            };
+        case "cancelled":
+            return {
+                status: "failed",
+                code: "setup_cancelled",
+                remediation: "Setup was cancelled before Hopper was installed. Rerun rea setup when ready.",
+            };
+        default:
+            return {
+                status: "failed",
+                code: "download_failed",
+                remediation: "REA could not download or unpack the official Hopper package. Check network and filesystem access, then retry setup.",
+            };
+    }
+};

package/dist/application/SetupPlan.js

@@ -0,0 +1,31 @@
+/** Build the complete setup mutation plan before approval. */
+export const setupPlan = (platform, installHopper, clients) => [
+    ...(installHopper
+        ? [
+            {
+                kind: "install_hopper",
+                target: platform === "darwin"
+                    ? "~/Applications/Hopper Disassembler.app"
+                    : "system package manager",
+                detail: platform === "linux"
+                    ? "Download, verify, and install Hopper plus its Xvfb demo-session dependencies. For the supported demo build, REA uses a private display and selects Hopper's offered demo mode for each analysis session."
+                    : "Download the official Hopper package, verify it, and install it. Hopper may show its demo or license prompt when first opened.",
+                external: true,
+            },
+        ]
+        : []),
+    ...clients
+        .filter(({ format }) => format !== "unsupported")
+        .map((client) => ({
+        kind: "configure_client",
+        target: client.configPath,
+        detail: `Add the REA MCP registration for ${client.name}; preserve unrelated configuration.`,
+        external: false,
+    })),
+    {
+        kind: "install_skill",
+        target: "~/.agents/skills/rea-analysis/SKILL.md",
+        detail: "Install or update the bundled REA analysis skill.",
+        external: false,
+    },
+];