@fgv/ts-extras 5.1.0-16 → 5.1.0-17

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

@@ -32,31 +32,17 @@
 import { isJsonObject } from '@fgv/ts-json-base';
 import { fail, succeed, Validators } from '@fgv/ts-utils';
 import { resolveModel } from './model';
+import { buildAnthropicMessages, buildGeminiContents, buildMessages, buildOpenAiChatUserContent, buildOpenAiResponsesUserContent } from './chatRequestBuilders';
+import { DEFAULT_MODEL_CAPABILITY_CONFIG } from './registry';
 import { toAnthropicTools, toGeminiTools, toResponsesApiTools } from './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) {
+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;
@@ -64,7 +50,8 @@ async function fetchJson(url, headers, body, logger) {
         response = await fetch(url, {
             method: 'POST',
             headers: Object.assign({ 'Content-Type': 'application/json' }, headers),
-            body: JSON.stringify(body)
+            body: JSON.stringify(body),
+            signal
         });
     }
     catch (err) {
@@ -97,6 +84,47 @@ async function fetchJson(url, headers, body, logger) {
     }
     return succeed(json);
 }
+/**
+ * Makes an HTTP GET request and returns the parsed JSON, or a failure.
+ * @internal
+ */
+async function fetchGetJson(url, headers, logger, signal) {
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.detail(`AI API request: GET ${url}`);
+    let response;
+    try {
+        response = await fetch(url, { method: 'GET', headers, 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);
+}
 const openAiMessage = Validators.object({
     content: Validators.string
 });
@@ -149,16 +177,18 @@ const geminiResponse = 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, additionalMessages, temperature = 0.7, logger, signal) {
     const url = `${config.baseUrl}/chat/completions`;
-    const messages = buildMessages(prompt, additionalMessages);
+    const messages = buildMessages(prompt.system, buildOpenAiChatUserContent(prompt), {
+        tail: 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);
+    const jsonResult = await fetchJson(url, headers, body, logger, signal);
     if (jsonResult.isFailure()) {
         return fail(jsonResult.message);
     }
@@ -197,9 +227,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) {
+async function callOpenAiResponsesCompletion(config, prompt, tools, additionalMessages, temperature = 0.7, logger, signal) {
     const url = `${config.baseUrl}/responses`;
-    const input = buildMessages(prompt, additionalMessages);
+    const input = buildMessages(prompt.system, buildOpenAiResponsesUserContent(prompt), {
+        tail: additionalMessages
+    });
     const body = {
         model: config.model,
         input,
@@ -211,7 +243,7 @@ async function callOpenAiResponsesCompletion(config, prompt, tools, additionalMe
     };
     /* 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 fetchJson(url, headers, body, logger, signal);
     if (jsonResult.isFailure()) {
         return fail(jsonResult.message);
     }
@@ -256,18 +288,10 @@ function extractAnthropicText(content) {
  * mixed content block responses.
  * @internal
  */
-async function callAnthropicCompletion(config, prompt, additionalMessages, temperature = 0.7, logger, tools) {
+async function callAnthropicCompletion(config, prompt, additionalMessages, temperature = 0.7, logger, tools, signal) {
     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 = buildAnthropicMessages(prompt, { tail: additionalMessages });
     const body = {
         model: config.model,
         system: prompt.system,
@@ -289,7 +313,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);
+    const jsonResult = await fetchJson(url, headers, body, logger, signal);
     if (jsonResult.isFailure()) {
         return fail(jsonResult.message);
     }
@@ -324,22 +348,10 @@ 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, additionalMessages, temperature = 0.7, logger, tools, signal) {
     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 = buildGeminiContents(prompt, { tail: additionalMessages });
     const body = {
         systemInstruction: { parts: [{ text: prompt.system }] },
         contents,
@@ -357,7 +369,7 @@ async function callGeminiCompletion(config, prompt, additionalMessages, temperat
     const headers = {
         'x-goog-api-key': config.apiKey
     };
-    const jsonResult = await fetchJson(url, headers, body, logger);
+    const jsonResult = await fetchJson(url, headers, body, logger, signal);
     if (jsonResult.isFailure()) {
         return fail(jsonResult.message);
     }
@@ -393,10 +405,13 @@ async function callGeminiCompletion(config, prompt, additionalMessages, temperat
  * @public
  */
 export async function callProviderCompletion(params) {
-    const { descriptor, apiKey, prompt, additionalMessages, temperature = 0.7, modelOverride, logger, tools } = params;
+    const { descriptor, apiKey, prompt, additionalMessages, temperature = 0.7, modelOverride, logger, tools, signal } = params;
     if (!descriptor.baseUrl) {
         return fail(`provider "${descriptor.id}" has no API endpoint configured`);
     }
+    if (prompt.attachments.length > 0 && !descriptor.acceptsImageInput) {
+        return fail(`provider "${descriptor.id}" does not accept image input`);
+    }
     const hasTools = tools !== undefined && tools.length > 0;
     const modelContext = hasTools ? 'tools' : undefined;
     const config = {
@@ -414,19 +429,465 @@ export async function callProviderCompletion(params) {
     switch (descriptor.apiFormat) {
         case 'openai':
             if (hasTools) {
-                return callOpenAiResponsesCompletion(config, prompt, tools, additionalMessages, temperature, logger);
+                return callOpenAiResponsesCompletion(config, prompt, tools, additionalMessages, temperature, logger, signal);
+            }
+            return callOpenAiCompletion(config, prompt, additionalMessages, temperature, logger, signal);
+        case 'anthropic':
+            return callAnthropicCompletion(config, prompt, additionalMessages, temperature, logger, tools, signal);
+        case 'gemini':
+            return callGeminiCompletion(config, prompt, additionalMessages, temperature, logger, tools, signal);
+        /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
+        default: {
+            const _exhaustive = descriptor.apiFormat;
+            return fail(`unsupported API format: ${String(_exhaustive)}`);
+        }
+    }
+}
+const openAiImageItem = Validators.object({
+    b64_json: Validators.string,
+    revised_prompt: Validators.string.optional()
+});
+const openAiImageResponse = Validators.object({
+    data: Validators.arrayOf(openAiImageItem).withConstraint((arr) => arr.length > 0)
+});
+const imagenPrediction = Validators.object({
+    bytesBase64Encoded: Validators.string,
+    mimeType: Validators.string.optional()
+});
+const imagenResponse = Validators.object({
+    predictions: Validators.arrayOf(imagenPrediction).withConstraint((arr) => arr.length > 0)
+});
+// ---- Proxied image generation response ----
+const proxiedGeneratedImage = Validators.object({
+    mimeType: Validators.string,
+    base64: Validators.string,
+    revisedPrompt: Validators.string.optional()
+});
+const proxiedImageGenerationResponse = Validators.object({
+    images: Validators.arrayOf(proxiedGeneratedImage).withConstraint((arr) => arr.length > 0)
+});
+const proxiedListModelsEntry = Validators.object({
+    id: Validators.string,
+    capabilities: Validators.arrayOf(Validators.enumeratedValue(['chat', 'tools', 'vision', 'image-generation'])),
+    displayName: Validators.string.optional()
+});
+const proxiedListModelsResponse = Validators.object({
+    models: Validators.arrayOf(proxiedListModelsEntry)
+});
+// ============================================================================
+// Image generation — adapters
+// ============================================================================
+/**
+ * Calls the OpenAI Images API. Used for both `openai-images` and `xai-images`
+ * formats — the request shape is the same; the only difference is whether the
+ * `size` field is honored (OpenAI: yes, xAI: ignored at the provider).
+ *
+ * @internal
+ */
+async function callOpenAiImageGeneration(config, request, defaultMimeType, logger, signal) {
+    var _a, _b;
+    const url = `${config.baseUrl}/images/generations`;
+    const opts = (_a = request.options) !== null && _a !== void 0 ? _a : {};
+    const body = {
+        model: config.model,
+        prompt: request.prompt,
+        n: (_b = opts.count) !== null && _b !== void 0 ? _b : 1,
+        response_format: 'b64_json'
+    };
+    if (opts.size !== undefined) {
+        body.size = opts.size;
+    }
+    if (opts.quality !== undefined) {
+        body.quality = opts.quality;
+    }
+    if (opts.seed !== undefined) {
+        body.seed = opts.seed;
+    }
+    const headers = {
+        Authorization: `Bearer ${config.apiKey}`
+    };
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`Image generation: model=${config.model}, n=${body.n}`);
+    const jsonResult = await fetchJson(url, headers, body, logger, signal);
+    if (jsonResult.isFailure()) {
+        return fail(jsonResult.message);
+    }
+    return openAiImageResponse
+        .validate(jsonResult.value)
+        .withErrorFormat((msg) => `OpenAI images API response: ${msg}`)
+        .onSuccess((response) => {
+        const images = response.data.map((item) => (Object.assign({ mimeType: defaultMimeType, base64: item.b64_json }, (item.revised_prompt !== undefined ? { revisedPrompt: item.revised_prompt } : {}))));
+        return succeed({ images });
+    });
+}
+/**
+ * Calls the Gemini Imagen `:predict` endpoint.
+ * @internal
+ */
+async function callImagenGeneration(config, request, logger, signal) {
+    var _a, _b, _c, _d;
+    const url = `${config.baseUrl}/models/${config.model}:predict`;
+    const opts = (_a = request.options) !== null && _a !== void 0 ? _a : {};
+    const parameters = {
+        sampleCount: (_b = opts.count) !== null && _b !== void 0 ? _b : 1
+    };
+    if (((_c = opts.imagen) === null || _c === void 0 ? void 0 : _c.aspectRatio) !== undefined) {
+        parameters.aspectRatio = opts.imagen.aspectRatio;
+    }
+    if (((_d = opts.imagen) === null || _d === void 0 ? void 0 : _d.negativePrompt) !== undefined) {
+        parameters.negativePrompt = opts.imagen.negativePrompt;
+    }
+    if (opts.seed !== undefined) {
+        parameters.seed = opts.seed;
+    }
+    const body = {
+        instances: [{ prompt: request.prompt }],
+        parameters
+    };
+    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);
+    if (jsonResult.isFailure()) {
+        return fail(jsonResult.message);
+    }
+    return imagenResponse
+        .validate(jsonResult.value)
+        .withErrorFormat((msg) => `Imagen API response: ${msg}`)
+        .onSuccess((response) => {
+        const images = response.predictions.map((p) => {
+            var _a;
+            return ({
+                mimeType: (_a = p.mimeType) !== null && _a !== void 0 ? _a : 'image/png',
+                base64: p.bytesBase64Encoded
+            });
+        });
+        return succeed({ images });
+    });
+}
+// ============================================================================
+// Image generation — dispatcher
+// ============================================================================
+/**
+ * Calls the appropriate image-generation API for a given provider.
+ *
+ * Routes based on `descriptor.imageApiFormat`:
+ * - `'openai-images'` for OpenAI (DALL-E, gpt-image-1)
+ * - `'xai-images'` for xAI Grok image models
+ * - `'gemini-imagen'` for Google Imagen
+ *
+ * Image-model selection reuses the existing `'image'` {@link ModelSpecKey}.
+ *
+ * @param params - Request parameters including descriptor, API key, and prompt
+ * @returns The generated images, or a failure
+ * @public
+ */
+export async function callProviderImageGeneration(params) {
+    const { descriptor, apiKey, params: request, modelOverride, logger, signal } = params;
+    if (descriptor.imageApiFormat === undefined) {
+        return fail(`provider "${descriptor.id}" does not support image generation`);
+    }
+    if (!descriptor.baseUrl) {
+        return fail(`provider "${descriptor.id}" has no API endpoint configured`);
+    }
+    const config = {
+        baseUrl: descriptor.baseUrl,
+        apiKey,
+        model: resolveModel(modelOverride !== null && modelOverride !== void 0 ? modelOverride : descriptor.defaultModel, 'image')
+    };
+    /* c8 ignore next 6 - optional logger diagnostic output */
+    if (logger) {
+        logger.info(`AI image generation: provider=${descriptor.id}, format=${descriptor.imageApiFormat}, ` +
+            `model=${config.model}`);
+    }
+    switch (descriptor.imageApiFormat) {
+        case 'openai-images':
+            return callOpenAiImageGeneration(config, request, 'image/png', logger, signal);
+        case 'xai-images':
+            return callOpenAiImageGeneration(config, request, 'image/jpeg', logger, signal);
+        case 'gemini-imagen':
+            return callImagenGeneration(config, request, logger, signal);
+        /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
+        default: {
+            const _exhaustive = descriptor.imageApiFormat;
+            return fail(`unsupported image API format: ${String(_exhaustive)}`);
+        }
+    }
+}
+const openAiListEntry = Validators.object({
+    id: Validators.string
+});
+const openAiListResponse = Validators.object({
+    data: Validators.arrayOf(openAiListEntry)
+});
+const anthropicListEntry = Validators.object({
+    id: Validators.string,
+    display_name: Validators.string.optional()
+});
+const anthropicListResponse = Validators.object({
+    data: Validators.arrayOf(anthropicListEntry)
+});
+const geminiListEntry = Validators.object({
+    name: Validators.string,
+    displayName: Validators.string.optional(),
+    supportedGenerationMethods: Validators.arrayOf(Validators.string).optional()
+});
+const geminiListResponse = Validators.object({
+    models: Validators.arrayOf(geminiListEntry)
+});
+// ============================================================================
+// List models — capability resolution
+// ============================================================================
+/**
+ * Translates Gemini's `supportedGenerationMethods` strings into our abstract
+ * capability vocabulary. Methods without a mapping are ignored.
+ * @internal
+ */
+function geminiMethodsToCapabilities(methods) {
+    const out = [];
+    for (const m of methods) {
+        if (m === 'generateContent') {
+            out.push('chat');
+        }
+        else if (m === 'predict') {
+            out.push('image-generation');
+        }
+    }
+    return out;
+}
+/**
+ * Strips the `models/` prefix Gemini includes on listed model names.
+ * @internal
+ */
+function geminiBareId(name) {
+    return name.startsWith('models/') ? name.substring('models/'.length) : name;
+}
+/**
+ * Applies a capability config to a model id. Walks per-provider rules then
+ * global rules; unions all matching rules' capabilities. Returns the union
+ * and the first matching `displayName` (if any).
+ * @internal
+ */
+function applyCapabilityConfig(config, providerId, modelId) {
+    var _a, _b, _c;
+    const caps = new Set();
+    let displayName;
+    const rulesets = [
+        (_b = (_a = config.perProvider) === null || _a === void 0 ? void 0 : _a[providerId]) !== null && _b !== void 0 ? _b : [],
+        (_c = config.global) !== null && _c !== void 0 ? _c : []
+    ];
+    for (const rules of rulesets) {
+        for (const rule of rules) {
+            rule.idPattern.lastIndex = 0;
+            if (rule.idPattern.test(modelId)) {
+                for (const cap of rule.capabilities) {
+                    caps.add(cap);
+                }
+                if (displayName === undefined && rule.displayName !== undefined) {
+                    displayName = typeof rule.displayName === 'function' ? rule.displayName(modelId) : rule.displayName;
+                }
             }
-            return callOpenAiCompletion(config, prompt, additionalMessages, temperature, logger);
+        }
+    }
+    return { capabilities: Array.from(caps), displayName };
+}
+/**
+ * Combines provider-native capability info (when supplied) and config-derived
+ * capability info into a final {@link IAiModelInfo}.
+ * @internal
+ */
+function buildModelInfo(providerId, id, nativeCapabilities, nativeDisplayName, config) {
+    const fromConfig = applyCapabilityConfig(config, providerId, id);
+    const all = new Set([...nativeCapabilities, ...fromConfig.capabilities]);
+    return Object.assign({ id, capabilities: all }, (nativeDisplayName !== undefined
+        ? { displayName: nativeDisplayName }
+        : fromConfig.displayName !== undefined
+            ? { displayName: fromConfig.displayName }
+            : {}));
+}
+// ============================================================================
+// List models — adapters
+// ============================================================================
+/**
+ * Calls the OpenAI-style `GET /models` endpoint. Used by openai, xai-grok,
+ * groq, and mistral. Provider supplies no capability info — capabilities are
+ * derived entirely from the config.
+ * @internal
+ */
+async function callOpenAiListModels(config, providerId, capabilityConfig, logger, signal) {
+    const url = `${config.baseUrl}/models`;
+    const headers = {
+        Authorization: `Bearer ${config.apiKey}`
+    };
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`List models: provider=${providerId}, format=openai`);
+    const jsonResult = await fetchGetJson(url, headers, logger, signal);
+    if (jsonResult.isFailure()) {
+        return fail(jsonResult.message);
+    }
+    return openAiListResponse
+        .validate(jsonResult.value)
+        .withErrorFormat((msg) => `OpenAI models API response: ${msg}`)
+        .onSuccess((response) => {
+        const models = response.data.map((entry) => buildModelInfo(providerId, entry.id, [], undefined, capabilityConfig));
+        return succeed(models);
+    });
+}
+/**
+ * Calls the Anthropic `GET /models` endpoint. Provider supplies a
+ * `display_name` but no native capability info.
+ * @internal
+ */
+async function callAnthropicListModels(config, providerId, capabilityConfig, logger, signal) {
+    const url = `${config.baseUrl}/models`;
+    const headers = {
+        'x-api-key': config.apiKey,
+        'anthropic-version': '2023-06-01',
+        'anthropic-dangerous-direct-browser-access': 'true'
+    };
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`List models: provider=${providerId}, format=anthropic`);
+    const jsonResult = await fetchGetJson(url, headers, logger, signal);
+    if (jsonResult.isFailure()) {
+        return fail(jsonResult.message);
+    }
+    return anthropicListResponse
+        .validate(jsonResult.value)
+        .withErrorFormat((msg) => `Anthropic models API response: ${msg}`)
+        .onSuccess((response) => {
+        const models = response.data.map((entry) => buildModelInfo(providerId, entry.id, [], entry.display_name, capabilityConfig));
+        return succeed(models);
+    });
+}
+/**
+ * Calls the Gemini `GET /models` endpoint. Provider supplies both a
+ * `displayName` and `supportedGenerationMethods` — translated to native
+ * capabilities and unioned with config-derived capabilities.
+ * @internal
+ */
+async function callGeminiListModels(config, providerId, capabilityConfig, logger, signal) {
+    const url = `${config.baseUrl}/models`;
+    const headers = {
+        'x-goog-api-key': config.apiKey
+    };
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`List models: provider=${providerId}, format=gemini`);
+    const jsonResult = await fetchGetJson(url, headers, logger, signal);
+    if (jsonResult.isFailure()) {
+        return fail(jsonResult.message);
+    }
+    return geminiListResponse
+        .validate(jsonResult.value)
+        .withErrorFormat((msg) => `Gemini models API response: ${msg}`)
+        .onSuccess((response) => {
+        const models = response.models.map((entry) => {
+            const id = geminiBareId(entry.name);
+            const native = entry.supportedGenerationMethods
+                ? geminiMethodsToCapabilities(entry.supportedGenerationMethods)
+                : [];
+            return buildModelInfo(providerId, id, native, entry.displayName, capabilityConfig);
+        });
+        return succeed(models);
+    });
+}
+// ============================================================================
+// List models — dispatcher
+// ============================================================================
+/**
+ * Lists models available from a provider, with capabilities resolved from
+ * native provider info (where supplied) and a configurable rule set.
+ *
+ * Routes based on `descriptor.apiFormat` — listing reuses the existing
+ * format dispatch and does not require a separate descriptor field.
+ *
+ * @param params - Request parameters including descriptor, API key, and optional capability filter
+ * @returns The resolved model list, or a failure
+ * @public
+ */
+export async function callProviderListModels(params) {
+    const { descriptor, apiKey, capability, capabilityConfig, logger, signal } = params;
+    if (!descriptor.baseUrl) {
+        return fail(`provider "${descriptor.id}" has no API endpoint configured`);
+    }
+    const config = {
+        baseUrl: descriptor.baseUrl,
+        apiKey,
+        model: '' // unused by listing
+    };
+    const effectiveConfig = capabilityConfig !== null && capabilityConfig !== void 0 ? capabilityConfig : DEFAULT_MODEL_CAPABILITY_CONFIG;
+    let listResult;
+    switch (descriptor.apiFormat) {
+        case 'openai':
+            listResult = await callOpenAiListModels(config, descriptor.id, effectiveConfig, logger, signal);
+            break;
         case 'anthropic':
-            return callAnthropicCompletion(config, prompt, additionalMessages, temperature, logger, tools);
+            listResult = await callAnthropicListModels(config, descriptor.id, effectiveConfig, logger, signal);
+            break;
         case 'gemini':
-            return callGeminiCompletion(config, prompt, additionalMessages, temperature, logger, tools);
+            listResult = await callGeminiListModels(config, descriptor.id, effectiveConfig, logger, signal);
+            break;
         /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
         default: {
             const _exhaustive = descriptor.apiFormat;
             return fail(`unsupported API format: ${String(_exhaustive)}`);
         }
     }
+    if (listResult.isFailure()) {
+        return listResult;
+    }
+    if (capability === undefined) {
+        return listResult;
+    }
+    return succeed(listResult.value.filter((m) => m.capabilities.has(capability)));
+}
+// ============================================================================
+// Proxied list models
+// ============================================================================
+/**
+ * Calls the model-listing endpoint on a proxy server.
+ *
+ * @remarks
+ * Proxy contract:
+ * - Endpoint: `POST ${proxyUrl}/api/ai/list-models`
+ * - Request body: `{providerId, apiKey, capability?}`. Capability config is
+ *   not forwarded — the proxy applies its own (typically the same default
+ *   the library ships).
+ * - Success response body: an `IAiModelInfo[]` (under key `models`) where
+ *   `capabilities` is serialized as a string array (not Set, which doesn't
+ *   round-trip through JSON).
+ * - Error response body: `{error: string}`, surfaced as `proxy: ${error}`.
+ *
+ * @public
+ */
+export async function callProxiedListModels(proxyUrl, params) {
+    const { descriptor, apiKey, capability, logger, signal } = params;
+    const body = {
+        providerId: descriptor.id,
+        apiKey
+    };
+    if (capability !== undefined) {
+        body.capability = capability;
+    }
+    /* 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);
+    if (jsonResult.isFailure()) {
+        return fail(jsonResult.message);
+    }
+    const response = jsonResult.value;
+    if (typeof response.error === 'string') {
+        return fail(`proxy: ${response.error}`);
+    }
+    return proxiedListModelsResponse
+        .validate(response)
+        .withErrorFormat((msg) => `proxy returned invalid response: ${msg}`)
+        .onSuccess((parsed) => {
+        const models = parsed.models.map((m) => (Object.assign({ id: m.id, capabilities: new Set(m.capabilities) }, (m.displayName !== undefined ? { displayName: m.displayName } : {}))));
+        return succeed(models);
+    });
 }
 // ============================================================================
 // Proxied completion (routes through a backend server)
@@ -445,11 +906,15 @@ export async function callProviderCompletion(params) {
  * @public
  */
 export async function callProxiedCompletion(proxyUrl, params) {
-    const { descriptor, apiKey, prompt, additionalMessages, temperature, modelOverride, logger, tools } = params;
+    const { descriptor, apiKey, prompt, additionalMessages, temperature, modelOverride, logger, tools, signal } = params;
+    const promptBody = { system: prompt.system, user: prompt.user };
+    if (prompt.attachments.length > 0) {
+        promptBody.attachments = prompt.attachments;
+    }
     const body = {
         providerId: descriptor.id,
         apiKey,
-        prompt: { system: prompt.system, user: prompt.user },
+        prompt: promptBody,
         temperature: temperature !== null && temperature !== void 0 ? temperature : 0.7
     };
     if (additionalMessages && additionalMessages.length > 0) {
@@ -464,7 +929,7 @@ export 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);
+    const jsonResult = await fetchJson(url, {}, body, logger, signal);
     if (jsonResult.isFailure()) {
         return fail(jsonResult.message);
     }
@@ -481,4 +946,51 @@ export async function callProxiedCompletion(proxyUrl, params) {
         truncated: response.truncated === true
     });
 }
+// ============================================================================
+// Proxied image generation
+// ============================================================================
+/**
+ * Calls the image-generation endpoint on a proxy server instead of calling
+ * the provider API directly from the browser.
+ *
+ * @remarks
+ * The proxy contract:
+ * - Endpoint: `POST ${proxyUrl}/api/ai/image-generation`
+ * - Request body: `{providerId, apiKey, params, modelOverride?}`
+ * - Success response body: an {@link IAiImageGenerationResponse}
+ * - Error response body: `{error: string}` (surfaced as `proxy: ${error}`)
+ *
+ * The proxy server is responsible for descriptor lookup, model resolution,
+ * provider dispatch, and response normalization.
+ *
+ * @param proxyUrl - Base URL of the proxy server (e.g. `http://localhost:3001`)
+ * @param params - Same parameters as {@link callProviderImageGeneration}
+ * @returns The generated images, or a failure
+ * @public
+ */
+export async function callProxiedImageGeneration(proxyUrl, params) {
+    const { descriptor, apiKey, params: request, modelOverride, logger, signal } = params;
+    const body = {
+        providerId: descriptor.id,
+        apiKey,
+        params: request
+    };
+    if (modelOverride !== undefined) {
+        body.modelOverride = modelOverride;
+    }
+    /* 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);
+    if (jsonResult.isFailure()) {
+        return fail(jsonResult.message);
+    }
+    const response = jsonResult.value;
+    if (typeof response.error === 'string') {
+        return fail(`proxy: ${response.error}`);
+    }
+    return proxiedImageGenerationResponse
+        .validate(response)
+        .withErrorFormat((msg) => `proxy returned invalid response: ${msg}`);
+}
 //# sourceMappingURL=apiClient.js.map