perf(plugins): reuse installed manifest realpaths (#96710)

vincentkoc · sheyanmin · web-flow · commit 94ae918d8f40 · 2026-06-25T16:41:26.000+08:00
Co-authored-by: sheyanmin &lt;she.yanmin@xydigit.com&gt;
diff --git a/src/plugins/manifest-registry-installed.test.ts b/src/plugins/manifest-registry-installed.test.ts
@@ -6,7 +6,7 @@ import {
   readPersistedInstalledPluginIndex,
   writePersistedInstalledPluginIndex,
 } from "./installed-plugin-index-store.js";
-import type { InstalledPluginIndex } from "./installed-plugin-index.js";
+import type { InstalledPluginIndex, InstalledPluginIndexRecord } from "./installed-plugin-index.js";
 import {
   loadPluginManifestRegistryForInstalledIndex,
   resolveInstalledManifestRegistryIndexFingerprint,
@@ -151,6 +151,24 @@ function createIndexWithPackageJson(rootDir: string): InstalledPluginIndex {
   };
 }
 
+function createIndexWithUnhashedPackageJson(rootDir: string): InstalledPluginIndex {
+  const index = createIndexWithFileSignatures(rootDir);
+  const packageJsonPath = writePackageManifest(rootDir, "Installed");
+  const record = index.plugins[0];
+  if (!record) {
+    throw new Error("expected index record");
+  }
+  record.packageJson = {
+    path: "package.json",
+    hash: "",
+    fileSignature: fileSignature(packageJsonPath),
+  };
+  return {
+    ...index,
+    plugins: [record],
+  };
+}
+
 describe("loadPluginManifestRegistryForInstalledIndex", () => {
   it("reuses frozen installed-index fingerprints when file signatures are persisted", () => {
     const rootDir = makeTempDir();
@@ -180,6 +198,97 @@ describe("loadPluginManifestRegistryForInstalledIndex", () => {
     expect(second).not.toBe(first);
   });
 
+  it("reuses package realpaths across mutable installed-index fingerprint builds", () => {
+    const rootDir = makeTempDir();
+    writePlugin(rootDir, "installed", "installed-");
+    const index = createIndexWithUnhashedPackageJson(rootDir);
+    const packageJsonPath = path.join(fs.realpathSync(rootDir), "package.json");
+    const realpathSpy = vi.spyOn(fs, "realpathSync");
+    let rootPathCalls: unknown[][];
+    let packageJsonPathCalls: unknown[][];
+    try {
+      resolveInstalledManifestRegistryIndexFingerprint(index);
+      resolveInstalledManifestRegistryIndexFingerprint(index);
+      rootPathCalls = realpathSpy.mock.calls.filter(([filePath]) => filePath === rootDir);
+      packageJsonPathCalls = realpathSpy.mock.calls.filter(
+        ([filePath]) => filePath === packageJsonPath,
+      );
+    } finally {
+      realpathSpy.mockRestore();
+    }
+
+    expect(rootPathCalls).toHaveLength(1);
+    expect(packageJsonPathCalls).toHaveLength(1);
+  });
+
+  it("clears package realpath memoization with plugin metadata lifecycle caches", () => {
+    const rootDir = makeTempDir();
+    writePlugin(rootDir, "installed", "installed-");
+    const index = createIndexWithUnhashedPackageJson(rootDir);
+    const packageJsonPath = path.join(fs.realpathSync(rootDir), "package.json");
+    const realpathSpy = vi.spyOn(fs, "realpathSync");
+    let rootPathCalls: unknown[][];
+    let packageJsonPathCalls: unknown[][];
+    try {
+      resolveInstalledManifestRegistryIndexFingerprint(index);
+      clearPluginMetadataLifecycleCaches();
+      resolveInstalledManifestRegistryIndexFingerprint(index);
+      rootPathCalls = realpathSpy.mock.calls.filter(([filePath]) => filePath === rootDir);
+      packageJsonPathCalls = realpathSpy.mock.calls.filter(
+        ([filePath]) => filePath === packageJsonPath,
+      );
+    } finally {
+      realpathSpy.mockRestore();
+    }
+
+    expect(rootPathCalls).toHaveLength(2);
+    expect(packageJsonPathCalls).toHaveLength(2);
+  });
+
+  it("bounds package realpath memoization across many fingerprint roots", () => {
+    const firstRootDir = makeTempDir();
+    writePlugin(firstRootDir, "installed", "installed-");
+    const firstIndex = createIndexWithUnhashedPackageJson(firstRootDir);
+    resolveInstalledManifestRegistryIndexFingerprint(firstIndex);
+
+    const records: InstalledPluginIndexRecord[] = [];
+    for (let index = 0; index < 300; index += 1) {
+      const rootDir = makeTempDir();
+      const pluginId = `installed-${index}`;
+      writePlugin(rootDir, pluginId, `${pluginId}-`);
+      const record = createIndexWithUnhashedPackageJson(rootDir).plugins[0];
+      if (!record) {
+        throw new Error("expected index record");
+      }
+      records.push({
+        ...record,
+        pluginId,
+        manifestHash: `manifest-hash-${index}`,
+      });
+    }
+    resolveInstalledManifestRegistryIndexFingerprint({
+      ...firstIndex,
+      plugins: records,
+    });
+
+    const packageJsonPath = path.join(fs.realpathSync(firstRootDir), "package.json");
+    const realpathSpy = vi.spyOn(fs, "realpathSync");
+    let rootPathCalls: unknown[][];
+    let packageJsonPathCalls: unknown[][];
+    try {
+      resolveInstalledManifestRegistryIndexFingerprint(firstIndex);
+      rootPathCalls = realpathSpy.mock.calls.filter(([filePath]) => filePath === firstRootDir);
+      packageJsonPathCalls = realpathSpy.mock.calls.filter(
+        ([filePath]) => filePath === packageJsonPath,
+      );
+    } finally {
+      realpathSpy.mockRestore();
+    }
+
+    expect(rootPathCalls).toHaveLength(1);
+    expect(packageJsonPathCalls).toHaveLength(1);
+  });
+
   it("does not cache shallow-frozen installed-index fingerprints with mutable nested records", () => {
     const rootDir = makeTempDir();
     writePlugin(rootDir, "installed", "installed-");
diff --git a/src/plugins/manifest-registry-installed.ts b/src/plugins/manifest-registry-installed.ts
@@ -32,8 +32,12 @@ import {
 const installedManifestRegistryIndexFingerprintCache = new WeakMap<InstalledPluginIndex, string>();
 const installedPackageJsonPathCache = new Map<string, string | null>();
 const installedPackageMetadataCache = new Map<string, InstalledPackageMetadata>();
+// Installed plugin metadata is process-stable between explicit lifecycle clears.
+// Share realpaths across fingerprint builds to avoid repeated package boundary IO.
+const installedManifestRegistryRealpathCache = new Map<string, string>();
 const MAX_INSTALLED_PACKAGE_JSON_PATH_CACHE_ENTRIES = 256;
 const MAX_INSTALLED_PACKAGE_METADATA_CACHE_ENTRIES = 256;
+const MAX_INSTALLED_MANIFEST_REGISTRY_REALPATH_CACHE_ENTRIES = 512;
 
 type InstalledPackageMetadata = {
   packageManifest?: OpenClawPackageManifest;
@@ -44,6 +48,7 @@ type InstalledPackageMetadata = {
 export function clearInstalledManifestRegistryProcessCaches(): void {
   installedPackageJsonPathCache.clear();
   installedPackageMetadataCache.clear();
+  installedManifestRegistryRealpathCache.clear();
 }
 
 registerPluginMetadataProcessMemoLifecycleClear(clearInstalledManifestRegistryProcessCaches);
@@ -169,6 +174,19 @@ function rememberInstalledPackageJsonPath(
   return packageJsonPath;
 }
 
+function trimInstalledManifestRegistryRealpathCache(): void {
+  while (
+    installedManifestRegistryRealpathCache.size >
+    MAX_INSTALLED_MANIFEST_REGISTRY_REALPATH_CACHE_ENTRIES
+  ) {
+    const oldest = installedManifestRegistryRealpathCache.keys().next().value;
+    if (oldest === undefined) {
+      break;
+    }
+    installedManifestRegistryRealpathCache.delete(oldest);
+  }
+}
+
 function buildInstalledPackageJsonPathCacheKey(
   record: InstalledPluginIndexRecord,
 ): string | undefined {
@@ -196,7 +214,6 @@ function buildInstalledPackageMetadataCacheKey(params: {
 }
 
 function buildInstalledManifestRegistryIndexKey(index: InstalledPluginIndex) {
-  const realpathCache = new Map<string, string>();
   return {
     version: index.version,
     hostContractVersion: index.hostContractVersion,
@@ -206,7 +223,11 @@ function buildInstalledManifestRegistryIndexKey(index: InstalledPluginIndex) {
     installRecords: index.installRecords,
     diagnostics: index.diagnostics,
     plugins: index.plugins.map((record) => {
-      const packageJsonPath = resolvePackageJsonPath(record, realpathCache);
+      const packageJsonPath = resolvePackageJsonPath(
+        record,
+        installedManifestRegistryRealpathCache,
+      );
+      trimInstalledManifestRegistryRealpathCache();
       const packageJsonFile = record.packageJson?.fileSignature
         ? packageJsonPath
           ? formatFileSignature(packageJsonPath, record.packageJson.fileSignature)
