perf(plugins): extend discovery threading to loader, manifest registry, installed-index, and config contracts (#84283)

RomneyDa · web-flow · commit 88d8d6af9336 · 2026-05-19T16:22:30.000-07:00
* perf(plugins): extend discovery threading to loader, manifest registry, installed-index, and config contracts Follow-up to #75451. Threads optional discovery?: PluginDiscoveryResult through the remaining helpers that still call discoverOpenClawPlugins internally during startup: - loadOpenClawPlugins / loadOpenClawPluginCliRegistry (src/plugins/loader.ts): add discovery? to PluginLoadOptions and consult it before falling back to an internal scan at both call sites. - loadPluginManifestRegistry (src/plugins/manifest-registry.ts): accept discovery? as a more ergonomic alternative to the existing candidates? / diagnostics? pair; candidates? still wins when both are supplied. - resolveInstalledPluginIndexRegistry (src/plugins/installed-plugin-index-registry.ts): add discovery? to LoadInstalledPluginIndexParams and use it when candidates aren't supplied. - resolvePluginConfigContractsById (src/plugins/config-contracts.ts): add discovery? and thread it into the bundled-fallback discovery call. Add discovery-threading.test.ts asserting each entry point skips its internal discoverOpenClawPlugins call when discovery is supplied, calls it when nothing is supplied, and prefers explicit candidates over discovery when both are present (6 tests, all pass). discoverOpenClawPlugins remains stateless; sharing is function-scoped per src/plugins/CLAUDE.md guidance. Backward compatible: every change is additive (new optional param). * perf(plugins): drop verbose JSDoc from discovery? params
diff --git a/src/plugins/config-contracts.ts b/src/plugins/config-contracts.ts
@@ -1,6 +1,6 @@
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { isRecord } from "../utils.js";
-import { discoverOpenClawPlugins } from "./discovery.js";
+import { discoverOpenClawPlugins, type PluginDiscoveryResult } from "./discovery.js";
 import { loadPluginManifestRegistry } from "./manifest-registry.js";
 import type { PluginManifestConfigContracts } from "./manifest.js";
 import type { PluginOrigin } from "./plugin-origin.types.js";
@@ -114,6 +114,7 @@ export function resolvePluginConfigContractsById(params: {
   fallbackToBundledMetadataForResolvedBundled?: boolean;
   fallbackBundledPluginIds?: readonly string[];
   pluginIds: readonly string[];
+  discovery?: PluginDiscoveryResult;
 }): ReadonlyMap<string, PluginConfigContractMetadata> {
   const matches = new Map<string, PluginConfigContractMetadata>();
   const pluginIds = [
@@ -132,10 +133,12 @@ export function resolvePluginConfigContractsById(params: {
     if (bundledContractFallbacks.has(pluginId)) {
       return bundledContractFallbacks.get(pluginId);
     }
-    const discovery = discoverOpenClawPlugins({
-      workspaceDir: params.workspaceDir,
-      env: params.env,
-    });
+    const discovery =
+      params.discovery ??
+      discoverOpenClawPlugins({
+        workspaceDir: params.workspaceDir,
+        env: params.env,
+      });
     const registry = loadPluginManifestRegistry({
       config: params.config,
       workspaceDir: params.workspaceDir,
diff --git a/src/plugins/discovery-threading.test.ts b/src/plugins/discovery-threading.test.ts
@@ -0,0 +1,63 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { PluginDiscoveryResult } from "./discovery.js";
+
+const discoverOpenClawPluginsMock = vi.fn();
+
+vi.mock("./discovery.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./discovery.js")>();
+  return {
+    ...actual,
+    discoverOpenClawPlugins: (...args: unknown[]) => discoverOpenClawPluginsMock(...args),
+  };
+});
+
+const { loadPluginManifestRegistry } = await import("./manifest-registry.js");
+const { resolveInstalledPluginIndexRegistry } =
+  await import("./installed-plugin-index-registry.js");
+
+const emptyDiscovery: PluginDiscoveryResult = { candidates: [], diagnostics: [] };
+
+describe("discovery threading", () => {
+  beforeEach(() => {
+    discoverOpenClawPluginsMock.mockReset();
+    discoverOpenClawPluginsMock.mockReturnValue(emptyDiscovery);
+  });
+
+  describe("loadPluginManifestRegistry", () => {
+    it("skips internal discoverOpenClawPlugins when discovery is supplied", () => {
+      loadPluginManifestRegistry({ discovery: emptyDiscovery });
+      expect(discoverOpenClawPluginsMock).not.toHaveBeenCalled();
+    });
+
+    it("calls discoverOpenClawPlugins when neither discovery nor candidates supplied", () => {
+      loadPluginManifestRegistry({});
+      expect(discoverOpenClawPluginsMock).toHaveBeenCalledTimes(1);
+    });
+
+    it("prefers explicit candidates over discovery when both are supplied", () => {
+      loadPluginManifestRegistry({ candidates: [], diagnostics: [], discovery: emptyDiscovery });
+      expect(discoverOpenClawPluginsMock).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("resolveInstalledPluginIndexRegistry", () => {
+    it("skips internal discoverOpenClawPlugins when discovery is supplied", () => {
+      resolveInstalledPluginIndexRegistry({ discovery: emptyDiscovery, installRecords: {} });
+      expect(discoverOpenClawPluginsMock).not.toHaveBeenCalled();
+    });
+
+    it("calls discoverOpenClawPlugins when neither discovery nor candidates supplied", () => {
+      resolveInstalledPluginIndexRegistry({ installRecords: {} });
+      expect(discoverOpenClawPluginsMock).toHaveBeenCalledTimes(1);
+    });
+
+    it("prefers explicit candidates over discovery when both are supplied", () => {
+      resolveInstalledPluginIndexRegistry({
+        candidates: [],
+        discovery: emptyDiscovery,
+        installRecords: {},
+      });
+      expect(discoverOpenClawPluginsMock).not.toHaveBeenCalled();
+    });
+  });
+});
diff --git a/src/plugins/installed-plugin-index-registry.ts b/src/plugins/installed-plugin-index-registry.ts
@@ -25,12 +25,14 @@ export function resolveInstalledPluginIndexRegistry(params: LoadInstalledPluginI
   const normalized = normalizePluginsConfig(params.config?.plugins);
   const installRecords =
     params.installRecords ?? loadInstalledPluginIndexInstallRecordsSync({ env: params.env });
-  const discovery = discoverOpenClawPlugins({
-    workspaceDir: params.workspaceDir,
-    extraPaths: normalized.loadPaths,
-    env: params.env,
-    installRecords,
-  });
+  const discovery =
+    params.discovery ??
+    discoverOpenClawPlugins({
+      workspaceDir: params.workspaceDir,
+      extraPaths: normalized.loadPaths,
+      env: params.env,
+      installRecords,
+    });
   return {
     candidates: discovery.candidates,
     registry: loadPluginManifestRegistry({
diff --git a/src/plugins/installed-plugin-index-types.ts b/src/plugins/installed-plugin-index-types.ts
@@ -1,7 +1,7 @@
 import type { OpenClawConfig } from "../config/types.js";
 import type { PluginInstallRecord } from "../config/types.plugins.js";
 import type { PluginCompatCode } from "./compat/registry.js";
-import type { PluginCandidate } from "./discovery.js";
+import type { PluginCandidate, PluginDiscoveryResult } from "./discovery.js";
 import type { PluginInstallSourceInfo } from "./install-source-info.js";
 import type { InstalledPluginFileSignature } from "./installed-plugin-index-hash.js";
 import type { PluginManifestRecord } from "./manifest-registry.js";
@@ -130,6 +130,7 @@ export type LoadInstalledPluginIndexParams = {
   installRecords?: Record<string, PluginInstallRecord>;
   candidates?: PluginCandidate[];
   diagnostics?: PluginDiagnostic[];
+  discovery?: PluginDiscoveryResult;
   now?: () => Date;
 };
 
diff --git a/src/plugins/loader.ts b/src/plugins/loader.ts
@@ -50,7 +50,11 @@ import {
   type NormalizedPluginsConfig,
 } from "./config-state.js";
 import { isPluginEnabledByDefaultForPlatform } from "./default-enablement.js";
-import { discoverOpenClawPlugins, type PluginCandidate } from "./discovery.js";
+import {
+  discoverOpenClawPlugins,
+  type PluginCandidate,
+  type PluginDiscoveryResult,
+} from "./discovery.js";
 import { shouldRejectHardlinkedPluginFiles } from "./hardlink-policy.js";
 import { getGlobalHookRunner, initializeGlobalHookRunner } from "./hook-runner-global.js";
 import { toSafeImportPath } from "./import-specifier.js";
@@ -198,6 +202,7 @@ export type PluginLoadOptions = {
   loadModules?: boolean;
   throwOnLoadError?: boolean;
   manifestRegistry?: PluginManifestRegistry;
+  discovery?: PluginDiscoveryResult;
 };
 
 function detailPluginStartupTrace(
@@ -1690,12 +1695,13 @@ export function loadOpenClawPlugins(options: PluginLoadOptions = {}): PluginRegi
           candidates: createPluginCandidatesFromManifestRegistry(suppliedManifestRegistry),
           diagnostics: [] as PluginDiagnostic[],
         }
-      : discoverOpenClawPlugins({
+      : (options.discovery ??
+        discoverOpenClawPlugins({
           workspaceDir: options.workspaceDir,
           extraPaths: normalized.loadPaths,
           env,
           installRecords,
-        });
+        }));
     const manifestRegistry =
       suppliedManifestRegistry ??
       loadPluginManifestRegistry({
@@ -2559,12 +2565,14 @@ export async function loadOpenClawPluginCliRegistry(
     activateGlobalSideEffects: false,
   });
 
-  const discovery = discoverOpenClawPlugins({
-    workspaceDir: options.workspaceDir,
-    extraPaths: normalized.loadPaths,
-    env,
-    installRecords,
-  });
+  const discovery =
+    options.discovery ??
+    discoverOpenClawPlugins({
+      workspaceDir: options.workspaceDir,
+      extraPaths: normalized.loadPaths,
+      env,
+      installRecords,
+    });
   const manifestRegistry = loadPluginManifestRegistry({
     config: cfg,
     workspaceDir: options.workspaceDir,
diff --git a/src/plugins/manifest-registry.ts b/src/plugins/manifest-registry.ts
@@ -10,7 +10,11 @@ import { resolveUserPath } from "../utils.js";
 import { resolveCompatibilityHostVersion } from "../version.js";
 import { loadBundleManifest } from "./bundle-manifest.js";
 import { normalizePluginsConfigWithResolver } from "./config-policy.js";
-import { discoverOpenClawPlugins, type PluginCandidate } from "./discovery.js";
+import {
+  discoverOpenClawPlugins,
+  type PluginCandidate,
+  type PluginDiscoveryResult,
+} from "./discovery.js";
 import { shouldRejectHardlinkedPluginFiles } from "./hardlink-policy.js";
 import { loadInstalledPluginIndexInstallRecordsSync } from "./installed-plugin-index-record-reader.js";
 import type { PluginManifestCommandAlias } from "./manifest-command-aliases.js";
@@ -916,6 +920,7 @@ export function loadPluginManifestRegistry(
     diagnostics?: PluginDiagnostic[];
     installRecords?: Record<string, PluginInstallRecord>;
     bundledChannelConfigCollector?: BundledChannelConfigCollector;
+    discovery?: PluginDiscoveryResult;
   } = {},
 ): PluginManifestRegistry {
   const config = params.config ?? {};
@@ -936,12 +941,13 @@ export function loadPluginManifestRegistry(
         candidates: params.candidates,
         diagnostics: params.diagnostics ?? [],
       }
-    : discoverOpenClawPlugins({
+    : (params.discovery ??
+      discoverOpenClawPlugins({
         workspaceDir: params.workspaceDir,
         extraPaths: normalized.loadPaths,
         env,
         installRecords: getInstallRecords(),
-      });
+      }));
   const diagnostics: PluginDiagnostic[] = [...discovery.diagnostics];
   const candidates: PluginCandidate[] = discovery.candidates;
   const records: PluginManifestRecord[] = [];
