refactor: privatize bundled sdk facades

docs/plugins/architecture.md

@@ -974,6 +974,9 @@ Compatibility note:
   helper is only needed by a bundled extension, keep it behind the extension's
   local `api.js` or `runtime-api.js` seam instead of promoting it into
   `openclaw/plugin-sdk/<extension>`.
+- Channel-branded bundled bars such as `feishu`, `googlechat`, `irc`, `line`,
+  `nostr`, `twitch`, and `zalo` stay private unless they are explicitly added
+  back to the public contract.
 - Capability-specific subpaths such as `image-generation`,
   `media-understanding`, and `speech` exist because bundled/native plugins use
   them today. Their presence does not by itself mean every exported helper is a

extensions/feishu/runtime-api.ts

@@ -1 +1,4 @@
-export * from "openclaw/plugin-sdk/feishu";
+// Private runtime barrel for the bundled Feishu extension.
+// Keep this barrel thin and aligned with the local extension surface.
+
+export * from "../../src/plugin-sdk/feishu.js";

extensions/googlechat/runtime-api.ts

@@ -1,4 +1,4 @@
 // Private runtime barrel for the bundled Google Chat extension.
-// Keep this barrel thin and aligned with the curated plugin-sdk/googlechat surface.
+// Keep this barrel thin and aligned with the local extension surface.
 
-export * from "openclaw/plugin-sdk/googlechat";
+export * from "../../src/plugin-sdk/googlechat.js";

extensions/irc/src/runtime-api.ts

@@ -1 +1,4 @@
-export * from "openclaw/plugin-sdk/irc";
+// Private runtime barrel for the bundled IRC extension.
+// Keep this barrel thin and aligned with the local extension surface.
+
+export * from "../../../src/plugin-sdk/irc.js";

extensions/line/api.ts

@@ -1,2 +1,2 @@
-export * from "openclaw/plugin-sdk/line";
+export * from "./runtime-api.js";
 export * from "./setup-api.js";

extensions/line/runtime-api.ts

@@ -1 +1,12 @@
-export * from "openclaw/plugin-sdk/line-core";
+// Private runtime barrel for the bundled LINE extension.
+// Keep this barrel thin and aligned with the local extension surface.
+
+export * from "../../src/plugin-sdk/line.js";
+export { resolveExactLineGroupConfigKey } from "../../src/plugin-sdk/line-core.js";
+export {
+  formatDocsLink,
+  setSetupChannelEnabled,
+  splitSetupEntries,
+  type ChannelSetupDmPolicy,
+  type ChannelSetupWizard,
+} from "../../src/plugin-sdk/line-core.js";

extensions/mattermost/runtime-api.ts

@@ -1 +1,4 @@
-export * from "openclaw/plugin-sdk/mattermost";
+// Private runtime barrel for the bundled Mattermost extension.
+// Keep this barrel thin and aligned with the local extension surface.
+
+export * from "../../src/plugin-sdk/mattermost.js";

extensions/msteams/runtime-api.ts

@@ -1 +1,4 @@
-export * from "openclaw/plugin-sdk/msteams";
+// Private runtime barrel for the bundled Microsoft Teams extension.
+// Keep this barrel thin and aligned with the local extension surface.
+
+export * from "../../src/plugin-sdk/msteams.js";

extensions/nextcloud-talk/runtime-api.ts

@@ -1 +1,4 @@
-export * from "openclaw/plugin-sdk/nextcloud-talk";
+// Private runtime barrel for the bundled Nextcloud Talk extension.
+// Keep this barrel thin and aligned with the local extension surface.
+
+export * from "../../src/plugin-sdk/nextcloud-talk.js";

extensions/nostr/api.ts

@@ -1 +1 @@
-export * from "openclaw/plugin-sdk/nostr";
+export * from "./runtime-api.js";

extensions/nostr/runtime-api.ts

@@ -1 +1,4 @@
-export * from "openclaw/plugin-sdk/nostr";
+// Private runtime barrel for the bundled Nostr extension.
+// Keep this barrel thin and aligned with the local extension surface.
+
+export * from "../../src/plugin-sdk/nostr.js";

extensions/signal/src/accounts.ts

@@ -4,7 +4,7 @@ import {
   resolveAccountEntry,
   type OpenClawConfig,
 } from "openclaw/plugin-sdk/account-resolution";
