@fgv/ts-extras 5.1.0-26 → 5.1.0-28

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

@@ -40,9 +40,11 @@ exports.callProxiedImageGeneration = callProxiedImageGeneration;
 const ts_json_base_1 = require("@fgv/ts-json-base");
 const ts_utils_1 = require("@fgv/ts-utils");
 const model_1 = require("./model");
+const thinkingOptionsResolver_1 = require("./thinkingOptionsResolver");
 const chatRequestBuilders_1 = require("./chatRequestBuilders");
 const endpoint_1 = require("./endpoint");
 const registry_1 = require("./registry");
+const imageOptionsResolver_1 = require("./imageOptionsResolver");
 const toolFormats_1 = require("./toolFormats");
 // ============================================================================
 // Shared helpers
@@ -112,6 +114,7 @@ async function fetchMultipart(url, headers, body, logger, 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}`);
@@ -129,13 +132,12 @@ async function fetchMultipart(url, headers, body, logger, signal) {
     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 (0, ts_utils_1.fail)('AI API returned invalid JSON response');
-    }
+    } /* c8 ignore stop */
+    /* c8 ignore next 5 - defensive: provider returning non-object JSON on a 2xx */
     if (!(0, ts_json_base_1.isJsonObject)(json)) {
-        /* c8 ignore next 1 - optional logger */
         logger === null || logger === void 0 ? void 0 : logger.error('AI API returned non-object JSON response');
         return (0, ts_utils_1.fail)('AI API returned non-object JSON response');
     }
@@ -201,6 +203,7 @@ async function fetchGetJson(url, headers, logger, signal) {
         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}`);
@@ -218,13 +221,12 @@ async function fetchGetJson(url, headers, logger, signal) {
     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 (0, ts_utils_1.fail)('AI API returned invalid JSON response');
-    }
+    } /* c8 ignore stop */
+    /* c8 ignore next 5 - defensive: provider returning non-object JSON on a 2xx */
     if (!(0, ts_json_base_1.isJsonObject)(json)) {
-        /* c8 ignore next 1 - optional logger */
         logger === null || logger === void 0 ? void 0 : logger.error('AI API returned non-object JSON response');
         return (0, ts_utils_1.fail)('AI API returned non-object JSON response');
     }
@@ -254,13 +256,6 @@ const responsesApiResponse = ts_utils_1.Validators.object({
     output: ts_utils_1.Validators.arrayOf(responsesApiOutputItem).withConstraint((arr) => arr.length > 0),
     status: ts_utils_1.Validators.string
 });
-const anthropicContentBlock = ts_utils_1.Validators.object({
-    text: ts_utils_1.Validators.string
-});
-const anthropicResponse = ts_utils_1.Validators.object({
-    content: ts_utils_1.Validators.arrayOf(anthropicContentBlock).withConstraint((arr) => arr.length > 0),
-    stop_reason: ts_utils_1.Validators.string
-});
 const geminiPart = ts_utils_1.Validators.object({
     text: ts_utils_1.Validators.string
 });
