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

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

@@ -0,0 +1,180 @@
+// 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.
+/**
+ * Per-format chat request shape builders. Shared between the synchronous
+ * (`apiClient.ts`) and streaming (`streamingClient.ts`) paths so the wire
+ * shapes stay consistent.
+ *
+ * @packageDocumentation
+ */
+import { toDataUrl } from './model';
+/**
+ * Builds the messages array from prompt + optional head/tail messages.
+ * The caller supplies the user content (string for text-only, parts array
+ * for vision prompts) since the parts shape differs by format.
+ *
+ * @internal
+ */
+export function buildMessages(systemPrompt, userContent, options) {
+    const messages = [
+        { role: 'system', content: systemPrompt }
+    ];
+    if (options === null || options === void 0 ? void 0 : options.head) {
+        for (const msg of options.head) {
+            messages.push({ role: msg.role, content: msg.content });
+        }
+    }
+    messages.push({ role: 'user', content: userContent });
+    if (options === null || options === void 0 ? void 0 : options.tail) {
+        for (const msg of options.tail) {
+            messages.push({ role: msg.role, content: msg.content });
+        }
+    }
+    return messages;
+}
+/**
+ * Builds the user content for OpenAI Chat Completions when attachments are
+ * present. Returns a string when there are no attachments.
+ *
+ * @internal
+ */
+export function buildOpenAiChatUserContent(prompt) {
+    if (prompt.attachments.length === 0) {
+        return prompt.user;
+    }
+    return [
+        { type: 'text', text: prompt.user },
+        ...prompt.attachments.map((att) => ({
+            type: 'image_url',
+            image_url: Object.assign({ url: toDataUrl(att) }, (att.detail !== undefined ? { detail: att.detail } : {}))
+        }))
+    ];
+}
+/**
+ * Builds the user content for OpenAI / xAI Responses API when attachments
+ * are present. Responses API uses `input_text` / `input_image` part types,
+ * distinct from Chat Completions' `text` / `image_url`.
+ *
+ * @internal
+ */
+export function buildOpenAiResponsesUserContent(prompt) {
+    if (prompt.attachments.length === 0) {
+        return prompt.user;
+    }
+    return [
+        { type: 'input_text', text: prompt.user },
+        ...prompt.attachments.map((att) => (Object.assign({ type: 'input_image', image_url: toDataUrl(att) }, (att.detail !== undefined ? { detail: att.detail } : {}))))
+    ];
+}
+/**
+ * Builds the user-message content for Anthropic when attachments are present.
+ *
+ * @internal
+ */
+export function buildAnthropicUserContent(prompt) {
+    if (prompt.attachments.length === 0) {
+        return prompt.user;
+    }
+    return [
+        { type: 'text', text: prompt.user },
+        ...prompt.attachments.map((att) => ({
+            type: 'image',
+            source: {
+                type: 'base64',
+                media_type: att.mimeType,
+                data: att.base64
+            }
+        }))
+    ];
+}
+/**
+ * Builds the Gemini `parts` array for the user turn, including any image
+ * attachments as `inlineData` parts.
+ *
+ * @internal
+ */
+export function buildGeminiUserParts(prompt) {
+    const parts = [{ text: prompt.user }];
+    for (const att of prompt.attachments) {
+        parts.push({ inlineData: { mimeType: att.mimeType, data: att.base64 } });
+    }
+    return parts;
+}
+/**
+ * Builds the Anthropic messages array, weaving any `head` messages between
+ * implicit system + the prompt's user message and appending `tail` messages
+ * after. System messages are filtered out (Anthropic uses a top-level system
+ * field).
+ *
+ * @internal
+ */
+export function buildAnthropicMessages(prompt, options) {
+    const messages = [];
+    if (options === null || options === void 0 ? void 0 : options.head) {
+        for (const msg of options.head) {
+            if (msg.role !== 'system') {
+                messages.push({ role: msg.role, content: msg.content });
+            }
+        }
+    }
+    messages.push({ role: 'user', content: buildAnthropicUserContent(prompt) });
+    if (options === null || options === void 0 ? void 0 : options.tail) {
+        for (const msg of options.tail) {
+            if (msg.role !== 'system') {
+                messages.push({ role: msg.role, content: msg.content });
+            }
+        }
+    }
+    return messages;
+}
+/**
+ * Builds the Gemini `contents` array, weaving any `head` messages before the
+ * prompt's user parts and appending `tail` messages after. System messages
+ * are filtered out (Gemini uses a top-level systemInstruction field) and
+ * assistant roles are mapped to Gemini's `model` role.
+ *
+ * @internal
+ */
+export function buildGeminiContents(prompt, options) {
+    const contents = [];
+    if (options === null || options === void 0 ? void 0 : options.head) {
+        for (const msg of options.head) {
+            if (msg.role !== 'system') {
+                contents.push({
+                    role: msg.role === 'assistant' ? 'model' : msg.role,
+                    parts: [{ text: msg.content }]
+                });
+            }
+        }
+    }
+    contents.push({ role: 'user', parts: buildGeminiUserParts(prompt) });
+    if (options === null || options === void 0 ? void 0 : options.tail) {
+        for (const msg of options.tail) {
+            if (msg.role !== 'system') {
+                contents.push({
+                    role: msg.role === 'assistant' ? 'model' : msg.role,
+                    parts: [{ text: msg.content }]
+                });
+            }
+        }
+    }
+    return contents;
+}
+//# sourceMappingURL=chatRequestBuilders.js.map

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

