docs: document plugin sdk runtime helpers

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 = {

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";

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";

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";

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";
 

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,

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,

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. */

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";
 

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";

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,

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";

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";

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";
 

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;

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,

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";

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";

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,

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 = {

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 = {

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";

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";

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";

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";

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,

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";
 

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,

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";

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 {

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";

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";