docs: document plugin runtime config helpers

src/plugins/cli-backends.runtime.ts

@@ -1,10 +1,12 @@
 import { getActiveRuntimePluginRegistry } from "./active-runtime-registry.js";
 import type { CliBackendPlugin } from "./cli-backend.types.js";
 
+/** Runtime CLI backend registration with owning plugin id. */
 export type PluginCliBackendEntry = CliBackendPlugin & {
   pluginId: string;
 };
 
+/** Resolves CLI backends from the active runtime plugin registry. */
 export function resolveRuntimeCliBackends(): PluginCliBackendEntry[] {
   return (getActiveRuntimePluginRegistry()?.cliBackends ?? []).map((entry) =>
     Object.assign({}, entry.backend, { pluginId: entry.pluginId }),

src/plugins/config-normalization-shared.ts

@@ -7,6 +7,7 @@ import { normalizeChatChannelId } from "../channels/ids.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { defaultSlotIdForKey } from "./slots.js";
 
+/** Canonical plugin config shape consumed by runtime policy and loaders. */
 export type NormalizedPluginsConfig = {
   enabled: boolean;
   allow: string[];
@@ -42,8 +43,10 @@ export type NormalizedPluginsConfig = {
   >;
 };
 
+/** Plugin id normalizer used while loading aliases or raw config. */
 export type NormalizePluginId = (id: string) => string;
 
+/** Default plugin id normalizer for already-canonical ids. */
 export const identityNormalizePluginId: NormalizePluginId = (id) => id.trim();
 
 function normalizeList(value: unknown, normalizePluginId: NormalizePluginId): string[] {
@@ -220,6 +223,7 @@ function normalizePluginEntries(
   return normalized;
 }
 
+/** Normalizes plugin config while allowing callers to resolve aliases first. */
 export function normalizePluginsConfigWithResolver(
   config?: OpenClawConfig["plugins"],
   normalizePluginId: NormalizePluginId = identityNormalizePluginId,

src/plugins/current-plugin-metadata-state.ts

@@ -3,6 +3,7 @@ let currentPluginMetadataSnapshotConfigFingerprint: string | undefined;
 let currentPluginMetadataSnapshotCompatiblePolicyHashes: readonly string[] | undefined;
 let currentPluginMetadataSnapshotCompatibleConfigFingerprints: readonly string[] | undefined;
 
+/** Stores the process-current plugin metadata snapshot and compatible config fingerprints. */
 export function setCurrentPluginMetadataSnapshotState(
   snapshot: unknown,
   configFingerprint: string | undefined,
@@ -19,6 +20,7 @@ export function setCurrentPluginMetadataSnapshotState(
     : undefined;
 }
 
+/** Clears the process-current plugin metadata snapshot. */
 export function clearCurrentPluginMetadataSnapshotState(): void {
   currentPluginMetadataSnapshot = undefined;
   currentPluginMetadataSnapshotConfigFingerprint = undefined;
@@ -26,6 +28,7 @@ export function clearCurrentPluginMetadataSnapshotState(): void {
   currentPluginMetadataSnapshotCompatibleConfigFingerprints = undefined;
 }
 
+/** Returns the process-current plugin metadata snapshot state. */
 export function getCurrentPluginMetadataSnapshotState(): {
   snapshot: unknown;
   configFingerprint: string | undefined;

src/plugins/gateway-startup-speech-providers.ts

@@ -18,6 +18,7 @@ const TTS_PROVIDER_CONFIG_RESERVED_KEYS = new Set([
   "timeoutMs",
 ]);
 
+/** Treats missing activation as enabled while honoring explicit false values. */
 function isConfigActivationValueEnabled(value: unknown): boolean {
   if (value === false) {
     return false;
@@ -28,6 +29,7 @@ function isConfigActivationValueEnabled(value: unknown): boolean {
   return true;
 }
 
+/** Normalizes configured TTS provider ids for startup plugin selection. */
 export function normalizeConfiguredSpeechProviderIdForStartup(value: unknown): string | undefined {
   if (typeof value !== "string") {
     return undefined;
@@ -39,6 +41,7 @@ export function normalizeConfiguredSpeechProviderIdForStartup(value: unknown): s
   return normalized === "edge" ? "microsoft" : normalized;
 }
 
+/** Resolves provider activation from both canonical providers maps and legacy root keys. */
 function resolveProviderConfigActivation(
   ttsConfig: Record<string, unknown>,
   providerId: string,
@@ -137,6 +140,7 @@ function addConfiguredTtsProviderIds(target: Set<string>, value: unknown): void
   }
 }
 
+/** Collects TTS provider ids referenced by root, agent, channel, account, and plugin config. */
 export function collectConfiguredSpeechProviderIds(config: OpenClawConfig): ReadonlySet<string> {
   const configured = new Set<string>();
   addConfiguredTtsProviderIds(configured, resolveEffectiveTtsConfig(config));

src/plugins/hook-registry.types.ts

@@ -1,6 +1,7 @@
 import type { HookEntry } from "../hooks/types.js";
 import type { PluginHookRegistration as TypedPluginHookRegistration } from "./hook-types.js";
 
+/** Legacy hook registration stored by the global hook runner registry. */
 export type PluginLegacyHookRegistration = {
   pluginId: string;
   entry: HookEntry;
@@ -9,11 +10,13 @@ export type PluginLegacyHookRegistration = {
   rootDir?: string;
 };
 
+/** Hook runner registry state for legacy and typed plugin hooks. */
 export type HookRunnerRegistry = {
   hooks: PluginLegacyHookRegistration[];
   typedHooks: TypedPluginHookRegistration[];
 };
 
+/** Global hook runner registry snapshot with plugin load status. */
 export type GlobalHookRunnerRegistry = HookRunnerRegistry & {
   plugins: Array<{
     id: string;

src/plugins/manifest-types.ts

@@ -1,3 +1,4 @@
+/** UI hint metadata for plugin config schema fields. */
 export type PluginConfigUiHint = {
   label?: string;
   help?: string;
@@ -7,10 +8,13 @@ export type PluginConfigUiHint = {
   placeholder?: string;
 };
 
+/** Top-level plugin manifest format. */
 export type PluginFormat = "openclaw" | "bundle";
 
+/** Supported external bundle manifest formats. */
 export type PluginBundleFormat = "codex" | "claude" | "cursor";
 
+/** Diagnostic emitted while discovering or validating plugins. */
 export type PluginDiagnostic = {
   level: "warn" | "error";
   message: string;

src/plugins/memory-runtime.ts

@@ -6,6 +6,7 @@ import { normalizePluginsConfig } from "./config-state.js";
 import { getMemoryRuntime } from "./memory-state.js";
 import { ensureStandaloneRuntimePluginRegistryLoaded } from "./runtime/standalone-runtime-registry-loader.js";
 
+/** Resolves the configured memory slot to the single runtime plugin that may load memory. */
 function resolveMemoryRuntimePluginIds(config: OpenClawConfig): string[] {
   const plugins = normalizePluginsConfig(config.plugins);
   const memorySlot = plugins.slots.memory;
@@ -53,6 +54,7 @@ function ensureMemoryRuntime(cfg?: OpenClawConfig) {
   return getMemoryRuntime();
 }
 
+/** Returns the active plugin-backed memory search manager for an agent. */
 export async function getActiveMemorySearchManager(params: {
   cfg: OpenClawConfig;
   agentId: string;
@@ -65,16 +67,19 @@ export async function getActiveMemorySearchManager(params: {
   return await runtime.getMemorySearchManager(params);
 }
 
+/** Resolves current memory backend config without constructing a manager. */
 export function resolveActiveMemoryBackendConfig(params: { cfg: OpenClawConfig; agentId: string }) {
   return ensureMemoryRuntime(params.cfg)?.resolveMemoryBackendConfig(params) ?? null;
 }
 
+/** Closes all active plugin-backed memory search managers. */
 export async function closeActiveMemorySearchManagers(cfg?: OpenClawConfig): Promise<void> {
   void cfg;
   const runtime = getMemoryRuntime();
   await runtime?.closeAllMemorySearchManagers?.();
 }
 
+/** Closes the plugin-backed memory search manager for one agent. */
 export async function closeActiveMemorySearchManager(params: {
   cfg: OpenClawConfig;
   agentId: string;

src/plugins/native-module-require.ts

@@ -27,6 +27,7 @@ const moduleWithResolver = Module as typeof Module & {
   }) => { deregister: () => void };
 };
 
+/** True for file extensions Node can load through the native JS module loader. */
 export function isJavaScriptModulePath(modulePath: string): boolean {
   return [".js", ".mjs", ".cjs"].includes(path.extname(modulePath).toLowerCase());
 }
@@ -55,6 +56,7 @@ function isSourceTransformFallbackError(error: unknown, modulePath: string): boo
   );
 }
 
+/** Attempts native require before falling back to source transform paths. */
 export function tryNativeRequireJavaScriptModule(
   modulePath: string,
   options: {
@@ -87,6 +89,7 @@ export function tryNativeRequireJavaScriptModule(
   }
 }
 
+/** Clears a native-loaded module and dependency subtree under the plugin dependency root. */
 export function clearNativeRequireJavaScriptModuleCache(
   modulePath: string,
   options: { dependencyRoot?: string } = {},
@@ -146,6 +149,7 @@ function requireWithOptionalAliases(
   return withNativeRequireAliases(aliasMap, () => nodeRequire(modulePath));
 }
 
+/** Runs a native require block with temporary CJS/ESM alias hooks and restores both afterward. */
 export function withNativeRequireAliases<T>(
   aliasMap: Record<string, string> | undefined,
   run: () => T,

src/plugins/npm-project-roots.ts

@@ -11,6 +11,7 @@ function sortPaths(paths: string[]): string[] {
   return paths.toSorted((left, right) => left.localeCompare(right));
 }
 
+/** Lists project-level npm roots managed below the plugin npm root. */
 export function listManagedPluginNpmProjectRootsSync(npmRoot: string): string[] {
   const projectsDir = resolvePluginNpmProjectsDir(npmRoot);
   try {
@@ -28,6 +29,7 @@ export function listManagedPluginNpmProjectRootsSync(npmRoot: string): string[]
   }
 }
 
+/** Async variant of project-level managed npm root discovery. */
 export async function listManagedPluginNpmProjectRoots(npmRoot: string): Promise<string[]> {
   const projectsDir = resolvePluginNpmProjectsDir(npmRoot);
   try {
@@ -44,10 +46,12 @@ export async function listManagedPluginNpmProjectRoots(npmRoot: string): Promise
   }
 }
 
+/** Returns the root npm install plus all managed project npm roots. */
 export function listManagedPluginNpmRootsSync(npmRoot: string): string[] {
   return [npmRoot, ...listManagedPluginNpmProjectRootsSync(npmRoot)];
 }
 
+/** Async variant of managed npm root discovery. */
 export async function listManagedPluginNpmRoots(npmRoot: string): Promise<string[]> {
   return [npmRoot, ...(await listManagedPluginNpmProjectRoots(npmRoot))];
 }

src/plugins/official-external-install-records.ts

@@ -40,6 +40,7 @@ function isOfficialClawHubInstallRecord(record: PluginInstallRecord): boolean {
   return (record.clawhubUrl ?? "").replace(/\/+$/, "") === "https://clawhub.ai";
 }
 
+/** Resolves the official npm spec when an install record matches the trusted catalog package. */
 export function resolveTrustedSourceLinkedOfficialNpmSpec(params: {
   pluginId: string;
   record: PluginInstallRecord;
@@ -64,6 +65,7 @@ export function resolveTrustedSourceLinkedOfficialNpmSpec(params: {
   return recordedPackageNames.includes(officialPackageName) ? officialSpec : undefined;
 }
 
+/** Resolves the official ClawHub spec when a trusted-source install record matches. */
 export function resolveTrustedSourceLinkedOfficialClawHubSpec(params: {
   pluginId: string;
   record: PluginInstallRecord;
@@ -71,6 +73,7 @@ export function resolveTrustedSourceLinkedOfficialClawHubSpec(params: {
   return resolveTrustedSourceLinkedOfficialClawHubInstall(params)?.clawhubSpec;
 }
 
+/** Resolves official ClawHub/npm specs linked to a trusted-source install record. */
 export function resolveTrustedSourceLinkedOfficialClawHubInstall(params: {
   pluginId: string;
   record: PluginInstallRecord;

src/plugins/toggle-config.ts

@@ -1,6 +1,7 @@
 import { normalizeChatChannelId } from "../channels/ids.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 
+/** Returns config with a plugin enabled/disabled and optional built-in channel state synced. */
 export function setPluginEnabledInConfig(
   config: OpenClawConfig,
   pluginId: string,

src/plugins/web-content-extractor-public-artifacts.ts

@@ -10,6 +10,7 @@ const WEB_CONTENT_EXTRACTOR_ARTIFACT_CANDIDATES = [
   "web-content-extractor-api.js",
 ] as const;
 
+/** Checks public artifact exports before adding them to runtime extractor registration. */
 function isWebContentExtractorPlugin(value: unknown): value is WebContentExtractorPlugin {
   return (
     isRecord(value) &&
@@ -42,6 +43,7 @@ function tryLoadBundledPublicArtifactModule(params: {
   return null;
 }
 
+/** Collects zero-arg factory exports in deterministic order for prompt-cache stability. */
 function collectExtractorFactories(mod: Record<string, unknown>): WebContentExtractorPlugin[] {
   const extractors: WebContentExtractorPlugin[] = [];
   for (const [name, exported] of Object.entries(mod).toSorted(([left], [right]) =>
@@ -63,6 +65,7 @@ function collectExtractorFactories(mod: Record<string, unknown>): WebContentExtr
   return extractors;
 }
 
+/** Loads bundled web content extractor entries from public plugin artifacts. */
 export function loadBundledWebContentExtractorEntriesFromDir(params: {
   dirName: string;
   pluginId: string;