From feffb6d02ff8cda2bedbc12c06f27fd7b67acee0 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 19:16:24 -0400
Subject: [PATCH] docs: document plugin sdk runtime helpers

---
 src/plugin-sdk/agent-media-payload.ts                | 1 +
 src/plugin-sdk/allow-from.ts                         | 1 +
 src/plugin-sdk/anthropic-vertex-auth-presence.ts     | 1 +
 src/plugin-sdk/api-baseline.ts                       | 1 +
 src/plugin-sdk/approval-auth-helpers.ts              | 1 +
 src/plugin-sdk/approval-client-helpers.ts            | 1 +
 src/plugin-sdk/approval-renderers.ts                 | 1 +
 src/plugin-sdk/boolean-param.ts                      | 1 +
 src/plugin-sdk/browser-control-auth.ts               | 1 +
 src/plugin-sdk/channel-actions.ts                    | 1 +
 src/plugin-sdk/channel-ingress.ts                    | 1 +
 src/plugin-sdk/channel-send-result.ts                | 1 +
 src/plugin-sdk/core.ts                               | 1 +
 src/plugin-sdk/gateway-method-runtime.ts             | 1 +
 src/plugin-sdk/keyed-async-queue.ts                  | 1 +
 src/plugin-sdk/memory-core-host-engine-embeddings.ts | 1 +
 src/plugin-sdk/opencode.ts                           | 1 +
 src/plugin-sdk/persistent-dedupe.ts                  | 1 +
 src/plugin-sdk/provider-auth.ts                      | 1 +
 src/plugin-sdk/provider-enable-config.ts             | 1 +
 src/plugin-sdk/provider-selection-runtime.ts         | 1 +
 src/plugin-sdk/qa-channel-protocol.ts                | 1 +
 src/plugin-sdk/qa-runner-runtime.ts                  | 1 +
 src/plugin-sdk/reply-payload.ts                      | 1 +
 src/plugin-sdk/session-transcript-hit.ts             | 1 +
 src/plugin-sdk/session-visibility.ts                 | 1 +
 src/plugin-sdk/telegram-account.ts                   | 1 +
 src/plugin-sdk/tool-payload.ts                       | 1 +
 src/plugin-sdk/tool-send.ts                          | 1 +
 src/plugin-sdk/tts-runtime.types.ts                  | 1 +
 src/plugin-sdk/webhook-request-guards.ts             | 1 +
 src/plugin-sdk/webhook-targets.ts                    | 1 +
 32 files changed, 32 insertions(+)

