docs: document plugin runtime contracts

src/plugins/bundled-capability-runtime.ts

@@ -1,3 +1,4 @@
+/** Loads capability providers from bundled plugin public runtime artifacts. */
 import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import { openRootFileSync } from "../infra/boundary-file-read.js";

src/plugins/bundled-channel-runtime.ts

@@ -1,3 +1,4 @@
+/** Loads bundled channel plugin runtime entries and setup metadata. */
 import fs from "node:fs";
 import path from "node:path";
 import { resolveBundledPluginGeneratedPath } from "./bundled-plugin-metadata.js";

src/plugins/capability-provider-runtime.ts

@@ -1,3 +1,4 @@
+/** Resolves plugin capability providers through manifest contracts, bundled compat, and runtime registries. */
 import { sortUniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import { resolveVoiceModelRefs } from "../../packages/speech-core/voice-models.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
@@ -99,6 +100,7 @@ function uniqueSorted(values: Iterable<string>): string[] {
   return sortUniqueStrings(values);
 }
 
+/** Loads the manifest snapshot used to resolve capability-provider ownership. */
 export function loadCapabilityManifestSnapshot(params: {
   cfg?: OpenClawConfig;
   workspaceDir?: string;

src/plugins/command-registration.ts

@@ -1,3 +1,4 @@
+/** Validates and registers plugin command definitions into the global command registry. */
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalLowercaseString,
@@ -76,16 +77,19 @@ function getAgentPromptSurfaces(): Set<string> {
   return agentPromptSurfaces;
 }
 
+/** Result returned when a plugin command registration succeeds or fails validation. */
 export type CommandRegistrationResult = {
   ok: boolean;
   error?: string;
 };
 
+/** Returns true when a command name is owned by built-in OpenClaw command handling. */
 export function isReservedCommandName(name: string): boolean {
   const trimmed = normalizeOptionalLowercaseString(name) ?? "";
   return Boolean(trimmed && getReservedCommands().has(trimmed));
 }
 
+/** Validates user-visible command names before plugin registration accepts them. */
 export function validateCommandName(
   name: string,
   opts?: { allowReservedCommandNames?: boolean },

src/plugins/config-contracts.ts

@@ -1,3 +1,4 @@
+/** Resolves plugin config contract metadata for scanners and secret/config policy checks. */
 import { normalizeSortedUniqueStringEntries } from "@openclaw/normalization-core/string-normalization";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { discoverOpenClawPlugins, type PluginDiscoveryResult } from "./discovery.js";

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

@@ -1,3 +1,4 @@
+/** Tracks the current plugin metadata snapshot for control-plane lookups. */
 import { setCurrentManifestModelIdNormalizationRecords } from "@openclaw/model-catalog-core/provider-model-id-normalization";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import {

src/plugins/hook-runner-global.test.ts

@@ -1,3 +1,4 @@
+/** Verifies global hook runner sequencing, mutation, and error behavior. */
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { createMockPluginRegistry } from "./hooks.test-helpers.js";
 

src/plugins/installed-plugin-index-record-reader.ts

@@ -1,3 +1,4 @@
+/** Reads installed-index records back into manifest registry records. */
 import fs from "node:fs";
 import path from "node:path";
 import { isRecord } from "@openclaw/normalization-core/record-coerce";

src/plugins/installed-plugin-index-records.ts

@@ -1,3 +1,4 @@
+/** Builds and compares installed plugin index records for refresh decisions. */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { PluginInstallRecord } from "../config/types.plugins.js";
 import {

src/plugins/loader-cache-state.test.ts

@@ -1,3 +1,4 @@
+/** Tests plugin loader cache state keys, invalidation, and reset behavior. */
 import { describe, expect, it } from "vitest";
 import { PluginLoaderCacheState, PluginLoadReentryError } from "./loader-cache-state.js";
 

src/plugins/manifest-model-id-normalization.ts

@@ -1,3 +1,4 @@
+/** Applies manifest-declared model-id normalization policies to provider model refs. */
 import {
   collectManifestModelIdNormalizationPolicies,
   normalizeProviderModelIdWithPolicies,

src/plugins/manifest-registry-installed.ts

@@ -1,3 +1,4 @@
+/** Builds manifest registry records from installed plugin index snapshots. */
 import fs from "node:fs";
 import path from "node:path";
 import { isRecord } from "@openclaw/normalization-core/record-coerce";

src/plugins/plugin-control-plane-context.ts

@@ -1,3 +1,4 @@
+/** Tracks control-plane plugin metadata context during registry and status operations. */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { hashJson } from "./installed-plugin-index-hash.js";
 import { resolveInstalledPluginIndexPolicyHash } from "./installed-plugin-index-policy.js";

src/plugins/plugin-lookup-table.ts

@@ -1,3 +1,4 @@
+/** Builds plugin lookup tables keyed by manifest ids, channels, providers, and commands. */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import {
   createGatewayStartupMetadataPluginIdScope,

src/plugins/plugin-version-drift.test.ts

@@ -1,3 +1,4 @@
+/** Tests plugin version drift detection between package, manifest, and install records. */
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/types.js";
 import type { PluginInstallRecord } from "../config/types.plugins.js";

src/plugins/provider-auth-choice-preference.ts

@@ -1,3 +1,4 @@
+/** Resolves preferred provider auth choices from config and plugin metadata. */
 import { normalizeLegacyOnboardAuthChoice } from "../commands/auth-choice-legacy.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { resolveManifestProviderAuthChoice } from "./provider-auth-choices.js";

src/plugins/provider-auth-input.ts

@@ -1,3 +1,4 @@
+/** Normalizes provider auth input metadata collected from plugin setup flows. */
 import {
   normalizeOptionalLowercaseString,
   normalizeStringifiedOptionalString,

src/plugins/provider-oauth-flow.ts

@@ -1,3 +1,4 @@
+/** Coordinates provider OAuth flows exposed by plugin-owned auth integrations. */
 import type { RuntimeEnv } from "../runtime.js";
 import type { WizardPrompter } from "../wizard/prompts.js";
 

src/plugins/provider-runtime.runtime.ts

@@ -1,3 +1,4 @@
+/** Runtime-side provider discovery and provider registration resolution helpers. */
 import { createLazyImportLoader } from "../shared/lazy-promise.js";
 
 type ProviderRuntimeModule = typeof import("./provider-runtime.js");

src/plugins/public-surface-runtime.test.ts

@@ -1,3 +1,4 @@
+/** Verifies public-surface runtime artifact loading for bundled plugins. */
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";

src/plugins/runtime.test.ts

@@ -1,3 +1,4 @@
+/** Covers plugin runtime registration API behavior and registry mutation guards. */
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { isPluginRegistryRetired } from "./registry-lifecycle.js";
 import { createEmptyPluginRegistry } from "./registry.js";

src/plugins/schema-validator.test.ts

@@ -1,3 +1,4 @@
+/** Covers plugin schema validation for manifests and exported config schemas. */
 import { Format } from "typebox/format";
 import { describe, expect, it } from "vitest";
 import { validateJsonSchemaValue } from "./schema-validator.js";

src/plugins/session-entry-slot-keys.ts

@@ -1,3 +1,4 @@
+/** Reserves session-entry keys so plugin extension slots cannot collide with core session state. */
 import type { SessionEntry } from "../config/sessions/types.js";
 
 const SESSION_ENTRY_RESERVED_SLOT_KEY_LIST = [
@@ -134,6 +135,7 @@ type ReservedSessionEntrySlotKey = Extract<
 >;
 type MissingSessionEntryReservedSlotKeys = Exclude<keyof SessionEntry, ReservedSessionEntrySlotKey>;
 type AssertNever<T extends never> = T;
+/** Compile-time guard that every SessionEntry key is excluded from plugin extension slot names. */
 export type _AssertAllSessionEntryKeysAreReserved =
   AssertNever<MissingSessionEntryReservedSlotKeys>;
 

src/plugins/status.test-helpers.ts

@@ -1,3 +1,4 @@
+/** Shared helpers for plugin status tests and installed-index fixture setup. */
 import type { PluginLoadResult } from "./loader.js";
 import type { PluginRecord } from "./registry.js";
 import type { PluginCompatibilityNotice } from "./status.js";