perf(agents/runtime): short-circuit ensureRuntimePluginsLoaded when active registry exists

poolside-ventures · claude · poolside-ventures · commit bcd6e4a3c020 · 2026-04-29T07:55:40.000+02:00
ensureRuntimePluginsLoaded is called from dispatchReplyFromConfig on
every inbound message and was rebuilding the entire plugin registry
on each call.

Root cause: it builds a 3-field options object (config, workspaceDir,
runtimeOptions) and calls resolveRuntimePluginRegistry. That ends up
in getCompatibleActivePluginRegistry, which does a strict cacheKey
equality check against the active registry's cache key. The boot path
(loadGatewayPlugins) populates the active registry with a 9+ field
options set (onlyPluginIds, activationSourceConfig, autoEnabledReasons,
coreGatewayHandlers, ...). The dispatch-time hash and the boot-time
hash always differ, the equality check always fails, and the dispatcher
falls through to a full loadOpenClawPlugins — re-importing every
plugin module, re-validating manifests, and re-running each plugin's
register(). On hosted gateways with plugins.entries populated, that's
~5–6s of wasted wall-clock per inbound message even when the active
registry was already a valid answer.

The function exists to *ensure* runtime plugins are loaded — if the
active registry is already populated, the goal is already met.
Plugin reconfiguration (installs / uninstalls / auto-enable changes)
already invalidates the active registry through other code paths
(setActivePluginRegistry, gateway restart on config write), so a stale
active registry is not a concern here.

Updates the existing "does not reactivate plugins when a process
already has an active registry" test (which was asserting one call —
incorrect; the prior code reactivated every time) into a regression
test that asserts zero calls when getActivePluginRegistry returns
truthy.

Co-authored-by: Claude Opus 4.7 &lt;noreply@anthropic.com&gt;
diff --git a/src/agents/runtime-plugins.test.ts b/src/agents/runtime-plugins.test.ts
@@ -2,6 +2,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const hoisted = vi.hoisted(() => ({
   resolveRuntimePluginRegistry: vi.fn(),
+  getActivePluginRegistry: vi.fn<() => unknown>(() => undefined),
   getActivePluginRuntimeSubagentMode: vi.fn<() => "default" | "explicit" | "gateway-bindable">(
     () => "default",
   ),
@@ -12,6 +13,7 @@ vi.mock("../plugins/loader.js", () => ({
 }));
 
 vi.mock("../plugins/runtime.js", () => ({
+  getActivePluginRegistry: hoisted.getActivePluginRegistry,
   getActivePluginRuntimeSubagentMode: hoisted.getActivePluginRuntimeSubagentMode,
 }));
 
@@ -21,25 +23,34 @@ describe("ensureRuntimePluginsLoaded", () => {
   beforeEach(async () => {
     hoisted.resolveRuntimePluginRegistry.mockReset();
     hoisted.resolveRuntimePluginRegistry.mockReturnValue(undefined);
+    hoisted.getActivePluginRegistry.mockReset();
+    hoisted.getActivePluginRegistry.mockReturnValue(undefined);
     hoisted.getActivePluginRuntimeSubagentMode.mockReset();
     hoisted.getActivePluginRuntimeSubagentMode.mockReturnValue("default");
     vi.resetModules();
     ({ ensureRuntimePluginsLoaded } = await import("./runtime-plugins.js"));
   });
 
-  it("does not reactivate plugins when a process already has an active registry", async () => {
-    hoisted.resolveRuntimePluginRegistry.mockReturnValue({});
+  it("short-circuits without rebuilding load options when an active registry exists", async () => {
+    // Regression: every inbound dispatch was calling
+    // resolveRuntimePluginRegistry with a 3-field options set that hashes
+    // to a different cacheKey than boot's 9+ field set, so
+    // getCompatibleActivePluginRegistry's strict equality check failed
+    // and the dispatcher fell through to a full loadOpenClawPlugins
+    // rebuild — costing ~5–6s per inbound message on hosted gateways even
+    // though the active registry was already a valid answer.
+    hoisted.getActivePluginRegistry.mockReturnValue({ plugins: [], channels: [] });
 
     ensureRuntimePluginsLoaded({
       config: {} as never,
       workspaceDir: "/tmp/workspace",
       allowGatewaySubagentBinding: true,
     });
 
-    expect(hoisted.resolveRuntimePluginRegistry).toHaveBeenCalledTimes(1);
+    expect(hoisted.resolveRuntimePluginRegistry).not.toHaveBeenCalled();
   });
 
-  it("resolves runtime plugins through the shared runtime helper", async () => {
+  it("resolves runtime plugins through the shared runtime helper when no active registry is present", async () => {
     ensureRuntimePluginsLoaded({
       config: {} as never,
       workspaceDir: "/tmp/workspace",
diff --git a/src/agents/runtime-plugins.ts b/src/agents/runtime-plugins.ts
@@ -1,13 +1,36 @@
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { resolveRuntimePluginRegistry } from "../plugins/loader.js";
-import { getActivePluginRuntimeSubagentMode } from "../plugins/runtime.js";
+import { getActivePluginRegistry, getActivePluginRuntimeSubagentMode } from "../plugins/runtime.js";
 import { resolveUserPath } from "../utils.js";
 
 export function ensureRuntimePluginsLoaded(params: {
   config?: OpenClawConfig;
   workspaceDir?: string | null;
   allowGatewaySubagentBinding?: boolean;
 }): void {
+  // Fast path: if the active plugin registry is already populated (the boot
+  // path ran `loadGatewayPlugins`), the function's intent — "ensure runtime
+  // plugins are loaded" — is already satisfied. Skip rebuilding load options
+  // and re-asking the loader.
+  //
+  // Without this short-circuit, every inbound dispatch hits
+  // `resolveRuntimePluginRegistry` with a 3-field options set
+  // (`config`, `workspaceDir`, `runtimeOptions`), which derives a different
+  // `cacheKey` than boot's 9+ field set (which includes `onlyPluginIds`,
+  // `activationSourceConfig`, `autoEnabledReasons`, etc.).
+  // `getCompatibleActivePluginRegistry`'s strict `cacheKey` equality fails;
+  // the call falls through to a full `loadOpenClawPlugins`, re-imports every
+  // plugin, and re-runs each plugin's `register()` — ~5–6s per inbound
+  // message on hosted gateways. The rebuild is wasted because the active
+  // registry is already a valid answer.
+  //
+  // Plugin reconfiguration (`installs`/`uninstalls`/auto-enable changes)
+  // already invalidates the active registry through other code paths
+  // (`setActivePluginRegistry`, gateway restart on config write), so a stale
+  // active registry is not a concern here.
+  if (getActivePluginRegistry()) {
+    return;
+  }
   const workspaceDir =
     typeof params.workspaceDir === "string" && params.workspaceDir.trim()
       ? resolveUserPath(params.workspaceDir)