diff --git a/src/plugin-sdk/agent-media-payload.ts b/src/plugin-sdk/agent-media-payload.ts
index 09f7f1fb4ba..e19811c798b 100644
--- a/src/plugin-sdk/agent-media-payload.ts
+++ b/src/plugin-sdk/agent-media-payload.ts
@@ -1,3 +1,4 @@
+// Agent media payload exports expose media roots and loaders for plugin-facing agent payloads.
 export { getAgentScopedMediaLocalRoots } from "../media/local-roots.js";
 
 export type AgentMediaPayload = {
diff --git a/src/plugin-sdk/allow-from.ts b/src/plugin-sdk/allow-from.ts
index 5b29df20c71..f7ad2804481 100644
--- a/src/plugin-sdk/allow-from.ts
+++ b/src/plugin-sdk/allow-from.ts
@@ -1,3 +1,4 @@
+// Allow-from helpers parse and match plugin channel allowlist entries.
 import { normalizeOptionalLowercaseString } from "../../packages/normalization-core/src/string-coerce.js";
 import { normalizeStringEntries } from "../../packages/normalization-core/src/string-normalization.js";
 import { isAllowedParsedChatSender as isAllowedParsedChatSenderShared } from "../channels/plugins/chat-target-prefixes.js";
diff --git a/src/plugin-sdk/anthropic-vertex-auth-presence.ts b/src/plugin-sdk/anthropic-vertex-auth-presence.ts
index a20980a1573..38a23b63c50 100644
--- a/src/plugin-sdk/anthropic-vertex-auth-presence.ts
+++ b/src/plugin-sdk/anthropic-vertex-auth-presence.ts
@@ -1,3 +1,4 @@
+// Anthropic Vertex auth helpers detect local credential presence for provider setup flows.
 import { readFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { join } from "node:path";
diff --git a/src/plugin-sdk/api-baseline.ts b/src/plugin-sdk/api-baseline.ts
index 49e7633a745..7c5c83e994d 100644
--- a/src/plugin-sdk/api-baseline.ts
+++ b/src/plugin-sdk/api-baseline.ts
@@ -1,3 +1,4 @@
+// API baseline helpers hash public SDK exports for contract drift checks.
 import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
diff --git a/src/plugin-sdk/approval-auth-helpers.ts b/src/plugin-sdk/approval-auth-helpers.ts
index 36a442214ed..058f97ca0da 100644
--- a/src/plugin-sdk/approval-auth-helpers.ts
+++ b/src/plugin-sdk/approval-auth-helpers.ts
@@ -1,3 +1,4 @@
+// Approval auth helpers resolve actor and channel identity for approval requests.
 import { normalizeOptionalString } from "../../packages/normalization-core/src/string-coerce.js";
 import type { OpenClawConfig } from "./config-runtime.js";
 
diff --git a/src/plugin-sdk/approval-client-helpers.ts b/src/plugin-sdk/approval-client-helpers.ts
index 33715d7b209..ec91aad8a26 100644
--- a/src/plugin-sdk/approval-client-helpers.ts
+++ b/src/plugin-sdk/approval-client-helpers.ts
@@ -1,3 +1,4 @@
+// Approval client helpers build approval URLs and status payloads for plugin clients.
 import {
   normalizeOptionalLowercaseString,
   normalizeOptionalString,
diff --git a/src/plugin-sdk/approval-renderers.ts b/src/plugin-sdk/approval-renderers.ts
index 23c2475f092..f3c1dbfbffd 100644
--- a/src/plugin-sdk/approval-renderers.ts
+++ b/src/plugin-sdk/approval-renderers.ts
@@ -1,3 +1,4 @@
+// Approval renderer helpers convert approval request data into channel-safe display text.
 import { normalizeOptionalString } from "../../packages/normalization-core/src/string-coerce.js";
 import {
   buildApprovalPresentation,
diff --git a/src/plugin-sdk/boolean-param.ts b/src/plugin-sdk/boolean-param.ts
index 25bf91d1c28..2e95178aeea 100644
--- a/src/plugin-sdk/boolean-param.ts
+++ b/src/plugin-sdk/boolean-param.ts
@@ -1,3 +1,4 @@
+// Boolean parameter helpers parse plugin-facing string flags into stable booleans.
 import { normalizeOptionalLowercaseString } from "../../packages/normalization-core/src/string-coerce.js";
 
 /** Read loose boolean params from tool input that may arrive as booleans or "true"/"false" strings. */
diff --git a/src/plugin-sdk/browser-control-auth.ts b/src/plugin-sdk/browser-control-auth.ts
index da37a1a6967..da52be9b191 100644
--- a/src/plugin-sdk/browser-control-auth.ts
+++ b/src/plugin-sdk/browser-control-auth.ts
@@ -1,3 +1,4 @@
+// Browser control auth helpers resolve plugin browser credentials from OpenClaw config.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { loadBundledPluginPublicSurfaceModuleSync } from "./facade-loader.js";
 
diff --git a/src/plugin-sdk/channel-actions.ts b/src/plugin-sdk/channel-actions.ts
index 6a6cb0a341d..cfd0b6972f5 100644
--- a/src/plugin-sdk/channel-actions.ts
+++ b/src/plugin-sdk/channel-actions.ts
@@ -1,3 +1,4 @@
+// Channel action schemas describe plugin-declared actions available through channel UIs.
 import { Type } from "typebox";
 import type { TSchema } from "typebox";
 import { stringEnum as createStringEnum } from "../agents/schema/typebox.js";
diff --git a/src/plugin-sdk/channel-ingress.ts b/src/plugin-sdk/channel-ingress.ts
index 036b5a129d2..866b41dfe19 100644
--- a/src/plugin-sdk/channel-ingress.ts
+++ b/src/plugin-sdk/channel-ingress.ts
@@ -1,3 +1,4 @@
+// Channel ingress helpers normalize inbound channel messages before agent routing.
 import { normalizeStringEntries } from "../../packages/normalization-core/src/string-normalization.js";
 import {
   decideChannelIngress,
diff --git a/src/plugin-sdk/channel-send-result.ts b/src/plugin-sdk/channel-send-result.ts
index d880c6cdc6b..c8957b0f066 100644
--- a/src/plugin-sdk/channel-send-result.ts
+++ b/src/plugin-sdk/channel-send-result.ts
@@ -1,3 +1,4 @@
+// Channel send result contracts normalize outbound delivery outcomes from channel plugins.
 import type { ChannelOutboundAdapter } from "../channels/plugins/outbound.types.js";
 import type { ChannelPollResult } from "../channels/plugins/types.public.js";
 import type { OutboundDeliveryResult } from "../infra/outbound/deliver.js";
diff --git a/src/plugin-sdk/core.ts b/src/plugin-sdk/core.ts
index 080f8b79178..27eff633f28 100644
--- a/src/plugin-sdk/core.ts
+++ b/src/plugin-sdk/core.ts
@@ -1,3 +1,4 @@
+// Core SDK contracts expose stable identifiers, manifests, and shared plugin metadata types.
 import { normalizeLowercaseStringOrEmpty } from "../../packages/normalization-core/src/string-coerce.js";
 import type { ResolvedConfiguredAcpBinding } from "../acp/persistent-bindings.types.js";
 import { buildChatChannelMetaById } from "../channels/chat-meta-shared.js";
diff --git a/src/plugin-sdk/gateway-method-runtime.ts b/src/plugin-sdk/gateway-method-runtime.ts
index 0afe8804280..10983f688bb 100644
--- a/src/plugin-sdk/gateway-method-runtime.ts
+++ b/src/plugin-sdk/gateway-method-runtime.ts
@@ -1,3 +1,4 @@
+// Gateway method runtime helpers dispatch plugin calls through the in-process gateway.
 import { dispatchGatewayMethodInProcessRaw } from "../gateway/server-plugins.js";
 import { getPluginRuntimeGatewayRequestScope } from "../plugins/runtime/gateway-request-scope.js";
 
diff --git a/src/plugin-sdk/keyed-async-queue.ts b/src/plugin-sdk/keyed-async-queue.ts
index ea33e6f03ce..97228eeeeb3 100644
--- a/src/plugin-sdk/keyed-async-queue.ts
+++ b/src/plugin-sdk/keyed-async-queue.ts
@@ -1,3 +1,4 @@
+// Keyed async queue helpers serialize async plugin work by key while preserving parallelism.
 export type KeyedAsyncQueueHooks = {
   onEnqueue?: () => void;
   onSettle?: () => void;
diff --git a/src/plugin-sdk/memory-core-host-engine-embeddings.ts b/src/plugin-sdk/memory-core-host-engine-embeddings.ts
index 8af451b510e..461e55ba3e9 100644
--- a/src/plugin-sdk/memory-core-host-engine-embeddings.ts
+++ b/src/plugin-sdk/memory-core-host-engine-embeddings.ts
@@ -1,3 +1,4 @@
+// Memory core host embedding exports expose host embedding primitives to the memory plugin.
 export {
   applyEmbeddingBatchOutputLine,
   buildBatchHeaders,
diff --git a/src/plugin-sdk/opencode.ts b/src/plugin-sdk/opencode.ts
index 238a5bc0ce9..78ee570c3ec 100644
--- a/src/plugin-sdk/opencode.ts
+++ b/src/plugin-sdk/opencode.ts
@@ -1,3 +1,4 @@
+// OpenCode provider helpers expose auth and model defaults for the OpenCode-compatible plugin.
 import { createProviderApiKeyAuthMethod, type OpenClawConfig } from "./provider-auth-api-key.js";
 
 export { applyOpencodeZenModelDefault, OPENCODE_ZEN_DEFAULT_MODEL } from "./provider-onboard.js";
diff --git a/src/plugin-sdk/persistent-dedupe.ts b/src/plugin-sdk/persistent-dedupe.ts
index f81d08e97d9..0e1685b3bb5 100644
--- a/src/plugin-sdk/persistent-dedupe.ts
+++ b/src/plugin-sdk/persistent-dedupe.ts
@@ -1,3 +1,4 @@
+// Persistent dedupe helpers give plugins bounded replay protection across process restarts.
 import { createDedupeCache } from "../infra/dedupe.js";
 import { resolveNonNegativeIntegerOption } from "../infra/numeric-options.js";
 import type { FileLockOptions } from "./file-lock.js";
diff --git a/src/plugin-sdk/provider-auth.ts b/src/plugin-sdk/provider-auth.ts
index daf7da930d6..2b37d99ef71 100644
--- a/src/plugin-sdk/provider-auth.ts
+++ b/src/plugin-sdk/provider-auth.ts
@@ -1,3 +1,4 @@
+// Provider auth helpers define auth methods, credential resolution, and setup status contracts.
 import path from "node:path";
 import {
   asDateTimestampMs,
diff --git a/src/plugin-sdk/provider-enable-config.ts b/src/plugin-sdk/provider-enable-config.ts
index 7ec974f16b1..e6629feedf7 100644
--- a/src/plugin-sdk/provider-enable-config.ts
+++ b/src/plugin-sdk/provider-enable-config.ts
@@ -1,3 +1,4 @@
+// Provider enable config helpers update provider allowlists and config enablement state.
 import { ensurePluginAllowlisted } from "../config/plugins-allowlist.js";
 
 type ProviderPluginConfig = {
diff --git a/src/plugin-sdk/provider-selection-runtime.ts b/src/plugin-sdk/provider-selection-runtime.ts
index d9368a4a152..49211ad0a16 100644
--- a/src/plugin-sdk/provider-selection-runtime.ts
+++ b/src/plugin-sdk/provider-selection-runtime.ts
@@ -1,3 +1,4 @@
+// Provider selection runtime helpers resolve plugin/provider choices from config and CLI input.
 import { normalizeOptionalString } from "../../packages/normalization-core/src/string-coerce.js";
 
 export type AutoSelectableProvider = {
diff --git a/src/plugin-sdk/qa-channel-protocol.ts b/src/plugin-sdk/qa-channel-protocol.ts
index ccbda1ccf8a..a52d28900d0 100644
--- a/src/plugin-sdk/qa-channel-protocol.ts
+++ b/src/plugin-sdk/qa-channel-protocol.ts
@@ -1,3 +1,4 @@
+// QA channel protocol helpers validate synthetic channel messages used by QA plugins.
 import { isRecord } from "../../packages/normalization-core/src/record-coerce.js";
 
 export type QaBusConversationKind = "direct" | "channel" | "group";
diff --git a/src/plugin-sdk/qa-runner-runtime.ts b/src/plugin-sdk/qa-runner-runtime.ts
index 432e3c79e03..6ce12ff6a05 100644
--- a/src/plugin-sdk/qa-runner-runtime.ts
+++ b/src/plugin-sdk/qa-runner-runtime.ts
@@ -1,3 +1,4 @@
+// QA runner runtime helpers expose plugin QA scenarios through the CLI command surface.
 import type { Command } from "commander";
 import type { PluginManifestRecord } from "../plugins/manifest-registry.js";
 import { loadPluginManifestRegistry } from "../plugins/manifest-registry.js";
diff --git a/src/plugin-sdk/reply-payload.ts b/src/plugin-sdk/reply-payload.ts
index bc7f6834382..2f262ce0917 100644
--- a/src/plugin-sdk/reply-payload.ts
+++ b/src/plugin-sdk/reply-payload.ts
@@ -1,3 +1,4 @@
+// Reply payload helpers normalize plugin reply targets, text, media, and approval metadata.
 import { normalizeLowercaseStringOrEmpty } from "../../packages/normalization-core/src/string-coerce.js";
 import { normalizeStringEntries } from "../../packages/normalization-core/src/string-normalization.js";
 import type { ReplyPayload as InternalReplyPayload } from "../auto-reply/reply-payload.js";
diff --git a/src/plugin-sdk/session-transcript-hit.ts b/src/plugin-sdk/session-transcript-hit.ts
index a4a9025a592..83088b2145d 100644
--- a/src/plugin-sdk/session-transcript-hit.ts
+++ b/src/plugin-sdk/session-transcript-hit.ts
@@ -1,3 +1,4 @@
+// Session transcript hit helpers describe and load matched transcript snippets for plugins.
 import path from "node:path";
 import { normalizeOptionalString } from "../../packages/normalization-core/src/string-coerce.js";
 import { uniqueStrings } from "../../packages/normalization-core/src/string-normalization.js";
diff --git a/src/plugin-sdk/session-visibility.ts b/src/plugin-sdk/session-visibility.ts
index a0df7456b31..572f9353c2b 100644
--- a/src/plugin-sdk/session-visibility.ts
+++ b/src/plugin-sdk/session-visibility.ts
@@ -1,3 +1,4 @@
+// Session visibility helpers decide which plugin sessions appear in user-facing lists.
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalString,
diff --git a/src/plugin-sdk/telegram-account.ts b/src/plugin-sdk/telegram-account.ts
index aee0d84ccf7..bed45592cf9 100644
--- a/src/plugin-sdk/telegram-account.ts
+++ b/src/plugin-sdk/telegram-account.ts
@@ -1,3 +1,4 @@
+// Telegram account helpers resolve Telegram plugin account config and display metadata.
 import type { OpenClawConfig } from "./config-types.js";
 import { loadBundledPluginPublicSurfaceModuleSync } from "./facade-loader.js";
 
diff --git a/src/plugin-sdk/tool-payload.ts b/src/plugin-sdk/tool-payload.ts
index c87e7bfff6e..0d01a00be13 100644
--- a/src/plugin-sdk/tool-payload.ts
+++ b/src/plugin-sdk/tool-payload.ts
@@ -1,3 +1,4 @@
+// Tool payload helpers normalize provider tool-call schemas and compatibility payloads.
 import {
   parseStandalonePlainTextToolCallBlocks as parseStandaloneRepairToolCallBlocks,
   stripPlainTextToolCallBlocks as stripRepairToolCallBlocks,
diff --git a/src/plugin-sdk/tool-send.ts b/src/plugin-sdk/tool-send.ts
index 6cc4e69bea8..f1d33d1f955 100644
--- a/src/plugin-sdk/tool-send.ts
+++ b/src/plugin-sdk/tool-send.ts
@@ -1,3 +1,4 @@
+// Tool send helpers normalize model tool-send requests before provider dispatch.
 import { readStringValue } from "../../packages/normalization-core/src/string-coerce.js";
 
 export type { ChannelToolSend } from "../channels/plugins/types.public.js";
diff --git a/src/plugin-sdk/tts-runtime.types.ts b/src/plugin-sdk/tts-runtime.types.ts
index f105a5f9d49..0ba6f0757f4 100644
--- a/src/plugin-sdk/tts-runtime.types.ts
+++ b/src/plugin-sdk/tts-runtime.types.ts
@@ -1,3 +1,4 @@
+// TTS runtime types define plugin-facing text-to-speech synthesis hooks and results.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { ResolvedTtsPersona, TtsAutoMode, TtsProvider } from "../config/types.tts.js";
 import type {
diff --git a/src/plugin-sdk/webhook-request-guards.ts b/src/plugin-sdk/webhook-request-guards.ts
index f23b47de0df..1627ad6ecd8 100644
--- a/src/plugin-sdk/webhook-request-guards.ts
+++ b/src/plugin-sdk/webhook-request-guards.ts
@@ -1,3 +1,4 @@
+// Webhook request guards validate incoming HTTP requests before plugin webhook dispatch.
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { normalizeOptionalLowercaseString } from "../../packages/normalization-core/src/string-coerce.js";
 import { formatErrorMessage } from "../infra/errors.js";
diff --git a/src/plugin-sdk/webhook-targets.ts b/src/plugin-sdk/webhook-targets.ts
index 3f8d0eb3368..c891c0dea35 100644
--- a/src/plugin-sdk/webhook-targets.ts
+++ b/src/plugin-sdk/webhook-targets.ts
@@ -1,3 +1,4 @@
+// Webhook target helpers resolve and validate plugin webhook destinations.
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { registerPluginHttpRoute } from "../plugins/http-registry.js";
 import type { FixedWindowRateLimiter } from "./webhook-memory-guards.js";