@@ -282,12 +277,17 @@ const geminiResponse = ts_utils_1.Validators.object({
  * Works for xAI Grok, OpenAI, Groq, and Mistral.
  * @internal
  */
-async function callOpenAiCompletion(config, prompt, additionalMessages, temperature = 0.7, logger, signal) {
+async function callOpenAiCompletion(config, prompt, additionalMessages, temperature = 0.7, logger, signal, resolvedThinking) {
+    var _a;
     const url = `${config.baseUrl}/chat/completions`;
     const messages = (0, chatRequestBuilders_1.buildMessages)(prompt.system, (0, chatRequestBuilders_1.buildOpenAiChatUserContent)(prompt), {
         tail: additionalMessages
     });
-    const body = { model: config.model, messages, temperature };
+    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 }, (effort === undefined || effort === 'none' ? { 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 = (0, endpoint_1.bearerAuthHeader)(config.apiKey);
     /* c8 ignore next 1 - optional logger */
     logger === null || logger === void 0 ? void 0 : logger.info(`OpenAI completion: model=${config.model}`);
@@ -330,17 +330,17 @@ 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, signal) {
+async function callOpenAiResponsesCompletion(config, prompt, tools, additionalMessages, temperature = 0.7, logger, signal, resolvedThinking) {
+    var _a;
     const url = `${config.baseUrl}/responses`;
     const input = (0, chatRequestBuilders_1.buildMessages)(prompt.system, (0, chatRequestBuilders_1.buildOpenAiResponsesUserContent)(prompt), {
         tail: additionalMessages
     });
-    const body = {
-        model: config.model,
-        input,
-        tools: (0, toolFormats_1.toResponsesApiTools)(tools),
-        temperature
-    };
+    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, input, tools: (0, toolFormats_1.toResponsesApiTools)(tools) }, (effort === undefined || effort === 'none' ? { 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 = (0, endpoint_1.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(',')}`);
@@ -383,23 +383,18 @@ function extractAnthropicText(content) {
     }
     return (0, ts_utils_1.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, signal) {
+/** Calls the Anthropic Messages API with optional tool support. @internal */
+async function callAnthropicCompletion(config, prompt, additionalMessages, temperature = 0.7, logger, tools, signal, resolvedThinking) {
     const url = `${config.baseUrl}/messages`;
-    // Anthropic uses system as a top-level field, not in messages
     const messages = (0, chatRequestBuilders_1.buildAnthropicMessages)(prompt, { tail: additionalMessages });
-    const body = {
-        model: config.model,
-        system: prompt.system,
-        messages,
-        max_tokens: 4096,
-        temperature
-    };
+    const body = Object.assign({ model: config.model, system: prompt.system, messages, max_tokens: 4096 }, ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.anthropicEffort) === undefined ? { temperature } : {}));
+    if ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.anthropicEffort) !== undefined) {
+        body.thinking = { type: 'enabled' };
+        body.output_config = { effort: resolvedThinking.anthropicEffort };
+    }
+    if ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.otherParams) !== undefined) {
+        Object.assign(body, resolvedThinking.otherParams);
+    }
     if (tools && tools.length > 0) {
         body.tools = (0, toolFormats_1.toAnthropicTools)(tools);
         /* c8 ignore next 3 - optional logger diagnostic output */
@@ -418,28 +413,18 @@ async function callAnthropicCompletion(config, prompt, additionalMessages, tempe
     if (jsonResult.isFailure()) {
         return (0, ts_utils_1.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 (0, ts_utils_1.fail)('Anthropic API response: content is not an array');
-        }
-        return extractAnthropicText(rawContent).onSuccess((text) => (0, ts_utils_1.succeed)({
-            content: text,
-            truncated: stopReason === 'max_tokens'
-        }));
+    const rawContent = jsonResult.value.content;
+    const stopReason = jsonResult.value.stop_reason;
+    if (!Array.isArray(rawContent)) {
+        return (0, ts_utils_1.fail)('Anthropic API response: content is not an array');
     }
-    return anthropicResponse
-        .validate(jsonResult.value)
-        .withErrorFormat((msg) => `Anthropic API response: ${msg}`)
-        .onSuccess((response) => {
-        return (0, ts_utils_1.succeed)({
-            content: response.content[0].text,
-            truncated: response.stop_reason === 'max_tokens'
-        });
-    });
+    if (typeof stopReason !== 'string') {
+        return (0, ts_utils_1.fail)('Anthropic API response: stop_reason is missing or not a string');
+    }
+    return extractAnthropicText(rawContent).onSuccess((text) => (0, ts_utils_1.succeed)({
+        content: text,
+        truncated: stopReason === 'max_tokens'
+    }));
 }
 // ============================================================================
 // Google Gemini adapter
@@ -449,14 +434,20 @@ 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, signal) {
+async function callGeminiCompletion(config, prompt, additionalMessages, temperature = 0.7, 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 = (0, chatRequestBuilders_1.buildGeminiContents)(prompt, { tail: additionalMessages });
+    const generationConfig = { 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 = (0, toolFormats_1.toGeminiTools)(tools);
@@ -490,23 +481,15 @@ async function callGeminiCompletion(config, prompt, additionalMessages, temperat
 // ============================================================================
 /**
  * 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
- *
+ * Routes by `apiFormat`: `'openai'` (xAI/OpenAI/Groq/Mistral — switches to Responses API when
+ * tools are set), `'anthropic'`, or `'gemini'`.
  * @param params - Request parameters including descriptor, API key, prompt, and optional tools
  * @returns The completion response with content and truncation status, or a failure
  * @public
  */
 async function callProviderCompletion(params) {
-    const { descriptor, apiKey, prompt, additionalMessages, temperature = 0.7, modelOverride, logger, tools, signal, endpoint } = params;
+    var _a;
+    const { descriptor, apiKey, prompt, additionalMessages, temperature, modelOverride, logger, tools, signal, endpoint, thinking } = params;
     const baseUrlResult = (0, endpoint_1.resolveEffectiveBaseUrl)(descriptor, endpoint);
     if (baseUrlResult.isFailure()) {
         return (0, ts_utils_1.fail)(baseUrlResult.message);
@@ -515,11 +498,31 @@ async function callProviderCompletion(params) {
         return (0, ts_utils_1.fail)(`provider "${descriptor.id}" does not accept image input`);
     }
     const hasTools = tools !== undefined && tools.length > 0;
-    const modelContext = hasTools ? 'tools' : undefined;
+    const discriminator = (0, thinkingOptionsResolver_1.providerDiscriminatorForId)(descriptor.id);
+    const hasThinkingConfig = discriminator !== undefined &&
+        ((thinking === null || thinking === void 0 ? void 0 : thinking.effort) !== undefined ||
+            ((_a = thinking === null || thinking === void 0 ? void 0 : thinking.providers) === null || _a === void 0 ? void 0 : _a.some((b) => b.provider === 'other' || b.provider === discriminator)) === true);
+    const modelContext = hasThinkingConfig ? 'thinking' : hasTools ? 'tools' : undefined;
     const model = (0, model_1.resolveModel)(modelOverride !== null && modelOverride !== void 0 ? modelOverride : descriptor.defaultModel, modelContext);
     if (model.length === 0) {
         return (0, ts_utils_1.fail)(`provider "${descriptor.id}": no model resolved; pass modelOverride or set descriptor.defaultModel`);
     }
+    let resolvedThinking;
+    if (thinking !== undefined) {
+        if (discriminator !== undefined) {
+            const mergeResult = (0, thinkingOptionsResolver_1.mergeThinkingConfig)(thinking, model, discriminator);
+            /* c8 ignore next 3 - mergeThinkingConfig always succeeds; defensive guard */
+            if (mergeResult.isFailure()) {
+                return (0, ts_utils_1.fail)(mergeResult.message);
+            }
+            resolvedThinking = mergeResult.value;
+            const conflictResult = (0, thinkingOptionsResolver_1.checkTemperatureConflict)(resolvedThinking, discriminator, temperature);
+            if (conflictResult.isFailure()) {
+                return (0, ts_utils_1.fail)(conflictResult.message);
+            }
+        }
+    }
+    const effectiveTemperature = temperature !== null && temperature !== void 0 ? temperature : 0.7;
     const config = {
         baseUrl: baseUrlResult.value,
         apiKey,
@@ -535,13 +538,13 @@ async function callProviderCompletion(params) {
     switch (descriptor.apiFormat) {
         case 'openai':
             if (hasTools) {
-                return callOpenAiResponsesCompletion(config, prompt, tools, additionalMessages, temperature, logger, signal);
+                return callOpenAiResponsesCompletion(config, prompt, tools, additionalMessages, effectiveTemperature, logger, signal, resolvedThinking);
             }
-            return callOpenAiCompletion(config, prompt, additionalMessages, temperature, logger, signal);
+            return callOpenAiCompletion(config, prompt, additionalMessages, effectiveTemperature, logger, signal, resolvedThinking);
         case 'anthropic':
-            return callAnthropicCompletion(config, prompt, additionalMessages, temperature, logger, tools, signal);
+            return callAnthropicCompletion(config, prompt, additionalMessages, effectiveTemperature, logger, tools, signal, resolvedThinking);
         case 'gemini':
-            return callGeminiCompletion(config, prompt, additionalMessages, temperature, logger, tools, signal);
+            return callGeminiCompletion(config, prompt, additionalMessages, effectiveTemperature, logger, tools, signal, resolvedThinking);
         /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
         default: {
             const _exhaustive = descriptor.apiFormat;
@@ -592,7 +595,13 @@ const proxiedImageGenerationResponse = ts_utils_1.Validators.object({
 });
 const proxiedListModelsEntry = ts_utils_1.Validators.object({
     id: ts_utils_1.Validators.string,
-    capabilities: ts_utils_1.Validators.arrayOf(ts_utils_1.Validators.enumeratedValue(['chat', 'tools', 'vision', 'image-generation'])),
+    capabilities: ts_utils_1.Validators.arrayOf(ts_utils_1.Validators.enumeratedValue([
+        'chat',
+        'tools',
+        'vision',
+        'image-generation',
+        'thinking'
+    ])),
     displayName: ts_utils_1.Validators.string.optional()
 });
 const proxiedListModelsResponse = ts_utils_1.Validators.object({
@@ -601,101 +610,160 @@ const proxiedListModelsResponse = ts_utils_1.Validators.object({
 // ============================================================================
 // 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 : [];
+/** 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 = (0, endpoint_1.bearerAuthHeader)(config.apiKey);
-    const n = (_c = opts.count) !== null && _c !== void 0 ? _c : 1;
+    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, request, headers, n, refs, logger, signal)
-        : await callOpenAiImagesGenerations(config, request, headers, n, logger, signal);
+        ? 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) => (0, ts_utils_1.succeed)({
-        images: response.data.map((item) => (Object.assign({ mimeType: defaultMimeType, base64: item.b64_json }, (item.revised_prompt !== undefined ? { revisedPrompt: item.revised_prompt } : {}))))
+        images: response.data.map((item) => (Object.assign({ mimeType: effectiveMimeType, 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) {
+/** Builds the JSON /images/generations request; handles outputParamStyle. @internal */
+function callOpenAiImagesGenerations(config, request, headers, resolved, capability, 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'
+        n: resolved.n
     };
-    if (opts.size !== undefined) {
-        body.size = opts.size;
+    // 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 (opts.quality !== undefined) {
-        body.quality = opts.quality;
+    if (resolved.seed !== undefined) {
+        body.seed = resolved.seed;
     }
-    if (opts.seed !== undefined) {
-        body.seed = opts.seed;
+    if (resolved.style !== undefined) {
+        body.style = resolved.style;
+    }
+    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=${n}`);
+    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 and posts the multipart `/images/edits` request (with refs).
- * @internal
- */
-async function callOpenAiImagesEdits(config, request, headers, n, refs, logger, signal) {
-    var _a;
+/** 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 = (0, ts_utils_1.mapResults)(refs.map((ref, i) => attachmentToBlob(ref).withErrorFormat((msg) => `reference image ${i}: ${msg}`)));
     /* c8 ignore next 3 - decode failure unreachable via Node's Buffer.from (silently strips invalid input) */
     if (blobsResult.isFailure()) {
         return (0, ts_utils_1.fail)(blobsResult.message);
     }
-    const opts = (_a = request.options) !== null && _a !== void 0 ? _a : {};
     const form = new FormData();
     form.append('model', config.model);
     form.append('prompt', request.prompt);
-    form.append('n', String(n));
-    form.append('response_format', 'b64_json');
-    if (opts.size !== undefined) {
-        form.append('size', opts.size);
+    form.append('n', String(resolved.n));
+    if (capability.outputParamStyle !== 'output-format') {
+        form.append('response_format', 'b64_json');
     }
-    if (opts.quality !== undefined) {
-        form.append('quality', opts.quality);
-    }
-    if (opts.seed !== undefined) {
-        form.append('seed', String(opts.seed));
+    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=${n}, refs=${refs.length}`);
+    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 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) {
+/** 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 (0, ts_utils_1.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`, (0, endpoint_1.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 = (0, endpoint_1.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) => (0, ts_utils_1.succeed)({
+        images: response.data.map((item) => {
+            var _a;
+            return ({
+                mimeType: (_a = capability.defaultOutputMimeType) !== null && _a !== void 0 ? _a : 'image/jpeg',
+                base64: item.b64_json
+            });
+        })
+    })));
+}
+/** 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 : [];
@@ -703,9 +771,17 @@ async function callGeminiImageOutGeneration(config, request, logger, signal) {
     for (const ref of refs) {
         parts.push({ inlineData: { mimeType: ref.mimeType, data: ref.base64 } });
     }
-    const body = {
-        contents: [{ role: 'user', parts }]
-    };
+    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
     };
@@ -732,33 +808,48 @@ async function callGeminiImageOutGeneration(config, request, logger, signal) {
         return (0, ts_utils_1.succeed)({ images });
     }));
 }
-/**
- * Calls the Gemini Imagen `:predict` endpoint.
- * @internal
- */
-async function callImagenGeneration(config, request, logger, signal) {
-    var _a, _b, _c, _d;
+/** Calls the Gemini Imagen :predict endpoint with Imagen 4 params. @internal */
+async function callImagenGeneration(config, request, resolved, logger, signal) {
     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
+        sampleCount: resolved.n
     };
-    if (((_c = opts.imagen) === null || _c === void 0 ? void 0 : _c.aspectRatio) !== undefined) {
-        parameters.aspectRatio = opts.imagen.aspectRatio;
+    if (resolved.imagenAspectRatio !== undefined) {
+        parameters.aspectRatio = resolved.imagenAspectRatio;
     }
-    if (((_d = opts.imagen) === null || _d === void 0 ? void 0 : _d.negativePrompt) !== undefined) {
-        parameters.negativePrompt = opts.imagen.negativePrompt;
+    if (resolved.imageSize !== undefined) {
+        parameters.imageSize = resolved.imageSize;
     }
-    if (opts.seed !== undefined) {
-        parameters.seed = opts.seed;
+    if (resolved.addWatermark !== undefined) {
+        parameters.addWatermark = resolved.addWatermark;
+    }
+    if (resolved.enhancePrompt !== undefined) {
+        parameters.enhancePrompt = resolved.enhancePrompt;
+    }
+    if (resolved.imagenOutputMimeType !== undefined || resolved.imagenOutputCompressionQuality !== undefined) {
+        const outputOptions = {};
+        if (resolved.imagenOutputMimeType !== undefined) {
+            outputOptions.mimeType = resolved.imagenOutputMimeType;
+        }
+        if (resolved.imagenOutputCompressionQuality !== undefined) {
+            outputOptions.compressionQuality = resolved.imagenOutputCompressionQuality;
+        }
+        parameters.outputOptions = outputOptions;
+    }
+    if (resolved.personGeneration !== undefined) {
+        parameters.personGeneration = resolved.personGeneration;
+    }
+    if (resolved.seed !== undefined) {
+        parameters.seed = resolved.seed;
+    }
+    if (resolved.otherParams !== undefined) {
+        Object.assign(parameters, resolved.otherParams);
     }
     const body = {
         instances: [{ prompt: request.prompt }],
         parameters
     };
-    const headers = {
-        'x-goog-api-key': config.apiKey
-    };
+    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);
@@ -784,25 +875,16 @@ async function callImagenGeneration(config, request, logger, signal) {
 // ============================================================================
 /**
  * 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`.
- *
+ * Routes by the `format` field of the resolved {@link IAiImageModelCapability}:
+ * `'openai-images'`, `'xai-images'`, `'xai-images-edits'`, `'gemini-imagen'`,
+ * 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
  * @returns The generated images, or a failure
  * @public
  */
 async function callProviderImageGeneration(params) {
-    var _a, _b;
+    var _a, _b, _c;
     const { descriptor, apiKey, params: request, modelOverride, logger, signal, endpoint } = params;
     if (!(0, registry_1.supportsImageGeneration)(descriptor)) {
         return (0, ts_utils_1.fail)(`provider "${descriptor.id}" does not support image generation`);
@@ -824,6 +906,11 @@ async function callProviderImageGeneration(params) {
     if (((_b = (_a = request.referenceImages) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0) > 0 && !capability.acceptsImageReferenceInput) {
         return (0, ts_utils_1.fail)(`model "${model}" does not support reference images`);
     }
+    const resolved = (0, imageOptionsResolver_1.resolveImageOptions)(model, capability, request.options);
+    const validationResult = (0, imageOptionsResolver_1.validateResolvedOptions)(model, capability, resolved);
+    if (validationResult.isFailure()) {
+        return (0, ts_utils_1.fail)(validationResult.message);
+    }
     const config = {
         baseUrl: baseUrlResult.value,
         apiKey,
@@ -836,13 +923,32 @@ async function callProviderImageGeneration(params) {
     }
     switch (capability.format) {
         case 'openai-images':
-            return callOpenAiImageGeneration(config, request, 'image/png', logger, signal);
+            return callOpenAiImageGeneration(config, request, capability, resolved, logger, signal);
         case 'xai-images':
-            return callOpenAiImageGeneration(config, request, 'image/jpeg', logger, signal);
+            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) => (0, ts_utils_1.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-imagen':
-            return callImagenGeneration(config, request, logger, signal);
+            return callImagenGeneration(config, request, resolved, logger, signal);
         case 'gemini-image-out':
-            return callGeminiImageOutGeneration(config, request, logger, signal);
+            return callGeminiImageOutGeneration(config, request, resolved, logger, signal);
         /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
         default: {
             const _exhaustive = capability.format;
@@ -896,6 +1002,7 @@ function geminiMethodsToCapabilities(methods) {
  * @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;
 }
 /**
@@ -1028,12 +1135,8 @@ async function callGeminiListModels(config, providerId, capabilityConfig, logger
 // 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.
- *
+ * 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 including descriptor, API key, and optional capability filter
  * @returns The resolved model list, or a failure
  * @public
@@ -1080,18 +1183,9 @@ async function callProviderListModels(params) {
 // ============================================================================
 /**
  * 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}`.
- *
+ * 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
  */
 async function callProxiedListModels(proxyUrl, params) {
@@ -1139,7 +1233,7 @@ async function callProxiedListModels(proxyUrl, params) {
  * @public
  */
 async function callProxiedCompletion(proxyUrl, params) {
-    const { descriptor, apiKey, prompt, additionalMessages, temperature, modelOverride, logger, tools, signal } = params;
+    const { descriptor, apiKey, prompt, additionalMessages, temperature, modelOverride, logger, tools, signal, thinking } = params;
     const promptBody = { system: prompt.system, user: prompt.user };
     if (prompt.attachments.length > 0) {
         promptBody.attachments = prompt.attachments;
@@ -1159,6 +1253,9 @@ 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`;
@@ -1166,7 +1263,6 @@ async function callProxiedCompletion(proxyUrl, params) {
     if (jsonResult.isFailure()) {
         return (0, ts_utils_1.fail)(jsonResult.message);
     }
-    // Check for error response from proxy
     const response = jsonResult.value;
     if (typeof response.error === 'string') {
         return (0, ts_utils_1.fail)(`proxy: ${response.error}`);
@@ -1185,20 +1281,11 @@ async function callProxiedCompletion(proxyUrl, params) {
 /**
  * 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`).
- *
+ * 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 (e.g. `http://localhost:3001`)
  * @param params - Same parameters as {@link callProviderImageGeneration}
  * @returns The generated images, or a failure