@fgv/ts-extras 5.0.2 → 5.1.0-0

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.54.0"
+      "packageVersion": "7.57.6"
     }
   ]
 }

package/lib/index.browser.d.ts

@@ -1,8 +1,10 @@
+import * as Crypto from './packlets/crypto-utils/index.browser';
 import * as Csv from './packlets/csv/index.browser';
 import * as Experimental from './packlets/experimental';
 import * as Hash from './packlets/hash/index.browser';
+import * as Mustache from './packlets/mustache';
 import * as RecordJar from './packlets/record-jar/index.browser';
 import * as ZipFileTree from './packlets/zip-file-tree';
 import { Converters } from './packlets/conversion';
-export { Converters, Csv, Experimental, Hash, RecordJar, ZipFileTree };
+export { Converters, Crypto, Csv, Experimental, Hash, Mustache, RecordJar, ZipFileTree };
 //# sourceMappingURL=index.browser.d.ts.map

package/lib/index.browser.js

@@ -54,9 +54,12 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZipFileTree = exports.RecordJar = exports.Hash = exports.Experimental = exports.Csv = exports.Converters = void 0;
+exports.ZipFileTree = exports.RecordJar = exports.Mustache = exports.Hash = exports.Experimental = exports.Csv = exports.Crypto = exports.Converters = void 0;
 /* c8 ignore start - Browser-specific export used conditionally in package.json */
 // eslint-disable-next-line @rushstack/packlets/mechanics
+const Crypto = __importStar(require("./packlets/crypto-utils/index.browser"));
+exports.Crypto = Crypto;
+// eslint-disable-next-line @rushstack/packlets/mechanics
 const Csv = __importStar(require("./packlets/csv/index.browser"));
 exports.Csv = Csv;
 const Experimental = __importStar(require("./packlets/experimental"));
@@ -64,6 +67,8 @@ exports.Experimental = Experimental;
 // eslint-disable-next-line @rushstack/packlets/mechanics
 const Hash = __importStar(require("./packlets/hash/index.browser"));
 exports.Hash = Hash;
+const Mustache = __importStar(require("./packlets/mustache"));
+exports.Mustache = Mustache;
 // eslint-disable-next-line @rushstack/packlets/mechanics
 const RecordJar = __importStar(require("./packlets/record-jar/index.browser"));
 exports.RecordJar = RecordJar;

package/lib/index.d.ts

@@ -1,8 +1,12 @@
+import * as AiAssist from './packlets/ai-assist';
+import * as CryptoUtils from './packlets/crypto-utils';
 import * as Csv from './packlets/csv';
 import * as Experimental from './packlets/experimental';
 import * as Hash from './packlets/hash';
+import * as Mustache from './packlets/mustache';
 import * as RecordJar from './packlets/record-jar';
+import * as Yaml from './packlets/yaml';
 import * as ZipFileTree from './packlets/zip-file-tree';
 import { Converters } from './packlets/conversion';
-export { Converters, Csv, Experimental, Hash, RecordJar, ZipFileTree };
+export { AiAssist, Converters, CryptoUtils, Csv, Experimental, Hash, Mustache, RecordJar, Yaml, ZipFileTree };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -54,15 +54,23 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZipFileTree = exports.RecordJar = exports.Hash = exports.Experimental = exports.Csv = exports.Converters = void 0;
+exports.ZipFileTree = exports.Yaml = exports.RecordJar = exports.Mustache = exports.Hash = exports.Experimental = exports.Csv = exports.CryptoUtils = exports.Converters = exports.AiAssist = void 0;
+const AiAssist = __importStar(require("./packlets/ai-assist"));
+exports.AiAssist = AiAssist;
+const CryptoUtils = __importStar(require("./packlets/crypto-utils"));
+exports.CryptoUtils = CryptoUtils;
 const Csv = __importStar(require("./packlets/csv"));
 exports.Csv = Csv;
 const Experimental = __importStar(require("./packlets/experimental"));
 exports.Experimental = Experimental;
 const Hash = __importStar(require("./packlets/hash"));
 exports.Hash = Hash;
+const Mustache = __importStar(require("./packlets/mustache"));
+exports.Mustache = Mustache;
 const RecordJar = __importStar(require("./packlets/record-jar"));
 exports.RecordJar = RecordJar;
+const Yaml = __importStar(require("./packlets/yaml"));
+exports.Yaml = Yaml;
 const ZipFileTree = __importStar(require("./packlets/zip-file-tree"));
 exports.ZipFileTree = ZipFileTree;
 const conversion_1 = require("./packlets/conversion");

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

