rea-agents 6.2.0 → 6.4.0

package/dist/application/SetupHost.js

@@ -1,15 +1,19 @@
 import { access } from "node:fs/promises";
 import { resolve } from "node:path";
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { ConfigurationError } from "../domain/configurationErrors.js";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { npxRegistrationCommand } from "./ClientRegistrationIdentity.js";
 import { SUPPORTED_NODE_VERSION_PROSE, supportsNodeVersion, } from "../domain/runtimeVersion.js";
 import { runDoctor, systemDoctorHost } from "./Doctor.js";
 import { installLinuxHopper, readLinuxDistribution, systemLinuxHopperInstallHost, } from "./LinuxHopper.js";
 import { installMacHopper, systemMacHopperInstallHost } from "./MacHopper.js";
-import { supportedClients } from "./SupportedClients.js";
-import { canonicalSkillNeedsInstall, installCanonicalSkill, } from "./SetupSkill.js";
+import { clientEvidencePaths, supportedClients, } from "./SupportedClients.js";
+import { skillDestinations, canonicalSkillNeedsInstall, installCanonicalSkill, } from "./SetupSkill.js";
 import { clientConfigurationAligned, configureClientConfiguration, inspectClientConfiguration, } from "./SetupClientConfiguration.js";
 import { setupInstallFailure } from "./SetupInstallFailure.js";
+import { RegularFileCleanupFailure, retryRegularFileCleanup, } from "./RegularFileRead.js";
 import { providerRegistrationEnvironment } from "./SetupRegistrationEnvironment.js";
 /** Resolve the executable and arguments used in a managed MCP registration. */
 export const setupRegistrationCommand = (platform, useNpmRunner) => useNpmRunner
@@ -40,20 +44,26 @@ export const hostRemediation = async (host, installHopper) => {
     }
     if ((await host.linuxDistribution())?.supported === true)
         return undefined;
