From fd5dc5bb3abe7110f6bdf38eb519a96bda1b6fd4 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 3 Jun 2026 20:39:16 -0400 Subject: [PATCH] docs: document plugin catalog install helpers --- src/plugins/api-facades.ts | 2 ++ src/plugins/clawhub-install-records.ts | 2 ++ src/plugins/installed-plugin-index-registry.ts | 1 + src/plugins/model-catalog-registration.ts | 5 +++-- src/plugins/openai-compatible-embedding-provider.ts | 5 +++++ src/plugins/provider-install-catalog.ts | 3 +++ src/plugins/provider-model-primary.ts | 2 ++ src/plugins/validation-diagnostics.ts | 1 + 8 files changed, 19 insertions(+), 2 deletions(-) diff --git a/src/plugins/api-facades.ts b/src/plugins/api-facades.ts index 9a7ab56c889..16c880def4e 100644 --- a/src/plugins/api-facades.ts +++ b/src/plugins/api-facades.ts @@ -4,6 +4,7 @@ type PluginApiFacadeFields = Pick< OpenClawPluginApi, "agent" | "lifecycle" | "runContext" | "session" >; +/** Plugin API shape without nested facade namespaces attached. */ export type OpenClawPluginApiWithoutFacades = Omit; type PluginApiFacadeSource = Pick< OpenClawPluginApi, @@ -23,6 +24,7 @@ type PluginApiFacadeSource = Pick< | "unscheduleSessionTurnsByTag" >; +/** Attaches nested facade namespaces to the flat plugin API implementation. */ export function attachPluginApiFacades( api: T & PluginApiFacadeSource & Partial, ): T & PluginApiFacadeFields { diff --git a/src/plugins/clawhub-install-records.ts b/src/plugins/clawhub-install-records.ts index 8eb7adcfc58..5dccaf59f95 100644 --- a/src/plugins/clawhub-install-records.ts +++ b/src/plugins/clawhub-install-records.ts @@ -1,6 +1,7 @@ import type { PluginInstallRecord } from "../config/types.plugins.js"; import type { ClawHubPackageChannel, ClawHubPackageFamily } from "../infra/clawhub.js"; +/** Install record fields captured for ClawHub plugin installs. */ export type ClawHubPluginInstallRecordFields = { source: "clawhub"; clawhubUrl: string; @@ -22,6 +23,7 @@ export type ClawHubPluginInstallRecordFields = { clawpackSize?: number; }; +/** Builds plugin install record fields from resolved ClawHub package metadata. */ export function buildClawHubPluginInstallRecordFields( fields: ClawHubPluginInstallRecordFields, ): Pick< diff --git a/src/plugins/installed-plugin-index-registry.ts b/src/plugins/installed-plugin-index-registry.ts index eda6e96d123..589f4bcd2a4 100644 --- a/src/plugins/installed-plugin-index-registry.ts +++ b/src/plugins/installed-plugin-index-registry.ts @@ -8,6 +8,7 @@ import { loadInstalledPluginIndexInstallRecordsSync } from "./installed-plugin-i import type { LoadInstalledPluginIndexParams } from "./installed-plugin-index-types.js"; import { loadPluginManifestRegistry, type PluginManifestRegistry } from "./manifest-registry.js"; +/** Resolves discovery candidates and manifest registry for installed plugin index loading. */ export function resolveInstalledPluginIndexRegistry(params: LoadInstalledPluginIndexParams): { registry: PluginManifestRegistry; candidates: readonly PluginCandidate[]; diff --git a/src/plugins/model-catalog-registration.ts b/src/plugins/model-catalog-registration.ts index 1bd806d5655..4d8f57480ac 100644 --- a/src/plugins/model-catalog-registration.ts +++ b/src/plugins/model-catalog-registration.ts @@ -7,13 +7,13 @@ import { type MediaGenerationCatalogKind, type MediaGenerationCatalogProvider, } from "../../packages/media-generation-core/src/catalog.js"; +import { normalizeOptionalString } from "../../packages/normalization-core/src/string-coerce.js"; +import { uniqueValues } from "../../packages/normalization-core/src/string-normalization.js"; import { synthesizeVoiceModelCatalogEntries, type VoiceModelCapabilities, type VoiceModelProvider, } from "../../packages/speech-core/voice-models.js"; -import { normalizeOptionalString } from "../../packages/normalization-core/src/string-coerce.js"; -import { uniqueValues } from "../../packages/normalization-core/src/string-normalization.js"; import type { PluginDiagnostic } from "./manifest-types.js"; import { projectProviderCatalogResultToUnifiedTextRows } from "./provider-catalog-unified-text.js"; import type { PluginRecord, PluginRegistry } from "./registry-types.js"; @@ -58,6 +58,7 @@ function mergeModelCatalogHooks( }; } +/** Creates handlers that register plugin model catalog providers into a registry. */ export function createModelCatalogRegistrationHandlers(params: { registry: PluginRegistry; pushDiagnostic: (diagnostic: PluginDiagnostic) => void; diff --git a/src/plugins/openai-compatible-embedding-provider.ts b/src/plugins/openai-compatible-embedding-provider.ts index 25c759d6f56..d124e6e28f5 100644 --- a/src/plugins/openai-compatible-embedding-provider.ts +++ b/src/plugins/openai-compatible-embedding-provider.ts @@ -11,9 +11,11 @@ import type { EmbeddingProviderCreateOptions, } from "./embedding-provider-types.js"; +/** Provider id for OpenAI-compatible remote embedding servers. */ export const OPENAI_COMPATIBLE_EMBEDDING_PROVIDER_ID = "openai-compatible"; const OPENAI_COMPATIBLE_MODEL_APIS = new Set(["openai-completions", "openai-responses"]); +/** Normalized OpenAI-compatible embedding client configuration. */ export type OpenAICompatibleEmbeddingClient = { baseUrl: string; headers: Record; @@ -326,6 +328,7 @@ async function postEmbeddingRequest(params: { } } +/** Creates a normalized OpenAI-compatible embedding client from runtime config. */ export async function createOpenAICompatibleEmbeddingClient( options: EmbeddingProviderCreateOptions, ): Promise { @@ -362,6 +365,7 @@ export async function createOpenAICompatibleEmbeddingClient( }; } +/** Creates an OpenAI-compatible embedding provider and its backing client. */ export async function createOpenAICompatibleEmbeddingProvider( options: EmbeddingProviderCreateOptions, ): Promise<{ @@ -398,6 +402,7 @@ export async function createOpenAICompatibleEmbeddingProvider( }; } +/** Embedding provider adapter for OpenAI-compatible remote embedding APIs. */ export const openAICompatibleEmbeddingProviderAdapter: EmbeddingProviderAdapter = { id: OPENAI_COMPATIBLE_EMBEDDING_PROVIDER_ID, transport: "remote", diff --git a/src/plugins/provider-install-catalog.ts b/src/plugins/provider-install-catalog.ts index 1575ead2d78..0f89b69b13d 100644 --- a/src/plugins/provider-install-catalog.ts +++ b/src/plugins/provider-install-catalog.ts @@ -24,6 +24,7 @@ import { type ProviderAuthChoiceMetadata, } from "./provider-auth-choices.js"; +/** Provider setup choice paired with install metadata for the owning plugin. */ export type ProviderInstallCatalogEntry = ProviderAuthChoiceMetadata & { label: string; origin: PluginOrigin; @@ -369,6 +370,7 @@ function resolveOfficialExternalProviderInstallCatalogEntries(params: { return entries; } +/** Lists install catalog entries for provider setup choices. */ export function resolveProviderInstallCatalogEntries( params?: ProviderInstallCatalogParams, ): ProviderInstallCatalogEntry[] { @@ -411,6 +413,7 @@ export function resolveProviderInstallCatalogEntries( ); } +/** Resolves one provider install catalog entry by setup choice id. */ export function resolveProviderInstallCatalogEntry( choiceId: string, params?: ProviderInstallCatalogParams, diff --git a/src/plugins/provider-model-primary.ts b/src/plugins/provider-model-primary.ts index 199669cc8be..82313667483 100644 --- a/src/plugins/provider-model-primary.ts +++ b/src/plugins/provider-model-primary.ts @@ -15,6 +15,7 @@ function resolvePrimaryModel(model?: AgentModelListConfig | string): string | un return undefined; } +/** Applies an agent default primary model and reports whether config changed. */ export function applyAgentDefaultPrimaryModel(params: { cfg: OpenClawConfig; model: string; @@ -49,6 +50,7 @@ export function applyAgentDefaultPrimaryModel(params: { }; } +/** Applies a primary model to agent defaults while preserving model fallback metadata. */ export function applyPrimaryModel(cfg: OpenClawConfig, model: string): OpenClawConfig { const normalizedModel = normalizeAgentModelRefForConfig(model); const defaults = cfg.agents?.defaults; diff --git a/src/plugins/validation-diagnostics.ts b/src/plugins/validation-diagnostics.ts index bc8b9dcebf0..e174cc5c28f 100644 --- a/src/plugins/validation-diagnostics.ts +++ b/src/plugins/validation-diagnostics.ts @@ -1,5 +1,6 @@ import type { PluginDiagnostic } from "./manifest-types.js"; +/** Pushes a normalized plugin validation diagnostic. */ export function pushPluginValidationDiagnostic(params: { level: PluginDiagnostic["level"]; pluginId: string;