docs: document plugin setup state

src/plugins/activation-planner.test.ts

@@ -1,3 +1,4 @@
+/** Tests manifest activation planning for commands, providers, channels, and capabilities. */
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 const mocks = vi.hoisted(() => ({

src/plugins/bundled-compat.ts

@@ -1,8 +1,10 @@
+/** Compatibility helpers that auto-enable bundled plugins for legacy and Vitest flows. */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { PluginEntryConfig } from "../config/types.plugins.js";
 import { hasExplicitPluginConfig } from "./config-policy.js";
 import { normalizePluginId } from "./config-state.js";
 
+/** Returns config with selected bundled plugins explicitly enabled when compat rules require it. */
 export function withBundledPluginEnablementCompat(params: {
   config: OpenClawConfig | undefined;
   pluginIds: readonly string[];
@@ -57,6 +59,7 @@ export function withBundledPluginEnablementCompat(params: {
   };
 }
 
+/** Enables bundled plugins in Vitest when tests did not provide explicit plugin config. */
 export function withBundledPluginVitestCompat(params: {
   config: OpenClawConfig | undefined;
   pluginIds: readonly string[];

src/plugins/cli-backend.types.ts

@@ -1,3 +1,4 @@
+/** Type contracts for plugin-owned CLI backend integrations. */
 import type { CliBackendConfig } from "../config/types.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { ContextEngineHostCapability } from "../context-engine/types.js";

src/plugins/cli-gateway-nodes-runtime.test.ts

@@ -1,3 +1,4 @@
+/** Tests plugin CLI node Gateway runtime timeout and invocation behavior. */
 import { MAX_TIMER_TIMEOUT_MS } from "@openclaw/normalization-core/number-coercion";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import {

src/plugins/cli.test.ts

@@ -1,3 +1,4 @@
+/** CLI integration coverage for plugin commands, setup, status, and registry flows. */
 import { Command } from "commander";
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";

src/plugins/config-state.ts

@@ -1,3 +1,4 @@
+/** Normalizes plugin config and resolves effective enablement, slots, and activation sources. */
 import {
   normalizeOptionalLowercaseString,
   normalizeOptionalString,
@@ -73,6 +74,7 @@ function createScopedPluginIdNormalizer(): NormalizePluginId {
     });
 }
 
+/** Normalizes user/config plugin ids into the canonical lowercase key form. */
 export function normalizePluginId(id: string): string {
   return normalizePluginIdWithLookup(id, getBundledPluginAliasLookup);
 }

src/plugins/effective-plugin-ids.ts

@@ -1,3 +1,4 @@
+/** Resolves effective plugin ids from config, installed records, and activation metadata. */
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import { sortUniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import {
@@ -140,6 +141,7 @@ function collectSelectedContextEnginePluginIds(config: OpenClawConfig): string[]
   return [pluginId];
 }
 
+/** Lists plugin ids that are effectively enabled for a config/discovery context. */
 export function resolveEffectivePluginIds(params: {
   config: OpenClawConfig;
   env: NodeJS.ProcessEnv;

src/plugins/embedding-provider-runtime-shared.ts

@@ -1,3 +1,4 @@
+/** Shared runtime helpers for embedding provider lookup across core and plugin capabilities. */
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import {

src/plugins/hook-agent-context.ts

@@ -1,3 +1,4 @@
+/** Builds plugin hook agent context snapshots from active session and model state. */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { parseRawSessionConversationRef } from "../sessions/session-key-utils.js";
 import type { PluginHookAgentContext } from "./hook-types.js";

src/plugins/host-hook-cleanup.ts

@@ -1,3 +1,4 @@
+/** Runs plugin cleanup callbacks and clears host-side plugin session/runtime state. */
 import fs from "node:fs";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { getRuntimeConfig } from "../config/config.js";
@@ -17,6 +18,7 @@ import { getActivePluginRegistry } from "./runtime.js";
 import { normalizeSessionEntrySlotKey } from "./session-entry-slot-keys.js";
 
 /** Failure captured while running plugin cleanup hooks. */
+/** Failure captured while running one plugin cleanup callback. */
 export type PluginHostCleanupFailure = {
   pluginId: string;
   hookId: string;
@@ -344,6 +346,7 @@ function collectSessionEntrySlotKeys(
 }
 
 /** Runs persistent and in-memory cleanup for a plugin, session, or host lifecycle event. */
+/** Runs cleanup callbacks for one plugin and returns failures instead of throwing. */
 export async function runPluginHostCleanup(params: {
   cfg?: OpenClawConfig;
   registry?: PluginRegistry | null;

src/plugins/host-hook-runtime.ts

@@ -1,3 +1,4 @@
+/** Stores plugin host-hook run context, scheduler jobs, and pending event cleanup state. */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { AgentEventPayload } from "../infra/agent-events.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
@@ -168,6 +169,7 @@ function getPluginRunContextNamespaces(params: {
   return namespaces;
 }
 
+/** Stores JSON-compatible plugin run context for one run/plugin/namespace tuple. */
 export function setPluginRunContext(params: {
   pluginId: string;
   patch: PluginRunContextPatch;
@@ -208,6 +210,7 @@ export function setPluginRunContext(params: {
 }
 
 // oxlint-disable-next-line typescript/no-unnecessary-type-parameters -- Run-context JSON reads are caller-typed by namespace.
+/** Reads previously stored plugin run context for one run/plugin/namespace tuple. */
 export function getPluginRunContext<T extends PluginJsonValue = PluginJsonValue>(params: {
   pluginId: string;
   get: PluginRunContextGetParams;

src/plugins/manifest-contract-runtime.test.ts

@@ -1,3 +1,4 @@
+/** Tests manifest contract runtime resolution across bundled and installed plugin metadata. */
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const loadPluginMetadataSnapshot = vi.hoisted(() => vi.fn());

src/plugins/manifest-owner-policy.ts

@@ -1,3 +1,4 @@
+/** Applies manifest owner policy for plugin availability and activation decisions. */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { normalizePluginsConfig, resolveEffectivePluginActivationState } from "./config-state.js";
 import { isPluginEnabledByDefaultForPlatform } from "./default-enablement.js";

src/plugins/memory-state.ts

@@ -1,3 +1,4 @@
+/** Registry state for plugin memory runtimes, prompt supplements, and flush planning. */
 import type { MemoryCitationsMode } from "../config/types.memory.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { MemorySearchManager } from "../memory-host-sdk/host/types.js";

src/plugins/npm-install-security-scan.release.test.ts

@@ -1,3 +1,4 @@
+/** Release-lane coverage for npm plugin install security scanning. */
 import { execFile, spawnSync } from "node:child_process";
 import fs, { copyFileSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";

src/plugins/plugin-lookup-table.test.ts

@@ -1,3 +1,4 @@
+/** Tests plugin lookup table indexing for manifest-owned contribution ids. */
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { resolveInstalledPluginIndexPolicyHash } from "./installed-plugin-index-policy.js";

src/plugins/provider-api-key-auth.ts

@@ -1,3 +1,4 @@
+/** Builds API-key provider auth methods that write profiles and config updates. */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { normalizeUniqueStringEntries } from "@openclaw/normalization-core/string-normalization";
 import { upsertAuthProfileWithLock } from "../agents/auth-profiles/profiles.js";

src/plugins/registry.provider-like.test.ts

@@ -1,3 +1,4 @@
+/** Verifies provider-like plugin registry entries across capability families. */
 import { describe, expect, it } from "vitest";
 import { createPluginRecord } from "./loader-records.js";
 import { createPluginRegistry } from "./registry.js";

src/plugins/setup-registry.runtime.ts

@@ -1,3 +1,4 @@
+/** Runtime lookup helpers for plugin setup CLI backend descriptors. */
 import { createRequire } from "node:module";
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
@@ -39,6 +40,7 @@ let setupRegistryRuntimeModule: SetupRegistryRuntimeModule | null | undefined;
 let cachedSetupCliBackendDescriptors: SetupCliBackendDescriptorCache | undefined;
 let cachedBundledSetupCliBackends: SetupCliBackendDescriptorCache | undefined;
 
+/** Test hooks for resetting setup-registry runtime module caches. */
 export const testing = {
   resetRuntimeState(): void {
     setupRegistryRuntimeModule = undefined;

src/plugins/web-search-providers.runtime.test.ts

@@ -1,3 +1,4 @@
+/** Covers runtime loading and sorting for plugin web search providers. */
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 type RegistryModule = typeof import("./registry.js");