refactor(channels): move bootstrap channel logic behind extension seams

src/plugin-sdk/bluebubbles.ts

@@ -1,3 +1,5 @@
+import type { ChannelAccountSnapshot } from "../channels/plugins/types.core.js";
+import type { ChannelStatusIssue } from "../channels/plugins/types.js";
 import type { OpenClawConfig } from "../config/config.js";
 import {
   parseChatTargetPrefixesOrThrow,
@@ -5,6 +7,7 @@ import {
   type ParsedChatTarget,
 } from "./channel-targets.js";
 import { loadBundledPluginPublicSurfaceModuleSync } from "./facade-runtime.js";
+import { asString, collectIssuesForEnabledAccounts, isRecord } from "./status-helpers.js";
 
 // Narrow plugin-sdk surface for the bundled BlueBubbles plugin.
 // Keep this list additive and scoped to the conversation-binding seam only.
@@ -263,6 +266,101 @@ export function resolveBlueBubblesConversationIdFromTarget(target: string): stri
   return normalizeBlueBubblesAcpConversationId(target)?.conversationId;
 }
 
+type BlueBubblesAccountStatus = {
+  accountId?: unknown;
+  enabled?: unknown;
+  configured?: unknown;
+  running?: unknown;
+  baseUrl?: unknown;
+  lastError?: unknown;
+  probe?: unknown;
+};
+
+type BlueBubblesProbeResult = {
+  ok?: boolean;
+  status?: number | null;
+  error?: string | null;
+};
+
+function readBlueBubblesAccountStatus(
+  value: ChannelAccountSnapshot,
+): BlueBubblesAccountStatus | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  return {
+    accountId: value.accountId,
+    enabled: value.enabled,
+    configured: value.configured,
+    running: value.running,
+    baseUrl: value.baseUrl,
+    lastError: value.lastError,
+    probe: value.probe,
+  };
+}
+
+function readBlueBubblesProbeResult(value: unknown): BlueBubblesProbeResult | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  return {
+    ok: typeof value.ok === "boolean" ? value.ok : undefined,
+    status: typeof value.status === "number" ? value.status : null,
+    error: asString(value.error) ?? null,
+  };
+}
+
+export function collectBlueBubblesStatusIssues(
+  accounts: ChannelAccountSnapshot[],
+): ChannelStatusIssue[] {
+  return collectIssuesForEnabledAccounts({
+    accounts,
+    readAccount: readBlueBubblesAccountStatus,
+    collectIssues: ({ account, accountId, issues }) => {
+      const configured = account.configured === true;
+      const running = account.running === true;
+      const lastError = asString(account.lastError);
+      const probe = readBlueBubblesProbeResult(account.probe);
+
+      if (!configured) {
+        issues.push({
+          channel: "bluebubbles",
+          accountId,
+          kind: "config",
+          message: "Not configured (missing serverUrl or password).",
+          fix: "Run: openclaw channels add bluebubbles --http-url <server-url> --password <password>",
+        });
+        return;
+      }
+
+      if (probe && probe.ok === false) {
+        const errorDetail = probe.error
+          ? `: ${probe.error}`
+          : probe.status
+            ? ` (HTTP ${probe.status})`
+            : "";
+        issues.push({
+          channel: "bluebubbles",
+          accountId,
+          kind: "runtime",
+          message: `BlueBubbles server unreachable${errorDetail}`,
+          fix: "Check that the BlueBubbles server is running and accessible. Verify serverUrl and password in your config.",
+        });
+      }
+
+      if (running && lastError) {
+        issues.push({
+          channel: "bluebubbles",
+          accountId,
+          kind: "runtime",
+          message: `Channel error: ${lastError}`,
+          fix: "Check gateway logs for details. If the webhook is failing, verify the webhook URL is configured in BlueBubbles server settings.",
+        });
+      }
+    },
+  });
+}
+
 export { resolveAckReaction } from "../agents/identity.js";
 export {
   createActionGate,
@@ -305,7 +403,6 @@ export {
   patchScopedAccountConfig,
 } from "../channels/plugins/setup-helpers.js";
 export { createAccountListHelpers } from "../channels/plugins/account-helpers.js";
-export { collectBlueBubblesStatusIssues } from "../channels/plugins/status-issues/bluebubbles.js";
 export type {
   BaseProbeResult,
   ChannelAccountSnapshot,

src/plugin-sdk/channel-status.ts

@@ -1,5 +1,4 @@
 export { PAIRING_APPROVED_MESSAGE } from "../channels/plugins/pairing-message.js";
-export { collectBlueBubblesStatusIssues } from "../channels/plugins/status-issues/bluebubbles.js";
 export {
   projectCredentialSnapshotFields,
   resolveConfiguredFromCredentialStatuses,

src/plugin-sdk/command-auth.ts

@@ -1,6 +1,6 @@
+import { getBundledChannelContractSurfaceModule } from "../channels/plugins/contract-surfaces.js";
 import type { OpenClawConfig } from "../config/config.js";
 import { resolveDmGroupAccessWithLists } from "../security/dm-policy-shared.js";
-export { buildCommandsPaginationKeyboard } from "../../extensions/telegram/api.js";
 export {
   createPreCryptoDirectDmAuthorizer,
   resolveInboundDirectDmAccessWithRuntime,
@@ -86,6 +86,37 @@ export {
   buildHelpMessage,
 } from "../auto-reply/status.js";
 
+type TelegramCommandUiContract = {
+  buildCommandsPaginationKeyboard: (
+    currentPage: number,
+    totalPages: number,
+    agentId?: string,
+  ) => Array<Array<{ text: string; callback_data: string }>>;
+};
+
+function loadTelegramCommandUiContract(): TelegramCommandUiContract {
+  const contract = getBundledChannelContractSurfaceModule<TelegramCommandUiContract>({
+    pluginId: "telegram",
+    preferredBasename: "contract-api.ts",
+  });
+  if (!contract) {
+    throw new Error("telegram command ui contract surface is unavailable");
+  }
+  return contract;
+}
+
+export function buildCommandsPaginationKeyboard(
+  currentPage: number,
+  totalPages: number,
+  agentId?: string,
+): Array<Array<{ text: string; callback_data: string }>> {
+  return loadTelegramCommandUiContract().buildCommandsPaginationKeyboard(
+    currentPage,
+    totalPages,
+    agentId,
+  );
+}
+
 export type ResolveSenderCommandAuthorizationParams = {
   cfg: OpenClawConfig;
   rawBody: string;

src/plugin-sdk/compat.ts

@@ -49,4 +49,4 @@ export {
   resolveBlueBubblesGroupRequireMention,
   resolveBlueBubblesGroupToolPolicy,
 } from "./bluebubbles-policy.js";
-export { collectBlueBubblesStatusIssues } from "../channels/plugins/status-issues/bluebubbles.js";
+export { collectBlueBubblesStatusIssues } from "./bluebubbles.js";

src/plugin-sdk/matrix-runtime-heavy.ts

@@ -1,13 +1,83 @@
+import type { OpenClawConfig } from "./config-runtime.js";
 import { loadBundledPluginPublicSurfaceModuleSync } from "./facade-runtime.js";
 
+type MatrixLegacyLog = {
+  info?: (message: string) => void;
+  warn?: (message: string) => void;
+};
+
+type MatrixLegacyCryptoPlan = {
+  accountId: string;
+  rootDir: string;
+  recoveryKeyPath: string;
+  statePath: string;
+  legacyCryptoPath: string;
+  homeserver: string;
+  userId: string;
+  accessToken: string;
+  deviceId: string | null;
+};
+
+type MatrixLegacyCryptoDetection = {
+  plans: MatrixLegacyCryptoPlan[];
+  warnings: string[];
+};
+
+type MatrixLegacyMigrationResult = {
+  migrated: boolean;
+  changes: string[];
+  warnings: string[];
+};
+
+type MatrixLegacyStatePlan = {
+  accountId: string;
+  legacyStoragePath: string;
+  legacyCryptoPath: string;
+  targetRootDir: string;
+  targetStoragePath: string;
+  targetCryptoPath: string;
+  selectionNote?: string;
+};
+
+type MatrixLegacyStateDetection = MatrixLegacyStatePlan | { warning: string } | null;
+
+type MatrixMigrationSnapshotResult = {
+  created: boolean;
+  archivePath: string;
+  markerPath: string;
+};
+
 type MatrixRuntimeHeavyModule = {
-  autoPrepareLegacyMatrixCrypto: (typeof import("../../extensions/matrix/src/runtime-heavy-api.js"))["autoPrepareLegacyMatrixCrypto"];
-  detectLegacyMatrixCrypto: (typeof import("../../extensions/matrix/src/runtime-heavy-api.js"))["detectLegacyMatrixCrypto"];
-  autoMigrateLegacyMatrixState: (typeof import("../../extensions/matrix/src/runtime-heavy-api.js"))["autoMigrateLegacyMatrixState"];
-  detectLegacyMatrixState: (typeof import("../../extensions/matrix/src/runtime-heavy-api.js"))["detectLegacyMatrixState"];
-  hasActionableMatrixMigration: (typeof import("../../extensions/matrix/src/runtime-heavy-api.js"))["hasActionableMatrixMigration"];
-  hasPendingMatrixMigration: (typeof import("../../extensions/matrix/src/runtime-heavy-api.js"))["hasPendingMatrixMigration"];
-  maybeCreateMatrixMigrationSnapshot: (typeof import("../../extensions/matrix/src/runtime-heavy-api.js"))["maybeCreateMatrixMigrationSnapshot"];
+  autoPrepareLegacyMatrixCrypto: (params: {
+    cfg: OpenClawConfig;
+    env?: NodeJS.ProcessEnv;
+    log?: MatrixLegacyLog;
+    deps?: Partial<Record<string, unknown>>;
+  }) => Promise<MatrixLegacyMigrationResult>;
+  detectLegacyMatrixCrypto: (params: {
+    cfg: OpenClawConfig;
+    env?: NodeJS.ProcessEnv;
+  }) => MatrixLegacyCryptoDetection;
+  autoMigrateLegacyMatrixState: (params: {
+    cfg: OpenClawConfig;
+    env?: NodeJS.ProcessEnv;
+    log?: MatrixLegacyLog;
+  }) => Promise<MatrixLegacyMigrationResult>;
+  detectLegacyMatrixState: (params: {
+    cfg: OpenClawConfig;
+    env?: NodeJS.ProcessEnv;
+  }) => MatrixLegacyStateDetection;
+  hasActionableMatrixMigration: (params: {
+    cfg: OpenClawConfig;
+    env?: NodeJS.ProcessEnv;
+  }) => boolean;
+  hasPendingMatrixMigration: (params: { cfg: OpenClawConfig; env?: NodeJS.ProcessEnv }) => boolean;
+  maybeCreateMatrixMigrationSnapshot: (params: {
+    trigger: string;
+    env?: NodeJS.ProcessEnv;
+    outputDir?: string;
+    log?: MatrixLegacyLog;
+  }) => Promise<MatrixMigrationSnapshotResult>;
 };
 
 function loadFacadeModule(): MatrixRuntimeHeavyModule {

src/plugin-sdk/telegram-command-config.ts

@@ -3,4 +3,6 @@ export {
   normalizeTelegramCommandDescription,
   normalizeTelegramCommandName,
   resolveTelegramCustomCommands,
-} from "../../extensions/telegram/src/command-config.js";
+  type TelegramCustomCommandInput,
+  type TelegramCustomCommandIssue,
+} from "../config/telegram-command-config.js";