-import type { SignalAccountConfig } from "openclaw/plugin-sdk/signal-core";
+import type { SignalAccountConfig } from "./runtime-api.js";
 
 export type ResolvedSignalAccount = {
   accountId: string;

extensions/signal/src/config-schema.ts

@@ -1,3 +1,3 @@
-import { buildChannelConfigSchema, SignalConfigSchema } from "openclaw/plugin-sdk/signal-core";
+import { buildChannelConfigSchema, SignalConfigSchema } from "./runtime-api.js";
 
 export const SignalChannelConfigSchema = buildChannelConfigSchema(SignalConfigSchema);

extensions/signal/src/runtime-api.ts

@@ -1 +1,4 @@
-export * from "openclaw/plugin-sdk/signal";
+// Private runtime barrel for the bundled Signal extension.
+// Keep this barrel thin and aligned with the local extension surface.
+
+export * from "../../../src/plugin-sdk/signal.js";

extensions/tlon/api.ts

@@ -1 +1 @@
-export * from "openclaw/plugin-sdk/tlon";
+export * from "./runtime-api.js";

extensions/tlon/runtime-api.ts

@@ -0,0 +1,4 @@
+// Private runtime barrel for the bundled Tlon extension.
+// Keep this barrel thin and aligned with the local extension surface.
+
+export * from "../../src/plugin-sdk/tlon.js";

extensions/twitch/api.ts

@@ -1 +1 @@
-export * from "openclaw/plugin-sdk/twitch";
+export * from "./runtime-api.js";

extensions/twitch/runtime-api.ts

@@ -1 +1,4 @@
-export * from "openclaw/plugin-sdk/twitch";
+// Private runtime barrel for the bundled Twitch extension.
+// Keep this barrel thin and aligned with the local extension surface.
+
+export * from "../../src/plugin-sdk/twitch.js";

extensions/voice-call/api.ts

@@ -1 +1 @@
-export * from "openclaw/plugin-sdk/voice-call";
+export * from "./runtime-api.js";

extensions/voice-call/runtime-api.ts

@@ -0,0 +1,4 @@
+// Private runtime barrel for the bundled Voice Call extension.
+// Keep this barrel thin and aligned with the local extension surface.
+
+export * from "../../src/plugin-sdk/voice-call.js";

extensions/zalo/runtime-api.ts

@@ -1 +1,4 @@
-export * from "openclaw/plugin-sdk/zalo";
+// Private runtime barrel for the bundled Zalo extension.
+// Keep this barrel thin and aligned with the local extension surface.
+
+export * from "../../src/plugin-sdk/zalo.js";

extensions/zalouser/runtime-api.ts

@@ -1 +1,4 @@
-export * from "openclaw/plugin-sdk/zalouser";
+// Private runtime barrel for the bundled Zalo Personal extension.
+// Keep this barrel thin and aligned with the local extension surface.
+
+export * from "../../src/plugin-sdk/zalouser.js";

package.json

@@ -189,38 +189,10 @@
       "types": "./dist/plugin-sdk/discord-core.d.ts",
       "default": "./dist/plugin-sdk/discord-core.js"
     },
-    "./plugin-sdk/feishu": {
-      "types": "./dist/plugin-sdk/feishu.d.ts",
-      "default": "./dist/plugin-sdk/feishu.js"
-    },
-    "./plugin-sdk/googlechat": {
-      "types": "./dist/plugin-sdk/googlechat.d.ts",
-      "default": "./dist/plugin-sdk/googlechat.js"
-    },
-    "./plugin-sdk/irc": {
-      "types": "./dist/plugin-sdk/irc.d.ts",
-      "default": "./dist/plugin-sdk/irc.js"
-    },
-    "./plugin-sdk/line-core": {
-      "types": "./dist/plugin-sdk/line-core.d.ts",
-      "default": "./dist/plugin-sdk/line-core.js"
-    },
     "./plugin-sdk/matrix": {
       "types": "./dist/plugin-sdk/matrix.d.ts",
       "default": "./dist/plugin-sdk/matrix.js"
     },