-    return "Automated Hopper setup supports Ubuntu 24.04+, Fedora 41+, 64-bit Arch Linux, and CachyOS; configure an existing supported provider instead.";
+    return "Automated Hopper setup supports Ubuntu 24.04+, Fedora 41+, Nobara 44+, 64-bit Arch Linux, CachyOS, and Omarchy; configure an existing supported provider instead.";
 };
 /** Production setup effects for Hopper, agent configuration, and the canonical skill directory. */
 export const systemSetupHost = (selectedDoctorHost = undefined, environment = process.env) => {
     const doctorHost = selectedDoctorHost ?? systemDoctorHost({ environment });
     const platform = doctorHost.platform;
     const { homeDirectory } = doctorHost;
+    const macHopperHost = platform === "darwin"
+        ? systemMacHopperInstallHost(homeDirectory, environment)
+        : undefined;
+    const resources = new ArtifactResourceScope();
     return {
         platform,
         homeDirectory,
+        skillDestinations: (clientIds) => skillDestinations(homeDirectory, clientIds, environment, platform),
         registrationCommand: setupRegistrationCommand(platform, environment.npm_command === "exec"),
         nodeVersion: process.versions.node,
         macosVersion: () => doctorHost.macosVersion(),
         linuxDistribution: readLinuxDistribution,
+        close: () => closeSetupResources(resources, macHopperHost),
         initialSetupState: async (scope) => {
             const diagnosis = await runDoctor(undefined, doctorHost, scope);
             return {
@@ -70,41 +80,111 @@ export const systemSetupHost = (selectedDoctorHost = undefined, environment = pr
             };
         },
         installHopper: async (replaceExisting) => {
-            const result = platform === "linux"
-                ? await installLinuxHopper(systemLinuxHopperInstallHost(environment))
-                : await installMacHopper({ replaceExisting }, systemMacHopperInstallHost(homeDirectory, environment));
+            if (platform === "linux") {
+                const result = await installLinuxHopper(systemLinuxHopperInstallHost(environment));
+                return result.status === "installed"
+                    ? result
+                    : setupInstallFailure(result.reason);
+            }
+            if (macHopperHost === undefined)
+                return setupInstallFailure("unsupported_host");
+            const result = await installMacHopper({ replaceExisting }, macHopperHost);
             if (result.status === "installed")
-                return result;
-            return setupInstallFailure(result.reason);
+                return {
+                    status: "installed",
+                    launcherPath: result.launcherPath,
+                    ...(result.cleanupFailure === undefined
+                        ? {}
+                        : { cleanupFailure: result.cleanupFailure }),
+                };
+            const failure = setupInstallFailure(result.reason);
+            if (result.cleanupFailure === undefined)
+                return failure;
+            return failure.status === "failed"
+                ? {
+                    ...failure,
+                    remediation: `${failure.remediation} ${result.cleanupFailure}`,
+                }
+                : failure;
         },
         detectedClients: () => detectClients(homeDirectory, platform, environment),
         supportedClients: () => Promise.resolve(supportedClients(homeDirectory, platform, environment)),
-        configureClient: (client, providerEnvironment, command) => client.format === "unsupported"
-            ? Promise.resolve({ status: "skipped" })
-            : configureClientConfiguration(client, providerEnvironment, command),
-        clientNeedsConfigure: (client, providerEnvironment, command) => client.format === "unsupported"
-            ? Promise.resolve(false)
-            : clientConfigurationAligned(client, providerEnvironment, command).then((aligned) => !aligned),
-        inspectClientConfiguration: inspectClientConfiguration,
-        skillNeedsInstall: () => canonicalSkillNeedsInstall(homeDirectory),
-        installSkill: () => installCanonicalSkill(homeDirectory),
+        ...clientConfigurationOperations(resources),
+        skillNeedsInstall: (clientIds) => canonicalSkillNeedsInstall(homeDirectory, clientIds, environment, platform),
+        installSkill: (clientIds) => installCanonicalSkill(homeDirectory, clientIds, environment, platform),
         doctor: (scope) => runDoctor(undefined, doctorHost, scope),
     };
 };
+const clientConfigurationOperations = (resources) => ({
+    configureClient: (client, providerEnvironment, command) => runClientConfigurationOperation(resources, async () => client.format === "unsupported"
+        ? { status: "skipped" }
+        : configureClientConfiguration(client, providerEnvironment, command)),
+    clientNeedsConfigure: (client, providerEnvironment, command) => runClientConfigurationOperation(resources, async () => client.format === "unsupported"
+        ? false
+        : !(await clientConfigurationAligned(client, providerEnvironment, command))),
+    inspectClientConfiguration: (client, providerEnvironment, command) => runClientConfigurationOperation(resources, () => inspectClientConfiguration(client, providerEnvironment, command)),
+});
+const closeSetupResources = async (resources, macHopperHost) => {
+    const [resourceCleanup, hopperCleanup] = await Promise.allSettled([
+        resources.close(),
+        Promise.resolve().then(() => macHopperHost?.close()),
+    ]);
+    const failures = [];
+    if (hopperCleanup.status === "rejected")
+        failures.push(`Hopper host cleanup failed: ${errorMessage(hopperCleanup.reason)}`);
+    else if (hopperCleanup.value !== undefined)
+        failures.push(hopperCleanup.value);
+    if (resourceCleanup.status === "rejected")
+        failures.push(errorMessage(resourceCleanup.reason));
+    return failures.length === 0 ? undefined : failures.join("; ");
+};
+const runClientConfigurationOperation = async (resources, operation) => {
+    try {
+        return await resources.run(async () => {
+            try {
+                return await operation();
+            }
+            catch (cause) {
+                if (!(cause instanceof RegularFileCleanupFailure))
+                    throw cause;
+                const cleanup = await retryRegularFileCleanup(cause, resources);
+                const primary = cleanup.outcome.kind === "failed"
+                    ? cleanup.outcome.cause
+                    : cause.cleanupCause;
+                throw configurationCleanupError(`Could not safely access client configuration at ${cause.path}: ${errorMessage(primary)}`, cause, cleanup.cleanup);
+            }
+        });
+    }
+    catch (cause) {
+        if (cause instanceof ArtifactReaderFailure)
+            throw configurationCleanupError(cause.message, cause, cause.cleanup);
+        throw cause;
+    }
+};
+const configurationCleanupError = (message, cause, cleanup) => new ConfigurationError(message, {
+    cause,
+    settings: [{ setting: "client configuration", constraint: message }],
+    ...(cleanup === undefined ? {} : { cleanup }),
+});
+const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
 /** Detect supported agents from their config files or stable installation markers. */
 export const detectClients = async (home, platform = process.platform, environment = process.env) => {
     const detected = [];
     for (const candidate of supportedClients(home, platform, environment)) {
-        const [hasConfig, hasMarker] = await Promise.all([
-            exists(candidate.configPath),
-            candidate.markerPath === undefined ? false : exists(candidate.markerPath),
-        ]);
-        if (hasConfig || hasMarker)
+        if (candidate.configPathError !== undefined)
+            continue;
+        if (await clientEvidencePresent(candidate))
             detected.push(candidate);
     }
     return detected;
 };
 const major = (version) => Number.parseInt(version.split(".")[0] ?? "0", 10);
+const clientEvidencePresent = async (client) => {
+    for (const path of clientEvidencePaths(client))
+        if (await exists(path))
+            return true;
+    return false;
+};
 const exists = async (path) => {
     try {
         await access(path);

package/dist/application/SetupPlan.js

@@ -1,5 +1,4 @@
 import { join } from "node:path";
-import { PRODUCT_IDENTITY } from "../identity.js";
 import { isOwnedClientRegistrationCommand } from "./ClientRegistrationIdentity.js";
 import { linuxHopperInstallDisclosure, } from "./LinuxHopper.js";
 import { macHopperInstallDisclosure } from "./MacHopper.js";
@@ -20,10 +19,9 @@ export const discoverSetupState = async (input) => {
             input.proposeHopper &&
             (Object.keys(input.providerEnvironment).length === 0 ||
                 linuxHopperRepairNeeded));
-    const [clients, detectedClients, skillNeedsInstall] = await Promise.all([
+    const [clients, detectedClients] = await Promise.all([
         input.host.supportedClients(),
         input.host.detectedClients(),
-        input.host.skillNeedsInstall(),
     ]);
     const detectedIds = new Set(detectedClients.map(({ name }) => name));
     const registrations = initialDoctor.identity?.registrations ?? [];
@@ -56,7 +54,6 @@ export const discoverSetupState = async (input) => {
     return {
         initialDoctor,
         installHopper,
-        skillNeedsInstall,
         clients,
         detectedClientIds: [...detectedIds],
         defaultClientIds,
@@ -119,6 +116,8 @@ export const planSetupActions = async (input) => {
             homeDirectory: input.host.homeDirectory,
             installHopper: input.discovery.installHopper,
             installSkill: input.installSkill,
+            skillClientIds: input.skillClientIds,
+            skillDestinations: input.host.skillDestinations(input.skillClientIds),
             clients: clientPlans,
             providerEnvironment: input.providerEnvironment,
             ...(input.discovery.linuxPackageFamily === undefined
@@ -170,17 +169,19 @@ const setupPlan = (input) => [
         ...(backupPath === undefined ? {} : { backupPath }),
     })),
     ...(input.installSkill
-        ? [
-            {
-                id: "install_skill",
-                kind: "install_skill",
-                label: "REA reverse-engineering skill",
-                target: join(input.homeDirectory, ".agents/skills", PRODUCT_IDENTITY.skillName),
-                detail: "Install or update the bundled REA reverse-engineering skill and on-demand references.",
-                external: false,
-                operation: "install",
-            },
-        ]
+        ? input.skillDestinations.map(({ client, path }) => ({
+            id: client === "shared" ? "install_skill" : `install_skill:${client}`,
+            kind: "install_skill",
+            label: client === "claude_code"
+                ? "REA skill for Claude Code"
+                : "REA reverse-engineering skill",
+            target: path,
+            detail: client === "claude_code"
+                ? "Install or update the REA skill in Claude Code's personal skill directory."
+                : "Install or update the bundled REA reverse-engineering skill and on-demand references.",
+            external: false,
+            operation: "install",
+        }))
         : []),
 ];
 const linuxDisclosure = (family) => {
@@ -197,8 +198,8 @@ const clientConfigurationDetail = (client, command, environment, installHopper)
         .sort(([left], [right]) => left.localeCompare(right))
         .map(([name, value]) => `${name}=${value}`);
     const environmentDetail = entries.length === 0
-        ? " No additional environment variables."
-        : ` Environment: ${entries.join(", ")}.`;
+        ? " No additional provider environment variables. Existing server environment overrides are retained."
+        : ` Detected provider environment: ${entries.join(", ")}. Existing server environment overrides are retained; detected values replace matching keys.`;
     const hopperDetail = installHopper
         ? environment.HOPPER_LAUNCHER_PATH === undefined
             ? " If this plan installs Hopper, REA will add HOPPER_LAUNCHER_PATH using the launcher path reported by that installation."

package/dist/application/SetupSkill.js

@@ -1,19 +1,54 @@
-import { mkdir, readFile, rm } from "node:fs/promises";
+import { copyFile, lstat, mkdir, readFile, rm } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
 import { dirname, join } from "node:path";
 import writeFileAtomic from "write-file-atomic";
 import { PRODUCT_IDENTITY } from "../identity.js";
-const SKILL_FILES = [
+import { NonRegularFileReadError } from "../filesystem/RegularFile.js";
+import { readRegularFileText } from "./RegularFileRead.js";
+import { clientSkillDirectories } from "./SupportedClients.js";
+export const MANAGED_SKILL_FILES = [
     "SKILL.md",
+    "references/connection-and-recovery.md",
     "references/native-and-artifacts.md",
     "references/javascript-applications.md",
     "references/android-applications.md",
     "references/runtime-observation.md",
     "references/evidence-workflows.md",
 ];
-const skillRoot = (home) => join(home, ".agents/skills", PRODUCT_IDENTITY.skillName);
+export const isManagedSkillManifest = (content) => content.startsWith(`---\nname: ${PRODUCT_IDENTITY.skillName}\n`) ||
+    content.startsWith(`---\r\nname: ${PRODUCT_IDENTITY.skillName}\r\n`);
+export const readSkillFile = (path) => readRegularFileText(path, { symlinks: "reject" });
+/** Resolve the skill roots required by a client selection, or all owned roots. */
+export const skillDestinations = (home, clientIds, environment = {}, platform = process.platform) => clientSkillDirectories(home, clientIds, environment, platform).map(({ client, directory }) => ({
+    client,
+    path: join(directory, PRODUCT_IDENTITY.skillName),
+}));
+/** Resolve existing REA-owned skill roots using setup's canonical destinations. */
+export const existingSkillDestinations = async (home, environment = {}, platform = process.platform) => {
+    const existing = [];
+    for (const destination of skillDestinations(home, undefined, environment, platform)) {
+        try {
+            const root = await lstat(destination.path);
+            if (root.isSymbolicLink() || !root.isDirectory())
+                continue;
+            const manifest = join(destination.path, "SKILL.md");
+            const content = await readSkillFile(manifest);
+            if (isManagedSkillManifest(content))
+                existing.push(destination);
+        }
+        catch (cause) {
+            if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+                continue;
+            if (cause instanceof NonRegularFileReadError)
+                continue;
+            throw cause;
+        }
+    }
+    return existing;
+};
 const readOptionalText = async (path) => {
     try {
-        return await readFile(path, "utf8");
+        return await readSkillFile(path);
     }
     catch (cause) {
         if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
@@ -21,18 +56,18 @@ const readOptionalText = async (path) => {
         throw cause;
     }
 };
-const canonicalSkillFiles = async (home) => Promise.all(SKILL_FILES.map(async (relativePath) => {
-    const destination = join(skillRoot(home), relativePath);
+const canonicalSkillFiles = async (home, clientIds, environment = {}, platform = process.platform) => Promise.all(skillDestinations(home, clientIds, environment, platform).flatMap(({ path: root }) => MANAGED_SKILL_FILES.map(async (relativePath) => {
+    const destination = join(root, relativePath);
     return {
         destination,
         content: await readFile(new URL(`../../skills/${PRODUCT_IDENTITY.skillName}/${relativePath}`, import.meta.url), "utf8"),
         original: await readOptionalText(destination),
     };
-}));
+})));
 /** Report whether setup would change any file in the managed REA skill bundle. */
-export const canonicalSkillNeedsInstall = async (home) => {
+export const canonicalSkillNeedsInstall = async (home, clientIds = [], environment = {}, platform = process.platform) => {
     try {
-        return (await canonicalSkillFiles(home)).some(({ content, original }) => original !== content);
+        return (await canonicalSkillFiles(home, clientIds, environment, platform)).some(({ content, original }) => original !== content);
     }
     catch (cause) {
         // Unreadable skill state fails open to install so setup can repair it.
@@ -41,6 +76,16 @@ export const canonicalSkillNeedsInstall = async (home) => {
     }
 };
 const writeText = (path, content) => writeFileAtomic(path, content, { encoding: "utf8", mode: 0o600 });
+const preserveSkillBackup = async (source, destination) => {
+    try {
+        await copyFile(source, destination, fsConstants.COPYFILE_EXCL);
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause && cause.code === "EEXIST")
+            return;
+        throw cause;
+    }
+};
 const restoreSkillFiles = async (changed) => {
     for (const { destination, original } of [...changed].reverse()) {
         if (original === undefined)
@@ -50,22 +95,22 @@ const restoreSkillFiles = async (changed) => {
     }
 };
 /** Transactionally install or upgrade the canonical REA skill and references. */
-export const installCanonicalSkill = async (home) => {
+export const installCanonicalSkill = async (home, clientIds = [], environment = {}, platform = process.platform) => {
     let changed = [];
     try {
-        const canonical = await canonicalSkillFiles(home);
+        const canonical = await canonicalSkillFiles(home, clientIds, environment, platform);
         changed = canonical.filter(({ content, original }) => original !== content);
         if (changed.length === 0)
             return "unchanged";
         for (const { destination, original } of changed) {
             await mkdir(dirname(destination), { recursive: true });
             if (original !== undefined)
-                await writeText(`${destination}.rea.backup`, original);
+                await preserveSkillBackup(destination, `${destination}.rea.backup`);
         }
         for (const { destination, content } of changed)
             await writeText(destination, content);
         for (const { destination, content } of changed)
-            if ((await readFile(destination, "utf8")) !== content)
+            if ((await readSkillFile(destination)) !== content)
                 throw new Error(`skill readback mismatch: ${destination}`);
         return "installed";
     }
@@ -82,3 +127,26 @@ export const installCanonicalSkill = async (home) => {
         return "failed";
     }
 };
+/** Read installed skill metadata and compare every managed location. */
+export const readInstalledSkillIdentity = async (home, clientIds, environment = {}, platform = process.platform) => {
+    const destinations = skillDestinations(home, clientIds, environment, platform);
+    let content;
+    for (const destination of destinations) {
+        try {
+            content = await readSkillFile(join(destination.path, "SKILL.md"));
+            break;
+        }
+        catch {
+            // Another selected copy may provide metadata; canonical validation below
+            // still marks missing or unreadable copies as stale.
+        }
+    }
+    if (content === undefined)
+        return undefined;
+    const toolCount = /^\s{2}tool_count:\s*(\d+)\s*$/mu.exec(content)?.[1];
+    return {
+        canonical: !(await canonicalSkillNeedsInstall(home, clientIds, environment, platform)),
+        version: /^\s{2}version:\s*"([^"]+)"\s*$/mu.exec(content)?.[1] ?? null,
+        toolCount: toolCount === undefined ? null : Number.parseInt(toolCount, 10),
+    };
+};