@fgv/ts-extras 5.1.0-34 → 5.1.0-36

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

@@ -1,18 +1,16 @@
 import { type Logging, Result } from '@fgv/ts-utils';
-import { AiPrompt, type AiModelCapability, type AiServerToolConfig, type IAiCompletionResponse, type IAiImageGenerationParams, type IAiImageGenerationResponse, type IAiModelCapabilityConfig, type IAiModelInfo, type IAiProviderDescriptor, type IChatMessage, type IThinkingConfig, type ModelSpec } from './model';
+import { type AiModelCapability, type AiServerToolConfig, type IAiCompletionResponse, type IAiImageGenerationParams, type IAiImageGenerationResponse, type IAiModelCapabilityConfig, type IAiModelInfo, type IAiProviderDescriptor, type IChatRequest, type IThinkingConfig, type ModelSpec } from './model';
 /**
- * Parameters for a provider completion request.
+ * 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 {
+export interface IProviderCompletionParams extends IChatRequest {
     /** The provider descriptor */
     readonly descriptor: IAiProviderDescriptor;
     /** API key for authentication */
     readonly apiKey: string;
-    /** The structured prompt to send */
-    readonly prompt: AiPrompt;
-    /** Additional messages to append after system+user in order (e.g. for correction retries). */
-    readonly additionalMessages?: ReadonlyArray<IChatMessage>;
     /** Sampling temperature (default: 0.7) */
     readonly temperature?: number;
     /** Optional model override — string or context-aware map (uses descriptor.defaultModel otherwise) */
@@ -37,11 +35,9 @@ export interface IProviderCompletionParams {
     readonly thinking?: IThinkingConfig;
 }
 /**
- * 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 declare function callProviderCompletion(params: IProviderCompletionParams): Promise<Result<IAiCompletionResponse>>;
@@ -66,13 +62,12 @@ export interface IProviderImageGenerationParams {
     readonly endpoint?: string;
 }
 /**
- * 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 declare function callProviderImageGeneration(params: IProviderImageGenerationParams): Promise<Result<IAiImageGenerationResponse>>;
@@ -99,30 +94,26 @@ export interface IProviderListModelsParams {
 /**
  * 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 declare function callProviderListModels(params: IProviderListModelsParams): Promise<Result<ReadonlyArray<IAiModelInfo>>>;
 /**
- * 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 declare function callProxiedListModels(proxyUrl: string, params: IProviderListModelsParams): Promise<Result<ReadonlyArray<IAiModelInfo>>>;
 /**
- * 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 declare function callProxiedCompletion(proxyUrl: string, params: IProviderCompletionParams): Promise<Result<IAiCompletionResponse>>;
@@ -134,9 +125,8 @@ export declare function callProxiedCompletion(proxyUrl: string, params: IProvide
  * 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 declare function callProxiedImageGeneration(proxyUrl: string, params: IProviderImageGenerationParams): Promise<Result<IAiImageGenerationResponse>>;

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

@@ -1 +1 @@
-{"version":3,"file":"apiClient.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/apiClient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"apiClient.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/apiClient.ts"],"names":[],"mappings":"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"}

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

@@ -27,13 +27,10 @@ exports.callProxiedCompletion = callProxiedCompletion;
 exports.callProxiedImageGeneration = callProxiedImageGeneration;
 /**
  * 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
  */
