@fgv/ts-extras 5.1.0-5 → 5.1.0-50

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

@@ -0,0 +1,74 @@
+import { type Logging, Result } from '@fgv/ts-utils';
+import { type AiServerToolConfig, type IAiCompletionResponse, type IAiProviderDescriptor, type IChatRequest, type IThinkingConfig, type ModelSpec } from './model';
+/**
+ * Parameters for a provider completion request. Carries the unified
+ * {@link AiAssist.IChatRequest} shape (`system?` + ordered `messages`, last =
+ * current user turn); history is linearized before the current turn.
+ * @public
+ */
+export interface IProviderCompletionParams extends IChatRequest {
+    /** The provider descriptor */
+    readonly descriptor: IAiProviderDescriptor;
+    /** API key for authentication */
+    readonly apiKey: string;
+    /**
+     * Sampling temperature. Sent to the provider only when explicitly provided; omitted otherwise
+     * so the provider's own default applies (current-gen models reject a caller-supplied default).
+     */
+    readonly temperature?: number;
+    /** Optional model override — string or context-aware map (uses descriptor.defaultModel otherwise) */
+    readonly modelOverride?: ModelSpec;
+    /**
+     * Optional quality tier selecting which completion model to use. `undefined`
+     * selects the `base` tier; `'frontier'` cascades to `advanced` then `base`
+     * when a tier is unset for a provider. Orthogonal to `thinking` and `tools`,
+     * which never select a model.
+     */
+    readonly tier?: 'advanced' | 'frontier';
+    /** Optional logger for request/response observability. */
+    readonly logger?: Logging.ILogger;
+    /** Server-side tools to include in the request. Overrides settings-level tool config when provided. */
+    readonly tools?: ReadonlyArray<AiServerToolConfig>;
+    /** Optional abort signal for cancelling the in-flight request. */
+    readonly signal?: AbortSignal;
+    /**
+     * Optional override of the descriptor's default base URL (scheme + host +
+     * optional port + path prefix). The per-route suffix (e.g. `/chat/completions`)
+     * is appended unchanged. Must be a well-formed `http`/`https` URL. Auth shape
+     * is unchanged: `needsSecret` providers still require an API key.
+     */
+    readonly endpoint?: string;
+    /**
+     * Optional thinking/reasoning config. Anthropic, OpenAI, and xAI reject `temperature` when
+     * the effective merged effort is non-`'none'`; Gemini always accepts both.
+     */
+    readonly thinking?: IThinkingConfig;
+    /**
+     * Optional cap on generated output tokens, mapped to each provider's native field:
+     * Anthropic `max_tokens`, OpenAI Chat Completions `max_completion_tokens`, OpenAI/xAI
+     * Responses `max_output_tokens`, Gemini `generationConfig.maxOutputTokens`, and the
+     * xAI/Groq/Mistral/Ollama/`openai-compat` chat-completions path `max_tokens`. When unset,
+     * every provider except Anthropic omits the field and applies its own default; Anthropic's
+     * Messages API requires the field, so it falls back to `DEFAULT_ANTHROPIC_MAX_TOKENS`.
+     */
+    readonly maxTokens?: number;
+}
+/**
+ * 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 declare function callProviderCompletion(params: IProviderCompletionParams): Promise<Result<IAiCompletionResponse>>;
+/**
+ * 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}
+ * @public
+ */
+export declare function callProxiedCompletion(proxyUrl: string, params: IProviderCompletionParams): Promise<Result<IAiCompletionResponse>>;
+//# sourceMappingURL=completionClient.d.ts.map

package/lib/packlets/ai-assist/completionClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completionClient.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/completionClient.ts"],"names":[],"mappings":"AA8BA,OAAO,EAAQ,KAAK,OAAO,EAAE,MAAM,EAAuC,MAAM,eAAe,CAAC;AAEhG,OAAO,EAEL,KAAK,kBAAkB,EAEvB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAE1B,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,SAAS,EAMf,MAAM,SAAS,CAAC;AA8BjB;;;;;GAKG;AACH,MAAM,WAAW,yBAA0B,SAAQ,YAAY;IAC7D,8BAA8B;IAC9B,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;IAC3C,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,qGAAqG;IACrG,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACxC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC;IAClC,uGAAuG;IACvG,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;IACnD,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;IACpC;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AA0aD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC,CAqIxC;AAMD;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC,CAwExC"}

