@fgv/ts-extras 5.0.2 → 5.1.0-0

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

@@ -0,0 +1,55 @@
+/**
+ * Converters for AI assist settings types.
+ * @packageDocumentation
+ */
+import { type Converter } from '@fgv/ts-utils';
+import { type AiProviderId, type AiServerToolConfig, type AiServerToolType, type IAiAssistProviderConfig, type IAiAssistSettings, type IAiToolEnablement, type IAiWebSearchToolConfig, type ModelSpec, type ModelSpecKey } from './model';
+/**
+ * Converter for {@link AiProviderId}.
+ * @public
+ */
+export declare const aiProviderId: Converter<AiProviderId>;
+/**
+ * Converter for {@link AiServerToolType}.
+ * @public
+ */
+export declare const aiServerToolType: Converter<AiServerToolType>;
+/**
+ * Converter for {@link IAiWebSearchToolConfig}.
+ * @public
+ */
+export declare const aiWebSearchToolConfig: Converter<IAiWebSearchToolConfig>;
+/**
+ * Converter for {@link AiServerToolConfig} (discriminated union on `type`).
+ * @public
+ */
+export declare const aiServerToolConfig: Converter<AiServerToolConfig>;
+/**
+ * Converter for {@link IAiToolEnablement}.
+ * @public
+ */
+export declare const aiToolEnablement: Converter<IAiToolEnablement>;
+/**
+ * Converter for {@link ModelSpecKey}.
+ * @public
+ */
+export declare const modelSpecKey: Converter<ModelSpecKey>;
+/**
+ * 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 declare const modelSpec: Converter<ModelSpec>;
+/**
+ * Converter for {@link IAiAssistProviderConfig}.
+ * @public
+ */
+export declare const aiAssistProviderConfig: Converter<IAiAssistProviderConfig>;
+/**
+ * Converter for {@link IAiAssistSettings}.
+ * @public
+ */
+export declare const aiAssistSettings: Converter<IAiAssistSettings>;
+//# sourceMappingURL=converters.d.ts.map

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

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

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

