@fgv/ts-extras 5.1.0-18 → 5.1.0-19

package/lib/packlets/ai-assist/apiClient.js

@@ -92,6 +92,102 @@ async function fetchJson(url, headers, body, logger, signal) {
     }
     return (0, ts_utils_1.succeed)(json);
 }
+/**
+ * Makes a multipart/form-data POST request and returns the parsed JSON, or a
+ * failure. The Content-Type header (with boundary) is set automatically by
+ * `fetch` from the `FormData` body — callers must NOT pass it explicitly.
+ * @internal
+ */
+async function fetchMultipart(url, headers, body, logger, signal) {
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.detail(`AI API request: POST ${url} (multipart)`);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            headers,
+            body,
+            signal
+        });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.error(`AI API request failed: ${detail}`);
+        return (0, ts_utils_1.fail)(`AI API request failed: ${detail}`);
+    }
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => 'unknown error');
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.error(`AI API returned ${response.status}: ${errorText}`);
+        return (0, ts_utils_1.fail)(`AI API returned ${response.status}: ${errorText}`);
+    }
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.detail(`AI API response: ${response.status}`);
+    let json;
+    try {
+        json = await response.json();
+    }
+    catch (_a) {
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.error('AI API returned invalid JSON response');
+        return (0, ts_utils_1.fail)('AI API returned invalid JSON response');
+    }
+    if (!(0, ts_json_base_1.isJsonObject)(json)) {
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.error('AI API returned non-object JSON response');
+        return (0, ts_utils_1.fail)('AI API returned non-object JSON response');
+    }
+    return (0, ts_utils_1.succeed)(json);
+}
+/**
+ * Decodes a base64-encoded image attachment into a `Blob` suitable for use as
+ * a multipart file field. On Node hands the `Buffer` straight to `Blob`
+ * (Buffer extends Uint8Array) to skip an intermediate copy; falls back to
+ * `atob` in browsers. Inputs come from `FileReader` or prior provider
+ * responses, which are trusted to be valid. Note that Node's
+ * `Buffer.from(..., 'base64')` silently strips invalid characters rather
+ * than throwing, so failures are only observable in the browser path.
+ * @internal
+ */
+function attachmentToBlob(attachment) {
+    if (typeof Buffer !== 'undefined') {
+        return (0, ts_utils_1.succeed)(new Blob([Buffer.from(attachment.base64, 'base64')], { type: attachment.mimeType }));
+    }
+    /* c8 ignore start - Browser-only fallback cannot be tested in Node.js environment */
+    try {
+        const binary = atob(attachment.base64);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++) {
+            bytes[i] = binary.charCodeAt(i);
+        }
+        return (0, ts_utils_1.succeed)(new Blob([bytes], { type: attachment.mimeType }));
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        return (0, ts_utils_1.fail)(`Invalid base64: ${message}`);
+    }
+    /* c8 ignore stop */
+}
+/**
+ * Maps a MIME type to a sensible file extension for multipart filenames.
+ * @internal
+ */
+function extensionForMimeType(mimeType) {
+    switch (mimeType) {
+        case 'image/png':
+            return 'png';
+        case 'image/jpeg':
+        case 'image/jpg':
+            return 'jpg';
+        case 'image/webp':
+            return 'webp';
+        case 'image/gif':
+            return 'gif';
+        default:
+            return 'bin';
+    }
+}
 /**
  * Makes an HTTP GET request and returns the parsed JSON, or a failure.
  * @internal
@@ -465,6 +561,24 @@ const imagenPrediction = ts_utils_1.Validators.object({
 const imagenResponse = ts_utils_1.Validators.object({
     predictions: ts_utils_1.Validators.arrayOf(imagenPrediction).withConstraint((arr) => arr.length > 0)
 });
+const geminiImageInlineData = ts_utils_1.Validators.object({
+    mimeType: ts_utils_1.Validators.string,
+    data: ts_utils_1.Validators.string
+});
+const geminiImageOutPart = ts_utils_1.Validators.object({
+    text: ts_utils_1.Validators.string.optional(),
+    inlineData: geminiImageInlineData.optional()
+});
+const geminiImageOutContent = ts_utils_1.Validators.object({
+    parts: ts_utils_1.Validators.arrayOf(geminiImageOutPart).withConstraint((arr) => arr.length > 0)
+});
+const geminiImageOutCandidate = ts_utils_1.Validators.object({
+    content: geminiImageOutContent,
+    finishReason: ts_utils_1.Validators.string.optional()
+});
+const geminiImageOutResponse = ts_utils_1.Validators.object({
+    candidates: ts_utils_1.Validators.arrayOf(geminiImageOutCandidate).withConstraint((arr) => arr.length > 0)
+});
 // ---- Proxied image generation response ----
 const proxiedGeneratedImage = ts_utils_1.Validators.object({
     mimeType: ts_utils_1.Validators.string,
@@ -490,16 +604,42 @@ const proxiedListModelsResponse = ts_utils_1.Validators.object({
  * formats — the request shape is the same; the only difference is whether the
  * `size` field is honored (OpenAI: yes, xAI: ignored at the provider).
  *
+ * When `request.referenceImages` is non-empty, routes to `/images/edits`
+ * (multipart) instead of `/images/generations` (JSON). Per-model edit support
+ * is not validated here (e.g. dall-e-3 does not support edits) — the
+ * provider's 400 surfaces through the failure path.
+ *
  * @internal
  */
 async function callOpenAiImageGeneration(config, request, defaultMimeType, logger, signal) {
-    var _a, _b;
-    const url = `${config.baseUrl}/images/generations`;
+    var _a, _b, _c;
+    const opts = (_a = request.options) !== null && _a !== void 0 ? _a : {};
+    const refs = (_b = request.referenceImages) !== null && _b !== void 0 ? _b : [];
+    const headers = {
+        Authorization: `Bearer ${config.apiKey}`
+    };
+    const n = (_c = opts.count) !== null && _c !== void 0 ? _c : 1;
+    const fetched = refs.length > 0
+        ? await callOpenAiImagesEdits(config, request, headers, n, refs, logger, signal)
+        : await callOpenAiImagesGenerations(config, request, headers, n, logger, signal);
+    return fetched.onSuccess((json) => openAiImageResponse
+        .validate(json)
+        .withErrorFormat((msg) => `OpenAI images API response: ${msg}`)
+        .onSuccess((response) => (0, ts_utils_1.succeed)({
+        images: response.data.map((item) => (Object.assign({ mimeType: defaultMimeType, base64: item.b64_json }, (item.revised_prompt !== undefined ? { revisedPrompt: item.revised_prompt } : {}))))
+    })));
+}
+/**
+ * Builds and posts the JSON `/images/generations` request (no refs).
+ * @internal
+ */
+function callOpenAiImagesGenerations(config, request, headers, n, logger, signal) {
+    var _a;
     const opts = (_a = request.options) !== null && _a !== void 0 ? _a : {};
     const body = {
         model: config.model,
         prompt: request.prompt,
-        n: (_b = opts.count) !== null && _b !== void 0 ? _b : 1,
+        n,
         response_format: 'b64_json'
     };
     if (opts.size !== undefined) {
@@ -511,22 +651,86 @@ async function callOpenAiImageGeneration(config, request, defaultMimeType, logge
     if (opts.seed !== undefined) {
         body.seed = opts.seed;
     }
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`Image generation: model=${config.model}, n=${n}`);
+    return fetchJson(`${config.baseUrl}/images/generations`, headers, body, logger, signal);
+}
+/**
+ * Builds and posts the multipart `/images/edits` request (with refs).
+ * @internal
+ */
+async function callOpenAiImagesEdits(config, request, headers, n, refs, logger, signal) {
+    var _a;
+    const blobsResult = (0, ts_utils_1.mapResults)(refs.map((ref, i) => attachmentToBlob(ref).withErrorFormat((msg) => `reference image ${i}: ${msg}`)));
+    /* c8 ignore next 3 - decode failure unreachable via Node's Buffer.from (silently strips invalid input) */
+    if (blobsResult.isFailure()) {
+        return (0, ts_utils_1.fail)(blobsResult.message);
+    }
+    const opts = (_a = request.options) !== null && _a !== void 0 ? _a : {};
+    const form = new FormData();
+    form.append('model', config.model);
+    form.append('prompt', request.prompt);
+    form.append('n', String(n));
+    form.append('response_format', 'b64_json');
+    if (opts.size !== undefined) {
+        form.append('size', opts.size);
+    }
+    if (opts.quality !== undefined) {
+        form.append('quality', opts.quality);
+    }
+    if (opts.seed !== undefined) {
+        form.append('seed', String(opts.seed));
+    }
+    blobsResult.value.forEach((blob, i) => {
+        form.append('image[]', blob, `ref-${i}.${extensionForMimeType(refs[i].mimeType)}`);
+    });
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`Image edit: model=${config.model}, n=${n}, refs=${refs.length}`);
+    return fetchMultipart(`${config.baseUrl}/images/edits`, headers, form, logger, signal);
+}
+/**
+ * Calls Gemini's chat-style `:generateContent` endpoint for image output
+ * (Gemini 2.5 Flash Image / "Nano Banana"). Accepts reference images, which
+ * are passed as `inlineData` parts alongside the text prompt.
+ *
+ * @internal
+ */
+async function callGeminiImageOutGeneration(config, request, logger, signal) {
+    var _a;
+    const url = `${config.baseUrl}/models/${config.model}:generateContent`;
+    const refs = (_a = request.referenceImages) !== null && _a !== void 0 ? _a : [];
+    const parts = [{ text: request.prompt }];
+    for (const ref of refs) {
+        parts.push({ inlineData: { mimeType: ref.mimeType, data: ref.base64 } });
+    }
+    const body = {
+        contents: [{ role: 'user', parts }]
+    };
     const headers = {
-        Authorization: `Bearer ${config.apiKey}`
+        'x-goog-api-key': config.apiKey
     };
     /* c8 ignore next 1 - optional logger */
-    logger === null || logger === void 0 ? void 0 : logger.info(`Image generation: model=${config.model}, n=${body.n}`);
-    const jsonResult = await fetchJson(url, headers, body, logger, signal);
-    if (jsonResult.isFailure()) {
-        return (0, ts_utils_1.fail)(jsonResult.message);
-    }
-    return openAiImageResponse
-        .validate(jsonResult.value)
-        .withErrorFormat((msg) => `OpenAI images API response: ${msg}`)
+    logger === null || logger === void 0 ? void 0 : logger.info(`Gemini image-out: model=${config.model}, refs=${refs.length}`);
+    return (await fetchJson(url, headers, body, logger, signal)).onSuccess((json) => geminiImageOutResponse
+        .validate(json)
+        .withErrorFormat((msg) => `Gemini image API response: ${msg}`)
         .onSuccess((response) => {
-        const images = response.data.map((item) => (Object.assign({ mimeType: defaultMimeType, base64: item.b64_json }, (item.revised_prompt !== undefined ? { revisedPrompt: item.revised_prompt } : {}))));
+        const images = [];
+        for (const candidate of response.candidates) {
+            for (const part of candidate.content.parts) {
+                if (part.inlineData) {
+                    images.push({
+                        mimeType: part.inlineData.mimeType,
+                        base64: part.inlineData.data
+                    });
+                }
+            }
+        }
+        if (images.length === 0) {
+            return (0, ts_utils_1.fail)('Gemini image API response: no image parts in response');
+        }
         return (0, ts_utils_1.succeed)({ images });
-    });
+    }));
 }
 /**
  * Calls the Gemini Imagen `:predict` endpoint.
@@ -581,45 +785,61 @@ async function callImagenGeneration(config, request, logger, signal) {
 /**
  * Calls the appropriate image-generation API for a given provider.
  *
- * Routes based on `descriptor.imageApiFormat`:
+ * Resolves a {@link IAiImageModelCapability} from
+ * {@link IAiProviderDescriptor.imageGeneration} for the requested model and
+ * routes by its `format`:
  * - `'openai-images'` for OpenAI (DALL-E, gpt-image-1)
  * - `'xai-images'` for xAI Grok image models
- * - `'gemini-imagen'` for Google Imagen
+ * - `'gemini-imagen'` for Google Imagen `:predict`
+ * - `'gemini-image-out'` for Gemini chat-style image output (Nano Banana)
  *
  * Image-model selection reuses the existing `'image'` {@link ModelSpecKey}.
+ * When `request.referenceImages` is non-empty, the call is rejected up front
+ * unless the resolved capability declares `acceptsImageReferenceInput`.
  *
  * @param params - Request parameters including descriptor, API key, and prompt
  * @returns The generated images, or a failure
  * @public
  */
 async function callProviderImageGeneration(params) {
+    var _a, _b;
     const { descriptor, apiKey, params: request, modelOverride, logger, signal } = params;
-    if (descriptor.imageApiFormat === undefined) {
+    if (!(0, registry_1.supportsImageGeneration)(descriptor)) {
         return (0, ts_utils_1.fail)(`provider "${descriptor.id}" does not support image generation`);
     }
     if (!descriptor.baseUrl) {
         return (0, ts_utils_1.fail)(`provider "${descriptor.id}" has no API endpoint configured`);
     }
+    const model = (0, model_1.resolveModel)(modelOverride !== null && modelOverride !== void 0 ? modelOverride : descriptor.defaultModel, 'image');
+    const capability = (0, registry_1.resolveImageCapability)(descriptor, model);
+    if (capability === undefined) {
+        return (0, ts_utils_1.fail)(`provider "${descriptor.id}" does not support image generation for model "${model}"`);
+    }
+    if (((_b = (_a = request.referenceImages) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0) > 0 && !capability.acceptsImageReferenceInput) {
+        return (0, ts_utils_1.fail)(`model "${model}" does not support reference images`);
+    }
     const config = {
         baseUrl: descriptor.baseUrl,
         apiKey,
-        model: (0, model_1.resolveModel)(modelOverride !== null && modelOverride !== void 0 ? modelOverride : descriptor.defaultModel, 'image')
+        model
     };
     /* c8 ignore next 6 - optional logger diagnostic output */
     if (logger) {
-        logger.info(`AI image generation: provider=${descriptor.id}, format=${descriptor.imageApiFormat}, ` +
+        logger.info(`AI image generation: provider=${descriptor.id}, format=${capability.format}, ` +
             `model=${config.model}`);
     }
-    switch (descriptor.imageApiFormat) {
+    switch (capability.format) {
         case 'openai-images':
             return callOpenAiImageGeneration(config, request, 'image/png', logger, signal);
         case 'xai-images':
             return callOpenAiImageGeneration(config, request, 'image/jpeg', logger, signal);
         case 'gemini-imagen':
             return callImagenGeneration(config, request, logger, signal);
+        case 'gemini-image-out':
+            return callGeminiImageOutGeneration(config, request, logger, signal);
         /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
         default: {
-            const _exhaustive = descriptor.imageApiFormat;
+            const _exhaustive = capability.format;
             return (0, ts_utils_1.fail)(`unsupported image API format: ${String(_exhaustive)}`);
         }
     }
@@ -969,7 +1189,10 @@ async function callProxiedCompletion(proxyUrl, params) {
  * - Error response body: `{error: string}` (surfaced as `proxy: ${error}`)
  *
  * The proxy server is responsible for descriptor lookup, model resolution,
- * provider dispatch, and response normalization.
+ * provider dispatch, and response normalization. When `params.referenceImages`
+ * is present, the proxy is also responsible for repackaging it into the
+ * upstream wire format (e.g. multipart/form-data for OpenAI `/images/edits`,
+ * `inlineData` parts for Gemini `:generateContent`).
  *
  * @param proxyUrl - Base URL of the proxy server (e.g. `http://localhost:3001`)
  * @param params - Same parameters as {@link callProviderImageGeneration}

package/lib/packlets/ai-assist/index.d.ts

@@ -2,8 +2,8 @@
  * AI assist packlet - provider registry, prompt class, settings, and API client.
  * @packageDocumentation
  */
-export { AiPrompt, type AiModelCapability, type AiProviderId, type AiServerToolType, type AiServerToolConfig, type IAiWebSearchToolConfig, type IAiToolEnablement, type IAiCompletionResponse, type IChatMessage, type AiApiFormat, type AiImageApiFormat, type IAiProviderDescriptor, type IAiAssistProviderConfig, type IAiAssistSettings, DEFAULT_AI_ASSIST, type IAiAssistKeyStore, type IAiImageAttachment, type IAiImageData, type IAiImageGenerationOptions, type IAiImageGenerationParams, type IAiGeneratedImage, type IAiImageGenerationResponse, type IAiModelCapabilityRule, type IAiModelCapabilityConfig, type IAiModelInfo, type IAiStreamEvent, type IAiStreamTextDelta, type IAiStreamToolEvent, type IAiStreamDone, type IAiStreamError, type ModelSpec, type ModelSpecKey, type IModelSpecMap, allModelSpecKeys, MODEL_SPEC_BASE_KEY, resolveModel, toDataUrl } from './model';
-export { allProviderIds, getProviderDescriptors, getProviderDescriptor, DEFAULT_MODEL_CAPABILITY_CONFIG } from './registry';
+export { AiPrompt, type AiModelCapability, type AiProviderId, type AiServerToolType, type AiServerToolConfig, type IAiWebSearchToolConfig, type IAiToolEnablement, type IAiCompletionResponse, type IChatMessage, type AiApiFormat, type AiImageApiFormat, type IAiImageModelCapability, type IAiProviderDescriptor, type IAiAssistProviderConfig, type IAiAssistSettings, DEFAULT_AI_ASSIST, type IAiAssistKeyStore, type IAiImageAttachment, type IAiImageData, type IAiImageGenerationOptions, type IAiImageGenerationParams, type IAiGeneratedImage, type IAiImageGenerationResponse, type IAiModelCapabilityRule, type IAiModelCapabilityConfig, type IAiModelInfo, type IAiStreamEvent, type IAiStreamTextDelta, type IAiStreamToolEvent, type IAiStreamDone, type IAiStreamError, type ModelSpec, type ModelSpecKey, type IModelSpecMap, allModelSpecKeys, MODEL_SPEC_BASE_KEY, resolveModel, toDataUrl } from './model';
+export { allProviderIds, getProviderDescriptors, getProviderDescriptor, resolveImageCapability, supportsImageGeneration, DEFAULT_MODEL_CAPABILITY_CONFIG } from './registry';
 export { callProviderCompletion, callProxiedCompletion, callProviderImageGeneration, callProxiedImageGeneration, callProviderListModels, callProxiedListModels, type IProviderCompletionParams, type IProviderImageGenerationParams, type IProviderListModelsParams } from './apiClient';
 export { callProviderCompletionStream, callProxiedCompletionStream, type IProviderCompletionStreamParams } from './streamingClient';
 export { aiProviderId, aiServerToolType, aiWebSearchToolConfig, aiServerToolConfig, aiToolEnablement, aiAssistProviderConfig, aiAssistSettings, modelSpecKey, modelSpec } from './converters';

package/lib/packlets/ai-assist/index.js

@@ -4,7 +4,7 @@
  * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveEffectiveTools = exports.modelSpec = exports.modelSpecKey = exports.aiAssistSettings = exports.aiAssistProviderConfig = exports.aiToolEnablement = exports.aiServerToolConfig = exports.aiWebSearchToolConfig = exports.aiServerToolType = exports.aiProviderId = exports.callProxiedCompletionStream = exports.callProviderCompletionStream = exports.callProxiedListModels = exports.callProviderListModels = exports.callProxiedImageGeneration = exports.callProviderImageGeneration = exports.callProxiedCompletion = exports.callProviderCompletion = exports.DEFAULT_MODEL_CAPABILITY_CONFIG = exports.getProviderDescriptor = exports.getProviderDescriptors = exports.allProviderIds = exports.toDataUrl = exports.resolveModel = exports.MODEL_SPEC_BASE_KEY = exports.allModelSpecKeys = exports.DEFAULT_AI_ASSIST = exports.AiPrompt = void 0;
+exports.resolveEffectiveTools = exports.modelSpec = exports.modelSpecKey = exports.aiAssistSettings = exports.aiAssistProviderConfig = exports.aiToolEnablement = exports.aiServerToolConfig = exports.aiWebSearchToolConfig = exports.aiServerToolType = exports.aiProviderId = exports.callProxiedCompletionStream = exports.callProviderCompletionStream = exports.callProxiedListModels = exports.callProviderListModels = exports.callProxiedImageGeneration = exports.callProviderImageGeneration = exports.callProxiedCompletion = exports.callProviderCompletion = exports.DEFAULT_MODEL_CAPABILITY_CONFIG = exports.supportsImageGeneration = exports.resolveImageCapability = exports.getProviderDescriptor = exports.getProviderDescriptors = exports.allProviderIds = exports.toDataUrl = exports.resolveModel = exports.MODEL_SPEC_BASE_KEY = exports.allModelSpecKeys = exports.DEFAULT_AI_ASSIST = exports.AiPrompt = void 0;
 var model_1 = require("./model");
 Object.defineProperty(exports, "AiPrompt", { enumerable: true, get: function () { return model_1.AiPrompt; } });
 Object.defineProperty(exports, "DEFAULT_AI_ASSIST", { enumerable: true, get: function () { return model_1.DEFAULT_AI_ASSIST; } });
@@ -16,6 +16,8 @@ var registry_1 = require("./registry");
 Object.defineProperty(exports, "allProviderIds", { enumerable: true, get: function () { return registry_1.allProviderIds; } });
 Object.defineProperty(exports, "getProviderDescriptors", { enumerable: true, get: function () { return registry_1.getProviderDescriptors; } });
 Object.defineProperty(exports, "getProviderDescriptor", { enumerable: true, get: function () { return registry_1.getProviderDescriptor; } });
+Object.defineProperty(exports, "resolveImageCapability", { enumerable: true, get: function () { return registry_1.resolveImageCapability; } });
+Object.defineProperty(exports, "supportsImageGeneration", { enumerable: true, get: function () { return registry_1.supportsImageGeneration; } });
 Object.defineProperty(exports, "DEFAULT_MODEL_CAPABILITY_CONFIG", { enumerable: true, get: function () { return registry_1.DEFAULT_MODEL_CAPABILITY_CONFIG; } });
 var apiClient_1 = require("./apiClient");
 Object.defineProperty(exports, "callProviderCompletion", { enumerable: true, get: function () { return apiClient_1.callProviderCompletion; } });

package/lib/packlets/ai-assist/model.d.ts

@@ -194,9 +194,20 @@ export type AiProviderId = 'copy-paste' | 'xai-grok' | 'openai' | 'anthropic' |
 export type AiApiFormat = 'openai' | 'anthropic' | 'gemini';
 /**
  * API format categories for image-generation provider routing.
+ *
+ * @remarks
+ * - `'openai-images'` — OpenAI Images API. Routes to `/images/generations`
+ *   (text-only) or `/images/edits` (when reference images are present).
+ * - `'xai-images'` — xAI Images API. Same wire shape as OpenAI but text-only;
+ *   no reference-image support on grok-2-image.
+ * - `'gemini-imagen'` — Google Imagen `:predict` endpoint. Text-only.
+ * - `'gemini-image-out'` — Google Gemini chat-style `:generateContent`
+ *   endpoint that returns image parts (Gemini 2.5 Flash Image / "Nano
+ *   Banana"). Accepts reference images.
+ *
  * @public
  */
-export type AiImageApiFormat = 'openai-images' | 'gemini-imagen' | 'xai-images';
+export type AiImageApiFormat = 'openai-images' | 'gemini-imagen' | 'xai-images' | 'gemini-image-out';
 /**
  * Result of an AI provider completion call.
  * @public
@@ -309,15 +320,55 @@ export interface IAiProviderDescriptor {
      */
     readonly acceptsImageInput: boolean;
     /**
-     * Which image-generation API format this provider uses, or undefined if it
-     * does not support image generation.
+     * Image-generation capabilities, scoped to model id prefixes. Empty or
+     * undefined means the provider does not support image generation.
      *
      * @remarks
+     * The dispatcher matches the resolved model id against each rule's
+     * `modelPrefix` and selects the longest match (see
+     * {@link AiAssist.resolveImageCapability}). An empty `modelPrefix` is the
+     * catch-all and matches every model id.
+     *
+     * Multiple entries support providers that host more than one image-API
+     * surface under one baseUrl. Google Gemini is the canonical case: the
+     * `imagen-*` family is predict-only via `:predict`, while
+     * `gemini-2.5-flash-image` uses chat-style `:generateContent` and accepts
+     * reference images. Listing both lets callers pick the right model and the
+     * dispatcher routes accordingly.
+     *
      * Image-model selection reuses the existing `image` {@link ModelSpecKey}.
-     * Providers with `imageApiFormat` set should declare a model in
+     * Providers that declare `imageGeneration` should declare a model in
      * `defaultModel.image`, e.g. `{ base: 'gpt-4o', image: 'dall-e-3' }`.
      */
-    readonly imageApiFormat?: AiImageApiFormat;
+    readonly imageGeneration?: ReadonlyArray<IAiImageModelCapability>;
+}
+/**
+ * Image-generation capability for a model family within a provider. Used as
+ * an entry in {@link IAiProviderDescriptor.imageGeneration}.
+ *
+ * @public
+ */
+export interface IAiImageModelCapability {
+    /**
+     * Prefix matched against the resolved image model id. The empty string is
+     * the catch-all and matches every model. When multiple rules' prefixes
+     * match a model id, the longest prefix wins; ties are broken by
+     * first-encountered.
+     */
+    readonly modelPrefix: string;
+    /** API format used to dispatch requests for matching models. */
+    readonly format: AiImageApiFormat;
+    /**
+     * Whether matching models accept reference images via
+     * {@link AiAssist.IAiImageGenerationParams.referenceImages}. When false or
+     * undefined, calls that include reference images are rejected up front.
+     *
+     * @remarks
+     * Per-model constraints beyond ref support (e.g. dall-e-3 ignores edits)
+     * are not validated here and surface as provider 400s, consistent with the
+     * existing image-generation policy.
+     */
+    readonly acceptsImageReferenceInput?: boolean;
 }
 /**
  * Options for image generation requests.
@@ -366,6 +417,16 @@ export interface IAiImageGenerationParams {
     readonly prompt: string;
     /** Optional generation options. */
     readonly options?: IAiImageGenerationOptions;
+    /**
+     * Optional reference images. When present, the provider will use them as
+     * visual context (e.g. to preserve a character's appearance across multiple
+     * generations). The dispatcher resolves the
+     * {@link AiAssist.IAiImageModelCapability} for the requested model and
+     * rejects the call up front if `acceptsImageReferenceInput` is not set on
+     * the matching capability. An empty array is treated identically to
+     * `undefined`.
+     */
+    readonly referenceImages?: ReadonlyArray<IAiImageAttachment>;
 }
 /**
  * A single generated image.

package/lib/packlets/ai-assist/registry.d.ts

@@ -3,7 +3,7 @@
  * @packageDocumentation
  */
 import { Result } from '@fgv/ts-utils';
-import { type AiProviderId, type IAiModelCapabilityConfig, type IAiProviderDescriptor } from './model';
+import { type AiProviderId, type IAiImageModelCapability, type IAiModelCapabilityConfig, type IAiProviderDescriptor } from './model';
 /**
  * All valid provider ID values, in the same order as the registry.
  * @public
@@ -22,6 +22,30 @@ export declare function getProviderDescriptors(): ReadonlyArray<IAiProviderDescr
  * @public
  */
 export declare function getProviderDescriptor(id: string): Result<IAiProviderDescriptor>;
+/**
+ * Whether a provider declares any image-generation capability at all.
+ *
+ * @param descriptor - The provider descriptor
+ * @returns `true` when {@link IAiProviderDescriptor.imageGeneration} has at
+ *   least one entry; `false` otherwise.
+ * @public
+ */
+export declare function supportsImageGeneration(descriptor: IAiProviderDescriptor): boolean;
+/**
+ * Resolve the image-generation capability that applies to a given model id
+ * for a provider. Returns the entry from
+ * {@link IAiProviderDescriptor.imageGeneration} whose `modelPrefix` is the
+ * longest prefix of `modelId`. Ties are broken by first-encountered, so rule
+ * order does not matter for correctness — only for tie-breaking among rules
+ * with identical-length prefixes (an unusual case).
+ *
+ * @param descriptor - The provider descriptor
+ * @param modelId - The resolved image model id
+ * @returns The matching capability, or `undefined` when no rule matches or
+ *   the provider declares no image-generation capabilities.
+ * @public
+ */
+export declare function resolveImageCapability(descriptor: IAiProviderDescriptor, modelId: string): IAiImageModelCapability | undefined;
 /**
  * Default capability config used by `callProviderListModels` when callers
  * don't supply their own. Patterns are intentionally narrow — false

package/lib/packlets/ai-assist/registry.js

@@ -22,6 +22,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_MODEL_CAPABILITY_CONFIG = exports.allProviderIds = void 0;
 exports.getProviderDescriptors = getProviderDescriptors;
 exports.getProviderDescriptor = getProviderDescriptor;
+exports.supportsImageGeneration = supportsImageGeneration;
+exports.resolveImageCapability = resolveImageCapability;
 /**
  * Centralized provider registry — single source of truth for all AI provider metadata.
  * @packageDocumentation
@@ -68,12 +70,17 @@ const BUILTIN_PROVIDERS = [
         needsSecret: true,
         apiFormat: 'gemini',
         baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
-        defaultModel: { base: 'gemini-2.5-flash', image: 'imagen-3.0-generate-002' },
+        defaultModel: { base: 'gemini-2.5-flash', image: 'gemini-2.5-flash-image' },
         supportedTools: ['web_search'],
         corsRestricted: false,
         streamingCorsRestricted: false,
         acceptsImageInput: true,
-        imageApiFormat: 'gemini-imagen'
+        imageGeneration: [
+            // imagen-* models are predict-only and do not accept reference images;
+            // everything else uses chat-style :generateContent with refs.
+            { modelPrefix: 'imagen-', format: 'gemini-imagen' },
+            { modelPrefix: '', format: 'gemini-image-out', acceptsImageReferenceInput: true }
+        ]
     },
     {
         id: 'groq',
@@ -113,7 +120,14 @@ const BUILTIN_PROVIDERS = [
         corsRestricted: false,
         streamingCorsRestricted: false,
         acceptsImageInput: true,
-        imageApiFormat: 'openai-images'
+        imageGeneration: [
+            // gpt-image-1 supports /images/edits with reference images. dall-e-3
+            // (the default image model) does not, so the catch-all rule omits
+            // acceptsImageReferenceInput; callers selecting dall-e-3 with refs hit
+            // the up-front rejection rather than a provider 400.
+            { modelPrefix: 'gpt-image-', format: 'openai-images', acceptsImageReferenceInput: true },
+            { modelPrefix: '', format: 'openai-images' }
+        ]
     },
     {
         id: 'xai-grok',
@@ -131,7 +145,7 @@ const BUILTIN_PROVIDERS = [
         corsRestricted: true,
         streamingCorsRestricted: true,
         acceptsImageInput: true,
-        imageApiFormat: 'xai-images'
+        imageGeneration: [{ modelPrefix: '', format: 'xai-images' }]
     }
 ];
 /**
@@ -168,6 +182,38 @@ function getProviderDescriptor(id) {
     }
     return (0, ts_utils_1.succeed)(descriptor);
 }
+/**
+ * Whether a provider declares any image-generation capability at all.
+ *
+ * @param descriptor - The provider descriptor
+ * @returns `true` when {@link IAiProviderDescriptor.imageGeneration} has at
+ *   least one entry; `false` otherwise.
+ * @public
+ */
+function supportsImageGeneration(descriptor) {
+    var _a, _b;
+    return ((_b = (_a = descriptor.imageGeneration) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0) > 0;
+}
+/**
+ * Resolve the image-generation capability that applies to a given model id
+ * for a provider. Returns the entry from
+ * {@link IAiProviderDescriptor.imageGeneration} whose `modelPrefix` is the
+ * longest prefix of `modelId`. Ties are broken by first-encountered, so rule
+ * order does not matter for correctness — only for tie-breaking among rules
+ * with identical-length prefixes (an unusual case).
+ *
+ * @param descriptor - The provider descriptor
+ * @param modelId - The resolved image model id
+ * @returns The matching capability, or `undefined` when no rule matches or
+ *   the provider declares no image-generation capabilities.
+ * @public
+ */
+function resolveImageCapability(descriptor, modelId) {
+    var _a;
+    return ((_a = descriptor.imageGeneration) !== null && _a !== void 0 ? _a : [])
+        .filter((cap) => modelId.startsWith(cap.modelPrefix))
+        .reduce((best, cap) => (best && best.modelPrefix.length >= cap.modelPrefix.length ? best : cap), undefined);
+}
 // ============================================================================
 // Default model capability config
 // ============================================================================
@@ -196,6 +242,7 @@ exports.DEFAULT_MODEL_CAPABILITY_CONFIG = {
         ],
         'google-gemini': [
             { idPattern: /^imagen/, capabilities: ['image-generation'] },
+            { idPattern: /^gemini-.*-image/, capabilities: ['image-generation'] },
             { idPattern: /^gemini-/, capabilities: ['chat', 'tools', 'vision'] }
         ],
         anthropic: [{ idPattern: /^claude-/, capabilities: ['chat', 'tools', 'vision'] }],