rea-agents 6.2.0 → 6.4.0

package/dist/application/RegularFileRead.js

@@ -0,0 +1,103 @@
+import { lstat, stat } from "node:fs/promises";
+import { RegularFileAdmissionFailure, openRegularFile, sameRegularFileState, RegularFileChangedError, } from "../filesystem/RegularFile.js";
+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
+import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";
+/** A close failed after reading; this error transfers the exact handle owner. */
+export class RegularFileCleanupFailure extends Error {
+    path;
+    owner;
+    outcome;
+    cleanupCause;
+    constructor(path, owner, outcome, cleanupCause) {
+        super(`Regular file cleanup failed: ${path}`, {
+            cause: outcome.kind === "failed" ? outcome.cause : cleanupCause,
+        });
+        this.path = path;
+        this.owner = owner;
+        this.outcome = outcome;
+        this.cleanupCause = cleanupCause;
+        this.name = "RegularFileCleanupFailure";
+    }
+}
+/** Retry a failed close through its retained owner and report any remaining cleanup. */
+export const retryRegularFileCleanup = async (failure, resources) => {
+    const released = await resources.release({
+        kind: "file-handle",
+        handle: failure.owner,
+        resource: failure.path,
+    });
+    if (released.kind === "released")
+        return { outcome: failure.outcome };
+    return {
+        outcome: failure.outcome,
+        cleanup: {
+            reason: `${failureMessage(failure.cleanupCause)}; retry: ${failureMessage(released.cause)}`,
+            resources: [failure.path],
+        },
+    };
+};
+const failureMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
+/** Admit one regular-file handle, retain it through the consumer, and always close it. */
+export const withRegularFile = async (path, read, options = {}) => {
+    const { signal } = options;
+    let handle;
+    try {
+        handle = await openRegularFile(path, {
+            symlinks: options.symlinks ?? "follow",
+            signal,
+        });
+    }
+    catch (cause) {
+        if (!(cause instanceof RegularFileAdmissionFailure))
+            throw cause;
+        throw new RegularFileCleanupFailure(path, cause.owner, { kind: "failed", cause: cause.cause }, cause.cleanupCause);
+    }
+    const owner = new OwnedFileHandle(handle);
+    let outcome;
+    try {
+        const stats = await handle.stat();
+        signal?.throwIfAborted();
+        const value = await read(handle, stats);
+        signal?.throwIfAborted();
+        const [opened, currentPath] = await Promise.all([
+            handle.stat(),
+            options.symlinks === "reject" ? lstat(path) : stat(path),
+        ]);
+        if (!sameRegularFileState(stats, opened) ||
+            !sameRegularFileState(stats, currentPath))
+            throw new RegularFileChangedError(path);
+        outcome = { kind: "completed", value };
+    }
+    catch (cause) {
+        outcome = { kind: "failed", cause };
+    }
+    try {
+        await owner.close();
+    }
+    catch (cleanupCause) {
+        throw new RegularFileCleanupFailure(path, owner, outcome, cleanupCause);
+    }
+    if (outcome.kind === "failed")
+        throw outcome.cause;
+    return outcome.value;
+};
+/** Admit a regular file without waiting for a pipe, then read its verified handle. */
+export const readRegularFile = (path, options = {}) => withRegularFile(path, async (handle, stats) => {
+    const bytes = await readBoundedFileBytes(handle, stats.size, options.signal);
+    if (bytes === undefined || bytes.length !== stats.size)
+        throw new RegularFileChangedError(path);
+    return bytes;
+}, options);
+/** Read one admitted regular file as UTF-8 without waiting on a pipe. */
+export const readRegularFileText = async (path, options = {}) => {
+    try {
+        return (await readRegularFile(path, options)).toString("utf8");
+    }
+    catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure &&
+            cause.outcome.kind === "completed" &&
+            Buffer.isBuffer(cause.outcome.value))
+            throw new RegularFileCleanupFailure(cause.path, cause.owner, { kind: "completed", value: cause.outcome.value.toString("utf8") }, cause.cleanupCause);
+        throw cause;
+    }
+};

