docs: document plugin public surface helpers

src/plugins/bundled-package-channel-metadata.test.ts

@@ -1,3 +1,4 @@
+// Verifies bundled package channel metadata stays aligned with catalogs.
 import fs from "node:fs";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";

src/plugins/cli-backends.runtime.ts

@@ -1,3 +1,4 @@
+// Runtime bridge for plugin-provided CLI backends.
 import { getActiveRuntimePluginRegistry } from "./active-runtime-registry.js";
 import type { CliBackendPlugin } from "./cli-backend.types.js";
 

src/plugins/commands.test.ts

@@ -1,3 +1,4 @@
+// Covers plugin CLI command behavior and output paths.
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { createChannelTestPluginBase, createTestRegistry } from "../test-utils/channel-plugins.js";

src/plugins/document-extractors.runtime.test.ts

@@ -1,3 +1,4 @@
+// Covers document extractor runtime hooks supplied by plugins.
 import { describe, expect, it, vi } from "vitest";
 import { resolvePluginDocumentExtractors } from "./document-extractors.runtime.js";
 import { loadPluginMetadataSnapshot } from "./plugin-metadata-snapshot.js";

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

@@ -1,3 +1,4 @@
+// Collects startup speech provider metadata from plugin manifests.
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import type { OpenClawConfig } from "../config/types.openclaw.js";

src/plugins/hooks.before-install.test.ts

@@ -1,3 +1,4 @@
+// Covers hook behavior before plugin install state exists.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { createHookRunner } from "./hooks.js";
 import { addTestHook } from "./hooks.test-helpers.js";

src/plugins/host-hook-scheduled-turns.ts

@@ -1,3 +1,4 @@
+// Schedules host hook turns requested by plugin hook contracts.
 import { randomUUID } from "node:crypto";
 import {
   resolveExpiresAtMsFromDurationMs,

src/plugins/host-hook-state.ts

@@ -1,3 +1,4 @@
+// Tracks host hook state and scheduled turn identifiers.
 import { randomUUID } from "node:crypto";
 import {
   normalizeLowercaseStringOrEmpty,

src/plugins/install.test.ts

@@ -1,3 +1,4 @@
+// Covers plugin install flows, manifests, and install records.
 import fs from "node:fs";
 import fsPromises from "node:fs/promises";
 import path from "node:path";

src/plugins/manifest-contract-runtime.ts

@@ -1,3 +1,4 @@
+// Resolves manifest contracts into runtime-facing plugin capabilities.
 import { sortUniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import {

src/plugins/marketplace.ts

@@ -1,3 +1,4 @@
+// Loads plugin marketplace entries for install and discovery flows.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";

src/plugins/memory-runtime.ts

@@ -1,3 +1,4 @@
+// Runtime bridge for plugin-owned memory hooks and state.
 import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { resolveUserPath } from "../utils.js";

src/plugins/migration-provider-runtime.ts

@@ -1,3 +1,4 @@
+// Runtime bridge for plugin-provided migration hooks.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { getLoadedRuntimePluginRegistry } from "./active-runtime-registry.js";
 import {

src/plugins/npm-project-roots.ts

@@ -1,3 +1,4 @@
+// Resolves npm project roots for plugin package inspection.
 import fs from "node:fs";
 import fsp from "node:fs/promises";
 import path from "node:path";

src/plugins/plugin-graceful-init-failure.test.ts

@@ -1,3 +1,4 @@
+// Verifies graceful plugin init failure handling and reporting.
 import fs from "node:fs";
 import path from "node:path";
 import { afterAll, describe, expect, it } from "vitest";

src/plugins/plugin-metadata-snapshot.memo.test.ts

@@ -1,3 +1,4 @@
+// Verifies plugin metadata snapshot memoization behavior.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";

src/plugins/provider-auth-choices.ts

@@ -1,3 +1,4 @@
+// Builds provider auth choice lists from plugin setup metadata.
 import { sanitizeForLog } from "../../packages/terminal-core/src/ansi.js";
 import { resolveProviderIdForAuth } from "../agents/provider-auth-aliases.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";

src/plugins/provider-contract-public-artifacts.ts

@@ -1,3 +1,4 @@
+// Extracts provider contract public artifacts from plugin manifests.
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
 import { sortUniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import { loadBundledPluginPublicArtifactModuleSync } from "./public-surface-loader.js";

src/plugins/public-surface-loader.ts

@@ -1,3 +1,4 @@
+// Loads documented plugin public surfaces while preserving lazy boundaries.
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";

src/plugins/registry.runtime-config.test.ts

@@ -1,3 +1,4 @@
+// Verifies plugin registry behavior with runtime config inputs.
 import { describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { createPluginRecord } from "./loader-records.js";

src/plugins/startup-trace-segment.ts

@@ -1,3 +1,4 @@
+// Sanitizes plugin startup trace segments for diagnostic labels.
 const SAFE_STARTUP_TRACE_SEGMENT_CHAR = /^[A-Za-z0-9_-]$/u;
 
 export function encodeStartupTraceSegment(value: string): string {

src/plugins/toggle-config.ts

@@ -1,3 +1,4 @@
+// Toggles plugin enablement config for channels and agents.
 import { normalizeChatChannelId } from "../channels/ids.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 

src/plugins/tool-descriptor-cache.test.ts

@@ -1,3 +1,4 @@
+// Covers plugin tool descriptor cache lifecycle and invalidation.
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 const hoisted = vi.hoisted(() => ({

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

@@ -1,3 +1,4 @@
+// Covers web fetch provider runtime hooks supplied by plugins.
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { createEmptyPluginRegistry } from "./registry-empty.js";