@fgv/ts-extras 5.0.2-0 → 5.1.0-0

package/CHANGELOG.json

@@ -1,6 +1,21 @@
 {
   "name": "@fgv/ts-extras",
   "entries": [
+    {
+      "version": "5.0.2",
+      "tag": "@fgv/ts-extras_v5.0.2",
+      "date": "Wed, 17 Dec 2025 18:08:09 GMT",
+      "comments": {
+        "none": [
+          {
+            "comment": "dual-publish"
+          },
+          {
+            "comment": "minor cleanup"
+          }
+        ]
+      }
+    },
     {
       "version": "5.0.1",
       "tag": "@fgv/ts-extras_v5.0.1",

package/dist/index.browser.js

@@ -21,15 +21,19 @@
  */
 /* c8 ignore start - Browser-specific export used conditionally in package.json */
 // eslint-disable-next-line @rushstack/packlets/mechanics
+import * as Crypto from './packlets/crypto-utils/index.browser';
+// eslint-disable-next-line @rushstack/packlets/mechanics
 import * as Csv from './packlets/csv/index.browser';
 import * as Experimental from './packlets/experimental';
 // eslint-disable-next-line @rushstack/packlets/mechanics
 import * as Hash from './packlets/hash/index.browser';
+import * as Mustache from './packlets/mustache';
 // eslint-disable-next-line @rushstack/packlets/mechanics
 import * as RecordJar from './packlets/record-jar/index.browser';
 import * as ZipFileTree from './packlets/zip-file-tree';
 import { Converters } from './packlets/conversion';
-// Browser-safe exports - Node.js crypto-based hash excluded (using CRC32 instead)
-export { Converters, Csv, Experimental, Hash, RecordJar, ZipFileTree };
+// Browser-safe exports - Node.js crypto-based providers excluded
+// Use BrowserCryptoProvider from @fgv/ts-web-extras for browser crypto
+export { Converters, Crypto, Csv, Experimental, Hash, Mustache, RecordJar, ZipFileTree };
 /* c8 ignore stop */
 //# sourceMappingURL=index.browser.js.map

package/dist/index.js

@@ -19,11 +19,15 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
+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.js.map

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

@@ -0,0 +1,484 @@
+// 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.
+/**
+ * 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
+ */
+import { isJsonObject } from '@fgv/ts-json-base';
+import { fail, succeed, Validators } from '@fgv/ts-utils';
+import { resolveModel } from './model';
+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) {
+    /* 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 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
+});
+const openAiChoice = Validators.object({
+    message: openAiMessage,
+    finish_reason: Validators.string
+});
+const openAiResponse = Validators.object({
+    choices: Validators.arrayOf(openAiChoice).withConstraint((arr) => arr.length > 0)
+});
+const responsesApiOutputText = Validators.object({
+    type: Validators.literal('output_text'),
+    text: Validators.string
+});
+const responsesApiMessage = Validators.object({
+    type: Validators.literal('message'),
+    role: Validators.string,
+    content: Validators.arrayOf(responsesApiOutputText).withConstraint((arr) => arr.length > 0)
+});
+const responsesApiOutputItem = Validators.isA('object', (v) => typeof v === 'object' && v !== null);
+const responsesApiResponse = Validators.object({
+    output: Validators.arrayOf(responsesApiOutputItem).withConstraint((arr) => arr.length > 0),
+    status: Validators.string
+});
+const anthropicContentBlock = Validators.object({
+    text: Validators.string
+});
+const anthropicResponse = Validators.object({
+    content: Validators.arrayOf(anthropicContentBlock).withConstraint((arr) => arr.length > 0),
+    stop_reason: Validators.string
+});
+const geminiPart = Validators.object({
+    text: Validators.string
+});
+const geminiContent = Validators.object({
+    parts: Validators.arrayOf(geminiPart).withConstraint((arr) => arr.length > 0)
+});
+const geminiCandidate = Validators.object({
+    content: geminiContent,
+    finishReason: Validators.string
+});
+const geminiResponse = Validators.object({
+    candidates: 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 fail(jsonResult.message);
+    }
+    return openAiResponse
+        .validate(jsonResult.value)
+        .withErrorFormat((msg) => `OpenAI API response: ${msg}`)
+        .onSuccess((response) => {
+        const choice = response.choices[0];
+        return 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 succeed(messageResult.value.content.map((c) => c.text).join(''));
+            }
+        }
+    }
+    return 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: 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 fail(jsonResult.message);
+    }
+    return responsesApiResponse
+        .validate(jsonResult.value)
+        .withErrorFormat((msg) => `Responses API response: ${msg}`)
+        .onSuccess((response) => {
+        return extractResponsesApiText(response.output).onSuccess((text) => 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 fail('Anthropic response contained no text content blocks');
+    }
+    return 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 = 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 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 fail('Anthropic API response: content is not an array');
+        }
+        return extractAnthropicText(rawContent).onSuccess((text) => succeed({
+            content: text,
+            truncated: stopReason === 'max_tokens'
+        }));
+    }
+    return anthropicResponse
+        .validate(jsonResult.value)
+        .withErrorFormat((msg) => `Anthropic API response: ${msg}`)
+        .onSuccess((response) => {
+        return 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 = 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 fail(jsonResult.message);
+    }
+    return geminiResponse
+        .validate(jsonResult.value)
+        .withErrorFormat((msg) => `Gemini API response: ${msg}`)
+        .onSuccess((response) => {
+        const candidate = response.candidates[0];
+        return 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
+ */
+export async function callProviderCompletion(params) {
+    const { descriptor, apiKey, prompt, additionalMessages, temperature = 0.7, modelOverride, logger, tools } = params;
+    if (!descriptor.baseUrl) {
+        return 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: 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 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
+ */
+export 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 fail(jsonResult.message);
+    }
+    // Check for error response from proxy
+    const response = jsonResult.value;
+    if (typeof response.error === 'string') {
+        return fail(`proxy: ${response.error}`);
+    }
+    if (typeof response.content !== 'string') {
+        return fail('proxy returned invalid response: missing content');
+    }
+    return succeed({
+        content: response.content,
+        truncated: response.truncated === true
+    });
+}
+//# sourceMappingURL=apiClient.js.map

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

@@ -0,0 +1,121 @@
+// 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.
+/**
+ * Converters for AI assist settings types.
+ * @packageDocumentation
+ */
+import { Converters } from '@fgv/ts-utils';
+import { allModelSpecKeys } from './model';
+import { allProviderIds } from './registry';
+// ============================================================================
+// Provider ID
+// ============================================================================
+/**
+ * Converter for {@link AiProviderId}.
+ * @public
+ */
+export const aiProviderId = Converters.enumeratedValue(allProviderIds);
+// ============================================================================
+// Server-Side Tool Converters
+// ============================================================================
+/**
+ * All known server-side tool type values.
+ * @internal
+ */
+const allServerToolTypes = ['web_search'];
+/**
+ * Converter for {@link AiServerToolType}.
+ * @public
+ */
+export const aiServerToolType = Converters.enumeratedValue(allServerToolTypes);
+/**
+ * Converter for {@link IAiWebSearchToolConfig}.
+ * @public
+ */
+export const aiWebSearchToolConfig = Converters.strictObject({
+    type: Converters.enumeratedValue(['web_search']),
+    allowedDomains: Converters.arrayOf(Converters.string).optional(),
+    blockedDomains: Converters.arrayOf(Converters.string).optional(),
+    maxUses: Converters.number.optional(),
+    enableImageUnderstanding: Converters.boolean.optional()
+});
+/**
+ * Converter for {@link AiServerToolConfig} (discriminated union on `type`).
+ * @public
+ */
+export const aiServerToolConfig = Converters.discriminatedObject('type', {
+    web_search: aiWebSearchToolConfig
+});
+/**
+ * Converter for {@link IAiToolEnablement}.
+ * @public
+ */
+export const aiToolEnablement = Converters.strictObject({
+    type: aiServerToolType,
+    enabled: Converters.boolean,
+    config: aiServerToolConfig.optional()
+});
+// ============================================================================
+// Model Specification
+// ============================================================================
+/**
+ * Converter for {@link ModelSpecKey}.
+ * @public
+ */
+export const modelSpecKey = Converters.enumeratedValue(allModelSpecKeys);
+/**
+ * Recursive converter for {@link ModelSpec}.
+ * Accepts a string or an object whose values are themselves ModelSpec values,
+ * with keys constrained to known {@link ModelSpecKey} values.
+ * Uses the `self` parameter from `Converters.generic` for recursion.
+ * @public
+ */
+export const modelSpec = Converters.generic((from, self) => {
+    return Converters.oneOf([
+        Converters.string,
+        Converters.recordOf(self, { keyConverter: modelSpecKey })
+    ])
+        .withFormattedError(() => 'expected model spec (string or object with keys: base, tools, image)')
+        .convert(from);
+});
+// ============================================================================
+// Provider Config & Settings
+// ============================================================================
+/**
+ * Converter for {@link IAiAssistProviderConfig}.
+ * @public
+ */
+export const aiAssistProviderConfig = Converters.strictObject({
+    provider: aiProviderId,
+    secretName: Converters.string.optional(),
+    model: modelSpec.optional(),
+    tools: Converters.arrayOf(aiToolEnablement).optional()
+});
+/**
+ * Converter for {@link IAiAssistSettings}.
+ * @public
+ */
+export const aiAssistSettings = Converters.strictObject({
+    providers: Converters.arrayOf(aiAssistProviderConfig),
+    defaultProvider: aiProviderId.optional(),
+    proxyUrl: Converters.string.optional(),
+    proxyAllProviders: Converters.boolean.optional()
+});
+//# sourceMappingURL=converters.js.map

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

@@ -0,0 +1,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 { aiProviderId, aiServerToolType, aiWebSearchToolConfig, aiServerToolConfig, aiToolEnablement, aiAssistProviderConfig, aiAssistSettings, modelSpecKey, modelSpec } from './converters';
+export { resolveEffectiveTools } from './toolFormats';
+//# sourceMappingURL=index.js.map