@@ -2,9 +2,10 @@
  * AI assist packlet - provider registry, prompt class, settings, and API client.
  * @packageDocumentation
  */
-export { AiPrompt, DEFAULT_AI_ASSIST, allModelSpecKeys, MODEL_SPEC_BASE_KEY, resolveModel } from './model';
-export { allProviderIds, getProviderDescriptors, getProviderDescriptor } from './registry';
-export { callProviderCompletion, callProxiedCompletion } from './apiClient';
+export { AiPrompt, DEFAULT_AI_ASSIST, allModelSpecKeys, MODEL_SPEC_BASE_KEY, resolveModel, toDataUrl } from './model';
+export { allProviderIds, getProviderDescriptors, getProviderDescriptor, DEFAULT_MODEL_CAPABILITY_CONFIG } from './registry';
+export { callProviderCompletion, callProxiedCompletion, callProviderImageGeneration, callProxiedImageGeneration, callProviderListModels, callProxiedListModels } from './apiClient';
+export { callProviderCompletionStream, callProxiedCompletionStream } from './streamingClient';
 export { aiProviderId, aiServerToolType, aiWebSearchToolConfig, aiServerToolConfig, aiToolEnablement, aiAssistProviderConfig, aiAssistSettings, modelSpecKey, modelSpec } from './converters';
 export { resolveEffectiveTools } from './toolFormats';
 //# sourceMappingURL=index.js.map

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

@@ -17,6 +17,15 @@
 // 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.
+/**
+ * Formats an {@link IAiImageData} as a `data:` URL suitable for browser display.
+ * @param image - The image to format
+ * @returns A `data:<mime>;base64,<data>` URL string
+ * @public
+ */
+export function toDataUrl(image) {
+    return `data:${image.mimeType};base64,${image.base64}`;
+}
 // ============================================================================
 // AiPrompt
 // ============================================================================
