From 8975f75c8b4802d92bc034d72457da925563d475 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 04:22:45 -0400
Subject: [PATCH] docs: document plugin public surface helpers

---
 src/plugins/bundled-package-channel-metadata.test.ts | 1 +
 src/plugins/cli-backends.runtime.ts                  | 1 +
 src/plugins/commands.test.ts                         | 1 +
 src/plugins/document-extractors.runtime.test.ts      | 1 +
 src/plugins/gateway-startup-speech-providers.ts      | 1 +
 src/plugins/hooks.before-install.test.ts             | 1 +
 src/plugins/host-hook-scheduled-turns.ts             | 1 +
 src/plugins/host-hook-state.ts                       | 1 +
 src/plugins/install.test.ts                          | 1 +
 src/plugins/manifest-contract-runtime.ts             | 1 +
 src/plugins/marketplace.ts                           | 1 +
 src/plugins/memory-runtime.ts                        | 1 +
 src/plugins/migration-provider-runtime.ts            | 1 +
 src/plugins/npm-project-roots.ts                     | 1 +
 src/plugins/plugin-graceful-init-failure.test.ts     | 1 +
 src/plugins/plugin-metadata-snapshot.memo.test.ts    | 1 +
 src/plugins/provider-auth-choices.ts                 | 1 +
 src/plugins/provider-contract-public-artifacts.ts    | 1 +
 src/plugins/public-surface-loader.ts                 | 1 +
 src/plugins/registry.runtime-config.test.ts          | 1 +
 src/plugins/startup-trace-segment.ts                 | 1 +
 src/plugins/toggle-config.ts                         | 1 +
 src/plugins/tool-descriptor-cache.test.ts            | 1 +
 src/plugins/web-fetch-providers.runtime.test.ts      | 1 +
 24 files changed, 24 insertions(+)

diff --git a/src/plugins/bundled-package-channel-metadata.test.ts b/src/plugins/bundled-package-channel-metadata.test.ts
index 410dcc82755c..ecb5292eeb37 100644
--- a/src/plugins/bundled-package-channel-metadata.test.ts
+++ b/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";
diff --git a/src/plugins/cli-backends.runtime.ts b/src/plugins/cli-backends.runtime.ts
index af287d73cdd7..c62d6e9c7d6f 100644
--- a/src/plugins/cli-backends.runtime.ts
+++ b/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";
 
