feat(plugins): narrow explicit provider loads from manifests

vincentkoc · vincentkoc · commit f69e89a5b39c · 2026-04-12T09:37:12.000+01:00
diff --git a/docs/plugins/architecture.md b/docs/plugins/architecture.md
@@ -527,9 +527,12 @@ actual behavior such as hooks, tools, commands, or provider flows.
 Optional manifest `activation` and `setup` blocks stay on the control plane.
 They are metadata-only descriptors for activation planning and setup discovery;
 they do not replace runtime registration, `register(...)`, or `setupEntry`.
-The first activation consumer now uses manifest command hints to narrow CLI
-plugin loading when a primary command is known, instead of always loading every
-CLI-capable plugin up front.
+The first live activation consumers now use manifest command and provider hints
+to narrow plugin loading before broader registry materialization:
+
+- CLI loading narrows to plugins that own the requested primary command
+- explicit provider setup/runtime resolution narrows to plugins that own the
+  requested provider id
 
 Setup discovery now prefers descriptor-owned ids such as `setup.providers` and
 `setup.cliBackends` to narrow candidate plugins before it falls back to
diff --git a/docs/plugins/manifest.md b/docs/plugins/manifest.md
@@ -222,8 +222,8 @@ should activate it later.
 This block is metadata only. It does not register runtime behavior, and it does
 not replace `register(...)`, `setupEntry`, or other runtime/plugin entrypoints.
 Current consumers use it as a narrowing hint before broader plugin loading, so
