docs: document plugin metadata utilities

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";

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";

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";

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";

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";

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";

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";
 

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;

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 {

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";

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>();

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,

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];

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 {

src/plugins/provider-wizard.ts

@@ -1,3 +1,4 @@
+/** Provider setup wizard helpers shared by provider plugins and CLI setup flows. */
 import {
   normalizeOptionalLowercaseString,
   normalizeOptionalString,

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 {

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";

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();
 }

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 = {

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,