@fgv/ts-extras 5.1.0-4 → 5.1.0-40

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

@@ -19,55 +19,135 @@
 // SOFTWARE.
 /**
  * Chat completion client for AI assist with support for multiple provider APIs.
- *
  * Supports OpenAI-compatible providers (xAI, OpenAI, Groq, Mistral) directly,
- * plus adapters for Anthropic and Google Gemini.
- *
- * When server-side tools (e.g. web_search) are configured, providers that support
- * them will include tool configuration in the request and handle tool-augmented
- * responses.
+ * plus adapters for Anthropic and Google Gemini. When server-side tools (e.g.
+ * web_search) are configured, providers that support them include tool
+ * configuration in the request and handle tool-augmented responses.
  *
  * @packageDocumentation
  */
 import { isJsonObject } from '@fgv/ts-json-base';
-import { fail, succeed, Validators } from '@fgv/ts-utils';
-import { resolveModel } from './model';
+import { fail, mapResults, succeed, Validators } from '@fgv/ts-utils';
+import { allModelCapabilities, isResponsesOnlyModel, resolveProviderModel } from './model';
+import { anthropicEffortToBudgetTokens, checkTemperatureConflict, mergeThinkingConfig, providerDiscriminatorForId } from './thinkingOptionsResolver';
+import { buildAnthropicMessages, buildGeminiContents, buildMessages, buildOpenAiChatUserContent, buildOpenAiResponsesUserContent, normalizeOutboundMessages, splitChatRequest } from './chatRequestBuilders';
+import { bearerAuthHeader, resolveEffectiveBaseUrl } from './endpoint';
+import { fetchJson } from './http';
+import { DEFAULT_MODEL_CAPABILITY_CONFIG, resolveImageCapability, supportsImageGeneration } from './registry';
+import { resolveImageOptions, validateResolvedOptions } from './imageOptionsResolver';
 import { toAnthropicTools, toGeminiTools, toResponsesApiTools } from './toolFormats';
 // ============================================================================
 // Shared helpers
 // ============================================================================
 /**
- * Builds the messages array from prompt + optional correction messages.
+ * 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
  */
-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 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) {
+        /* c8 ignore next 1 - defensive: fetch errors are always Error instances in practice */
+        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 /* c8 ignore start - defensive: response.json() failure on a 2xx */ (_a) {
+        logger === null || logger === void 0 ? void 0 : logger.error('AI API returned invalid JSON response');
+        return fail('AI API returned invalid JSON response');
+    } /* c8 ignore stop */
+    /* c8 ignore next 5 - defensive: provider returning non-object JSON on a 2xx */
+    if (!isJsonObject(json)) {
+        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);
+}
+/**
+ * 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 }));
     }
-    return messages;
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        return fail(`Invalid base64: ${message}`);
+    }
+    /* c8 ignore stop */
 }
 /**
- * Makes an HTTP request and returns the parsed JSON, or a failure.
+ * Maps a MIME type to a sensible file extension for multipart filenames.
  * @internal
  */
-async function fetchJson(url, headers, body, logger) {
+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: POST ${url}`);
+    logger === null || logger === void 0 ? void 0 : logger.detail(`AI API request: GET ${url}`);
     let response;
     try {
-        response = await fetch(url, {
-            method: 'POST',
-            headers: Object.assign({ 'Content-Type': 'application/json' }, headers),
-            body: JSON.stringify(body)
-        });
+        response = await fetch(url, { method: 'GET', headers, signal });
     }
     catch (err) {
+        /* c8 ignore next 1 - defensive: fetch errors are always Error instances in practice */
         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}`);
@@ -85,13 +165,12 @@ async function fetchJson(url, headers, body, logger) {
     try {
         json = await response.json();
     }
-    catch (_a) {
-        /* c8 ignore next 1 - optional logger */
+    catch /* c8 ignore start - defensive: response.json() failure on a 2xx */ (_a) {
         logger === null || logger === void 0 ? void 0 : logger.error('AI API returned invalid JSON response');
         return fail('AI API returned invalid JSON response');
-    }
+    } /* c8 ignore stop */
+    /* c8 ignore next 5 - defensive: provider returning non-object JSON on a 2xx */
     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');
     }