package/dist/application/Setup.js

@@ -2,8 +2,49 @@ import { manualRegistrationRemediation, } from "./SupportedClients.js";
 import { configureDetectedClients } from "./SetupClients.js";
 import { discoverSetupState, planSetupActions } from "./SetupPlan.js";
 import { filterClientsNeedingConfigure, hostRemediation, systemSetupHost, } from "./SetupHost.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 /** Discover, approve, and apply setup actions idempotently. */
 export const runSetup = async (options, host = systemSetupHost(), confirm) => {
+    let result;
+    let primaryFailure;
+    let threw = false;
+    try {
+        result = await runSetupWorkflow(options, host, confirm);
+    }
+    catch (cause) {
+        threw = true;
+        primaryFailure = cause;
+    }
+    let cleanupFailure;
+    try {
+        cleanupFailure = await host.close?.();
+    }
+    catch (cause) {
+        cleanupFailure = `Setup resource cleanup failed: ${failureMessage(cause)}`;
+    }
+    if (threw) {
+        if (cleanupFailure !== undefined && primaryFailure instanceof AnalysisError)
+            throw analysisErrorWithCleanupFailure(primaryFailure, new ProviderCleanupError("setup", primaryFailure.cleanupResources, { reason: cleanupFailure }, { operation: "setup" }), "setup");
+        if (cleanupFailure !== undefined)
+            throw new AggregateError([primaryFailure, new Error(cleanupFailure)], "Setup and resource cleanup failed.", { cause: primaryFailure });
+        throw primaryFailure;
+    }
+    if (result === undefined)
+        throw new Error("Setup returned no result.");
+    if (cleanupFailure === undefined)
+        return result;
+    return {
+        ...result,
+        status: "needs_human",
+        code: result.code ?? "cleanup_failed",
+        remediation: result.remediation
+            ? `${result.remediation} ${cleanupFailure}`
+            : cleanupFailure,
+    };
+};
+const runSetupWorkflow = async (options, host, confirm) => {
     const appliedActions = [];
     let plannedActions = [];
     const clients = {};
@@ -27,6 +68,7 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
         options.readinessScope?.clients === undefined &&
         options.allDetectedClients !== true &&
         options.installHopper !== true &&
+        options.skillClientIds === undefined &&
         options.installSkill === undefined;
     const interactiveSelection = confirm !== undefined && !options.structured && clientSelectionAllowed;
     let selectedClientIds = options.allDetectedClients
@@ -34,18 +76,29 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
         : (options.clientIds ??
             options.readinessScope?.clients ??
             discovery.defaultClientIds);
+    let selectedSkillClientIds = options.skillClientIds ?? selectedClientIds;
+    let skillNeedsInstall = await host.skillNeedsInstall(selectedSkillClientIds);
     let skillSelected = options.installSkill === true ||
-        (options.installSkill !== false && selectedClientIds.length > 0);
-    let installSkill = skillSelected && discovery.skillNeedsInstall;
+        (options.installSkill !== false &&
+            (selectedClientIds.length > 0 || selectedSkillClientIds.length > 0));
+    let installSkill = skillSelected && skillNeedsInstall;
     let planDiscovery = discovery;
     if (interactiveSelection) {
-        const offerSkillAction = options.installSkill !== false && discovery.skillNeedsInstall;
+        const selectionSkillClientIds = [
+            ...new Set([
+                ...discovery.defaultClientIds,
+                ...discovery.detectedClientIds,
+            ]),
+        ];
+        const selectionSkillNeedsInstall = await host.skillNeedsInstall(selectionSkillClientIds);
+        const offerSkillAction = options.installSkill !== false && selectionSkillNeedsInstall;
         const selectionActions = await planSetupActions({
             discovery,
             host,
             providerEnvironment,
             command: host.registrationCommand,
             clientIds: [],
+            skillClientIds: selectionSkillClientIds,
             installSkill: offerSkillAction,
         });
         const decision = await confirm(selectionActions.plannedActions, {
@@ -67,6 +120,7 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
         selectedClientIds = [...selectedActionIds]
             .filter((id) => id.startsWith("configure_client:"))
             .map((id) => id.slice("configure_client:".length));
+        skillNeedsInstall = await host.skillNeedsInstall(selectedClientIds);
         const proposedInstallAction = selectionActions.plannedActions.some(({ id }) => id === "install_hopper");
         planDiscovery = {
             ...discovery,
@@ -78,7 +132,8 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
                 (selectedActionIds.has("install_skill") &&
                     selectedClientIds.length === 0) ||
                 (options.installSkill !== false && selectedClientIds.length > 0);
-        installSkill = skillSelected && discovery.skillNeedsInstall;
+        installSkill = skillSelected && skillNeedsInstall;
+        selectedSkillClientIds = selectedClientIds;
     }
     const planned = await planSetupActions({
         discovery: planDiscovery,
@@ -86,6 +141,7 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
         providerEnvironment,
         command: host.registrationCommand,
         clientIds: selectedClientIds,
+        skillClientIds: selectedSkillClientIds,
         installSkill,
     });
     plannedActions = planned.plannedActions;
@@ -177,8 +233,8 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
     if (clientFailure !== undefined)
         return fail(clientFailure);
     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.");
+        !(await installSkillAction(host, options, appliedActions, selectedSkillClientIds)))
+        return fail("REA analysis skill could not be installed or verified. Check permissions for its planned skill directories, then rerun setup.");
     const doctor = summarizeDoctor(await host.doctor(readinessScope));
     const remediation = combineRemediation(finalSetupRemediation(host.platform, appliedActions.includes("installed_hopper"), doctor.healthy, hopperPath), manualRemediation);
     return {
@@ -223,8 +279,10 @@ const installHopperAction = async (input) => {
     emitProgress(input.options, {
         actionId: "install_hopper",
         label,
-        state: "completed",
-        detail: installed.launcherPath,
+        state: installed.cleanupFailure === undefined ? "completed" : "warning",
+        detail: installed.cleanupFailure === undefined
+            ? installed.launcherPath
+            : `${installed.launcherPath}; ${installed.cleanupFailure}`,
     });
     const providerEnvironment = {
         ...input.providerEnvironment,
@@ -236,14 +294,14 @@ const installHopperAction = async (input) => {
         selectedClients: await filterClientsNeedingConfigure(input.host, input.selectedClients, providerEnvironment, input.host.registrationCommand),
     };
 };
-const installSkillAction = async (host, options, appliedActions) => {
+const installSkillAction = async (host, options, appliedActions, skillClientIds) => {
     const label = "REA reverse-engineering skill";
     emitProgress(options, {
         actionId: "install_skill",
         label,
         state: "started",
     });
-    const skill = await host.installSkill();
+    const skill = await host.installSkill(skillClientIds);
     if (skill === "failed") {
         emitProgress(options, {
             actionId: "install_skill",
@@ -334,3 +392,4 @@ const summarizeDoctor = (report) => ({
             },
         }),
 });
+const failureMessage = (cause) => cause instanceof Error ? cause.message : String(cause);

package/dist/application/SetupClientConfiguration.js

@@ -1,43 +1,82 @@
-import { clientRegistrationEntry, clientConfigurationValuesEqual, clientServerPath, grokServerListedDisabled, legacyClientServerPath, parseClientConfiguration, serializeClientConfiguration, withClientServers, } from "./ClientConfigurationDocument.js";
+import { readClientPolicyBlock } from "./GeminiClientSettings.js";
+import { readClientConfigurationFiles } from "./ClientConfigurationFiles.js";
+import { clientRegistrationEntry, clientConfigurationValuesEqual, clientServerListedDisabled, clientServerPath, legacyClientServerPath, OMP_DISABLED_SERVERS_KEY, parseClientConfiguration, serializeClientConfiguration, withClientServers, } from "./ClientConfigurationDocument.js";
 import { constants as fsConstants } from "node:fs";
-import { copyFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { copyFile, mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import writeFileAtomic from "write-file-atomic";
+import { clientRegistrationEnvironment } from "./ClientRegistrationEnvironment.js";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { npxRegistrationCommand } from "./ClientRegistrationIdentity.js";
 import { MCP_STARTUP_POLICY } from "../mcpStartupPolicy.js";
 import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
-const defaultCommand = () => npxRegistrationCommand();
+import { readRegularFileText, RegularFileCleanupFailure, } from "./RegularFileRead.js";
 /** 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);
+export const configureClientConfiguration = (client, environment = {}, command = npxRegistrationCommand()) => {
+    if (client.configPathError !== undefined)
+        return Promise.resolve({ status: "failed", reason: "path" });
+    return configureClientDocument(client, environment, command);
 };
-const configureClientDocument = async (client, environment, command, format) => {
+const configureClientDocument = async (client, environment, command) => {
+    const format = client.format;
+    if (format === undefined || format === "unsupported")
+        return { status: "failed", reason: "readback" };
+    const files = await readClientConfigurationFiles(client);
+    if (!files.ok) {
+        throwCleanupFailure(files.error);
+        return { status: "failed", reason: "readback" };
+    }
+    const policy = await readClientPolicyBlock(client, undefined, clientConfigurationDesired(client, environment, command, files.value.at(-1)));
+    if (!policy.ok) {
+        throwCleanupFailure(policy.error);
+        return { status: "failed", reason: "readback" };
+    }
+    if (policy.value !== undefined)
+        return { status: "failed", reason: "readback" };
     const transactionPath = await resolveClientConfigTransactionPath(client.configPath);
     if (transactionPath === undefined)
         return { status: "failed", reason: "path" };
     let original;
     try {
-        original = await readFile(transactionPath, "utf8");
+        original = await readRegularFileText(transactionPath);
     }
     catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw cause;
         if (!isMissing(cause))
             return { status: "failed", reason: "readback" };
     }
     let parsed;
     try {
         parsed = parseClientConfiguration(original ?? (format === "toml" || format === "grok" ? "" : "{}"), format);
+        const policy = await readClientPolicyBlock(client, parsed, clientConfigurationDesired(client, environment, command, parsed));
+        if (!policy.ok) {
+            throwCleanupFailure(policy.error);
+            return { status: "failed", reason: "readback" };
+        }
+        if (policy.value !== undefined)
+            return { status: "failed", reason: "readback" };
     }
     catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw cause;
         // Malformed existing configuration fails the readback gate.
         void cause;
         return { status: "failed", reason: "readback" };
     }
-    const desired = clientConfigurationDesired(client, environment, command, parsed.dialect);
+    const desired = clientConfigurationDesired(client, environment, command, parsed);
     if (registrationCurrent(parsed, desired))
         return { status: "unchanged" };
+    return persistClientConfiguration({
+        client,
+        transactionPath,
+        format,
+        original,
+        parsed,
+        desired,
+    });
+};
+const persistClientConfiguration = async ({ client, transactionPath, format, original, parsed, desired, }) => {
     const backupPath = original === undefined ? undefined : `${client.configPath}.rea.backup`;
     if (backupPath !== undefined &&
         !(await preserveConfigBackup(transactionPath, backupPath)))
@@ -45,12 +84,25 @@ const configureClientDocument = async (client, environment, command, format) =>
     // A native OpenCode V2 entry replaces REA's legacy V1 entry, which would
     // otherwise conflict with it.
     const legacyPath = legacyClientServerPath(parsed, PRODUCT_IDENTITY.mcpServerKey);
-    const document = withClientServers(parsed, { ...parsed.servers, [PRODUCT_IDENTITY.mcpServerKey]: desired }, PRODUCT_IDENTITY.mcpServerKey);
+    const registered = withClientServers(parsed, { ...parsed.servers, [PRODUCT_IDENTITY.mcpServerKey]: desired }, PRODUCT_IDENTITY.mcpServerKey);
+    // OMP's denylist would hide the registration; keep every other listed name.
+    const ompDisabled = parsed.dialect === "omp"
+        ? parsed.document[OMP_DISABLED_SERVERS_KEY]
+        : undefined;
+    const enableOmp = Array.isArray(ompDisabled) &&
+        ompDisabled.includes(PRODUCT_IDENTITY.mcpServerKey);
+    const document = enableOmp && Array.isArray(ompDisabled)
+        ? {
+            ...registered,
+            [OMP_DISABLED_SERVERS_KEY]: ompDisabled.filter((name) => name !== PRODUCT_IDENTITY.mcpServerKey),
+        }
+        : registered;
     try {
         await mkdir(dirname(client.configPath), { recursive: true });
         await writeFileAtomic(transactionPath, serializeClientConfiguration(document, format, original, [
             clientServerPath(parsed, PRODUCT_IDENTITY.mcpServerKey),
             ...(legacyPath === undefined ? [] : [legacyPath]),
+            ...(enableOmp ? [[OMP_DISABLED_SERVERS_KEY]] : []),
         ]), {
             encoding: "utf8",
             mode: 0o600,
@@ -62,13 +114,15 @@ const configureClientDocument = async (client, environment, command, format) =>
         return { status: "failed", reason: "write" };
     }
     try {
-        const readback = parseClientConfiguration(await readFile(transactionPath, "utf8"), format);
+        const readback = parseClientConfiguration(await readRegularFileText(transactionPath), format);
         if (!registrationCurrent(readback, desired)) {
             await restoreConfig(transactionPath, original);
             return { status: "failed", reason: "readback" };
         }
     }
     catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw cause;
         // Readback failure restores the transaction before reporting.
         void cause;
         await restoreConfig(transactionPath, original);
@@ -81,12 +135,27 @@ const configureClientDocument = async (client, environment, command, format) =>
 };
 /** Determine whether an existing client configuration matches the desired registration. */
 export const clientConfigurationAligned = async (client, providerEnvironment, command) => {
+    if (client.configPathError !== undefined)
+        return false;
     try {
-        const original = await readFile(client.configPath, "utf8");
+        const files = await readClientConfigurationFiles(client);
+        if (!files.ok) {
+            throwCleanupFailure(files.error);
+            return false;
+        }
+        const original = await readRegularFileText(client.configPath);
         const parsed = parseClientConfiguration(original, client.format);
-        return registrationCurrent(parsed, clientConfigurationDesired(client, providerEnvironment, command, parsed.dialect));
+        const policy = await readClientPolicyBlock(client, parsed, clientConfigurationDesired(client, providerEnvironment, command, parsed));
+        if (!policy.ok) {
+            throwCleanupFailure(policy.error);
+            return false;
+        }
+        return (policy.value === undefined &&
+            registrationCurrent(parsed, clientConfigurationDesired(client, providerEnvironment, command, parsed)));
     }
     catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw cause;
         // Unreadable configuration is treated as not aligned so setup repairs it.
         void cause;
         return false;
@@ -94,8 +163,28 @@ export const clientConfigurationAligned = async (client, providerEnvironment, co
 };
 /** Preflight one client configuration before setup presents any mutations. */
 export const inspectClientConfiguration = async (client, providerEnvironment, command) => {
+    if (client.configPathError !== undefined)
+        return { status: "invalid", remediation: client.configPathError };
     if (client.format === "unsupported")
         return { status: "already_current" };
+    const files = await readClientConfigurationFiles(client);
+    if (!files.ok) {
+        throwCleanupFailure(files.error);
+        return {
+            status: "invalid",
+            remediation: files.error.detail,
+        };
+    }
+    const policy = await readClientPolicyBlock(client, undefined, clientConfigurationDesired(client, providerEnvironment, command, files.value.at(-1)));
+    if (!policy.ok) {
+        throwCleanupFailure(policy.error);
+        return {
+            status: "invalid",
+            remediation: policy.error.detail,
+        };
+    }
+    if (policy.value !== undefined)
+        return { status: "invalid", remediation: policy.value };
     const transactionPath = await resolveClientConfigTransactionPath(client.configPath);
     if (transactionPath === undefined)
         return {
@@ -104,23 +193,37 @@ export const inspectClientConfiguration = async (client, providerEnvironment, co
         };
     let original;
     try {
-        original = await readFile(transactionPath, "utf8");
+        original = await readRegularFileText(transactionPath);
     }
     catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw cause;
         if (isMissing(cause))
             return { status: "create" };
         return {
             status: "invalid",
-            remediation: "The configuration file could not be read. Check its permissions before rerunning setup.",
+            remediation: `The configuration file could not be read. Check its permissions before rerunning setup. ${cause instanceof Error ? cause.message : String(cause)}`,
         };
     }
     try {
         const parsed = parseClientConfiguration(original, client.format);
-        const desired = clientConfigurationDesired(client, providerEnvironment, command, parsed.dialect);
+        const policy = await readClientPolicyBlock(client, parsed, clientConfigurationDesired(client, providerEnvironment, command, parsed));
+        if (!policy.ok) {
+            throwCleanupFailure(policy.error);
+            return {
+                status: "invalid",
+                remediation: policy.error.detail,
+            };
+        }
+        if (policy.value !== undefined)
+            return { status: "invalid", remediation: policy.value };
+        const desired = clientConfigurationDesired(client, providerEnvironment, command, parsed);
         if (registrationCurrent(parsed, desired))
             return { status: "already_current" };
     }
     catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw cause;
         // Malformed configuration is reported with the invalid remediation.
         void cause;
         return {
@@ -134,6 +237,10 @@ export const inspectClientConfiguration = async (client, providerEnvironment, co
     };
 };
 const isMissing = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";
+const throwCleanupFailure = (error) => {
+    if (error.cleanupFailure !== undefined)
+        throw error.cleanupFailure;
+};
 const preserveConfigBackup = async (source, destination) => {
     try {
         await copyFile(source, destination, fsConstants.COPYFILE_EXCL);
@@ -155,14 +262,18 @@ const restoreConfig = async (path, original) => {
         void cause;
     }
 };
-/** Whether REA's entry matches, no legacy entry remains, and Grok is not suppressing it. */
+/** Whether REA's entry matches, no legacy entry remains, and no client disable list suppresses it. */
 const registrationCurrent = (parsed, desired) => clientConfigurationValuesEqual(parsed.servers[PRODUCT_IDENTITY.mcpServerKey], desired) &&
     !Object.hasOwn(parsed.legacyServers, PRODUCT_IDENTITY.mcpServerKey) &&
-    !(parsed.dialect === "grok" &&
-        grokServerListedDisabled(parsed.document, PRODUCT_IDENTITY.mcpServerKey));
-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);
+    !clientServerListedDisabled(parsed, PRODUCT_IDENTITY.mcpServerKey);
+const clientConfigurationDesired = (client, providerEnvironment, command, parsed) => {
+    const format = parsed?.dialect ?? client.format ?? "json";
+    // Preserve explicitly configured server settings, never the ambient process
+    // environment. Newly discovered provider paths win only for their own keys.
+    const environment = clientRegistrationEnvironment(parsed, providerEnvironment);
+    if (!environment.ok)
+        throw environment.error;
+    const registration = clientRegistrationEntry(format, command.length === 0 ? [PRODUCT_IDENTITY.cliBinary, "mcp"] : command, environment.value);
     return {
         ...registration,
         ...(client.name === "codex" || client.name === "grok_build"