Files
reverse-engineering-anything/src/application/SupportedClients.ts
T
morluto 5f718ce30e refactor(kernel): give error-message, byte-hex and SHA-256 hex helpers one owner in a new src/kernel layer (#11542)
* refactor(kernel): give error-to-message text one owner in a new src/kernel layer

* fix(kernel): keep the regex worker's own error text inside its isolated source

* refactor(kernel): exclude copies that run in another realm from the error-message guard by name

The regex worker's source string and the page.evaluate fetch in PlaywrightScenarioRequest cannot import errorMessage. The guard now names them, so the counted baseline does not invite a later slice to rewrite them.

* refactor(kernel): migrate the long tail of inline error-message copies to errorMessage (#11552)

Every provider and adapter folder with six or fewer copies now calls errorMessage from src/kernel. Local helpers whose whole body was the copy (failureMessage, gdbErrorMessage, message, describe, reasonOf, recoveryFailureMessage and four local errorMessage definitions) are removed and their call sites call the owner.

Refs #11548

* refactor(kernel): give byte-to-hex formatting one owner in src/kernel (#11560)

byteToHex returns the two lowercase hexadecimal digits of one byte. All eight inline copies (native, contracts, domain firmware and desktop, pcap) call it, keeping their own 0x, % or \x notation, and a counted guard with an empty baseline keeps new copies out.

Refs #11548

* refactor(kernel): give one-shot SHA-256 hex digests one owner in src/kernel (#11562)

sha256Hex digests one in-memory value. A counted guard records the one-shot createHash("sha256").update(x).digest("hex") chains (115 in 101 files) and the first slice migrates domain, contracts and process (35 copies), removing local wrappers (sha256, sha256Text, hash) and the exported sha256Text. Incremental and streamed hashing is not counted.

Refs #11548

* refactor(kernel): migrate the application layer's inline error-message copies to errorMessage (#11563)

All 69 copies in src/application call errorMessage from src/kernel. Local helpers whose whole body was the copy (errorDetail, causeReason and five local errorMessage definitions) are removed and their call sites call the owner.

Refs #11548

* refactor(kernel): migrate the native provider's inline error-message copies to errorMessage (#11567)

All 49 copies in src/native call errorMessage from src/kernel. The local errorReason helpers in LldbCallTracer and LldbRetainedObservations, whose whole body was the copy, are removed and their call sites call the owner.

Refs #11548

* refactor(kernel): migrate the remaining inline error-message copies to errorMessage (#11569)
2026-11-16 07:05:30 +08:00

2206 lines
74 KiB
TypeScript

import type {
ClientRegistrationConnectionProfile,
ClientRegistrationProfile,
NativeStdioIncompatibility,
} from "./ClientRegistrationProfile.js";
import type {
ClientConfigurationFormat,
ClientInlineConfiguration,
} from "./ClientConfigurationDocument.js";
import { dirname, isAbsolute, join, posix, resolve, win32 } from "node:path";
import { fileURLToPath } from "node:url";
import { existsSync, lstatSync, readFileSync, statSync } from "node:fs";
import { err, ok, type Result } from "../domain/result.js";
import {
HermesClientPathError,
resolveHermesClientHome,
} from "./HermesClientHome.js";
import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
import {
absoluteCallerPath,
appendCallerPath,
} from "../filesystem/callerPath.js";
import {
absoluteClientRoot,
clientPathDependence,
absoluteXdgConfigHome,
type ClientRootFailure,
mcporterExpandHome,
mcporterXdgConfigHome,
vscodeUserDirectory,
xdgConfigHomeOrDefault,
} from "./ClientConfigRoots.js";
import { resolveWindowsClaudeDesktopLocation } from "./ClaudeDesktopConfigLocation.js";
import { resolveClineCliSettingsPath } from "./ClineCliLocation.js";
import type { JunieLocationSettings } from "./JunieClientSettings.js";
import { ConfigurationError } from "../domain/configurationErrors.js";
import {
kiloDefaultLocation,
kiloGlobalLocation,
type KiloLocationContext,
} from "./KiloClientLocation.js";
import {
type MsixPackageView,
windowsAppDataRoots,
} from "./MsixPackageStorage.js";
import { kiloProjectLocation } from "./McpRegistrationKiloLocations.js";
import type {
McpRegistrationLocation,
McpRegistrationLocationContext,
} from "./McpRegistrationLocations.js";
import { errorMessage } from "../kernel/errorMessage.js";
/** One supported client configuration location. */
export interface SetupClient {
readonly name: string;
readonly registrationProfile: ClientRegistrationProfile;
readonly displayName?: string;
readonly configPath: string;
/** User configuration files in increasing precedence, including the write target. */
readonly configPaths?: readonly string[];
/** Read-only configuration the client merges over every file layer. */
readonly inlineConfiguration?: ClientInlineConfiguration;
/** Read-only Gemini scopes and trust inputs; never setup write targets. */
readonly geminiSettings?: {
readonly systemPath: string;
readonly defaultsPath: string;
readonly workspaceDirectory: string;
readonly trustedFoldersPath: string;
readonly trustOverride?: boolean;
readonly platform: NodeJS.Platform;
};
/** Inputs deciding whether Junie loads its default user MCP location. */
readonly junieSettings?: JunieLocationSettings;
/** Unresolved path evidence only; consumers must not perform I/O on it. */
readonly configPathError?: string;
/** The access failure behind `configPathError`, when one was observed. */
readonly configPathFailure?: ConfigurationError;
/** Same-scope fallback ZCode stops loading after its first native server. */
readonly zcodeFallbackPath?: string;
readonly markerPath?: string;
/**
* Registration storage shared with other products. Its presence never proves
* this product is installed; only a recognizable REA-owned row in it proves
* ownership of a registration REA wrote.
*/
readonly sharedRegistration?: boolean;
/**
* Only a registration REA wrote makes this client applicable: setup never
* detects it, and doctor reports it only when its file holds a `rea` row.
*/
readonly registrationApplicability?: true;
/**
* The configuration is a private profile: folder 0700, file 0600. `home` is
* the caller's home folder, which that folder mode must never reach.
*/
readonly privateProfile?: { readonly home: string };
/**
* Layers before `configPath` belong to the system or an administrator: REA
* reads them for the effective registration but changes only `configPath`.
*/
readonly readOnlyLowerLayers?: true;
/** MSIX package storage that decides which configuration the client reads. */
readonly msixPackage?: MsixPackageView;
/** A running client can rewrite its configuration from memory. */
readonly quitBeforeSetup?: boolean;
/** Product-specific applicability evidence when configuration storage is shared. */
readonly discoveryPaths?: readonly string[];
readonly format?:
| "json"
| "claude_code"
| "toml"
| "vscode"
| "copilot_cli"
| "opencode"
| "commandcode"
| "grok"
| "omp"
| "pi"
| "kimi"
| "lm_studio"
| "hermes"
| "zcode_fallback"
| "zcode"
| "dsh"
| "zed"
| "amp"
| "fx"
| "goose"
| "kilo"
| "unsupported";
}
interface ClientPathFailure extends ClientRootFailure {
readonly msixPackage?: MsixPackageView;
/** The access failure that left the path unresolved, with its cause. */
readonly failure?: ConfigurationError;
}
type ClientPathResult = Result<string, ClientPathFailure>;
type ClientPath =
| readonly string[]
| ((paths: ClientPathContext) => string | ClientPathResult);
interface ClientPathContext {
readonly home: string;
readonly platform: NodeJS.Platform;
readonly env: Readonly<NodeJS.ProcessEnv>;
readonly systemPaths?: ClientSystemPaths;
}
/**
* Fixed system-wide files a client reads that no environment variable moves.
* Omitted entries use the client's native location; a caller supplies one only
* to isolate the host's real file.
*/
export interface ClientSystemPaths {
readonly gooseSystemConfig?: string;
}
/**
* A user-scope location decided by which configuration layers exist, which
* only an asynchronous probe can observe.
*/
interface ClientLayeredLocation {
readonly configPath: string;
/** Every file layer in load order, including `configPath`. */
readonly configPaths: readonly string[];
readonly inlineConfiguration?: ClientInlineConfiguration;
}
/** One resolved configuration location and its detection evidence. */
interface ClientLocation {
readonly configPath: string;
readonly markerPath: string;
readonly msixPackage?: MsixPackageView;
}
type ClientDefinition = ClientDefinitionBase & ClientDefinitionLocation;
type ClientDefinitionLocation =
| {
readonly configPath: ClientPath;
readonly markerPath: ClientPath;
readonly location?: undefined;
}
| {
/** Resolve configuration and marker together when they share probes. */
readonly location: (
context: ClientPathContext,
) => Result<ClientLocation, ClientPathFailure>;
readonly configPath?: undefined;
readonly markerPath?: undefined;
};
/**
* How `rea mcp add` selects this client beyond its user-scope registration.
* The registration itself uses this row's location, format, profile and
* read-scope facts, so both commands share one definition.
*/
type McpAddExposure = {
/** add-mcp agent aliases that select this client. */
readonly aliases?: readonly string[];
/** Dialect of the project document when it differs from the user one. */
readonly projectFormat?: ClientConfigurationFormat;
} & (
| {
/** Project documents in native precedence; absent means global-only. */
readonly projectPaths?: readonly [string, ...string[]];
readonly projectLocation?: undefined;
}
| {
/** A project location only an asynchronous probe can decide. */
readonly projectLocation: (
context: McpRegistrationLocationContext,
) => Promise<McpRegistrationLocation>;
readonly projectPaths?: undefined;
}
);
interface ClientDefinitionBase {
readonly name: string;
readonly registrationProfile: ClientRegistrationProfile;
readonly displayName: string;
readonly mcpAdd?: McpAddExposure;
readonly discoveryPaths?: (context: ClientPathContext) => readonly string[];
readonly sharedRegistration?: true;
readonly registrationApplicability?: true;
readonly privateProfile?: true;
readonly readOnlyLowerLayers?: true;
readonly format: NonNullable<SetupClient["format"]>;
readonly quitBeforeSetup?: boolean;
readonly zcodeFallbackPath?: (context: ClientPathContext) => string;
readonly skillPath?: ClientPath;
readonly configPaths?: (context: ClientPathContext) => readonly string[];
readonly geminiSettings?: (
context: ClientPathContext,
) => NonNullable<SetupClient["geminiSettings"]>;
/** Junie's location inputs, from the context and its resolved home. */
readonly junieSettings?: (
context: ClientPathContext,
location: ClientLocation,
) => JunieLocationSettings;
/**
* The write target and layers once present layers are observed.
* `resolveSupportedClients` applies it; the synchronous row keeps the
* default target and every candidate layer.
*/
readonly layeredLocation?: (
context: ClientPathContext,
) => Promise<Result<ClientLayeredLocation, ClientPathFailure>>;
}
const traeUserDirectory = ({
home,
platform,
env,
}: ClientPathContext): string => {
if (platform === "win32")
return join(windowsAppDataRoots(home, env).roaming, "Trae", "User");
if (platform === "darwin")
return join(home, "Library", "Application Support", "Trae", "User");
return join(xdgConfigHomeOrDefault({ home, env }), "Trae", "User");
};
/** Windows packaging decides which file Claude Desktop reads; see its resolver. */
const claudeDesktopLocation = (
context: ClientPathContext,
): Result<ClientLocation, ClientPathFailure> => {
if (context.platform === "win32")
return resolveWindowsClaudeDesktopLocation(context.home, context.env);
const directory =
context.platform === "linux"
? join(xdgConfigHomeOrDefault(context), "Claude")
: join(context.home, "Library", "Application Support", "Claude");
return ok({
configPath: join(directory, "claude_desktop_config.json"),
markerPath: directory,
});
};
const claudeCodeConfigDirectory = ({ home, env }: ClientPathContext): string =>
env.CLAUDE_CONFIG_DIR || home;
const claudeCodeMarkerDirectory = ({ home, env }: ClientPathContext): string =>
env.CLAUDE_CONFIG_DIR || join(home, ".claude");
const codexDirectory = ({ home, env }: ClientPathContext): string =>
env.CODEX_HOME || join(home, ".codex");
/** Kimi Code stores MCP declarations beside the rest of its home data. */
const kimiDirectory = ({ home, env }: ClientPathContext): string =>
env.KIMI_CODE_HOME || join(home, ".kimi-code");
/**
* LM Studio's findLMStudioHome, read-only: a home pointer file wins, then an
* existing ~/.cache/lm-studio, then ~/.lmstudio. Setup never writes the pointer.
*/
const lmStudioLocation = ({
home,
}: ClientPathContext): Result<ClientLocation, ClientPathFailure> => {
const pointerPath = join(home, ".lmstudio-home-pointer");
let directory: string;
try {
directory = readFileSync(pointerPath, "utf8").trim();
} catch (cause: unknown) {
if (!(cause instanceof Error && "code" in cause && cause.code === "ENOENT"))
return err({
path: pointerPath,
message: `${pointerPath} could not be read, so REA cannot establish which LM Studio home holds mcp.json: ${errorMessage(cause)}. Repair access to that file, then rerun.`,
});
const cache = join(home, ".cache", "lm-studio");
directory = existsSync(cache) ? cache : join(home, ".lmstudio");
}
if (!isAbsolute(directory))
return err({
path: pointerPath,
message: `${pointerPath} does not hold an absolute LM Studio home path. Correct or remove that file, then rerun.`,
});
return ok({ configPath: join(directory, "mcp.json"), markerPath: directory });
};
const qoderDirectory = ({ home, env }: ClientPathContext): string =>
env.QODER_CONFIG_DIR || join(home, ".qoder");
/** Droid's override selects the home containing .factory, including personal skills. */
const factoryDirectory = ({ home, env }: ClientPathContext): string =>
join(env.FACTORY_HOME_OVERRIDE || home, ".factory");
/** Match Qwen Code's home override, including tilde and cwd-relative paths. */
const qwenCodeDirectory = ({ home, env }: ClientPathContext): string => {
const override = env.QWEN_HOME;
if (!override) return join(home, ".qwen");
const expanded =
override === "~"
? home
: override.startsWith("~/") || override.startsWith("~\\")
? join(
home,
...override
.slice(2)
.split(/[/\\]+/)
.filter(Boolean),
)
: override;
return isAbsolute(expanded) ? expanded : resolve(expanded);
};
const grokDirectory = ({ home, env }: ClientPathContext): string =>
env.GROK_HOME || join(home, ".grok");
/** Match Harness home-paths for both independent roots; trim only to detect blanks. */
const dshDirectory = (
home: string,
override: string | undefined,
fallback: string,
): string => {
const selected =
override !== undefined && override.trim().length > 0
? override
: join(home, fallback);
const expanded =
selected === "~"
? home
: selected.startsWith("~/") || selected.startsWith("~\\")
? join(home, selected.slice(2))
: selected;
return resolve(expanded);
};
const dshHomeDirectory = ({ home, env }: ClientPathContext): string =>
dshDirectory(home, env.DSH_HOME, ".dsh");
const dshPatchDirectory = (context: ClientPathContext): string =>
join(dshHomeDirectory(context), "cordis.patch.yml");
const hermesDirectory = ({ home, platform, env }: ClientPathContext): string =>
resolveHermesClientHome(home, platform, env);
/** Grok Bot uses an absolute SAND_DATA_ROOT; anything else stays ~/.grokbot. */
const grokBotDirectory = ({ home, env }: ClientPathContext): string => {
const root = env.SAND_DATA_ROOT;
return root !== undefined && root !== "" && isAbsolute(root)
? root
: join(home, ".grokbot");
};
/**
* Grok Bot stores connectors in the signed-in account and runs them on its
* hosted computer. The data directory is only a detection marker.
*/
export const GROK_BOT_MANUAL_REGISTRATION_REMEDIATION =
"Grok Bot keeps connectors in the signed-in account and runs them on its hosted computer. Setup does not write that account store, and a data-directory mcp.json is not a registration. In the Grok Bot chat, add a custom MCP server named rea that runs on the Bot's computer with `npx -y rea-agents@<version> mcp`. Do not put credentials in the command or arguments. A stdio server on this machine is not attached.";
/** Remediation for a client whose connector is not a local configuration file. */
export const manualRegistrationRemediation = (
clientName: string,
): string | undefined =>
clientName === "grok_bot"
? GROK_BOT_MANUAL_REGISTRATION_REMEDIATION
: undefined;
/**
* Facts a setup plan must disclose so an approved registration persists:
* which file an MSIX package reads, and that a running client can overwrite it.
*/
export const registrationPersistenceDetail = (
client: SetupClient,
): string | undefined => {
const name = client.displayName ?? client.name;
const msix = client.msixPackage;
const packageDetail =
msix === undefined
? undefined
: client.configPath === msix.privateConfigPath
? `${name} is installed as MSIX package ${msix.packageFamilyName}, which reads this package-private file instead of ${msix.appDataConfigPath}.`
: `${name} is installed as MSIX package ${msix.packageFamilyName}, which reads this file until it saves its own copy at ${msix.privateConfigPath}.`;
const quitDetail =
client.quitBeforeSetup === true
? `Quit ${name} fully before approving; closing its window is not enough. A running ${name} can rewrite this file from memory and drop the registration. Start it again after setup.`
: undefined;
const details = [packageDetail, quitDetail].filter(
(detail): detail is string => detail !== undefined,
);
return details.length === 0 ? undefined : details.join(" ");
};
/**
* What a direct registration (no approval step) must tell the caller after it
* wrote a client that can rewrite its configuration from memory.
*/
export const runningClientRewriteNotice = (
client: Pick<SetupClient, "name" | "displayName" | "quitBeforeSetup">,
): string | undefined => {
if (client.quitBeforeSetup !== true) return undefined;
const name = client.displayName ?? client.name;
return `A running ${name} can rewrite its configuration from memory and drop the registration. If ${name} was running, quit it fully (closing its window is not enough), rerun rea mcp add, then start ${name} again.`;
};
/**
* Why this process must not change an MSIX client's configuration. A process
* the running app started sees its redirected AppData, and the app would
* overwrite the change from memory; an unknown view cannot rule that out.
*/
export const registrationWriteBlocker = (
client: SetupClient,
operation: "setup" | "uninstall" | "mcp add",
): string | undefined => {
const msix = client.msixPackage;
if (msix === undefined || msix.processView === "direct") return undefined;
const name = client.displayName ?? client.name;
if (msix.processView === "redirected")
return `This process was started from ${name}'s MSIX package ${msix.packageFamilyName}: its AppData is redirected into that package, so ${name} is running and would overwrite ${msix.privateConfigPath} from memory. Quit ${name} fully, then rerun ${operation} from a terminal that ${name} did not start.`;
// Registration writes the configuration the app reads; uninstall cleans both files.
const manualEdit =
operation !== "uninstall"
? `Add REA's entry to ${client.configPath} by hand`
: `Remove REA's entry by hand from each of ${msix.privateConfigPath} and ${msix.appDataConfigPath} that has one`;
return `REA cannot tell whether ${name}'s MSIX package ${msix.packageFamilyName} started this process, because no private file under ${dirname(dirname(msix.privateConfigPath))} could be compared with ${dirname(dirname(msix.appDataConfigPath))}, and a ${name} that started it would overwrite the change from memory. ${manualEdit} while ${name} is fully quit, or rerun ${operation} from a terminal that ${name} did not start once REA can compare a private file there.`;
};
/** The MSIX package view, if any, that redirects this process's AppData writes. */
export const appDataRedirection = (
clients: readonly SetupClient[],
): MsixPackageView | undefined =>
clients.find(({ msixPackage }) => msixPackage?.processView === "redirected")
?.msixPackage;
const OMP_PROFILE_NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/u;
const OMP_RESERVED_PROFILE =
/^(?:CON|PRN|AUX|NUL|COM[0-9]|LPT[0-9])(?:\..*)?$/iu;
/**
* The OMP agent directory whose `mcp.json` holds user-scope MCP servers. OMP
* joins PI_CONFIG_DIR to the home directory, and a named profile ignores
* PI_CODING_AGENT_DIR. Relative overrides use the setup process working directory.
*/
const ompAgentDirectory = (context: ClientPathContext): ClientPathResult => {
const root = join(context.home, context.env.PI_CONFIG_DIR || ".omp");
// OMP_PROFILE wins even when empty. Match OMP's validation on every host.
const profile = (context.env.OMP_PROFILE ?? context.env.PI_PROFILE)?.trim();
if (profile !== undefined && profile !== "" && profile !== "default") {
if (
!OMP_PROFILE_NAME.test(profile) ||
profile.endsWith(".") ||
OMP_RESERVED_PROFILE.test(profile)
)
return err({
path: root,
message: `Invalid OMP profile ${JSON.stringify(profile)}: names must match ^[a-z0-9][a-z0-9._-]{0,63}$, cannot end with ".", and cannot be a Windows reserved device name (CON, PRN, AUX, NUL, COM0-9, LPT0-9, including extensions). Repair OMP_PROFILE or PI_PROFILE before configuring OMP.`,
});
return ok(join(root, "profiles", profile, "agent"));
}
const override = context.env.PI_CODING_AGENT_DIR;
return ok(override ? resolve(override) : join(root, "agent"));
};
/**
* Pi's public getAgentDir()/normalizePath semantics, not OMP's profiles.
* Keep relative overrides relative: filesystem consumers resolve them in cwd.
*/
const piAgentDirectory = ({
home,
platform,
env,
}: ClientPathContext): string => {
const paths = platform === "win32" ? win32 : { join };
let directory = env.PI_CODING_AGENT_DIR;
if (!directory) return paths.join(home, ".pi", "agent");
if (
platform === "win32" &&
directory.startsWith("/") &&
!directory.startsWith("//") &&
!directory.includes("\\")
) {
const drive = /^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/iu.exec(
directory,
);
if (drive !== null)
directory = `${drive[1]?.toUpperCase()}:\\${drive[2]?.replaceAll("/", "\\") ?? ""}`;
}
if (directory === "~") return home;
if (
directory.startsWith("~/") ||
(platform === "win32" && directory.startsWith("~\\"))
)
return paths.join(home, directory.slice(2));
if (directory.startsWith("file://"))
return fileURLToPath(directory, { windows: platform === "win32" });
return directory;
};
const copilotDirectory = ({ home, env }: ClientPathContext): string =>
env.COPILOT_HOME || join(home, ".copilot");
const commandCodeDirectory = ({ home }: ClientPathContext): string =>
join(home, ".commandcode");
/**
* OpenCode appends `OPENCODE_CONFIG_DIR` only when the value is non-empty.
* An empty variable is the same as unset and leaves the XDG directory in place.
*/
const openCodeOverrideDirectory = (
env: ClientPathContext["env"],
): string | undefined => {
const directory = env.OPENCODE_CONFIG_DIR;
return directory === undefined || directory === "" ? undefined : directory;
};
const opencodeDirectory = (context: ClientPathContext): string =>
openCodeOverrideDirectory(context.env) ??
join(xdgConfigHomeOrDefault(context), "opencode");
/** OpenCode loads global JSON before JSONC, then explicit file and directory overrides. */
const openCodeConfigurationPaths = (
context: ClientPathContext,
): readonly string[] => {
const directory = join(xdgConfigHomeOrDefault(context), "opencode");
const overrideDirectory = openCodeOverrideDirectory(context.env);
const paths = [
join(directory, "config.json"),
join(directory, "opencode.json"),
join(directory, "opencode.jsonc"),
...(context.env.OPENCODE_CONFIG ? [context.env.OPENCODE_CONFIG] : []),
...(overrideDirectory !== undefined
? [
join(overrideDirectory, "opencode.json"),
join(overrideDirectory, "opencode.jsonc"),
]
: []),
];
const resolved = paths.map((path) => resolve(path));
return resolved.filter((path, index) => resolved.lastIndexOf(path) === index);
};
const existingOpenCodeConfigPath = (context: ClientPathContext): string => {
// The selected directory is loaded after an explicit file by OpenCode V1.
const overrideDirectory = openCodeOverrideDirectory(context.env);
const candidates =
overrideDirectory !== undefined
? [
join(overrideDirectory, "opencode.json"),
join(overrideDirectory, "opencode.jsonc"),
].map((path) => resolve(path))
: context.env.OPENCODE_CONFIG
? [resolve(context.env.OPENCODE_CONFIG)]
: [
join(opencodeDirectory(context), "opencode.json"),
join(opencodeDirectory(context), "opencode.jsonc"),
].map((path) => resolve(path));
return (
[...candidates].reverse().find((path) => {
try {
lstatSync(path);
return true;
} catch (cause: unknown) {
return !(
cause instanceof Error &&
"code" in cause &&
cause.code === "ENOENT"
);
}
}) ??
resolve(
overrideDirectory !== undefined
? join(overrideDirectory, "opencode.json")
: context.env.OPENCODE_CONFIG ||
join(opencodeDirectory(context), "opencode.json"),
)
);
};
const geminiSettings = ({
home,
platform,
env,
}: ClientPathContext): NonNullable<SetupClient["geminiSettings"]> => {
const system =
env.GEMINI_CLI_SYSTEM_SETTINGS_PATH ||
(platform === "darwin"
? "/Library/Application Support/GeminiCli/settings.json"
: platform === "win32"
? "C:\\ProgramData\\gemini-cli\\settings.json"
: "/etc/gemini-cli/settings.json");
const trustOverride =
env.GEMINI_RESTRICTED_MODE === "true" ||
env.GEMINI_CLI_TRUST_WORKSPACE === "false"
? false
: env.GEMINI_CLI_TRUST_WORKSPACE === "true"
? true
: undefined;
return {
systemPath: system,
defaultsPath:
env.GEMINI_CLI_SYSTEM_DEFAULTS_PATH ||
join(dirname(system), "system-defaults.json"),
workspaceDirectory: process.cwd(),
trustedFoldersPath:
env.GEMINI_CLI_TRUSTED_FOLDERS_PATH ||
join(env.GEMINI_CLI_HOME || home, ".gemini", "trustedFolders.json"),
...(trustOverride === undefined ? {} : { trustOverride }),
platform,
};
};
const devinDirectory = ({ home, platform, env }: ClientPathContext): string =>
platform === "win32"
? join(windowsAppDataRoots(home, env).roaming, "devin")
: join(xdgConfigHomeOrDefault({ home, env }), "devin");
/** The Cline extension's settings in one editor's global storage. */
const clineSettingsDirectory =
(dataFolder: string) =>
(context: ClientPathContext): string =>
join(
vscodeUserDirectory(context, dataFolder),
"globalStorage",
"saoudrizwan.claude-dev",
"settings",
);
const clineVscodeSettingsDirectory = clineSettingsDirectory("Code");
/** Flathub's Zed (`dev.zed.Zed`) gets this XDG_CONFIG_HOME inside its sandbox. */
const ZED_FLATPAK_CONFIG = [".var", "app", "dev.zed.Zed", "config"] as const;
const directoryPresent = (path: string): Result<boolean, ClientPathFailure> => {
try {
lstatSync(path);
return ok(true);
} catch (cause: unknown) {
if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
return ok(false);
return err({
path,
message: `Cannot determine whether ${path} exists: ${errorMessage(cause)}. Repair its access before configuring Zed.`,
});
}
};
/** Whether two existing paths resolve to the same folder, by device and inode. */
const sameDirectory = (
first: string,
second: string,
): Result<boolean, ClientPathFailure> => {
const identities: { dev: bigint; ino: bigint }[] = [];
for (const path of [first, second]) {
try {
const { dev, ino } = statSync(path, { bigint: true });
identities.push({ dev, ino });
} catch (cause: unknown) {
return err({
path,
message: `Cannot resolve ${path}: ${errorMessage(cause)}. Repair it before configuring Zed.`,
});
}
}
const [a, b] = identities;
return ok(
a !== undefined && b !== undefined && a.dev === b.dev && a.ino === b.ino,
);
};
/**
* Zed's `paths::config_dir`. On Windows it reads the RoamingAppData known
* folder, which APPDATA normally names. On Linux and FreeBSD,
* `FLATPAK_XDG_CONFIG_HOME` wins, then `dirs::config_dir`, which admits only an
* absolute XDG_CONFIG_HOME. A Flathub Zed reads its sandbox's config folder,
* so REA uses it when only that folder exists and refuses to guess when a
* native configuration exists too.
*/
const zedLocation = ({
home,
platform,
env,
}: ClientPathContext): Result<ClientLocation, ClientPathFailure> => {
const at = (directory: string): ClientLocation => ({
configPath: join(directory, "settings.json"),
markerPath: directory,
});
if (platform === "darwin") return ok(at(join(home, ".config", "zed")));
if (platform === "win32")
return ok(at(join(windowsAppDataRoots(home, env).roaming, "Zed")));
const flatpakOverride = env.FLATPAK_XDG_CONFIG_HOME;
if (flatpakOverride) {
const selected = absoluteClientRoot(
flatpakOverride,
"FLATPAK_XDG_CONFIG_HOME",
"Zed",
platform,
);
return selected.ok ? ok(at(join(selected.value, "zed"))) : selected;
}
const native = join(absoluteXdgConfigHome({ home, env }), "zed");
const sandboxed = join(home, ...ZED_FLATPAK_CONFIG, "zed");
const flatpak = directoryPresent(sandboxed);
if (!flatpak.ok) return flatpak;
if (!flatpak.value) return ok(at(native));
const nativePresent = directoryPresent(native);
if (!nativePresent.ok) return nativePresent;
if (!nativePresent.value) return ok(at(sandboxed));
// XDG_CONFIG_HOME or a link may make both names one folder.
const same = sameDirectory(native, sandboxed);
if (!same.ok) return same;
return same.value
? ok(at(native))
: err({
path: sandboxed,
message: `Both ${native} and the Flatpak Zed folder ${sandboxed} exist, so REA cannot tell which Zed you use. Remove the configuration of the Zed you no longer use, then configure Zed again.`,
});
};
const regularPathPresent = (
path: string,
): Result<boolean, ClientPathFailure> => {
try {
lstatSync(path);
return ok(true);
} catch (cause: unknown) {
if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
return ok(false);
return err({
path,
message: `Cannot determine whether ${path} exists: ${errorMessage(cause)}. Repair its access before configuring MCPorter.`,
});
}
};
/**
* MCPorter's home layer (`listConfigLayerPaths`): a non-empty
* `MCPORTER_CONFIG` is the only file it loads; otherwise the first existing of
* the XDG and legacy `~/.mcporter` candidates (`mcporterConfigCandidates`),
* where only an absolute `XDG_CONFIG_HOME` counts. A new file goes where
* `mcporter config add --scope home` puts it. A relative `MCPORTER_CONFIG`
* follows each invocation's directory, which REA cannot know.
*/
const mcporterLocation = ({
home,
platform,
env,
}: ClientPathContext): Result<ClientLocation, ClientPathFailure> => {
const pathApi = platform === "win32" ? win32 : posix;
const legacy = join(home, ".mcporter");
const selected = env.MCPORTER_CONFIG?.trim();
if (selected) {
const path = mcporterExpandHome(selected, home);
// MCPorter applies path.resolve: `..` collapses lexically, not through
// links. The selected file is also the evidence that MCPorter is in use.
const absolute = absoluteClientRoot(
path,
"MCPORTER_CONFIG",
"MCPorter",
platform,
);
return absolute.ok
? ok({
configPath: pathApi.resolve(absolute.value),
markerPath: pathApi.resolve(absolute.value),
})
: absolute;
}
const configHome = mcporterXdgConfigHome({ home, platform, env });
const base = configHome === undefined ? legacy : join(configHome, "mcporter");
const candidates = [base, ...(base === legacy ? [] : [legacy])].flatMap(
(directory) => [
join(directory, "mcporter.json"),
join(directory, "mcporter.jsonc"),
],
);
for (const candidate of candidates) {
const present = regularPathPresent(candidate);
if (!present.ok) return present;
// The loaded file's folder is the evidence, even when it is the legacy one.
if (present.value)
return ok({ configPath: candidate, markerPath: dirname(candidate) });
}
return ok({ configPath: join(base, "mcporter.json"), markerPath: base });
};
/** mcporter getUrl's native nullish priority; an empty first value suppresses later aliases. */
const MCPORTER_URL_FIELDS = [
"baseUrl",
"base_url",
"url",
"serverUrl",
"server_url",
] as const;
const MCPORTER_STDIO_INCOMPATIBILITIES: readonly NativeStdioIncompatibility[] =
[
// RawEntrySchema admits only optional strings, including an empty string.
...MCPORTER_URL_FIELDS.map((field): NativeStdioIncompatibility => ({
kind: "invalid-string",
field,
})),
...MCPORTER_URL_FIELDS.map((field, index): NativeStdioIncompatibility =>
index === 0
? { kind: "truthy", field }
: {
kind: "all",
conditions: [
...MCPORTER_URL_FIELDS.slice(0, index).map(
(prior): NativeStdioIncompatibility => ({
kind: "nullish",
field: prior,
}),
),
{ kind: "truthy", field },
],
},
),
];
/**
* Amp's user settings: `settings.json` or `settings.jsonc` in
* `~/.config/amp` on every platform. Amp does not document which one wins
* when both exist, so that case stays unresolved.
*/
const ampLocation = ({
home,
}: ClientPathContext): Result<ClientLocation, ClientPathFailure> => {
const directory = join(home, ".config", "amp");
const candidates = ["settings.json", "settings.jsonc"].map((name) =>
join(directory, name),
);
const present: string[] = [];
for (const candidate of candidates) {
try {
lstatSync(candidate);
present.push(candidate);
} catch (cause: unknown) {
if (
!(cause instanceof Error && "code" in cause && cause.code === "ENOENT")
)
return err({
path: candidate,
message: `Cannot determine whether ${candidate} exists: ${errorMessage(cause)}. Repair its access before configuring Amp.`,
});
}
}
if (present.length > 1)
return err({
path: directory,
message: `Both ${candidates[0]} and ${candidates[1]} exist, and Amp does not document which one it reads. Merge them into one file before configuring Amp.`,
});
return ok({
configPath: present[0] ?? join(directory, "settings.json"),
markerPath: directory,
});
};
/**
* fx's profile folder (`useFxHome`): a non-empty `FX_HOME` must be absolute
* and name neither the root nor the home folder, ignoring trailing slashes;
* otherwise `~/.fx`. fx refuses an invalid value, so REA does too.
*/
const fxLocation = ({
home,
platform,
env,
}: ClientPathContext): Result<ClientLocation, ClientPathFailure> => {
const value = env.FX_HOME;
const pathApi = platform === "win32" ? win32 : posix;
if (!value) {
const directory = join(home, ".fx");
return ok({
configPath: join(directory, "mcp.json"),
markerPath: directory,
});
}
const trimmed = value.replace(/\/+$/u, "");
// fx opens FX_HOME as written, so `.` and `..` resolve through links on the
// filesystem. Refusing them keeps REA's file and its root/home check on the
// folder fx opens, so the private profile mode can never land on home.
const dotSegment = trimmed
.split(/[\\/]/u)
.some((segment) => segment === "." || segment === "..");
if (
!pathApi.isAbsolute(value) ||
trimmed.length === 0 ||
dotSegment ||
pathApi.parse(trimmed).root === trimmed ||
trimmed === home.replace(/[\\/]+$/u, "")
)
return err({
path: value,
message:
"FX_HOME must be an absolute path without . or .. segments, other than the root and home folders. Repair FX_HOME before configuring fx; no settings were written.",
});
return ok({
configPath: pathApi.join(trimmed, "mcp.json"),
markerPath: trimmed,
});
};
/**
* Junie's home: `JUNIE_HOME` for Junie CLI, else `~/.junie`. add-mcp notes the
* JetBrains plugin always reads `~/.junie`. Junie resolves a relative
* `JUNIE_HOME` against its own working directory, so REA refuses one.
*/
const junieLocation = ({
home,
platform,
env,
}: ClientPathContext): Result<ClientLocation, ClientPathFailure> => {
const selected = env.JUNIE_HOME
? absoluteClientRoot(env.JUNIE_HOME, "JUNIE_HOME", "Junie", platform)
: ok(join(home, ".junie"));
return selected.ok
? ok({
configPath: join(selected.value, "mcp", "mcp.json"),
markerPath: selected.value,
})
: selected;
};
/**
* Goose's user configuration (`Paths::config_dir`): an absolute
* `GOOSE_PATH_ROOT` selects `<root>/config`; otherwise etcetera's app strategy,
* where only an absolute `XDG_CONFIG_HOME` counts.
*/
const gooseUserConfigPath = ({ home, platform, env }: ClientPathContext) => {
const pathApi = platform === "win32" ? win32 : posix;
const root = env.GOOSE_PATH_ROOT;
if (root && pathApi.isAbsolute(root))
return pathApi.join(root, "config", "config.yaml");
return platform === "win32"
? join(
windowsAppDataRoots(home, env).roaming,
"Block",
"goose",
"config",
"config.yaml",
)
: join(absoluteXdgConfigHome({ home, env }), "goose", "config.yaml");
};
/**
* `GOOSE_ADDITIONAL_CONFIG_FILES`, split as Rust's `env::split_paths`: `:` on
* Unix; on Windows `;` outside double quotes, which are removed.
*/
const gooseAdditionalConfigFiles = ({
platform,
env,
}: Pick<ClientPathContext, "platform" | "env">): string[] => {
const value = env.GOOSE_ADDITIONAL_CONFIG_FILES ?? "";
if (platform !== "win32")
return value.split(":").filter((path) => path.length > 0);
const paths: string[] = [];
let current = "";
let quoted = false;
for (const character of value) {
if (character === '"') quoted = !quoted;
else if (character === ";" && !quoted) {
paths.push(current);
current = "";
} else current += character;
}
paths.push(current);
return paths.filter((path) => path.length > 0);
};
/**
* Goose's layers in increasing precedence (`Config::default`): the system
* file, each `GOOSE_ADDITIONAL_CONFIG_FILES` entry, then the user file it
* writes. A relative additional entry follows Goose's working directory, and a
* Windows drive-less one its current drive, which REA cannot know.
*/
const gooseLocation = (
context: ClientPathContext,
): Result<ClientLocation, ClientPathFailure> => {
const configPath = gooseUserConfigPath(context);
for (const path of gooseAdditionalConfigFiles(context)) {
const dependence = clientPathDependence(path, context.platform);
if (dependence === "relative")
return err({
path,
message: `GOOSE_ADDITIONAL_CONFIG_FILES names the relative path ${path}, which Goose resolves against its own working directory. Use absolute paths before configuring Goose.`,
});
if (dependence === "driveless")
return err({
path,
message: `GOOSE_ADDITIONAL_CONFIG_FILES names ${path}, which has no drive, so the file Goose reads depends on its current drive. Use a path with a drive letter or a UNC path before configuring Goose.`,
});
}
return ok({ configPath, markerPath: configPath });
};
/**
* Goose's load order: the system file, each additional file, then the user
* file it writes. An additional entry can name the user file too; Goose then
* loads it twice, and its last load decides precedence.
*/
const gooseConfigPaths = (context: ClientPathContext) => [
context.systemPaths?.gooseSystemConfig ??
(context.platform === "win32"
? win32.join(
context.env.PROGRAMDATA || "C:\\ProgramData",
"goose",
"config.yaml",
)
: "/etc/goose/config.yaml"),
...gooseAdditionalConfigFiles(context),
gooseUserConfigPath(context),
];
/**
* FreeBuff's own profile directory (its `state.json` root, fixed under
* `.config` on every platform). The shared `~/.agents` folder is not
* FreeBuff-specific: REA's own skill installs create it, so it cannot
* prove FreeBuff is installed.
*/
const freebuffProfileDirectory = ({ home }: ClientPathContext): string =>
join(home, ".config", "freebuff-desktop");
type ClientDefinitionInput = Omit<ClientDefinitionBase, "registrationProfile"> &
ClientDefinitionLocation & {
readonly registrationConnection: ClientRegistrationConnectionProfile;
};
/** Bind native identity once while retaining the original definition's literal name. */
/**
* Kilo resolves its configured paths against its own working directory, which
* setup cannot know, so the table accepts only absolute ones.
*/
const kiloTableContext = (context: ClientPathContext): KiloLocationContext => ({
root: context,
path: (path) => {
// Normalized as rea mcp add normalizes it, so joined layer paths compare.
const dependence = clientPathDependence(path, context.platform);
if (dependence === undefined)
return absoluteCallerPath(path, { platform: context.platform });
throw new KiloPathDependenceError(path, dependence);
},
});
class KiloPathDependenceError extends Error {
constructor(
readonly path: string,
dependence: "relative" | "driveless",
) {
super(
dependence === "relative"
? `Kilo's configuration path ${path} is relative, so the file Kilo reads depends on its working directory. Set an absolute path before configuring Kilo.`
: `Kilo's configuration path ${path} has no drive, so the file Kilo reads depends on its current drive. Set a path with a drive letter or a UNC path before configuring Kilo.`,
);
}
}
const kiloPathFailure = (cause: unknown): ClientPathFailure => {
if (cause instanceof KiloPathDependenceError)
return { path: cause.path, message: cause.message };
throw cause;
};
const kiloLocation = (
context: ClientPathContext,
): Result<ClientLocation, ClientPathFailure> => {
try {
const { configPath, markerPath } = kiloDefaultLocation(
kiloTableContext(context),
);
return ok({ configPath, markerPath });
} catch (cause: unknown) {
return err(kiloPathFailure(cause));
}
};
const kiloLayeredLocation = async (
context: ClientPathContext,
): Promise<Result<ClientLayeredLocation, ClientPathFailure>> => {
const kilo = kiloTableContext(context);
try {
const { configPath, configPaths, inlineConfiguration } =
await kiloGlobalLocation(kilo);
return ok({
configPath,
configPaths,
...(inlineConfiguration === undefined ? {} : { inlineConfiguration }),
});
} catch (cause: unknown) {
if (cause instanceof ConfigurationError)
return err({
path: kiloDefaultLocation(kilo).markerPath,
message: cause.message,
failure: cause,
});
return err(kiloPathFailure(cause));
}
};
/** Candidate layers when relative paths leave the location unresolved. */
const kiloCandidatePaths = (context: ClientPathContext): readonly string[] => {
try {
return kiloDefaultLocation(kiloTableContext(context)).configPaths;
} catch (cause: unknown) {
kiloPathFailure(cause);
return [];
}
};
const kiloDiscoveryPaths = (context: ClientPathContext): readonly string[] => {
try {
return kiloDefaultLocation(kiloTableContext(context)).discoveryPaths;
} catch (cause: unknown) {
kiloPathFailure(cause);
return [];
}
};
const defineClient = <const Definition extends ClientDefinitionInput>(
definition: Definition,
) => {
const { registrationConnection, ...metadata } = definition;
return {
...metadata,
registrationProfile: {
nativeClient: definition.name,
connection: registrationConnection,
},
};
};
/** Stable product metadata used to derive setup discovery and documentation. */
export const SUPPORTED_CLIENT_DEFINITIONS = [
defineClient({
name: "claude_code",
mcpAdd: { projectPaths: [".mcp.json"] },
registrationConnection: {
kind: "flat",
fields: ["type", "url"],
stdio: [
{ kind: "optional-enum", field: "type", values: ["stdio"] },
{ kind: "present", field: "url" },
],
},
displayName: "Claude Code",
skillPath: (context: ClientPathContext) =>
join(claudeCodeMarkerDirectory(context), "skills"),
configPath: (context: ClientPathContext) =>
join(claudeCodeConfigDirectory(context), ".claude.json"),
markerPath: claudeCodeMarkerDirectory,
format: "claude_code",
}),
defineClient({
name: "claude_desktop",
mcpAdd: {},
registrationConnection: {
kind: "flat",
fields: ["type"],
stdio: [{ kind: "optional-enum", field: "type", values: ["stdio"] }],
},
displayName: "Claude Desktop",
location: claudeDesktopLocation,
quitBeforeSetup: true,
format: "json",
}),
defineClient({
name: "codex",
mcpAdd: { projectPaths: [".codex/config.toml"] },
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "non-nullish", field: "url" }],
},
displayName: "Codex",
configPath: (context: ClientPathContext) =>
appendCallerPath(codexDirectory(context), "config.toml"),
markerPath: codexDirectory,
format: "toml",
}),
defineClient({
name: "cursor",
mcpAdd: { projectPaths: [".cursor/mcp.json"] },
registrationConnection: {
kind: "flat",
fields: ["type", "url"],
stdio: [
{ kind: "optional-enum", field: "type", values: ["stdio"] },
{ kind: "present", field: "url" },
],
},
displayName: "Cursor",
configPath: [".cursor", "mcp.json"],
markerPath: [".cursor"],
format: "json",
}),
defineClient({
name: "codebuddy",
registrationConnection: {
kind: "stdio-only",
documentedFields: ["env", "type"],
},
displayName: "CodeBuddy",
skillPath: [".codebuddy", "skills"],
configPath: [".codebuddy", "mcp.json"],
markerPath: [".codebuddy"],
format: "json",
}),
defineClient({
// Cline discovers the shared ~/.agents/skills directory. Keep REA's
// existing shared destination instead of managing another skill copy.
name: "cline",
mcpAdd: {},
registrationConnection: { kind: "cline" },
displayName: "Cline CLI",
location: ({ home, env, platform }: ClientPathContext) => {
const selected = resolveClineCliSettingsPath({
home,
platform,
environment: env,
});
const pathApi = platform === "win32" ? win32 : posix;
return selected.ok
? ok({
configPath: selected.value,
markerPath: pathApi.dirname(selected.value),
})
: selected;
},
format: "json",
}),
defineClient({
name: "gemini_cli",
mcpAdd: { aliases: ["gemini"], projectPaths: [".gemini/settings.json"] },
registrationConnection: {
kind: "flat",
fields: ["type", "url", "httpUrl"],
stdio: [
{ kind: "truthy", field: "httpUrl" },
{ kind: "truthy", field: "url" },
],
},
displayName: "Gemini CLI",
geminiSettings,
configPath: ({ home, env }: ClientPathContext) =>
join(env.GEMINI_CLI_HOME || home, ".gemini", "settings.json"),
markerPath: ({ home, env }: ClientPathContext) =>
join(env.GEMINI_CLI_HOME || home, ".gemini"),
// Antigravity keeps its configuration under the same .gemini directory,
// so the directory alone does not show Gemini CLI. Its own settings,
// trusted-folder records and session state do.
discoveryPaths: (context: ClientPathContext) => {
const root = join(context.env.GEMINI_CLI_HOME || context.home, ".gemini");
return [
join(root, "settings.json"),
geminiSettings(context).trustedFoldersPath,
join(root, "tmp"),
];
},
skillPath: ({ home, env }: ClientPathContext) =>
join(env.GEMINI_CLI_HOME || home, ".agents", "skills"),
format: "json",
}),
defineClient({
name: "windsurf",
mcpAdd: { aliases: ["codeium", "cascade"] },
registrationConnection: {
kind: "flat",
fields: ["serverUrl", "url"],
stdio: [
{ kind: "present", field: "serverUrl" },
{ kind: "present", field: "url" },
],
},
displayName: "Windsurf",
configPath: [".codeium", "windsurf", "mcp_config.json"],
markerPath: [".codeium", "windsurf"],
format: "json",
}),
defineClient({
name: "devin",
registrationConnection: {
kind: "flat",
fields: ["url", "transport"],
stdio: [
{ kind: "optional-enum", field: "transport", values: ["stdio"] },
{ kind: "present", field: "url" },
],
},
displayName: "Devin",
configPath: ({ home, platform, env }: ClientPathContext) =>
join(devinDirectory({ home, platform, env }), "mcp_config.json"),
markerPath: devinDirectory,
format: "json",
}),
defineClient({
name: "opencode",
mcpAdd: {
projectPaths: [
"opencode.jsonc",
"opencode.json",
".opencode/opencode.jsonc",
".opencode/opencode.json",
],
},
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "required-enum", field: "type", values: ["local"] }],
},
displayName: "OpenCode",
configPath: existingOpenCodeConfigPath,
configPaths: openCodeConfigurationPaths,
markerPath: opencodeDirectory,
format: "opencode",
}),
defineClient({
name: "antigravity",
mcpAdd: {},
registrationConnection: {
kind: "flat",
fields: ["serverUrl", "url"],
stdio: [
{ kind: "present", field: "serverUrl" },
{ kind: "present", field: "url" },
],
},
displayName: "Antigravity",
skillPath: [".gemini", "config", "skills"],
configPath: [".gemini", "config", "mcp_config.json"],
markerPath: [".gemini", "config"],
format: "json",
}),
defineClient({
name: "copilot_cli",
mcpAdd: {
projectPaths: [".mcp.json", ".github/mcp.json"],
projectFormat: "copilot_cli_project",
},
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [
{ kind: "optional-enum", field: "type", values: ["stdio", "local"] },
{ kind: "present", field: "url" },
],
},
displayName: "GitHub Copilot CLI",
configPath: (context: ClientPathContext) =>
join(copilotDirectory(context), "mcp-config.json"),
markerPath: copilotDirectory,
format: "copilot_cli",
}),
defineClient({
name: "commandcode",
registrationConnection: { kind: "commandcode" },
displayName: "Command Code",
configPath: (context: ClientPathContext) =>
join(commandCodeDirectory(context), "mcp.json"),
markerPath: commandCodeDirectory,
format: "commandcode",
}),
defineClient({
name: "qwen_code",
registrationConnection: {
kind: "flat",
fields: ["type", "httpUrl", "url"],
stdio: [
{ kind: "truthy", field: "httpUrl" },
{ kind: "truthy", field: "url" },
{ kind: "equals", field: "type", value: "sdk" },
],
},
displayName: "Qwen Code",
configPath: (context: ClientPathContext) =>
join(qwenCodeDirectory(context), "settings.json"),
markerPath: qwenCodeDirectory,
format: "json",
}),
defineClient({
name: "kimi",
mcpAdd: { aliases: ["kimi"], projectPaths: [".kimi-code/mcp.json"] },
registrationConnection: {
kind: "flat",
fields: ["type", "url", "transport"],
stdio: [
{ kind: "optional-enum", field: "type", values: ["stdio"] },
{ kind: "optional-enum", field: "transport", values: ["stdio"] },
{ kind: "present", field: "url" },
],
},
displayName: "Kimi Code",
configPath: (context: ClientPathContext) =>
join(kimiDirectory(context), "mcp.json"),
markerPath: kimiDirectory,
format: "kimi",
}),
defineClient({
name: "vscode",
mcpAdd: { aliases: ["github-copilot"], projectPaths: [".vscode/mcp.json"] },
registrationConnection: {
kind: "flat",
fields: ["url", "transport"],
stdio: [
{ kind: "required-enum", field: "type", values: ["stdio"] },
{ kind: "optional-enum", field: "transport", values: ["stdio"] },
{ kind: "present", field: "url" },
],
},
displayName: "VS Code",
configPath: (context: ClientPathContext) =>
join(vscodeUserDirectory(context), "mcp.json"),
markerPath: vscodeUserDirectory,
format: "vscode",
}),
defineClient({
name: "trae",
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "present", field: "url" }],
},
displayName: "Trae",
skillPath: [".trae", "skills"],
configPath: (context: ClientPathContext) =>
join(traeUserDirectory(context), "mcp.json"),
markerPath: traeUserDirectory,
format: "json",
}),
defineClient({
name: "workbuddy",
registrationConnection: { kind: "stdio-only", documentedFields: ["env"] },
displayName: "WorkBuddy",
skillPath: [".workbuddy", "skills"],
configPath: [".workbuddy", "mcp.json"],
markerPath: [".workbuddy"],
format: "json",
}),
defineClient({
name: "lm_studio",
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "present", field: "url" }],
},
displayName: "LM Studio",
location: lmStudioLocation,
format: "lm_studio",
}),
defineClient({
name: "grok_build",
mcpAdd: { aliases: ["grok"], projectPaths: [".grok/config.toml"] },
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "non-nullish", field: "url" }],
},
displayName: "Grok Build",
configPath: (context: ClientPathContext) =>
join(grokDirectory(context), "config.toml"),
markerPath: grokDirectory,
format: "grok",
}),
defineClient({
name: "omp",
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "optional-enum", field: "type", values: ["stdio"] }],
},
displayName: "OMP",
configPath: (context: ClientPathContext) => {
const directory = ompAgentDirectory(context);
return directory.ok ? ok(join(directory.value, "mcp.json")) : directory;
},
markerPath: ompAgentDirectory,
format: "omp",
}),
defineClient({
name: "pi",
mcpAdd: { aliases: ["pi-agent"], projectPaths: [".pi/mcp.json"] },
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [
{ kind: "optional-enum", field: "type", values: ["stdio"] },
{
kind: "all",
conditions: [
{ kind: "missing", field: "type" },
{ kind: "string", field: "url" },
],
},
],
},
displayName: "Pi",
configPath: (context: ClientPathContext) =>
(context.platform === "win32" ? win32 : { join }).join(
piAgentDirectory(context),
"mcp.json",
),
markerPath: piAgentDirectory,
format: "pi",
}),
defineClient({
name: "hermes",
mcpAdd: { aliases: ["hermes-agent"] },
registrationConnection: {
kind: "flat",
fields: ["url", "transport"],
stdio: [
{ kind: "optional-enum", field: "transport", values: ["stdio"] },
{ kind: "present", field: "url" },
],
},
displayName: "Hermes",
skillPath: (context: ClientPathContext) =>
appendCallerPath(hermesDirectory(context), "skills"),
configPath: (context: ClientPathContext) =>
appendCallerPath(hermesDirectory(context), "config.yaml"),
markerPath: hermesDirectory,
format: "hermes",
}),
defineClient({
name: "qoder",
registrationConnection: {
kind: "flat",
fields: ["type", "url", "qoder_url", "tcp"],
stdio: [
{ kind: "optional-enum", field: "type", values: ["stdio"] },
{ kind: "present", field: "url" },
{ kind: "present", field: "qoder_url" },
{ kind: "present", field: "tcp" },
],
},
displayName: "Qoder",
skillPath: (context: ClientPathContext) =>
join(qoderDirectory(context), "skills"),
configPath: (context: ClientPathContext) =>
join(qoderDirectory(context), "settings.json"),
markerPath: qoderDirectory,
format: "json",
}),
defineClient({
name: "droid",
mcpAdd: {
aliases: ["droid", "factory"],
projectPaths: [".factory/mcp.json"],
},
registrationConnection: {
kind: "flat",
fields: ["type", "url"],
stdio: [
{ kind: "optional-enum", field: "type", values: ["stdio"] },
{ kind: "present", field: "url" },
],
},
displayName: "Factory Droid",
skillPath: (context: ClientPathContext) =>
join(factoryDirectory(context), "skills"),
configPath: (context: ClientPathContext) =>
join(factoryDirectory(context), "mcp.json"),
markerPath: factoryDirectory,
format: "json",
}),
defineClient({
name: "zcode",
registrationConnection: {
kind: "flat",
fields: ["type", "url"],
stdio: [
{ kind: "optional-enum", field: "type", values: ["stdio"] },
{ kind: "present", field: "url" },
],
},
zcodeFallbackPath: ({ home }: ClientPathContext) =>
join(home, ".agents", "mcp.json"),
displayName: "ZCode",
configPath: [".zcode", "cli", "config.json"],
markerPath: [".zcode", "cli"],
skillPath: [".zcode", "skills"],
discoveryPaths: ({ home }: ClientPathContext) => [
join(home, ".zcode", "cli"),
],
format: "zcode",
}),
defineClient({
name: "dsh",
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "required-enum", field: "transport", values: ["stdio"] }],
},
displayName: "DeepSeek Harness",
// The home Cordis patch applies to every profile; the skill directory is
// shared agent storage Harness discovers.
skillPath: ({ home, env }: ClientPathContext) =>
join(dshDirectory(home, env.DSH_AGENTS_HOME, ".agents"), "skills"),
configPath: dshPatchDirectory,
markerPath: dshHomeDirectory,
format: "dsh",
}),
defineClient({
name: "freebuff",
registrationConnection: {
kind: "flat",
fields: ["type", "url"],
stdio: [
{ kind: "optional-enum", field: "type", values: ["stdio"] },
{ kind: "present", field: "url" },
],
},
displayName: "FreeBuff",
// FreeBuff discovers personal skills in the shared user agents directory.
skillPath: ({ home }: ClientPathContext) => join(home, ".agents", "skills"),
// FreeBuff loads MCP servers from the shared user agents directory.
configPath: ({ home }: ClientPathContext) =>
join(home, ".agents", "mcp.json"),
markerPath: freebuffProfileDirectory,
discoveryPaths: (context: ClientPathContext) => [
freebuffProfileDirectory(context),
],
// The same file doubles as ZCode's user-scope fallback, so its presence
// proves neither product is installed; see clientOwnershipEvidencePaths.
sharedRegistration: true,
format: "json",
}),
defineClient({
name: "cline_vscode",
mcpAdd: { aliases: ["cline-vscode"] },
registrationConnection: { kind: "cline" },
displayName: "Cline VS Code extension",
configPath: (context: ClientPathContext) =>
join(clineVscodeSettingsDirectory(context), "cline_mcp_settings.json"),
markerPath: clineVscodeSettingsDirectory,
format: "json",
}),
defineClient({
name: "cline_vscode_insiders",
registrationConnection: { kind: "cline" },
displayName: "Cline in VS Code Insiders",
configPath: (context: ClientPathContext) =>
join(
clineSettingsDirectory("Code - Insiders")(context),
"cline_mcp_settings.json",
),
markerPath: clineSettingsDirectory("Code - Insiders"),
format: "json",
}),
defineClient({
name: "cline_vscodium",
registrationConnection: { kind: "cline" },
displayName: "Cline in VSCodium",
configPath: (context: ClientPathContext) =>
join(
clineSettingsDirectory("VSCodium")(context),
"cline_mcp_settings.json",
),
markerPath: clineSettingsDirectory("VSCodium"),
format: "json",
}),
defineClient({
name: "cline_cursor",
registrationConnection: { kind: "cline" },
displayName: "Cline in Cursor",
configPath: (context: ClientPathContext) =>
join(
clineSettingsDirectory("Cursor")(context),
"cline_mcp_settings.json",
),
markerPath: clineSettingsDirectory("Cursor"),
format: "json",
}),
defineClient({
name: "cline_windsurf",
registrationConnection: { kind: "cline" },
displayName: "Cline in Windsurf",
configPath: (context: ClientPathContext) =>
join(
clineSettingsDirectory("Windsurf")(context),
"cline_mcp_settings.json",
),
markerPath: clineSettingsDirectory("Windsurf"),
format: "json",
}),
defineClient({
name: "kiro",
mcpAdd: { aliases: ["kiro"], projectPaths: [".kiro/settings/mcp.json"] },
registrationConnection: {
kind: "flat",
fields: ["type", "url"],
stdio: [
{ kind: "optional-enum", field: "type", values: ["stdio"] },
{ kind: "present", field: "url" },
],
},
// The IDE, CLI and web clients share the user file.
displayName: "Kiro",
configPath: [".kiro", "settings", "mcp.json"],
markerPath: [".kiro"],
format: "json",
}),
defineClient({
name: "mastracode",
mcpAdd: { aliases: ["mastra"], projectPaths: [".mastracode/mcp.json"] },
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "string", field: "url" }],
},
displayName: "Mastra Code",
configPath: [".mastracode", "mcp.json"],
markerPath: [".mastracode"],
format: "json",
}),
defineClient({
name: "zed",
mcpAdd: { projectPaths: [".zed/settings.json"] },
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "present", field: "url" }],
},
displayName: "Zed",
location: zedLocation,
format: "zed",
}),
defineClient({
name: "amp",
mcpAdd: {},
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "present", field: "url" }],
},
displayName: "Amp",
location: ampLocation,
format: "amp",
}),
defineClient({
name: "mcporter",
mcpAdd: { projectPaths: ["config/mcporter.json"] },
registrationConnection: {
kind: "flat",
fields: [...MCPORTER_URL_FIELDS, "executable"],
stdio: MCPORTER_STDIO_INCOMPATIBILITIES,
},
displayName: "MCPorter",
location: mcporterLocation,
// MCPorter imports setup-managed clients' registrations by default, so a
// registration of its own is opt-in.
registrationApplicability: true,
format: "json",
}),
defineClient({
name: "fx",
mcpAdd: {},
registrationConnection: {
kind: "flat",
fields: ["url", "args"],
stdio: [
{ kind: "optional-enum", field: "type", values: ["local", "stdio"] },
{
kind: "all",
conditions: [
{ kind: "missing", field: "type" },
{ kind: "present", field: "url" },
],
},
],
},
displayName: "fx",
location: fxLocation,
privateProfile: true,
format: "fx",
}),
defineClient({
name: "junie",
mcpAdd: { projectPaths: [".junie/mcp/mcp.json"] },
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "present", field: "url" }],
},
displayName: "Junie",
location: junieLocation,
junieSettings: (context: ClientPathContext, { markerPath }) => ({
userConfigPath: join(markerPath, "config.json"),
...(context.env.JUNIE_MCP_DEFAULT_LOCATIONS === undefined
? {}
: { mcpDefaultLocations: context.env.JUNIE_MCP_DEFAULT_LOCATIONS }),
...(context.env.JUNIE_CONFIG_LOCATION === undefined
? {}
: { configLocation: context.env.JUNIE_CONFIG_LOCATION }),
...(context.env.JUNIE_CONFIG_DEFAULT_LOCATIONS === undefined
? {}
: {
configDefaultLocations: context.env.JUNIE_CONFIG_DEFAULT_LOCATIONS,
}),
}),
format: "json",
}),
defineClient({
name: "goose",
mcpAdd: {},
registrationConnection: {
kind: "flat",
fields: ["uri"],
stdio: [{ kind: "required-enum", field: "type", values: ["stdio"] }],
},
displayName: "Goose",
location: gooseLocation,
configPaths: gooseConfigPaths,
readOnlyLowerLayers: true,
format: "goose",
}),
defineClient({
name: "kilo",
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "required-enum", field: "type", values: ["local"] }],
},
displayName: "Kilo Code",
mcpAdd: {
aliases: ["kilo", "kilocode"],
projectLocation: kiloProjectLocation,
},
location: kiloLocation,
configPaths: kiloCandidatePaths,
discoveryPaths: kiloDiscoveryPaths,
layeredLocation: kiloLayeredLocation,
format: "kilo",
}),
defineClient({
name: "grok_bot",
registrationConnection: {
kind: "unavailable",
reason:
"Grok Bot has no supported configuration writer. Configure its MCP connection manually.",
},
displayName: "Grok Bot",
configPath: grokBotDirectory,
markerPath: grokBotDirectory,
format: "unsupported",
}),
] as const satisfies readonly ClientDefinition[];
export type SupportedClientName =
(typeof SUPPORTED_CLIENT_DEFINITIONS)[number]["name"];
/** One client's row, for selection surfaces such as `rea mcp add` that project it. */
export const supportedClientDefinition = (
name: SupportedClientName,
): Pick<
ClientDefinition,
"name" | "displayName" | "format" | "registrationProfile" | "mcpAdd"
> => {
const definitions: readonly ClientDefinition[] = SUPPORTED_CLIENT_DEFINITIONS;
const definition = definitions.find((candidate) => candidate.name === name);
if (definition === undefined)
throw new Error(`No supported client definition for ${name}`);
return definition;
};
/** Setup and registration consume the same already-bound native profile object. */
export const supportedClientRegistrationProfile = (
name: SupportedClientName,
): ClientRegistrationProfile =>
supportedClientDefinition(name).registrationProfile;
/**
* Paths whose presence means the product itself is applicable, so doctor and
* setup should inspect the client. Layered sources count: OpenCode still loads
* its XDG files when a custom directory override does not exist. Shared
* registration storage never establishes applicability; see
* {@link clientOwnershipEvidencePaths}.
*/
export const clientEvidencePaths = (
client: Pick<
SetupClient,
"configPath" | "configPaths" | "markerPath" | "discoveryPaths"
>,
): readonly string[] => [
...new Set(
(
client.discoveryPaths ?? [
client.configPath,
...(client.configPaths ?? []),
client.markerPath,
]
).filter((path): path is string => path !== undefined && path.length > 0),
),
];
/**
* Paths where a recognizable REA-owned row proves ownership of a registration
* REA wrote, never that the product is installed: shared storage is created by
* other products and by REA's own skill installs. A client whose registration
* is product-local declares no shared storage, so this stays empty for it.
*/
export const clientOwnershipEvidencePaths = (
client: Pick<
SetupClient,
"configPath" | "configPaths" | "sharedRegistration"
>,
): readonly string[] =>
client.sharedRegistration === true
? [client.configPath, ...(client.configPaths ?? [])].filter(
(path): path is string => path !== undefined && path.length > 0,
)
: [];
/**
* Registration storage this client shares with another product: its own shared
* configuration plus any same-scope fallback another client also loads. Only
* this storage may be retained when product applicability is unproven, because
* failing closed on it would block REA removals for files REA does not own.
* Product-local configuration is REA's own boundary and stays fail-closed.
*/
export const clientSharedRegistrationPaths = (
client: Pick<
SetupClient,
"configPath" | "configPaths" | "sharedRegistration" | "zcodeFallbackPath"
>,
): ReadonlySet<string> =>
new Set([
...clientOwnershipEvidencePaths(client),
...(client.zcodeFallbackPath === undefined
? []
: [client.zcodeFallbackPath]),
]);
const resolvePath = (
path: ClientPath,
context: ClientPathContext,
): ClientPathResult => {
const resolved =
typeof path === "function" ? path(context) : join(context.home, ...path);
return typeof resolved === "string" ? ok(resolved) : resolved;
};
const resolveLocation = (
definition: ClientDefinition,
context: ClientPathContext,
): Result<ClientLocation, ClientPathFailure> => {
if (definition.location !== undefined) return definition.location(context);
const config = resolvePath(definition.configPath, context);
if (!config.ok) return config;
const marker = resolvePath(definition.markerPath, context);
return marker.ok
? ok({ configPath: config.value, markerPath: marker.value })
: marker;
};
/**
* Layers in increasing precedence, ending with the writable file unless the
* row already places it. A file loaded more than once takes effect at its last
* load, so only that occurrence is kept.
*/
const layerLoadOrder = (
paths: readonly string[],
configPath: string,
): readonly string[] => {
const ordered = paths.includes(configPath) ? paths : [...paths, configPath];
return ordered.filter((path, index) => ordered.lastIndexOf(path) === index);
};
/** Describe every client location that setup, doctor, or uninstall may inspect. */
export const supportedClients = (
home: string,
platform: NodeJS.Platform,
env: ClientPathContext["env"] = process.env,
systemPaths: ClientSystemPaths = {},
): readonly SetupClient[] => {
const context = { home, platform, env, systemPaths };
const definitions: readonly ClientDefinition[] = SUPPORTED_CLIENT_DEFINITIONS;
return definitions.map((definition) => {
try {
const location = resolveLocation(definition, context);
if (!location.ok)
return {
name: definition.name,
registrationProfile: definition.registrationProfile,
displayName: definition.displayName,
format: definition.format,
configPath: location.error.path,
configPathError: location.error.message,
...(location.error.msixPackage === undefined
? {}
: { msixPackage: location.error.msixPackage }),
};
const { configPath, markerPath, msixPackage } = location.value;
return {
name: definition.name,
registrationProfile: definition.registrationProfile,
displayName: definition.displayName,
configPath,
...(definition.geminiSettings === undefined
? {}
: { geminiSettings: definition.geminiSettings(context) }),
...(definition.junieSettings === undefined
? {}
: {
junieSettings: definition.junieSettings(context, location.value),
}),
...(definition.configPaths === undefined
? {}
: {
configPaths: layerLoadOrder(
definition.configPaths(context),
configPath,
),
}),
...(definition.zcodeFallbackPath === undefined
? {}
: { zcodeFallbackPath: definition.zcodeFallbackPath(context) }),
markerPath,
...(msixPackage === undefined ? {} : { msixPackage }),
...(definition.quitBeforeSetup === true
? { quitBeforeSetup: true }
: {}),
...(definition.discoveryPaths === undefined
? {}
: { discoveryPaths: definition.discoveryPaths(context) }),
...(definition.privateProfile === true
? { privateProfile: { home } }
: {}),
...(definition.readOnlyLowerLayers === true
? { readOnlyLowerLayers: true }
: {}),
...(definition.registrationApplicability === true
? { registrationApplicability: true }
: {}),
...(definition.sharedRegistration === true
? { sharedRegistration: true }
: {}),
format: definition.format,
};
} catch (cause: unknown) {
if (cause instanceof HermesClientPathError)
return {
name: definition.name,
registrationProfile: definition.registrationProfile,
displayName: definition.displayName,
format: definition.format,
configPath: cause.path,
configPathError: cause.message,
};
if (definition.name !== "pi") throw cause;
return {
name: definition.name,
registrationProfile: definition.registrationProfile,
displayName: definition.displayName,
format: definition.format,
configPath: env.PI_CODING_AGENT_DIR ?? "",
configPathError: `Invalid PI_CODING_AGENT_DIR: ${errorMessage(cause)}. Repair the override before configuring Pi.`,
};
}
});
};
/**
* The client table with each layered location resolved: the rows setup,
* doctor, update and uninstall act on.
*/
export const resolveSupportedClients = async (
home: string,
platform: NodeJS.Platform,
env: ClientPathContext["env"] = process.env,
systemPaths: ClientSystemPaths = {},
): Promise<readonly SetupClient[]> => {
const context = { home, platform, env, systemPaths };
const definitions: readonly ClientDefinition[] = SUPPORTED_CLIENT_DEFINITIONS;
const rows = supportedClients(home, platform, env, systemPaths);
return Promise.all(
rows.map(async (row) => {
const resolve = definitions.find(
({ name }) => name === row.name,
)?.layeredLocation;
if (resolve === undefined || row.configPathError !== undefined)
return row;
const location = await resolve(context);
return location.ok
? { ...row, ...location.value }
: {
...row,
configPath: location.error.path,
configPathError: location.error.message,
...(location.error.failure === undefined
? {}
: { configPathFailure: location.error.failure }),
};
}),
);
};
/** Resolved destinations and unresolved selections share one path-resolution owner. */
export const clientSkillDirectories = (
home: string,
clientIds: readonly string[] | undefined,
environment: Readonly<NodeJS.ProcessEnv>,
platform: NodeJS.Platform,
): {
readonly directories: readonly {
readonly client: string;
readonly directory: string;
}[];
readonly unresolved: readonly {
readonly client: string;
readonly path: string;
readonly detail: string;
}[];
} => {
const unresolved: { client: string; path: string; detail: string }[] = [];
const definitions: readonly ClientDefinition[] = SUPPORTED_CLIENT_DEFINITIONS;
const selected =
clientIds === undefined
? [
"shared",
...definitions
.filter(({ skillPath }) => skillPath !== undefined)
.map(({ name }) => name),
]
: clientIds.length === 0
? ["shared"]
: clientIds;
const sharedDirectory = appendCallerPath(home, ".agents/skills", platform);
const destinations = new Map<string, { client: string; directory: string }>();
for (const client of selected) {
const definition = definitions.find(({ name }) => name === client);
if (definition === undefined && client !== "shared") {
unresolved.push({
client,
path: client,
detail: `Unsupported skill client: ${client}`,
});
continue;
}
let directory: string;
try {
const resolved =
definition?.skillPath === undefined
? ok(sharedDirectory)
: resolvePath(definition.skillPath, {
home,
platform,
env: environment,
});
if (!resolved.ok) {
unresolved.push({
client,
path: resolved.error.path,
detail: resolved.error.message,
});
continue;
}
directory = resolved.value;
} catch (cause: unknown) {
if (cause instanceof HermesClientPathError) {
unresolved.push({ client, path: cause.path, detail: cause.message });
continue;
}
throw cause;
}
if (!destinations.has(directory))
destinations.set(directory, {
client: directory === sharedDirectory ? "shared" : client,
directory,
});
}
return {
directories: [...destinations.values()].sort((left, right) =>
compareUnicodeCodePoints(left.directory, right.directory),
),
unresolved,
};
};