From cb33fa8376a996c958ae9009731bdd2ce1fdeef3 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Tue, 17 Nov 2026 00:55:50 -0500 Subject: [PATCH] perf(doctor): slim cold CLI/MCP doctor module graphs and run probes concurrently Record default catalog counts and digests in recordedCatalogDigests.js, reuse the SHA-256-verified mcp-catalog.json in default rea mcp doctor runs, move Windows existing-project Ghidra admission constants to GhidraAdmission, defer BinaryTargetResolver and Kuna installation probes until needed, and join independent Doctor host/provider/identity probes via settleConcurrent. Statically loaded JS drops 7.03 MB -> 2.07 MB (-70.6%) for rea doctor/setup (command_ms 440ms -> 207ms, -53.0%) and 5.71 MB -> 0.85 MB (-85.1%) for rea mcp doctor. --- scripts/record-catalog-digests.mjs | 9 +- src/application/Doctor.lifecycle.test.ts | 69 ++++++++++ src/application/Doctor.ts | 75 +++++++---- src/application/DoctorDiagnostics.ts | 30 ++++- src/application/settleConcurrent.ts | 29 ++++ .../catalog/defaultCatalogIdentity.ts | 14 ++ src/contracts/catalog/mcpDoctorCatalog.ts | 49 +++++++ .../catalog/recordedCatalogDigests.ts | 20 +++ src/doctorRuntime.ts | 100 ++++++++------ src/ghidra/GhidraAdmission.ts | 8 ++ src/ghidra/GhidraDoctor.ts | 4 +- src/ghidra/GhidraProviderCapabilities.ts | 17 +-- src/kuna/KunaDoctor.ts | 19 ++- src/mcpDoctor.ts | 127 ++++++++++++------ tests/boundary/mcp/mcpDoctor.test.ts | 5 +- 15 files changed, 445 insertions(+), 130 deletions(-) create mode 100644 src/application/settleConcurrent.ts create mode 100644 src/contracts/catalog/defaultCatalogIdentity.ts create mode 100644 src/contracts/catalog/mcpDoctorCatalog.ts diff --git a/scripts/record-catalog-digests.mjs b/scripts/record-catalog-digests.mjs index b8498453e0..494d1058f6 100644 --- a/scripts/record-catalog-digests.mjs +++ b/scripts/record-catalog-digests.mjs @@ -9,19 +9,22 @@ const compiledRoot = resolve( dirname(fileURLToPath(import.meta.url)), "../dist", ); -const { createCatalogDigestProfiles } = await import( +const { createCatalogDigestProfiles, DEFAULT_CATALOG_IDENTITY } = await import( pathToFileURL(join(compiledRoot, "contracts/catalog/catalogIdentity.js")).href ); // Retain only hashes, with every shared record frozen. Schemas remain owned by // the compiled contracts and are converted once for both identities. -const profiles = Object.entries(createCatalogDigestProfiles()) +const digestProfiles = createCatalogDigestProfiles(); +const profiles = Object.entries(digestProfiles) .map( ([output, digests]) => `${JSON.stringify(output)}: Object.freeze(${JSON.stringify(digests)})`, ) .join(","); +const defaultCounts = JSON.stringify(DEFAULT_CATALOG_IDENTITY.counts); +const defaultDigests = JSON.stringify(digestProfiles.off); await writeFile( join(compiledRoot, "contracts/catalog/recordedCatalogDigests.js"), - `/** Recorded from compiled catalog profiles by scripts/record-catalog-digests.mjs; do not edit. */\nexport const RECORDED_CATALOG_DIGEST_PROFILES = Object.freeze({${profiles}});\n`, + `/** Recorded from compiled catalog profiles by scripts/record-catalog-digests.mjs; do not edit. */\nexport const RECORDED_CATALOG_DIGEST_PROFILES = Object.freeze({${profiles}});\nexport const RECORDED_DEFAULT_CATALOG_IDENTITY = Object.freeze({ counts: Object.freeze(${defaultCounts}), digests: Object.freeze(${defaultDigests}) });\n`, "utf8", ); diff --git a/src/application/Doctor.lifecycle.test.ts b/src/application/Doctor.lifecycle.test.ts index f80c7bed97..5e0b26c2e7 100644 --- a/src/application/Doctor.lifecycle.test.ts +++ b/src/application/Doctor.lifecycle.test.ts @@ -7,6 +7,7 @@ import { settledCause, } from "../../tests/support/lifecycleHarness.js"; import { AnalysisError } from "../domain/analysisErrorBase.js"; +import { cancelledBy } from "../domain/analysisErrorCore.js"; import { ProviderAdapterError } from "../domain/providerAdapterError.js"; import { createDoctorHostFixture } from "./Doctor.fixture.js"; import { runDoctorOwned, systemDoctorHost } from "./Doctor.js"; @@ -110,3 +111,71 @@ it("preserves an inspection-authored physical failure when final cleanup also ob ).rejects.toBe(physical); expect(physical.cause).toBeUndefined(); }); + +it("joins concurrent sibling probes before closing and prefers physical failure over sibling cancellation", async () => { + const controller = new AbortController(); + const siblingInFlight = phaseGate(); + const refusedCleanup = controlledCleanup({ refused: true }); + const physical = new ProviderAdapterError("jadx", "doctor", { + diagnostics: { reason: "concurrent provider fault" }, + }); + let closeStarted = false; + let siblingSettledBeforeClose = false; + const ownedSystem = systemDoctorHost({ + signal: controller.signal, + platform: "darwin", + environment: {}, + providerInspections: async (owner) => { + await siblingInFlight.hold(); + siblingSettledBeforeClose = !closeStarted; + owner.retain( + { close: () => refusedCleanup.close() }, + "sibling-prerequisite", + ); + throw physical; + }, + }); + const ownedHost = { + ...ownedSystem, + macosVersion: async () => { + controller.abort({ request: "concurrent cancellation" }); + throw cancelledBy("doctor", controller.signal); + }, + close: async () => { + closeStarted = true; + return ownedSystem.close!(); + }, + }; + const running = settledCause(runDoctorOwned(undefined, ownedHost)); + await withVerifierCleanup(async () => { + await siblingInFlight.reached(running, "concurrent provider probe"); + expect(closeStarted).toBe(false); + siblingInFlight.release(); + const failure = await running; + expect(siblingSettledBeforeClose).toBe(true); + if (!(failure instanceof AnalysisError)) + throw new Error("Expected attributed composite failure"); + expect(failure.cleanupResources).toEqual(["sibling-prerequisite"]); + expect(failure.cleanupIncomplete).toBe(true); + expect(failure.diagnostics).toMatchObject({ + primary_error: { + details: { + provider_id: "jadx", + diagnostics: { reason: "concurrent provider fault" }, + }, + }, + }); + refusedCleanup.allow(); + await ownedHost.close(); + expect(failure.cleanupIncomplete).toBe(false); + }, [ + () => { + refusedCleanup.allow(); + siblingInFlight.release(); + }, + async () => { + await running; + }, + () => ownedHost.close(), + ]); +}); diff --git a/src/application/Doctor.ts b/src/application/Doctor.ts index 51d51a103d..4e56bd510f 100644 --- a/src/application/Doctor.ts +++ b/src/application/Doctor.ts @@ -33,7 +33,6 @@ import { appendCallerPath } from "../filesystem/callerPath.js"; import { analysisErrorRemediationAction } from "../domain/analysisErrorPresentation.js"; import { BinaryTargetError } from "../domain/configurationErrors.js"; -import { parseBinaryTarget } from "./BinaryTargetResolver.js"; import { execFileOutput, ExecFileOutputCancelledError, @@ -61,7 +60,8 @@ import { type InstalledSkillIdentity, type SkillPathIssue, } from "./SetupSkill.js"; -import { DEFAULT_CATALOG_IDENTITY } from "../contracts/catalog/catalogIdentity.js"; +import type { CatalogIdentitySnapshot } from "../contracts/catalog/recordedCatalogDigests.js"; +import { loadDefaultCatalogIdentity } from "../contracts/catalog/defaultCatalogIdentity.js"; import { PRODUCT_IDENTITY, SDK_IDENTITY } from "../identity.js"; import { readClientRegistrationStatuses, @@ -86,6 +86,7 @@ import type { OwnedProviderSetting, } from "../ports/DesktopBuildHost.js"; import { errorMessage } from "../kernel/errorMessage.js"; +import { settleConcurrent } from "./settleConcurrent.js"; /** Read-only host capabilities required by diagnostics. */ export interface DoctorHost { @@ -176,7 +177,7 @@ interface DoctorIdentity { readonly expected_skill_version: string; readonly sdk: typeof SDK_IDENTITY; /** Package default advertisement; the active server reports its selected profile. */ - readonly catalog: typeof DEFAULT_CATALOG_IDENTITY; + readonly catalog: CatalogIdentitySnapshot; readonly live_server: { readonly state: "unknown"; readonly remediation: string; @@ -450,23 +451,43 @@ const collectDoctorIdentity = async ( readonly checks: readonly DoctorCheck[]; readonly value: DoctorIdentity; }> => { - const launchers = (await host.installationLaunchers?.()) ?? []; - const registrations = - (await host.clientRegistrations?.( - scope.clients, - Object.fromEntries( - selections.flatMap(({ settings }) => Object.entries(settings)), - ), - )) ?? []; const skillClientIds = scope.skill_clients ?? (scope.clients.length > 0 ? scope.clients : undefined); - const installedSkillIdentity = - await host.installedSkillIdentity?.(skillClientIds); - const skillAligned = skillIdentityAligned(installedSkillIdentity); + const [ + resolvedLaunchers, + resolvedRegistrations, + installedSkillIdentity, + defaultCatalogIdentity, + ] = await settleConcurrent([ + Promise.resolve(host.installationLaunchers?.()), + Promise.resolve( + host.clientRegistrations?.( + scope.clients, + Object.fromEntries( + selections.flatMap(({ settings }) => Object.entries(settings)), + ), + ), + ), + Promise.resolve(host.installedSkillIdentity?.(skillClientIds)), + loadDefaultCatalogIdentity(), + ]); + const launchers = resolvedLaunchers ?? []; + const registrations = resolvedRegistrations ?? []; + const skillAligned = skillIdentityAligned( + installedSkillIdentity, + defaultCatalogIdentity.counts.mcp_tools, + ); return { checks: [ - ...(skillAligned ? [] : [skillIdentityCheck(installedSkillIdentity)]), + ...(skillAligned + ? [] + : [ + skillIdentityCheck( + installedSkillIdentity, + defaultCatalogIdentity.counts.mcp_tools, + ), + ]), ...registrations .filter( (registration): registration is UnhealthyClientRegistrationStatus => @@ -479,8 +500,8 @@ const collectDoctorIdentity = async ( expected_skill_version: PRODUCT_IDENTITY.skillVersion, sdk: SDK_IDENTITY, catalog: { - counts: DEFAULT_CATALOG_IDENTITY.counts, - digests: DEFAULT_CATALOG_IDENTITY.digests, + counts: defaultCatalogIdentity.counts, + digests: defaultCatalogIdentity.digests, }, live_server: { state: "unknown", @@ -498,7 +519,10 @@ const collectDoctorIdentity = async ( skill: { installed_version: installedSkillIdentity?.version ?? null, installed_tool_count: installedSkillIdentity?.toolCount ?? null, - state: skillIdentityState(installedSkillIdentity), + state: skillIdentityState( + installedSkillIdentity, + defaultCatalogIdentity.counts.mcp_tools, + ), ...(installedSkillIdentity?.issues === undefined ? {} : { issues: installedSkillIdentity.issues }), @@ -513,13 +537,15 @@ const collectDoctorIdentity = async ( const skillIdentityAligned = ( identity: InstalledSkillIdentity | undefined, + expectedToolCount: number, ): boolean => identity?.version === PRODUCT_IDENTITY.skillVersion && - identity.toolCount === DEFAULT_CATALOG_IDENTITY.counts.mcp_tools && + identity.toolCount === expectedToolCount && identity.canonical; const skillIdentityState = ( identity: InstalledSkillIdentity | undefined, + expectedToolCount: number, ): DoctorSkillState => { if ( identity?.issues?.some( @@ -538,7 +564,7 @@ const skillIdentityState = ( return "missing"; return identity === undefined ? "missing" - : skillIdentityAligned(identity) + : skillIdentityAligned(identity, expectedToolCount) ? "aligned" : "stale"; }; @@ -562,17 +588,18 @@ const skillIdentityRemediation = ( const skillIdentityCheck = ( identity: InstalledSkillIdentity | undefined, + expectedToolCount: number, ): DoctorCheck => { const issues = identity?.issues; + const state = skillIdentityState(identity, expectedToolCount); return { name: "skill:identity", ok: false, // An unreadable or unresolved copy is unknown, not proven drift. - classification: - skillIdentityState(identity) === "unknown" ? "unknown" : "config_drift", + classification: state === "unknown" ? "unknown" : "config_drift", detail: issues !== undefined && issues.length > 0 - ? `Selected skill identity is ${skillIdentityState(identity)}: ${issues.map(({ path }) => path).join(", ")}.` + ? `Selected skill identity is ${state}: ${issues.map(({ path }) => path).join(", ")}.` : identity === undefined ? "Installed REA skill identity is missing." : "Installed REA skill identity is stale.", @@ -751,6 +778,7 @@ export const systemDoctorHost = ( readMacosVersion(hostExecFileOutput, commandEnvironment), linuxDistribution: () => readLinuxDistribution(architecture), async validTarget(path) { + const { parseBinaryTarget } = await import("./BinaryTargetResolver.js"); return ( await parseBinaryTarget(path, { cwd: process.cwd(), @@ -759,6 +787,7 @@ export const systemDoctorHost = ( ).ok; }, async inspectTarget(path) { + const { parseBinaryTarget } = await import("./BinaryTargetResolver.js"); const result = await parseBinaryTarget(path, { cwd: process.cwd(), hostArchitecture: architecture, diff --git a/src/application/DoctorDiagnostics.ts b/src/application/DoctorDiagnostics.ts index f45056a17a..26683de5b5 100644 --- a/src/application/DoctorDiagnostics.ts +++ b/src/application/DoctorDiagnostics.ts @@ -12,6 +12,7 @@ import type { DoctorCheck, DoctorProviderInspection, } from "../ports/DoctorProviderInspection.js"; +import { settleConcurrent } from "./settleConcurrent.js"; /** Ordered environment diagnostics consumed by the Doctor report assembler. */ export interface DoctorDiagnostics { @@ -27,25 +28,40 @@ export const collectDoctorDiagnostics = async ( clients: readonly string[] = [], ): Promise => { const checks: DoctorCheck[] = [nodeCheck(host)]; - checks.push(await hostCheck(host)); + const [ + resolvedHostCheck, + hopperOutcome, + providerInspections, + ilspyCheck, + targetCheck, + ] = await settleConcurrent([ + hostCheck(host), + (async () => { + const hopperPath = await findHopper(host); + const [hopperVersionCheck, hopperDemoCheck] = await settleConcurrent([ + optionalHopperVersionCheck(host, hopperPath), + optionalHopperDemoCheck(host, hopperPath), + ]); + return { hopperPath, hopperVersionCheck, hopperDemoCheck }; + })(), + Promise.resolve(host.providerInspections?.(clients ?? [])), + optionalIlspyCheck(host), + optionalTargetCheck(target, host), + ]); + checks.push(resolvedHostCheck); - const hopperPath = await findHopper(host); + const { hopperPath, hopperVersionCheck, hopperDemoCheck } = hopperOutcome; checks.push(hopperCheck(host, hopperPath)); const hopperTimeoutCheck = optionalHopperStartupTimeoutCheck(host); if (hopperTimeoutCheck !== undefined) checks.push(hopperTimeoutCheck); checks.push(...runtimeConfigurationChecks(host)); - const hopperVersionCheck = await optionalHopperVersionCheck(host, hopperPath); if (hopperVersionCheck !== undefined) checks.push(hopperVersionCheck); - const providerInspections = await host.providerInspections?.(clients ?? []); if (providerInspections !== undefined) checks.push(...providerInspections.flatMap(providerDoctorChecks)); - const ilspyCheck = await optionalIlspyCheck(host); if (ilspyCheck !== undefined) checks.push(ilspyCheck); - const hopperDemoCheck = await optionalHopperDemoCheck(host, hopperPath); if (hopperDemoCheck !== undefined) checks.push(hopperDemoCheck); - const targetCheck = await optionalTargetCheck(target, host); if (targetCheck !== undefined) checks.push(targetCheck); return { diff --git a/src/application/settleConcurrent.ts b/src/application/settleConcurrent.ts new file mode 100644 index 0000000000..bbd8b4b0ec --- /dev/null +++ b/src/application/settleConcurrent.ts @@ -0,0 +1,29 @@ +import { AnalysisError } from "../domain/analysisErrorBase.js"; +import { AnalysisCancelledError } from "../domain/analysisErrorCore.js"; + +/** + * Join independent read-only inspections before surfacing any failure so peers + * finish handing retained resources to the owning scope first. Prefer physical + * failures and incomplete-cleanup attributions over plain cancellation. + */ +export const settleConcurrent = async (tasks: { + [K in keyof T]: Promise; +}): Promise => { + const settled = await Promise.allSettled(tasks); + const rejected = settled.flatMap((outcome) => + outcome.status === "rejected" ? [outcome.reason] : [], + ); + if (rejected.length > 0) { + const physical = rejected.find( + (cause) => !(cause instanceof AnalysisCancelledError), + ); + if (physical !== undefined) throw physical; + const withCleanup = rejected.find( + (cause) => cause instanceof AnalysisError && cause.cleanupIncomplete, + ); + throw withCleanup ?? rejected[0]; + } + return settled.map((outcome) => + outcome.status === "fulfilled" ? outcome.value : undefined, + ) as unknown as T; +}; diff --git a/src/contracts/catalog/defaultCatalogIdentity.ts b/src/contracts/catalog/defaultCatalogIdentity.ts new file mode 100644 index 0000000000..7eef8976b6 --- /dev/null +++ b/src/contracts/catalog/defaultCatalogIdentity.ts @@ -0,0 +1,14 @@ +import { + RECORDED_DEFAULT_CATALOG_IDENTITY, + type CatalogIdentitySnapshot, +} from "./recordedCatalogDigests.js"; + +/** + * Resolve the package's default catalog counts and digests from the recorded + * build fact when available, falling back to live contract evaluation in + * uncompiled source runs. + */ +export const loadDefaultCatalogIdentity = + async (): Promise => + RECORDED_DEFAULT_CATALOG_IDENTITY ?? + (await import("./catalogIdentity.js")).DEFAULT_CATALOG_IDENTITY; diff --git a/src/contracts/catalog/mcpDoctorCatalog.ts b/src/contracts/catalog/mcpDoctorCatalog.ts new file mode 100644 index 0000000000..2b0f4d2a59 --- /dev/null +++ b/src/contracts/catalog/mcpDoctorCatalog.ts @@ -0,0 +1,49 @@ +import { createCatalogIdentity } from "./catalogIdentity.js"; +import { + DISCOVER_TOOLS, + HOT_TOOL_NAMES, + progressiveCatalogIdentity, +} from "./catalogDiscovery.js"; +import { contractsForToolFamilies } from "../toolFamilies.js"; +import { toolContract } from "../toolContracts.js"; +import { advertisedOutputJsonSchema } from "../toolSchemaMetadata.js"; +import { promptsForToolFamilies } from "../promptToolFamilyScope.js"; +import type { McpOutputSchemaProfile } from "../mcpSchemaPresentation.js"; +import type { CatalogIdentitySnapshot } from "./recordedCatalogDigests.js"; + +export interface McpDoctorCatalogExpectation { + readonly catalog: CatalogIdentitySnapshot; + readonly expectedToolNames: readonly string[]; + readonly expectedPromptNames: readonly string[]; + readonly binarySessionOutputSchema: Record; +} + +/** Build expectations from live contracts when family selection or source runs require it. */ +export const buildLiveMcpDoctorExpectation = ( + selection: ReadonlySet | undefined, + outputSchemaProfile: McpOutputSchemaProfile, + progressive: boolean, +): McpDoctorCatalogExpectation => { + const contracts = contractsForToolFamilies(selection); + const promptContracts = promptsForToolFamilies(selection); + const catalog = createCatalogIdentity({ + contracts, + outputSchemaProfile, + promptContracts, + }); + return { + catalog: progressive ? progressiveCatalogIdentity(catalog) : catalog, + expectedToolNames: progressive + ? [ + ...contracts + .map(({ name }) => name) + .filter((name) => HOT_TOOL_NAMES.has(name)), + DISCOVER_TOOLS.name, + ] + : contracts.map(({ name }) => name), + expectedPromptNames: promptContracts.map(({ name }) => name), + binarySessionOutputSchema: advertisedOutputJsonSchema( + toolContract("binary_session"), + ), + }; +}; diff --git a/src/contracts/catalog/recordedCatalogDigests.ts b/src/contracts/catalog/recordedCatalogDigests.ts index 61c82edc48..7565cf4cd3 100644 --- a/src/contracts/catalog/recordedCatalogDigests.ts +++ b/src/contracts/catalog/recordedCatalogDigests.ts @@ -11,6 +11,17 @@ export type CatalogDigestProfiles = Readonly< Record >; +export type CatalogCounts = { + readonly cli_commands: number; + readonly mcp_tools: number; + readonly mcp_prompts: number; +}; + +export type CatalogIdentitySnapshot = { + readonly counts: CatalogCounts; + readonly digests: CatalogDigests; +}; + /** * Digests of the two built-in output schema profiles over the compact input * presentation, recorded from the compiled contracts by @@ -20,3 +31,12 @@ export type CatalogDigestProfiles = Readonly< export const RECORDED_CATALOG_DIGEST_PROFILES: | CatalogDigestProfiles | undefined = undefined; + +/** + * Default catalog counts and digests recorded from the compiled contracts by + * `scripts/record-catalog-digests.mjs` so read-only CLI diagnostics do not load + * the complete contract registry. Source runs leave this undefined. + */ +export const RECORDED_DEFAULT_CATALOG_IDENTITY: + | CatalogIdentitySnapshot + | undefined = undefined; diff --git a/src/doctorRuntime.ts b/src/doctorRuntime.ts index ea93e38d35..ebf95db4eb 100644 --- a/src/doctorRuntime.ts +++ b/src/doctorRuntime.ts @@ -42,6 +42,7 @@ import { inspectLinuxHopperPythonRuntime, linuxHopperPythonUnavailable, } from "./application/LinuxHopperPython.js"; +import { settleConcurrent } from "./application/settleConcurrent.js"; /** * A selected client's own environment, when its registration records one. @@ -366,44 +367,67 @@ export const createSystemDoctorHost = ( environment, platform, ); - return [ - unresolvedProvider( - "ghidra", - selected, - inspectionEnvironment, - platform, - ) ?? - (await inspectSystemGhidraProvider( - inspectionEnvironment, - resourceScope, - inspectionSignal, - )), - unresolvedProvider("ida", selected, inspectionEnvironment, platform) ?? - (await inspectIdaRegistration( - inspectionEnvironment.REA_IDA_MCP_CONFIG, - resourceScope, - inspectionSignal, - inspectionEnvironment.REA_IDA_MCP_CONFIG === undefined - ? undefined - : readRegistration( - inspectionEnvironment.REA_IDA_MCP_CONFIG, - resourceScope, - inspectionSignal, - ), - )), - unresolvedProvider("jadx", selected, inspectionEnvironment, platform) ?? - (await inspectJadxProvider( - inspectionEnvironment, - resourceScope, - host, - inspectionSignal, - )), - unresolvedProvider("kuna", selected, inspectionEnvironment, platform) ?? - (await inspectKunaProvider(inspectionEnvironment, platform, { - resourceScope, - signal: inspectionSignal, - })), - ] satisfies readonly DoctorProviderInspection[]; + const ghidraUnresolved = unresolvedProvider( + "ghidra", + selected, + inspectionEnvironment, + platform, + ); + const idaUnresolved = unresolvedProvider( + "ida", + selected, + inspectionEnvironment, + platform, + ); + const jadxUnresolved = unresolvedProvider( + "jadx", + selected, + inspectionEnvironment, + platform, + ); + const kunaUnresolved = unresolvedProvider( + "kuna", + selected, + inspectionEnvironment, + platform, + ); + return await settleConcurrent([ + ghidraUnresolved !== undefined + ? Promise.resolve(ghidraUnresolved) + : inspectSystemGhidraProvider( + inspectionEnvironment, + resourceScope, + inspectionSignal, + ), + idaUnresolved !== undefined + ? Promise.resolve(idaUnresolved) + : inspectIdaRegistration( + inspectionEnvironment.REA_IDA_MCP_CONFIG, + resourceScope, + inspectionSignal, + inspectionEnvironment.REA_IDA_MCP_CONFIG === undefined + ? undefined + : readRegistration( + inspectionEnvironment.REA_IDA_MCP_CONFIG, + resourceScope, + inspectionSignal, + ), + ), + jadxUnresolved !== undefined + ? Promise.resolve(jadxUnresolved) + : inspectJadxProvider( + inspectionEnvironment, + resourceScope, + host, + inspectionSignal, + ), + kunaUnresolved !== undefined + ? Promise.resolve(kunaUnresolved) + : inspectKunaProvider(inspectionEnvironment, platform, { + resourceScope, + signal: inspectionSignal, + }), + ]); }, desktopBuildFacts: readDesktopBuildFacts, linuxDemoRuntimeCheck: (resourceScope, inspectionSignal) => diff --git a/src/ghidra/GhidraAdmission.ts b/src/ghidra/GhidraAdmission.ts index 91dcf6d283..e808c83367 100644 --- a/src/ghidra/GhidraAdmission.ts +++ b/src/ghidra/GhidraAdmission.ts @@ -8,6 +8,14 @@ import type { UnavailableGhidraInstallation, } from "./GhidraInstallation.js"; +/** The selected database mode is not part of Windows P0 authority. */ +export const EXISTING_PROJECT_WINDOWS_UNAVAILABLE = + "An existing Ghidra project cannot be opened on the Windows launch path."; + +/** Windows P0 imports targets into ephemeral projects only. */ +export const EXISTING_PROJECT_WINDOWS_REMEDIATION = + "Unset REA_GHIDRA_PROJECT_PATH in the environment that starts REA to import targets into an ephemeral project, or open the existing project on a supported Linux or macOS host; restart REA after changing the environment."; + /** Why Ghidra's local prerequisites refuse an inspected installation. */ export type GhidraAdmissionRefusal = | { diff --git a/src/ghidra/GhidraDoctor.ts b/src/ghidra/GhidraDoctor.ts index 5789a79c3a..4fb6527d55 100644 --- a/src/ghidra/GhidraDoctor.ts +++ b/src/ghidra/GhidraDoctor.ts @@ -5,11 +5,11 @@ import type { DoctorProviderCheck, DoctorProviderInspection, } from "../ports/DoctorProviderInspection.js"; -import { admitGhidraInstallation } from "./GhidraAdmission.js"; import { + admitGhidraInstallation, EXISTING_PROJECT_WINDOWS_REMEDIATION, EXISTING_PROJECT_WINDOWS_UNAVAILABLE, -} from "./GhidraProviderCapabilities.js"; +} from "./GhidraAdmission.js"; import { inspectGhidraInstallation, type GhidraInstallationCheck, diff --git a/src/ghidra/GhidraProviderCapabilities.ts b/src/ghidra/GhidraProviderCapabilities.ts index 175d3757f7..9eb9d3ca0b 100644 --- a/src/ghidra/GhidraProviderCapabilities.ts +++ b/src/ghidra/GhidraProviderCapabilities.ts @@ -8,6 +8,15 @@ import { GHIDRA_FUNCTION_OPERATIONS } from "./GhidraFunctionOperations.js"; import { GHIDRA_INVENTORY_OPERATIONS } from "./GhidraInventoryOperations.js"; import { GHIDRA_MUTATING_OPERATIONS } from "./GhidraSessionValues.js"; import { ghidraLoadImageVerificationNote } from "./GhidraVerifiedLoadImageFormats.js"; +import { + EXISTING_PROJECT_WINDOWS_REMEDIATION, + EXISTING_PROJECT_WINDOWS_UNAVAILABLE, +} from "./GhidraAdmission.js"; + +export { + EXISTING_PROJECT_WINDOWS_REMEDIATION, + EXISTING_PROJECT_WINDOWS_UNAVAILABLE, +}; /** Target architectures admitted by the Windows P0 native PE boundary. */ export const WINDOWS_P0_NATIVE_PE_ARCHITECTURES: readonly string[] = @@ -296,14 +305,6 @@ export const checkpointCapabilities = (): readonly CapabilityDescriptor[] => limitations: limitationsFor(capability.operation, "owned-checkpoint"), })); -/** The selected database mode is not part of Windows P0 authority. */ -export const EXISTING_PROJECT_WINDOWS_UNAVAILABLE = - "An existing Ghidra project cannot be opened on the Windows launch path."; - -/** Windows P0 imports targets into ephemeral projects only. */ -export const EXISTING_PROJECT_WINDOWS_REMEDIATION = - "Unset REA_GHIDRA_PROJECT_PATH in the environment that starts REA to import targets into an ephemeral project, or open the existing project on a supported Linux or macOS host; restart REA after changing the environment."; - /** Read-only project mode retains precise unavailable mutation capabilities. */ export const existingProjectCapabilities = ( platform: NodeJS.Platform, diff --git a/src/kuna/KunaDoctor.ts b/src/kuna/KunaDoctor.ts index c1db97266c..e62f2ebef2 100644 --- a/src/kuna/KunaDoctor.ts +++ b/src/kuna/KunaDoctor.ts @@ -14,11 +14,9 @@ import type { RetainedResourceScope } from "../ports/AnalysisProvider.js"; import type { JsonValue } from "../domain/jsonValue.js"; import { ProviderAdapterError } from "../domain/providerAdapterError.js"; import { classifyProviderFailure } from "../providers/classifyProviderFailure.js"; -import { kunaInstallationDialect } from "./KunaCommand.js"; -import { - createKunaResourceScope, - inspectKunaInstallation, - type KunaReadinessFailure, +import type { + KunaReadinessFailure, + KunaResourceScope, } from "./KunaInstallation.js"; import { KUNA_COMMAND_REMEDIATION, @@ -125,6 +123,8 @@ const versionCheck = async ( readonly version: string | null; readonly check: DoctorProviderCheck; }> => { + const { createKunaResourceScope, inspectKunaInstallation } = + await import("./KunaInstallation.js"); const kunaResources = createKunaResourceScope(options.resourceScope); let installation: Awaited>; try { @@ -134,7 +134,11 @@ const versionCheck = async ( ...(options.signal === undefined ? {} : { signal: options.signal }), }); } catch (cause: unknown) { - return { version: null, check: probeCleanupFailure(cause, kunaResources) }; + const { kunaInstallationDialect } = await import("./KunaCommand.js"); + return { + version: null, + check: probeCleanupFailure(cause, kunaResources, kunaInstallationDialect), + }; } if (!installation.ok) { const check = probeFailure(installation.error); @@ -217,7 +221,8 @@ const cleanupIncompleteCheck = ( */ const probeCleanupFailure = ( cause: unknown, - kunaResources: ReturnType, + kunaResources: KunaResourceScope, + kunaInstallationDialect: (typeof import("./KunaCommand.js"))["kunaInstallationDialect"], ): DoctorProviderCheck => { let recognised = true; const failure = classifyProviderFailure( diff --git a/src/mcpDoctor.ts b/src/mcpDoctor.ts index 30e04d83c8..7e1f174001 100644 --- a/src/mcpDoctor.ts +++ b/src/mcpDoctor.ts @@ -1,11 +1,11 @@ import { Client, SdkError, SdkErrorCode } from "@modelcontextprotocol/client"; import { OwnedMcpClient } from "./process/OwnedMcpClient.js"; import { formatCommandHelp } from "./cli/help.js"; +import { readFileSync } from "node:fs"; import { performance } from "node:perf_hooks"; import { resolve } from "node:path"; import { StringDecoder } from "node:string_decoder"; -import { createCatalogIdentity } from "./contracts/catalog/catalogIdentity.js"; import { jsonLinesErrorRecord } from "./cli/jsonLines.js"; import { CLI_DOCUMENT_OUTPUT_FORMATS, @@ -20,10 +20,15 @@ import { HOT_TOOL_NAMES, progressiveCatalogIdentity, } from "./contracts/catalog/catalogDiscovery.js"; -import { contractsForToolFamilies } from "./contracts/toolFamilies.js"; -import { toolContract } from "./contracts/toolContracts.js"; -import { advertisedOutputJsonSchema } from "./contracts/toolSchemaMetadata.js"; -import { promptsForToolFamilies } from "./contracts/promptToolFamilyScope.js"; +import { + RECORDED_CATALOG_DIGEST_PROFILES, + type CatalogIdentitySnapshot, +} from "./contracts/catalog/recordedCatalogDigests.js"; +import { + RECORDED_MCP_CATALOG_SHA256, + type RecordedMcpCatalog, +} from "./recordedMcpCatalog.js"; +import type { McpDoctorCatalogExpectation } from "./contracts/catalog/mcpDoctorCatalog.js"; import { err, ok } from "./domain/result.js"; import { AnalysisError } from "./domain/analysisErrorBase.js"; import { PRODUCT_IDENTITY } from "./identity.js"; @@ -38,6 +43,7 @@ import { import { MCP_DOCTOR_ALIAS, MCP_DOCTOR_OPTIONS } from "./mcpDoctorOptions.js"; import { OwnedMcpStdioTransport } from "./process/OwnedMcpStdioTransport.js"; import { isRecord } from "./kernel/isRecord.js"; +import { sha256Hex } from "./kernel/sha256Hex.js"; import { resolveMcpOutputSchemaProfile } from "./contracts/mcpSchemaPresentation.js"; import { errorMessage } from "./kernel/errorMessage.js"; @@ -111,7 +117,9 @@ export const runProductionMcpDoctor = async (options: McpDoctorOptions) => { stderr_truncated: false, }, }; - const expectation = doctorExpectationForEnvironment(options.environment); + const expectation = await doctorExpectationForEnvironment( + options.environment, + ); const budget = parsedBudgets.value.doctor; const budgetMs = budget.milliseconds; const deadline = performance.now() + budgetMs; @@ -236,13 +244,6 @@ class DoctorStdioTransport extends OwnedMcpStdioTransport { const MCP_DOCTOR_SESSION_SCOPE_DETAIL = "binary_session is outside the selected tool families; include the session family for request-flow and identity checks"; -/** Doctor expectations derived from the same environment the child inherits. */ -interface DoctorCatalogExpectation { - readonly catalog: ReturnType; - readonly expectedToolNames: readonly string[]; - readonly expectedPromptNames: readonly string[]; -} - const listPromptsWhenAdvertised = ( client: Client, request: ReturnType, @@ -255,7 +256,7 @@ const inspectProductionMcpSession = async ( client: Client, deadline: number, signal: AbortSignal, - expectation: DoctorCatalogExpectation, + expectation: McpDoctorCatalogExpectation, budget: McpPhaseBudget, ) => { const request = requestOptions(deadline, signal); @@ -276,7 +277,7 @@ const inspectProductionMcpSession = async ( name: "binary_session", inputSchema: { type: "object" as const }, }), - outputSchema: advertisedOutputJsonSchema(toolContract("binary_session")), + outputSchema: expectation.binarySessionOutputSchema, }; // A scope without the session family cannot serve request flow at all; // every other case still probes the call so the report names the real cause. @@ -600,12 +601,43 @@ const targetFreeEnvironment = ( return result; }; -const doctorExpectationForEnvironment = ( +let cachedVerifiedCatalog: RecordedMcpCatalog | null | undefined; + +const readVerifiedRecordedMcpCatalog = (): RecordedMcpCatalog | undefined => { + if (cachedVerifiedCatalog !== undefined) + return cachedVerifiedCatalog ?? undefined; + if (RECORDED_MCP_CATALOG_SHA256 === undefined) { + cachedVerifiedCatalog = null; + return undefined; + } + try { + const bytes = readFileSync(new URL("./mcp-catalog.json", import.meta.url)); + if (sha256Hex(bytes) !== RECORDED_MCP_CATALOG_SHA256) { + cachedVerifiedCatalog = null; + return undefined; + } + const parsed: unknown = JSON.parse(bytes.toString("utf8")); + if (!isRecord(parsed) || parsed.version !== 1) { + cachedVerifiedCatalog = null; + return undefined; + } + cachedVerifiedCatalog = parsed as unknown as RecordedMcpCatalog; + return cachedVerifiedCatalog; + } catch { + cachedVerifiedCatalog = null; + return undefined; + } +}; + +const doctorExpectationForEnvironment = async ( environment: Readonly>, -): DoctorCatalogExpectation => { +): Promise => { const outputProfile = parseMcpOutputSchemaProfile( environment.REA_MCP_OUTPUT_SCHEMA_PROFILE, ); + const resolvedOutputProfile = resolveMcpOutputSchemaProfile( + outputProfile.ok ? outputProfile.value : undefined, + ); // An invalid selection fails child startup, which the transport check // reports with the server's diagnostics; expect the complete catalog so a // failed start is never mistaken for a scope mismatch. @@ -614,31 +646,50 @@ const doctorExpectationForEnvironment = ( families.ok && families.value !== undefined ? new Set(families.value) : undefined; - const contracts = contractsForToolFamilies(selection); - const promptContracts = promptsForToolFamilies(selection); const catalogProfile = parseMcpToolCatalogProfile( environment.REA_MCP_TOOL_CATALOG_PROFILE, ); const progressive = catalogProfile.ok && catalogProfile.value === "hot-cold"; - const catalog = createCatalogIdentity({ - contracts, - outputSchemaProfile: resolveMcpOutputSchemaProfile( - outputProfile.ok ? outputProfile.value : undefined, - ), - promptContracts, - }); - return { - catalog: progressive ? progressiveCatalogIdentity(catalog) : catalog, - expectedToolNames: progressive - ? [ - ...contracts - .map(({ name }) => name) - .filter((name) => HOT_TOOL_NAMES.has(name)), - DISCOVER_TOOLS.name, - ] - : contracts.map(({ name }) => name), - expectedPromptNames: promptContracts.map(({ name }) => name), - }; + if ( + selection === undefined && + RECORDED_CATALOG_DIGEST_PROFILES !== undefined + ) { + const recorded = readVerifiedRecordedMcpCatalog(); + const sessionTool = recorded?.tools.find( + ({ name }) => name === "binary_session", + ); + if ( + recorded !== undefined && + sessionTool !== undefined && + isRecord(sessionTool.outputSchema) + ) { + const baseCatalog: CatalogIdentitySnapshot = { + counts: recorded.identity.counts, + digests: RECORDED_CATALOG_DIGEST_PROFILES[resolvedOutputProfile], + }; + const toolNames = recorded.tools.map(({ name }) => name); + return { + catalog: progressive + ? progressiveCatalogIdentity(baseCatalog) + : baseCatalog, + expectedToolNames: progressive + ? [ + ...toolNames.filter((name) => HOT_TOOL_NAMES.has(name)), + DISCOVER_TOOLS.name, + ] + : toolNames, + expectedPromptNames: recorded.prompts.map(({ name }) => name), + binarySessionOutputSchema: sessionTool.outputSchema, + }; + } + } + const { buildLiveMcpDoctorExpectation } = + await import("./contracts/catalog/mcpDoctorCatalog.js"); + return buildLiveMcpDoctorExpectation( + selection, + resolvedOutputProfile, + progressive, + ); }; const captureStderr = () => { diff --git a/tests/boundary/mcp/mcpDoctor.test.ts b/tests/boundary/mcp/mcpDoctor.test.ts index 61e7724632..0d1cbf28ea 100644 --- a/tests/boundary/mcp/mcpDoctor.test.ts +++ b/tests/boundary/mcp/mcpDoctor.test.ts @@ -88,10 +88,7 @@ const runCachedMcpDoctor = ( ) => runProductionMcpDoctor({ ...options, - environment: - options.environment === undefined - ? undefined - : withCompileCache(options.environment), + environment: withCompileCache(options.environment), }); const expectDoctorDeadline = (