@fgv/ts-extras 5.1.0-33 → 5.1.0-35

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

@@ -19,74 +19,26 @@
 // 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, mapResults, succeed, Validators } from '@fgv/ts-utils';
-import { resolveModel } from './model';
-import { checkTemperatureConflict, mergeThinkingConfig, providerDiscriminatorForId } from './thinkingOptionsResolver';
-import { buildAnthropicMessages, buildGeminiContents, buildMessages, buildOpenAiChatUserContent, buildOpenAiResponsesUserContent } from './chatRequestBuilders';
+import { allModelCapabilities, resolveModel } 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
 // ============================================================================
-/**
- * Makes an HTTP request and returns the parsed JSON, or a failure.
- * @internal
- */
-async function fetchJson(url, headers, body, logger, signal) {
-    /* c8 ignore next 1 - optional logger */
-    logger === null || logger === void 0 ? void 0 : logger.detail(`AI API request: POST ${url}`);
-    let response;
-    try {
-        response = await fetch(url, {
-            method: 'POST',
-            headers: Object.assign({ 'Content-Type': 'application/json' }, headers),
-            body: JSON.stringify(body),
-            signal
-        });
-    }
-    catch (err) {
-        const detail = err instanceof Error ? err.message : String(err);
-        /* c8 ignore next 1 - optional logger */
-        logger === null || logger === void 0 ? void 0 : logger.error(`AI API request failed: ${detail}`);
-        return fail(`AI API request failed: ${detail}`);
-    }
-    if (!response.ok) {
-        const errorText = await response.text().catch(() => 'unknown error');
-        /* c8 ignore next 1 - optional logger */
-        logger === null || logger === void 0 ? void 0 : logger.error(`AI API returned ${response.status}: ${errorText}`);
-        return fail(`AI API returned ${response.status}: ${errorText}`);
-    }
-    /* c8 ignore next 1 - optional logger */
-    logger === null || logger === void 0 ? void 0 : logger.detail(`AI API response: ${response.status}`);
-    let json;
-    try {
-        json = await response.json();
-    }
-    catch (_a) {
-        /* c8 ignore next 1 - optional logger */
-        logger === null || logger === void 0 ? void 0 : logger.error('AI API returned invalid JSON response');
-        return fail('AI API returned invalid JSON response');
-    }
-    if (!isJsonObject(json)) {
-        /* c8 ignore next 1 - optional logger */
-        logger === null || logger === void 0 ? void 0 : logger.error('AI API returned non-object JSON response');
-        return fail('AI API returned non-object JSON response');
-    }
-    return succeed(json);
-}
 /**
  * Makes a multipart/form-data POST request and returns the parsed JSON, or a
  * failure. The Content-Type header (with boundary) is set automatically by
@@ -269,11 +221,11 @@ const geminiResponse = Validators.object({
  * Works for xAI Grok, OpenAI, Groq, and Mistral.
  * @internal
  */
