docs: document sdk migration and approval contracts

src/plugin-sdk/approval-handler-runtime.ts

@@ -86,6 +86,7 @@ export function resolvePreparedApprovalAccountId(params: {
   contextAccountId?: string | null;
   fallbackAccountId: string;
 }): string;
+/** Resolve prepared approval account id when every source may be missing. */
 export function resolvePreparedApprovalAccountId(params: {
   plannedAccountId?: string | null;
   contextAccountId?: string | null;

src/plugin-sdk/approval-renderers.ts

@@ -82,6 +82,7 @@ export function buildApprovalResolvedReplyPayload(params: {
   };
 }
 
+/** Build pending plugin approval copy and metadata from a plugin approval request. */
 export function buildPluginApprovalPendingReplyPayload(params: {
   /** Plugin approval request to render. */
   request: PluginApprovalRequest;
@@ -108,6 +109,7 @@ export function buildPluginApprovalPendingReplyPayload(params: {
   });
 }
 
+/** Build resolved plugin approval copy and metadata from a plugin approval event. */
 export function buildPluginApprovalResolvedReplyPayload(params: {
   /** Resolved plugin approval event to render. */
   resolved: PluginApprovalResolved;

src/plugin-sdk/image-generation-core.ts

@@ -33,6 +33,7 @@ export { parseImageGenerationModelRef } from "../image-generation/model-ref.js";
 export { createSubsystemLogger } from "../logging/subsystem.js";
 export { normalizeGooglePreviewModelId as normalizeGoogleModelId } from "./provider-model-shared.js";
 export { getProviderEnvVars } from "../secrets/provider-env-vars.js";
+/** Default OpenAI image model used when image-generation provider config omits one. */
 export const OPENAI_DEFAULT_IMAGE_MODEL = "gpt-image-2";
 
 type ImageGenerationCoreAuthRuntimeModule =
@@ -47,6 +48,7 @@ async function loadImageGenerationCoreAuthRuntime(): Promise<ImageGenerationCore
   return imageGenerationCoreAuthRuntimePromise;
 }
 
+/** Resolve image-generation provider API keys through the lazy auth runtime helper. */
 export async function resolveApiKeyForProvider(
   ...args: Parameters<ImageGenerationCoreAuthRuntimeModule["resolveApiKeyForProvider"]>
 ): Promise<Awaited<ReturnType<ImageGenerationCoreAuthRuntimeModule["resolveApiKeyForProvider"]>>> {

src/plugin-sdk/migration-runtime.ts

@@ -19,6 +19,7 @@ import {
 
 export type { MigrationApplyResult, MigrationItem } from "../plugins/types.js";
 
+/** Wrap migration runtime config access with a cached mutable snapshot during apply. */
 export function withCachedMigrationConfigRuntime(
   runtime: MigrationProviderContext["runtime"] | undefined,
   fallbackConfig: MigrationProviderContext["config"],
@@ -130,6 +131,7 @@ async function resolveUniqueArchivePath(
   return candidate;
 }
 
+/** Archive a migration item source into the report directory and mark the item migrated. */
 export async function archiveMigrationItem(
   item: MigrationItem,
   reportDir: string,
@@ -166,6 +168,7 @@ export async function archiveMigrationItem(
   }
 }
 
+/** Copy a migration item source to its target, optionally backing up an overwritten target. */
 export async function copyMigrationFileItem(
   item: MigrationItem,
   reportDir: string,
@@ -201,6 +204,7 @@ export async function copyMigrationFileItem(
   }
 }
 
+/** Write redacted JSON and Markdown migration reports into the apply report directory. */
 export async function writeMigrationReport(
   result: MigrationApplyResult,
   opts: { title?: string } = {},

src/plugin-sdk/migration.ts

@@ -19,7 +19,9 @@ export type {
   MigrationSummary,
 };
 
+/** Shared migration failure reason when an item lacks required paths. */
 export const MIGRATION_REASON_MISSING_SOURCE_OR_TARGET = "missing source or target";
+/** Shared migration conflict reason when a target already exists. */
 export const MIGRATION_REASON_TARGET_EXISTS = "target exists";
 
 /** Creates a migration item, defaulting new provider output to the planned state. */
@@ -98,6 +100,7 @@ function isSecretKey(key: string): boolean {
   return SECRET_KEY_MARKERS.some((marker) => normalized.includes(marker));
 }
 
+/** Structured config patch details stored on migration items. */
 export type MigrationConfigPatchDetails = {
   /** Config object path where the patch should be merged. */
   path: string[];

src/plugin-sdk/ssrf-policy.ts

@@ -19,6 +19,7 @@ import type { OpenClawConfig } from "./config-runtime.js";
 export { isPrivateIpAddress, mergeSsrFPolicies };
 export type { SsrFPolicy };
 
+/** Accepted channel config shapes that opt into private-network HTTP targets. */
 export type PrivateNetworkOptInInput =
   | boolean
   | null
@@ -128,6 +129,7 @@ function hasLegacyAllowPrivateNetworkInAccounts(value: unknown): boolean {
   );
 }
 
+/** Build doctor rules that migrate legacy private-network aliases for one channel config. */
 export function createLegacyPrivateNetworkDoctorContract(params: { channelKey: string }): {
   legacyConfigRules: ChannelDoctorLegacyConfigRule[];
   normalizeCompatibilityConfig: (params: { cfg: OpenClawConfig }) => ChannelDoctorConfigMutation;