rea-agents 3.2.1 → 4.0.0

package/dist/application/Setup.js

@@ -9,71 +9,201 @@ import { installMacHopper } from "./MacHopper.js";
 import { configureDetectedClients } from "./SetupClients.js";
 import { supportedClients } from "./SupportedClients.js";
 import { canonicalSkillNeedsInstall, installCanonicalSkill, } from "./SetupSkill.js";
-import { discoverSetupActions } from "./SetupPlan.js";
-import { clientConfigurationAligned, configureJsonClient, configureTomlClient, inspectClientConfiguration, } from "./SetupClientConfiguration.js";
+import { discoverSetupState, planSetupActions } from "./SetupPlan.js";
+import { clientConfigurationAligned, configureClientConfiguration, configureJsonClient, configureTomlClient, inspectClientConfiguration, } from "./SetupClientConfiguration.js";
 export { configureJsonClient, configureTomlClient };
 import { setupInstallFailure, } from "./SetupInstallFailure.js";
 import { providerRegistrationEnvironment } from "./SetupRegistrationEnvironment.js";
 export { canonicalSkillNeedsInstall, installCanonicalSkill };
-const registrationCommand = () => process.env.npm_command === "exec"
+/** Resolve the executable and arguments used in a managed MCP registration. */
+export const setupRegistrationCommand = (platform, useNpmRunner = process.env.npm_command === "exec") => useNpmRunner
     ? PRODUCT_IDENTITY.mcpCommand.split(" ")
