mirror of
https://github.com/morluto/rea.git
synced 2026-11-16 19:53:50 +00:00
524 lines
19 KiB
TypeScript
524 lines
19 KiB
TypeScript
import { z } from "zod";
|
|
import {
|
|
clientRegistrationSource,
|
|
gooseEnvironmentField,
|
|
} from "./ClientRegistrationSource.js";
|
|
import { PRODUCT_IDENTITY } from "../identity.js";
|
|
import { jsonRecordSchema } from "../domain/jsonRecord.js";
|
|
|
|
import { ConfigurationError } from "../domain/configurationErrors.js";
|
|
import { err, ok, type Result } from "../domain/result.js";
|
|
import {
|
|
MCP_STARTUP_POLICY,
|
|
recommendedMcpToolTimeoutMs,
|
|
recommendedMcpToolTimeoutSeconds,
|
|
type McpToolTimeoutInputs,
|
|
} from "../config/mcpStartupPolicy.js";
|
|
import {
|
|
clientConfigurationRecordSchema,
|
|
clientRegistrationEntry,
|
|
clientRegistrationLauncherEntry,
|
|
type ClientRegistrationDialect,
|
|
} from "./ClientConfigurationDocument.js";
|
|
import type { SetupClient } from "./SupportedClients.js";
|
|
import {
|
|
stdioSelectingFields,
|
|
type ClientRegistrationTarget,
|
|
} from "./ClientRegistrationProfile.js";
|
|
import {
|
|
classifyClientRegistrationCommand,
|
|
equivalentClientRegistrationCommands,
|
|
type ClientRegistrationCommandIdentity,
|
|
} from "./ClientRegistrationIdentity.js";
|
|
import { CURRENT_ENTRYPOINT_PATH } from "../process/CurrentEntrypointPath.js";
|
|
|
|
const tomlTimeoutSchema = z.union([
|
|
z.number().positive(),
|
|
z.bigint().positive(),
|
|
]);
|
|
|
|
const launcherSchema = z
|
|
.object({
|
|
command: z.string().min(1),
|
|
args: z.array(z.string()).default([]),
|
|
})
|
|
.passthrough();
|
|
const arrayLauncherSchema = z
|
|
.object({
|
|
command: z.array(z.string()).min(1),
|
|
})
|
|
.passthrough();
|
|
const opencodeLauncherSchema = arrayLauncherSchema.extend({
|
|
type: z.literal("local"),
|
|
});
|
|
const normalizeOpencodeLauncher = (
|
|
entry: z.output<typeof arrayLauncherSchema>,
|
|
): z.output<typeof launcherSchema> => {
|
|
const [command = "", ...args] = entry.command;
|
|
return { ...entry, command, args };
|
|
};
|
|
|
|
const registrationSchema = launcherSchema.extend({
|
|
startup_timeout_sec: tomlTimeoutSchema.optional(),
|
|
tool_timeout_sec: tomlTimeoutSchema.optional(),
|
|
startupTimeoutMs: z.number().positive().optional(),
|
|
toolTimeoutMs: z.number().positive().optional(),
|
|
// Native transport tags belong to the selected profile's admission owner.
|
|
// Other clients may retain arbitrary metadata under these same names.
|
|
type: z.unknown().optional(),
|
|
transport: z.unknown().optional(),
|
|
serverName: z.string().optional(),
|
|
disabled: z.boolean().optional(),
|
|
enabled: z.boolean().optional(),
|
|
});
|
|
|
|
export type ClientRegistration = z.output<typeof registrationSchema>;
|
|
|
|
// https://developers.openai.com/codex/config-reference/#mcp_servers
|
|
const codexApprovalModeSchema = z.enum(["auto", "prompt", "writes", "approve"]);
|
|
const codexToolPolicySchema = z
|
|
.object({
|
|
approval_mode: codexApprovalModeSchema.optional(),
|
|
output_token_limit: z
|
|
.union([z.number().int().positive(), z.bigint().positive()])
|
|
.optional(),
|
|
})
|
|
.passthrough();
|
|
const codexPolicySchema = z
|
|
.object({
|
|
default_tools_approval_mode: codexApprovalModeSchema.optional(),
|
|
enabled_tools: z.array(z.string()).optional(),
|
|
disabled_tools: z.array(z.string()).optional(),
|
|
tools: clientConfigurationRecordSchema
|
|
.superRefine((tools, context) => {
|
|
for (const [name, value] of Object.entries(tools)) {
|
|
const policy = codexToolPolicySchema.safeParse(value);
|
|
if (!policy.success)
|
|
for (const issue of policy.error.issues)
|
|
context.addIssue({ ...issue, path: [name, ...issue.path] });
|
|
}
|
|
})
|
|
.optional(),
|
|
})
|
|
.passthrough();
|
|
|
|
const registrationError = (error: z.ZodError): ConfigurationError =>
|
|
new ConfigurationError("Invalid client registration settings", {
|
|
settings: error.issues.map((issue) => ({
|
|
setting: issue.path.join("."),
|
|
constraint: issue.message,
|
|
})),
|
|
});
|
|
|
|
/** Launcher identity remains usable when unrelated readiness settings are invalid. */
|
|
export const parseClientRegistrationLauncher = (
|
|
value: unknown,
|
|
target: ClientRegistrationTarget,
|
|
): Result<{ command: string; args: string[] }, ConfigurationError> => {
|
|
const { dialect, profile } = target;
|
|
if (profile.connection.kind === "unavailable")
|
|
return err(new ConfigurationError(profile.connection.reason));
|
|
value = clientRegistrationSource(value, profile).connection ?? value;
|
|
const parsed =
|
|
dialect === "opencode" ||
|
|
dialect === "opencode_v2" ||
|
|
dialect === "fx" ||
|
|
dialect === "kilo"
|
|
? arrayLauncherSchema
|
|
.transform(normalizeOpencodeLauncher)
|
|
.safeParse(value)
|
|
: dialect === "goose"
|
|
? z
|
|
.object({
|
|
cmd: z.string().min(1),
|
|
args: z.array(z.string()).default([]),
|
|
})
|
|
.passthrough()
|
|
.transform((entry) => ({ command: entry.cmd, args: entry.args }))
|
|
.safeParse(value)
|
|
: launcherSchema.safeParse(value);
|
|
return parsed.success
|
|
? ok({ command: parsed.data.command, args: parsed.data.args })
|
|
: err(registrationError(parsed.error));
|
|
};
|
|
|
|
/** Launcher ownership is independent of readiness and caller-owned policy. */
|
|
export const clientRegistrationOwnership = (
|
|
value: unknown,
|
|
client: SetupClient,
|
|
/** The REA entry point that owns registrations; update names the new one. */
|
|
currentCommandPath: string | undefined = CURRENT_ENTRYPOINT_PATH,
|
|
): ClientRegistrationCommandIdentity => {
|
|
const parsed = parseClientRegistrationLauncher(value, {
|
|
dialect: client.format ?? "json",
|
|
profile: client.registrationProfile,
|
|
});
|
|
return parsed.ok
|
|
? classifyClientRegistrationCommand(
|
|
[parsed.value.command, ...parsed.value.args],
|
|
currentCommandPath,
|
|
)
|
|
: "unknown";
|
|
};
|
|
|
|
/** Explain the same ownership admission decision in setup and doctor. */
|
|
export const clientRegistrationOwnershipRemediation = (
|
|
ownership: Exclude<ClientRegistrationCommandIdentity, "owned">,
|
|
paths: readonly string[],
|
|
): string =>
|
|
`The existing "${PRODUCT_IDENTITY.mcpServerKey}" registration read from ${paths.join(", ")} has ${ownership} ownership and was not changed. Review its launcher and manually rename or remove that registration before rerunning setup. A different installation path does not prove REA ownership.`;
|
|
|
|
/** Policy belongs to the client dialect, and is validated before refresh writes. */
|
|
const validateClientPolicy = (
|
|
value: unknown,
|
|
client: SetupClient,
|
|
): Result<void, ConfigurationError> => {
|
|
const policy =
|
|
client.name === "codex"
|
|
? codexPolicySchema.safeParse(value)
|
|
: client.format === "copilot_cli"
|
|
? z.object({ tools: z.array(z.string()).optional() }).safeParse(value)
|
|
: undefined;
|
|
return policy === undefined || policy.success
|
|
? ok(undefined)
|
|
: err(registrationError(policy.error));
|
|
};
|
|
|
|
/** Parse launcher syntax and client policy; native transport selection is admitted separately. */
|
|
export const parseClientRegistrationPolicy = (
|
|
value: unknown,
|
|
client: SetupClient,
|
|
): Result<ClientRegistration, ConfigurationError> => {
|
|
const policy = validateClientPolicy(value, client);
|
|
if (!policy.ok) return policy;
|
|
if (client.format === "dsh") {
|
|
const parsed = registrationSchema
|
|
.pick({ command: true, args: true, serverName: true, transport: true })
|
|
.strip()
|
|
.safeParse(value);
|
|
return parsed.success
|
|
? ok(parsed.data)
|
|
: err(registrationError(parsed.error));
|
|
}
|
|
// Kilo keeps OpenCode's launcher and environment shape.
|
|
if (client.format === "opencode" || client.format === "kilo") {
|
|
const entry = opencodeLauncherSchema
|
|
.extend({
|
|
environment: jsonRecordSchema(z.string()).optional(),
|
|
})
|
|
.transform(normalizeOpencodeLauncher)
|
|
.safeParse(value);
|
|
if (!entry.success) return err(registrationError(entry.error));
|
|
value = entry.data;
|
|
} else if (client.format === "fx" || client.format === "goose") {
|
|
// fx's command array and Goose's `cmd` are dialect launcher shapes;
|
|
// normalize them once through the launcher owner.
|
|
const launcher = parseClientRegistrationLauncher(value, {
|
|
dialect: client.format,
|
|
profile: client.registrationProfile,
|
|
});
|
|
if (!launcher.ok) return launcher;
|
|
const entry = clientConfigurationRecordSchema.safeParse(value);
|
|
value = {
|
|
...(entry.success ? entry.data : {}),
|
|
command: launcher.value.command,
|
|
args: launcher.value.args,
|
|
};
|
|
}
|
|
const source = clientRegistrationSource(value, client.registrationProfile);
|
|
if (source.nested)
|
|
value = {
|
|
...source.source,
|
|
command: source.connection?.command,
|
|
args: source.connection?.args,
|
|
};
|
|
const parsed = registrationSchema.safeParse(value);
|
|
if (!parsed.success) return err(registrationError(parsed.error));
|
|
const registration = parsed.data;
|
|
return ok(registration);
|
|
};
|
|
|
|
// These fields select REA's connection and activation. Everything else belongs
|
|
// to the caller/client, including future policy keys. Client-specific timeout
|
|
// defaults and preservation rules are applied below.
|
|
const managedPolicyKeys = new Set([
|
|
"env",
|
|
"envs",
|
|
"environment",
|
|
"enabled",
|
|
"disabled",
|
|
"enable",
|
|
"serverName",
|
|
]);
|
|
|
|
/** Own only fields selected by this native client's admitted profile. */
|
|
export const clientRegistrationSourceFacts = (
|
|
target: ClientRegistrationTarget,
|
|
command: readonly string[],
|
|
previous: unknown,
|
|
): Result<
|
|
{
|
|
readonly source: Record<string, unknown> | undefined;
|
|
readonly connection: Record<string, unknown> | undefined;
|
|
readonly nested: boolean;
|
|
readonly connectionFields: ReadonlySet<string>;
|
|
},
|
|
ConfigurationError
|
|
> => {
|
|
const { profile } = target;
|
|
const connection = profile.connection;
|
|
if (connection.kind === "unavailable")
|
|
return err(new ConfigurationError(connection.reason));
|
|
const parsed = clientRegistrationSource(previous, profile);
|
|
const { source } = parsed;
|
|
const fields = new Set(
|
|
Object.keys(clientRegistrationLauncherEntry(target.dialect, command)),
|
|
);
|
|
if (connection.kind === "stdio-only") {
|
|
const admitted = new Set([...fields, ...connection.documentedFields]);
|
|
const unknown = Object.keys(source ?? {}).filter(
|
|
(key) => !admitted.has(key),
|
|
);
|
|
if (
|
|
(previous !== undefined && source === undefined) ||
|
|
unknown.length > 0 ||
|
|
(source !== undefined &&
|
|
Object.hasOwn(source, "type") &&
|
|
source.type !== "stdio")
|
|
)
|
|
return err(
|
|
new ConfigurationError(
|
|
`Write applicability for ${profile.nativeClient} is unknown outside its documented stdio profile. Review the selected row in the client's native settings; no configuration was changed.`,
|
|
{
|
|
settings: [
|
|
{
|
|
setting: unknown[0] ?? "type",
|
|
constraint:
|
|
"Native interpretation is not established by the documented stdio profile",
|
|
},
|
|
],
|
|
},
|
|
),
|
|
);
|
|
} else {
|
|
const launcherFields = new Set(fields);
|
|
for (const field of connection.kind === "cline"
|
|
? ["transport", "type", "transportType", "url"]
|
|
: connection.kind === "commandcode"
|
|
? ["type", "url"]
|
|
: connection.fields)
|
|
fields.add(field);
|
|
// An existing selector that already chooses stdio stays, including one
|
|
// inherited through a YAML merge; only remote selectors are superseded.
|
|
if (connection.kind === "flat")
|
|
for (const field of stdioSelectingFields(source ?? {}, connection))
|
|
if (!launcherFields.has(field)) fields.delete(field);
|
|
}
|
|
return ok({ ...parsed, connectionFields: fields });
|
|
};
|
|
|
|
const inheritsGooseEnvironmentAlias = (inherited: unknown): boolean =>
|
|
typeof inherited === "object" &&
|
|
inherited !== null &&
|
|
Object.hasOwn(inherited, "env");
|
|
|
|
/** Explicit launcher replacement preserves policy and native environment, while
|
|
* superseding connection selectors that could keep the old remote transport.
|
|
* Goose's single env alias becomes envs unless a lower layer declares the
|
|
* alias; declaring both remains ambiguous. */
|
|
export const replaceClientRegistrationLauncher = (
|
|
target: ClientRegistrationTarget,
|
|
command: readonly string[],
|
|
previous: unknown,
|
|
inherited?: unknown,
|
|
): Result<Record<string, unknown>, ConfigurationError> => {
|
|
const { dialect } = target;
|
|
const facts = clientRegistrationSourceFacts(target, command, previous);
|
|
if (!facts.ok) return facts;
|
|
const { source, connectionFields: launcherConnectionKeys } = facts.value;
|
|
const retained: Record<string, unknown> =
|
|
source === undefined
|
|
? {}
|
|
: Object.fromEntries(
|
|
Object.entries(source).filter(
|
|
([key]) => !launcherConnectionKeys.has(key),
|
|
),
|
|
);
|
|
const gooseField =
|
|
dialect === "goose" ? gooseEnvironmentField(retained) : ok("envs");
|
|
if (!gooseField.ok) return gooseField;
|
|
if (gooseField.value === "env") {
|
|
const alias = jsonRecordSchema(z.string()).safeParse(retained.env);
|
|
if (!alias.success)
|
|
return err(
|
|
new ConfigurationError("Invalid Goose env alias", {
|
|
cause: alias.error,
|
|
settings: [
|
|
{
|
|
setting: "env",
|
|
constraint: "Expected a mapping of string environment values",
|
|
},
|
|
],
|
|
}),
|
|
);
|
|
// Goose overlays each field separately, so an alias a lower layer also
|
|
// declares keeps its spelling; `envs` beside it would be ambiguous.
|
|
if (inheritsGooseEnvironmentAlias(inherited)) retained.env = alias.data;
|
|
else {
|
|
retained.envs = alias.data;
|
|
delete retained.env;
|
|
}
|
|
}
|
|
const defaults = clientRegistrationEntry(dialect, command, {});
|
|
// Layered native clients inherit policy without copying it into the edited
|
|
// fragment. Defaults must not override an explicitly configured lower layer.
|
|
const inheritedPolicy = clientConfigurationRecordSchema.safeParse(inherited);
|
|
if (inheritedPolicy.success)
|
|
for (const key of Object.keys(defaults))
|
|
if (
|
|
!launcherConnectionKeys.has(key) &&
|
|
(Object.hasOwn(inheritedPolicy.data, key) ||
|
|
// Goose reads its `env` alias as `envs`.
|
|
(dialect === "goose" &&
|
|
key === "envs" &&
|
|
inheritsGooseEnvironmentAlias(inherited)) ||
|
|
(dialect === "opencode" &&
|
|
key === "enabled" &&
|
|
Object.hasOwn(inheritedPolicy.data, "disabled")))
|
|
)
|
|
delete defaults[key];
|
|
// V1 already accepts a disabled policy. Adding enabled:true would override
|
|
// that existing activation dialect when OpenCode migrates the row.
|
|
if (
|
|
dialect === "opencode" &&
|
|
source !== undefined &&
|
|
Object.hasOwn(source, "disabled")
|
|
)
|
|
delete defaults.enabled;
|
|
const launcher = clientRegistrationLauncherEntry(dialect, command);
|
|
if (facts.value.nested)
|
|
for (const key of Object.keys(launcher)) delete defaults[key];
|
|
return ok(
|
|
writeRegistrationConnection(
|
|
facts.value,
|
|
{ ...defaults, ...retained },
|
|
launcher,
|
|
),
|
|
);
|
|
};
|
|
|
|
const writeRegistrationConnection = (
|
|
facts: ReturnType<typeof clientRegistrationSource>,
|
|
retained: Record<string, unknown>,
|
|
fields: Record<string, unknown>,
|
|
): Record<string, unknown> =>
|
|
facts.nested
|
|
? {
|
|
...retained,
|
|
transport: {
|
|
...Object.fromEntries(
|
|
Object.entries(facts.connection ?? {}).filter(
|
|
([key]) =>
|
|
key !== "type" && key !== "url" && !Object.hasOwn(fields, key),
|
|
),
|
|
),
|
|
type: "stdio",
|
|
...fields,
|
|
},
|
|
}
|
|
: { ...retained, ...fields };
|
|
|
|
/** Whether a rea setup repair for this target preserves the row's
|
|
* `enable: false` instead of dropping it. Shared registration doubles as
|
|
* ZCode's fallback, so the activation fact belongs to every reader; a repair
|
|
* preserves it instead of silently re-enabling a row it does not own. A
|
|
* client's own native storage has a single reader, so an explicitly selected
|
|
* setup may still repair it. Doctor's remediation reads this same rule so a
|
|
* preserved disable never points at an ineffective setup run. */
|
|
export const setupPreservesDisabledActivation = (
|
|
client: Pick<SetupClient, "sharedRegistration">,
|
|
format: string | undefined,
|
|
): boolean => client.sharedRegistration === true || format === "zcode_fallback";
|
|
|
|
/** Patch a source fragment, retaining client-owned settings rather than rebuilding it. */
|
|
export const refreshClientRegistration = (
|
|
client: SetupClient,
|
|
dialect: ClientRegistrationDialect,
|
|
command: readonly string[],
|
|
environment: Readonly<Record<string, string>>,
|
|
previous: unknown,
|
|
timeoutInputs: McpToolTimeoutInputs,
|
|
): Result<Record<string, unknown>, ConfigurationError> => {
|
|
const target = { dialect, profile: client.registrationProfile };
|
|
const facts = clientRegistrationSourceFacts(target, command, previous);
|
|
if (!facts.ok) return facts;
|
|
const existing = facts.value.source ?? {};
|
|
const policy = validateClientPolicy(existing, client);
|
|
if (!policy.ok) return policy;
|
|
const prior = parseClientRegistrationLauncher(existing, target);
|
|
const priorCommand = prior.ok
|
|
? [prior.value.command, ...prior.value.args]
|
|
: undefined;
|
|
const launcher =
|
|
priorCommand !== undefined &&
|
|
equivalentClientRegistrationCommands(priorCommand, command)
|
|
? priorCommand
|
|
: command;
|
|
const defaults = clientRegistrationEntry(dialect, launcher, environment);
|
|
const fields = facts.value.nested
|
|
? {
|
|
...clientRegistrationLauncherEntry(dialect, launcher),
|
|
...(Object.keys(environment).length === 0
|
|
? {}
|
|
: { env: { ...environment } }),
|
|
}
|
|
: clientRegistrationLauncherEntry(dialect, launcher);
|
|
if (facts.value.nested)
|
|
for (const key of Object.keys(fields)) delete defaults[key];
|
|
const registration = writeRegistrationConnection(
|
|
facts.value,
|
|
{
|
|
...defaults,
|
|
...Object.fromEntries(
|
|
Object.entries(existing).filter(
|
|
([key]) =>
|
|
!facts.value.connectionFields.has(key) &&
|
|
(!managedPolicyKeys.has(key) ||
|
|
(facts.value.nested && key === "env")),
|
|
),
|
|
),
|
|
},
|
|
fields,
|
|
);
|
|
if (
|
|
setupPreservesDisabledActivation(client, dialect) &&
|
|
existing.enable === false
|
|
)
|
|
registration.enable = false;
|
|
if (client.name === "codex" || client.name === "grok_build")
|
|
registration.startup_timeout_sec =
|
|
positiveTimeout(existing.startup_timeout_sec) ??
|
|
MCP_STARTUP_POLICY.codexStartupTimeoutSeconds;
|
|
if (client.name === "codex")
|
|
registration.tool_timeout_sec =
|
|
positiveTimeout(existing.tool_timeout_sec) ??
|
|
recommendedMcpToolTimeoutSeconds(timeoutInputs);
|
|
if (client.name === "kimi") {
|
|
registration.startupTimeoutMs =
|
|
positiveTimeout(existing.startupTimeoutMs) ??
|
|
MCP_STARTUP_POLICY.kimiStartupTimeoutMs;
|
|
registration.toolTimeoutMs =
|
|
positiveTimeout(existing.toolTimeoutMs) ??
|
|
recommendedMcpToolTimeoutMs(timeoutInputs);
|
|
}
|
|
return ok(registration);
|
|
};
|
|
|
|
const positiveTimeout = (value: unknown): number | bigint | undefined => {
|
|
// TOML keeps integers beyond the safe Number range exact as bigint.
|
|
if (typeof value === "bigint") return value > 0n ? value : undefined;
|
|
return typeof value === "number" && Number.isFinite(value) && value > 0
|
|
? value
|
|
: undefined;
|
|
};
|