-    "./plugin-sdk/mattermost": {
-      "types": "./dist/plugin-sdk/mattermost.d.ts",
-      "default": "./dist/plugin-sdk/mattermost.js"
-    },
-    "./plugin-sdk/msteams": {
-      "types": "./dist/plugin-sdk/msteams.d.ts",
-      "default": "./dist/plugin-sdk/msteams.js"
-    },
-    "./plugin-sdk/nextcloud-talk": {
-      "types": "./dist/plugin-sdk/nextcloud-talk.d.ts",
-      "default": "./dist/plugin-sdk/nextcloud-talk.js"
-    },
     "./plugin-sdk/slack": {
       "types": "./dist/plugin-sdk/slack.d.ts",
       "default": "./dist/plugin-sdk/slack.js"
@@ -237,10 +209,6 @@
       "types": "./dist/plugin-sdk/imessage-core.d.ts",
       "default": "./dist/plugin-sdk/imessage-core.js"
     },
-    "./plugin-sdk/signal": {
-      "types": "./dist/plugin-sdk/signal.d.ts",
-      "default": "./dist/plugin-sdk/signal.js"
-    },
     "./plugin-sdk/whatsapp": {
       "types": "./dist/plugin-sdk/whatsapp.d.ts",
       "default": "./dist/plugin-sdk/whatsapp.js"
@@ -357,10 +325,6 @@
       "types": "./dist/plugin-sdk/keyed-async-queue.d.ts",
       "default": "./dist/plugin-sdk/keyed-async-queue.js"
     },
-    "./plugin-sdk/line": {
-      "types": "./dist/plugin-sdk/line.d.ts",
-      "default": "./dist/plugin-sdk/line.js"
-    },
     "./plugin-sdk/llm-task": {
       "types": "./dist/plugin-sdk/llm-task.d.ts",
       "default": "./dist/plugin-sdk/llm-task.js"
@@ -417,10 +381,6 @@
       "types": "./dist/plugin-sdk/image-generation.d.ts",
       "default": "./dist/plugin-sdk/image-generation.js"
     },
-    "./plugin-sdk/nostr": {
-      "types": "./dist/plugin-sdk/nostr.d.ts",
-      "default": "./dist/plugin-sdk/nostr.js"
-    },
     "./plugin-sdk/reply-history": {
       "types": "./dist/plugin-sdk/reply-history.d.ts",
       "default": "./dist/plugin-sdk/reply-history.js"
@@ -457,38 +417,14 @@
       "types": "./dist/plugin-sdk/secret-input.d.ts",
       "default": "./dist/plugin-sdk/secret-input.js"
     },
-    "./plugin-sdk/signal-core": {
-      "types": "./dist/plugin-sdk/signal-core.d.ts",
-      "default": "./dist/plugin-sdk/signal-core.js"
-    },
     "./plugin-sdk/thread-ownership": {
       "types": "./dist/plugin-sdk/thread-ownership.d.ts",
       "default": "./dist/plugin-sdk/thread-ownership.js"
     },
-    "./plugin-sdk/tlon": {
-      "types": "./dist/plugin-sdk/tlon.d.ts",
-      "default": "./dist/plugin-sdk/tlon.js"
-    },
-    "./plugin-sdk/twitch": {
-      "types": "./dist/plugin-sdk/twitch.d.ts",
-      "default": "./dist/plugin-sdk/twitch.js"
-    },
-    "./plugin-sdk/voice-call": {
-      "types": "./dist/plugin-sdk/voice-call.d.ts",
-      "default": "./dist/plugin-sdk/voice-call.js"
-    },
     "./plugin-sdk/web-media": {
       "types": "./dist/plugin-sdk/web-media.d.ts",
       "default": "./dist/plugin-sdk/web-media.js"
     },