-    : [resolve(process.argv[1] ?? PRODUCT_IDENTITY.cliBinary), "mcp"];
+    : platform === "win32"
+        ? [
+            process.execPath,
+            resolve(process.argv[1] ?? PRODUCT_IDENTITY.cliBinary),
+            "mcp",
+        ]
+        : [resolve(process.argv[1] ?? PRODUCT_IDENTITY.cliBinary), "mcp"];
+/** Whether the requested setup actions still need approval or human repair. */
+export const isSetupFailure = (result) => {
+    const status = result.status;
+    switch (status) {
+        case "planned":
+        case "cancelled":
+        case "ready":
+            return false;
+        case "needs_confirmation":
+        case "needs_human":
+            return true;
+        default: {
+            const exhaustive = status;
+            throw new TypeError(`Unhandled setup result status: ${String(exhaustive)}`);
+        }
+    }
+};
 /** Discover, approve, and apply setup actions idempotently. */
 export const runSetup = async (options, host = systemSetupHost(), confirm) => {
     const appliedActions = [];
     let plannedActions = [];
     const clients = {};
-    const fail = (remediation) => setupFailure(remediation, [host, plannedActions, appliedActions, clients], options.readinessScope);
-    const unsupported = await hostRemediation(host, options.installHopper);
+    let clientStates = [];
+    let readinessScope = options.readinessScope;
+    const fail = (remediation) => setupFailure(remediation, [host, plannedActions, appliedActions, clients, clientStates], readinessScope);
+    const unsupported = await hostRemediation(host, false);
     if (unsupported !== undefined)
         return fail(unsupported);
     let hopperPath = await host.hopperPath();
     let providerEnvironment = await initialProviderEnvironment(host, hopperPath);
-    const discovery = await discoverSetupActions({
+    const discovery = await discoverSetupState({
         host,
         providerEnvironment,
-        command: registrationCommand(),
         forceHopperInstall: options.installHopper,
-        proposeHopper: options.proposeHopper ?? true,
-        selectedClientIds: options.clientIds,
-        installSkillSelection: options.installSkill,
+        proposeHopper: options.proposeHopper ?? (confirm !== undefined && !options.structured),
         doctorScope: options.readinessScope,
     });
-    if (discovery.blocker !== undefined)
-        return fail(discovery.blocker);
-    const selection = await resolveSetupSelection(options, discovery, confirm);
-    plannedActions = selection.plannedActions;
-    if (!selection.approved)
+    clientStates = discovery.clientStates;
+    const clientSelectionAllowed = options.clientIds === undefined &&
+        options.readinessScope?.clients === undefined &&
+        options.allDetectedClients !== true &&
+        options.installHopper !== true &&
+        options.installSkill === undefined;
+    const interactiveSelection = confirm !== undefined && !options.structured && clientSelectionAllowed;
+    let selectedClientIds = options.allDetectedClients
+        ? discovery.detectedClientIds
+        : (options.clientIds ??
+            options.readinessScope?.clients ??
+            discovery.defaultClientIds);
+    let skillSelected = options.installSkill === true ||
+        (options.installSkill !== false && selectedClientIds.length > 0);
+    let installSkill = skillSelected && discovery.skillNeedsInstall;
+    let planDiscovery = discovery;
+    if (interactiveSelection) {
+        const offerSkillAction = options.installSkill !== false && discovery.skillNeedsInstall;
+        const selectionActions = await planSetupActions({
+            discovery,
+            host,
+            providerEnvironment,
+            command: setupRegistrationCommand(host.platform),
+            clientIds: [],
+            installSkill: offerSkillAction,
+        });
+        const decision = await confirm(selectionActions.plannedActions, {
+            stage: "select",
+            clientStates,
+            selectedClientIds: discovery.defaultClientIds,
+            clientSelectionAllowed,
+        });
+        if (isSetupDecisionCancelled(decision))
+            return setupCancelled(selectionActions.plannedActions, clients, clientStates, discovery.initialDoctor);
+        const selectedActionIds = new Set(typeof decision === "boolean"
+            ? decision
+                ? [
+                    ...selectionActions.plannedActions.map(({ id }) => id),
+                    ...discovery.defaultClientIds.map((id) => `configure_client:${id}`),
+                ]
+                : []
+            : decision.selectedActionIds);
+        selectedClientIds = [...selectedActionIds]
+            .filter((id) => id.startsWith("configure_client:"))
+            .map((id) => id.slice("configure_client:".length));
+        const proposedInstallAction = selectionActions.plannedActions.some(({ id }) => id === "install_hopper");
+        planDiscovery = {
+            ...discovery,
+            installHopper: options.installHopper ||
+                (proposedInstallAction && selectedActionIds.has("install_hopper")),
+        };
+        skillSelected =
+            options.installSkill === true ||
+                (selectedActionIds.has("install_skill") &&
+                    selectedClientIds.length === 0) ||
+                (options.installSkill !== false && selectedClientIds.length > 0);
+        installSkill = skillSelected && discovery.skillNeedsInstall;
+    }
+    const planned = await planSetupActions({
+        discovery: planDiscovery,
+        host,
+        providerEnvironment,
+        command: setupRegistrationCommand(host.platform),
+        clientIds: selectedClientIds,
+        installSkill,
+    });
+    plannedActions = planned.plannedActions;
+    if (planned.blocker !== undefined)
+        return fail(planned.blocker);
+    const hopperBlocker = await hostRemediation(host, planDiscovery.installHopper);
+    if (hopperBlocker !== undefined)
+        return fail(hopperBlocker);
+    const planSelection = {
+        installHopper: planDiscovery.installHopper,
+        installSkill,
+        skillSelected,
+        selectedClients: planned.selectedClients,
+        clientsToConfigure: planned.clientsToConfigure,
+    };
+    readinessScope = resolvedReadinessScope(options.readinessScope, planSelection);
+    if (options.dryRun === true)
         return {
-            status: confirm === undefined ? "needs_confirmation" : "planned",
+            status: "planned",
             plannedActions,
             appliedActions,
             clients,
-            doctor: discovery.initialDoctor,
-            remediation: "Review the setup plan, then rerun interactively or with --yes.",
+            doctor: summarizeDoctor(discovery.initialDoctor),
+            clientStates,
         };
-    let detectedClients = selection.detectedClients;
-    if (selection.installHopper &&
-        (selection.interactiveApproval || options.installHopper)) {
+    let approved = options.approved || plannedActions.length === 0;
+    let interactiveApproval = false;
+    if (!approved && confirm !== undefined && !options.structured) {
+        const decision = await confirm?.(plannedActions, {
+            stage: "confirm",
+            clientStates,
+            selectedClientIds,
+            clientSelectionAllowed: false,
+        });
+        if (decision !== undefined) {
+            if (isSetupDecisionCancelled(decision))
+                return setupCancelled(plannedActions, clients, clientStates, discovery.initialDoctor);
+            approved = typeof decision === "boolean" ? decision : decision.approved;
+            interactiveApproval = approved;
+        }
+    }
+    if (!approved)
+        return {
+            status: confirm === undefined ? "needs_confirmation" : "cancelled",
+            plannedActions,
+            appliedActions,
+            clients,
+            doctor: summarizeDoctor(discovery.initialDoctor),
+            clientStates,
+            ...(confirm === undefined
+                ? {
+                    remediation: "Review the setup plan, then rerun interactively or with --yes.",
+                }
+                : {}),
+        };
+    let selectedClients = planSelection.clientsToConfigure;
+    if (planSelection.installHopper &&
+        (interactiveApproval || options.installHopper)) {
         const install = await installHopperAction({
             host,
             options,
             plannedActions,
             appliedActions,
             clients,
-            detectedClients,
+            selectedClients,
             providerEnvironment,
-            doctorScope: options.readinessScope,
+            doctorScope: readinessScope,
+            clientStates,
         });
         if ("failure" in install)
             return install.failure;
-        ({ hopperPath, providerEnvironment, detectedClients } = install);
+        ({ hopperPath, providerEnvironment, selectedClients } = install);
     }
     const clientFailure = await configureDetectedClients({
         host,
-        detectedClients,
+        detectedClients: selectedClients,
         providerEnvironment,
-        command: registrationCommand(),
+        command: setupRegistrationCommand(host.platform),
         clients,
         appliedActions,
         ...(options.onProgress === undefined
@@ -82,10 +212,10 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
     });
     if (clientFailure !== undefined)
         return fail(clientFailure);
-    if (selection.installSkill &&
+    if (planSelection.installSkill &&
         !(await installSkillAction(host, options, appliedActions)))
         return fail("REA analysis skill could not be installed or verified. Check permissions for `~/.agents/skills`, then rerun setup.");
-    const doctor = await host.doctor(options.readinessScope);
+    const doctor = summarizeDoctor(await host.doctor(readinessScope));
     const remediation = finalSetupRemediation(host.platform, appliedActions.includes("installed_hopper"), doctor.healthy, hopperPath);
     return {
         status: remediation === undefined ? "ready" : "needs_human",
@@ -93,38 +223,10 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
         appliedActions,
         clients,
         doctor,
+        clientStates,
         ...(remediation === undefined ? {} : { remediation }),
     };
 };
-const resolveSetupSelection = async (options, discovery, confirm) => {
-    let { installHopper, installSkill, detectedClients, plannedActions } = discovery;
-    let approved = options.approved || plannedActions.length === 0;
-    let interactiveApproval = false;
-    if (!approved && confirm !== undefined && !options.structured) {
-        const decision = await confirm(plannedActions);
-        if (typeof decision === "boolean") {
-            interactiveApproval = decision;
-            approved = decision;
-        }
-        else {
-            const selected = new Set(decision.selectedActionIds);
-            plannedActions = plannedActions.filter(({ id }) => selected.has(id));
-            installHopper = plannedActions.some(({ kind }) => kind === "install_hopper");
-            installSkill = plannedActions.some(({ kind }) => kind === "install_skill");
-            detectedClients = detectedClients.filter((client) => selected.has(`configure_client:${client.name}`));
-            interactiveApproval = decision.approved;
-            approved = decision.approved;
-        }
-    }
-    return {
-        approved,
-        interactiveApproval,
-        installHopper,
-        installSkill,
-        detectedClients,
-        plannedActions,
-    };
-};
 const installHopperAction = async (input) => {
     const label = "Hopper deep-analysis provider";
     emitProgress(input.options, {
@@ -146,7 +248,8 @@ const installHopperAction = async (input) => {
                 plannedActions: input.plannedActions,
                 appliedActions: input.appliedActions,
                 clients: input.clients,
-                doctor: await input.host.doctor(input.doctorScope),
+                doctor: summarizeDoctor(await input.host.doctor(input.doctorScope)),
+                clientStates: input.clientStates,
                 code: installed.code,
                 remediation: installed.remediation,
             },
@@ -166,7 +269,7 @@ const installHopperAction = async (input) => {
     return {
         hopperPath: installed.launcherPath,
         providerEnvironment,
-        detectedClients: await filterClientsNeedingConfigure(input.host, input.detectedClients, providerEnvironment, registrationCommand()),
+        selectedClients: await filterClientsNeedingConfigure(input.host, input.selectedClients, providerEnvironment, setupRegistrationCommand(input.host.platform)),
     };
 };
 const installSkillAction = async (host, options, appliedActions) => {
@@ -195,14 +298,17 @@ const installSkillAction = async (host, options, appliedActions) => {
     });
     return true;
 };
-const setupFailure = async (remediation, [host, plannedActions, appliedActions, clients], scope) => ({
-    status: "needs_human",
-    plannedActions,
-    appliedActions,
-    clients,
-    doctor: await host.doctor(scope),
-    remediation,
-});
+const setupFailure = async (remediation, [host, plannedActions, appliedActions, clients, clientStates], scope) => {
+    return {
+        status: "needs_human",
+        plannedActions,
+        appliedActions,
+        clients,
+        doctor: summarizeDoctor(await host.doctor(scope)),
+        clientStates,
+        remediation,
+    };
+};
 const emitProgress = (options, event) => options.onProgress?.(event);
 const filterClientsNeedingConfigure = async (host, detectedClients, providerEnvironment, command) => {
     const needs = await Promise.all(detectedClients.map((client) => host.clientNeedsConfigure(client, providerEnvironment, command)));
@@ -221,11 +327,57 @@ const finalSetupRemediation = (platform, installedHopper, healthy, hopperPath) =
         ? "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, forceHopperInstall) => {
-    if (host.platform !== "darwin" && host.platform !== "linux")
-        return "REA supports Hopper on macOS and selected 64-bit Linux distributions.";
+const isSetupDecisionCancelled = (decision) => typeof decision === "boolean" ? !decision : decision.cancelled === true;
+const setupCancelled = (plannedActions, clients, clientStates, doctor) => ({
+    status: "cancelled",
+    plannedActions,
+    appliedActions: [],
+    clients,
+    doctor: summarizeDoctor(doctor),
+    clientStates,
+});
+const resolvedReadinessScope = (requested, selection) => ({
+    clients: selection.selectedClients.map(({ name }) => name),
+    providers: selection.installHopper
+        ? ["hopper"]
+        : (requested?.providers ?? []),
+    skill: selection.skillSelected === true || requested?.skill === true,
+});
+const summarizeDoctor = (report) => ({
+    healthy: report.healthy,
+    environment_healthy: report.environment_healthy,
+    scope: report.scope,
+    availableProviders: [
+        ...(report.hopperPath !== undefined &&
+            report.checks
+                .filter(({ name }) => name.startsWith("hopper"))
+                .every(({ ok }) => ok)
+            ? ["hopper"]
+            : []),
+        ...(report.providerInspections ?? [])
+            .filter(({ available }) => available)
+            .map(({ id }) => id),
+    ],
+    ...(report.hopperPath === undefined ? {} : { hopperPath: report.hopperPath }),
+    ...(report.providerInspections === undefined
+        ? {}
+        : { providerInspections: report.providerInspections }),
+    ...(report.identity === undefined
+        ? {}
+        : {
+            identity: {
+                skill: report.identity.skill,
+                registrations: report.identity.registrations,
+            },
+        }),
+});
+const hostRemediation = async (host, installHopper) => {
     if (!supportsNodeVersion(host.nodeVersion))
         return "Install Node.js 22.19+ or 24.11+ and rerun setup.";
+    if (!installHopper)
+        return undefined;
+    if (host.platform !== "darwin" && host.platform !== "linux")
+        return "REA supports Hopper on macOS and selected 64-bit Linux distributions.";
     if (host.platform === "darwin") {
         const version = await host.macosVersion();
         return version === undefined || major(version) < 12
@@ -234,17 +386,13 @@ const hostRemediation = async (host, forceHopperInstall) => {
     }
     if ((await host.linuxDistribution())?.supported === true)
         return undefined;
-    const providerEnvironment = await host.providerEnvironment?.();
-    if (!forceHopperInstall &&
-        providerEnvironment !== undefined &&
-        Object.keys(providerEnvironment).length > 0)
-        return undefined;
     return "Automated Hopper setup supports Ubuntu 24.04+, Fedora 41+, and 64-bit Arch Linux; configure an existing supported provider instead.";
 };
 /** Production setup effects for Hopper, agent configuration, and the canonical skill directory. */
 export const systemSetupHost = (doctorHost = systemDoctorHost()) => {
+    const platform = doctorHost.platform;
     return {
-        platform: process.platform,
+        platform,
         nodeVersion: process.versions.node,
         macosVersion: () => doctorHost.macosVersion(),
         linuxDistribution: readLinuxDistribution,
@@ -259,7 +407,7 @@ export const systemSetupHost = (doctorHost = systemDoctorHost()) => {
             };
         },
         installHopper: async (replaceExisting) => {
-            const result = process.platform === "linux"
+            const result = platform === "linux"
                 ? await installLinuxHopper()
                 : await installMacHopper({ replaceExisting });
             if (result.status === "installed")
@@ -267,11 +415,10 @@ export const systemSetupHost = (doctorHost = systemDoctorHost()) => {
             return setupInstallFailure(result.reason);
         },
         detectedClients: () => detectClients(homedir()),
+        supportedClients: () => Promise.resolve(supportedClients(homedir())),
         configureClient: (client, providerEnvironment, command) => client.format === "unsupported"
             ? Promise.resolve({ status: "skipped" })
-            : client.format === "toml"
-                ? configureTomlClient(client, providerEnvironment, command)
-                : configureJsonClient(client, providerEnvironment, command),
+            : configureClientConfiguration(client, providerEnvironment, command),
         clientNeedsConfigure: (client, providerEnvironment, command) => clientConfigurationAligned(client, providerEnvironment, command).then((aligned) => !aligned),
         inspectClientConfiguration: inspectClientConfiguration,
         skillNeedsInstall: () => canonicalSkillNeedsInstall(homedir()),
@@ -279,12 +426,17 @@ export const systemSetupHost = (doctorHost = systemDoctorHost()) => {
         doctor: (scope) => runDoctor(undefined, doctorHost, scope),
     };
 };
-/** Detect supported agents from stable per-user installation markers. */
+/** Detect supported agents from their config files or stable installation markers. */
 export const detectClients = async (home) => {
     const detected = [];
-    for (const candidate of supportedClients(home))
-        if (await exists(candidate.markerPath ?? candidate.configPath))
+    for (const candidate of supportedClients(home)) {
+        const [hasConfig, hasMarker] = await Promise.all([
+            exists(candidate.configPath),
+            candidate.markerPath === undefined ? false : exists(candidate.markerPath),
+        ]);
+        if (hasConfig || hasMarker)
             detected.push(candidate);
+    }
     return detected;
 };
 const major = (version) => Number.parseInt(version.split(".")[0] ?? "0", 10);

package/dist/application/SetupClientConfiguration.js

@@ -1,4 +1,4 @@
-import { clientConfigurationValuesEqual, parseClientConfiguration, serializeClientConfiguration, } from "./ClientConfigurationDocument.js";
+import { clientRegistrationEntry, clientConfigurationValuesEqual, parseClientConfiguration, serializeClientConfiguration, } from "./ClientConfigurationDocument.js";
 import { constants as fsConstants } from "node:fs";
 import { copyFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
@@ -16,6 +16,12 @@ const defaultCommand = () => [
 export const configureJsonClient = (client, environment = {}, command = defaultCommand()) => configureClientDocument(client, environment, command, "json");
 /** Back up, atomically update, and semantically read back one TOML MCP configuration. */
 export const configureTomlClient = (client, environment = {}, command = defaultCommand()) => configureClientDocument(client, environment, command, "toml");
+/** Configure one supported client's native stdio MCP registration shape. */
+export const configureClientConfiguration = (client, environment = {}, command = defaultCommand()) => {
+    if (client.format === undefined || client.format === "unsupported")
+        return Promise.resolve({ status: "failed", reason: "readback" });
+    return configureClientDocument(client, environment, command, client.format);
+};
 const configureClientDocument = async (client, environment, command, format) => {
     const transactionPath = await resolveClientConfigTransactionPath(client.configPath);
     if (transactionPath === undefined)
@@ -36,7 +42,7 @@ const configureClientDocument = async (client, environment, command, format) =>
         return { status: "failed", reason: "readback" };
     }
     const { document, servers, serversKey } = parsed;
-    const desired = clientConfigurationDesired(client, environment, command);
+    const desired = clientConfigurationDesired(client, environment, command, format);
     if (clientConfigurationValuesEqual(servers[PRODUCT_IDENTITY.mcpServerKey], desired))
         return { status: "unchanged" };
     const backupPath = original === undefined ? undefined : `${client.configPath}.rea.backup`;
@@ -49,7 +55,7 @@ const configureClientDocument = async (client, environment, command, format) =>
     };
     try {
         await mkdir(dirname(client.configPath), { recursive: true });
-        await writeFileAtomic(transactionPath, serializeClientConfiguration(document, format), {
+        await writeFileAtomic(transactionPath, serializeClientConfiguration(document, format, original, PRODUCT_IDENTITY.mcpServerKey), {
             encoding: "utf8",
             mode: 0o600,
         });
@@ -75,7 +81,7 @@ const configureClientDocument = async (client, environment, command, format) =>
 };
 /** Determine whether an existing client configuration matches the desired registration. */
 export const clientConfigurationAligned = async (client, providerEnvironment, command) => {
-    const desired = clientConfigurationDesired(client, providerEnvironment, command);
+    const desired = clientConfigurationDesired(client, providerEnvironment, command, client.format);
     try {
         const original = await readFile(client.configPath, "utf8");
         const { servers } = parseClientConfiguration(original, client.format);
@@ -107,7 +113,7 @@ export const inspectClientConfiguration = async (client, providerEnvironment, co
             remediation: "The configuration file could not be read. Check its permissions before rerunning setup.",
         };
     }
-    const desired = clientConfigurationDesired(client, providerEnvironment, command);
+    const desired = clientConfigurationDesired(client, providerEnvironment, command, client.format);
     try {
         const { servers } = parseClientConfiguration(original, client.format);
         if (clientConfigurationValuesEqual(servers[PRODUCT_IDENTITY.mcpServerKey], desired))
@@ -145,16 +151,15 @@ const restoreConfig = async (path, original) => {
         // The backup remains available for the remediation reported by setup.
     }
 };
-const clientConfigurationDesired = (client, providerEnvironment, command) => {
+const clientConfigurationDesired = (client, providerEnvironment, command, format) => {
     const environment = Object.fromEntries(Object.entries(providerEnvironment).sort(([left], [right]) => left.localeCompare(right)));
+    const registration = clientRegistrationEntry(format ?? "json", command.length === 0 ? [PRODUCT_IDENTITY.cliBinary, "mcp"] : command, environment);
     return {
-        command: command[0] ?? PRODUCT_IDENTITY.cliBinary,
-        args: command.slice(1),
+        ...registration,
         ...(client.name === "codex"
             ? {
                 startup_timeout_sec: MCP_STARTUP_POLICY.codexStartupTimeoutSeconds,
             }
             : {}),
-        ...(Object.keys(environment).length === 0 ? {} : { env: environment }),
     };
 };