-missing activation metadata only costs performance; it should not change
-correctness.
+missing activation metadata usually only costs performance; it should not
+change correctness while legacy manifest ownership fallbacks still exist.
 
 ```json
 {
@@ -245,9 +245,13 @@ correctness.
 | `onRoutes`       | No       | `string[]`                                           | Route kinds that should activate this plugin.                     |
 | `onCapabilities` | No       | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Broad capability hints used by control-plane activation planning. |
 
-For command-triggered planning specifically, OpenClaw still falls back to
-legacy `commandAliases[].cliCommand` or `commandAliases[].name` when a plugin
-has not added explicit `activation.onCommands` metadata yet.
+Current live consumers:
+
+- command-triggered CLI planning falls back to legacy
+  `commandAliases[].cliCommand` or `commandAliases[].name`
+- provider-triggered setup/runtime planning falls back to legacy
+  `providers[]` and top-level `cliBackends[]` ownership when explicit provider
+  activation metadata is missing
 
 ## setup reference
 
diff --git a/src/plugins/providers.runtime.ts b/src/plugins/providers.runtime.ts
@@ -1,5 +1,6 @@
 import { withActivatedPluginIds } from "./activation-context.js";
 import { resolveBundledPluginCompatibleActivationInputs } from "./activation-context.js";
+import { resolveManifestActivationPluginIds } from "./activation-planner.js";
 import {
   isPluginRegistryLoadInFlight,
   loadOpenClawPlugins,
@@ -21,6 +22,54 @@ import {
 } from "./runtime/load-context.js";
 import type { ProviderPlugin } from "./types.js";
 
+function dedupeSortedPluginIds(values: Iterable<string>): string[] {
+  return [...new Set(values)].toSorted((left, right) => left.localeCompare(right));
+}
+
+function resolveExplicitProviderOwnerPluginIds(params: {
+  providerRefs: readonly string[];
+  config?: PluginLoadOptions["config"];
+  workspaceDir?: string;
+  env?: PluginLoadOptions["env"];
+}): string[] {
+  return dedupeSortedPluginIds(
+    params.providerRefs.flatMap((provider) => {
+      const plannedPluginIds = resolveManifestActivationPluginIds({
+        trigger: {
+          kind: "provider",
+          provider,
+        },
+        config: params.config,
+        workspaceDir: params.workspaceDir,
+        env: params.env,
+      });
+      if (plannedPluginIds.length > 0) {
+        return plannedPluginIds;
+      }
+      // Keep legacy provider/CLI-backend ownership working until every owner is
+      // expressible through activation descriptors.
+      return (
+        resolveOwningPluginIdsForProvider({
+          provider,
+          config: params.config,
+          workspaceDir: params.workspaceDir,
+          env: params.env,
+        }) ?? []
+      );
+    }),
+  );
+}
+
+function mergeExplicitOwnerPluginIds(
+  providerPluginIds: readonly string[],
+  explicitOwnerPluginIds: readonly string[],
+): string[] {
+  if (explicitOwnerPluginIds.length === 0) {
+    return [...providerPluginIds];
+  }
+  return dedupeSortedPluginIds([...providerPluginIds, ...explicitOwnerPluginIds]);
+}
+
 function resolvePluginProviderLoadBase(params: {
   config?: PluginLoadOptions["config"];
   workspaceDir?: string;
@@ -32,19 +81,12 @@ function resolvePluginProviderLoadBase(params: {
   const env = params.env ?? process.env;
   const workspaceDir = params.workspaceDir ?? getActivePluginRegistryWorkspaceDir();
   const providerOwnedPluginIds = params.providerRefs?.length
-    ? [
-        ...new Set(
-          params.providerRefs.flatMap(
-            (provider) =>
-              resolveOwningPluginIdsForProvider({
-                provider,
-                config: params.config,
-                workspaceDir,
-                env,
-              }) ?? [],
-          ),
-        ),
-      ]
+    ? resolveExplicitProviderOwnerPluginIds({
+        providerRefs: params.providerRefs,
+        config: params.config,
+        workspaceDir,
+        env,
+      })
     : [];
   const modelOwnedPluginIds = params.modelRefs?.length
     ? resolveOwningPluginIdsForModelRefs({
@@ -68,14 +110,19 @@ function resolvePluginProviderLoadBase(params: {
           ]),
         ].toSorted((left, right) => left.localeCompare(right))
       : undefined;
+  const explicitOwnerPluginIds = dedupeSortedPluginIds([
+    ...providerOwnedPluginIds,
+    ...modelOwnedPluginIds,
+  ]);
   const runtimeConfig = withActivatedPluginIds({
     config: params.config,
-    pluginIds: [...providerOwnedPluginIds, ...modelOwnedPluginIds],
+    pluginIds: explicitOwnerPluginIds,
   });
   return {
     env,
     workspaceDir,
     requestedPluginIds,
+    explicitOwnerPluginIds,
     runtimeConfig,
   };
 }
@@ -92,13 +139,15 @@ function resolveSetupProviderPluginLoadState(
     includeUntrustedWorkspacePlugins: params.includeUntrustedWorkspacePlugins,
   });
   if (providerPluginIds.length === 0) {
-    return undefined;
+    if (base.explicitOwnerPluginIds.length === 0) {
+      return undefined;
+    }
   }
   const loadOptions = buildPluginRuntimeLoadOptionsFromValues(
     {
       config: withActivatedPluginIds({
         config: base.runtimeConfig,
-        pluginIds: providerPluginIds,
+        pluginIds: mergeExplicitOwnerPluginIds(providerPluginIds, base.explicitOwnerPluginIds),
       }),
       activationSourceConfig: base.runtimeConfig,
       autoEnabledReasons: {},
@@ -107,7 +156,7 @@ function resolveSetupProviderPluginLoadState(
       logger: createPluginRuntimeLoaderLogger(),
     },
     {
-      onlyPluginIds: providerPluginIds,
+      onlyPluginIds: mergeExplicitOwnerPluginIds(providerPluginIds, base.explicitOwnerPluginIds),
       pluginSdkResolution: params.pluginSdkResolution,
       cache: params.cache ?? false,
       activate: params.activate ?? false,
@@ -140,12 +189,15 @@ function resolveRuntimeProviderPluginLoadState(
         env: base.env,
       })
     : activation.config;
-  const providerPluginIds = resolveEnabledProviderPluginIds({
-    config,
-    workspaceDir: base.workspaceDir,
-    env: base.env,
-    onlyPluginIds: base.requestedPluginIds,
-  });
+  const providerPluginIds = mergeExplicitOwnerPluginIds(
+    resolveEnabledProviderPluginIds({
+      config,
+      workspaceDir: base.workspaceDir,
+      env: base.env,
+      onlyPluginIds: base.requestedPluginIds,
+    }),
+    base.explicitOwnerPluginIds,
+  );
   const loadOptions = buildPluginRuntimeLoadOptionsFromValues(
     {
       config,
diff --git a/src/plugins/providers.test.ts b/src/plugins/providers.test.ts
@@ -32,6 +32,8 @@ function createManifestProviderPlugin(params: {
   origin?: "bundled" | "workspace";
   enabledByDefault?: boolean;
   modelSupport?: { modelPrefixes?: string[]; modelPatterns?: string[] };
+  activation?: PluginManifestRecord["activation"];
+  setup?: PluginManifestRecord["setup"];
 }): PluginManifestRecord {
   return {
     id: params.id,
@@ -40,6 +42,8 @@ function createManifestProviderPlugin(params: {
     providers: params.providerIds,
     cliBackends: params.cliBackends ?? [],
     modelSupport: params.modelSupport,
+    activation: params.activation,
+    setup: params.setup,
     skills: [],
     hooks: [],
     origin: params.origin ?? "bundled",
@@ -709,6 +713,98 @@ describe("resolvePluginProviders", () => {
       }),
     );
   });
+
+  it("uses activation.onProviders to keep explicit provider owners on the runtime path", () => {
+    setManifestPlugins([
+      createManifestProviderPlugin({
+        id: "activation-owned-provider",
+        providerIds: [],
+        activation: {
+          onProviders: ["activation-owned"],
+        },
+      }),
+    ]);
+
+    resolvePluginProviders({
+      config: {},
+      providerRefs: ["activation-owned"],
+      activate: true,
+    });
+
+    expect(resolveRuntimePluginRegistryMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        onlyPluginIds: ["activation-owned-provider"],
+        activate: true,
+        config: expect.objectContaining({
+          plugins: expect.objectContaining({
+            allow: ["activation-owned-provider"],
+            entries: {
+              "activation-owned-provider": { enabled: true },
+            },
+          }),
+        }),
+      }),
+    );
+  });
+
+  it("uses setup.providers to keep explicit provider owners on the setup path", () => {
+    setManifestPlugins([
+      createManifestProviderPlugin({
+        id: "setup-owned-provider",
+        providerIds: [],
+        setup: {
+          providers: [{ id: "setup-owned" }],
+        },
+      }),
+    ]);
+
+    resolvePluginProviders({
+      config: {},
+      providerRefs: ["setup-owned"],
+      activate: true,
+      mode: "setup",
+    });
+
+    expect(loadOpenClawPluginsMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        onlyPluginIds: ["setup-owned-provider"],
+        activate: true,
+        config: expect.objectContaining({
+          plugins: expect.objectContaining({
+            allow: ["setup-owned-provider"],
+            entries: {
+              "setup-owned-provider": { enabled: true },
+            },
+          }),
+        }),
+      }),
+    );
+  });
+
+  it("keeps legacy CLI backend ownership as the explicit provider fallback", () => {
+    setOwningProviderManifestPlugins();
+
+    resolvePluginProviders({
+      config: {},
+      providerRefs: ["claude-cli"],
+      activate: true,
+    });
+
+    expect(resolveRuntimePluginRegistryMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        onlyPluginIds: ["anthropic"],
+        activate: true,
+        config: expect.objectContaining({
+          plugins: expect.objectContaining({
+            allow: ["anthropic"],
+            entries: {
+              anthropic: { enabled: true },
+            },
+          }),
+        }),
+      }),
+    );
+  });
   it.each([
     {
       provider: "minimax-portal",