@@ -43,58 +40,13 @@ 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 registry_1 = require("./registry");
 const imageOptionsResolver_1 = require("./imageOptionsResolver");
 const toolFormats_1 = require("./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 (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);
-}
 /**
  * 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
@@ -277,11 +229,11 @@ 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, resolvedThinking) {
+async function callOpenAiCompletion(config, prompt, head, 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
+        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 } : {}));
@@ -291,7 +243,7 @@ async function callOpenAiCompletion(config, prompt, additionalMessages, temperat
     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, signal);
+    const jsonResult = await (0, http_1.fetchJson)(url, headers, body, logger, signal);
     if (jsonResult.isFailure()) {
         return (0, ts_utils_1.fail)(jsonResult.message);
     }
@@ -330,11 +282,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 = (0, chatRequestBuilders_1.buildMessages)(prompt.system, (0, chatRequestBuilders_1.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: (0, toolFormats_1.toResponsesApiTools)(tools) }, (effort === undefined || effort === 'none' ? { temperature } : {})), (effort !== undefined && config.model !== 'grok-4' ? { reasoning: { effort } } : {}));
@@ -344,7 +296,7 @@ async function callOpenAiResponsesCompletion(config, prompt, tools, additionalMe
     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, signal);
+    const jsonResult = await (0, http_1.fetchJson)(url, headers, body, logger, signal);
     if (jsonResult.isFailure()) {
         return (0, ts_utils_1.fail)(jsonResult.message);
     }
@@ -384,9 +336,9 @@ function extractAnthropicText(content) {
     return (0, ts_utils_1.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 = (0, chatRequestBuilders_1.buildAnthropicMessages)(prompt, { tail: additionalMessages });
+    const messages = (0, chatRequestBuilders_1.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 } : {}));
     const effort = resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.anthropicEffort;
     if (effort !== undefined) {
@@ -409,7 +361,7 @@ async function callAnthropicCompletion(config, prompt, additionalMessages, tempe
         'anthropic-version': '2023-06-01',
         'anthropic-dangerous-direct-browser-access': 'true'
     };
-    const jsonResult = await fetchJson(url, headers, body, logger, signal);
+    const jsonResult = await (0, http_1.fetchJson)(url, headers, body, logger, signal);
     if (jsonResult.isFailure()) {
         return (0, ts_utils_1.fail)(jsonResult.message);
     }
@@ -434,9 +386,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 = (0, chatRequestBuilders_1.buildGeminiContents)(prompt, { tail: additionalMessages });
+    const contents = (0, chatRequestBuilders_1.buildGeminiContents)(prompt, { head });
     const generationConfig = { temperature };
     if ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.geminiThinkingBudget) !== undefined) {
         generationConfig.thinkingConfig = { thinkingBudget: resolvedThinking.geminiThinkingBudget };
@@ -461,7 +413,7 @@ async function callGeminiCompletion(config, prompt, additionalMessages, temperat
     const headers = {
         'x-goog-api-key': config.apiKey
     };
-    const jsonResult = await fetchJson(url, headers, body, logger, signal);
+    const jsonResult = await (0, http_1.fetchJson)(url, headers, body, logger, signal);
     if (jsonResult.isFailure()) {
         return (0, ts_utils_1.fail)(jsonResult.message);
     }
@@ -480,16 +432,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
  */
 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 = (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);
