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

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

@@ -0,0 +1,89 @@
+/**
+ * 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 { AiPrompt, type IChatMessage } from './model';
+/**
+ * Optional head/tail messages to weave around the prompt's user message.
+ *
+ * @internal
+ */
+export interface IBuildMessagesOptions {
+    /**
+     * Messages inserted between the system prompt and the prompt's user
+     * message (e.g. prior conversation history for multi-turn chat).
+     */
+    readonly head?: ReadonlyArray<IChatMessage>;
+    /**
+     * Messages appended after the prompt's user message (e.g. assistant
+     * + correction turns for the JSON-validation retry loop).
+     */
+    readonly tail?: ReadonlyArray<IChatMessage>;
+}
+/**
+ * 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 declare function buildMessages(systemPrompt: string, userContent: string | unknown[], options?: IBuildMessagesOptions): Array<{
+    role: string;
+    content: string | unknown[];
+}>;
+/**
+ * Builds the user content for OpenAI Chat Completions when attachments are
+ * present. Returns a string when there are no attachments.
+ *
+ * @internal
+ */
+export declare function buildOpenAiChatUserContent(prompt: AiPrompt): string | unknown[];
+/**
+ * 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 declare function buildOpenAiResponsesUserContent(prompt: AiPrompt): string | unknown[];
+/**
+ * Builds the user-message content for Anthropic when attachments are present.
+ *
+ * @internal
+ */
+export declare function buildAnthropicUserContent(prompt: AiPrompt): string | unknown[];
+/**
+ * Builds the Gemini `parts` array for the user turn, including any image
+ * attachments as `inlineData` parts.
+ *
+ * @internal
+ */
+export declare function buildGeminiUserParts(prompt: AiPrompt): Array<Record<string, unknown>>;
+/**
+ * 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 declare function buildAnthropicMessages(prompt: AiPrompt, options?: IBuildMessagesOptions): Array<{
+    role: string;
+    content: string | unknown[];
+}>;
+/**
+ * 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 declare function buildGeminiContents(prompt: AiPrompt, options?: IBuildMessagesOptions): Array<{
+    role: string;
+    parts: Array<Record<string, unknown>>;
+}>;
+//# sourceMappingURL=chatRequestBuilders.d.ts.map

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

@@ -0,0 +1,189 @@
+"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.buildMessages = buildMessages;
+exports.buildOpenAiChatUserContent = buildOpenAiChatUserContent;
+exports.buildOpenAiResponsesUserContent = buildOpenAiResponsesUserContent;
+exports.buildAnthropicUserContent = buildAnthropicUserContent;
+exports.buildGeminiUserParts = buildGeminiUserParts;
+exports.buildAnthropicMessages = buildAnthropicMessages;
+exports.buildGeminiContents = buildGeminiContents;
+/**
+ * Per-format chat request shape builders. Shared between the synchronous
+ * (`apiClient.ts`) and streaming (`streamingClient.ts`) paths so the wire
+ * shapes stay consistent.
+ *
+ * @packageDocumentation
+ */
+const model_1 = require("./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
+ */
+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
+ */
+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: (0, model_1.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
+ */
+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: (0, model_1.toDataUrl)(att) }, (att.detail !== undefined ? { detail: att.detail } : {}))))
+    ];
+}
+/**
+ * Builds the user-message content for Anthropic when attachments are present.
+ *
+ * @internal
+ */
+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
+ */
+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
+ */
+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
+ */
+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/lib/packlets/ai-assist/index.d.ts

@@ -2,9 +2,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 { AiPrompt, type AiModelCapability, type AiProviderId, type AiServerToolType, type AiServerToolConfig, type IAiWebSearchToolConfig, type IAiToolEnablement, type IAiCompletionResponse, type IChatMessage, type AiApiFormat, type AiImageApiFormat, type IAiProviderDescriptor, type IAiAssistProviderConfig, type IAiAssistSettings, DEFAULT_AI_ASSIST, type IAiAssistKeyStore, type IAiImageAttachment, type IAiImageData, type IAiImageGenerationOptions, type IAiImageGenerationParams, type IAiGeneratedImage, type IAiImageGenerationResponse, type IAiModelCapabilityRule, type IAiModelCapabilityConfig, type IAiModelInfo, type IAiStreamEvent, type IAiStreamTextDelta, type IAiStreamToolEvent, type IAiStreamDone, type IAiStreamError, type ModelSpec, type ModelSpecKey, type IModelSpecMap, 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, type IProviderCompletionParams, type IProviderImageGenerationParams, type IProviderListModelsParams } from './apiClient';
+export { callProviderCompletionStream, callProxiedCompletionStream, type IProviderCompletionStreamParams } from './streamingClient';
 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