-async function callOpenAiCompletion(config, prompt, additionalMessages, temperature = 0.7, logger, signal, resolvedThinking) {
+async function callOpenAiCompletion(config, prompt, head, temperature = 0.7, logger, signal, resolvedThinking) {
     var _a;
     const url = `${config.baseUrl}/chat/completions`;
     const messages = buildMessages(prompt.system, buildOpenAiChatUserContent(prompt), {
-        tail: additionalMessages
+        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 }, (effort === undefined || effort === 'none' ? { temperature } : {})), (effort !== undefined && config.model !== 'grok-4' ? { reasoning_effort: effort } : {}));
@@ -322,11 +274,11 @@ 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, resolvedThinking) {
+async function callOpenAiResponsesCompletion(config, prompt, tools, head, temperature = 0.7, logger, signal, resolvedThinking) {
     var _a;
     const url = `${config.baseUrl}/responses`;
     const input = buildMessages(prompt.system, buildOpenAiResponsesUserContent(prompt), {
-        tail: additionalMessages
+        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, input, tools: toResponsesApiTools(tools) }, (effort === undefined || effort === 'none' ? { temperature } : {})), (effort !== undefined && config.model !== 'grok-4' ? { reasoning: { effort } } : {}));
@@ -376,13 +328,13 @@ function extractAnthropicText(content) {
     return succeed(textParts.join(''));
 }
 /** Calls the Anthropic Messages API with optional tool support. @internal */
-async function callAnthropicCompletion(config, prompt, additionalMessages, temperature = 0.7, logger, tools, signal, resolvedThinking) {
+async function callAnthropicCompletion(config, prompt, head, temperature = 0.7, logger, tools, signal, resolvedThinking) {
     const url = `${config.baseUrl}/messages`;
-    const messages = buildAnthropicMessages(prompt, { tail: additionalMessages });
+    const messages = buildAnthropicMessages(prompt, { head });
     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 };
+    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);
@@ -426,9 +378,9 @@ 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, resolvedThinking) {
+async function callGeminiCompletion(config, prompt, head, temperature = 0.7, logger, tools, signal, resolvedThinking) {
     const url = `${config.baseUrl}/models/${config.model}:generateContent`;
-    const contents = buildGeminiContents(prompt, { tail: additionalMessages });
+    const contents = buildGeminiContents(prompt, { head });
     const generationConfig = { temperature };
     if ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.geminiThinkingBudget) !== undefined) {
         generationConfig.thinkingConfig = { thinkingBudget: resolvedThinking.geminiThinkingBudget };
@@ -472,16 +424,19 @@ async function callGeminiCompletion(config, prompt, additionalMessages, temperat
 // Provider dispatcher
 // ============================================================================
 /**
- * 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'`.
- * @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) {
     var _a;
-    const { descriptor, apiKey, prompt, additionalMessages, temperature, modelOverride, logger, tools, signal, endpoint, thinking } = params;
+    const { descriptor, apiKey, system, messages, temperature, modelOverride, 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);
@@ -530,13 +485,13 @@ export async function callProviderCompletion(params) {
     switch (descriptor.apiFormat) {
         case 'openai':
             if (hasTools) {
-                return callOpenAiResponsesCompletion(config, prompt, tools, additionalMessages, effectiveTemperature, logger, signal, resolvedThinking);
+                return callOpenAiResponsesCompletion(config, prompt, tools, head, effectiveTemperature, logger, signal, resolvedThinking);
             }
-            return callOpenAiCompletion(config, prompt, additionalMessages, effectiveTemperature, logger, signal, resolvedThinking);
+            return callOpenAiCompletion(config, prompt, head, effectiveTemperature, logger, signal, resolvedThinking);
         case 'anthropic':
-            return callAnthropicCompletion(config, prompt, additionalMessages, effectiveTemperature, logger, tools, signal, resolvedThinking);
+            return callAnthropicCompletion(config, prompt, head, effectiveTemperature, logger, tools, signal, resolvedThinking);
         case 'gemini':
-            return callGeminiCompletion(config, prompt, additionalMessages, effectiveTemperature, logger, tools, signal, resolvedThinking);
+            return callGeminiCompletion(config, prompt, head, effectiveTemperature, logger, tools, signal, resolvedThinking);
         /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
         default: {
             const _exhaustive = descriptor.apiFormat;
@@ -587,13 +542,7 @@ const proxiedImageGenerationResponse = Validators.object({
 });
 const proxiedListModelsEntry = Validators.object({
     id: Validators.string,
-    capabilities: Validators.arrayOf(Validators.enumeratedValue([
-        'chat',
-        'tools',
-        'vision',
-        'image-generation',
-        'thinking'
-    ])),
+    capabilities: Validators.arrayOf(Validators.enumeratedValue(allModelCapabilities)),
     displayName: Validators.string.optional()
 });
 const proxiedListModelsResponse = Validators.object({
@@ -866,13 +815,12 @@ async function callImagenGeneration(config, request, resolved, logger, signal) {
 // 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'`, `'gemini-imagen'`,
- * or `'gemini-image-out'`. Rejects up front if `referenceImages` is set but the
+ * 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'`, `'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
  */
 export async function callProviderImageGeneration(params) {
@@ -1129,8 +1077,7 @@ async function callGeminiListModels(config, providerId, capabilityConfig, logger
 /**
  * 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
+ * @param params - Request parameters (descriptor, API key, optional capability filter)
  * @public
  */
 export async function callProviderListModels(params) {
@@ -1174,10 +1121,10 @@ export async function callProviderListModels(params) {
 // 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}`.
+ * 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) {
@@ -1212,32 +1159,32 @@ export async function callProxiedListModels(proxyUrl, 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
  */
 export async function callProxiedCompletion(proxyUrl, 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;
+    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: promptBody,
+        messages: normalizeOutboundMessages(splitResult.value),
         temperature: temperature !== null && temperature !== void 0 ? temperature : 0.7
     };
-    if (additionalMessages && additionalMessages.length > 0) {
-        body.additionalMessages = additionalMessages;
+    if (system !== undefined) {
+        body.system = system;
     }
     if (modelOverride !== undefined) {
         body.modelOverride = modelOverride;
@@ -1278,9 +1225,8 @@ export async function callProxiedCompletion(proxyUrl, params) {
  * 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 proxyUrl - Base URL of the proxy server
  * @param params - Same parameters as {@link callProviderImageGeneration}
- * @returns The generated images, or a failure
  * @public
  */
 export async function callProxiedImageGeneration(proxyUrl, params) {