From f4d2748ca5123bfc4c65a3ff8b83aa2ff1be6505 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 04:57:24 -0400
Subject: [PATCH] docs: document plugin metadata utilities

---
 src/plugins/bundle-manifest.test.ts                   | 1 +
 src/plugins/channel-plugin-ids.test.ts                | 1 +
 src/plugins/gateway-startup-plugin-ids.ts             | 1 +
 src/plugins/hooks.phase-hooks.test.ts                 | 1 +
 src/plugins/host-tool-param-parsers.test.ts           | 1 +
 src/plugins/installed-plugin-index.ts                 | 1 +
 src/plugins/logger.test.ts                            | 1 +
 src/plugins/manifest-command-aliases.runtime.ts       | 3 +++
 src/plugins/manifest-owner-policy.test.ts             | 1 +
 src/plugins/native-module-require.test.ts             | 1 +
 src/plugins/plugin-metadata-lifecycle.ts              | 1 +
 src/plugins/plugin-module-loader-cache.ts             | 3 +++
 src/plugins/provider-auth-ref.ts                      | 3 +++
 src/plugins/provider-catalog-unified-text.ts          | 1 +
 src/plugins/provider-wizard.ts                        | 1 +
 src/plugins/slots.test.ts                             | 1 +
 src/plugins/source-checkout-runtime.test.ts           | 1 +
 src/plugins/tool-descriptor-cache.ts                  | 3 +++
 src/plugins/update.ts                                 | 3 +++
 src/plugins/wired-hooks-reply-payload-sending.test.ts | 1 +
 20 files changed, 30 insertions(+)

diff --git a/src/plugins/bundle-manifest.test.ts b/src/plugins/bundle-manifest.test.ts
index ca0d63cfbe4..27c3cf6e161 100644
--- a/src/plugins/bundle-manifest.test.ts
+++ b/src/plugins/bundle-manifest.test.ts
@@ -1,3 +1,4 @@
+/** Tests bundle manifest parsing for Codex, Claude, Cursor, and OpenClaw formats. */
 import fs from "node:fs";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
diff --git a/src/plugins/channel-plugin-ids.test.ts b/src/plugins/channel-plugin-ids.test.ts
index 3571c3552bc..ac10595da06 100644
--- a/src/plugins/channel-plugin-ids.test.ts
+++ b/src/plugins/channel-plugin-ids.test.ts
@@ -1,3 +1,4 @@
+/** Tests channel plugin id resolution from config, manifests, and installed state. */
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import type { InstalledPluginIndex, InstalledPluginIndexRecord } from "./installed-plugin-index.js";
diff --git a/src/plugins/gateway-startup-plugin-ids.ts b/src/plugins/gateway-startup-plugin-ids.ts
index 4e99703276c..a99736fdd34 100644
--- a/src/plugins/gateway-startup-plugin-ids.ts
+++ b/src/plugins/gateway-startup-plugin-ids.ts
@@ -1,3 +1,4 @@
+/** Resolves plugin ids that should load during Gateway startup. */
 import { collectConfiguredModelRefs } from "@openclaw/model-catalog-core/configured-model-refs";
 import { buildModelCatalogMergeKey } from "@openclaw/model-catalog-core/model-catalog-refs";
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
diff --git a/src/plugins/hooks.phase-hooks.test.ts b/src/plugins/hooks.phase-hooks.test.ts
index a27364935dd..47fac9be608 100644
--- a/src/plugins/hooks.phase-hooks.test.ts
+++ b/src/plugins/hooks.phase-hooks.test.ts
@@ -1,3 +1,4 @@
+/** Tests phase-scoped plugin hooks and hook registration ordering. */
 import { beforeEach, describe, expect, it } from "vitest";
 import { createHookRunner } from "./hooks.js";
 import { addStaticTestHooks } from "./hooks.test-helpers.js";