@@ -26,13 +35,21 @@
  * @public
  */
 export class AiPrompt {
-    constructor(user, system) {
+    constructor(user, system, attachments) {
         this.system = system;
         this.user = user;
+        this.attachments = attachments !== null && attachments !== void 0 ? attachments : [];
     }
-    /** Combined single-string version (user + system joined) for copy/paste. */
+    /**
+     * Combined single-string version (user + system joined) for copy/paste.
+     * When attachments are present, includes a sentinel noting they aren't
+     * part of the copied text.
+     */
     get combined() {
-        return `${this.user}\n\n${this.system}`;
+        const sentinel = this.attachments.length > 0
+            ? `\n\n[${this.attachments.length} image attachment(s) — not included in copied text]`
+            : '';
+        return `${this.user}${sentinel}\n\n${this.system}`;
     }
 }
 /**

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

@@ -39,7 +39,9 @@ const BUILTIN_PROVIDERS = [
         baseUrl: '',
         defaultModel: '',
         supportedTools: [],
-        corsRestricted: false
+        corsRestricted: false,
+        streamingCorsRestricted: false,
+        acceptsImageInput: false
     },
     {
         id: 'anthropic',
@@ -50,7 +52,9 @@ const BUILTIN_PROVIDERS = [
         baseUrl: 'https://api.anthropic.com/v1',
         defaultModel: 'claude-sonnet-4-5-20250929',
         supportedTools: ['web_search'],
-        corsRestricted: false
+        corsRestricted: false,
+        streamingCorsRestricted: false,
+        acceptsImageInput: true
     },
     {
         id: 'google-gemini',
@@ -59,9 +63,12 @@ const BUILTIN_PROVIDERS = [
         needsSecret: true,
         apiFormat: 'gemini',
         baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
-        defaultModel: 'gemini-2.5-flash',
+        defaultModel: { base: 'gemini-2.5-flash', image: 'imagen-3.0-generate-002' },
         supportedTools: ['web_search'],
-        corsRestricted: false
+        corsRestricted: false,
+        streamingCorsRestricted: false,
+        acceptsImageInput: true,
+        imageApiFormat: 'gemini-imagen'
     },
     {
         id: 'groq',
@@ -72,7 +79,9 @@ const BUILTIN_PROVIDERS = [
         baseUrl: 'https://api.groq.com/openai/v1',
         defaultModel: 'llama-3.3-70b-versatile',
         supportedTools: [],
-        corsRestricted: false
+        corsRestricted: false,
+        streamingCorsRestricted: false,
+        acceptsImageInput: false
     },
     {
         id: 'mistral',
@@ -83,7 +92,9 @@ const BUILTIN_PROVIDERS = [
         baseUrl: 'https://api.mistral.ai/v1',
         defaultModel: 'mistral-large-latest',
         supportedTools: [],
-        corsRestricted: false
+        corsRestricted: false,
+        streamingCorsRestricted: false,
+        acceptsImageInput: false
     },
     {
         id: 'openai',
@@ -92,9 +103,12 @@ const BUILTIN_PROVIDERS = [
         needsSecret: true,
         apiFormat: 'openai',
         baseUrl: 'https://api.openai.com/v1',
-        defaultModel: 'gpt-4o',
+        defaultModel: { base: 'gpt-4o', image: 'dall-e-3' },
         supportedTools: ['web_search'],
-        corsRestricted: false
+        corsRestricted: false,
+        streamingCorsRestricted: false,
+        acceptsImageInput: true,
+        imageApiFormat: 'openai-images'
     },
     {
         id: 'xai-grok',
@@ -103,9 +117,16 @@ const BUILTIN_PROVIDERS = [
         needsSecret: true,
         apiFormat: 'openai',
         baseUrl: 'https://api.x.ai/v1',
-        defaultModel: { base: 'grok-4-1-fast', tools: 'grok-4-1-fast-reasoning' },
+        defaultModel: {
+            base: 'grok-4-1-fast',
+            tools: 'grok-4-1-fast-reasoning',
+            image: 'grok-2-image-1212'
+        },
         supportedTools: ['web_search'],
-        corsRestricted: true
+        corsRestricted: true,
+        streamingCorsRestricted: true,
+        acceptsImageInput: true,
+        imageApiFormat: 'xai-images'
     }
 ];
 /**
@@ -142,4 +163,39 @@ export function getProviderDescriptor(id) {
     }
     return succeed(descriptor);
 }
+// ============================================================================
+// Default model capability config
+// ============================================================================
+/**
+ * Default capability config used by `callProviderListModels` when callers
+ * don't supply their own. Patterns are intentionally narrow — false
+ * positives are worse than missing a model. Caller can override per call
+ * via {@link IProviderListModelsParams.capabilityConfig}.
+ *
+ * @public
+ */
+export const DEFAULT_MODEL_CAPABILITY_CONFIG = {
+    perProvider: {
+        openai: [
+            { idPattern: /^dall-e/, capabilities: ['image-generation'] },
+            { idPattern: /^gpt-image/, capabilities: ['image-generation'] },
+            { idPattern: /^gpt-4/, capabilities: ['chat', 'tools', 'vision'] },
+            { idPattern: /^gpt-3\.5/, capabilities: ['chat'] },
+            { idPattern: /^o\d/, capabilities: ['chat', 'tools'] }
+        ],
+        'xai-grok': [
+            { idPattern: /-image/, capabilities: ['image-generation'] },
+            { idPattern: /^grok-4/, capabilities: ['chat', 'tools', 'vision'] },
+            { idPattern: /^grok-3/, capabilities: ['chat', 'tools'] },
+            { idPattern: /^grok-2/, capabilities: ['chat', 'vision'] }
+        ],
+        'google-gemini': [
+            { idPattern: /^imagen/, capabilities: ['image-generation'] },
+            { idPattern: /^gemini-/, capabilities: ['chat', 'tools', 'vision'] }
+        ],
+        anthropic: [{ idPattern: /^claude-/, capabilities: ['chat', 'tools', 'vision'] }],
+        groq: [{ idPattern: /./, capabilities: ['chat'] }],
+        mistral: [{ idPattern: /./, capabilities: ['chat'] }]
+    }
+};
 //# sourceMappingURL=registry.js.map

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

@@ -0,0 +1,122 @@
+// 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.
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+/**
+ * Parses a single SSE message (the text between blank-line separators) into
+ * an {@link ISseEvent}. Returns undefined for messages with no `data:` lines
+ * (comments, heartbeats).
+ *
+ * @internal
+ */
+export function parseSseEvent(chunk) {
+    let event;
+    const dataLines = [];
+    for (const line of chunk.split('\n')) {
+        if (line.startsWith('event:')) {
+            event = line.slice(6).trim();
+        }
+        else if (line.startsWith('data:')) {
+            // Per the SSE spec the value starts after the colon, with one optional leading space stripped.
+            const value = line.slice(5);
+            dataLines.push(value.startsWith(' ') ? value.slice(1) : value);
+        }
+    }
+    if (dataLines.length === 0) {
+        return undefined;
+    }
+    return event !== undefined ? { event, data: dataLines.join('\n') } : { data: dataLines.join('\n') };
+}
+/**
+ * Reads an SSE response body and yields parsed events. Buffers across read()
+ * boundaries so a message split mid-chunk still parses cleanly. Terminates
+ * when the stream closes (normal EOF or aborted fetch).
+ *
+ * @internal
+ */
+export function readSseEvents(body) {
+    return __asyncGenerator(this, arguments, function* readSseEvents_1() {
+        var _a;
+        const reader = body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            let streaming = true;
+            while (streaming) {
+                const { value, done } = yield __await(reader.read());
+                if (done) {
+                    streaming = false;
+                    if (buffer.length > 0) {
+                        const tail = parseSseEvent(buffer.replace(/\r\n/g, '\n'));
+                        if (tail) {
+                            yield yield __await(tail);
+                        }
+                    }
+                    break;
+                }
+                buffer += decoder.decode(value, { stream: true });
+                // SSE messages are separated by a blank line; some servers use \r\n.
+                const normalized = buffer.replace(/\r\n/g, '\n');
+                const parts = normalized.split('\n\n');
+                // Last element is the partial chunk (no terminating blank line yet); buffer it.
+                buffer = (_a = parts.pop()) !== null && _a !== void 0 ? _a : '';
+                for (const chunk of parts) {
+                    const event = parseSseEvent(chunk);
+                    if (event) {
+                        yield yield __await(event);
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    });
+}
+/**
+ * Parses the `data` payload of an SSE event as JSON. Returns undefined for
+ * the OpenAI `[DONE]` sentinel and for any payload that fails to parse —
+ * adapters treat both as "skip this event."
+ *
+ * @internal
+ */
+export function parseSseEventJson(data) {
+    if (data === '[DONE]') {
+        return undefined;
+    }
+    try {
+        return JSON.parse(data);
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+//# sourceMappingURL=sseParser.js.map