-    "./plugin-sdk/zalo": {
-      "types": "./dist/plugin-sdk/zalo.d.ts",
-      "default": "./dist/plugin-sdk/zalo.js"
-    },
-    "./plugin-sdk/zalouser": {
-      "types": "./dist/plugin-sdk/zalouser.d.ts",
-      "default": "./dist/plugin-sdk/zalouser.js"
-    },
     "./plugin-sdk/speech": {
       "types": "./dist/plugin-sdk/speech.d.ts",
       "default": "./dist/plugin-sdk/speech.js"

scripts/lib/plugin-sdk-entrypoints.json

@@ -37,19 +37,11 @@
   "telegram-core",
   "discord",
   "discord-core",
-  "feishu",
-  "googlechat",
-  "irc",
-  "line-core",
   "matrix",
-  "mattermost",
-  "msteams",
-  "nextcloud-talk",
   "slack",
   "slack-core",
   "imessage",
   "imessage-core",
-  "signal",
   "whatsapp",
   "whatsapp-shared",
   "whatsapp-action-runtime",
@@ -79,7 +71,6 @@
   "directory-runtime",
   "json-store",
   "keyed-async-queue",
-  "line",
   "llm-task",
   "memory-lancedb",
   "provider-auth",
@@ -94,7 +85,6 @@
   "provider-usage",
   "provider-web-search",
   "image-generation",
-  "nostr",
   "reply-history",
   "media-understanding",
   "secret-input-runtime",
@@ -104,14 +94,8 @@
   "webhook-path",
   "runtime-store",
   "secret-input",
-  "signal-core",
   "thread-ownership",
-  "tlon",
-  "twitch",
-  "voice-call",
   "web-media",
-  "zalo",
-  "zalouser",
   "speech",
   "state-paths",
   "tool-send"

src/plugin-sdk/acpx.ts

@@ -1,4 +1,4 @@
-// Public ACPX runtime backend helpers.
+// Private ACPX runtime backend helpers for bundled extensions.
 // Keep this surface narrow and limited to the ACP runtime/backend contract.
 
 export type { AcpRuntimeErrorCode } from "../acp/runtime/errors.js";

src/plugin-sdk/device-pair.ts

@@ -1,10 +0,0 @@
-// Narrow plugin-sdk surface for the bundled device-pair plugin.
-// Keep this list additive and scoped to symbols used under extensions/device-pair.
-
-export { definePluginEntry } from "./core.js";
-export { approveDevicePairing, listDevicePairing } from "../infra/device-pairing.js";
-export { issueDeviceBootstrapToken } from "../infra/device-bootstrap.js";
-export type { OpenClawPluginApi } from "../plugins/types.js";
-export { resolveGatewayBindUrl } from "../shared/gateway-bind-url.js";
-export { resolveTailnetHostWithRunner } from "../shared/tailscale-status.js";
-export { runPluginCommandWithTimeout } from "./run-command.js";

src/plugin-sdk/feishu.ts

@@ -1,4 +1,4 @@
-// Narrow plugin-sdk surface for the bundled feishu plugin.
+// Private helper surface for the bundled feishu plugin.
 // Keep this list additive and scoped to symbols used under extensions/feishu.
 
 export type { HistoryEntry } from "../auto-reply/reply/history.js";

src/plugin-sdk/google.ts

@@ -1,4 +1,4 @@
-// Public Google-specific helpers used by bundled Google plugins.
+// Private Google-specific helpers used by bundled Google plugins.
 
 export { normalizeGoogleModelId } from "../agents/model-id-normalization.js";
 export { parseGeminiAuth } from "../infra/gemini-auth.js";

src/plugin-sdk/googlechat.ts

@@ -1,4 +1,4 @@
-// Narrow plugin-sdk surface for the bundled googlechat plugin.
+// Private helper surface for the bundled googlechat plugin.
 // Keep this list additive and scoped to symbols used under extensions/googlechat.
 
 import { resolveChannelGroupRequireMention } from "./channel-policy.js";

src/plugin-sdk/irc.ts

@@ -1,4 +1,4 @@
-// Narrow plugin-sdk surface for the bundled irc plugin.
+// Private helper surface for the bundled irc plugin.
 // Keep this list additive and scoped to symbols used under extensions/irc.
 
 export { resolveControlCommandGate } from "../channels/command-gating.js";

src/plugin-sdk/lobster.ts

@@ -1,4 +1,4 @@
-// Public Lobster plugin helpers.
+// Private Lobster plugin helpers for bundled extensions.
 // Keep this surface narrow and limited to the Lobster workflow/tool contract.
 
 export { definePluginEntry } from "./core.js";

src/plugin-sdk/mattermost.ts

@@ -1,4 +1,4 @@
-// Narrow plugin-sdk surface for the bundled mattermost plugin.
+// Private helper surface for the bundled mattermost plugin.
 // Keep this list additive and scoped to symbols used under extensions/mattermost.
 
 export { formatInboundFromLabel } from "../auto-reply/envelope.js";

src/plugin-sdk/msteams.ts

@@ -1,4 +1,4 @@
-// Narrow plugin-sdk surface for the bundled msteams plugin.
+// Private helper surface for the bundled msteams plugin.
 // Keep this list additive and scoped to symbols used under extensions/msteams.
 
 import { createOptionalChannelSetupSurface } from "./channel-setup.js";

src/plugin-sdk/nextcloud-talk.ts

@@ -1,4 +1,4 @@
-// Narrow plugin-sdk surface for the bundled nextcloud-talk plugin.
+// Private helper surface for the bundled nextcloud-talk plugin.
 // Keep this list additive and scoped to symbols used under extensions/nextcloud-talk.
 
 export { logInboundDrop } from "../channels/logging.js";

src/plugin-sdk/nostr.ts

@@ -1,4 +1,4 @@
-// Narrow plugin-sdk surface for the bundled nostr plugin.
+// Private helper surface for the bundled nostr plugin.
 // Keep this list additive and scoped to symbols used under extensions/nostr.
 
 import { createOptionalChannelSetupSurface } from "./channel-setup.js";

src/plugin-sdk/runtime-api-guardrails.test.ts

@@ -34,13 +34,13 @@ const RUNTIME_API_EXPORT_GUARDS: Record<string, readonly string[]> = {
     'export { probeIMessage } from "./src/probe.js";',
     'export { sendMessageIMessage } from "./src/send.js";',
   ],
-  "extensions/googlechat/runtime-api.ts": ['export * from "openclaw/plugin-sdk/googlechat";'],
+  "extensions/googlechat/runtime-api.ts": ['export * from "../../src/plugin-sdk/googlechat.js";'],
   "extensions/matrix/runtime-api.ts": [
     'export * from "./src/auth-precedence.js";',
     'export * from "./helper-api.js";',
   ],
   "extensions/nextcloud-talk/runtime-api.ts": [
-    'export * from "openclaw/plugin-sdk/nextcloud-talk";',
+    'export * from "../../src/plugin-sdk/nextcloud-talk.js";',
   ],
   "extensions/signal/runtime-api.ts": ['export * from "./src/runtime-api.js";'],
   "extensions/slack/runtime-api.ts": [

src/plugin-sdk/signal-core.ts

@@ -1,3 +1,6 @@
+// Private helper surface for the bundled signal plugin.
+// Keep this list additive and scoped to symbols used under extensions/signal.
+
 export type { SignalAccountConfig } from "../config/types.js";
 export type { ChannelPlugin } from "./channel-plugin-common.js";
 export {

src/plugin-sdk/signal.ts

@@ -1,3 +1,6 @@
+// Private helper surface for the bundled signal plugin.
+// Keep this list additive and scoped to symbols used under extensions/signal.
+
 export type { ChannelMessageActionAdapter } from "../channels/plugins/types.js";
 export type { OpenClawConfig } from "../config/config.js";
 export type { SignalAccountConfig } from "../config/types.js";

src/plugin-sdk/subpaths.test.ts

@@ -61,14 +61,30 @@ describe("plugin-sdk subpath exports", () => {
     expect(pluginSdkSubpaths).not.toContain("acpx");
     expect(pluginSdkSubpaths).not.toContain("compat");
     expect(pluginSdkSubpaths).not.toContain("device-pair");
+    expect(pluginSdkSubpaths).not.toContain("feishu");
     expect(pluginSdkSubpaths).not.toContain("google");
+    expect(pluginSdkSubpaths).not.toContain("googlechat");
+    expect(pluginSdkSubpaths).not.toContain("irc");
+    expect(pluginSdkSubpaths).not.toContain("line");
+    expect(pluginSdkSubpaths).not.toContain("line-core");
     expect(pluginSdkSubpaths).not.toContain("lobster");
+    expect(pluginSdkSubpaths).not.toContain("mattermost");
+    expect(pluginSdkSubpaths).not.toContain("msteams");
+    expect(pluginSdkSubpaths).not.toContain("nextcloud-talk");
+    expect(pluginSdkSubpaths).not.toContain("nostr");
     expect(pluginSdkSubpaths).not.toContain("pairing-access");
     expect(pluginSdkSubpaths).not.toContain("qwen-portal-auth");
     expect(pluginSdkSubpaths).not.toContain("reply-prefix");
+    expect(pluginSdkSubpaths).not.toContain("signal");
+    expect(pluginSdkSubpaths).not.toContain("signal-core");
     expect(pluginSdkSubpaths).not.toContain("synology-chat");
+    expect(pluginSdkSubpaths).not.toContain("tlon");
+    expect(pluginSdkSubpaths).not.toContain("twitch");
     expect(pluginSdkSubpaths).not.toContain("typing");
+    expect(pluginSdkSubpaths).not.toContain("voice-call");
+    expect(pluginSdkSubpaths).not.toContain("zalo");
     expect(pluginSdkSubpaths).not.toContain("zai");
+    expect(pluginSdkSubpaths).not.toContain("zalouser");
     expect(pluginSdkSubpaths).not.toContain("provider-model-definitions");
   });
 

src/plugin-sdk/synology-chat.ts

@@ -1,23 +0,0 @@
-// Narrow plugin-sdk surface for the bundled synology-chat plugin.
-// Keep this list additive and scoped to symbols used under extensions/synology-chat.
-
-export { setAccountEnabledInConfigSection } from "../channels/plugins/config-helpers.js";
-export { buildChannelConfigSchema } from "../channels/plugins/config-schema.js";
-export type { ChannelSetupAdapter } from "../channels/plugins/types.adapters.js";
-export {
-  isRequestBodyLimitError,
-  readRequestBodyWithLimit,
-  requestBodyErrorToText,
-} from "../infra/http-body.js";
-export { emptyPluginConfigSchema } from "../plugins/config-schema.js";
-export { registerPluginHttpRoute } from "../plugins/http-registry.js";
-export type { OpenClawConfig } from "../config/config.js";
-export type { PluginRuntime } from "../plugins/runtime/types.js";
-export type { OpenClawPluginApi } from "../plugins/types.js";
-export { DEFAULT_ACCOUNT_ID } from "../routing/session-key.js";
-export type { FixedWindowRateLimiter } from "./webhook-memory-guards.js";
-export { createFixedWindowRateLimiter } from "./webhook-memory-guards.js";
-export {
-  synologyChatSetupAdapter,
-  synologyChatSetupWizard,
-} from "../../extensions/synology-chat/setup-api.js";

src/plugin-sdk/tlon.ts

@@ -1,4 +1,4 @@
-// Narrow plugin-sdk surface for the bundled tlon plugin.
+// Private helper surface for the bundled tlon plugin.
 // Keep this list additive and scoped to symbols used under extensions/tlon.
 
 import { createOptionalChannelSetupSurface } from "./channel-setup.js";

src/plugin-sdk/twitch.ts

@@ -1,4 +1,4 @@
-// Narrow plugin-sdk surface for the bundled twitch plugin.
+// Private helper surface for the bundled twitch plugin.
 // Keep this list additive and scoped to symbols used under extensions/twitch.
 
 import { createOptionalChannelSetupSurface } from "./channel-setup.js";

src/plugin-sdk/voice-call.ts

@@ -1,4 +1,4 @@
-// Public Voice Call plugin helpers.
+// Private helper surface for the bundled voice-call plugin.
 // Keep this surface narrow and limited to the voice-call feature contract.
 
 export { definePluginEntry } from "./core.js";

src/plugin-sdk/zai.ts

@@ -1,4 +1,4 @@
-// Public Z.ai helpers for provider plugins that need endpoint detection.
+// Private Z.ai helpers for bundled provider plugins that need endpoint detection.
 
 export {
   detectZaiEndpoint,

src/plugin-sdk/zalo.ts

@@ -1,4 +1,4 @@
-// Narrow plugin-sdk surface for the bundled zalo plugin.
+// Private helper surface for the bundled zalo plugin.
 // Keep this list additive and scoped to symbols used under extensions/zalo.
 
 export { jsonResult, readStringParam } from "../agents/tools/common.js";

src/plugin-sdk/zalouser.ts

@@ -1,4 +1,4 @@
-// Narrow plugin-sdk surface for the bundled zalouser plugin.
+// Private helper surface for the bundled zalouser plugin.
 // Keep this list additive and scoped to symbols used under extensions/zalouser.
 
 import { createOptionalChannelSetupSurface } from "./channel-setup.js";