diff --git a/src/plugins/host-tool-param-parsers.test.ts b/src/plugins/host-tool-param-parsers.test.ts
index 5a8991a6cb7..efac8996278 100644
--- a/src/plugins/host-tool-param-parsers.test.ts
+++ b/src/plugins/host-tool-param-parsers.test.ts
@@ -1,3 +1,4 @@
+/** Tests host tool parameter parsers exposed to plugin callbacks. */
 import path from "node:path";
 import { describe, expect, it } from "vitest";
 import { deriveToolParams } from "./host-tool-param-parsers.js";
diff --git a/src/plugins/installed-plugin-index.ts b/src/plugins/installed-plugin-index.ts
index 274441bbfaa..790b8406cb5 100644
--- a/src/plugins/installed-plugin-index.ts
+++ b/src/plugins/installed-plugin-index.ts
@@ -1,3 +1,4 @@
+/** Public installed-plugin-index API for load, refresh, policy hash, and invalidation checks. */
 import type { OpenClawConfig } from "../config/types.js";
 import { resolveCompatibilityHostVersion } from "../version.js";
 import { normalizePluginsConfig, resolveEffectivePluginActivationState } from "./config-state.js";
diff --git a/src/plugins/logger.test.ts b/src/plugins/logger.test.ts
index 6877fda3324..d022a0af08e 100644
--- a/src/plugins/logger.test.ts
+++ b/src/plugins/logger.test.ts
@@ -1,3 +1,4 @@
+/** Tests plugin logger formatting and diagnostic forwarding behavior. */
 import { describe, expect, it, vi } from "vitest";
 import { createPluginLoaderLogger } from "./logger.js";
 
diff --git a/src/plugins/manifest-command-aliases.runtime.ts b/src/plugins/manifest-command-aliases.runtime.ts
index 3db4ac0120a..583608a7562 100644
--- a/src/plugins/manifest-command-aliases.runtime.ts
+++ b/src/plugins/manifest-command-aliases.runtime.ts
@@ -1,3 +1,4 @@
+/** Resolves manifest-declared command and tool ownership at runtime. */
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { resolveManifestActivationPluginIds } from "./activation-planner.js";
@@ -15,6 +16,7 @@ import {
 } from "./manifest-contract-eligibility.js";
 import { hasManifestToolAvailability } from "./manifest-tool-availability.js";
 
