docs: document sdk runtime helper contracts

steipete · steipete · commit de68623ffed7 · 2026-06-04T22:14:54.000-04:00
diff --git a/src/plugin-sdk/file-lock.ts b/src/plugin-sdk/file-lock.ts
@@ -8,6 +8,7 @@ import {
 import { shouldRemoveDeadOwnerOrExpiredLock } from "../infra/stale-lock-file.js";
 import { getProcessStartTime } from "../shared/pid-alive.js";
 
+/** Retry and stale-recovery policy for acquiring a filesystem lock. */
 export type FileLockOptions = {
   /** Retry policy used while waiting for another process or re-entrant holder to release. */
   retries: {
@@ -21,23 +22,28 @@ export type FileLockOptions = {
   stale: number;
 };
 
+/** Live file-lock handle returned after successful acquisition. */
 export type FileLockHandle = {
   /** Absolute path to the `.lock` sidecar held for this file path. */
   lockPath: string;
   /** Releases one held reference; callers must await it before assuming peers can proceed. */
   release: () => Promise<void>;
 };
 
+/** Stable error code used when lock acquisition retries are exhausted. */
 export const FILE_LOCK_TIMEOUT_ERROR_CODE = "file_lock_timeout";
+/** Stable error code used when stale lock recovery cannot proceed safely. */
 export const FILE_LOCK_STALE_ERROR_CODE = "file_lock_stale";
 
+/** Typed error thrown when a lock cannot be acquired before timeout. */
 export type FileLockTimeoutError = Error & {
   /** Stable error discriminator for lock acquisition timeout handling. */
   code: typeof FILE_LOCK_TIMEOUT_ERROR_CODE;
   /** Lock sidecar path that could not be acquired before retries were exhausted. */
   lockPath: string;
 };
 
+/** Typed error thrown when a stale lock sidecar cannot be reclaimed safely. */
 export type FileLockStaleError = Error & {
   /** Stable error discriminator for stale-lock reclaim failures. */
   code: typeof FILE_LOCK_STALE_ERROR_CODE;
@@ -76,10 +82,12 @@ function normalizeLockError(err: unknown): never {
   throw err;
 }
 
+/** Reset process-local file-lock state for tests that isolate lock managers. */
 export function resetFileLockStateForTest(): void {
   resetFileLockManagerForTest(FILE_LOCK_MANAGER_KEY, FILE_LOCK_MANAGER_KEY);
 }
 
+/** Wait for process-local file-lock state to drain before test teardown. */
 export async function drainFileLockStateForTest(): Promise<void> {
   await drainFileLockManagerForTest(FILE_LOCK_MANAGER_KEY, FILE_LOCK_MANAGER_KEY);
 }
diff --git a/src/plugin-sdk/gateway-method-runtime.ts b/src/plugin-sdk/gateway-method-runtime.ts
@@ -2,6 +2,7 @@
 import { dispatchGatewayMethodInProcessRaw } from "../gateway/server-plugins.js";
 import { getPluginRuntimeGatewayRequestScope } from "../plugins/runtime/gateway-request-scope.js";
 
+/** Error envelope returned by in-process Gateway method dispatch. */
 export type GatewayMethodDispatchError = {
   /** Stable machine-readable error code returned by the Gateway method. */
   code: string;
@@ -15,6 +16,7 @@ export type GatewayMethodDispatchError = {
   retryAfterMs?: number;
 };
 
+/** Response envelope returned to plugins after dispatching a Gateway method. */
 export type GatewayMethodDispatchResponse = {
   /** True when the Gateway method completed and `payload` contains its result. */
   ok: boolean;
@@ -26,6 +28,7 @@ export type GatewayMethodDispatchResponse = {
   meta?: Record<string, unknown>;
 };
 
+/** Dispatch controls for plugin-initiated Gateway method calls. */
 export type GatewayMethodDispatchOptions = {
   /** Wait for the Gateway's final response instead of returning the first response frame. */
   expectFinal?: boolean;
diff --git a/src/plugin-sdk/provider-selection-runtime.ts b/src/plugin-sdk/provider-selection-runtime.ts
@@ -1,13 +1,15 @@
 // Provider selection runtime helpers resolve plugin/provider choices from config and CLI input.
 import { normalizeOptionalString } from "../../packages/normalization-core/src/string-coerce.js";
 
+/** Provider descriptor fields needed for explicit or automatic selection. */
 export type AutoSelectableProvider = {
   /** Provider id used for explicit config lookup and selected result metadata. */
   id: string;
   /** Lower values win when no explicit provider is configured. */
   autoSelectOrder?: number;
 };
 
+/** Provider selection result before capability-specific configuration checks run. */
 export type ProviderSelection<TProvider> = {
   /** Normalized explicit provider id, when the caller supplied one. */
   configuredProviderId?: string;
@@ -17,6 +19,7 @@ export type ProviderSelection<TProvider> = {
   provider: TProvider | undefined;
 };
 
+/** Final provider resolution result including capability-specific config. */
 export type ResolvedConfiguredProvider<TProvider, TConfig> =
   | {
       /** Provider exists and passed the capability-specific configuration check. */
@@ -39,6 +42,7 @@ export type ResolvedConfiguredProvider<TProvider, TConfig> =
       provider?: TProvider;
     };
 
+/** Select an explicit provider when configured, otherwise the lowest-order auto provider. */
 export function selectConfiguredOrAutoProvider<TProvider extends AutoSelectableProvider>(params: {
   /** Optional explicit provider id from config or user input. */
   configuredProviderId?: string;
@@ -67,6 +71,7 @@ export function selectConfiguredOrAutoProvider<TProvider extends AutoSelectableP
   };
 }
 
+/** Merge canonical provider config with selected-provider override config. */
 export function resolveProviderRawConfig(params: {
   /** Canonical provider id whose default config should be read first. */
   providerId: string;
@@ -87,6 +92,7 @@ export function resolveProviderRawConfig(params: {
   };
 }
 
+/** Resolve a configured or auto-selected provider that passes capability config checks. */
 export function resolveConfiguredCapabilityProvider<
   TConfig,
   TFullConfig,
diff --git a/src/plugin-sdk/provider-stream-shared.ts b/src/plugin-sdk/provider-stream-shared.ts
@@ -15,10 +15,12 @@ import { streamSimple } from "../llm/stream.js";
 import { createAssistantMessageEventStream } from "../llm/utils/event-stream.js";
 import type { ProviderWrapStreamFnContext } from "./plugin-entry.js";
 
+/** Optional provider stream decorator factory used by shared provider wrappers. */
 export type ProviderStreamWrapperFactory =
   /** Wrapper factory that can decorate, replace, or omit a provider stream function. */
   ((streamFn: StreamFn | undefined) => StreamFn | undefined) | null | undefined | false;
 
+/** Compose stream wrapper factories from left to right around a base stream function. */
 export function composeProviderStreamWrappers(
   /** Base provider stream function to pass through the wrapper chain. */
   baseStreamFn: StreamFn | undefined,
@@ -235,6 +237,7 @@ export function defaultToolStreamExtraParams(
   };
 }
 
+/** Wrap a provider stream so callers can patch the outbound provider payload once. */
 export function createPayloadPatchStreamWrapper(
   /** Provider stream function whose outbound payload should be patched. */
   baseStreamFn: StreamFn | undefined,
diff --git a/src/plugin-sdk/qa-channel-protocol.ts b/src/plugin-sdk/qa-channel-protocol.ts
@@ -1,14 +1,17 @@
 // QA channel protocol helpers validate synthetic channel messages used by QA plugins.
 import { isRecord } from "../../packages/normalization-core/src/record-coerce.js";
 
+/** Conversation shape supported by the synthetic QA channel bus. */
 export type QaBusConversationKind = "direct" | "channel" | "group";
 
+/** Addressable conversation used by QA bus messages and thread state. */
 export type QaBusConversation = {
   id: string;
   kind: QaBusConversationKind;
   title?: string;
 };
 
+/** Media/file attachment fixture accepted by QA bus message APIs. */
 export type QaBusAttachment = {
   id: string;
   kind: "image" | "video" | "audio" | "file";
@@ -24,11 +27,13 @@ export type QaBusAttachment = {
   transcript?: string;
 };
 
+/** Tool-call fixture attached to QA messages for agent-runtime tests. */
 export type QaBusToolCall = {
   name: string;
   arguments?: Record<string, unknown>;
 };
 
+/** Stored QA bus message after defaults, reactions, and account ids are normalized. */
 export type QaBusMessage = {
   id: string;
   accountId: string;
@@ -52,6 +57,7 @@ export type QaBusMessage = {
   }>;
 };
 
+/** Synthetic thread record created inside a QA bus conversation. */
 export type QaBusThread = {
   id: string;
   accountId: string;
@@ -61,6 +67,7 @@ export type QaBusThread = {
   createdBy: string;
 };
 
+/** Ordered event emitted by QA bus polling and state snapshots. */
 export type QaBusEvent =
   | { cursor: number; kind: "inbound-message"; accountId: string; message: QaBusMessage }
   | { cursor: number; kind: "outbound-message"; accountId: string; message: QaBusMessage }
@@ -76,6 +83,7 @@ export type QaBusEvent =
       senderId: string;
     };
 
+/** Input for injecting an inbound message from a synthetic user/channel. */
 export type QaBusInboundMessageInput = {
   accountId?: string;
   conversation: QaBusConversation;
@@ -90,6 +98,7 @@ export type QaBusInboundMessageInput = {
   toolCalls?: QaBusToolCall[];
 };
 
+/** Input for recording an outbound message sent by an OpenClaw runtime. */
 export type QaBusOutboundMessageInput = {
   accountId?: string;
   to: string;
@@ -103,6 +112,7 @@ export type QaBusOutboundMessageInput = {
   toolCalls?: QaBusToolCall[];
 };
 
+/** Input for creating a synthetic QA bus thread. */
 export type QaBusCreateThreadInput = {
   accountId?: string;
   conversationId: string;
@@ -111,6 +121,7 @@ export type QaBusCreateThreadInput = {
   timestamp?: number;
 };
 
+/** Input for adding a reaction event to an existing QA bus message. */
 export type QaBusReactToMessageInput = {
   accountId?: string;
   messageId: string;
@@ -119,19 +130,22 @@ export type QaBusReactToMessageInput = {
   timestamp?: number;
 };
 
+/** Input for editing an existing QA bus message. */
 export type QaBusEditMessageInput = {
   accountId?: string;
   messageId: string;
   text: string;
   timestamp?: number;
 };
 
+/** Input for marking an existing QA bus message as deleted. */
 export type QaBusDeleteMessageInput = {
   accountId?: string;
   messageId: string;
   timestamp?: number;
 };
 
+/** Search filter accepted by QA bus message lookup helpers. */
 export type QaBusSearchMessagesInput = {
   accountId?: string;
   query?: string;
@@ -140,23 +154,27 @@ export type QaBusSearchMessagesInput = {
   limit?: number;
 };
 
+/** Lookup key for reading one QA bus message. */
 export type QaBusReadMessageInput = {
   accountId?: string;
   messageId: string;
 };
 
+/** Cursor and timeout options used by QA bus polling. */
 export type QaBusPollInput = {
   accountId?: string;
   cursor?: number;
   timeoutMs?: number;
   limit?: number;
 };
 
+/** Poll response containing the next cursor and ordered events. */
 export type QaBusPollResult = {
   cursor: number;
   events: QaBusEvent[];
 };
 
+/** Complete QA bus state snapshot exposed to tests and diagnostics. */
 export type QaBusStateSnapshot = {
   cursor: number;
   conversations: QaBusConversation[];
@@ -212,6 +230,7 @@ function sanitizeQaBusToolCallValue(value: unknown, depth: number, key?: string)
   return undefined;
 }
 
+/** Sanitize arbitrary tool-call arguments before storing them in QA bus messages. */
 export function sanitizeQaBusToolCallArguments(
   value: unknown,
 ): Record<string, unknown> | undefined {
@@ -222,6 +241,7 @@ export function sanitizeQaBusToolCallArguments(
   return isRecord(sanitized) ? sanitized : undefined;
 }
 
+/** Normalize and redact a bounded list of tool calls from untrusted QA input. */
 export function sanitizeQaBusToolCalls(value: unknown): QaBusToolCall[] | undefined {
   if (!Array.isArray(value)) {
     return undefined;
@@ -245,6 +265,7 @@ export function sanitizeQaBusToolCalls(value: unknown): QaBusToolCall[] | undefi
   return sanitized.length > 0 ? sanitized : undefined;
 }
 
+/** Predicate input used by QA helpers that wait for bus events or messages. */
 export type QaBusWaitForInput =
   | {
       timeoutMs?: number;
