feat(ghidra): add private headless provider session

This commit is contained in:
N0zoM1z0
2026-07-16 01:27:54 +09:00
committed by N0zoM1z0
parent ed17e76473
commit f0e625d7ee
234 changed files with 8968 additions and 513 deletions
+116 -2
View File
@@ -40,6 +40,27 @@ export interface DoctorCheck {
readonly detail?: string;
readonly remediation?: string;
}
/** One provider-owned check projected without importing its adapter types. */
export interface DoctorProviderCheck {
readonly name: string;
readonly ok: boolean;
readonly code: string | null;
readonly detail: string;
readonly remediation: string | null;
readonly classification: Exclude<DoctorCheck["classification"], "healthy">;
}
/** Read-only provider inspection supplied by an outer composition adapter. */
export interface DoctorProviderInspection {
readonly id: string;
readonly configured: boolean;
readonly available: boolean;
readonly providerVersion: string | null;
/** Exact non-secret variables safe to persist in an approved registration. */
readonly registrationEnvironment: Readonly<Record<string, string>>;
readonly checks: readonly DoctorProviderCheck[];
}
/** Read-only host capabilities required by diagnostics. */
export interface DoctorHost {
readonly platform: NodeJS.Platform;
@@ -53,6 +74,7 @@ export interface DoctorHost {
linuxDemoRuntimeReady(): Promise<boolean>;
brewHopperPath(): Promise<string | undefined>;
manualHopperPaths(): Promise<readonly string[]>;
providerInspections?(): Promise<readonly DoctorProviderInspection[]>;
installationPaths?(): Promise<readonly string[]>;
installedSkillVersion?(): Promise<string | undefined>;
clientRegistrations?(): Promise<readonly ClientRegistrationStatus[]>;
@@ -69,6 +91,7 @@ export const runDoctor = async (
): Promise<{
readonly healthy: boolean;
readonly hopperPath?: string;
readonly providerInspections?: readonly DoctorProviderInspection[];
readonly checks: readonly DoctorCheck[];
readonly identity?: {
readonly cli_package_version: string;
@@ -168,6 +191,7 @@ export const runDoctor = async (
},
),
);
const providerInspections = await inspectDoctorProviders(host, checks);
if (host.platform === "linux" && hopperPath !== undefined)
checks.push(
check(
@@ -203,8 +227,17 @@ export const runDoctor = async (
"Run rea setup, then restart the affected client.",
});
return {
healthy: checks.every(({ ok }) => ok),
healthy: doctorHealthy(checks, {
hopperAvailable:
hopperPath !== undefined &&
checks
.filter(({ name }) => name.startsWith("hopper"))
.every(({ ok }) => ok),
hopperConfigured: host.configuredHopperPath !== undefined,
providerInspections,
}),
...(hopperPath === undefined ? {} : { hopperPath }),
...(providerInspections === undefined ? {} : { providerInspections }),
checks,
identity: {
cli_package_version: PRODUCT_IDENTITY.packageVersion,
@@ -249,8 +282,17 @@ const unsupportedHopperRemediation = (configured: boolean): string =>
? "Unset or update HOPPER_LAUNCHER_PATH, install the Hopper build supported by this REA release, or update REA."
: "Install the Hopper build supported by this REA release, or update REA for a newer Hopper build.";
/** Optional outer-adapter diagnostics composed without reversing dependencies. */
export interface SystemDoctorHostOptions {
readonly providerInspections?: () => Promise<
readonly DoctorProviderInspection[]
>;
}
/** Create diagnostics backed by the current process and host commands. */
export const systemDoctorHost = (): DoctorHost => ({
export const systemDoctorHost = (
options: SystemDoctorHostOptions = {},
): DoctorHost => ({
platform: process.platform,
nodeVersion: process.versions.node,
...(process.env.HOPPER_LAUNCHER_PATH === undefined
@@ -330,6 +372,9 @@ export const systemDoctorHost = (): DoctorHost => ({
}
return paths;
},
...(options.providerInspections === undefined
? {}
: { providerInspections: options.providerInspections }),
async installationPaths() {
try {
const command = process.platform === "win32" ? "where" : "which";
@@ -383,3 +428,72 @@ const check = (
...(detail === undefined ? {} : { detail }),
...(ok ? {} : { remediation: failure.remediation }),
});
const providerDoctorChecks = (
inspection: DoctorProviderInspection,
): readonly DoctorCheck[] =>
inspection.checks.map((candidate) => ({
name:
candidate.name === "configuration"
? inspection.id
: `${inspection.id}-${candidate.name}`,
ok: candidate.ok,
classification: candidate.ok ? "healthy" : candidate.classification,
detail: candidate.detail,
...(candidate.remediation === null
? {}
: { remediation: candidate.remediation }),
}));
const inspectDoctorProviders = async (
host: DoctorHost,
checks: DoctorCheck[],
): Promise<readonly DoctorProviderInspection[] | undefined> => {
const inspections = await host.providerInspections?.();
if (inspections === undefined) return undefined;
for (const inspection of inspections)
checks.push(...providerDoctorChecks(inspection));
return inspections;
};
const doctorHealthy = (
checks: readonly DoctorCheck[],
providers: {
readonly hopperAvailable: boolean;
readonly hopperConfigured: boolean;
readonly providerInspections:
| readonly DoctorProviderInspection[]
| undefined;
},
): boolean => {
if (providers.providerInspections === undefined)
return checks.every(({ ok }) => ok);
const providerChecks = checks.filter(
({ name }) =>
name.startsWith("hopper") ||
providers.providerInspections?.some((inspection) =>
providerCheckName(inspection.id, name),
) === true,
);
const coreHealthy = checks
.filter((candidate) => !providerChecks.includes(candidate))
.every(({ ok }) => ok);
const configuredProvidersHealthy = providerChecks
.filter(({ name }) => {
if (name.startsWith("hopper")) return providers.hopperConfigured;
return providers.providerInspections?.some(
(inspection) =>
inspection.configured && providerCheckName(inspection.id, name),
);
})
.every(({ ok }) => ok);
return (
coreHealthy &&
configuredProvidersHealthy &&
(providers.hopperAvailable ||
providers.providerInspections.some(({ available }) => available))
);
};
const providerCheckName = (providerId: string, name: string): boolean =>
name === providerId || name.startsWith(`${providerId}-`);
+108 -48
View File
@@ -16,7 +16,12 @@ import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
import { PRODUCT_IDENTITY } from "../identity.js";
import { supportsNodeVersion } from "../domain/runtimeVersion.js";
import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
import { runDoctor, systemDoctorHost } from "./Doctor.js";
import {
runDoctor,
systemDoctorHost,
type DoctorHost,
type DoctorProviderInspection,
} from "./Doctor.js";
import {
installLinuxHopper,
readLinuxDistribution,
@@ -38,6 +43,9 @@ import {
} from "./SetupInstallFailure.js";
export type { SetupHopperInstallResult } from "./SetupInstallFailure.js";
/** Exact non-secret provider variables propagated into managed registrations. */
export type SetupProviderEnvironment = Readonly<Record<string, string>>;
export {
canonicalSkillNeedsInstall,
installCanonicalSkill,
@@ -70,15 +78,16 @@ export interface SetupHost {
linuxDistribution(): Promise<LinuxDistribution | undefined>;
hopperPath(): Promise<string | undefined>;
installHopper(replaceExisting: boolean): Promise<SetupHopperInstallResult>;
providerEnvironment?(): Promise<SetupProviderEnvironment>;
detectedClients(): Promise<readonly SetupClient[]>;
configureClient(
client: SetupClient,
hopperPath: string | undefined,
providerEnvironment: SetupProviderEnvironment,
command: readonly string[],
): Promise<ClientConfigurationResult>;
clientNeedsConfigure(
client: SetupClient,
hopperPath: string | undefined,
providerEnvironment: SetupProviderEnvironment,
command: readonly string[],
): Promise<boolean>;
skillNeedsInstall(): Promise<boolean>;
@@ -141,12 +150,13 @@ export const runSetup = async (
doctor: await host.doctor(),
remediation,
});
const unsupported = await hostRemediation(host);
const unsupported = await hostRemediation(host, options.installHopper);
if (unsupported !== undefined) return fail(unsupported);
let hopperPath = await host.hopperPath();
let providerEnvironment = await initialProviderEnvironment(host, hopperPath);
const discovery = await discoverSetupActions(
host,
hopperPath,
providerEnvironment,
options.installHopper,
);
const { installHopper, installSkill } = discovery;
@@ -182,18 +192,22 @@ export const runSetup = async (
remediation: installed.remediation,
};
hopperPath = installed.launcherPath;
providerEnvironment = {
...providerEnvironment,
HOPPER_LAUNCHER_PATH: installed.launcherPath,
};
appliedActions.push("installed_hopper");
detectedClients = await filterClientsNeedingConfigure(
host,
detectedClients,
hopperPath,
providerEnvironment,
registrationCommand(),
);
}
const clientFailure = await configureDetectedClients({
host,
detectedClients,
hopperPath,
providerEnvironment,
command: registrationCommand(),
clients,
appliedActions,
@@ -226,7 +240,7 @@ export const runSetup = async (
const discoverSetupActions = async (
host: SetupHost,
hopperPath: string | undefined,
providerEnvironment: SetupProviderEnvironment,
forceHopperInstall: boolean,
) => {
const initialDoctor = await host.doctor();
@@ -237,7 +251,9 @@ const discoverSetupActions = async (
(name === "hopper-version" && detail === "/opt/hopper/bin/Hopper")),
);
const installHopper =
forceHopperInstall || hopperPath === undefined || linuxHopperRepairNeeded;
forceHopperInstall ||
Object.keys(providerEnvironment).length === 0 ||
linuxHopperRepairNeeded;
const [detectedClients, installSkill] = await Promise.all([
host.detectedClients(),
host.skillNeedsInstall(),
@@ -248,7 +264,7 @@ const discoverSetupActions = async (
: await filterClientsNeedingConfigure(
host,
detectedClients,
hopperPath,
providerEnvironment,
command,
);
const plannedActions = setupPlan(
@@ -256,6 +272,7 @@ const discoverSetupActions = async (
installHopper,
installSkill,
clients,
providerEnvironment,
);
return {
installHopper,
@@ -268,17 +285,25 @@ const discoverSetupActions = async (
const filterClientsNeedingConfigure = async (
host: SetupHost,
detectedClients: readonly SetupClient[],
hopperPath: string | undefined,
providerEnvironment: SetupProviderEnvironment,
command: readonly string[],
): Promise<readonly SetupClient[]> => {
const needs = await Promise.all(
detectedClients.map((client) =>
host.clientNeedsConfigure(client, hopperPath, command),
host.clientNeedsConfigure(client, providerEnvironment, command),
),
);
return detectedClients.filter((_, index) => needs[index]);
};
const initialProviderEnvironment = async (
host: SetupHost,
hopperPath: string | undefined,
): Promise<SetupProviderEnvironment> => ({
...(await host.providerEnvironment?.()),
...(hopperPath === undefined ? {} : { HOPPER_LAUNCHER_PATH: hopperPath }),
});
const finalSetupRemediation = (
platform: NodeJS.Platform,
installedHopper: boolean,
@@ -295,6 +320,7 @@ const finalSetupRemediation = (
const hostRemediation = async (
host: SetupHost,
forceHopperInstall: boolean,
): Promise<string | undefined> => {
if (host.platform !== "darwin" && host.platform !== "linux")
return "REA supports Hopper on macOS and selected 64-bit Linux distributions.";
@@ -306,20 +332,36 @@ const hostRemediation = async (
? "Upgrade to macOS 12 or newer."
: undefined;
}
return (await host.linuxDistribution())?.supported === true
? undefined
: "REA supports Hopper on Ubuntu 24.04+, Fedora 41+, and 64-bit Arch Linux.";
if ((await host.linuxDistribution())?.supported === true) return undefined;
const providerEnvironment = await host.providerEnvironment?.();
if (
!forceHopperInstall &&
providerEnvironment !== undefined &&
Object.keys(providerEnvironment).length > 0
)
return undefined;
return "Automated Hopper setup supports Ubuntu 24.04+, Fedora 41+, and 64-bit Arch Linux; configure an existing supported provider instead.";
};
/** Production setup effects for Hopper, agent configuration, and the canonical skill directory. */
const systemSetupHost = (): SetupHost => {
const doctorHost = systemDoctorHost();
export const systemSetupHost = (
doctorHost: DoctorHost = systemDoctorHost(),
): SetupHost => {
return {
platform: process.platform,
nodeVersion: process.versions.node,
macosVersion: () => doctorHost.macosVersion(),
linuxDistribution: readLinuxDistribution,
hopperPath: async () => (await runDoctor(undefined, doctorHost)).hopperPath,
providerEnvironment: async () => {
const diagnosis = await runDoctor(undefined, doctorHost);
return {
...providerRegistrationEnvironment(diagnosis.providerInspections ?? []),
...(diagnosis.hopperPath === undefined
? {}
: { HOPPER_LAUNCHER_PATH: diagnosis.hopperPath }),
};
},
installHopper: async (replaceExisting) => {
const result =
process.platform === "linux"
@@ -329,14 +371,14 @@ const systemSetupHost = (): SetupHost => {
return setupInstallFailure(result.reason);
},
detectedClients: () => detectClients(homedir()),
configureClient: (client, hopperPath, command) =>
configureClient: (client, providerEnvironment, command) =>
client.format === "unsupported"
? Promise.resolve({ status: "skipped" })
: client.format === "toml"
? configureTomlClient(client, hopperPath, command)
: configureJsonClient(client, hopperPath, command),
clientNeedsConfigure: (client, hopperPath, command) =>
clientConfigurationAligned(client, hopperPath, command).then(
? configureTomlClient(client, providerEnvironment, command)
: configureJsonClient(client, providerEnvironment, command),
clientNeedsConfigure: (client, providerEnvironment, command) =>
clientConfigurationAligned(client, providerEnvironment, command).then(
(aligned) => !aligned,
),
skillNeedsInstall: () => canonicalSkillNeedsInstall(homedir()),
@@ -359,7 +401,7 @@ export const detectClients = async (
/** Back up, atomically update, and semantically read back one JSON MCP configuration. */
export const configureJsonClient = async (
client: SetupClient,
hopperPath?: string,
environment: SetupProviderEnvironment | string = {},
command: readonly string[] = [
"npx",
"-y",
@@ -386,13 +428,10 @@ export const configureJsonClient = async (
} catch {
return { status: "failed", reason: "readback" };
}
const desired = {
command: command[0] ?? PRODUCT_IDENTITY.cliBinary,
args: command.slice(1),
...(hopperPath === undefined
? {}
: { env: { HOPPER_LAUNCHER_PATH: hopperPath } }),
};
const desired = clientConfigurationDesired(
normalizeProviderEnvironment(environment),
command,
);
if (
JSON.stringify(servers[PRODUCT_IDENTITY.mcpServerKey]) ===
JSON.stringify(desired)
@@ -440,7 +479,7 @@ export const configureJsonClient = async (
/** Back up, atomically update, and semantically read back Codex TOML configuration. */
export const configureTomlClient = async (
client: SetupClient,
hopperPath?: string,
environment: SetupProviderEnvironment | string = {},
command: readonly string[] = [
"npx",
"-y",
@@ -467,13 +506,10 @@ export const configureTomlClient = async (
} catch {
return { status: "failed", reason: "readback" };
}
const desired = {
command: command[0] ?? PRODUCT_IDENTITY.cliBinary,
args: command.slice(1),
...(hopperPath === undefined
? {}
: { env: { HOPPER_LAUNCHER_PATH: hopperPath } }),
};
const desired = clientConfigurationDesired(
normalizeProviderEnvironment(environment),
command,
);
if (
JSON.stringify(servers[PRODUCT_IDENTITY.mcpServerKey]) ===
JSON.stringify(desired)
@@ -558,22 +594,27 @@ const restoreConfig = async (
};
const clientConfigurationDesired = (
hopperPath: string | undefined,
providerEnvironment: SetupProviderEnvironment,
command: readonly string[],
) => ({
command: command[0] ?? PRODUCT_IDENTITY.cliBinary,
args: command.slice(1),
...(hopperPath === undefined
? {}
: { env: { HOPPER_LAUNCHER_PATH: hopperPath } }),
});
) => {
const environment = Object.fromEntries(
Object.entries(providerEnvironment).sort(([left], [right]) =>
left.localeCompare(right),
),
);
return {
command: command[0] ?? PRODUCT_IDENTITY.cliBinary,
args: command.slice(1),
...(Object.keys(environment).length === 0 ? {} : { env: environment }),
};
};
const clientConfigurationAligned = async (
client: SetupClient,
hopperPath: string | undefined,
providerEnvironment: SetupProviderEnvironment,
command: readonly string[],
): Promise<boolean> => {
const desired = clientConfigurationDesired(hopperPath, command);
const desired = clientConfigurationDesired(providerEnvironment, command);
try {
const original = await readFile(client.configPath, "utf8");
if (client.format === "toml") {
@@ -594,3 +635,22 @@ const clientConfigurationAligned = async (
return false;
}
};
const normalizeProviderEnvironment = (
environment: SetupProviderEnvironment | string,
): SetupProviderEnvironment =>
typeof environment === "string"
? { HOPPER_LAUNCHER_PATH: environment }
: environment;
const providerRegistrationEnvironment = (
inspections: readonly DoctorProviderInspection[],
): SetupProviderEnvironment =>
Object.fromEntries(
inspections
.filter(({ available }) => available)
.flatMap(({ registrationEnvironment }) =>
Object.entries(registrationEnvironment),
)
.sort(([left], [right]) => left.localeCompare(right)),
);
+3 -2
View File
@@ -2,6 +2,7 @@ import type {
ClientConfigurationResult,
SetupClient,
SetupHost,
SetupProviderEnvironment,
} from "./Setup.js";
const failedConfigurationMessage = (
@@ -20,7 +21,7 @@ const failedConfigurationMessage = (
export const configureDetectedClients = async (options: {
readonly host: SetupHost;
readonly detectedClients: readonly SetupClient[];
readonly hopperPath: string | undefined;
readonly providerEnvironment: SetupProviderEnvironment;
readonly command: readonly string[];
readonly clients: Record<string, ClientConfigurationResult>;
readonly appliedActions: string[];
@@ -29,7 +30,7 @@ export const configureDetectedClients = async (options: {
for (const client of options.detectedClients) {
const result = await options.host.configureClient(
client,
options.hopperPath,
options.providerEnvironment,
options.command,
);
options.clients[client.name] = result;
+19 -2
View File
@@ -1,4 +1,8 @@
import type { SetupAction, SetupClient } from "./Setup.js";
import type {
SetupAction,
SetupClient,
SetupProviderEnvironment,
} from "./Setup.js";
/** Build the complete setup mutation plan before approval. */
export const setupPlan = (
@@ -6,6 +10,7 @@ export const setupPlan = (
installHopper: boolean,
installSkill: boolean,
clients: readonly SetupClient[],
providerEnvironment: SetupProviderEnvironment,
): readonly SetupAction[] => [
...(installHopper
? [
@@ -29,7 +34,7 @@ export const setupPlan = (
(client): SetupAction => ({
kind: "configure_client",
target: client.configPath,
detail: `Add the REA MCP registration for ${client.name}; preserve unrelated configuration.`,
detail: clientConfigurationDetail(client.name, providerEnvironment),
external: false,
}),
),
@@ -44,3 +49,15 @@ export const setupPlan = (
]
: []),
];
const clientConfigurationDetail = (
client: string,
environment: SetupProviderEnvironment,
): string => {
const entries = Object.entries(environment)
.sort(([left], [right]) => left.localeCompare(right))
.map(([name, value]) => `${name}=${value}`);
const suffix =
entries.length === 0 ? "" : ` Environment: ${entries.join(", ")}.`;
return `Add the REA MCP registration for ${client}; preserve unrelated configuration.${suffix}`;
};
+3 -1
View File
@@ -1,6 +1,7 @@
import type { AppConfig } from "../config.js";
import { BinarySession } from "./BinarySession.js";
import { HopperProvider } from "../hopper/HopperProvider.js";
import { GhidraProvider } from "../ghidra/GhidraProvider.js";
import { NativeMacOSProvider } from "../native/NativeMacOSProvider.js";
import { ArtifactProvider } from "../artifacts/ArtifactProvider.js";
import { silentLogger, type Logger } from "../logger.js";
@@ -17,9 +18,10 @@ export const createBinarySession = (
logger: Logger = silentLogger,
): BinarySession => {
const hopper = new HopperProvider(config, logger);
const ghidra = new GhidraProvider(config, logger);
return new BinarySession(
SessionProviderRouter.selectable(
new AnalysisProviderRegistry([hopper], config.analysisProvider),
new AnalysisProviderRegistry([hopper, ghidra], config.analysisProvider),
[
new ArtifactProvider(
config.artifactNativeMountEnabled,