@@ -0,0 +1,10 @@
+/**
+ * AI assist packlet - provider registry, prompt class, settings, and API client.
+ * @packageDocumentation
+ */
+export { AiPrompt, type AiProviderId, type AiServerToolType, type AiServerToolConfig, type IAiWebSearchToolConfig, type IAiToolEnablement, type IAiCompletionResponse, type IChatMessage, type AiApiFormat, type IAiProviderDescriptor, type IAiAssistProviderConfig, type IAiAssistSettings, DEFAULT_AI_ASSIST, type IAiAssistKeyStore, type ModelSpec, type ModelSpecKey, type IModelSpecMap, allModelSpecKeys, MODEL_SPEC_BASE_KEY, resolveModel } from './model';
+export { allProviderIds, getProviderDescriptors, getProviderDescriptor } from './registry';
+export { callProviderCompletion, callProxiedCompletion, type IProviderCompletionParams } from './apiClient';
+export { aiProviderId, aiServerToolType, aiWebSearchToolConfig, aiServerToolConfig, aiToolEnablement, aiAssistProviderConfig, aiAssistSettings, modelSpecKey, modelSpec } from './converters';
+export { resolveEffectiveTools } from './toolFormats';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * AI assist packlet - provider registry, prompt class, settings, and API client.
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveEffectiveTools = exports.modelSpec = exports.modelSpecKey = exports.aiAssistSettings = exports.aiAssistProviderConfig = exports.aiToolEnablement = exports.aiServerToolConfig = exports.aiWebSearchToolConfig = exports.aiServerToolType = exports.aiProviderId = exports.callProxiedCompletion = exports.callProviderCompletion = exports.getProviderDescriptor = exports.getProviderDescriptors = exports.allProviderIds = exports.resolveModel = exports.MODEL_SPEC_BASE_KEY = exports.allModelSpecKeys = exports.DEFAULT_AI_ASSIST = exports.AiPrompt = void 0;
+var model_1 = require("./model");
+Object.defineProperty(exports, "AiPrompt", { enumerable: true, get: function () { return model_1.AiPrompt; } });
+Object.defineProperty(exports, "DEFAULT_AI_ASSIST", { enumerable: true, get: function () { return model_1.DEFAULT_AI_ASSIST; } });
+Object.defineProperty(exports, "allModelSpecKeys", { enumerable: true, get: function () { return model_1.allModelSpecKeys; } });
+Object.defineProperty(exports, "MODEL_SPEC_BASE_KEY", { enumerable: true, get: function () { return model_1.MODEL_SPEC_BASE_KEY; } });
+Object.defineProperty(exports, "resolveModel", { enumerable: true, get: function () { return model_1.resolveModel; } });
+var registry_1 = require("./registry");
+Object.defineProperty(exports, "allProviderIds", { enumerable: true, get: function () { return registry_1.allProviderIds; } });
+Object.defineProperty(exports, "getProviderDescriptors", { enumerable: true, get: function () { return registry_1.getProviderDescriptors; } });
+Object.defineProperty(exports, "getProviderDescriptor", { enumerable: true, get: function () { return registry_1.getProviderDescriptor; } });
+var apiClient_1 = require("./apiClient");
+Object.defineProperty(exports, "callProviderCompletion", { enumerable: true, get: function () { return apiClient_1.callProviderCompletion; } });
+Object.defineProperty(exports, "callProxiedCompletion", { enumerable: true, get: function () { return apiClient_1.callProxiedCompletion; } });
+var converters_1 = require("./converters");
+Object.defineProperty(exports, "aiProviderId", { enumerable: true, get: function () { return converters_1.aiProviderId; } });
+Object.defineProperty(exports, "aiServerToolType", { enumerable: true, get: function () { return converters_1.aiServerToolType; } });
+Object.defineProperty(exports, "aiWebSearchToolConfig", { enumerable: true, get: function () { return converters_1.aiWebSearchToolConfig; } });
+Object.defineProperty(exports, "aiServerToolConfig", { enumerable: true, get: function () { return converters_1.aiServerToolConfig; } });
+Object.defineProperty(exports, "aiToolEnablement", { enumerable: true, get: function () { return converters_1.aiToolEnablement; } });
+Object.defineProperty(exports, "aiAssistProviderConfig", { enumerable: true, get: function () { return converters_1.aiAssistProviderConfig; } });
+Object.defineProperty(exports, "aiAssistSettings", { enumerable: true, get: function () { return converters_1.aiAssistSettings; } });
+Object.defineProperty(exports, "modelSpecKey", { enumerable: true, get: function () { return converters_1.modelSpecKey; } });
+Object.defineProperty(exports, "modelSpec", { enumerable: true, get: function () { return converters_1.modelSpec; } });
+var toolFormats_1 = require("./toolFormats");
+Object.defineProperty(exports, "resolveEffectiveTools", { enumerable: true, get: function () { return toolFormats_1.resolveEffectiveTools; } });
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,222 @@
+/**
+ * Core types for AI assist: prompt class, provider descriptors, settings, and chat messages.
+ * @packageDocumentation
+ */
+import { type Result } from '@fgv/ts-utils';
+/**
+ * A structured AI prompt with system/user split for direct API calls,
+ * and a lazily-constructed combined version for copy/paste workflows.
+ * @public
+ */
+export declare class AiPrompt {
+    /** System instructions: schema documentation, format rules, general guidance. */
+    readonly system: string;
+    /** User request: the specific entity generation request. */
+    readonly user: string;
+    constructor(user: string, system: string);
+    /** Combined single-string version (user + system joined) for copy/paste. */
+    get combined(): string;
+}
+/**
+ * A single chat message in OpenAI format.
+ * @public
+ */
+export interface IChatMessage {
+    /** Message role */
+    readonly role: 'system' | 'user' | 'assistant';
+    /** Message content */
+    readonly content: string;
+}
+/**
+ * Built-in server-side tool types supported across providers.
+ * @public
+ */
+export type AiServerToolType = 'web_search';
+/**
+ * Configuration specific to web search tools.
+ * @public
+ */
+export interface IAiWebSearchToolConfig {
+    readonly type: 'web_search';
+    /** Optional: restrict search to these domains. */
+    readonly allowedDomains?: ReadonlyArray<string>;
+    /** Optional: exclude these domains from search. */
+    readonly blockedDomains?: ReadonlyArray<string>;
+    /** Optional: max number of searches per request. */
+    readonly maxUses?: number;
+    /**
+     * Optional: enable image understanding during web search.
+     * When true, the model can view and analyze images found during search.
+     * Currently supported by xAI only; ignored by other providers.
+     */
+    readonly enableImageUnderstanding?: boolean;
+}
+/**
+ * Union of all server-side tool configurations. Discriminated on `type`.
+ * @public
+ */
+export type AiServerToolConfig = IAiWebSearchToolConfig;
+/**
+ * Declares a tool as enabled/disabled in provider settings.
+ * Tools are disabled by default — consuming apps must opt in explicitly.
+ * @public
+ */
+export interface IAiToolEnablement {
+    /** Which tool type. */
+    readonly type: AiServerToolType;
+    /** Whether this tool is enabled by default for this provider. */
+    readonly enabled: boolean;
+    /** Optional tool-specific configuration. */
+    readonly config?: AiServerToolConfig;
+}
+/**
+ * Known context keys for model specification maps.
+ * @public
+ */
+export type ModelSpecKey = 'base' | 'tools' | 'image';
+/**
+ * All valid {@link ModelSpecKey} values.
+ * @public
+ */
+export declare const allModelSpecKeys: ReadonlyArray<ModelSpecKey>;
+/**
+ * Default context key used as fallback when resolving a {@link ModelSpec}.
+ * @public
+ */
+export declare const MODEL_SPEC_BASE_KEY: ModelSpecKey;
+/**
+ * A model specification: either a simple model string or a record mapping
+ * context keys to nested model specs.
+ *
+ * @remarks
+ * A bare string is equivalent to `{ base: string }`. This keeps the simple
+ * case simple while allowing context-aware model selection (e.g. different
+ * models for tool-augmented vs. base completions).
+ *
+ * @example
+ * ```typescript
+ * // Simple — same model for all contexts:
+ * const simple: ModelSpec = 'grok-4-1-fast';
+ *
+ * // Context-aware — reasoning model when tools are active:
+ * const split: ModelSpec = { base: 'grok-4-1-fast', tools: 'grok-4-1-fast-reasoning' };
+ *
+ * // Future nested — per-tool model selection:
+ * const nested: ModelSpec = { base: 'grok-fast', tools: { base: 'grok-r', image: 'grok-v' } };
+ * ```
+ * @public
+ */
+export interface IModelSpecMap {
+    readonly [key: string]: ModelSpec;
+}
+/**
+ * @public
+ */
+export type ModelSpec = string | IModelSpecMap;
+/**
+ * Resolves a {@link ModelSpec} to a concrete model string given an optional context key.
+ *
+ * @remarks
+ * Resolution rules:
+ * 1. If the spec is a string, return it directly (context is irrelevant).
+ * 2. If the spec is an object and the context key exists, recurse into that branch.
+ * 3. Otherwise, fall back to the {@link MODEL_SPEC_BASE_KEY | 'base'} key.
+ * 4. If neither context nor `'base'` exists, use the first available value.
+ *
+ * @param spec - The model specification to resolve
+ * @param context - Optional context key (e.g. `'tools'`)
+ * @returns The resolved model string
+ * @public
+ */
+export declare function resolveModel(spec: ModelSpec, context?: string): string;
+/**
+ * All known AI provider identifiers.
+ * @public
+ */
+export type AiProviderId = 'copy-paste' | 'xai-grok' | 'openai' | 'anthropic' | 'google-gemini' | 'groq' | 'mistral';
+/**
+ * API format categories for provider routing.
+ * @public
+ */
+export type AiApiFormat = 'openai' | 'anthropic' | 'gemini';
+/**
+ * Result of an AI provider completion call.
+ * @public
+ */
+export interface IAiCompletionResponse {
+    /** The generated text content */
+    readonly content: string;
+    /** Whether the response was truncated due to token limits */
+    readonly truncated: boolean;
+}
+/**
+ * Describes a single AI provider — single source of truth for all metadata.
+ * @public
+ */
+export interface IAiProviderDescriptor {
+    /** Provider identifier (e.g. 'xai-grok', 'anthropic') */
+    readonly id: AiProviderId;
+    /** Human-readable label (e.g. "xAI Grok") */
+    readonly label: string;
+    /** Button label for action buttons (e.g. "AI Assist | Grok") */
+    readonly buttonLabel: string;
+    /** Whether this provider requires an API key secret */
+    readonly needsSecret: boolean;
+    /** Which API adapter format to use */
+    readonly apiFormat: AiApiFormat;
+    /** Base URL for the API (e.g. 'https://api.x.ai/v1') */
+    readonly baseUrl: string;
+    /** Default model specification — string or context-aware map. */
+    readonly defaultModel: ModelSpec;
+    /** Which server-side tools this provider supports (empty = none). */
+    readonly supportedTools: ReadonlyArray<AiServerToolType>;
+    /** Whether this provider's API enforces CORS restrictions that prevent direct browser calls. */
+    readonly corsRestricted: boolean;
+}
+/**
+ * Configuration for a single AI assist provider.
+ * @public
+ */
+export interface IAiAssistProviderConfig {
+    /** Which provider this configures */
+    readonly provider: AiProviderId;
+    /** For API-based providers: the keystore secret name holding the API key */
+    readonly secretName?: string;
+    /** Optional model override — string or context-aware map. */
+    readonly model?: ModelSpec;
+    /** Tool enablement/configuration. Tools are disabled unless explicitly enabled. */
+    readonly tools?: ReadonlyArray<IAiToolEnablement>;
+}
+/**
+ * AI assist settings — which providers are enabled and their configuration.
+ * @public
+ */
+export interface IAiAssistSettings {
+    /** Enabled providers and their configuration. */
+    readonly providers: ReadonlyArray<IAiAssistProviderConfig>;
+    /** Which enabled provider is the default for the main button. Falls back to first in list. */
+    readonly defaultProvider?: AiProviderId;
+    /** Optional proxy URL for routing API requests through a backend server (e.g. `http://localhost:3002`). */
+    readonly proxyUrl?: string;
+    /** When true, route all providers through the proxy. When false (default), only CORS-restricted providers use the proxy. */
+    readonly proxyAllProviders?: boolean;
+}
+/**
+ * Default AI assist settings (copy-paste only).
+ * @public
+ */
+export declare const DEFAULT_AI_ASSIST: IAiAssistSettings;
+/**
+ * Minimal keystore interface for AI assist API key resolution.
+ * Satisfied structurally by the concrete `KeyStore` class from `@fgv/ts-extras`.
+ * @public
+ */
+export interface IAiAssistKeyStore {
+    /** Whether the keystore is currently unlocked */
+    readonly isUnlocked: boolean;
+    /** Check if a named secret exists */
+    hasSecret(name: string): Result<boolean>;
+    /** Get an API key by secret name */
+    getApiKey(name: string): Result<string>;
+}
+//# sourceMappingURL=model.d.ts.map

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

