From 4756d6a42a06df9b79f8ef2442e476f3ab39656e Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 4 Jun 2026 22:24:26 -0400 Subject: [PATCH] docs: document sdk migration and approval contracts --- src/plugin-sdk/approval-handler-runtime.ts | 1 + src/plugin-sdk/approval-renderers.ts | 2 ++ src/plugin-sdk/image-generation-core.ts | 2 ++ src/plugin-sdk/migration-runtime.ts | 4 ++++ src/plugin-sdk/migration.ts | 3 +++ src/plugin-sdk/ssrf-policy.ts | 2 ++ 6 files changed, 14 insertions(+) diff --git a/src/plugin-sdk/approval-handler-runtime.ts b/src/plugin-sdk/approval-handler-runtime.ts index 1ff734e2f475..3e101e0a5fc2 100644 --- a/src/plugin-sdk/approval-handler-runtime.ts +++ b/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; diff --git a/src/plugin-sdk/approval-renderers.ts b/src/plugin-sdk/approval-renderers.ts index f3c1dbfbffdd..ce7e4773cda5 100644 --- a/src/plugin-sdk/approval-renderers.ts +++ b/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; diff --git a/src/plugin-sdk/image-generation-core.ts b/src/plugin-sdk/image-generation-core.ts index d3aa8af02215..1ac00dd278f1 100644 --- a/src/plugin-sdk/image-generation-core.ts +++ b/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 ): Promise>> { diff --git a/src/plugin-sdk/migration-runtime.ts b/src/plugin-sdk/migration-runtime.ts index b772992f61ee..cbd3f192c846 100644 --- a/src/plugin-sdk/migration-runtime.ts +++ b/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 } = {}, diff --git a/src/plugin-sdk/migration.ts b/src/plugin-sdk/migration.ts index 2aada95a291e..c183ff6a7565 100644 --- a/src/plugin-sdk/migration.ts +++ b/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[]; diff --git a/src/plugin-sdk/ssrf-policy.ts b/src/plugin-sdk/ssrf-policy.ts index 0c22dfcc6618..71aecee8a766 100644 --- a/src/plugin-sdk/ssrf-policy.ts +++ b/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;