refactor(channels): split chat-meta accessors along the SDK contract

steipete · steipete · commit 1ac75ceeeeb7 · 2026-07-12T00:17:44.000+01:00
getChatChannelMeta keeps its shipped plugin-SDK signature (defined for
bundled ids, fail-loud on impossible misses); new findChatChannelMeta
carries the drift-tolerant optional contract for core auto-enable and
formatting paths.
diff --git a/src/channels/chat-meta.ts b/src/channels/chat-meta.ts
@@ -3,6 +3,7 @@
  *
  * Provides ordered channel metadata for setup, status, and selection surfaces.
  */
+import { expectDefined } from "@openclaw/normalization-core";
 import { buildChatChannelMetaById, type ChatChannelMeta } from "./chat-meta-shared.js";
 import { CHAT_CHANNEL_ORDER, type ChatChannelId } from "./ids.js";
 
@@ -26,7 +27,16 @@ export function listChatChannels(): ChatChannelMeta[] {
 /**
  * Returns metadata for one built-in chat channel id.
  */
-export function getChatChannelMeta(id: ChatChannelId): ChatChannelMeta | undefined {
-  // Undefined is a real state: callers tolerate bundled channel id metadata drift.
+/** Drift-tolerant lookup: undefined when the id is missing from the bundled catalog. */
+export function findChatChannelMeta(id: ChatChannelId): ChatChannelMeta | undefined {
   return getChatChannelMetaById()[id];
 }
+
+/**
+ * Returns metadata for one built-in chat channel id.
+ * Shipped plugin-SDK contract: callers pass bundled ids, so absence is an invariant
+ * violation; drift-tolerant core paths use findChatChannelMeta instead.
+ */
+export function getChatChannelMeta(id: ChatChannelId): ChatChannelMeta {
+  return expectDefined(findChatChannelMeta(id), `chat channel meta for ${id}`);
+}
diff --git a/src/channels/registry.ts b/src/channels/registry.ts
@@ -11,7 +11,7 @@ import {
   findRegisteredChannelPluginEntryById,
   listRegisteredChannelPluginEntries,
 } from "./registry-lookup.js";
-export { getChatChannelMeta } from "./chat-meta.js";
+export { findChatChannelMeta, getChatChannelMeta } from "./chat-meta.js";
 export { CHAT_CHANNEL_ORDER } from "./ids.js";
 export type { ChatChannelId } from "./ids.js";
 export { normalizeChatChannelId };
diff --git a/src/config/plugin-auto-enable.prefer-over.ts b/src/config/plugin-auto-enable.prefer-over.ts
@@ -3,7 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { normalizeStringEntries } from "@openclaw/normalization-core/string-normalization";
-import { getChatChannelMeta, normalizeChatChannelId } from "../channels/registry.js";
+import { findChatChannelMeta, normalizeChatChannelId } from "../channels/registry.js";
 import type { PluginManifestRegistry } from "../plugins/manifest-registry.js";
 import { isRecord, resolveConfigDir, resolveUserPath } from "../utils.js";
 import type { PluginAutoEnableCandidate } from "./plugin-auto-enable.types.js";
@@ -97,7 +97,7 @@ function resolveBuiltInChannelPreferOver(channelId: string): readonly string[] {
   if (!builtInChannelId) {
     return [];
   }
-  return getChatChannelMeta(builtInChannelId)?.preferOver ?? [];
+  return findChatChannelMeta(builtInChannelId)?.preferOver ?? [];
 }
 
 function resolvePreferredOverIds(
diff --git a/src/config/plugin-auto-enable.shared.ts b/src/config/plugin-auto-enable.shared.ts
@@ -12,7 +12,7 @@ import {
   hasBundledChannelConfiguredState,
   listBundledChannelIdsWithConfiguredState,
 } from "../channels/plugins/configured-state.js";
-import { getChatChannelMeta, normalizeChatChannelId } from "../channels/registry.js";
+import { findChatChannelMeta, normalizeChatChannelId } from "../channels/registry.js";
 import { isBlockedObjectKey } from "../infra/prototype-keys.js";
 import { normalizePluginsConfig } from "../plugins/config-state.js";
 import { getCurrentPluginMetadataSnapshot } from "../plugins/current-plugin-metadata-snapshot.js";
@@ -1014,7 +1014,7 @@ function resolveChannelAutoEnableDisplayLabel(
   const builtInChannelId = normalizeChatChannelId(entry.channelId);
   const plugin = manifestRegistry.plugins.find((record) => record.id === entry.pluginId);
   return (
-    (builtInChannelId ? getChatChannelMeta(builtInChannelId)?.label : undefined) ??
+    (builtInChannelId ? findChatChannelMeta(builtInChannelId)?.label : undefined) ??
     plugin?.channelConfigs?.[entry.channelId]?.label ??
     plugin?.channelCatalogMeta?.label
   );
diff --git a/src/infra/outbound/format.ts b/src/infra/outbound/format.ts
@@ -1,6 +1,6 @@
 // Outbound delivery formatting produces human CLI summaries for direct and
 // gateway send results.
-import { getChatChannelMeta } from "../../channels/chat-meta.js";
+import { findChatChannelMeta } from "../../channels/chat-meta.js";
 import { getChannelPlugin } from "../../channels/plugins/index.js";
 import type { ChannelId } from "../../channels/plugins/types.public.js";
 import { normalizeChatChannelId } from "../../channels/registry.js";
@@ -32,7 +32,7 @@ const resolveChannelLabel = (channel: string) => {
   // Some legacy chat channels are not plugins; keep their human labels for CLI output.
   const normalized = normalizeChatChannelId(channel);
   if (normalized) {
-    return getChatChannelMeta(normalized)?.label ?? channel;
+    return findChatChannelMeta(normalized)?.label ?? channel;
   }
   return channel;
 };
diff --git a/src/plugins/channel-validation.test.ts b/src/plugins/channel-validation.test.ts
@@ -57,10 +57,10 @@ describe("normalizeRegisteredChannelPlugin", () => {
       docsPath: normalized?.meta.docsPath,
       blurb: normalized?.meta.blurb,
     }).toEqual({
-      label: telegram?.label,
-      selectionLabel: telegram?.selectionLabel,
-      docsPath: telegram?.docsPath,
-      blurb: telegram?.blurb,
+      label: telegram.label,
+      selectionLabel: telegram.selectionLabel,
+      docsPath: telegram.docsPath,
+      blurb: telegram.blurb,
     });
     expect(diagnostics).toEqual([
       {
diff --git a/src/utils/message-channel.ts b/src/utils/message-channel.ts
@@ -8,7 +8,7 @@ import {
   normalizeGatewayClientName,
 } from "../../packages/gateway-protocol/src/client-info.js";
 import { listBundledChannelCatalogEntries } from "../channels/bundled-channel-catalog-read.js";
-import { getChatChannelMeta } from "../channels/chat-meta.js";
+import { findChatChannelMeta } from "../channels/chat-meta.js";
 import { getRegisteredChannelPluginMeta, normalizeChatChannelId } from "../channels/registry.js";
 export {
   isDeliverableMessageChannel,
@@ -103,7 +103,7 @@ export function isMarkdownCapableMessageChannel(raw?: string | null): boolean {
   }
   const builtInChannel = normalizeChatChannelId(channel);
   if (builtInChannel) {
-    const builtInMeta = getChatChannelMeta(builtInChannel);
+    const builtInMeta = findChatChannelMeta(builtInChannel);
     if (builtInMeta) {
       return builtInMeta.markdownCapable === true;
     }