@@ -0,0 +1,95 @@
+"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.DEFAULT_AI_ASSIST = exports.MODEL_SPEC_BASE_KEY = exports.allModelSpecKeys = exports.AiPrompt = void 0;
+exports.resolveModel = resolveModel;
+// ============================================================================
+// AiPrompt
+// ============================================================================
+/**
+ * A structured AI prompt with system/user split for direct API calls,
+ * and a lazily-constructed combined version for copy/paste workflows.
+ * @public
+ */
+class AiPrompt {
+    constructor(user, system) {
+        this.system = system;
+        this.user = user;
+    }
+    /** Combined single-string version (user + system joined) for copy/paste. */
+    get combined() {
+        return `${this.user}\n\n${this.system}`;
+    }
+}
+exports.AiPrompt = AiPrompt;
+/**
+ * All valid {@link ModelSpecKey} values.
+ * @public
+ */
+exports.allModelSpecKeys = ['base', 'tools', 'image'];
+/**
+ * Default context key used as fallback when resolving a {@link ModelSpec}.
+ * @public
+ */
+exports.MODEL_SPEC_BASE_KEY = 'base';
+/**
+ * Resolves a {@link ModelSpec} to a concrete model string given an optional context key.
+ *
+ * @remarks
+ * Resolution rules:
+ * 1. If the spec is a string, return it directly (context is irrelevant).
+ * 2. If the spec is an object and the context key exists, recurse into that branch.
+ * 3. Otherwise, fall back to the {@link MODEL_SPEC_BASE_KEY | 'base'} key.
+ * 4. If neither context nor `'base'` exists, use the first available value.
+ *
+ * @param spec - The model specification to resolve
+ * @param context - Optional context key (e.g. `'tools'`)
+ * @returns The resolved model string
+ * @public
+ */
+function resolveModel(spec, context) {
+    if (typeof spec === 'string') {
+        return spec;
+    }
+    // Try the requested context key first
+    if (context !== undefined && context in spec) {
+        return resolveModel(spec[context]);
+    }
+    // Fall back to 'base'
+    if (exports.MODEL_SPEC_BASE_KEY in spec) {
+        return resolveModel(spec[exports.MODEL_SPEC_BASE_KEY]);
+    }
+    // Last resort: first value in the record
+    const first = Object.values(spec)[0];
+    /* c8 ignore next 3 - defensive: only reachable with empty object (prevented by converter) */
+    if (first === undefined) {
+        return '';
+    }
+    return resolveModel(first);
+}
+/**
+ * Default AI assist settings (copy-paste only).
+ * @public
+ */
+exports.DEFAULT_AI_ASSIST = {
+    providers: [{ provider: 'copy-paste' }]
+};
+//# sourceMappingURL=model.js.map

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

@@ -0,0 +1,25 @@
+/**
+ * Centralized provider registry — single source of truth for all AI provider metadata.
+ * @packageDocumentation
+ */
+import { Result } from '@fgv/ts-utils';
+import { type AiProviderId, type IAiProviderDescriptor } from './model';
+/**
+ * All valid provider ID values, in the same order as the registry.
+ * @public
+ */
+export declare const allProviderIds: ReadonlyArray<AiProviderId>;
+/**
+ * Get all known provider descriptors. Copy-paste first, then alphabetical.
+ * @returns All built-in provider descriptors
+ * @public
+ */
+export declare function getProviderDescriptors(): ReadonlyArray<IAiProviderDescriptor>;
+/**
+ * Get a provider descriptor by id.
+ * @param id - The provider identifier
+ * @returns The descriptor, or a failure if the provider is unknown
+ * @public
+ */
+export declare function getProviderDescriptor(id: string): Result<IAiProviderDescriptor>;
+//# sourceMappingURL=registry.d.ts.map