refactor(providers): unify lifecycle-safe manifest registration (#114381)

* refactor(providers): canonicalize manifest-driven registration * fix(zai): eliminate type-only SDK import side effects
2026-08-02 07:31:33 +00:00 · 2026-07-27 03:20:02 -04:00
parent 65cce37480
commit eec2c0cc26
20 changed files with 892 additions and 825 deletions
--- a/extensions/opencode/index.test.ts
+++ b/extensions/opencode/index.test.ts
@@ -44,6 +44,21 @@ describe("opencode provider plugin", () => {
  beforeEach(() => {
    clearLiveCatalogCacheForTests();
  });
+
+  it("registers only the Zen auth choice from its own provider manifest", async () => {
+    const provider = await registerSingleProviderPlugin(plugin);
+
+    expect(provider.id).toBe("opencode");
+    expect(provider.envVars).toEqual(["OPENCODE_API_KEY", "OPENCODE_ZEN_API_KEY"]);
+    expect(provider.auth.map((method) => method.id)).toEqual(["api-key"]);
+    expect(provider.auth.map((method) => method.wizard?.choiceId)).toEqual(["opencode-zen"]);
+    expect(provider.auth[0]?.wizard).toMatchObject({
+      choiceLabel: "OpenCode Zen catalog",
+      groupId: "opencode",
+      groupHint: "Shared API key for Zen + Go catalogs",
+    });
+  });
+
  it("registers image media understanding through the OpenCode plugin", async () => {
    const { mediaProviders } = await registerProviderPlugin({
      plugin,
--- a/extensions/opencode/index.ts
+++ b/extensions/opencode/index.ts
@@ -1,6 +1,5 @@
 // Opencode plugin entrypoint registers its OpenClaw integration.
-import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
-import { createProviderApiKeyAuthMethod } from "openclaw/plugin-sdk/provider-auth-api-key";
+import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry";
 import {
  buildProviderReplayFamilyHooks,
  matchesExactOrPrefix,
@@ -8,6 +7,7 @@ import {
 import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { applyOpencodeZenConfig, OPENCODE_ZEN_DEFAULT_MODEL } from "./api.js";
 import { opencodeMediaUnderstandingProvider } from "./media-understanding-provider.js";
+import manifest from "./openclaw.plugin.json" with { type: "json" };
 import {
  buildOpencodeZenLiveProviderConfig,
  buildStaticOpencodeZenProviderConfig,
@@ -22,12 +22,6 @@ const PROVIDER_ID = "opencode";
 const MINIMAX_MODERN_MODEL_MATCHERS = ["minimax-m2.7"] as const;
 const OPENCODE_SHARED_PROFILE_IDS = ["opencode:default", "opencode-go:default"] as const;
 const OPENCODE_SHARED_HINT = "Shared API key for Zen + Go catalogs";
-const OPENCODE_SHARED_WIZARD_GROUP = {
-  groupId: "opencode",
-  groupLabel: "OpenCode",
-  groupHint: OPENCODE_SHARED_HINT,
-} as const;
-
 type OpencodeZenCatalogAuth = {
  apiKey?: string;
  discoveryApiKey?: string;
@@ -56,103 +50,85 @@ function isModernOpencodeModel(modelId: string): boolean {
  return !matchesExactOrPrefix(lower, MINIMAX_MODERN_MODEL_MATCHERS);
 }

-export default definePluginEntry({
+export default defineSingleProviderPluginEntry({
  id: PROVIDER_ID,
  name: "OpenCode Zen Provider",
  description: "Bundled OpenCode Zen provider plugin",
-  register(api) {
-    api.registerProvider({
-      id: PROVIDER_ID,
-      label: "OpenCode Zen",
-      docsPath: "/providers/models",
-      envVars: ["OPENCODE_API_KEY", "OPENCODE_ZEN_API_KEY"],
-      auth: [
-        createProviderApiKeyAuthMethod({
-          providerId: PROVIDER_ID,
-          methodId: "api-key",
-          label: "OpenCode Zen catalog",
-          hint: OPENCODE_SHARED_HINT,
-          optionKey: "opencodeZenApiKey",
-          flagName: "--opencode-zen-api-key",
-          envVar: "OPENCODE_API_KEY",
-          promptMessage: "Enter OpenCode API key",
-          profileIds: [...OPENCODE_SHARED_PROFILE_IDS],
-          defaultModel: OPENCODE_ZEN_DEFAULT_MODEL,
-          applyConfig: (cfg) => applyOpencodeZenConfig(cfg),
-          expectedProviders: ["opencode", "opencode-go"],
-          noteMessage: [
-            "OpenCode uses one API key across the Zen and Go catalogs.",
-            "Zen provides access to Claude, GPT, Gemini, and more models.",
-            "Get your API key at: https://opencode.ai/auth",
-            "Choose the Zen catalog when you want the curated multi-model proxy.",
-          ].join("\n"),
-          noteTitle: "OpenCode",
-          wizard: {
-            choiceId: "opencode-zen",
-            choiceLabel: "OpenCode Zen catalog",
-            ...OPENCODE_SHARED_WIZARD_GROUP,
-          },
-        }),
-      ],
-      normalizeConfig: ({ providerConfig }) => {
-        const normalizedBaseUrl = normalizeOpencodeZenBaseUrl({
-          api: providerConfig.api,
-          baseUrl: providerConfig.baseUrl,
-        });
-        return normalizedBaseUrl && normalizedBaseUrl !== providerConfig.baseUrl
-          ? { ...providerConfig, baseUrl: normalizedBaseUrl }
-          : undefined;
-      },
-      normalizeResolvedModel: ({ model }) => {
-        const normalizedBaseUrl = normalizeOpencodeZenBaseUrl({
-          api: model.api,
-          baseUrl: model.baseUrl,
-        });
-        return normalizedBaseUrl && normalizedBaseUrl !== model.baseUrl
-          ? { ...model, baseUrl: normalizedBaseUrl }
-          : undefined;
-      },
-      normalizeTransport: ({ api: apiLocal, baseUrl }) => {
-        const normalizedBaseUrl = normalizeOpencodeZenBaseUrl({ api: apiLocal, baseUrl });
-        return normalizedBaseUrl && normalizedBaseUrl !== baseUrl
-          ? {
-              api: apiLocal,
-              baseUrl: normalizedBaseUrl,
-            }
-          : undefined;
-      },
-      resolveDynamicModel: ({ modelId }) => resolveOpencodeZenModel(modelId),
-      staticCatalog: {
-        order: "simple",
-        run: async () => ({
-          provider: buildStaticOpencodeZenProviderConfig(),
-        }),
-      },
-      catalog: {
-        order: "simple",
-        run: async (ctx) => {
-          const auth = resolveOpencodeZenCatalogAuth(ctx.resolveProviderApiKey);
-          if (!auth) {
-            return null;
-          }
-          if (!auth.discoveryApiKey) {
-            return {
-              provider: buildStaticOpencodeZenProviderConfig(auth.apiKey),
-            };
+  manifest,
+  provider: {
+    label: "OpenCode Zen",
+    docsPath: "/providers/models",
+    envVars: ["OPENCODE_API_KEY", "OPENCODE_ZEN_API_KEY"],
+    manifestAuth: {
+      hint: OPENCODE_SHARED_HINT,
+      promptMessage: "Enter OpenCode API key",
+      profileIds: [...OPENCODE_SHARED_PROFILE_IDS],
+      defaultModel: OPENCODE_ZEN_DEFAULT_MODEL,
+      applyConfig: applyOpencodeZenConfig,
+      expectedProviders: ["opencode", "opencode-go"],
+      noteMessage: [
+        "OpenCode uses one API key across the Zen and Go catalogs.",
+        "Zen provides access to Claude, GPT, Gemini, and more models.",
+        "Get your API key at: https://opencode.ai/auth",
+        "Choose the Zen catalog when you want the curated multi-model proxy.",
+      ].join("\n"),
+      noteTitle: "OpenCode",
+    },
+    normalizeConfig: ({ providerConfig }) => {
+      const normalizedBaseUrl = normalizeOpencodeZenBaseUrl({
+        api: providerConfig.api,
+        baseUrl: providerConfig.baseUrl,
+      });
+      return normalizedBaseUrl && normalizedBaseUrl !== providerConfig.baseUrl
+        ? { ...providerConfig, baseUrl: normalizedBaseUrl }
+        : undefined;
+    },
+    normalizeResolvedModel: ({ model }) => {
+      const normalizedBaseUrl = normalizeOpencodeZenBaseUrl({
+        api: model.api,
+        baseUrl: model.baseUrl,
+      });
+      return normalizedBaseUrl && normalizedBaseUrl !== model.baseUrl
+        ? { ...model, baseUrl: normalizedBaseUrl }
+        : undefined;
+    },
+    normalizeTransport: ({ api: apiLocal, baseUrl }) => {
+      const normalizedBaseUrl = normalizeOpencodeZenBaseUrl({ api: apiLocal, baseUrl });
+      return normalizedBaseUrl && normalizedBaseUrl !== baseUrl
+        ? {
+            api: apiLocal,
+            baseUrl: normalizedBaseUrl,
          }
+        : undefined;
+    },
+    resolveDynamicModel: ({ modelId }) => resolveOpencodeZenModel(modelId),
+    catalog: {
+      order: "simple",
+      run: async (ctx) => {
+        const auth = resolveOpencodeZenCatalogAuth(ctx.resolveProviderApiKey);
+        if (!auth) {
+          return null;
+        }
+        if (!auth.discoveryApiKey) {
          return {
-            provider: await buildOpencodeZenLiveProviderConfig({
-              apiKey: auth.apiKey ?? auth.discoveryApiKey,
-              discoveryApiKey: auth.discoveryApiKey,
-            }),
+            provider: buildStaticOpencodeZenProviderConfig(auth.apiKey),
          };
-        },
+        }
+        return {
+          provider: await buildOpencodeZenLiveProviderConfig({
+            apiKey: auth.apiKey ?? auth.discoveryApiKey,
+            discoveryApiKey: auth.discoveryApiKey,
+          }),
+        };
      },
-      augmentModelCatalog: () => listOpencodeZenModelCatalogEntries(),
-      ...buildProviderReplayFamilyHooks({ family: "passthrough-gemini" }),
-      isModernModelRef: ({ modelId }) => isModernOpencodeModel(modelId),
-      resolveThinkingProfile: resolveOpencodeThinkingProfile,
-    });
+      staticRun: async () => ({ provider: buildStaticOpencodeZenProviderConfig() }),
+    },
+    augmentModelCatalog: () => listOpencodeZenModelCatalogEntries(),
+    ...buildProviderReplayFamilyHooks({ family: "passthrough-gemini" }),
+    isModernModelRef: ({ modelId }) => isModernOpencodeModel(modelId),
+    resolveThinkingProfile: resolveOpencodeThinkingProfile,
+  },
+  register(api) {
    api.registerMediaUnderstandingProvider(opencodeMediaUnderstandingProvider);
    registerOpenCodeSessionCatalog(api);
  },