@fgv/ts-extras 5.1.0-2 → 5.1.0-21

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

@@ -30,41 +30,77 @@
  * @packageDocumentation
  */
 import { isJsonObject } from '@fgv/ts-json-base';
-import { fail, succeed, Validators } from '@fgv/ts-utils';
+import { fail, mapResults, succeed, Validators } from '@fgv/ts-utils';
 import { resolveModel } from './model';
+import { buildAnthropicMessages, buildGeminiContents, buildMessages, buildOpenAiChatUserContent, buildOpenAiResponsesUserContent } from './chatRequestBuilders';
+import { bearerAuthHeader, resolveEffectiveBaseUrl } from './endpoint';
+import { DEFAULT_MODEL_CAPABILITY_CONFIG, resolveImageCapability, supportsImageGeneration } from './registry';
 import { toAnthropicTools, toGeminiTools, toResponsesApiTools } from './toolFormats';
 // ============================================================================
 // Shared helpers
 // ============================================================================
 /**
- * Builds the messages array from prompt + optional correction messages.
+ * Makes an HTTP request and returns the parsed JSON, or a failure.
  * @internal
  */
-function buildMessages(prompt, additionalMessages) {
-    const messages = [
-        { role: 'system', content: prompt.system },
-        { role: 'user', content: prompt.user }
-    ];
-    if (additionalMessages) {
-        for (const msg of additionalMessages) {
-            messages.push({ role: msg.role, content: msg.content });
-        }
+async function fetchJson(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}`);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            headers: Object.assign({ 'Content-Type': 'application/json' }, headers),
+            body: JSON.stringify(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 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 fail(`AI API returned ${response.status}: ${errorText}`);
     }
-    return messages;
+    /* 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 fail('AI API returned invalid JSON response');
+    }
+    if (!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 fail('AI API returned non-object JSON response');
+    }
+    return succeed(json);
 }
 /**
- * Makes an HTTP request and returns the parsed JSON, or a failure.
+ * 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 fetchJson(url, headers, body, logger) {
+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}`);
+    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: Object.assign({ 'Content-Type': 'application/json' }, headers),
-            body: JSON.stringify(body)
+            headers,
+            body,
+            signal
         });
     }
     catch (err) {
@@ -97,6 +133,95 @@ async function fetchJson(url, headers, body, logger) {
     }
     return 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 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 succeed(new Blob([bytes], { type: attachment.mimeType }));
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        return 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
+ */
+async function fetchGetJson(url, headers, logger, signal) {
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.detail(`AI API request: GET ${url}`);
+    let response;
+    try {
+        response = await fetch(url, { method: 'GET', headers, 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 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 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 fail('AI API returned invalid JSON response');
+    }
+    if (!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 fail('AI API returned non-object JSON response');
+    }
+    return succeed(json);
+}
 const openAiMessage = Validators.object({
     content: Validators.string
 });
@@ -149,16 +274,16 @@ const geminiResponse = Validators.object({
  * Works for xAI Grok, OpenAI, Groq, and Mistral.
  * @internal
  */
-async function callOpenAiCompletion(config, prompt, additionalMessages, temperature = 0.7, logger) {
+async function callOpenAiCompletion(config, prompt, additionalMessages, temperature = 0.7, logger, signal) {
     const url = `${config.baseUrl}/chat/completions`;
-    const messages = buildMessages(prompt, additionalMessages);
+    const messages = buildMessages(prompt.system, buildOpenAiChatUserContent(prompt), {
+        tail: additionalMessages
+    });
     const body = { model: config.model, messages, temperature };
-    const headers = {
-        Authorization: `Bearer ${config.apiKey}`
-    };
+    const headers = bearerAuthHeader(config.apiKey);
     /* c8 ignore next 1 - optional logger */
     logger === null || logger === void 0 ? void 0 : logger.info(`OpenAI completion: model=${config.model}`);
-    const jsonResult = await fetchJson(url, headers, body, logger);
+    const jsonResult = await fetchJson(url, headers, body, logger, signal);
     if (jsonResult.isFailure()) {
         return fail(jsonResult.message);
     }
@@ -197,21 +322,21 @@ function extractResponsesApiText(output) {
  * Used when tools are configured for an openai-format provider.
  * @internal
  */
-async function callOpenAiResponsesCompletion(config, prompt, tools, additionalMessages, temperature = 0.7, logger) {
+async function callOpenAiResponsesCompletion(config, prompt, tools, additionalMessages, temperature = 0.7, logger, signal) {
     const url = `${config.baseUrl}/responses`;
-    const input = buildMessages(prompt, additionalMessages);
+    const input = buildMessages(prompt.system, buildOpenAiResponsesUserContent(prompt), {
+        tail: additionalMessages
+    });
     const body = {
         model: config.model,
         input,
         tools: toResponsesApiTools(tools),
         temperature
     };
-    const headers = {
-        Authorization: `Bearer ${config.apiKey}`
-    };
+    const headers = bearerAuthHeader(config.apiKey);
     /* c8 ignore next 1 - optional logger */
     logger === null || logger === void 0 ? void 0 : logger.info(`OpenAI Responses API: model=${config.model}, tools=${tools.map((t) => t.type).join(',')}`);
-    const jsonResult = await fetchJson(url, headers, body, logger);
+    const jsonResult = await fetchJson(url, headers, body, logger, signal);
     if (jsonResult.isFailure()) {
         return fail(jsonResult.message);
     }
@@ -256,18 +381,10 @@ function extractAnthropicText(content) {
  * mixed content block responses.
  * @internal
  */
-async function callAnthropicCompletion(config, prompt, additionalMessages, temperature = 0.7, logger, tools) {
+async function callAnthropicCompletion(config, prompt, additionalMessages, temperature = 0.7, logger, tools, signal) {
     const url = `${config.baseUrl}/messages`;
     // Anthropic uses system as a top-level field, not in messages
-    const messages = [{ role: 'user', content: prompt.user }];
-    if (additionalMessages) {
-        for (const msg of additionalMessages) {
-            // Anthropic doesn't have a system role in messages
-            if (msg.role !== 'system') {
-                messages.push({ role: msg.role, content: msg.content });
-            }
-        }
-    }
+    const messages = buildAnthropicMessages(prompt, { tail: additionalMessages });
     const body = {
         model: config.model,
         system: prompt.system,
@@ -289,7 +406,7 @@ async function callAnthropicCompletion(config, prompt, additionalMessages, tempe
         'anthropic-version': '2023-06-01',
         'anthropic-dangerous-direct-browser-access': 'true'
     };
-    const jsonResult = await fetchJson(url, headers, body, logger);
+    const jsonResult = await fetchJson(url, headers, body, logger, signal);
     if (jsonResult.isFailure()) {
         return fail(jsonResult.message);
     }
@@ -324,22 +441,10 @@ async function callAnthropicCompletion(config, prompt, additionalMessages, tempe
  * When tools are configured, includes Google Search grounding.
  * @internal
  */
-async function callGeminiCompletion(config, prompt, additionalMessages, temperature = 0.7, logger, tools) {
+async function callGeminiCompletion(config, prompt, additionalMessages, temperature = 0.7, logger, tools, signal) {
     const url = `${config.baseUrl}/models/${config.model}:generateContent`;
     // Gemini uses 'contents' with 'parts', and 'model' role instead of 'assistant'
-    const contents = [
-        { role: 'user', parts: [{ text: prompt.user }] }
-    ];
-    if (additionalMessages) {
-        for (const msg of additionalMessages) {
-            if (msg.role !== 'system') {
-                contents.push({
-                    role: msg.role === 'assistant' ? 'model' : msg.role,
-                    parts: [{ text: msg.content }]
-                });
-            }
-        }
-    }
+    const contents = buildGeminiContents(prompt, { tail: additionalMessages });
     const body = {
         systemInstruction: { parts: [{ text: prompt.system }] },
         contents,
@@ -357,7 +462,7 @@ async function callGeminiCompletion(config, prompt, additionalMessages, temperat
     const headers = {
         'x-goog-api-key': config.apiKey
     };
-    const jsonResult = await fetchJson(url, headers, body, logger);
+    const jsonResult = await fetchJson(url, headers, body, logger, signal);
     if (jsonResult.isFailure()) {
         return fail(jsonResult.message);
     }
@@ -393,16 +498,24 @@ async function callGeminiCompletion(config, prompt, additionalMessages, temperat
  * @public
  */
 export async function callProviderCompletion(params) {
-    const { descriptor, apiKey, prompt, additionalMessages, temperature = 0.7, modelOverride, logger, tools } = params;
-    if (!descriptor.baseUrl) {
-        return fail(`provider "${descriptor.id}" has no API endpoint configured`);
+    const { descriptor, apiKey, prompt, additionalMessages, temperature = 0.7, modelOverride, logger, tools, signal, endpoint } = params;
+    const baseUrlResult = resolveEffectiveBaseUrl(descriptor, endpoint);
+    if (baseUrlResult.isFailure()) {
+        return fail(baseUrlResult.message);
+    }
+    if (prompt.attachments.length > 0 && !descriptor.acceptsImageInput) {
+        return fail(`provider "${descriptor.id}" does not accept image input`);
     }
     const hasTools = tools !== undefined && tools.length > 0;
     const modelContext = hasTools ? 'tools' : undefined;
+    const model = resolveModel(modelOverride !== null && modelOverride !== void 0 ? modelOverride : descriptor.defaultModel, modelContext);
+    if (model.length === 0) {
+        return fail(`provider "${descriptor.id}": no model resolved; pass modelOverride or set descriptor.defaultModel`);
+    }
     const config = {
-        baseUrl: descriptor.baseUrl,
+        baseUrl: baseUrlResult.value,
         apiKey,
-        model: resolveModel(modelOverride !== null && modelOverride !== void 0 ? modelOverride : descriptor.defaultModel, modelContext)
+        model
     };
     /* c8 ignore next 8 - optional logger diagnostic output */
     if (logger) {
@@ -414,13 +527,13 @@ export async function callProviderCompletion(params) {
     switch (descriptor.apiFormat) {
         case 'openai':
             if (hasTools) {
-                return callOpenAiResponsesCompletion(config, prompt, tools, additionalMessages, temperature, logger);
+                return callOpenAiResponsesCompletion(config, prompt, tools, additionalMessages, temperature, logger, signal);
             }
-            return callOpenAiCompletion(config, prompt, additionalMessages, temperature, logger);
+            return callOpenAiCompletion(config, prompt, additionalMessages, temperature, logger, signal);
         case 'anthropic':
-            return callAnthropicCompletion(config, prompt, additionalMessages, temperature, logger, tools);
+            return callAnthropicCompletion(config, prompt, additionalMessages, temperature, logger, tools, signal);
         case 'gemini':
-            return callGeminiCompletion(config, prompt, additionalMessages, temperature, logger, tools);
+            return callGeminiCompletion(config, prompt, additionalMessages, temperature, logger, tools, signal);
         /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
         default: {
             const _exhaustive = descriptor.apiFormat;
@@ -428,6 +541,579 @@ export async function callProviderCompletion(params) {
         }
     }
 }
+const openAiImageItem = Validators.object({
+    b64_json: Validators.string,
+    revised_prompt: Validators.string.optional()
+});
+const openAiImageResponse = Validators.object({
+    data: Validators.arrayOf(openAiImageItem).withConstraint((arr) => arr.length > 0)
+});
+const imagenPrediction = Validators.object({
+    bytesBase64Encoded: Validators.string,
+    mimeType: Validators.string.optional()
+});
+const imagenResponse = Validators.object({
+    predictions: Validators.arrayOf(imagenPrediction).withConstraint((arr) => arr.length > 0)
+});
+const geminiImageInlineData = Validators.object({
+    mimeType: Validators.string,
+    data: Validators.string
+});
+const geminiImageOutPart = Validators.object({
+    text: Validators.string.optional(),
+    inlineData: geminiImageInlineData.optional()
+});
+const geminiImageOutContent = Validators.object({
+    parts: Validators.arrayOf(geminiImageOutPart).withConstraint((arr) => arr.length > 0)
+});
+const geminiImageOutCandidate = Validators.object({
+    content: geminiImageOutContent,
+    finishReason: Validators.string.optional()
+});
+const geminiImageOutResponse = Validators.object({
+    candidates: Validators.arrayOf(geminiImageOutCandidate).withConstraint((arr) => arr.length > 0)
+});
+// ---- Proxied image generation response ----
+const proxiedGeneratedImage = Validators.object({
+    mimeType: Validators.string,
+    base64: Validators.string,
+    revisedPrompt: Validators.string.optional()
+});
+const proxiedImageGenerationResponse = Validators.object({
+    images: Validators.arrayOf(proxiedGeneratedImage).withConstraint((arr) => arr.length > 0)
+});
+const proxiedListModelsEntry = Validators.object({
+    id: Validators.string,
+    capabilities: Validators.arrayOf(Validators.enumeratedValue(['chat', 'tools', 'vision', 'image-generation'])),
+    displayName: Validators.string.optional()
+});
+const proxiedListModelsResponse = Validators.object({
+    models: Validators.arrayOf(proxiedListModelsEntry)
+});
+// ============================================================================
+// Image generation — adapters
+// ============================================================================
+/**
+ * Calls the OpenAI Images API. Used for both `openai-images` and `xai-images`
+ * 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, _c;
+    const opts = (_a = request.options) !== null && _a !== void 0 ? _a : {};
+    const refs = (_b = request.referenceImages) !== null && _b !== void 0 ? _b : [];
+    const headers = bearerAuthHeader(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) => 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,
+        response_format: 'b64_json'
+    };
+    if (opts.size !== undefined) {
+        body.size = opts.size;
+    }
+    if (opts.quality !== undefined) {
+        body.quality = opts.quality;
+    }
+    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 = 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 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 = {
+        'x-goog-api-key': config.apiKey
+    };
+    /* c8 ignore next 1 - optional logger */
+    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 = [];
+        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 fail('Gemini image API response: no image parts in response');
+        }
+        return succeed({ images });
+    }));
+}
+/**
+ * Calls the Gemini Imagen `:predict` endpoint.
+ * @internal
+ */
+async function callImagenGeneration(config, request, logger, signal) {
+    var _a, _b, _c, _d;
+    const url = `${config.baseUrl}/models/${config.model}:predict`;
+    const opts = (_a = request.options) !== null && _a !== void 0 ? _a : {};
+    const parameters = {
+        sampleCount: (_b = opts.count) !== null && _b !== void 0 ? _b : 1
+    };
+    if (((_c = opts.imagen) === null || _c === void 0 ? void 0 : _c.aspectRatio) !== undefined) {
+        parameters.aspectRatio = opts.imagen.aspectRatio;
+    }
+    if (((_d = opts.imagen) === null || _d === void 0 ? void 0 : _d.negativePrompt) !== undefined) {
+        parameters.negativePrompt = opts.imagen.negativePrompt;
+    }
+    if (opts.seed !== undefined) {
+        parameters.seed = opts.seed;
+    }
+    const body = {
+        instances: [{ prompt: request.prompt }],
+        parameters
+    };
+    const headers = {
+        'x-goog-api-key': config.apiKey
+    };
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`Imagen generation: model=${config.model}, n=${parameters.sampleCount}`);
+    const jsonResult = await fetchJson(url, headers, body, logger, signal);
+    if (jsonResult.isFailure()) {
+        return fail(jsonResult.message);
+    }
+    return imagenResponse
+        .validate(jsonResult.value)
+        .withErrorFormat((msg) => `Imagen API response: ${msg}`)
+        .onSuccess((response) => {
+        const images = response.predictions.map((p) => {
+            var _a;
+            return ({
+                mimeType: (_a = p.mimeType) !== null && _a !== void 0 ? _a : 'image/png',
+                base64: p.bytesBase64Encoded
+            });
+        });
+        return succeed({ images });
+    });
+}
+// ============================================================================
+// Image generation — dispatcher
+// ============================================================================
+/**
+ * Calls the appropriate image-generation API for a given provider.
+ *
+ * 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 `: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
+ */
+export async function callProviderImageGeneration(params) {
+    var _a, _b;
+    const { descriptor, apiKey, params: request, modelOverride, logger, signal, endpoint } = params;
+    if (!supportsImageGeneration(descriptor)) {
+        return fail(`provider "${descriptor.id}" does not support image generation`);
+    }
+    const baseUrlResult = resolveEffectiveBaseUrl(descriptor, endpoint);
+    if (baseUrlResult.isFailure()) {
+        return fail(baseUrlResult.message);
+    }
+    const model = resolveModel(modelOverride !== null && modelOverride !== void 0 ? modelOverride : descriptor.defaultModel, 'image');
+    if (model.length === 0) {
+        return fail(`provider "${descriptor.id}": no image model resolved; ` +
+            `pass modelOverride or set descriptor.defaultModel ` +
+            `(a plain string, or an object with an "image" entry)`);
+    }
+    const capability = resolveImageCapability(descriptor, model);
+    if (capability === undefined) {
+        return 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 fail(`model "${model}" does not support reference images`);
+    }
+    const config = {
+        baseUrl: baseUrlResult.value,
+        apiKey,
+        model
+    };
+    /* c8 ignore next 6 - optional logger diagnostic output */
+    if (logger) {
+        logger.info(`AI image generation: provider=${descriptor.id}, format=${capability.format}, ` +
+            `model=${config.model}`);
+    }
+    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 = capability.format;
+            return fail(`unsupported image API format: ${String(_exhaustive)}`);
+        }
+    }
+}
+const openAiListEntry = Validators.object({
+    id: Validators.string
+});
+const openAiListResponse = Validators.object({
+    data: Validators.arrayOf(openAiListEntry)
+});
+const anthropicListEntry = Validators.object({
+    id: Validators.string,
+    display_name: Validators.string.optional()
+});
+const anthropicListResponse = Validators.object({
+    data: Validators.arrayOf(anthropicListEntry)
+});
+const geminiListEntry = Validators.object({
+    name: Validators.string,
+    displayName: Validators.string.optional(),
+    supportedGenerationMethods: Validators.arrayOf(Validators.string).optional()
+});
+const geminiListResponse = Validators.object({
+    models: Validators.arrayOf(geminiListEntry)
+});
+// ============================================================================
+// List models — capability resolution
+// ============================================================================
+/**
+ * Translates Gemini's `supportedGenerationMethods` strings into our abstract
+ * capability vocabulary. Methods without a mapping are ignored.
+ * @internal
+ */
+function geminiMethodsToCapabilities(methods) {
+    const out = [];
+    for (const m of methods) {
+        if (m === 'generateContent') {
+            out.push('chat');
+        }
+        else if (m === 'predict') {
+            out.push('image-generation');
+        }
+    }
+    return out;
+}
+/**
+ * Strips the `models/` prefix Gemini includes on listed model names.
+ * @internal
+ */
+function geminiBareId(name) {
+    return name.startsWith('models/') ? name.substring('models/'.length) : name;
+}
+/**
+ * Applies a capability config to a model id. Walks per-provider rules then
+ * global rules; unions all matching rules' capabilities. Returns the union
+ * and the first matching `displayName` (if any).
+ * @internal
+ */
+function applyCapabilityConfig(config, providerId, modelId) {
+    var _a, _b, _c;
+    const caps = new Set();
+    let displayName;
+    const rulesets = [
+        (_b = (_a = config.perProvider) === null || _a === void 0 ? void 0 : _a[providerId]) !== null && _b !== void 0 ? _b : [],
+        (_c = config.global) !== null && _c !== void 0 ? _c : []
+    ];
+    for (const rules of rulesets) {
+        for (const rule of rules) {
+            rule.idPattern.lastIndex = 0;
+            if (rule.idPattern.test(modelId)) {
+                for (const cap of rule.capabilities) {
+                    caps.add(cap);
+                }
+                if (displayName === undefined && rule.displayName !== undefined) {
+                    displayName = typeof rule.displayName === 'function' ? rule.displayName(modelId) : rule.displayName;
+                }
+            }
+        }
+    }
+    return { capabilities: Array.from(caps), displayName };
+}
+/**
+ * Combines provider-native capability info (when supplied) and config-derived
+ * capability info into a final {@link IAiModelInfo}.
+ * @internal
+ */
+function buildModelInfo(providerId, id, nativeCapabilities, nativeDisplayName, config) {
+    const fromConfig = applyCapabilityConfig(config, providerId, id);
+    const all = new Set([...nativeCapabilities, ...fromConfig.capabilities]);
+    return Object.assign({ id, capabilities: all }, (nativeDisplayName !== undefined
+        ? { displayName: nativeDisplayName }
+        : fromConfig.displayName !== undefined
+            ? { displayName: fromConfig.displayName }
+            : {}));
+}
+// ============================================================================
+// List models — adapters
+// ============================================================================
+/**
+ * Calls the OpenAI-style `GET /models` endpoint. Used by openai, xai-grok,
+ * groq, and mistral. Provider supplies no capability info — capabilities are
+ * derived entirely from the config.
+ * @internal
+ */
+async function callOpenAiListModels(config, providerId, capabilityConfig, logger, signal) {
+    const url = `${config.baseUrl}/models`;
+    const headers = bearerAuthHeader(config.apiKey);
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`List models: provider=${providerId}, format=openai`);
+    const jsonResult = await fetchGetJson(url, headers, logger, signal);
+    if (jsonResult.isFailure()) {
+        return fail(jsonResult.message);
+    }
+    return openAiListResponse
+        .validate(jsonResult.value)
+        .withErrorFormat((msg) => `OpenAI models API response: ${msg}`)
+        .onSuccess((response) => {
+        const models = response.data.map((entry) => buildModelInfo(providerId, entry.id, [], undefined, capabilityConfig));
+        return succeed(models);
+    });
+}
+/**
+ * Calls the Anthropic `GET /models` endpoint. Provider supplies a
+ * `display_name` but no native capability info.
+ * @internal
+ */
+async function callAnthropicListModels(config, providerId, capabilityConfig, logger, signal) {
+    const url = `${config.baseUrl}/models`;
+    const headers = {
+        'x-api-key': config.apiKey,
+        'anthropic-version': '2023-06-01',
+        'anthropic-dangerous-direct-browser-access': 'true'
+    };
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`List models: provider=${providerId}, format=anthropic`);
+    const jsonResult = await fetchGetJson(url, headers, logger, signal);
+    if (jsonResult.isFailure()) {
+        return fail(jsonResult.message);
+    }
+    return anthropicListResponse
+        .validate(jsonResult.value)
+        .withErrorFormat((msg) => `Anthropic models API response: ${msg}`)
+        .onSuccess((response) => {
+        const models = response.data.map((entry) => buildModelInfo(providerId, entry.id, [], entry.display_name, capabilityConfig));
+        return succeed(models);
+    });
+}
+/**
+ * Calls the Gemini `GET /models` endpoint. Provider supplies both a
+ * `displayName` and `supportedGenerationMethods` — translated to native
+ * capabilities and unioned with config-derived capabilities.
+ * @internal
+ */
+async function callGeminiListModels(config, providerId, capabilityConfig, logger, signal) {
+    const url = `${config.baseUrl}/models`;
+    const headers = {
+        'x-goog-api-key': config.apiKey
+    };
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`List models: provider=${providerId}, format=gemini`);
+    const jsonResult = await fetchGetJson(url, headers, logger, signal);
+    if (jsonResult.isFailure()) {
+        return fail(jsonResult.message);
+    }
+    return geminiListResponse
+        .validate(jsonResult.value)
+        .withErrorFormat((msg) => `Gemini models API response: ${msg}`)
+        .onSuccess((response) => {
+        const models = response.models.map((entry) => {
+            const id = geminiBareId(entry.name);
+            const native = entry.supportedGenerationMethods
+                ? geminiMethodsToCapabilities(entry.supportedGenerationMethods)
+                : [];
+            return buildModelInfo(providerId, id, native, entry.displayName, capabilityConfig);
+        });
+        return succeed(models);
+    });
+}
+// ============================================================================
+// List models — dispatcher
+// ============================================================================
+/**
+ * Lists models available from a provider, with capabilities resolved from
+ * native provider info (where supplied) and a configurable rule set.
+ *
+ * Routes based on `descriptor.apiFormat` — listing reuses the existing
+ * format dispatch and does not require a separate descriptor field.
+ *
+ * @param params - Request parameters including descriptor, API key, and optional capability filter
+ * @returns The resolved model list, or a failure
+ * @public
+ */
+export async function callProviderListModels(params) {
+    const { descriptor, apiKey, capability, capabilityConfig, logger, signal, endpoint } = params;
+    const baseUrlResult = resolveEffectiveBaseUrl(descriptor, endpoint);
+    if (baseUrlResult.isFailure()) {
+        return fail(baseUrlResult.message);
+    }
+    const config = {
+        baseUrl: baseUrlResult.value,
+        apiKey,
+        model: '' // unused by listing
+    };
+    const effectiveConfig = capabilityConfig !== null && capabilityConfig !== void 0 ? capabilityConfig : DEFAULT_MODEL_CAPABILITY_CONFIG;
+    let listResult;
+    switch (descriptor.apiFormat) {
+        case 'openai':
+            listResult = await callOpenAiListModels(config, descriptor.id, effectiveConfig, logger, signal);
+            break;
+        case 'anthropic':
+            listResult = await callAnthropicListModels(config, descriptor.id, effectiveConfig, logger, signal);
+            break;
+        case 'gemini':
+            listResult = await callGeminiListModels(config, descriptor.id, effectiveConfig, logger, signal);
+            break;
+        /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
+        default: {
+            const _exhaustive = descriptor.apiFormat;
+            return fail(`unsupported API format: ${String(_exhaustive)}`);
+        }
+    }
+    if (listResult.isFailure()) {
+        return listResult;
+    }
+    if (capability === undefined) {
+        return listResult;
+    }
+    return succeed(listResult.value.filter((m) => m.capabilities.has(capability)));
+}
+// ============================================================================
+// Proxied list models
+// ============================================================================
+/**
+ * Calls the model-listing endpoint on a proxy server.
+ *
+ * @remarks
+ * Proxy contract:
+ * - Endpoint: `POST ${proxyUrl}/api/ai/list-models`
+ * - Request body: `{providerId, apiKey, capability?}`. Capability config is
+ *   not forwarded — the proxy applies its own (typically the same default
+ *   the library ships).
+ * - Success response body: an `IAiModelInfo[]` (under key `models`) where
+ *   `capabilities` is serialized as a string array (not Set, which doesn't
+ *   round-trip through JSON).
+ * - Error response body: `{error: string}`, surfaced as `proxy: ${error}`.
+ *
+ * @public
+ */
+export async function callProxiedListModels(proxyUrl, params) {
+    const { descriptor, apiKey, capability, logger, signal } = params;
+    const body = {
+        providerId: descriptor.id,
+        apiKey
+    };
+    if (capability !== undefined) {
+        body.capability = capability;
+    }
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`AI list-models proxy request: provider=${descriptor.id}, proxy=${proxyUrl}`);
+    const url = `${proxyUrl}/api/ai/list-models`;
+    const jsonResult = await fetchJson(url, {}, body, logger, signal);
+    if (jsonResult.isFailure()) {
+        return fail(jsonResult.message);
+    }
+    const response = jsonResult.value;
+    if (typeof response.error === 'string') {
+        return fail(`proxy: ${response.error}`);
+    }
+    return proxiedListModelsResponse
+        .validate(response)
+        .withErrorFormat((msg) => `proxy returned invalid response: ${msg}`)
+        .onSuccess((parsed) => {
+        const models = parsed.models.map((m) => (Object.assign({ id: m.id, capabilities: new Set(m.capabilities) }, (m.displayName !== undefined ? { displayName: m.displayName } : {}))));
+        return succeed(models);
+    });
+}
 // ============================================================================
 // Proxied completion (routes through a backend server)
 // ============================================================================
@@ -445,11 +1131,15 @@ export async function callProviderCompletion(params) {
  * @public
  */
 export async function callProxiedCompletion(proxyUrl, params) {
-    const { descriptor, apiKey, prompt, additionalMessages, temperature, modelOverride, logger, tools } = params;
+    const { descriptor, apiKey, prompt, additionalMessages, temperature, modelOverride, logger, tools, signal } = params;
+    const promptBody = { system: prompt.system, user: prompt.user };
+    if (prompt.attachments.length > 0) {
+        promptBody.attachments = prompt.attachments;
+    }
     const body = {
         providerId: descriptor.id,
         apiKey,
-        prompt: { system: prompt.system, user: prompt.user },
+        prompt: promptBody,
         temperature: temperature !== null && temperature !== void 0 ? temperature : 0.7
     };
     if (additionalMessages && additionalMessages.length > 0) {
@@ -464,7 +1154,7 @@ export async function callProxiedCompletion(proxyUrl, params) {
     /* c8 ignore next 1 - optional logger */
     logger === null || logger === void 0 ? void 0 : logger.info(`AI proxy request: provider=${descriptor.id}, proxy=${proxyUrl}`);
     const url = `${proxyUrl}/api/ai/completion`;
-    const jsonResult = await fetchJson(url, {}, body, logger);
+    const jsonResult = await fetchJson(url, {}, body, logger, signal);
     if (jsonResult.isFailure()) {
         return fail(jsonResult.message);
     }
@@ -481,4 +1171,54 @@ export async function callProxiedCompletion(proxyUrl, params) {
         truncated: response.truncated === true
     });
 }
+// ============================================================================
+// Proxied image generation
+// ============================================================================
+/**
+ * Calls the image-generation endpoint on a proxy server instead of calling
+ * the provider API directly from the browser.
+ *
+ * @remarks
+ * The proxy contract:
+ * - Endpoint: `POST ${proxyUrl}/api/ai/image-generation`
+ * - Request body: `{providerId, apiKey, params, modelOverride?}`
+ * - Success response body: an {@link IAiImageGenerationResponse}
+ * - Error response body: `{error: string}` (surfaced as `proxy: ${error}`)
+ *
+ * The proxy server is responsible for descriptor lookup, model resolution,
+ * 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}
+ * @returns The generated images, or a failure
+ * @public
+ */
+export async function callProxiedImageGeneration(proxyUrl, params) {
+    const { descriptor, apiKey, params: request, modelOverride, logger, signal } = params;
+    const body = {
+        providerId: descriptor.id,
+        apiKey,
+        params: request
+    };
+    if (modelOverride !== undefined) {
+        body.modelOverride = modelOverride;
+    }
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`AI image proxy request: provider=${descriptor.id}, proxy=${proxyUrl}`);
+    const url = `${proxyUrl}/api/ai/image-generation`;
+    const jsonResult = await fetchJson(url, {}, body, logger, signal);
+    if (jsonResult.isFailure()) {
+        return fail(jsonResult.message);
+    }
+    const response = jsonResult.value;
+    if (typeof response.error === 'string') {
+        return fail(`proxy: ${response.error}`);
+    }
+    return proxiedImageGenerationResponse
+        .validate(response)
+        .withErrorFormat((msg) => `proxy returned invalid response: ${msg}`);
+}
 //# sourceMappingURL=apiClient.js.map