@@ -4,20 +4,29 @@
  * @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;
+exports.resolveEffectiveTools = exports.modelSpec = exports.modelSpecKey = exports.aiAssistSettings = exports.aiAssistProviderConfig = exports.aiToolEnablement = exports.aiServerToolConfig = exports.aiWebSearchToolConfig = exports.aiServerToolType = exports.aiProviderId = exports.callProxiedCompletionStream = exports.callProviderCompletionStream = exports.callProxiedListModels = exports.callProviderListModels = exports.callProxiedImageGeneration = exports.callProviderImageGeneration = exports.callProxiedCompletion = exports.callProviderCompletion = exports.DEFAULT_MODEL_CAPABILITY_CONFIG = exports.getProviderDescriptor = exports.getProviderDescriptors = exports.allProviderIds = exports.toDataUrl = 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; } });
+Object.defineProperty(exports, "toDataUrl", { enumerable: true, get: function () { return model_1.toDataUrl; } });
 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; } });
+Object.defineProperty(exports, "DEFAULT_MODEL_CAPABILITY_CONFIG", { enumerable: true, get: function () { return registry_1.DEFAULT_MODEL_CAPABILITY_CONFIG; } });
 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; } });
+Object.defineProperty(exports, "callProviderImageGeneration", { enumerable: true, get: function () { return apiClient_1.callProviderImageGeneration; } });
+Object.defineProperty(exports, "callProxiedImageGeneration", { enumerable: true, get: function () { return apiClient_1.callProxiedImageGeneration; } });
+Object.defineProperty(exports, "callProviderListModels", { enumerable: true, get: function () { return apiClient_1.callProviderListModels; } });
+Object.defineProperty(exports, "callProxiedListModels", { enumerable: true, get: function () { return apiClient_1.callProxiedListModels; } });
+var streamingClient_1 = require("./streamingClient");
+Object.defineProperty(exports, "callProviderCompletionStream", { enumerable: true, get: function () { return streamingClient_1.callProviderCompletionStream; } });
+Object.defineProperty(exports, "callProxiedCompletionStream", { enumerable: true, get: function () { return streamingClient_1.callProxiedCompletionStream; } });
 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; } });

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

@@ -3,6 +3,49 @@
  * @packageDocumentation
  */
 import { type Result } from '@fgv/ts-utils';
+/**
+ * Universal image representation used for both image input (vision prompts)
+ * and image output (generation responses).
+ *
+ * @remarks
+ * The base64 string is raw — no `data:` URL prefix. Use {@link AiAssist.toDataUrl} to
+ * format it for browser-display contexts.
+ *
+ * @public
+ */
+export interface IAiImageData {
+    /** MIME type, e.g. `'image/png'`, `'image/jpeg'`, `'image/webp'`. */
+    readonly mimeType: string;
+    /** Base64-encoded image bytes (no `data:` prefix). */
+    readonly base64: string;
+}
+/**
+ * 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 declare function toDataUrl(image: IAiImageData): string;
+/**
+ * Image attachment for a vision (image-input) prompt.
+ *
+ * @remarks
+ * Extends {@link IAiImageData} with an OpenAI-specific `detail` hint that is
+ * silently ignored by Anthropic, Gemini, and other providers.
+ *
+ * @public
+ */
+export interface IAiImageAttachment extends IAiImageData {
+    /**
+     * OpenAI vision detail hint:
+     * - `'low'`: faster, cheaper, lower fidelity
+     * - `'high'`: slower, more expensive, higher fidelity
+     * - `'auto'` (default): provider chooses
+     *
+     * Ignored by providers other than OpenAI.
+     */
+    readonly detail?: 'low' | 'high' | 'auto';
+}
 /**
  * A structured AI prompt with system/user split for direct API calls,
  * and a lazily-constructed combined version for copy/paste workflows.
@@ -13,8 +56,18 @@ export declare class AiPrompt {
     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. */
+    /**
+     * Optional image attachments. When present, vision-capable providers will
+     * include them in the user message; non-vision providers will reject the
+     * call up front (see {@link AiAssist.IAiProviderDescriptor.acceptsImageInput}).
+     */
+    readonly attachments: ReadonlyArray<IAiImageAttachment>;
+    constructor(user: string, system: string, attachments?: ReadonlyArray<IAiImageAttachment>);
+    /**
+     * 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(): string;
 }
 /**
@@ -139,6 +192,11 @@ export type AiProviderId = 'copy-paste' | 'xai-grok' | 'openai' | 'anthropic' |
  * @public
  */
 export type AiApiFormat = 'openai' | 'anthropic' | 'gemini';
