docs: document sdk utility contracts

src/plugin-sdk/error-runtime.ts

@@ -1,9 +1,12 @@
 // Shared error graph/format helpers without the full infra-runtime surface.
 
+/** Stable error code for subagent APIs called outside an authenticated gateway request. */
 export const SUBAGENT_RUNTIME_REQUEST_SCOPE_ERROR_CODE = "OPENCLAW_SUBAGENT_RUNTIME_REQUEST_SCOPE";
+/** Default message paired with `SUBAGENT_RUNTIME_REQUEST_SCOPE_ERROR_CODE`. */
 export const SUBAGENT_RUNTIME_REQUEST_SCOPE_ERROR_MESSAGE =
   "Plugin runtime subagent methods are only available during a gateway request.";
 
+/** Error thrown when request-scoped plugin runtime APIs are used outside their scope. */
 export class RequestScopedSubagentRuntimeError extends Error {
   code = SUBAGENT_RUNTIME_REQUEST_SCOPE_ERROR_CODE;
 

src/plugin-sdk/keyed-async-queue.ts

@@ -1,4 +1,5 @@
 // Keyed async queue helpers serialize async plugin work by key while preserving parallelism.
+/** Optional lifecycle hooks fired around each queued task. */
 export type KeyedAsyncQueueHooks = {
   onEnqueue?: () => void;
   onSettle?: () => void;
@@ -33,6 +34,7 @@ export function enqueueKeyedTask<T>(params: {
   return current;
 }
 
+/** Small per-key async queue wrapper for plugin runtimes that need serialized work. */
 export class KeyedAsyncQueue {
   private readonly tails = new Map<string, Promise<void>>();
 

src/plugin-sdk/lazy-value.ts

@@ -5,6 +5,7 @@ type LazyValue<T> = T | (() => T);
 
 /** Returns a getter that resolves the supplied value at most once. */
 export function createCachedLazyValueGetter<T>(value: LazyValue<T>): () => T;
+/** Returns a getter that resolves once and substitutes a fallback for nullish values. */
 export function createCachedLazyValueGetter<T>(
   value: LazyValue<T | null | undefined>,
   fallback: T,

src/plugin-sdk/runtime-store.ts

@@ -49,19 +49,26 @@ function resolvePluginRuntimeStoreOptions(
   return options;
 }
 
-/** Create a tiny mutable runtime slot with strict access when the runtime has not been initialized. */
+/**
+ * Create a process-local runtime slot that throws when accessed before initialization.
+ *
+ * String keys create isolated module-local stores; option objects create global
+ * named slots so duplicate SDK module instances share the same plugin runtime.
+ */
 export function createPluginRuntimeStore<T>(errorMessage: string): {
   setRuntime: (next: T) => void;
   clearRuntime: () => void;
   tryGetRuntime: () => T | null;
   getRuntime: () => T;
 };
+/** Create a globally shared runtime slot keyed by plugin id or explicit registry key. */
 export function createPluginRuntimeStore<T>(options: PluginRuntimeStoreOptions): {
   setRuntime: (next: T) => void;
   clearRuntime: () => void;
   tryGetRuntime: () => T | null;
   getRuntime: () => T;
 };
+/** Implementation overload accepting either legacy error-message strings or structured options. */
 export function createPluginRuntimeStore<T>(options: string | PluginRuntimeStoreOptions): {
   setRuntime: (next: T) => void;
   clearRuntime: () => void;

src/plugin-sdk/security-runtime.ts

@@ -46,6 +46,7 @@ export {
   type FsSafeErrorCode as SafeOpenErrorCode,
 } from "../infra/fs-safe.js";
 
+/** Safely open a path beneath a trusted root while rejecting hardlinks and unsafe symlinks by default. */
 export async function openFileWithinRoot(params: {
   rootDir: string;
   relativePath: string;
@@ -61,6 +62,7 @@ export async function openFileWithinRoot(params: {
   });
 }
 
+/** Copy a source file into a path beneath a trusted root using fs-safe root policy. */
 export async function writeFileFromPathWithinRoot(params: {
   rootDir: string;
   relativePath: string;

src/plugin-sdk/windows-spawn.ts

@@ -14,6 +14,7 @@ export type WindowsSpawnResolution =
   | "exe-entrypoint"
   | "shell-fallback";
 
+/** Direct-spawn resolution before shell fallback is considered. */
 export type WindowsSpawnCandidateResolution = Exclude<WindowsSpawnResolution, "shell-fallback">;
 
 /** Direct-spawn candidate before shell fallback policy is applied. */
@@ -56,10 +57,12 @@ export type ResolveWindowsSpawnProgramParams = {
   /** Trusted compatibility escape hatch for callers that intentionally accept shell-mediated wrapper execution. */
   allowShellFallback?: boolean;
 };
+/** Inputs for candidate resolution that intentionally excludes shell fallback policy. */
 export type ResolveWindowsSpawnProgramCandidateParams = Omit<
   ResolveWindowsSpawnProgramParams,
   "allowShellFallback"
 >;
+/** Parsed executable plus inline arguments from a command string. */
 export type WindowsSpawnCommandInlineArgs = {
   executable: string;
   arguments: string;
@@ -115,6 +118,7 @@ function readCommandToken(command: string): { token: string; rest: string } | nu
   };
 }
 
+/** Detect command strings like `node script.js` that should be split before spawn. */
 export function detectWindowsSpawnCommandInlineArgs(
   command: string,
 ): WindowsSpawnCommandInlineArgs | null {