package/lib/packlets/ai-assist/{apiClient.js → completionClient.js}

@@ -21,86 +21,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.callProviderCompletion = callProviderCompletion;
 exports.callProxiedCompletion = callProxiedCompletion;
-/**
- * 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.
- *
- * @packageDocumentation
- */
-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 http_1 = require("./http");
 const toolFormats_1 = require("./toolFormats");
-// ============================================================================
-// Shared helpers
-// ============================================================================
-/**
- * Builds the messages array from prompt + optional correction messages.
- * @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 });
-        }
-    }
-    return messages;
-}
-/**
- * Makes an HTTP request and returns the parsed JSON, or a failure.
- * @internal
- */
-async function fetchJson(url, headers, body, logger) {
-    /* c8 ignore next 1 - optional logger */
-    logger === null || logger === void 0 ? void 0 : logger.detail(`AI API request: POST ${url}`);
-    let response;
-    try {
-        response = await fetch(url, {
-            method: 'POST',
-            headers: Object.assign({ 'Content-Type': 'application/json' }, headers),
-            body: JSON.stringify(body)
-        });
-    }
-    catch (err) {
-        const detail = err instanceof Error ? err.message : String(err);
-        /* c8 ignore next 1 - optional logger */
-        logger === null || logger === void 0 ? void 0 : logger.error(`AI API request failed: ${detail}`);
-        return (0, ts_utils_1.fail)(`AI API request failed: ${detail}`);
-    }
-    if (!response.ok) {
-        const errorText = await response.text().catch(() => 'unknown error');
-        /* c8 ignore next 1 - optional logger */
-        logger === null || logger === void 0 ? void 0 : logger.error(`AI API returned ${response.status}: ${errorText}`);
-        return (0, ts_utils_1.fail)(`AI API returned ${response.status}: ${errorText}`);
-    }
-    /* c8 ignore next 1 - optional logger */
-    logger === null || logger === void 0 ? void 0 : logger.detail(`AI API response: ${response.status}`);
-    let json;
-    try {
-        json = await response.json();
-    }
-    catch (_a) {
-        /* c8 ignore next 1 - optional logger */
-        logger === null || logger === void 0 ? void 0 : logger.error('AI API returned invalid JSON response');
-        return (0, ts_utils_1.fail)('AI API returned invalid JSON response');
-    }
-    if (!(0, ts_json_base_1.isJsonObject)(json)) {
-        /* c8 ignore next 1 - optional logger */
-        logger === null || logger === void 0 ? void 0 : logger.error('AI API returned non-object JSON response');
-        return (0, ts_utils_1.fail)('AI API returned non-object JSON response');
-    }
-    return (0, ts_utils_1.succeed)(json);
-}
 const openAiMessage = ts_utils_1.Validators.object({
     content: ts_utils_1.Validators.string
 });
@@ -125,13 +52,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
 });
