docs: document plugin hook provider helpers

src/plugins/host-hook-attachments.ts

@@ -23,6 +23,7 @@ import type {
 import type { PluginOrigin } from "./plugin-origin.types.js";
 
 const DEFAULT_ATTACHMENT_MAX_BYTES = 25 * 1024 * 1024;
+/** Filesystem adapter used by attachment MIME probes and tests. */
 export const attachmentProbeFs = {
   open: (...args: Parameters<typeof fsPromises.open>) => fsPromises.open(...args),
 };
@@ -95,6 +96,7 @@ async function readMimeSniffBuffer(
   }
 }
 
+/** Resolves channel-specific attachment delivery options from caption format and hints. */
 export function resolveAttachmentDelivery(params: {
   channel: string;
   captionFormat?: PluginSessionAttachmentCaptionFormat;
@@ -218,6 +220,7 @@ function normalizeOptionalThreadId(value: unknown): string | number | undefined
   return normalizeOptionalString(value);
 }
 
+/** Resolves the thread id used when delivering a plugin session attachment. */
 export function resolveSessionAttachmentThreadId(params: {
   deliveryThreadId?: unknown;
   explicitThreadId?: unknown;
@@ -232,6 +235,7 @@ export function resolveSessionAttachmentThreadId(params: {
   );
 }
 
+/** Sends a bundled-plugin session attachment through the session's active delivery route. */
 export async function sendPluginSessionAttachment(
   params: PluginSessionAttachmentParams & { config?: OpenClawConfig; origin?: PluginOrigin },
 ): Promise<PluginSessionAttachmentResult> {

src/plugins/host-hook-turn-types.ts

@@ -1,7 +1,9 @@
 import type { PluginJsonValue } from "./host-hook-json.js";
 
+/** Placement for context injected into the next agent turn. */
 export type PluginNextTurnInjectionPlacement = "prepend_context" | "append_context";
 
+/** Plugin request to inject text into the next turn for a session. */
 export type PluginNextTurnInjection = {
   sessionKey: string;
   text: string;
@@ -11,6 +13,7 @@ export type PluginNextTurnInjection = {
   metadata?: PluginJsonValue;
 };
 
+/** Stored next-turn injection after session/plugin metadata is attached. */
 export type PluginNextTurnInjectionRecord = Omit<PluginNextTurnInjection, "sessionKey"> & {
   id: string;
   pluginId: string;
@@ -19,29 +22,34 @@ export type PluginNextTurnInjectionRecord = Omit<PluginNextTurnInjection, "sessi
   placement: PluginNextTurnInjectionPlacement;
 };
 
+/** Result returned after enqueueing a next-turn injection. */
 export type PluginNextTurnInjectionEnqueueResult = {
   enqueued: boolean;
   id: string;
   sessionKey: string;
 };
 
+/** Event passed to plugins before an agent turn is prepared. */
 export type PluginAgentTurnPrepareEvent = {
   prompt: string;
   messages: unknown[];
   queuedInjections: PluginNextTurnInjectionRecord[];
 };
 
+/** Plugin contribution to prepend or append context for a prepared agent turn. */
 export type PluginAgentTurnPrepareResult = {
   prependContext?: string;
   appendContext?: string;
 };
 
+/** Event passed to plugins that contribute heartbeat prompt context. */
 export type PluginHeartbeatPromptContributionEvent = {
   sessionKey?: string;
   agentId?: string;
   heartbeatName?: string;
 };
 
+/** Plugin contribution to heartbeat prompt context. */
 export type PluginHeartbeatPromptContributionResult = {
   prependContext?: string;
   appendContext?: string;

src/plugins/install-overrides.ts

@@ -2,9 +2,12 @@ import path from "node:path";
 import { parseRegistryNpmSpec } from "../infra/npm-registry-spec.js";
 import { isRecord, resolveUserPath } from "../utils.js";
 
+/** Env var containing JSON plugin install override specs. */
 export const PLUGIN_INSTALL_OVERRIDES_ENV = "OPENCLAW_PLUGIN_INSTALL_OVERRIDES";
+/** Env var gate that must be enabled before install overrides are honored. */
 export const ALLOW_PLUGIN_INSTALL_OVERRIDES_ENV = "OPENCLAW_ALLOW_PLUGIN_INSTALL_OVERRIDES";
 
+/** Parsed plugin install override for tests and maintainer repair flows. */
 export type PluginInstallOverride =
   | {
       kind: "npm";
@@ -40,6 +43,7 @@ function parseOverrideSpec(raw: string): PluginInstallOverride | null {
   return null;
 }
 
+/** Resolves a gated plugin install override from environment configuration. */
 export function resolvePluginInstallOverride(params: {
   pluginId: string;
   env?: NodeJS.ProcessEnv;

src/plugins/loader-provenance.ts

@@ -19,6 +19,7 @@ type InstallTrackingRule = {
   matcher: PathMatcher;
 };
 
+/** Provenance lookup for trusted plugin load paths and install records. */
 export type PluginProvenanceIndex = {
   loadPathMatcher: PathMatcher;
   installRules: Map<string, InstallTrackingRule>;
@@ -65,6 +66,7 @@ function matchesPathMatcher(matcher: PathMatcher, sourcePath: string): boolean {
   return matcher.dirs.some((dirPath) => isPathInside(dirPath, sourcePath));
 }
 
+/** Builds provenance matchers from configured load paths and install records. */
 export function buildProvenanceIndex(params: {
   normalizedLoadPaths: string[];
   env: NodeJS.ProcessEnv;
@@ -175,6 +177,7 @@ function resolveCandidateDuplicateRank(params: {
   return 5;
 }
 
+/** Orders duplicate plugin candidates by configured, installed, bundled, then workspace trust. */
 export function compareDuplicateCandidateOrder(params: {
   left: PluginCandidate;
   right: PluginCandidate;
@@ -203,6 +206,7 @@ export function compareDuplicateCandidateOrder(params: {
   );
 }
 
+/** Warns when an open plugin allowlist may auto-load non-bundled plugins. */
 export function warnWhenAllowlistIsOpen(params: {
   emitWarning: boolean;
   logger: PluginLogger;
@@ -241,6 +245,7 @@ export function warnWhenAllowlistIsOpen(params: {
   );
 }
 
+/** Adds diagnostics for loaded plugins without install or load-path provenance. */
 export function warnAboutUntrackedLoadedPlugins(params: {
   registry: PluginRegistry;
   provenance: PluginProvenanceIndex;

src/plugins/provider-public-artifacts.ts

@@ -17,6 +17,7 @@ import { loadBundledPluginPublicArtifactModuleSync } from "./public-surface-load
 const PROVIDER_POLICY_ARTIFACT_CANDIDATES = ["provider-policy-api.js"] as const;
 const providerPolicySurfaceByPluginId = new Map<string, BundledProviderPolicySurface | null>();
 
+/** Provider policy hooks loaded from bundled plugin public artifacts. */
 export type BundledProviderPolicySurface = {
   normalizeConfig?: (ctx: ProviderNormalizeConfigContext) => ModelProviderConfig | null | undefined;
   applyConfigDefaults?: (
@@ -121,6 +122,7 @@ function pluginOwnsProviderPolicyRef(
   return false;
 }
 
+/** Resolves provider policy hooks for a bundled provider or its owning plugin. */
 export function resolveBundledProviderPolicySurface(
   providerId: string,
   options: { manifestRegistry?: Pick<PluginManifestRegistry, "plugins"> } = {},

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

@@ -11,6 +11,7 @@ import {
   createPluginRuntimeLoaderLogger,
 } from "./runtime/load-context.js";
 
+/** Shared options for resolving plugin-backed web providers. */
 export type ResolvePluginWebProvidersParams = {
   config?: PluginLoadOptions["config"];
   workspaceDir?: string;
@@ -144,6 +145,7 @@ function resolveRuntimeRegistryWebProviders<TEntry>(params: {
   };
 }
 
+/** Resolves plugin web providers from setup, active runtime, or a scoped load. */
 export function resolvePluginWebProviders<TEntry>(
   params: ResolvePluginWebProvidersParams,
   deps: ResolveWebProviderRuntimeDeps<TEntry>,
@@ -236,6 +238,7 @@ export function resolvePluginWebProviders<TEntry>(
   });
 }
 
+/** Resolves web providers from the active runtime registry before falling back to plugin loading. */
 export function resolveRuntimeWebProviders<TEntry>(
   params: Omit<ResolvePluginWebProvidersParams, "activate" | "cache" | "mode">,
   deps: ResolveWebProviderRuntimeDeps<TEntry>,