docs: document channel plugin runtime helpers

src/channels/plugins/doctor-contract-api.ts

@@ -1,3 +1,8 @@
+/**
+ * Bundled channel doctor contract loader.
+ *
+ * Loads public doctor hooks for channel-owned legacy config rules and compatibility repairs.
+ */
 import type { LegacyConfigRule } from "../../config/legacy.shared.js";
 import type { OpenClawConfig } from "../../config/types.js";
 import { loadBundledPluginPublicArtifactModuleSync } from "../../plugins/public-surface-loader.js";

src/channels/plugins/exposure.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel exposure helpers.
+ *
+ * Resolves whether channel metadata should appear in configured, setup, and docs views.
+ */
 import type { ChannelMeta } from "./types.core.js";
 
 /**

src/channels/plugins/gateway-auth-bypass.ts

@@ -1,3 +1,8 @@
+/**
+ * Bundled channel gateway auth bypass loader.
+ *
+ * Reads optional public artifacts that declare unauthenticated Gateway callback paths.
+ */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { loadBundledPluginPublicArtifactModuleSync } from "../../plugins/public-surface-loader.js";
 

src/channels/plugins/meta-normalization.ts

@@ -1,8 +1,11 @@
+/**
+ * Channel metadata normalizer.
+ *
+ * Recomputes required metadata fields while preserving optional manifest/registry fields.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { ChannelMeta } from "./types.public.js";
 
-// Normalizes partially declared channel metadata while preserving optional
-// extension-owned fields from an existing manifest or registry entry.
 function stripRequiredChannelMeta(meta?: Partial<ChannelMeta> | null) {
   const {
     id: _ignoredId,

src/channels/plugins/module-loader.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel plugin module loader.
+ *
+ * Loads JavaScript or source plugin modules through native require or cached TS loaders.
+ */
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";

src/channels/plugins/native-approval-prompt.ts

@@ -1,3 +1,8 @@
+/**
+ * Native approval prompt capability helpers.
+ *
+ * Detects loaded or known channels that can render approval prompts natively.
+ */
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import { resolveChannelApprovalCapability } from "./approvals.js";
 import type { ChannelPlugin } from "./types.plugin.js";
@@ -6,9 +11,6 @@ export const NATIVE_APPROVAL_PROMPT_RUNTIME_CAPABILITY = "nativeApprovals";
 
 const NATIVE_APPROVAL_PROMPT_RUNTIME_CAPABILITY_NORMALIZED = "nativeapprovals";
 