@@ -121,13 +200,6 @@ const responsesApiResponse = Validators.object({
     output: Validators.arrayOf(responsesApiOutputItem).withConstraint((arr) => arr.length > 0),
     status: Validators.string
 });
-const anthropicContentBlock = Validators.object({
-    text: Validators.string
-});
-const anthropicResponse = Validators.object({
-    content: Validators.arrayOf(anthropicContentBlock).withConstraint((arr) => arr.length > 0),
-    stop_reason: Validators.string
-});
 const geminiPart = Validators.object({
     text: Validators.string
 });
@@ -149,16 +221,21 @@ 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, head, temperature, logger, signal, resolvedThinking) {
+    var _a;
     const url = `${config.baseUrl}/chat/completions`;
-    const messages = buildMessages(prompt, additionalMessages);
-    const body = { model: config.model, messages, temperature };
-    const headers = {
-        Authorization: `Bearer ${config.apiKey}`
-    };
+    const messages = buildMessages(prompt.system, buildOpenAiChatUserContent(prompt), {
+        head
+    });
+    const effort = (_a = resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.openAiEffort) !== null && _a !== void 0 ? _a : resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.xaiEffort;
+    const body = Object.assign(Object.assign({ model: config.model, messages }, (temperature !== undefined ? { temperature } : {})), (effort !== undefined && config.model !== 'grok-4' ? { reasoning_effort: effort } : {}));
+    if ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.otherParams) !== undefined) {
+        Object.assign(body, resolvedThinking.otherParams);
+    }
+    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 +274,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 = [], head, temperature, logger, signal, resolvedThinking) {
+    var _a;
     const url = `${config.baseUrl}/responses`;
-    const input = buildMessages(prompt, additionalMessages);
-    const body = {
-        model: config.model,
-        input,
-        tools: toResponsesApiTools(tools),
-        temperature
-    };
-    const headers = {
-        Authorization: `Bearer ${config.apiKey}`
-    };
+    const input = buildMessages(prompt.system, buildOpenAiResponsesUserContent(prompt), {
+        head
+    });
+    const effort = (_a = resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.openAiEffort) !== null && _a !== void 0 ? _a : resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.xaiEffort;
+    const body = Object.assign(Object.assign(Object.assign({ model: config.model, input }, (tools.length > 0 ? { tools: toResponsesApiTools(tools) } : {})), (temperature !== undefined ? { temperature } : {})), (effort !== undefined && config.model !== 'grok-4' ? { reasoning: { effort } } : {}));
+    if ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.otherParams) !== undefined) {
+        Object.assign(body, resolvedThinking.otherParams);
+    }
+    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);
     }
@@ -250,31 +327,18 @@ function extractAnthropicText(content) {
     }
     return succeed(textParts.join(''));
 }
-/**
- * Calls the Anthropic Messages API.
- * When tools are configured, includes them in the request and handles
- * mixed content block responses.
- * @internal
- */
-async function callAnthropicCompletion(config, prompt, additionalMessages, temperature = 0.7, logger, tools) {
+/** Calls the Anthropic Messages API with optional tool support. @internal */
+async function callAnthropicCompletion(config, prompt, head, temperature, logger, tools, signal, resolvedThinking) {
     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, { head });
+    const body = Object.assign({ model: config.model, system: prompt.system, messages, max_tokens: 4096 }, (temperature !== undefined ? { temperature } : {}));
+    const effort = resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.anthropicEffort;
+    if (effort !== undefined) {
+        body.thinking = { type: 'enabled', budget_tokens: anthropicEffortToBudgetTokens(effort) };
+    }
+    if ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.otherParams) !== undefined) {
+        Object.assign(body, resolvedThinking.otherParams);
     }
-    const body = {
-        model: config.model,
-        system: prompt.system,
-        messages,
-        max_tokens: 4096,
-        temperature
-    };
     if (tools && tools.length > 0) {
         body.tools = toAnthropicTools(tools);
         /* c8 ignore next 3 - optional logger diagnostic output */
@@ -289,32 +353,22 @@ 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);
     }