+/** Resolves the manifest owner for a CLI command alias when one is declared. */
 export function resolveManifestCommandAliasOwner(params: {
   command: string | undefined;
   config?: OpenClawConfig;
@@ -35,6 +37,7 @@ export function resolveManifestCommandAliasOwner(params: {
   });
 }
 
+/** Resolves the plugin id that should be activated for a CLI command surface. */
 export function resolveManifestCliCommandSurfaceOwner(params: {
   command: string | undefined;
   config?: OpenClawConfig;
diff --git a/src/plugins/manifest-owner-policy.test.ts b/src/plugins/manifest-owner-policy.test.ts
index 0cc9626875f..d2fb9f67722 100644
--- a/src/plugins/manifest-owner-policy.test.ts
+++ b/src/plugins/manifest-owner-policy.test.ts
@@ -1,3 +1,4 @@
+/** Tests manifest owner availability policy for bundled, workspace, and installed plugins. */
 import { describe, expect, it } from "vitest";
 import { normalizePluginsConfig } from "./config-state.js";
 import {
diff --git a/src/plugins/native-module-require.test.ts b/src/plugins/native-module-require.test.ts
index d4baa1b4841..6ee75d39883 100644
--- a/src/plugins/native-module-require.test.ts
+++ b/src/plugins/native-module-require.test.ts
@@ -1,3 +1,4 @@
+/** Tests native module require behavior for plugin runtime loading. */
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
diff --git a/src/plugins/plugin-metadata-lifecycle.ts b/src/plugins/plugin-metadata-lifecycle.ts
index d08812015df..d5fad8ee5ee 100644
--- a/src/plugins/plugin-metadata-lifecycle.ts
+++ b/src/plugins/plugin-metadata-lifecycle.ts
@@ -1,3 +1,4 @@
+/** Coordinates plugin metadata snapshot and process memo cache lifecycle resets. */
 import { clearCurrentPluginMetadataSnapshotState } from "./current-plugin-metadata-state.js";
 
 const pluginMetadataProcessMemoClears = new Set<() => void>();
diff --git a/src/plugins/plugin-module-loader-cache.ts b/src/plugins/plugin-module-loader-cache.ts
index a63c2291fac..7e296c32da9 100644
--- a/src/plugins/plugin-module-loader-cache.ts
+++ b/src/plugins/plugin-module-loader-cache.ts
@@ -1,3 +1,4 @@
+/** Caches plugin module loaders and native-load stats for runtime/source module imports. */
 import { createRequire } from "node:module";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -13,6 +14,7 @@ import {
   type PluginSdkResolutionPreference,
 } from "./sdk-alias.js";
 
+/** Jiti-based module loader used for plugin source/runtime imports. */
 export type PluginModuleLoader = ReturnType<typeof createJiti>;
 export type PluginModuleLoaderFactory = typeof createJiti;
 export type PluginModuleLoaderCache = Pick<
@@ -80,6 +82,7 @@ function recordSourceTransformTarget(target: string): void {
   }
 }
 
+/** Returns process-local plugin module loader stats for diagnostics and tests. */
 export function getPluginModuleLoaderStats(): PluginModuleLoaderStatsSnapshot {
   return {
     calls: pluginModuleLoaderStats.calls,
diff --git a/src/plugins/provider-auth-ref.ts b/src/plugins/provider-auth-ref.ts
index 3db8a1667d6..1bd06be951c 100644
--- a/src/plugins/provider-auth-ref.ts
+++ b/src/plugins/provider-auth-ref.ts
@@ -1,3 +1,4 @@
+/** Resolves provider auth secret refs from env, file, and exec-backed secret providers. */
 import {
   normalizeOptionalString,
   normalizeStringifiedOptionalString,
@@ -26,6 +27,7 @@ const ENV_SOURCE_LABEL_RE = /(?:^|:\s)([A-Z][A-Z0-9_]*)$/;
 
 type SecretRefChoice = "env" | "provider"; // pragma: allowlist secret
 
+/** Copy overrides used while prompting for provider secret-ref setup. */
 export type SecretRefSetupPromptCopy = {
   sourceMessage?: string;
   envVarMessage?: string;
@@ -37,6 +39,7 @@ export type SecretRefSetupPromptCopy = {
   providerValidatedMessage?: (provider: string, id: string, source: "file" | "exec") => string;
 };
 
+/** Extracts a trailing env var name from a human-facing secret source label. */
 export function extractEnvVarFromSourceLabel(source: string): string | undefined {
   const match = ENV_SOURCE_LABEL_RE.exec(source.trim());
   return match?.[1];
diff --git a/src/plugins/provider-catalog-unified-text.ts b/src/plugins/provider-catalog-unified-text.ts
index 76caf80a001..2e6ae6dc290 100644
--- a/src/plugins/provider-catalog-unified-text.ts
+++ b/src/plugins/provider-catalog-unified-text.ts
@@ -1,3 +1,4 @@
+/** Builds unified text-inference provider catalog metadata from plugin providers. */
 import type { UnifiedModelCatalogEntry } from "@openclaw/model-catalog-core/model-catalog-types";
 import { readRecordValue } from "../shared/safe-record.js";
 import {
diff --git a/src/plugins/provider-wizard.ts b/src/plugins/provider-wizard.ts
index c0cfa88aeae..1189a09e57e 100644
--- a/src/plugins/provider-wizard.ts
+++ b/src/plugins/provider-wizard.ts
@@ -1,3 +1,4 @@
+/** Provider setup wizard helpers shared by provider plugins and CLI setup flows. */
 import {
   normalizeOptionalLowercaseString,
   normalizeOptionalString,
diff --git a/src/plugins/slots.test.ts b/src/plugins/slots.test.ts
index 9ac30f171c5..42634ff75e2 100644
--- a/src/plugins/slots.test.ts
+++ b/src/plugins/slots.test.ts
@@ -1,3 +1,4 @@
+/** Tests plugin slot normalization and exclusive slot selection behavior. */
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import {
diff --git a/src/plugins/source-checkout-runtime.test.ts b/src/plugins/source-checkout-runtime.test.ts
index d05fe906c0d..c9df997db88 100644
--- a/src/plugins/source-checkout-runtime.test.ts
+++ b/src/plugins/source-checkout-runtime.test.ts
@@ -1,3 +1,4 @@
+/** Verifies source-checkout plugin runtime resolution and dependency diagnostics. */
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { setBundledPluginsDirOverrideForTest } from "./bundled-dir.js";
diff --git a/src/plugins/tool-descriptor-cache.ts b/src/plugins/tool-descriptor-cache.ts
index 873f25d5941..b2daf9cd1df 100644
--- a/src/plugins/tool-descriptor-cache.ts
+++ b/src/plugins/tool-descriptor-cache.ts
@@ -1,3 +1,4 @@
+/** Caches plugin tool descriptors by plugin source, contract names, and runtime context. */
 import fs from "node:fs";
 import type { AnyAgentTool } from "../agents/tools/common.js";
 import { resolveRuntimeConfigCacheKey } from "../config/runtime-snapshot.js";
@@ -8,6 +9,7 @@ import type { OpenClawPluginToolContext } from "./types.js";
 const PLUGIN_TOOL_DESCRIPTOR_CACHE_VERSION = 1;
 const PLUGIN_TOOL_DESCRIPTOR_CACHE_LIMIT = 256;
 
+/** Cached display descriptor for one plugin-created tool. */
 export type CachedPluginToolDescriptor = {
   descriptor: ToolDescriptor;
   displaySummary?: string;
@@ -20,6 +22,7 @@ let nextDescriptorCacheObjectId = 1;
 
 export type PluginToolDescriptorConfigCacheKeyMemo = WeakMap<object, string | number | null>;
 
+/** Creates a memo table for config cache keys reused across descriptor cache calls. */
 export function createPluginToolDescriptorConfigCacheKeyMemo(): PluginToolDescriptorConfigCacheKeyMemo {
   return new WeakMap();
 }
diff --git a/src/plugins/update.ts b/src/plugins/update.ts
index 6b380077489..eb6cf69b4e8 100644
--- a/src/plugins/update.ts
+++ b/src/plugins/update.ts
@@ -1,3 +1,4 @@
+/** Updates installed plugins across npm, ClawHub, marketplace, Git, and bundled bridge sources. */
 import path from "node:path";
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
@@ -67,12 +68,14 @@ import { resolvePackagePluginApiRange } from "./package-compat.js";
 import { linkOpenClawPeerDependencies } from "./plugin-peer-link.js";
 import { defaultSlotIdForKey } from "./slots.js";
 
+/** Logger surface used by plugin update flows. */
 export type PluginUpdateLogger = {
   info?: (message: string) => void;
   warn?: (message: string) => void;
   error?: (message: string) => void;
 };
 
+/** Outcome status for one plugin update attempt. */
 export type PluginUpdateStatus = "updated" | "unchanged" | "skipped" | "error";
 
 export type PluginUpdateChannelFallback = {
diff --git a/src/plugins/wired-hooks-reply-payload-sending.test.ts b/src/plugins/wired-hooks-reply-payload-sending.test.ts
index 3c144d66dd7..238f96be448 100644
--- a/src/plugins/wired-hooks-reply-payload-sending.test.ts
+++ b/src/plugins/wired-hooks-reply-payload-sending.test.ts
@@ -1,3 +1,4 @@
+/** Tests reply payload sending through wired plugin hook flows. */
 import { describe, expect, it, vi } from "vitest";
 import {
   getReplyPayloadMetadata,