@@ -153,16 +73,22 @@ 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) {
+async function callOpenAiCompletion(config, prompt, head, temperature, logger, signal, resolvedThinking, maxTokens, useMaxCompletionTokensField = false) {
+    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 = (0, chatRequestBuilders_1.buildMessages)(prompt.system, (0, chatRequestBuilders_1.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 maxTokensField = useMaxCompletionTokensField ? 'max_completion_tokens' : 'max_tokens';
+    const body = Object.assign(Object.assign(Object.assign({ model: config.model, messages }, (temperature !== undefined ? { temperature } : {})), (effort !== undefined && config.model !== 'grok-4' ? { reasoning_effort: effort } : {})), (maxTokens !== undefined ? { [maxTokensField]: maxTokens } : {}));
+    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}`);
-    const jsonResult = await fetchJson(url, headers, body, logger);
+    const jsonResult = await (0, http_1.fetchJson)(url, headers, body, logger, signal);
     if (jsonResult.isFailure()) {
         return (0, ts_utils_1.fail)(jsonResult.message);
     }
@@ -201,21 +127,25 @@ 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, maxTokens) {
+    var _a;
     const url = `${config.baseUrl}/responses`;
-    const input = buildMessages(prompt, additionalMessages);
-    const body = {
-        model: config.model,
-        input,
-        tools: (0, toolFormats_1.toResponsesApiTools)(tools),
-        temperature
-    };
-    const headers = {
-        Authorization: `Bearer ${config.apiKey}`
-    };
+    const input = (0, chatRequestBuilders_1.buildMessages)(prompt.system, (0, chatRequestBuilders_1.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: (0, toolFormats_1.toResponsesApiTools)(tools) } : {})), (temperature !== undefined ? { temperature } : {})), (effort !== undefined && config.model !== 'grok-4' ? { reasoning: { effort } } : {}));
+    // Shared by OpenAI and xAI — both route through the Responses API with the same field name.
+    if (maxTokens !== undefined) {
+        body.max_output_tokens = maxTokens;
+    }
+    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(',')}`);
-    const jsonResult = await fetchJson(url, headers, body, logger);
+    const jsonResult = await (0, http_1.fetchJson)(url, headers, body, logger, signal);
     if (jsonResult.isFailure()) {
         return (0, ts_utils_1.fail)(jsonResult.message);
     }
@@ -254,31 +184,29 @@ 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) {
+/** Calls the Anthropic Messages API with optional tool support. @internal */
+async function callAnthropicCompletion(config, prompt, head, temperature, logger, tools, signal, resolvedThinking, useAdaptiveThinking = false, maxTokens) {
     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 = (0, chatRequestBuilders_1.buildAnthropicMessages)(prompt, { head });
+    const body = Object.assign({ model: config.model, system: prompt.system, messages, 
+        // Anthropic's Messages API requires max_tokens on every request — see
+        // AiAssist.DEFAULT_ANTHROPIC_MAX_TOKENS for why only this provider defaults it.
+        max_tokens: maxTokens !== null && maxTokens !== void 0 ? maxTokens : model_1.DEFAULT_ANTHROPIC_MAX_TOKENS }, (temperature !== undefined ? { temperature } : {}));
+    const effort = resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.anthropicEffort;
+    if (effort !== undefined) {
+        if (useAdaptiveThinking) {
+            // Claude 5 family: adaptive thinking — no budget_tokens; effort moves to the
+            // top-level output_config block. See AiAssist.isAdaptiveThinkingModel.
+            body.thinking = { type: 'adaptive' };
+            body.output_config = { effort };
+        }
+        else {
+            body.thinking = { type: 'enabled', budget_tokens: (0, thinkingOptionsResolver_1.anthropicEffortToBudgetTokens)(effort) };
         }
     }
-    const body = {
-        model: config.model,
-        system: prompt.system,
-        messages,
-        max_tokens: 4096,
-        temperature
-    };
+    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 */
@@ -288,37 +216,23 @@ async function callAnthropicCompletion(config, prompt, additionalMessages, tempe
         /* c8 ignore next 1 - optional logger */
         logger === null || logger === void 0 ? void 0 : logger.info(`Anthropic completion: model=${config.model}`);
     }
-    const headers = {
-        'x-api-key': config.apiKey,
-        'anthropic-version': '2023-06-01',
-        'anthropic-dangerous-direct-browser-access': 'true'
-    };
-    const jsonResult = await fetchJson(url, headers, body, logger);
+    const headers = (0, endpoint_1.anthropicAuthHeaders)(config.apiKey);
+    const jsonResult = await (0, http_1.fetchJson)(url, headers, body, logger, signal);
     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
@@ -328,26 +242,27 @@ 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, maxTokens) {
     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 = (0, chatRequestBuilders_1.buildGeminiContents)(prompt, { head });
+    // Temperature is sent only when explicitly provided; otherwise Gemini's default applies.
+    const generationConfig = {};
+    if (temperature !== undefined) {
+        generationConfig.temperature = temperature;
+    }
+    if (maxTokens !== undefined) {
+        generationConfig.maxOutputTokens = maxTokens;
+    }
+    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);
@@ -358,10 +273,8 @@ async function callGeminiCompletion(config, prompt, additionalMessages, temperat
         /* c8 ignore next 1 - optional logger */
         logger === null || logger === void 0 ? void 0 : logger.info(`Gemini completion: model=${config.model}`);
     }
-    const headers = {
-        'x-goog-api-key': config.apiKey
-    };
-    const jsonResult = await fetchJson(url, headers, body, logger);
+    const headers = (0, endpoint_1.geminiAuthHeader)(config.apiKey);
+    const jsonResult = await (0, http_1.fetchJson)(url, headers, body, logger, signal);
     if (jsonResult.isFailure()) {
         return (0, ts_utils_1.fail)(jsonResult.message);
     }
@@ -380,33 +293,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
  */
 async function callProviderCompletion(params) {
-    const { descriptor, apiKey, prompt, additionalMessages, temperature = 0.7, modelOverride, logger, tools } = params;
-    if (!descriptor.baseUrl) {
-        return (0, ts_utils_1.fail)(`provider "${descriptor.id}" has no API endpoint configured`);
+    const { descriptor, apiKey, system, messages, temperature, modelOverride, tier, logger, tools, signal, endpoint, thinking, maxTokens } = params;
+    const splitResult = (0, chatRequestBuilders_1.splitChatRequest)(system, messages);
+    if (splitResult.isFailure()) {
+        return (0, ts_utils_1.fail)(splitResult.message);
+    }
+    const { prompt, head } = splitResult.value;
+    const baseUrlResult = (0, endpoint_1.resolveEffectiveBaseUrl)(descriptor, endpoint);
+    if (baseUrlResult.isFailure()) {
+        return (0, ts_utils_1.fail)(baseUrlResult.message);
+    }
+    if (prompt.attachments.length > 0 && !descriptor.acceptsImageInput) {
+        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);
+    // 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 = (0, model_1.resolveProviderModel)(descriptor, modelOverride, modelContext);
+    if (modelResult.isFailure()) {
+        return (0, ts_utils_1.fail)(modelResult.message);
+    }
+    const model = modelResult.value;
+    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 config = {
-        baseUrl: descriptor.baseUrl,
+        baseUrl: baseUrlResult.value,
         apiKey,
-        model: (0, model_1.resolveModel)(modelOverride !== null && modelOverride !== void 0 ? modelOverride : descriptor.defaultModel, modelContext)
+        model
     };
     /* c8 ignore next 8 - optional logger diagnostic output */
     if (logger) {
@@ -417,14 +351,16 @@ 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 || (0, model_1.isResponsesOnlyModel)(descriptor, config.model)) {
+                return callOpenAiResponsesCompletion(config, prompt, tools, head, temperature, logger, signal, resolvedThinking, maxTokens);
             }
-            return callOpenAiCompletion(config, prompt, additionalMessages, temperature, logger);
+            return callOpenAiCompletion(config, prompt, head, temperature, logger, signal, resolvedThinking, maxTokens, (0, model_1.usesMaxCompletionTokensField)(descriptor));
         case 'anthropic':
-            return callAnthropicCompletion(config, prompt, additionalMessages, temperature, logger, tools);
+            return callAnthropicCompletion(config, prompt, head, temperature, logger, tools, signal, resolvedThinking, (0, model_1.isAdaptiveThinkingModel)(descriptor, config.model), maxTokens);
         case 'gemini':
-            return callGeminiCompletion(config, prompt, additionalMessages, temperature, logger, tools);
+            return callGeminiCompletion(config, prompt, head, temperature, logger, tools, signal, resolvedThinking, maxTokens);
         /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
         default: {
             const _exhaustive = descriptor.apiFormat;
@@ -436,28 +372,36 @@ async function callProviderCompletion(params) {
 // 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
  */
 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, maxTokens } = params;
+    const splitResult = (0, chatRequestBuilders_1.splitChatRequest)(system, messages);
+    if (splitResult.isFailure()) {
+        return (0, ts_utils_1.fail)(splitResult.message);
+    }
+    if (splitResult.value.prompt.attachments.length > 0 && !descriptor.acceptsImageInput) {
+        return (0, ts_utils_1.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: (0, chatRequestBuilders_1.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;
@@ -465,14 +409,21 @@ async function callProxiedCompletion(proxyUrl, params) {
     if (tools && tools.length > 0) {
         body.tools = tools;
     }
+    if (thinking !== undefined) {
+        body.thinking = thinking;
+    }
+    // Forwarded only when explicitly provided; the proxy is responsible for mapping it to the
+    // correct upstream provider field (see AiAssist.usesMaxCompletionTokensField).
+    if (maxTokens !== undefined) {
+        body.maxTokens = maxTokens;
+    }
     /* 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 (0, http_1.fetchJson)(url, {}, body, logger, signal);
     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}`);
@@ -485,4 +436,4 @@ async function callProxiedCompletion(proxyUrl, params) {
         truncated: response.truncated === true
     });
 }
-//# sourceMappingURL=apiClient.js.map
+//# sourceMappingURL=completionClient.js.map