Skip to content

Commit 506c2ee

Browse files
steipetesteipete
committed
docs: document qa video gateway sdk contracts
1 parent 1e6fb50 commit 506c2ee

3 files changed

Lines changed: 28 additions & 0 deletions

File tree

‎src/plugin-sdk/qa-runner-runtime.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ import {
88
} from "./facade-runtime.js";
99
import { resolvePrivateQaBundledPluginsEnv } from "./private-qa-bundled-env.js";
1010

11+
/** CLI registration exported by a QA runner plugin runtime surface. */
1112
export type QaRunnerCliRegistration = {
1213
commandName: string;
1314
register(qa: Command): void;
@@ -28,6 +29,7 @@ type QaRuntimeSurface = {
2829
startQaLiveLaneGateway: (...args: unknown[]) => Promise<unknown>;
2930
};
3031

32+
/** Resolved QA runner CLI contribution declared by plugin manifest metadata. */
3133
export type QaRunnerCliContribution =
3234
| {
3335
pluginId: string;
@@ -54,6 +56,7 @@ function isMissingQaRuntimeError(error: unknown) {
5456
);
5557
}
5658

59+
/** Load the private QA Lab runtime facade used by QA runner commands. */
5760
export function loadQaRuntimeModule(): QaRuntimeSurface {
5861
const env = resolvePrivateQaBundledPluginsEnv();
5962
return loadBundledPluginPublicSurfaceModuleSync<QaRuntimeSurface>({
@@ -64,6 +67,7 @@ export function loadQaRuntimeModule(): QaRuntimeSurface {
6467
}
6568

6669
// oxlint-disable-next-line typescript/no-unnecessary-type-parameters -- QA runtime loader uses caller-supplied test API surface type.
70+
/** Load a bundled QA runner plugin test API facade by plugin id. */
6771
export function loadQaRunnerBundledPluginTestApi<T extends object>(pluginId: string): T {
6872
const env = resolvePrivateQaBundledPluginsEnv();
6973
return loadBundledPluginPublicSurfaceModuleSync<T>({
@@ -73,6 +77,7 @@ export function loadQaRunnerBundledPluginTestApi<T extends object>(pluginId: str
7377
});
7478
}
7579

80+
/** Returns whether the private QA Lab runtime facade is available in this build. */
7681
export function isQaRuntimeAvailable(): boolean {
7782
try {
7883
loadQaRuntimeModule();
@@ -147,6 +152,7 @@ function loadQaRunnerRuntimeSurface(
147152
});
148153
}
149154

155+
/** List QA runner CLI contributions declared by manifests and backed by runtime registrations. */
150156
export function listQaRunnerCliContributions(): readonly QaRunnerCliContribution[] {
151157
const env = resolvePrivateQaBundledPluginsEnv();
152158
const contributions = new Map<string, QaRunnerCliContribution>();

‎src/plugin-sdk/vercel-ai-gateway.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,36 +26,46 @@ function loadFacadeModule(): FacadeModule {
2626
artifactBasename: "api.js",
2727
});
2828
}
29+
/** Build the Vercel AI Gateway provider config through the bundled provider facade. */
2930
export const buildVercelAiGatewayProvider: FacadeModule["buildVercelAiGatewayProvider"] = ((
3031
...args
3132
) =>
3233
loadFacadeModule()["buildVercelAiGatewayProvider"](
3334
...args,
3435
)) as FacadeModule["buildVercelAiGatewayProvider"];
36+
/** Discover Vercel AI Gateway models through the bundled provider facade. */
3537
export const discoverVercelAiGatewayModels: FacadeModule["discoverVercelAiGatewayModels"] = ((
3638
...args
3739
) =>
3840
loadFacadeModule()["discoverVercelAiGatewayModels"](
3941
...args,
4042
)) as FacadeModule["discoverVercelAiGatewayModels"];
43+
/** Return the static Vercel AI Gateway model catalog used before live discovery. */
4144
export const getStaticVercelAiGatewayModelCatalog: FacadeModule["getStaticVercelAiGatewayModelCatalog"] =
4245
((...args) =>
4346
loadFacadeModule()["getStaticVercelAiGatewayModelCatalog"](
4447
...args,
4548
)) as FacadeModule["getStaticVercelAiGatewayModelCatalog"];
49+
/** Default Vercel AI Gateway base URL. */
4650
export const VERCEL_AI_GATEWAY_BASE_URL: FacadeModule["VERCEL_AI_GATEWAY_BASE_URL"] =
4751
loadFacadeModule()["VERCEL_AI_GATEWAY_BASE_URL"];
52+
/** Default context window assigned to Vercel AI Gateway models without catalog metadata. */
4853
export const VERCEL_AI_GATEWAY_DEFAULT_CONTEXT_WINDOW: FacadeModule["VERCEL_AI_GATEWAY_DEFAULT_CONTEXT_WINDOW"] =
4954
loadFacadeModule()["VERCEL_AI_GATEWAY_DEFAULT_CONTEXT_WINDOW"];
55+
/** Default cost metadata assigned to Vercel AI Gateway models without catalog metadata. */
5056
export const VERCEL_AI_GATEWAY_DEFAULT_COST: FacadeModule["VERCEL_AI_GATEWAY_DEFAULT_COST"] =
5157
createLazyFacadeObjectValue(
5258
() => loadFacadeModule()["VERCEL_AI_GATEWAY_DEFAULT_COST"] as object,
5359
) as FacadeModule["VERCEL_AI_GATEWAY_DEFAULT_COST"];
60+
/** Default max-token value assigned to Vercel AI Gateway models without catalog metadata. */
5461
export const VERCEL_AI_GATEWAY_DEFAULT_MAX_TOKENS: FacadeModule["VERCEL_AI_GATEWAY_DEFAULT_MAX_TOKENS"] =
5562
loadFacadeModule()["VERCEL_AI_GATEWAY_DEFAULT_MAX_TOKENS"];
63+
/** Default Vercel AI Gateway model id used by setup flows. */
5664
export const VERCEL_AI_GATEWAY_DEFAULT_MODEL_ID: FacadeModule["VERCEL_AI_GATEWAY_DEFAULT_MODEL_ID"] =
5765
loadFacadeModule()["VERCEL_AI_GATEWAY_DEFAULT_MODEL_ID"];
66+
/** Default Vercel AI Gateway provider/model reference written by setup flows. */
5867
export const VERCEL_AI_GATEWAY_DEFAULT_MODEL_REF: FacadeModule["VERCEL_AI_GATEWAY_DEFAULT_MODEL_REF"] =
5968
loadFacadeModule()["VERCEL_AI_GATEWAY_DEFAULT_MODEL_REF"];
69+
/** Provider id used for Vercel AI Gateway config and model refs. */
6070
export const VERCEL_AI_GATEWAY_PROVIDER_ID: FacadeModule["VERCEL_AI_GATEWAY_PROVIDER_ID"] =
6171
loadFacadeModule()["VERCEL_AI_GATEWAY_PROVIDER_ID"];

‎src/plugin-sdk/video-generation.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ import type {
2222
VideoGenerationTransformCapabilities as CoreVideoGenerationTransformCapabilities,
2323
} from "../video-generation/types.js";
2424

25+
/** Video asset returned by a provider after generation or transformation. */
2526
export type GeneratedVideoAsset = {
2627
/** Raw video bytes. Either buffer or url must be present. */
2728
buffer?: Buffer;
@@ -34,6 +35,7 @@ export type GeneratedVideoAsset = {
3435
metadata?: Record<string, unknown>;
3536
};
3637

38+
/** Resolution label accepted by video generation providers. */
3739
export type VideoGenerationResolution =
3840
| "360P"
3941
| "480P"
@@ -55,6 +57,7 @@ export type VideoGenerationAssetRole =
5557
| "reference_video"
5658
| "reference_audio";
5759

60+
/** Source media asset supplied to image/video/audio-to-video providers. */
5861
export type VideoGenerationSourceAsset = {
5962
url?: string;
6063
buffer?: Buffer;
@@ -69,11 +72,13 @@ export type VideoGenerationSourceAsset = {
6972
metadata?: Record<string, unknown>;
7073
};
7174

75+
/** Context passed when checking whether a video provider is configured. */
7276
export type VideoGenerationProviderConfiguredContext = {
7377
cfg?: OpenClawConfig;
7478
agentDir?: string;
7579
};
7680

81+
/** Context passed when resolving model-specific video generation capabilities. */
7782
export type VideoGenerationModelCapabilitiesContext = {
7883
provider: string;
7984
model: string;
@@ -83,6 +88,7 @@ export type VideoGenerationModelCapabilitiesContext = {
8388
timeoutMs?: number;
8489
};
8590

91+
/** Normalized request object passed to a selected video generation provider. */
8692
export type VideoGenerationRequest = {
8793
provider: string;
8894
model: string;
@@ -105,12 +111,14 @@ export type VideoGenerationRequest = {
105111
providerOptions?: Record<string, unknown>;
106112
};
107113

114+
/** Provider video generation response returned to the runtime. */
108115
export type VideoGenerationResult = {
109116
videos: GeneratedVideoAsset[];
110117
model?: string;
111118
metadata?: Record<string, unknown>;
112119
};
113120

121+
/** Supported high-level video generation operation modes. */
114122
export type VideoGenerationMode = "generate" | "imageToVideo" | "videoToVideo";
115123

116124
/**
@@ -120,6 +128,7 @@ export type VideoGenerationMode = "generate" | "imageToVideo" | "videoToVideo";
120128
*/
121129
export type VideoGenerationProviderOptionType = "number" | "boolean" | "string";
122130

131+
/** Capability limits and supported options for one video generation mode. */
123132
export type VideoGenerationModeCapabilities = {
124133
maxVideos?: number;
125134
maxInputImages?: number;
@@ -150,16 +159,19 @@ export type VideoGenerationModeCapabilities = {
150159
providerOptions?: Readonly<Record<string, VideoGenerationProviderOptionType>>;
151160
};
152161

162+
/** Capability block for transform modes that may be independently enabled. */
153163
export type VideoGenerationTransformCapabilities = VideoGenerationModeCapabilities & {
154164
enabled: boolean;
155165
};
156166

167+
/** Full provider capability map including base and transform mode overrides. */
157168
export type VideoGenerationProviderCapabilities = VideoGenerationModeCapabilities & {
158169
generate?: VideoGenerationModeCapabilities;
159170
imageToVideo?: VideoGenerationTransformCapabilities;
160171
videoToVideo?: VideoGenerationTransformCapabilities;
161172
};
162173

174+
/** Video generation provider contract implemented by provider plugins. */
163175
export type VideoGenerationProvider = {
164176
id: string;
165177
aliases?: string[];

0 commit comments

Comments
 (0)