diff --git a/src/plugins/commands.test.ts b/src/plugins/commands.test.ts
index 09b9e69a83e9..88902f37efc7 100644
--- a/src/plugins/commands.test.ts
+++ b/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";
diff --git a/src/plugins/document-extractors.runtime.test.ts b/src/plugins/document-extractors.runtime.test.ts
index 2a472a8d5da2..30fa3ed312ab 100644
--- a/src/plugins/document-extractors.runtime.test.ts
+++ b/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";
diff --git a/src/plugins/gateway-startup-speech-providers.ts b/src/plugins/gateway-startup-speech-providers.ts
index 5b8175a0cc7f..a6d90011bc22 100644
--- a/src/plugins/gateway-startup-speech-providers.ts
+++ b/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";
diff --git a/src/plugins/hooks.before-install.test.ts b/src/plugins/hooks.before-install.test.ts
index be281ef9cebd..0f4c02fd991c 100644
--- a/src/plugins/hooks.before-install.test.ts
+++ b/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";
diff --git a/src/plugins/host-hook-scheduled-turns.ts b/src/plugins/host-hook-scheduled-turns.ts
index 4a7fec8b05b2..616eee91ed49 100644
--- a/src/plugins/host-hook-scheduled-turns.ts
+++ b/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,
diff --git a/src/plugins/host-hook-state.ts b/src/plugins/host-hook-state.ts
index b8170543742f..031215a5157b 100644
--- a/src/plugins/host-hook-state.ts
+++ b/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,
diff --git a/src/plugins/install.test.ts b/src/plugins/install.test.ts
index d4bc5a2953ce..d8b19c62b0c1 100644
--- a/src/plugins/install.test.ts
+++ b/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";
diff --git a/src/plugins/manifest-contract-runtime.ts b/src/plugins/manifest-contract-runtime.ts
index e20d09762e0d..5aa1c9963f55 100644
--- a/src/plugins/manifest-contract-runtime.ts
+++ b/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 {
diff --git a/src/plugins/marketplace.ts b/src/plugins/marketplace.ts
index 4af62bda818a..2422e427c2e6 100644
--- a/src/plugins/marketplace.ts
+++ b/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";
diff --git a/src/plugins/memory-runtime.ts b/src/plugins/memory-runtime.ts
index 0a7811a8c996..831e35c993fb 100644
--- a/src/plugins/memory-runtime.ts
+++ b/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";
diff --git a/src/plugins/migration-provider-runtime.ts b/src/plugins/migration-provider-runtime.ts
index 91a67619f507..62d2129912e4 100644
--- a/src/plugins/migration-provider-runtime.ts
+++ b/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 {
diff --git a/src/plugins/npm-project-roots.ts b/src/plugins/npm-project-roots.ts
index dad539b2afd0..60aea85934a5 100644
--- a/src/plugins/npm-project-roots.ts
+++ b/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";
diff --git a/src/plugins/plugin-graceful-init-failure.test.ts b/src/plugins/plugin-graceful-init-failure.test.ts
index b31acbf1e59d..0ccaa3bd21dc 100644
--- a/src/plugins/plugin-graceful-init-failure.test.ts
+++ b/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";
diff --git a/src/plugins/plugin-metadata-snapshot.memo.test.ts b/src/plugins/plugin-metadata-snapshot.memo.test.ts
index 65feefb130f8..3b9165fead1d 100644
--- a/src/plugins/plugin-metadata-snapshot.memo.test.ts
+++ b/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";
diff --git a/src/plugins/provider-auth-choices.ts b/src/plugins/provider-auth-choices.ts
index bbd32636d6c6..506da83dbc5d 100644
--- a/src/plugins/provider-auth-choices.ts
+++ b/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";
diff --git a/src/plugins/provider-contract-public-artifacts.ts b/src/plugins/provider-contract-public-artifacts.ts
index 4f7faa64c8ea..f08c50c0d0c7 100644
--- a/src/plugins/provider-contract-public-artifacts.ts
+++ b/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";
diff --git a/src/plugins/public-surface-loader.ts b/src/plugins/public-surface-loader.ts
index 224330589289..d7538d1fc8a4 100644
--- a/src/plugins/public-surface-loader.ts
+++ b/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";
diff --git a/src/plugins/registry.runtime-config.test.ts b/src/plugins/registry.runtime-config.test.ts
index c120aa1403e3..bfed6eba9d05 100644
--- a/src/plugins/registry.runtime-config.test.ts
+++ b/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";
diff --git a/src/plugins/startup-trace-segment.ts b/src/plugins/startup-trace-segment.ts
index a6e478b4af3f..551443a90341 100644
--- a/src/plugins/startup-trace-segment.ts
+++ b/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 {
diff --git a/src/plugins/toggle-config.ts b/src/plugins/toggle-config.ts
index 00d526829a89..78e2b4fed0a6 100644
--- a/src/plugins/toggle-config.ts
+++ b/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";
 
diff --git a/src/plugins/tool-descriptor-cache.test.ts b/src/plugins/tool-descriptor-cache.test.ts
index 19ef35d8cf51..bd4e77404abb 100644
--- a/src/plugins/tool-descriptor-cache.test.ts
+++ b/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(() => ({
diff --git a/src/plugins/web-fetch-providers.runtime.test.ts b/src/plugins/web-fetch-providers.runtime.test.ts
index 49b6f8be208e..a00924bb5360 100644
--- a/src/plugins/web-fetch-providers.runtime.test.ts
+++ b/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";