-    // When tools are used, the response content is a mixed array of block types.
-    // We need to extract text from all text blocks.
-    if (tools && tools.length > 0) {
-        const rawContent = jsonResult.value.content;
-        const stopReason = jsonResult.value.stop_reason;
-        if (!Array.isArray(rawContent)) {
-            return fail('Anthropic API response: content is not an array');
-        }
-        return extractAnthropicText(rawContent).onSuccess((text) => succeed({
-            content: text,
-            truncated: stopReason === 'max_tokens'
-        }));
+    const rawContent = jsonResult.value.content;
+    const stopReason = jsonResult.value.stop_reason;
+    if (!Array.isArray(rawContent)) {
+        return fail('Anthropic API response: content is not an array');
     }
-    return anthropicResponse
-        .validate(jsonResult.value)
-        .withErrorFormat((msg) => `Anthropic API response: ${msg}`)
-        .onSuccess((response) => {
-        return succeed({
-            content: response.content[0].text,
-            truncated: response.stop_reason === 'max_tokens'
-        });
-    });
+    if (typeof stopReason !== 'string') {
+        return fail('Anthropic API response: stop_reason is missing or not a string');
+    }
+    return extractAnthropicText(rawContent).onSuccess((text) => succeed({
+        content: text,
+        truncated: stopReason === 'max_tokens'
+    }));
 }
 // ============================================================================
 // Google Gemini adapter
@@ -324,26 +378,24 @@ 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, head, temperature, logger, tools, signal, resolvedThinking) {
     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, { head });
+    // Temperature is sent only when explicitly provided; otherwise Gemini's default applies.
+    const generationConfig = {};
+    if (temperature !== undefined) {
+        generationConfig.temperature = temperature;
+    }
+    if ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.geminiThinkingBudget) !== undefined) {
+        generationConfig.thinkingConfig = { thinkingBudget: resolvedThinking.geminiThinkingBudget };
+    }
+    if ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.otherParams) !== undefined) {
+        Object.assign(generationConfig, resolvedThinking.otherParams);
     }
     const body = {
         systemInstruction: { parts: [{ text: prompt.system }] },
         contents,
-        generationConfig: { temperature }
+        generationConfig
     };
     if (tools && tools.length > 0) {
         body.tools = toGeminiTools(tools);
@@ -357,7 +409,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);
     }