+/**
+ * API format categories for image-generation provider routing.
+ * @public
+ */
+export type AiImageApiFormat = 'openai-images' | 'gemini-imagen' | 'xai-images';
 /**
  * Result of an AI provider completion call.
  * @public
@@ -149,6 +207,67 @@ export interface IAiCompletionResponse {
     /** Whether the response was truncated due to token limits */
     readonly truncated: boolean;
 }
+/**
+ * A text-content delta arriving during a streaming completion.
+ * @public
+ */
+export interface IAiStreamTextDelta {
+    readonly type: 'text-delta';
+    /** The newly arrived text fragment. */
+    readonly delta: string;
+}
+/**
+ * A server-side tool progress event arriving during a streaming completion.
+ * Surfaced for providers that emit explicit tool-progress markers (OpenAI
+ * Responses API, Anthropic). Gemini's grounding doesn't emit these.
+ * @public
+ */
+export interface IAiStreamToolEvent {
+    readonly type: 'tool-event';
+    /** Which server-side tool this event describes. */
+    readonly toolType: AiServerToolType;
+    /** Tool lifecycle phase. */
+    readonly phase: 'started' | 'completed';
+    /**
+     * Optional provider-specific detail. For web_search this is typically the
+     * search query when available; format varies by provider.
+     */
+    readonly detail?: string;
+}
+/**
+ * Terminal success event for a streaming completion. Carries the aggregated
+ * full text and truncation status for callers that want both the progressive
+ * UI and the complete result.
+ * @public
+ */
+export interface IAiStreamDone {
+    readonly type: 'done';
+    /** Whether the response was truncated due to token limits. */
+    readonly truncated: boolean;
+    /** The full concatenated text from all `text-delta` events. */
+    readonly fullText: string;
+}
+/**
+ * Terminal failure event for a streaming completion. After this event no
+ * further events are emitted.
+ *
+ * @remarks
+ * Connection-time failures (auth, network, pre-flight CORS rejection) are
+ * surfaced via the outer `Result.fail` returned by
+ * `callProviderCompletionStream` rather than as an `error` event, so callers
+ * can distinguish "didn't start" from "started but errored mid-stream."
+ *
+ * @public
+ */
+export interface IAiStreamError {
+    readonly type: 'error';
+    readonly message: string;
+}
+/**
+ * Discriminated union of events emitted by a streaming completion.
+ * @public
+ */
+export type IAiStreamEvent = IAiStreamTextDelta | IAiStreamToolEvent | IAiStreamDone | IAiStreamError;
 /**
  * Describes a single AI provider — single source of truth for all metadata.
  * @public
@@ -172,6 +291,156 @@ export interface IAiProviderDescriptor {
     readonly supportedTools: ReadonlyArray<AiServerToolType>;
     /** Whether this provider's API enforces CORS restrictions that prevent direct browser calls. */
     readonly corsRestricted: boolean;
