refactor(plugin-sdk): collapse internal config-schema facade usage onto one module (#104665)

steipete · web-flow · commit e34bff22763d · 2026-07-11T13:00:53.000-07:00
diff --git a/extensions/discord/config-api.ts b/extensions/discord/config-api.ts
@@ -1,5 +1,3 @@
 // Discord API module exposes the plugin public contract.
-export {
-  buildChannelConfigSchema,
-  DiscordConfigSchema,
-} from "openclaw/plugin-sdk/bundled-channel-config-schema";
+export { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";
+export { DiscordConfigSchema } from "openclaw/plugin-sdk/bundled-channel-config-schema";
diff --git a/extensions/feishu/src/channel-runtime-api.ts b/extensions/feishu/src/channel-runtime-api.ts
@@ -8,7 +8,7 @@ export type {
 
 export { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-resolution";
 export { createActionGate } from "openclaw/plugin-sdk/channel-actions";
-export { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-primitives";
+export { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";
 export {
   buildProbeChannelStatusSummary,
   createDefaultChannelRuntimeState,
diff --git a/extensions/googlechat/config-api.ts b/extensions/googlechat/config-api.ts
@@ -1,3 +1,3 @@
 // Googlechat API module exposes the plugin public contract.
+export { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";
 export { GoogleChatConfigSchema } from "openclaw/plugin-sdk/bundled-channel-config-schema";
-export { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-primitives";
diff --git a/extensions/googlechat/runtime-api.ts b/extensions/googlechat/runtime-api.ts
@@ -9,7 +9,7 @@ export {
   readReactionParams,
   readStringParam,
 } from "openclaw/plugin-sdk/channel-actions";
-export { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-primitives";
+export { buildChannelConfigSchema, GoogleChatConfigSchema } from "./config-api.js";
 export type {
   ChannelMessageActionAdapter,
   ChannelMessageActionName,
@@ -25,7 +25,6 @@ export { createChannelMessageReplyPipeline } from "openclaw/plugin-sdk/channel-o
 export { PAIRING_APPROVED_MESSAGE } from "openclaw/plugin-sdk/channel-status";
 export { chunkTextForOutbound } from "openclaw/plugin-sdk/text-chunking";
 export type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
-export { GoogleChatConfigSchema } from "openclaw/plugin-sdk/bundled-channel-config-schema";
 export {
   GROUP_POLICY_BLOCKED_LABEL,
   resolveAllowlistProviderRuntimeGroupPolicy,
diff --git a/extensions/imessage/config-api.ts b/extensions/imessage/config-api.ts
@@ -1,5 +1,3 @@
 // Imessage API module exposes the plugin public contract.
-export {
-  buildChannelConfigSchema,
-  IMessageConfigSchema,
-} from "openclaw/plugin-sdk/bundled-channel-config-schema";
+export { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";
+export { IMessageConfigSchema } from "openclaw/plugin-sdk/bundled-channel-config-schema";
diff --git a/extensions/irc/src/runtime-api.ts b/extensions/irc/src/runtime-api.ts
@@ -17,7 +17,7 @@ export type {
 } from "openclaw/plugin-sdk/config-contracts";
 export type { OutboundReplyPayload } from "openclaw/plugin-sdk/reply-payload";
 export { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-id";
-export { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-primitives";
+export { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";
 export {
   PAIRING_APPROVED_MESSAGE,
   buildBaseChannelStatusSummary,
diff --git a/extensions/matrix/src/config-schema.ts b/extensions/matrix/src/config-schema.ts
@@ -1,7 +1,7 @@
 // Matrix helper module supports config schema behavior.
-import { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-primitives";
 import {
   AllowFromListSchema,
+  buildChannelConfigSchema,
   buildNestedDmConfigSchema,
   ContextVisibilityModeSchema,
   GroupPolicySchema,
diff --git a/extensions/matrix/src/runtime-api.ts b/extensions/matrix/src/runtime-api.ts
@@ -14,7 +14,7 @@ export {
   readStringParam,
   ToolAuthorizationError,
 } from "openclaw/plugin-sdk/channel-actions";
-export { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-primitives";
+export { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";
 export type { ChannelPlugin } from "openclaw/plugin-sdk/channel-core";
 export type {
   BaseProbeResult,
diff --git a/extensions/mattermost/src/config-schema-core.ts b/extensions/mattermost/src/config-schema-core.ts
@@ -5,7 +5,7 @@ import {
   GroupPolicySchema,
   MarkdownConfigSchema,
   requireOpenAllowFrom,
-} from "openclaw/plugin-sdk/channel-config-primitives";
+} from "openclaw/plugin-sdk/channel-config-schema";
 import { z } from "zod";
 import { buildSecretInputSchema } from "./secret-input.js";
 
diff --git a/extensions/mattermost/src/config-surface.ts b/extensions/mattermost/src/config-surface.ts
@@ -1,5 +1,5 @@
 // Mattermost helper module supports config surface behavior.
-import { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-primitives";
+import { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";
 import { MattermostConfigSchema } from "./config-schema-core.js";
 import { mattermostChannelConfigUiHints } from "./config-ui-hints.js";
 
diff --git a/extensions/msteams/config-api.ts b/extensions/msteams/config-api.ts
@@ -1,5 +1,3 @@
 // Msteams API module exposes the plugin public contract.
-export {
-  buildChannelConfigSchema,
-  MSTeamsConfigSchema,
-} from "openclaw/plugin-sdk/bundled-channel-config-schema";
+export { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";
+export { MSTeamsConfigSchema } from "openclaw/plugin-sdk/bundled-channel-config-schema";
diff --git a/extensions/nostr/src/config-schema.ts b/extensions/nostr/src/config-schema.ts
@@ -3,7 +3,7 @@ import {
   AllowFromListSchema,
   DmPolicySchema,
   MarkdownConfigSchema,
-} from "openclaw/plugin-sdk/channel-config-primitives";
+} from "openclaw/plugin-sdk/channel-config-schema";
 import { buildSecretInputSchema } from "openclaw/plugin-sdk/secret-input";
 import { z } from "zod";
 
diff --git a/extensions/signal/config-api.ts b/extensions/signal/config-api.ts
@@ -1,5 +1,3 @@
 // Signal API module exposes the plugin public contract.
-export {
-  buildChannelConfigSchema,
-  SignalConfigSchema,
-} from "openclaw/plugin-sdk/bundled-channel-config-schema";
+export { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";
+export { SignalConfigSchema } from "openclaw/plugin-sdk/bundled-channel-config-schema";
diff --git a/extensions/slack/config-api.ts b/extensions/slack/config-api.ts
@@ -1,5 +1,3 @@
 // Slack API module exposes the plugin public contract.
-export {
-  buildChannelConfigSchema,
-  SlackConfigSchema,
-} from "openclaw/plugin-sdk/bundled-channel-config-schema";
+export { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";
+export { SlackConfigSchema } from "openclaw/plugin-sdk/bundled-channel-config-schema";
diff --git a/extensions/sms/src/config-schema.ts b/extensions/sms/src/config-schema.ts
@@ -4,7 +4,7 @@ import {
   buildChannelConfigSchema,
   DmPolicySchema,
   requireOpenAllowFrom,
-} from "openclaw/plugin-sdk/channel-config-primitives";
+} from "openclaw/plugin-sdk/channel-config-schema";
 import { requireChannelOpenAllowFrom } from "openclaw/plugin-sdk/extension-shared";
 import { buildSecretInputSchema } from "openclaw/plugin-sdk/secret-input";
 import { z } from "zod";
diff --git a/extensions/telegram/config-api.ts b/extensions/telegram/config-api.ts
@@ -1,8 +1,6 @@
 // Telegram API module exposes the plugin public contract.
-export {
-  buildChannelConfigSchema,
-  TelegramConfigSchema,
-} from "openclaw/plugin-sdk/bundled-channel-config-schema";
+export { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";
+export { TelegramConfigSchema } from "openclaw/plugin-sdk/bundled-channel-config-schema";
 export {
   normalizeTelegramCommandDescription,
   normalizeTelegramCommandName,
diff --git a/extensions/twitch/src/config-schema.ts b/extensions/twitch/src/config-schema.ts
@@ -1,5 +1,5 @@
 // Twitch helper module supports config schema behavior.
-import { MarkdownConfigSchema } from "openclaw/plugin-sdk/channel-config-primitives";
+import { MarkdownConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";
 import { z } from "zod";
 
 /**
diff --git a/extensions/whatsapp/config-api.ts b/extensions/whatsapp/config-api.ts
@@ -1,5 +1,3 @@
 // Whatsapp API module exposes the plugin public contract.
-export {
-  buildChannelConfigSchema,
-  WhatsAppConfigSchema,
-} from "openclaw/plugin-sdk/bundled-channel-config-schema";
+export { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";
+export { WhatsAppConfigSchema } from "openclaw/plugin-sdk/bundled-channel-config-schema";
diff --git a/src/plugin-sdk/bundled-channel-config-schema.ts b/src/plugin-sdk/bundled-channel-config-schema.ts
@@ -3,16 +3,15 @@
  *
  * Third-party plugins should define plugin-local schemas and import primitives
  * from openclaw/plugin-sdk/channel-config-schema instead of depending on these
- * bundled channel schemas.
+ * bundled channel schemas. Internal callers use this subpath only for the
+ * bundled provider schemas; generic primitives come from channel-config-schema.
  */
 export {
   AllowFromListSchema,
-  buildChannelConfigSchema,
+  BlockStreamingCoalesceSchema,
   buildCatchallMultiAccountChannelSchema,
+  buildChannelConfigSchema,
   buildNestedDmConfigSchema,
-} from "../channels/plugins/config-schema.js";
-export {
-  BlockStreamingCoalesceSchema,
   ContextVisibilityModeSchema,
   DmConfigSchema,
   DmPolicySchema,
@@ -21,8 +20,8 @@ export {
   ReplyRuntimeConfigSchemaShape,
   requireAllowlistAllowFrom,
   requireOpenAllowFrom,
-} from "../config/zod-schema.core.js";
-export { ToolPolicySchema } from "../config/zod-schema.agent-runtime.js";
+  ToolPolicySchema,
+} from "./channel-config-schema.js";
 export {
   DiscordConfigSchema,
   IMessageConfigSchema,
diff --git a/src/plugin-sdk/channel-config-helpers.ts b/src/plugin-sdk/channel-config-helpers.ts
@@ -1,4 +1,10 @@
-// Channel config helpers normalize account and channel config values for plugin setup.
+/**
+ * Channel config adapter and DM-access helpers for plugin setup.
+ *
+ * Not part of the config-schema facade trio despite the similar name: those
+ * export Zod schema builders, while this subpath owns config CRUD adapters,
+ * config-write authorization, and DM access/policy resolution for accounts.
+ */
 import { normalizeOptionalLowercaseString } from "../../packages/normalization-core/src/string-coerce.js";
 import { normalizeStringEntries } from "../../packages/normalization-core/src/string-normalization.js";
 import {
diff --git a/src/plugin-sdk/channel-config-primitives.ts b/src/plugin-sdk/channel-config-primitives.ts
@@ -1,17 +1,21 @@
-/** Narrow channel config-schema primitives without provider-schema re-exports. */
+/**
+ * Narrow channel config-schema primitives without provider-schema re-exports.
+ *
+ * Re-export shell over openclaw/plugin-sdk/channel-config-schema, kept for
+ * third-party plugins until the next SDK break train. Internal and bundled
+ * code imports openclaw/plugin-sdk/channel-config-schema directly.
+ */
 export {
   AllowFromListSchema,
-  buildChannelConfigSchema,
+  BlockStreamingCoalesceSchema,
   buildCatchallMultiAccountChannelSchema,
+  buildChannelConfigSchema,
   buildNestedDmConfigSchema,
-} from "../channels/plugins/config-schema.js";
-export {
-  BlockStreamingCoalesceSchema,
   DmConfigSchema,
   DmPolicySchema,
   GroupPolicySchema,
   MarkdownConfigSchema,
   ReplyRuntimeConfigSchemaShape,
   requireAllowlistAllowFrom,
   requireOpenAllowFrom,
-} from "../config/zod-schema.core.js";
+} from "./channel-config-schema.js";
diff --git a/src/plugin-sdk/channel-config-schema.ts b/src/plugin-sdk/channel-config-schema.ts
@@ -1,4 +1,9 @@
-/** Shared config-schema primitives for channel plugins with DM/group policy knobs. */
+/**
+ * Shared config-schema primitives for channel plugins with DM/group policy knobs.
+ *
+ * Canonical config-schema module: internal/bundled code imports this subpath;
+ * the primitives/bundled/legacy facades are re-export shells over it.
+ */
 export {
   AllowFromListSchema,
   buildChannelConfigSchema,
diff --git a/src/plugin-sdk/discord.ts b/src/plugin-sdk/discord.ts
@@ -42,7 +42,7 @@ export {
   projectCredentialSnapshotFields,
   resolveConfiguredFromCredentialStatuses,
 } from "./channel-status.js";
-export { DiscordConfigSchema } from "./bundled-channel-config-schema.js";
+export { DiscordConfigSchema } from "../config/zod-schema.providers-core.js";
 
 /** Discord channel config shape for one account in OpenClaw config. */
 export type DiscordAccountConfig = NonNullable<NonNullable<OpenClawConfig["channels"]>["discord"]>;
diff --git a/src/plugins/contracts/config-footprint-guardrails.test.ts b/src/plugins/contracts/config-footprint-guardrails.test.ts
@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
 import { GENERATED_BUNDLED_CHANNEL_CONFIG_METADATA } from "../../config/bundled-channel-config-metadata.generated.js";
 import { computeBaseConfigSchemaResponse } from "../../config/schema-base.js";
+import { listGitTrackedFiles } from "../../test-utils/repo-files.js";
 
 const SRC_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
 const REPO_ROOT = resolve(SRC_ROOT, "..");
@@ -211,5 +212,36 @@ describe("config footprint guardrails", () => {
     expect(legacySource).toContain("Compatibility surface for bundled channel schemas");
     expect(legacySource).toContain("openclaw/plugin-sdk/bundled-channel-config-schema");
     expect(legacySource).toContain('export * from "./bundled-channel-config-schema.js";');
+    // Non-canonical facades are re-export shells over the canonical
+    // channel-config-schema module; only bundled provider schemas bypass it.
+    const primitivesSource = readSource("src/plugin-sdk/channel-config-primitives.ts");
+    expect(primitivesSource).toContain('from "./channel-config-schema.js";');
+    expect(primitivesSource).not.toContain("../channels/");
+    expect(primitivesSource).not.toContain("../config/");
+    expect(bundledSource).toContain('from "./channel-config-schema.js";');
+    expect(bundledSource).not.toContain("../channels/");
+  });
+
+  it("keeps internal src imports off the non-canonical channel config schema facades", () => {
+    // channel-config-schema is the canonical internal module; the primitives,
+    // bundled, and legacy shells stay export-compatible for plugins only.
+    const allowedShellImporters = new Set([
+      // The deprecated alias shell re-exports the bundled facade by design.
+      "src/plugin-sdk/channel-config-schema-legacy.ts",
+      // This guardrail file embeds facade specifiers in shell-shape assertions.
+      "src/plugins/contracts/config-footprint-guardrails.test.ts",
+    ]);
+    const facadeImportPattern =
+      /\bfrom\s*["'][^"']*(?:channel-config-primitives|bundled-channel-config-schema|channel-config-schema-legacy)(?:\.js)?["']/u;
+    const files = listGitTrackedFiles({ repoRoot: REPO_ROOT, pathspecs: "src" }) ?? [];
+
+    const offenders = files.filter((file) => {
+      if (!(file.endsWith(".ts") || file.endsWith(".tsx")) || allowedShellImporters.has(file)) {
+        return false;
+      }
+      return facadeImportPattern.test(readFileSync(resolve(REPO_ROOT, file), "utf8"));
+    });
+
+    expect(offenders).toStrictEqual([]);
   });
 });
diff --git a/src/plugins/contracts/plugin-sdk-package-contract-guardrails.test.ts b/src/plugins/contracts/plugin-sdk-package-contract-guardrails.test.ts
@@ -38,6 +38,9 @@ const GENERIC_CORE_PLUGIN_OWNER_NAME_PATTERN =
 const PACKAGE_CONTRACT_SCAN_TIMEOUT_MS = 240_000;
 const DEPRECATED_EXTENSION_SDK_SPECIFIERS = new Set([
   "openclaw/plugin-sdk",
+  // Bundled code uses the canonical channel-config-schema subpath; the
+  // primitives/legacy shells stay export-compatible for third parties only.
+  "openclaw/plugin-sdk/channel-config-primitives",
   "openclaw/plugin-sdk/channel-config-schema-legacy",
   "openclaw/plugin-sdk/compat",
   "openclaw/plugin-sdk/testing",
diff --git a/src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts b/src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts
@@ -86,7 +86,7 @@ const RUNTIME_API_EXPORT_GUARDS: Record<string, readonly string[]> = {
   })]: [
     'export { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-id";',
     'export { createActionGate, jsonResult, readNumberParam, readReactionParams, readStringParam } from "openclaw/plugin-sdk/channel-actions";',
-    'export { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-primitives";',
+    'export { buildChannelConfigSchema, GoogleChatConfigSchema } from "./config-api.js";',
     'export type { ChannelMessageActionAdapter, ChannelMessageActionName, ChannelStatusIssue } from "openclaw/plugin-sdk/channel-contract";',
     'export { missingTargetError } from "openclaw/plugin-sdk/channel-feedback";',
     'export { createAccountStatusSink, runPassiveAccountLifecycle } from "openclaw/plugin-sdk/channel-outbound";',
@@ -95,7 +95,6 @@ const RUNTIME_API_EXPORT_GUARDS: Record<string, readonly string[]> = {
     'export { PAIRING_APPROVED_MESSAGE } from "openclaw/plugin-sdk/channel-status";',
     'export { chunkTextForOutbound } from "openclaw/plugin-sdk/text-chunking";',
     'export type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";',
-    'export { GoogleChatConfigSchema } from "openclaw/plugin-sdk/bundled-channel-config-schema";',
     'export { GROUP_POLICY_BLOCKED_LABEL, resolveAllowlistProviderRuntimeGroupPolicy, resolveDefaultGroupPolicy, warnMissingProviderGroupPolicyFallbackOnce } from "openclaw/plugin-sdk/runtime-group-policy";',
     'export { isDangerousNameMatchingEnabled } from "openclaw/plugin-sdk/dangerous-name-runtime";',
     'export type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";',
diff --git a/test/extension-test-boundary.test.ts b/test/extension-test-boundary.test.ts
@@ -131,6 +131,15 @@ function getImportBasename(importPath: string): string {
   return importPath.split("/").at(-1) ?? importPath;
 }
 
+function readImportBindingName(binding: string): string {
+  return (
+    binding
+      .trim()
+      .replace(/^type\s+/u, "")
+      .split(/\s+as\s+/u)[0] ?? ""
+  );
+}
+
 function collectBundledPluginIds(): Set<string> {
   const extensionFiles = listGitFiles(path.join(repoRoot, "extensions"));
   if (extensionFiles) {
@@ -358,12 +367,43 @@ describe("non-extension test boundaries", () => {
     expect(offenders).toStrictEqual([]);
   });
 
-  it("keeps bundled extension sources off deprecated channel config schema aliases", () => {
+  it("keeps bundled extension sources on the canonical channel config schema facade", () => {
     const files = walkCode(path.join(repoRoot, "extensions"));
+    // The legacy/primitives shells stay export-compatible for third-party
+    // plugins only; bundled code imports channel-config-schema, plus the
+    // bundled facade strictly for retained bundled provider schemas.
+    const bannedSpecifiers = [
+      "openclaw/plugin-sdk/channel-config-schema-legacy",
+      "openclaw/plugin-sdk/channel-config-primitives",
+    ];
+    const bundledProviderSchemaNames = new Set([
+      "DiscordConfigSchema",
+      "GoogleChatConfigSchema",
+      "IMessageConfigSchema",
+      "MSTeamsConfigSchema",
+      "SignalConfigSchema",
+      "SlackConfigSchema",
+      "TelegramConfigSchema",
+      "WhatsAppConfigSchema",
+    ]);
+    const bundledFacadeBindingPattern =
+      /\b(?:import|export)\s+(?:type\s+)?\{(?<bindings>[^}]*)\}\s*from\s*["']openclaw\/plugin-sdk\/bundled-channel-config-schema["']/gu;
 
-    const offenders = files.filter((file) => {
+    const offenders = files.flatMap((file) => {
       const source = fs.readFileSync(path.join(repoRoot, file), "utf8");
-      return source.includes("openclaw/plugin-sdk/channel-config-schema-legacy");
+      const fileOffenders = bannedSpecifiers
+        .filter((specifier) => source.includes(specifier))
+        .map((specifier) => `${file}: ${specifier}`);
+      for (const match of source.matchAll(bundledFacadeBindingPattern)) {
+        const genericBindings = (match.groups?.bindings ?? "")
+          .split(",")
+          .map(readImportBindingName)
+          .filter((name) => name.length > 0 && !bundledProviderSchemaNames.has(name));
+        fileOffenders.push(
+          ...genericBindings.map((name) => `${file}: bundled-channel-config-schema#${name}`),
+        );
+      }
+      return fileOffenders;
     });
 
     expect(offenders).toStrictEqual([]);