@@ -376,33 +428,54 @@ async function callGeminiCompletion(config, prompt, additionalMessages, temperat
 // Provider dispatcher
 // ============================================================================
 /**
- * Calls the appropriate chat completion API for a given provider.
- *
- * Routes based on the provider descriptor's `apiFormat` field:
- * - `'openai'` for xAI, OpenAI, Groq, Mistral
- * - `'anthropic'` for Anthropic Claude
- * - `'gemini'` for Google Gemini
- *
- * When tools are provided and the provider supports them:
- * - OpenAI-format providers switch to the Responses API
- * - Anthropic includes tools in the Messages API request
- * - Gemini includes Google Search grounding
- *
- * @param params - Request parameters including descriptor, API key, prompt, and optional tools
- * @returns The completion response with content and truncation status, or a failure
+ * Calls the appropriate chat completion API for a given provider. Routes by
+ * `apiFormat`: `'openai'` (xAI/OpenAI/Groq/Mistral — switches to Responses API
+ * when tools are set), `'anthropic'`, or `'gemini'`.
  * @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, system, messages, temperature, modelOverride, tier, logger, tools, signal, endpoint, thinking } = params;
+    const splitResult = splitChatRequest(system, messages);
+    if (splitResult.isFailure()) {
+        return fail(splitResult.message);
+    }
+    const { prompt, head } = splitResult.value;
+    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 discriminator = providerDiscriminatorForId(descriptor.id);
+    // The quality tier is the only completion-model selector; thinking and tools
+    // are orthogonal request params/capabilities and never pick a model.
+    const modelContext = tier;
+    const modelResult = resolveProviderModel(descriptor, modelOverride, modelContext);
+    if (modelResult.isFailure()) {
+        return fail(modelResult.message);
+    }
+    const model = modelResult.value;
+    let resolvedThinking;
+    if (thinking !== undefined) {
+        if (discriminator !== undefined) {
+            const mergeResult = mergeThinkingConfig(thinking, model, discriminator);
+            /* c8 ignore next 3 - mergeThinkingConfig always succeeds; defensive guard */
+            if (mergeResult.isFailure()) {
+                return fail(mergeResult.message);
+            }
+            resolvedThinking = mergeResult.value;
+            const conflictResult = checkTemperatureConflict(resolvedThinking, discriminator, temperature);
+            if (conflictResult.isFailure()) {
+                return fail(conflictResult.message);
+            }
+        }
+    }
     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) {
@@ -413,14 +486,16 @@ export async function callProviderCompletion(params) {
     }
     switch (descriptor.apiFormat) {
         case 'openai':
-            if (hasTools) {
-                return callOpenAiResponsesCompletion(config, prompt, tools, additionalMessages, temperature, logger);
+            // Responses-API-only models (e.g. gpt-5.5-pro) 400 on /chat/completions, so they route
+            // to the Responses path even with no tools requested — same path the tools case uses.
+            if (hasTools || isResponsesOnlyModel(descriptor, config.model)) {
+                return callOpenAiResponsesCompletion(config, prompt, tools, head, temperature, logger, signal, resolvedThinking);
             }
-            return callOpenAiCompletion(config, prompt, additionalMessages, temperature, logger);
+            return callOpenAiCompletion(config, prompt, head, temperature, logger, signal, resolvedThinking);
         case 'anthropic':
-            return callAnthropicCompletion(config, prompt, additionalMessages, temperature, logger, tools);
+            return callAnthropicCompletion(config, prompt, head, temperature, logger, tools, signal, resolvedThinking);
         case 'gemini':
-            return callGeminiCompletion(config, prompt, additionalMessages, temperature, logger, tools);
+            return callGeminiCompletion(config, prompt, head, temperature, logger, tools, signal, resolvedThinking);
         /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
         default: {
             const _exhaustive = descriptor.apiFormat;
@@ -428,32 +503,643 @@ 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 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)
+});
+const geminiImageOutCandidate = Validators.object({
+    content: geminiImageOutContent.optional(),
+    finishReason: Validators.string.optional(),
+    finishMessage: 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(allModelCapabilities)),
+    displayName: Validators.string.optional()
+});
+const proxiedListModelsResponse = Validators.object({
+    models: Validators.arrayOf(proxiedListModelsEntry)
+});
+// ============================================================================
+// Image generation — adapters
+// ============================================================================
+/** Routes to /images/generations or /images/edits; handles outputParamStyle. @internal */
+async function callOpenAiImageGeneration(config, request, capability, resolved, logger, signal) {
+    var _a, _b;
+    const refs = (_a = request.referenceImages) !== null && _a !== void 0 ? _a : [];
+    const headers = bearerAuthHeader(config.apiKey);
+    const effectiveMimeType = resolved.outputFormat !== undefined
+        ? `image/${resolved.outputFormat}`
+        : (_b = capability.defaultOutputMimeType) !== null && _b !== void 0 ? _b : 'image/png';
+    const fetched = refs.length > 0
+        ? await callOpenAiImagesEdits(config, capability, request, headers, resolved, logger, signal)
+        : await callOpenAiImagesGenerations(config, request, headers, resolved, capability, 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: effectiveMimeType, base64: item.b64_json }, (item.revised_prompt !== undefined ? { revisedPrompt: item.revised_prompt } : {}))))
+    })));
+}
+/** Builds the JSON /images/generations request; handles outputParamStyle. @internal */
+function callOpenAiImagesGenerations(config, request, headers, resolved, capability, logger, signal) {
+    var _a;
+    const body = {
+        model: config.model,
+        prompt: request.prompt,
+        n: resolved.n
+    };
+    // Output format param — conditional on model capability
+    if (capability.outputParamStyle === 'response-format') {
+        body.response_format = 'b64_json';
+    }
+    else if (capability.outputParamStyle === 'output-format') {
+        body.output_format = (_a = resolved.outputFormat) !== null && _a !== void 0 ? _a : 'png';
+    }
+    if (resolved.size !== undefined) {
+        body.size = resolved.size;
+    }
+    if (capability.supportsQualityParam && resolved.quality !== undefined) {
+        body.quality = resolved.quality;
+    }
+    if (resolved.seed !== undefined) {
+        body.seed = resolved.seed;
+    }
+    if (resolved.background !== undefined) {
+        body.background = resolved.background;
+    }
+    if (resolved.moderation !== undefined) {
+        body.moderation = resolved.moderation;
+    }
+    if (resolved.outputCompression !== undefined) {
+        body.output_compression = resolved.outputCompression;
+    }
+    if (resolved.otherParams !== undefined) {
+        Object.assign(body, resolved.otherParams);
+    }
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`Image generation: model=${config.model}, n=${resolved.n}`);
+    return fetchJson(`${config.baseUrl}/images/generations`, headers, body, logger, signal);
+}
+/** Builds the multipart /images/edits request with ref images. @internal */
+async function callOpenAiImagesEdits(config, capability, request, headers, resolved, logger, signal) {
+    const refs = request.referenceImages; // callers verify refs.length > 0 before calling this function
+    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 form = new FormData();
+    form.append('model', config.model);
+    form.append('prompt', request.prompt);
+    form.append('n', String(resolved.n));
+    if (capability.outputParamStyle !== 'output-format') {
+        form.append('response_format', 'b64_json');
+    }
+    if (resolved.size !== undefined) {
+        form.append('size', resolved.size);
+    }
+    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=${resolved.n}, refs=${refs.length}`);
+    return fetchMultipart(`${config.baseUrl}/images/edits`, headers, form, logger, signal);
+}
+/** Calls xAI /images/edits with JSON body (not multipart); up to 3 source images. @internal */
+async function callXaiImagesEdits(config, request, resolved, logger, signal) {
+    var _a;
+    /* c8 ignore next 1 - defensive: referenceImages always defined when this function is called */
+    const refs = (_a = request.referenceImages) !== null && _a !== void 0 ? _a : [];
+    if (refs.length > 3) {
+        return fail(`xAI image edits supports at most 3 reference images; got ${refs.length}`);
+    }
+    const images = refs.map((ref) => ({
+        type: 'image_url',
+        url: `data:${ref.mimeType};base64,${ref.base64}`
+    }));
+    const body = {
+        model: config.model,
+        prompt: request.prompt,
+        n: resolved.n,
+        response_format: 'b64_json',
+        image: images
+    };
+    if (resolved.aspectRatio !== undefined) {
+        body.aspect_ratio = resolved.aspectRatio;
+    }
+    if (resolved.resolution !== undefined) {
+        body.resolution = resolved.resolution;
+    }
+    if (resolved.otherParams !== undefined) {
+        Object.assign(body, resolved.otherParams);
+    }
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`xAI image edit: model=${config.model}, n=${resolved.n}, refs=${refs.length}`);
+    return fetchJson(`${config.baseUrl}/images/edits`, bearerAuthHeader(config.apiKey), body, logger, signal);
+}
+/** Calls xAI /images/generations; uses aspect_ratio instead of size. @internal */
+async function callXaiImageGeneration(config, request, capability, resolved, logger, signal) {
+    const headers = bearerAuthHeader(config.apiKey);
+    const body = {
+        model: config.model,
+        prompt: request.prompt,
+        n: resolved.n,
+        response_format: 'b64_json'
+    };
+    if (resolved.aspectRatio !== undefined) {
+        body.aspect_ratio = resolved.aspectRatio;
+    }
+    if (resolved.resolution !== undefined) {
+        body.resolution = resolved.resolution;
+    }
+    if (resolved.otherParams !== undefined) {
+        Object.assign(body, resolved.otherParams);
+    }
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`xAI image generation: model=${config.model}, n=${resolved.n}`);
+    const fetched = await fetchJson(`${config.baseUrl}/images/generations`, headers, body, logger, signal);
+    return fetched.onSuccess((json) => openAiImageResponse
+        .validate(json)
+        .withErrorFormat((msg) => `xAI images API response: ${msg}`)
+        .onSuccess((response) => succeed({
+        images: response.data.map((item) => {
+            var _a;
+            return ({
+                mimeType: (_a = capability.defaultOutputMimeType) !== null && _a !== void 0 ? _a : 'image/jpeg',
+                base64: item.b64_json
+            });
+        })
+    })));
+}
+/**
+ * Gemini `finishReason` values that indicate a normal terminal completion rather
+ * than a refusal. `STOP` is set on every successful generation (and on completions
+ * that return a text part instead of an image); `MAX_TOKENS` is a benign truncation.
+ * A candidate carrying only one of these is NOT a decline — treating it as one would
+ * mislabel an ordinary no-image outcome as a policy refusal. @internal
+ */
+const benignGeminiImageFinishReasons = new Set(['STOP', 'MAX_TOKENS']);
+/** Calls Gemini :generateContent for image output; accepts ref images as inlineData. @internal */
+async function callGeminiImageOutGeneration(config, request, resolved, 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 generationConfig = {};
+    if (resolved.geminiAspectRatio !== undefined) {
+        generationConfig.imageConfig = { aspectRatio: resolved.geminiAspectRatio };
+    }
+    if (resolved.otherParams !== undefined) {
+        Object.assign(generationConfig, resolved.otherParams);
+    }
+    const body = { contents: [{ role: 'user', parts }] };
+    if (Object.keys(generationConfig).length > 0) {
+        body.generationConfig = generationConfig;
+    }
+    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) => {
+        var _a, _b;
+        const images = [];
+        for (const candidate of response.candidates) {
+            for (const part of (_b = (_a = candidate.content) === null || _a === void 0 ? void 0 : _a.parts) !== null && _b !== void 0 ? _b : []) {
+                if (part.inlineData) {
+                    images.push({
+                        mimeType: part.inlineData.mimeType,
+                        base64: part.inlineData.data
+                    });
+                }
+            }
+        }
+        if (images.length === 0) {
+            // A candidate with no image parts is a *decline* only when it carries a
+            // refusal-shaped finishReason — i.e. present and not a benign terminal reason
+            // (`STOP`/`MAX_TOKENS`). A normal completion that emitted text-instead-of-image
+            // carries `finishReason: 'STOP'` and must fall through to the no-image message.
+            const declined = response.candidates.find((candidate) => candidate.finishReason !== undefined &&
+                !benignGeminiImageFinishReasons.has(candidate.finishReason));
+            if ((declined === null || declined === void 0 ? void 0 : declined.finishReason) !== undefined) {
+                // Truthiness (not `!== undefined`) so an empty-string finishMessage is treated
+                // as "no message" and produces no dangling ` — ` separator.
+                const suffix = declined.finishMessage ? ` — ${declined.finishMessage}` : '';
+                return fail(`Gemini image generation declined: ${declined.finishReason}${suffix}`);
+            }
+            return fail('Gemini image API response: no image parts in response');
+        }
+        return succeed({ images });
+    }));
+}
+// ============================================================================
+// Image generation — dispatcher
+// ============================================================================
+/**
+ * Calls the appropriate image-generation API for a given provider. Routes by the
+ * `format` field of the resolved {@link IAiImageModelCapability}:
+ * `'openai-images'`, `'xai-images'`, `'xai-images-edits'`, or
+ * `'gemini-image-out'`. Rejects up front if `referenceImages` is set but the
+ * capability does not declare `acceptsImageReferenceInput`.
+ * @param params - Request parameters including descriptor, API key, and prompt
+ * @public
+ */
+export async function callProviderImageGeneration(params) {
+    var _a, _b, _c;
+    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 modelResult = resolveProviderModel(descriptor, modelOverride, 'image');
+    if (modelResult.isFailure()) {
+        return fail(modelResult.message);
+    }
+    const model = modelResult.value;
+    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 resolved = resolveImageOptions(model, capability, request.options);
+    const validationResult = validateResolvedOptions(model, capability, resolved);
+    if (validationResult.isFailure()) {
+        return fail(validationResult.message);
+    }
+    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, capability, resolved, logger, signal);
+        case 'xai-images':
+            return callXaiImageGeneration(config, request, capability, resolved, logger, signal);
+        case 'xai-images-edits': {
+            const refs = (_c = request.referenceImages) !== null && _c !== void 0 ? _c : [];
+            if (refs.length > 0) {
+                const editsResult = await callXaiImagesEdits(config, request, resolved, logger, signal);
+                return editsResult.onSuccess((json) => openAiImageResponse
+                    .validate(json)
+                    .withErrorFormat((msg) => `xAI images API response: ${msg}`)
+                    .onSuccess((response) => succeed({
+                    images: response.data.map((item) => {
+                        var _a;
+                        return ({
+                            mimeType: (_a = capability.defaultOutputMimeType) !== null && _a !== void 0 ? _a : 'image/jpeg',
+                            base64: item.b64_json
+                        });
+                    })
+                })));
+            }
+            return callXaiImageGeneration(config, request, capability, resolved, logger, signal);
+        }
+        case 'gemini-image-out':
+            return callGeminiImageOutGeneration(config, request, resolved, 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) {
+    /* c8 ignore next 1 - defensive: Gemini API always returns names prefixed with 'models/' */
+    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, routing by `descriptor.apiFormat`.
+ * Capabilities are resolved from native provider info and a configurable rule set.
+ * @param params - Request parameters (descriptor, API key, optional capability filter)
+ * @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. Endpoint:
+ * `POST ${proxyUrl}/api/ai/list-models`. Capability config is not forwarded;
+ * `capabilities` is serialized as a string array. Error body `{error: string}`
+ * is 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)
 // ============================================================================
 /**
- * Calls the AI completion endpoint on a proxy server instead of calling
- * the provider API directly from the browser.
- *
- * The proxy server handles provider dispatch, CORS, and API key forwarding.
- * The request shape mirrors {@link IProviderCompletionParams} but is serialized
- * as JSON for the proxy endpoint.
- *
- * @param proxyUrl - Base URL of the proxy server (e.g. `http://localhost:3001`)
+ * Calls the AI completion endpoint on a proxy server instead of calling the
+ * provider API directly from the browser. The proxy handles provider dispatch,
+ * CORS, and API key forwarding. The request body serializes the unified
+ * {@link AiAssist.IChatRequest} shape (`system?` + `messages`). Enforces the same
+ * non-empty / trailing-user-turn and image-input invariants as the direct path.
+ * @param proxyUrl - Base URL of the proxy server
  * @param params - Same parameters as {@link callProviderCompletion}
- * @returns The completion response, or a failure
  * @public
  */
 export async function callProxiedCompletion(proxyUrl, params) {
-    const { descriptor, apiKey, prompt, additionalMessages, temperature, modelOverride, logger, tools } = params;
+    const { descriptor, apiKey, system, messages, temperature, modelOverride, logger, tools, signal, thinking } = params;
+    const splitResult = splitChatRequest(system, messages);
+    if (splitResult.isFailure()) {
+        return fail(splitResult.message);
+    }
+    if (splitResult.value.prompt.attachments.length > 0 && !descriptor.acceptsImageInput) {
+        return fail(`provider "${descriptor.id}" does not accept image input`);
+    }
     const body = {
         providerId: descriptor.id,
         apiKey,
-        prompt: { system: prompt.system, user: prompt.user },
-        temperature: temperature !== null && temperature !== void 0 ? temperature : 0.7
+        messages: normalizeOutboundMessages(splitResult.value)
     };
-    if (additionalMessages && additionalMessages.length > 0) {
-        body.additionalMessages = additionalMessages;
+    // Temperature is forwarded only when explicitly provided, matching the direct path — the proxy
+    // omits it from the upstream request so the provider default applies.
+    if (temperature !== undefined) {
+        body.temperature = temperature;
+    }
+    if (system !== undefined) {
+        body.system = system;
     }
     if (modelOverride !== undefined) {
         body.modelOverride = modelOverride;
@@ -461,14 +1147,16 @@ export async function callProxiedCompletion(proxyUrl, params) {
     if (tools && tools.length > 0) {
         body.tools = tools;
     }
+    if (thinking !== undefined) {
+        body.thinking = thinking;
+    }
     /* 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);
     }
-    // Check for error response from proxy
     const response = jsonResult.value;
     if (typeof response.error === 'string') {
         return fail(`proxy: ${response.error}`);
@@ -481,4 +1169,44 @@ 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.
+ * Endpoint: `POST ${proxyUrl}/api/ai/image-generation`. Request body:
+ * `{providerId, apiKey, params, modelOverride?}`. The proxy handles descriptor
+ * lookup, model resolution, provider dispatch, and response normalization
+ * (including repackaging `referenceImages` for the upstream wire format).
+ * Error body `{error: string}` is surfaced as `proxy: ${error}`.
+ * @param proxyUrl - Base URL of the proxy server
+ * @param params - Same parameters as {@link callProviderImageGeneration}
+ * @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