@@ -538,13 +493,13 @@ 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;
@@ -595,13 +550,7 @@ 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',
-        'thinking'
-    ])),
+    capabilities: ts_utils_1.Validators.arrayOf(ts_utils_1.Validators.enumeratedValue(model_1.allModelCapabilities)),
     displayName: ts_utils_1.Validators.string.optional()
 });
 const proxiedListModelsResponse = ts_utils_1.Validators.object({
@@ -669,7 +618,7 @@ function callOpenAiImagesGenerations(config, request, headers, resolved, capabil
     }
     /* c8 ignore next 1 - optional logger */
     logger === null || logger === void 0 ? void 0 : logger.info(`Image generation: model=${config.model}, n=${resolved.n}`);
-    return fetchJson(`${config.baseUrl}/images/generations`, headers, body, logger, signal);
+    return (0, http_1.fetchJson)(`${config.baseUrl}/images/generations`, headers, body, logger, signal);
 }
 /** Builds the multipart /images/edits request with ref images. @internal */
 async function callOpenAiImagesEdits(config, capability, request, headers, resolved, logger, signal) {
@@ -726,7 +675,7 @@ async function callXaiImagesEdits(config, request, resolved, logger, signal) {
     }
     /* 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);
+    return (0, http_1.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) {
@@ -748,7 +697,7 @@ async function callXaiImageGeneration(config, request, capability, resolved, log
     }
     /* 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);
+    const fetched = await (0, http_1.fetchJson)(`${config.baseUrl}/images/generations`, headers, body, logger, signal);
     return fetched.onSuccess((json) => openAiImageResponse
         .validate(json)
         .withErrorFormat((msg) => `xAI images API response: ${msg}`)
@@ -787,7 +736,7 @@ async function callGeminiImageOutGeneration(config, request, resolved, logger, s
     };
     /* c8 ignore next 1 - optional logger */
     logger === null || logger === void 0 ? void 0 : logger.info(`Gemini image-out: model=${config.model}, refs=${refs.length}`);
-    return (await fetchJson(url, headers, body, logger, signal)).onSuccess((json) => geminiImageOutResponse
+    return (await (0, http_1.fetchJson)(url, headers, body, logger, signal)).onSuccess((json) => geminiImageOutResponse
         .validate(json)
         .withErrorFormat((msg) => `Gemini image API response: ${msg}`)
         .onSuccess((response) => {
@@ -852,7 +801,7 @@ async function callImagenGeneration(config, request, resolved, logger, signal) {
     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);
+    const jsonResult = await (0, http_1.fetchJson)(url, headers, body, logger, signal);
     if (jsonResult.isFailure()) {
         return (0, ts_utils_1.fail)(jsonResult.message);
     }
@@ -874,13 +823,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
  */
 async function callProviderImageGeneration(params) {
@@ -1137,8 +1085,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
  */
 async function callProviderListModels(params) {
@@ -1182,10 +1129,10 @@ 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
  */
 async function callProxiedListModels(proxyUrl, params) {
@@ -1200,7 +1147,7 @@ async function callProxiedListModels(proxyUrl, params) {
     /* c8 ignore next 1 - optional logger */
     logger === null || logger === void 0 ? void 0 : logger.info(`AI list-models proxy request: provider=${descriptor.id}, proxy=${proxyUrl}`);
     const url = `${proxyUrl}/api/ai/list-models`;
-    const jsonResult = await fetchJson(url, {}, body, logger, signal);
+    const jsonResult = await (0, http_1.fetchJson)(url, {}, body, logger, signal);
     if (jsonResult.isFailure()) {
         return (0, ts_utils_1.fail)(jsonResult.message);
     }
@@ -1220,32 +1167,32 @@ 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
  */
 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 = (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: promptBody,
+        messages: (0, chatRequestBuilders_1.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;
@@ -1259,7 +1206,7 @@ async function callProxiedCompletion(proxyUrl, params) {
     /* c8 ignore next 1 - optional logger */
     logger === null || logger === void 0 ? void 0 : logger.info(`AI proxy request: provider=${descriptor.id}, proxy=${proxyUrl}`);
     const url = `${proxyUrl}/api/ai/completion`;
-    const jsonResult = await fetchJson(url, {}, body, logger, signal);
+    const jsonResult = await (0, http_1.fetchJson)(url, {}, body, logger, signal);
     if (jsonResult.isFailure()) {
         return (0, ts_utils_1.fail)(jsonResult.message);
     }
@@ -1286,9 +1233,8 @@ 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
  */
 async function callProxiedImageGeneration(proxyUrl, params) {
@@ -1304,7 +1250,7 @@ async function callProxiedImageGeneration(proxyUrl, params) {
     /* c8 ignore next 1 - optional logger */
     logger === null || logger === void 0 ? void 0 : logger.info(`AI image proxy request: provider=${descriptor.id}, proxy=${proxyUrl}`);
     const url = `${proxyUrl}/api/ai/image-generation`;
-    const jsonResult = await fetchJson(url, {}, body, logger, signal);
+    const jsonResult = await (0, http_1.fetchJson)(url, {}, body, logger, signal);
     if (jsonResult.isFailure()) {
         return (0, ts_utils_1.fail)(jsonResult.message);
     }