+    /**
+     * Whether this provider's streaming completion endpoint requires a proxy
+     * for direct browser calls. Some providers gate streaming separately from
+     * non-streaming (rare), so this is tracked independently from
+     * {@link IAiProviderDescriptor.corsRestricted}.
+     *
+     * @remarks
+     * When `true`, `callProviderCompletionStream` rejects up front unless the
+     * call is being routed through a proxy.
+     */
+    readonly streamingCorsRestricted: boolean;
+    /**
+     * Whether this provider's chat completions API accepts image input
+     * (i.e. supports vision prompts). When false, calls with
+     * `prompt.attachments` are rejected up front.
+     */
+    readonly acceptsImageInput: boolean;
+    /**
+     * Which image-generation API format this provider uses, or undefined if it
+     * does not support image generation.
+     *
+     * @remarks
+     * Image-model selection reuses the existing `image` {@link ModelSpecKey}.
+     * Providers with `imageApiFormat` set should declare a model in
+     * `defaultModel.image`, e.g. `{ base: 'gpt-4o', image: 'dall-e-3' }`.
+     */
+    readonly imageApiFormat?: AiImageApiFormat;
+}
+/**
+ * Options for image generation requests.
+ *
+ * @remarks
+ * Provider compatibility is documented per field. The library does not
+ * pre-validate against per-model constraints (e.g. `dall-e-3` rejects
+ * `count > 1`); provider 400 errors surface through the failure path.
+ *
+ * @public
+ */
+export interface IAiImageGenerationOptions {
+    /**
+     * Image dimensions. Used by openai-format providers (mapped to the
+     * provider's `size` field). Ignored by Imagen — use
+     * {@link IAiImageGenerationOptions.imagen} `aspectRatio` instead.
+     *
+     * Note: each model has its own accepted set; `dall-e-3` only accepts the
+     * values listed here.
+     */
+    readonly size?: '1024x1024' | '1024x1792' | '1792x1024' | 'auto';
+    /**
+     * Number of images to generate. Default 1.
+     *
+     * Note: `dall-e-3` rejects `count > 1`.
+     */
+    readonly count?: number;
+    /** Generation quality hint where supported. */
+    readonly quality?: 'standard' | 'high';
+    /** Random seed for reproducibility, where supported. */
+    readonly seed?: number;
+    /**
+     * Imagen-specific options. Ignored by other providers.
+     */
+    readonly imagen?: {
+        readonly negativePrompt?: string;
+        readonly aspectRatio?: '1:1' | '3:4' | '4:3' | '9:16' | '16:9';
+    };
+}
+/**
+ * Parameters for an image-generation request.
+ * @public
+ */
+export interface IAiImageGenerationParams {
+    /** The text prompt describing the desired image. */
+    readonly prompt: string;
+    /** Optional generation options. */
+    readonly options?: IAiImageGenerationOptions;
+}
+/**
+ * A single generated image.
+ * @public
+ */
+export interface IAiGeneratedImage extends IAiImageData {
+    /**
+     * The prompt as rewritten by the provider, if any. OpenAI's image models
+     * commonly rewrite prompts; other providers do not.
+     */
+    readonly revisedPrompt?: string;
+}
+/**
+ * Capability vocabulary used to describe what a model can do. Used as both
+ * a filter and as a tag in {@link AiAssist.IAiModelInfo.capabilities}.
+ *
+ * @remarks
+ * Adding a new capability is cheap; adding the *first* one after consumers
+ * already exist forces churn. The initial vocabulary is intentionally broad
+ * even though only `image-generation` is fully exercised today.
+ *
+ * @public
+ */
+export type AiModelCapability = 'chat' | 'tools' | 'vision' | 'image-generation';
+/**
+ * Information about a single model returned by a provider's list endpoint,
+ * with capabilities already resolved (native + config rules).
+ * @public
+ */
+export interface IAiModelInfo {
+    /** Provider-native model identifier. */
+    readonly id: string;
+    /** Resolved capability set — union of native declarations and config rules. */
+    readonly capabilities: ReadonlySet<AiModelCapability>;
+    /** Friendly name for display, when known. */
+    readonly displayName?: string;
+}
+/**
+ * One rule in an {@link IAiModelCapabilityConfig}. Multiple rules can match
+ * a single model — their capability arrays are unioned.
+ * @public
+ */
+export interface IAiModelCapabilityRule {
+    /** RegExp tested against the model id (using `.test`). */
+    readonly idPattern: RegExp;
+    /** Capabilities this rule attributes to matching models. */
+    readonly capabilities: ReadonlyArray<AiModelCapability>;
+    /**
+     * Friendly display-name override for matching models. The function form
+     * lets one rule format many ids (e.g. `(id) => id.toUpperCase()`).
+     * If multiple matching rules supply `displayName`, the first match wins.
+     */
+    readonly displayName?: string | ((id: string) => string);
+}
+/**
+ * Configuration that maps model id patterns to capabilities. Used to
+ * augment (or, where the provider supplies no capability info, fully
+ * derive) the capability set for each listed model.
+ * @public
+ */
+export interface IAiModelCapabilityConfig {
+    /** Per-provider rules. Tried before {@link AiAssist.IAiModelCapabilityConfig.global}. */
+    readonly perProvider?: {
+        readonly [P in AiProviderId]?: ReadonlyArray<IAiModelCapabilityRule>;
+    };
+    /** Cross-provider fallback rules. */
+    readonly global?: ReadonlyArray<IAiModelCapabilityRule>;
+}
+/**
+ * Result of an image-generation call.
+ * @public
+ */
+export interface IAiImageGenerationResponse {
+    /** The generated images, in provider-returned order. */
+    readonly images: ReadonlyArray<IAiGeneratedImage>;
 }
 /**
  * Configuration for a single AI assist provider.

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

@@ -20,7 +20,17 @@
 // SOFTWARE.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_AI_ASSIST = exports.MODEL_SPEC_BASE_KEY = exports.allModelSpecKeys = exports.AiPrompt = void 0;
+exports.toDataUrl = toDataUrl;
 exports.resolveModel = resolveModel;
+/**
+ * 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
+ */
+function toDataUrl(image) {
+    return `data:${image.mimeType};base64,${image.base64}`;
+}
 // ============================================================================
 // AiPrompt
 // ============================================================================
@@ -30,13 +40,21 @@ exports.resolveModel = resolveModel;
  * @public
  */
 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}`;
     }
 }
 exports.AiPrompt = AiPrompt;