docs: document image generation runtime

steipete · steipete · commit 0135a0a7803f · 2026-06-04T05:00:21.000-04:00
diff --git a/src/image-generation/image-assets.test.ts b/src/image-generation/image-assets.test.ts
@@ -1,3 +1,4 @@
+/** Tests image asset parsing, MIME sniffing, and OpenAI-compatible response conversion. */
 import { describe, expect, it } from "vitest";
 import {
   generatedImageAssetFromDataUrl,
diff --git a/src/image-generation/image-assets.ts b/src/image-generation/image-assets.ts
@@ -1,3 +1,4 @@
+/** Converts image provider base64/data-url payloads into generated or source image assets. */
 import { canonicalizeBase64 } from "@openclaw/media-core/base64";
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
 import {
@@ -11,6 +12,7 @@ const DEFAULT_IMAGE_FILE_PREFIX = "image";
 
 // Image asset helpers for provider responses and source uploads. They normalize
 // base64/data-url inputs into in-memory assets with predictable filenames.
+/** Result of conservative image MIME sniffing for provider responses. */
 export type ImageMimeTypeDetection = {
   mimeType: string;
   extension: string;
@@ -33,6 +35,7 @@ function throwMalformedImageResponse(message: string | undefined): never | undef
   return undefined;
 }
 
+/** Maps an image MIME type to a stable filename extension. */
 export function imageFileExtensionForMimeType(
   mimeType: string | undefined,
   fallback = "png",
diff --git a/src/image-generation/live-test-helpers.test.ts b/src/image-generation/live-test-helpers.test.ts
@@ -1,3 +1,4 @@
+/** Tests live image-generation helper parsing and provider selection. */
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import {
diff --git a/src/image-generation/live-test-helpers.ts b/src/image-generation/live-test-helpers.ts
@@ -1,3 +1,4 @@
+/** Helpers for selecting image-generation providers and models in live tests. */
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import {
diff --git a/src/image-generation/model-ref.ts b/src/image-generation/model-ref.ts
@@ -1,3 +1,4 @@
+/** Parses image-generation model references into provider/model components. */
 import { parseGenerationModelRef } from "../../packages/media-generation-core/src/model-ref.js";
 
 // Image model refs share the generic media-generation provider/model grammar:
diff --git a/src/image-generation/normalization.ts b/src/image-generation/normalization.ts
@@ -1,3 +1,4 @@
+/** Normalizes image generation request overrides against provider/model capabilities. */
 import {
   hasMediaNormalizationEntry,
   resolveClosestAspectRatio,
@@ -37,6 +38,7 @@ function finalizeImageNormalization(
     : undefined;
 }
 
+/** Returns supported image overrides plus ignored/normalized override metadata for replies. */
 export function resolveImageGenerationOverrides(params: {
   provider: ImageGenerationProvider;
   model?: string;
diff --git a/src/image-generation/openai-compatible-image-provider.test.ts b/src/image-generation/openai-compatible-image-provider.test.ts
@@ -1,3 +1,4 @@
+/** Tests OpenAI-compatible image provider request building and response handling. */
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   createOpenAiCompatibleImageGenerationProvider,
diff --git a/src/image-generation/openai-compatible-image-provider.ts b/src/image-generation/openai-compatible-image-provider.ts
@@ -1,3 +1,4 @@
+/** Factory for image providers with OpenAI-compatible generation/edit endpoints. */
 import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
 import { isProviderApiKeyConfigured } from "openclaw/plugin-sdk/provider-auth";
 import { resolveApiKeyForProvider } from "openclaw/plugin-sdk/provider-auth-runtime";
@@ -24,6 +25,7 @@ import type {
 // /images/edits endpoints while still allowing provider-specific bodies.
 type ModelProviderConfig = NonNullable<NonNullable<OpenClawConfig["models"]>["providers"]>[string];
 
+/** OpenAI-compatible image endpoint mode. */
 export type OpenAiCompatibleImageRequestMode = "generate" | "edit";
 
 export type OpenAiCompatibleImageProviderRequestParams = {
@@ -125,6 +127,7 @@ function resolveRequestTimeoutMs(params: {
   });
 }
 
+/** Creates an image-generation provider backed by OpenAI-style image endpoints. */
 export function createOpenAiCompatibleImageGenerationProvider(
   options: OpenAiCompatibleImageProviderOptions,
 ): ImageGenerationProvider {
diff --git a/src/image-generation/provider-registry.test.ts b/src/image-generation/provider-registry.test.ts
@@ -1,3 +1,4 @@
+/** Tests image-generation provider registry aliases and plugin capability integration. */
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/types.js";
 import type { ImageGenerationProviderPlugin } from "../plugins/types.js";
diff --git a/src/image-generation/provider-registry.ts b/src/image-generation/provider-registry.ts
@@ -1,3 +1,4 @@
+/** Registry for image-generation providers contributed by plugin capabilities. */
 import { normalizeProviderId } from "../agents/model-selection.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { isBlockedObjectKey } from "../infra/prototype-keys.js";
@@ -63,12 +64,14 @@ function buildProviderMaps(cfg?: OpenClawConfig): {
   return { canonical, aliases };
 }
 
+/** Lists canonical image-generation providers visible for config. */
 export function listImageGenerationProviders(
   cfg?: OpenClawConfig,
 ): ImageGenerationProviderPlugin[] {
   return [...buildProviderMaps(cfg).canonical.values()];
 }
 
+/** Resolves an image-generation provider by canonical id or alias. */
 export function getImageGenerationProvider(
   providerId: string | undefined,
   cfg?: OpenClawConfig,
diff --git a/src/image-generation/runtime-types.ts b/src/image-generation/runtime-types.ts
@@ -1,3 +1,4 @@
+/** Public runtime parameter and result types for image generation calls. */
 import type { AuthProfileStore } from "../agents/auth-profiles/types.js";
 import type { FallbackAttempt } from "../agents/model-fallback.types.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
diff --git a/src/image-generation/runtime.test.ts b/src/image-generation/runtime.test.ts
@@ -1,3 +1,4 @@
+/** Tests image-generation runtime fallback, overrides, and error reporting. */
 import { beforeEach, describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import {
diff --git a/src/image-generation/runtime.ts b/src/image-generation/runtime.ts
@@ -1,3 +1,4 @@
+/** Runtime entrypoint for image generation with provider fallback and override normalization. */
 import { describeFailoverError, isFailoverError } from "../agents/failover-error.js";
 import type { FallbackAttempt } from "../agents/model-fallback.types.js";
 import { resolveAgentModelTimeoutMsValue } from "../config/model-input.js";
@@ -22,6 +23,7 @@ const log = createSubsystemLogger("image-generation");
 
 // Runtime dependency seam for tests and plugin-host callers. Production uses
 // the plugin registry and provider-env helpers by default.
+/** Dependency seam used by image-generation runtime tests and plugin host callers. */
 export type ImageGenerationRuntimeDeps = {
   getProvider?: typeof getImageGenerationProvider;
   listProviders?: typeof listImageGenerationProviders;
@@ -44,6 +46,7 @@ function buildNoImageGenerationModelConfiguredMessage(
   });
 }
 
+/** Lists image-generation providers visible for the current config. */
 export function listRuntimeImageGenerationProviders(
   params?: { config?: OpenClawConfig },
   deps: ImageGenerationRuntimeDeps = {},
diff --git a/src/image-generation/types.ts b/src/image-generation/types.ts
@@ -1,8 +1,10 @@
+/** Shared image-generation request, provider, capability, and result contracts. */
 import type { MediaNormalizationEntry } from "../../packages/media-generation-core/src/normalization.js";
 import type { AuthProfileStore } from "../agents/auth-profiles/types.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { SsrFPolicy } from "../infra/net/ssrf.js";
 
+/** Binary image asset returned by an image-generation provider. */
 export type GeneratedImageAsset = {
   buffer: Buffer;
   mimeType: string;
@@ -59,6 +61,7 @@ export type ImageGenerationProviderConfiguredContext = {
   agentDir?: string;
 };
 
+/** Runtime request passed to an image-generation provider implementation. */
 export type ImageGenerationRequest = {
   provider: string;
   model: string;
diff --git a/src/plugins/provider-self-hosted-setup.test.ts b/src/plugins/provider-self-hosted-setup.test.ts
@@ -1,3 +1,4 @@
+/** Tests self-hosted provider setup helpers and auth/config defaults. */
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import {
   configureOpenAICompatibleSelfHostedProviderNonInteractive,
diff --git a/src/plugins/web-content-extractors.runtime.test.ts b/src/plugins/web-content-extractors.runtime.test.ts
@@ -1,3 +1,4 @@
+/** Tests runtime loading and sorting for plugin web content extractors. */
 import { describe, expect, it } from "vitest";
 import { resolvePluginWebContentExtractors } from "./web-content-extractors.runtime.js";
 

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/** Tests image asset parsing, MIME sniffing, and OpenAI-compatible response conversion. */`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import {`
`3`	`4`	`generatedImageAssetFromDataUrl,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/** Tests live image-generation helper parsing and provider selection. */`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import type { OpenClawConfig } from "../config/config.js";`
`3`	`4`	`import {`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/** Helpers for selecting image-generation providers and models in live tests. */`
`1`	`2`	`import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";`
`2`	`3`	`import type { OpenClawConfig } from "../config/types.openclaw.js";`
`3`	`4`	`import {`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/** Parses image-generation model references into provider/model components. */`
`1`	`2`	`import { parseGenerationModelRef } from "../../packages/media-generation-core/src/model-ref.js";`
`2`	`3`
`3`	`4`	`// Image model refs share the generic media-generation provider/model grammar:`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/** Tests OpenAI-compatible image provider request building and response handling. */`
`1`	`2`	`import { afterEach, describe, expect, it, vi } from "vitest";`
`2`	`3`	`import {`
`3`	`4`	`createOpenAiCompatibleImageGenerationProvider,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/** Tests image-generation provider registry aliases and plugin capability integration. */`
`1`	`2`	`import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";`
`2`	`3`	`import type { OpenClawConfig } from "../config/types.js";`
`3`	`4`	`import type { ImageGenerationProviderPlugin } from "../plugins/types.js";`