@@ -0,0 +1,60 @@
+import { type Logging, Result } from '@fgv/ts-utils';
+import { AiPrompt, type AiServerToolConfig, type IAiCompletionResponse, type IAiProviderDescriptor, type IChatMessage, type ModelSpec } from './model';
+/**
+ * Parameters for a provider completion request.
+ * @public
+ */
+export interface IProviderCompletionParams {
+    /** 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 (e.g. for correction retries).
+     * These are appended in order after the initial system and user messages.
+     */
+    readonly additionalMessages?: ReadonlyArray<IChatMessage>;
+    /** Sampling temperature (default: 0.7) */
+    readonly temperature?: number;
+    /** Optional model override — string or context-aware map (uses descriptor.defaultModel otherwise) */
+    readonly modelOverride?: ModelSpec;
+    /** 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>;
+}
+/**
+ * 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
+ * @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 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`)
+ * @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>>;
+//# sourceMappingURL=apiClient.d.ts.map

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

@@ -0,0 +1,488 @@
+"use strict";
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+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 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
+});
+const openAiChoice = ts_utils_1.Validators.object({
+    message: openAiMessage,
+    finish_reason: ts_utils_1.Validators.string
+});
+const openAiResponse = ts_utils_1.Validators.object({
+    choices: ts_utils_1.Validators.arrayOf(openAiChoice).withConstraint((arr) => arr.length > 0)
+});
+const responsesApiOutputText = ts_utils_1.Validators.object({
+    type: ts_utils_1.Validators.literal('output_text'),
+    text: ts_utils_1.Validators.string
+});
+const responsesApiMessage = ts_utils_1.Validators.object({
+    type: ts_utils_1.Validators.literal('message'),
+    role: ts_utils_1.Validators.string,
+    content: ts_utils_1.Validators.arrayOf(responsesApiOutputText).withConstraint((arr) => arr.length > 0)
+});
+const responsesApiOutputItem = ts_utils_1.Validators.isA('object', (v) => typeof v === 'object' && v !== null);
+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
+});
+const geminiContent = ts_utils_1.Validators.object({
+    parts: ts_utils_1.Validators.arrayOf(geminiPart).withConstraint((arr) => arr.length > 0)
+});
+const geminiCandidate = ts_utils_1.Validators.object({
+    content: geminiContent,
+    finishReason: ts_utils_1.Validators.string
+});
+const geminiResponse = ts_utils_1.Validators.object({
+    candidates: ts_utils_1.Validators.arrayOf(geminiCandidate).withConstraint((arr) => arr.length > 0)
+});
+// ============================================================================
+// OpenAI-compatible client (Chat Completions — no tools)
+// ============================================================================
+/**
+ * Calls an OpenAI-compatible chat completion endpoint.
+ * Works for xAI Grok, OpenAI, Groq, and Mistral.
+ * @internal
+ */
+async function callOpenAiCompletion(config, prompt, additionalMessages, temperature = 0.7, logger) {
+    const url = `${config.baseUrl}/chat/completions`;
+    const messages = buildMessages(prompt, additionalMessages);
+    const body = { model: config.model, messages, temperature };
+    const headers = {
+        Authorization: `Bearer ${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);
+    if (jsonResult.isFailure()) {
+        return (0, ts_utils_1.fail)(jsonResult.message);
+    }
+    return openAiResponse
+        .validate(jsonResult.value)
+        .withErrorFormat((msg) => `OpenAI API response: ${msg}`)
+        .onSuccess((response) => {
+        const choice = response.choices[0];
+        return (0, ts_utils_1.succeed)({
+            content: choice.message.content,
+            truncated: choice.finish_reason === 'length'
+        });
+    });
+}
+// ============================================================================
+// OpenAI/xAI Responses API (with tools)
+// ============================================================================
+/**
+ * Extracts text content from a Responses API output array.
+ * Finds the first message-type output item and concatenates its text content blocks.
+ * @internal
+ */
+function extractResponsesApiText(output) {
+    for (const item of output) {
+        if (item.type === 'message') {
+            const messageResult = responsesApiMessage.validate(item);
+            if (messageResult.isSuccess()) {
+                return (0, ts_utils_1.succeed)(messageResult.value.content.map((c) => c.text).join(''));
+            }
+        }
+    }
+    return (0, ts_utils_1.fail)('Responses API output contained no message with text content');
+}
+/**
+ * Calls the xAI/OpenAI Responses API with server-side tools.
+ * Used when tools are configured for an openai-format provider.
+ * @internal
+ */
+async function callOpenAiResponsesCompletion(config, prompt, tools, additionalMessages, temperature = 0.7, logger) {
+    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}`
+    };
+    /* 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);
+    if (jsonResult.isFailure()) {
+        return (0, ts_utils_1.fail)(jsonResult.message);
+    }
+    return responsesApiResponse
+        .validate(jsonResult.value)
+        .withErrorFormat((msg) => `Responses API response: ${msg}`)
+        .onSuccess((response) => {
+        return extractResponsesApiText(response.output).onSuccess((text) => (0, ts_utils_1.succeed)({
+            content: text,
+            truncated: response.status === 'incomplete'
+        }));
+    });
+}
+// ============================================================================
+// Anthropic adapter
+// ============================================================================
+/**
+ * Extracts text content from Anthropic response content blocks.
+ * When tools are used, the content array contains mixed block types
+ * (text, server_tool_use, web_search_tool_result). We extract and
+ * concatenate only the text blocks.
+ * @internal
+ */
+function extractAnthropicText(content) {
+    const textParts = [];
+    for (const block of content) {
+        if (typeof block === 'object' && block !== null && 'type' in block) {
+            const typed = block;
+            if (typed.type === 'text' && typeof typed.text === 'string') {
+                textParts.push(typed.text);
+            }
+        }
+    }
+    if (textParts.length === 0) {
+        return (0, ts_utils_1.fail)('Anthropic response contained no text content blocks');
+    }
+    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) {
+    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 body = {
+        model: config.model,
+        system: prompt.system,
+        messages,
+        max_tokens: 4096,
+        temperature
+    };
+    if (tools && tools.length > 0) {
+        body.tools = (0, toolFormats_1.toAnthropicTools)(tools);
+        /* c8 ignore next 3 - optional logger diagnostic output */
+        logger === null || logger === void 0 ? void 0 : logger.info(`Anthropic completion: model=${config.model}, tools=${tools.map((t) => t.type).join(',')}`);
+    }
+    else {
+        /* 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);
+    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'
+        }));
+    }
+    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'
+        });
+    });
+}
+// ============================================================================
+// Google Gemini adapter
+// ============================================================================
+/**
+ * Calls the Google Gemini generateContent API.
+ * When tools are configured, includes Google Search grounding.
+ * @internal
+ */
+async function callGeminiCompletion(config, prompt, additionalMessages, temperature = 0.7, logger, tools) {
+    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 body = {
+        systemInstruction: { parts: [{ text: prompt.system }] },
+        contents,
+        generationConfig: { temperature }
+    };
+    if (tools && tools.length > 0) {
+        body.tools = (0, toolFormats_1.toGeminiTools)(tools);
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.info(`Gemini completion: model=${config.model}, tools=${tools.map((t) => t.type).join(',')}`);
+    }
+    else {
+        /* 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);
+    if (jsonResult.isFailure()) {
+        return (0, ts_utils_1.fail)(jsonResult.message);
+    }
+    return geminiResponse
+        .validate(jsonResult.value)
+        .withErrorFormat((msg) => `Gemini API response: ${msg}`)
+        .onSuccess((response) => {
+        const candidate = response.candidates[0];
+        return (0, ts_utils_1.succeed)({
+            content: candidate.content.parts[0].text,
+            truncated: candidate.finishReason === 'MAX_TOKENS'
+        });
+    });
+}
+// ============================================================================
+// 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
+ * @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 hasTools = tools !== undefined && tools.length > 0;
+    const modelContext = hasTools ? 'tools' : undefined;
+    const config = {
+        baseUrl: descriptor.baseUrl,
+        apiKey,
+        model: (0, model_1.resolveModel)(modelOverride !== null && modelOverride !== void 0 ? modelOverride : descriptor.defaultModel, modelContext)
+    };
+    /* c8 ignore next 8 - optional logger diagnostic output */
+    if (logger) {
+        const toolTypes = hasTools ? tools.map((t) => t.type).join(',') : 'none';
+        const supported = descriptor.supportedTools.length > 0 ? descriptor.supportedTools.join(',') : 'none';
+        logger.info(`AI completion: provider=${descriptor.id}, format=${descriptor.apiFormat}, model=${config.model}, ` +
+            `tools=${toolTypes}, supported=${supported}`);
+    }
+    switch (descriptor.apiFormat) {
+        case 'openai':
+            if (hasTools) {
+                return callOpenAiResponsesCompletion(config, prompt, tools, additionalMessages, temperature, logger);
+            }
+            return callOpenAiCompletion(config, prompt, additionalMessages, temperature, logger);
+        case 'anthropic':
+            return callAnthropicCompletion(config, prompt, additionalMessages, temperature, logger, tools);
+        case 'gemini':
+            return callGeminiCompletion(config, prompt, additionalMessages, temperature, logger, tools);
+        /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
+        default: {
+            const _exhaustive = descriptor.apiFormat;
+            return (0, ts_utils_1.fail)(`unsupported API format: ${String(_exhaustive)}`);
+        }
+    }
+}
+// ============================================================================
+// 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`)
+ * @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 body = {
+        providerId: descriptor.id,
+        apiKey,
+        prompt: { system: prompt.system, user: prompt.user },
+        temperature: temperature !== null && temperature !== void 0 ? temperature : 0.7
+    };
+    if (additionalMessages && additionalMessages.length > 0) {
+        body.additionalMessages = additionalMessages;
+    }
+    if (modelOverride !== undefined) {
+        body.modelOverride = modelOverride;
+    }
+    if (tools && tools.length > 0) {
+        body.tools = tools;
+    }
+    /* 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);
+    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}`);
+    }
+    if (typeof response.content !== 'string') {
+        return (0, ts_utils_1.fail)('proxy returned invalid response: missing content');
+    }
+    return (0, ts_utils_1.succeed)({
+        content: response.content,
+        truncated: response.truncated === true
+    });
+}
+//# sourceMappingURL=apiClient.js.map