-// Keep prompt construction lightweight. Full plugin loading is too expensive on
-// prompt-only import paths; plugin-backed checks still cover loaded native
-// channels at runtime.
 const KNOWN_NATIVE_APPROVAL_PROMPT_CHANNELS = new Set([
   "discord",
   "matrix",

src/channels/plugins/outbound.types.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel outbound adapter types.
+ *
+ * Defines text/media/payload/poll contexts, presentation capabilities, and send results.
+ */
 import type { ReplyPayload } from "../../auto-reply/reply-payload.js";
 import type { ReplyToMode } from "../../config/types.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";

src/channels/plugins/outbound/direct-text-media.ts

@@ -1,3 +1,8 @@
+/**
+ * Direct text/media outbound adapter helpers.
+ *
+ * Builds lightweight SDK-backed send adapters with chunking, sanitization, and media limits.
+ */
 import { sendTextMediaPayload } from "openclaw/plugin-sdk/reply-payload";
 import { chunkText } from "../../../auto-reply/chunk.js";
 import type { OpenClawConfig } from "../../../config/types.openclaw.js";
@@ -7,10 +12,6 @@ import type { OutboundMediaAccess } from "../../../media/load-options.js";
 import { resolveChannelMediaMaxBytes } from "../media-limits.js";
 import type { ChannelOutboundAdapter } from "../types.adapters.js";
 
-/**
- * Shared direct text/media outbound adapter factory for SDK-backed channels.
- */
-
 type DirectSendOptions = {
   cfg: OpenClawConfig;
   accountId?: string | null;

src/channels/plugins/outbound/interactive.ts

@@ -1,3 +1,8 @@
+/**
+ * Interactive outbound compatibility helpers.
+ *
+ * Re-exports presentation adapters and keeps the deprecated interactive reducer available.
+ */
 import type { InteractiveReply, InteractiveReplyBlock } from "../../../interactive/payload.js";
 export {
   adaptMessagePresentationForChannel,

src/channels/plugins/outbound/load.ts

@@ -1,13 +1,13 @@
+/**
+ * Lazy channel outbound adapter loader.
+ *
+ * Loads only outbound send primitives from the channel registry for cheap delivery paths.
+ */
 import type { ChannelId } from "../channel-id.types.js";
 import type { ChannelOutboundAdapter } from "../outbound.types.js";
 import { createChannelRegistryLoader } from "../registry-loader.js";
 import type { LoadChannelOutboundAdapter } from "./load.types.js";
 
-// Channel docking: outbound sends should stay cheap to import.
-//
-// The full channel plugins (src/channels/plugins/*.ts) pull in status,
-// setup, gateway monitors, etc. Outbound delivery only needs chunking +
-// send primitives, so we keep a dedicated, lightweight loader here.
 const loadOutboundAdapterFromRegistry = createChannelRegistryLoader<ChannelOutboundAdapter>(
   (entry) => entry.plugin.outbound,
 );

src/channels/plugins/outbound/load.types.ts

@@ -1,3 +1,8 @@
+/**
+ * Lazy outbound adapter loader type.
+ *
+ * Describes the minimal async boundary used by channel delivery code.
+ */
 import type { ChannelId } from "../channel-id.types.js";
 import type { ChannelOutboundAdapter } from "../outbound.types.js";
 

src/channels/plugins/outbound/presentation-limits.ts

@@ -1,3 +1,8 @@
+/**
+ * Presentation limit adapters for channel outbound payloads.
+ *
+ * Truncates and reshapes portable presentation blocks to match per-channel limits.
+ */
 import { normalizeStringEntries } from "@openclaw/normalization-core/string-normalization";
 import { resolveMessagePresentationActionValue } from "../../../interactive/payload.js";
 import type {

src/channels/plugins/package-state-probes.ts

@@ -1,3 +1,8 @@
+/**
+ * Bundled channel package-state probes.
+ *
+ * Resolves lightweight configured/auth state checkers from package metadata and source overlays.
+ */
 import fs from "node:fs";
 import path from "node:path";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
@@ -17,10 +22,6 @@ import {
 } from "../../plugins/plugin-module-loader-cache.js";
 import { loadChannelPluginModule, resolveExistingPluginModulePath } from "./module-loader.js";
 
-/**
- * Package-state probes for bundled channel configured/auth state metadata.
- */
-
 type ChannelPackageStateChecker = (params: {
   cfg: OpenClawConfig;
   env?: NodeJS.ProcessEnv;

src/channels/plugins/pairing-adapters.ts

@@ -1,8 +1,9 @@
-import type { ChannelPairingAdapter } from "./types.adapters.js";
-
 /**
- * Shared pairing adapter helpers for channel SDK/runtime facades.
+ * Channel pairing adapter helpers.
+ *
+ * Creates prefix-stripping normalizers and logged/text pairing approval notifiers.
  */
+import type { ChannelPairingAdapter } from "./types.adapters.js";
 
 type PairingNotifyParams = Parameters<NonNullable<ChannelPairingAdapter["notifyApproval"]>>[0];
 

src/channels/plugins/pairing.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel pairing registry facade.
+ *
+ * Lists pairing-capable channels and dispatches approval notifications through adapters.
+ */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { RuntimeEnv } from "../../runtime.js";
 import type { ChannelId } from "./channel-id.types.js";

src/channels/plugins/pairing.types.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel pairing adapter types.
+ *
+ * Defines setup/allowlist approval hooks used by pairing flows.
+ */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { RuntimeEnv } from "../../runtime.js";
 

src/channels/plugins/persisted-auth-state.ts

@@ -1,3 +1,8 @@
+/**
+ * Bundled channel persisted-auth state probes.
+ *
+ * Lists and checks channel package metadata that can report persisted auth state.
+ */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { PluginDiscoveryResult } from "../../plugins/discovery.js";
 import {
@@ -5,10 +10,6 @@ import {
   listBundledChannelIdsForPackageState,
 } from "./package-state-probes.js";
 
-/**
- * Persisted-auth state probes backed by bundled channel package metadata.
- */
-
 /**
  * Lists bundled channels that declare persisted-auth state metadata.
  */

src/channels/plugins/read-only-command-defaults.ts

@@ -1,3 +1,8 @@
+/**
+ * Read-only channel command default resolver.
+ *
+ * Reads native command/skill defaults from installed plugin manifests without loading plugins.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { isBlockedObjectKey } from "../../infra/prototype-keys.js";
@@ -6,10 +11,6 @@ import type { PluginManifestRecord } from "../../plugins/manifest-registry.js";
 import { resolvePluginMetadataSnapshot } from "../../plugins/plugin-metadata-snapshot.js";
 import type { ChannelPlugin } from "./types.plugin.js";
 
-/**
- * Read-only command default resolution from installed plugin manifests.
- */
-
 const SAFE_MANIFEST_CHANNEL_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/i;
 
 /**

src/channels/plugins/read-only.ts

@@ -1,3 +1,8 @@
+/**
+ * Read-only channel plugin discovery.
+ *
+ * Builds lightweight channel plugin views from config, manifests, and setup metadata.
+ */
 import { createHash } from "node:crypto";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";

src/channels/plugins/registry-loaded-read.ts

@@ -1,13 +1,14 @@
+/**
+ * Hot-path loaded channel plugin reader.
+ *
+ * Reads active runtime channel state without materializing the full registry view.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { ActiveChannelPluginRuntimeShape } from "../../plugins/channel-registry-state.types.js";
 import { getActivePluginChannelRegistryFromState } from "../../plugins/runtime-channel-state.js";
 import type { ChannelPlugin } from "./types.plugin.js";
 import type { ChannelId } from "./types.public.js";
 
-/**
- * Minimal loaded-plugin reader for hot outbound/read paths.
- */
-
 function coerceLoadedChannelPlugin(
   plugin: ActiveChannelPluginRuntimeShape | null | undefined,
 ): ChannelPlugin | undefined {

src/channels/plugins/registry-loaded.ts

@@ -1,3 +1,8 @@
+/**
+ * Loaded channel plugin registry view.
+ *
+ * Normalizes and sorts active plugin runtime state for channel registry callers.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type {
   ActiveChannelPluginRuntimeShape,
@@ -6,10 +11,6 @@ import type {
 import { getActivePluginChannelRegistryFromState } from "../../plugins/runtime-channel-state.js";
 import { CHAT_CHANNEL_ORDER } from "../registry.js";
 
-/**
- * Loaded channel plugin registry view derived from active plugin runtime state.
- */
-
 /**
  * Loaded channel plugin shape after id/meta normalization.
  */

src/channels/plugins/registry-loader.ts

@@ -1,11 +1,12 @@
+/**
+ * Lazy channel registry value loader.
+ *
+ * Resolves plugin sub-surfaces from active channel or full plugin registry state.
+ */
 import type { PluginChannelRegistration } from "../../plugins/registry-types.js";
 import { getActivePluginChannelRegistry, getActivePluginRegistry } from "../../plugins/runtime.js";
 import type { ChannelId } from "./channel-id.types.js";
 
-/**
- * Generic channel registry loader for lazily resolved plugin sub-surfaces.
- */
-
 type ChannelRegistryValueResolver<TValue> = (
   entry: PluginChannelRegistration,
 ) => TValue | undefined;

src/channels/plugins/registry.ts

@@ -1,3 +1,8 @@
+/**
+ * Runtime channel plugin registry facade.
+ *
+ * Lists, resolves, and normalizes active channel plugins with bundled fallback.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { normalizeAnyChannelId } from "../registry.js";
 import { getBundledChannelPlugin } from "./bundled.js";
@@ -9,10 +14,6 @@ import {
 import type { ChannelPlugin } from "./types.plugin.js";
 import type { ChannelId } from "./types.public.js";
 
-/**
- * Runtime channel plugin registry facade used by core command/gateway paths.
- */
-
 /**
  * Lists currently loaded channel plugins in registry order.
  */

src/channels/plugins/runtime-forwarders.ts

@@ -1,8 +1,9 @@
-import type { ChannelDirectoryAdapter, ChannelOutboundAdapter } from "./types.adapters.js";
-
 /**
- * Runtime delegate factories for plugin adapters that load heavy runtimes lazily.
+ * Runtime adapter forwarders.
+ *
+ * Creates directory and outbound adapters whose methods delegate to lazily resolved runtimes.
  */
+import type { ChannelDirectoryAdapter, ChannelOutboundAdapter } from "./types.adapters.js";
 
 type MaybePromise<T> = T | Promise<T>;
 

src/channels/plugins/session-conversation.ts

@@ -1,3 +1,8 @@
+/**
+ * Session conversation key helpers.
+ *
+ * Resolves threaded channel session keys through plugin hooks and generic parsing.
+ */
 import {
   normalizeOptionalLowercaseString,
   normalizeOptionalString,
@@ -14,10 +19,6 @@ import {
 import { normalizeChannelId as normalizeChatChannelId } from "../registry.js";
 import { getLoadedChannelPlugin, normalizeChannelId as normalizeAnyChannelId } from "./registry.js";
 
-/**
- * Session-key conversation resolution helpers for threaded channel targets.
- */
-
 /**
  * Normalized conversation id details for one channel raw id.
  */

src/channels/plugins/session-thread-info-loaded.ts

@@ -1,3 +1,8 @@
+/**
+ * Loaded-plugin session thread info resolver.
+ *
+ * Uses only already loaded channel hooks to resolve thread suffix metadata on hot paths.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import {
   parseRawSessionConversationRef,
@@ -6,10 +11,6 @@ import {
 } from "../../sessions/session-key-utils.js";
 import { getLoadedChannelPluginForRead } from "./registry-loaded-read.js";
 
-/**
- * Hot-path thread info resolver that consults only already loaded channel plugins.
- */
-
 type SessionConversationHookResult = {
   id: string;
   threadId?: string | null;

src/channels/plugins/setup-group-access-configure.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel setup group access configurator.
+ *
+ * Applies prompted group policy and allowlist entries through channel-specific hooks.
+ */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { WizardPrompter } from "../../wizard/prompts.js";
 import { promptChannelAccessConfig, type ChannelAccessPolicy } from "./setup-group-access.js";

src/channels/plugins/setup-group-access.ts

@@ -1,10 +1,11 @@
+/**
+ * Channel setup group access prompts.
+ *
+ * Prompts and normalizes allowlist/open/disabled group access policy choices.
+ */
 import { normalizeStringEntries } from "@openclaw/normalization-core/string-normalization";
 import type { WizardPrompter } from "../../wizard/prompts.js";
 
-/**
- * Shared setup prompts for channel group access allowlists.
- */
-
 /**
  * Group access policy selected during channel setup.
  */

src/channels/plugins/setup-helpers.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel setup config mutation helpers.
+ *
+ * Applies account names and validates setup results for channel onboarding adapters.
+ */
 import { z, type ZodType } from "zod";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "../../routing/session-key.js";

src/channels/plugins/setup-promotion-helpers.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel setup promotion helpers.
+ *
+ * Moves legacy single-account channel config into account-scoped config records.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "../../routing/session-key.js";
 import { getBundledChannelPlugin, hasBundledChannelPackageSetupFeature } from "./bundled.js";
@@ -7,10 +12,6 @@ import {
   isCommonSingleAccountPromotionKey,
 } from "./setup-promotion-keys.js";
 
-/**
- * Helpers for promoting legacy single-account channel config into `accounts`.
- */
-
 type ChannelSectionBase = {
   defaultAccount?: string;
   accounts?: Record<string, Record<string, unknown>>;

src/channels/plugins/setup-registry.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel setup plugin registry.
+ *
+ * Resolves loaded or bundled setup plugins for onboarding flows.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import {
   getActivePluginChannelRegistry,
@@ -8,10 +13,6 @@ import { listBundledChannelSetupPlugins } from "./bundled.js";
 import type { ChannelPlugin } from "./types.plugin.js";
 import type { ChannelId } from "./types.public.js";
 
-/**
- * Setup plugin registry facade for channel onboarding flows.
- */
-
 type ChannelSetupPluginView = {
   sorted: ChannelPlugin[];
   byId: Map<string, ChannelPlugin>;

src/channels/plugins/setup-wizard-binary.ts

@@ -1,3 +1,8 @@
+/**
+ * Setup wizard binary helpers.
+ *
+ * Builds status and text-input helpers for channel setup flows that need local binaries.
+ */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { detectBinary as defaultDetectBinary } from "../../plugins/setup-binary.js";
 import type {