@fgv/ts-extras 5.1.0-26 → 5.1.0-27

package/dist/ts-extras.d.ts

@@ -3,6 +3,7 @@ import { Converter } from '@fgv/ts-utils';
 import { DateTime } from 'luxon';
 import { FileTree } from '@fgv/ts-json-base';
 import { Hash as Hash_2 } from '@fgv/ts-utils';
+import { JsonObject } from '@fgv/ts-json-base';
 import { JsonValue } from '@fgv/ts-json-base';
 import { Logging } from '@fgv/ts-utils';
 import { Result } from '@fgv/ts-utils';
@@ -42,6 +43,30 @@ declare namespace AiAssist {
         IAiAssistKeyStore,
         IAiImageAttachment,
         IAiImageData,
+        AiImageSize,
+        AiImageQuality,
+        DallE2Size,
+        DallE3Size,
+        GptImageSize,
+        DallE3Quality,
+        GptImageQuality,
+        DallEModelNames,
+        GptImageModelNames,
+        GrokImagineModelNames,
+        Imagen4ModelNames,
+        GeminiFlashImageModelNames,
+        IDallEImageGenerationConfig,
+        IGptImageGenerationConfig,
+        IGrokImagineImageGenerationConfig,
+        IImagen4GenerationConfig,
+        IGeminiFlashImageGenerationConfig,
+        IDallEModelOptions,
+        IGptImageModelOptions,
+        IGrokImagineModelOptions,
+        IImagen4ModelOptions,
+        IGeminiFlashImageModelOptions,
+        IOtherModelOptions,
+        IModelFamilyConfig,
         IAiImageGenerationOptions,
         IAiImageGenerationParams,
         IAiGeneratedImage,
@@ -61,6 +86,25 @@ declare namespace AiAssist {
         MODEL_SPEC_BASE_KEY,
         resolveModel,
         toDataUrl,
+        AiThinkingMode,
+        IThinkingConfig,
+        IThinkingProviderConfig,
+        IAnthropicThinkingOptions,
+        IOpenAiThinkingOptions,
+        IGeminiThinkingOptions,
+        IXAiThinkingOptions,
+        IOtherThinkingOptions,
+        IAnthropicThinkingConfig,
+        IOpenAiThinkingConfig,
+        IGeminiThinkingConfig,
+        IXAiThinkingConfig,
+        AnthropicThinkingModelNames,
+        OpenAiThinkingModelNames,
+        GeminiThinkingModelNames,
+        XAiThinkingModelNames,
+        IResolvedImageOptions,
+        resolveImageOptions,
+        validateResolvedOptions,
         allProviderIds,
         getProviderDescriptors,
         getProviderDescriptor,
@@ -121,8 +165,9 @@ declare const aiAssistSettings: Converter<IAiAssistSettings>;
  * @remarks
  * - `'openai-images'` — OpenAI Images API. Routes to `/images/generations`
  *   (text-only) or `/images/edits` (when reference images are present).
- * - `'xai-images'` — xAI Images API. Same wire shape as OpenAI but text-only;
- *   no reference-image support on grok-2-image.
+ * - `'xai-images'` — xAI Images API. Text-only JSON generation request.
+ * - `'xai-images-edits'` — xAI Images API for Grok Imagine models. Uses JSON
+ *   body with `{ type: "image_url" }` objects (not multipart).
  * - `'gemini-imagen'` — Google Imagen `:predict` endpoint. Text-only.
  * - `'gemini-image-out'` — Google Gemini chat-style `:generateContent`
  *   endpoint that returns image parts (Gemini 2.5 Flash Image / "Nano
@@ -130,7 +175,13 @@ declare const aiAssistSettings: Converter<IAiAssistSettings>;
  *
  * @public
  */
-declare type AiImageApiFormat = 'openai-images' | 'gemini-imagen' | 'xai-images' | 'gemini-image-out';
+declare type AiImageApiFormat = 'openai-images' | 'gemini-imagen' | 'xai-images' | 'xai-images-edits' | 'gemini-image-out';
+
+/** All accepted quality strings across all providers. @public */
+declare type AiImageQuality = DallE3Quality | GptImageQuality;
+
+/** All accepted image size strings across all providers. @public */
+declare type AiImageSize = DallE2Size | DallE3Size | GptImageSize;
 
 /**
  * Capability vocabulary used to describe what a model can do. Used as both
@@ -143,7 +194,7 @@ declare type AiImageApiFormat = 'openai-images' | 'gemini-imagen' | 'xai-images'
  *
  * @public
  */
-declare type AiModelCapability = 'chat' | 'tools' | 'vision' | 'image-generation';
+declare type AiModelCapability = 'chat' | 'tools' | 'vision' | 'image-generation' | 'thinking';
 
 /**
  * A structured AI prompt with system/user split for direct API calls,
@@ -206,6 +257,12 @@ declare type AiServerToolType = 'web_search';
  */
 declare const aiServerToolType: Converter<AiServerToolType>;
 
+/**
+ * Thinking/reasoning mode support for a provider.
+ * @public
+ */
+declare type AiThinkingMode = 'optional' | 'required' | 'unsupported';
+
 /**
  * Converter for {@link IAiToolEnablement}.
  * @public
@@ -254,6 +311,12 @@ declare const allModelSpecKeys: ReadonlyArray<ModelSpecKey>;
  */
 declare const allProviderIds: ReadonlyArray<AiProviderId>;
 
+/**
+ * Model IDs for Anthropic thinking-capable models.
+ * @public
+ */
+declare type AnthropicThinkingModelNames = 'claude-sonnet-4-5' | 'claude-sonnet-4-6' | 'claude-opus-4-6' | 'claude-opus-4-7';
+
 /**
  * Converter for base64 strings (validates format).
  * @public
@@ -262,17 +325,8 @@ declare const base64String: Converter<string>;
 
 /**
  * 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
- *
+ * Routes by `apiFormat`: `'openai'` (xAI/OpenAI/Groq/Mistral — switches to Responses API when
+ * tools are set), `'anthropic'`, or `'gemini'`.
  * @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
@@ -301,19 +355,10 @@ declare function callProviderCompletionStream(params: IProviderCompletionStreamP
 
 /**
  * Calls the appropriate image-generation API for a given provider.
- *
- * Resolves a {@link IAiImageModelCapability} from
- * {@link IAiProviderDescriptor.imageGeneration} for the requested model and
- * routes by its `format`:
- * - `'openai-images'` for OpenAI (DALL-E, gpt-image-1)
- * - `'xai-images'` for xAI Grok image models
- * - `'gemini-imagen'` for Google Imagen `:predict`
- * - `'gemini-image-out'` for Gemini chat-style image output (Nano Banana)
- *
- * Image-model selection reuses the existing `'image'` {@link ModelSpecKey}.
- * When `request.referenceImages` is non-empty, the call is rejected up front
- * unless the resolved capability declares `acceptsImageReferenceInput`.
- *
+ * Routes by the `format` field of the resolved {@link IAiImageModelCapability}:
+ * `'openai-images'`, `'xai-images'`, `'xai-images-edits'`, `'gemini-imagen'`,
+ * or `'gemini-image-out'`. Rejects up front if `referenceImages` is set but the
+ * capability does not declare `acceptsImageReferenceInput`.
  * @param params - Request parameters including descriptor, API key, and prompt
  * @returns The generated images, or a failure
  * @public
@@ -321,12 +366,8 @@ declare function callProviderCompletionStream(params: IProviderCompletionStreamP
 declare function callProviderImageGeneration(params: IProviderImageGenerationParams): Promise<Result<IAiImageGenerationResponse>>;
 
 /**
- * Lists models available from a provider, with capabilities resolved from
- * native provider info (where supplied) and a configurable rule set.
- *
- * Routes based on `descriptor.apiFormat` — listing reuses the existing
- * format dispatch and does not require a separate descriptor field.
- *
+ * Lists models available from a provider, routing by `descriptor.apiFormat`.
+ * Capabilities are resolved from native provider info and a configurable rule set.
  * @param params - Request parameters including descriptor, API key, and optional capability filter
  * @returns The resolved model list, or a failure
  * @public
@@ -374,20 +415,11 @@ declare function callProxiedCompletionStream(proxyUrl: string, params: IProvider
 /**
  * Calls the image-generation endpoint on a proxy server instead of calling
  * the provider API directly from the browser.
- *
- * @remarks
- * The proxy contract:
- * - Endpoint: `POST ${proxyUrl}/api/ai/image-generation`
- * - Request body: `{providerId, apiKey, params, modelOverride?}`
- * - Success response body: an {@link IAiImageGenerationResponse}
- * - Error response body: `{error: string}` (surfaced as `proxy: ${error}`)
- *
- * The proxy server is responsible for descriptor lookup, model resolution,
- * provider dispatch, and response normalization. When `params.referenceImages`
- * is present, the proxy is also responsible for repackaging it into the
- * upstream wire format (e.g. multipart/form-data for OpenAI `/images/edits`,
- * `inlineData` parts for Gemini `:generateContent`).
- *
+ * Endpoint: `POST ${proxyUrl}/api/ai/image-generation`. Request body:
+ * `{providerId, apiKey, params, modelOverride?}`. The proxy handles descriptor
+ * lookup, model resolution, provider dispatch, and response normalization
+ * (including repackaging `referenceImages` for the upstream wire format).
+ * Error body `{error: string}` is surfaced as `proxy: ${error}`.
  * @param proxyUrl - Base URL of the proxy server (e.g. `http://localhost:3001`)
  * @param params - Same parameters as {@link callProviderImageGeneration}
  * @returns The generated images, or a failure
@@ -397,18 +429,9 @@ declare function callProxiedImageGeneration(proxyUrl: string, params: IProviderI
 
 /**
  * Calls the model-listing endpoint on a proxy server.
- *
- * @remarks
- * Proxy contract:
- * - Endpoint: `POST ${proxyUrl}/api/ai/list-models`
- * - Request body: `{providerId, apiKey, capability?}`. Capability config is
- *   not forwarded — the proxy applies its own (typically the same default
- *   the library ships).
- * - Success response body: an `IAiModelInfo[]` (under key `models`) where
- *   `capabilities` is serialized as a string array (not Set, which doesn't
- *   round-trip through JSON).
- * - Error response body: `{error: string}`, surfaced as `proxy: ${error}`.
- *
+ * Endpoint: `POST ${proxyUrl}/api/ai/list-models`. Capability config is not
+ * forwarded. `capabilities` is serialized as a string array. Error body
+ * `{error: string}` is surfaced as `proxy: ${error}`.
  * @public
  */
 declare function callProxiedListModels(proxyUrl: string, params: IProviderListModelsParams): Promise<Result<ReadonlyArray<IAiModelInfo>>>;
@@ -550,6 +573,18 @@ declare interface CsvOptions {
     delimiter?: string;
 }
 
+/** Pixel dimension sizes accepted by dall-e-2. @public */
+declare type DallE2Size = '256x256' | '512x512' | '1024x1024';
+
+/** Quality values for dall-e-3. @public */
+declare type DallE3Quality = 'standard' | 'hd';
+
+/** Pixel dimension sizes accepted by dall-e-3. @public */
+declare type DallE3Size = '1024x1024' | '1792x1024' | '1024x1792';
+
+/** Model names in the DALL-E family. @public */
+declare type DallEModelNames = 'dall-e-2' | 'dall-e-3';
+
 /**
  * Decrypts an {@link CryptoUtils.IEncryptedFile | encrypted file} and returns the JSON content.
  * @typeParam TPayload - Expected type of decrypted content
@@ -936,6 +971,15 @@ declare const GCM_AUTH_TAG_SIZE: number;
  */
 declare const GCM_IV_SIZE: number;
 
+/** Model names in the Gemini Flash Image family. @public */
+declare type GeminiFlashImageModelNames = 'gemini-2.5-flash-image';
+
+/**
+ * Model IDs for Google Gemini thinking-capable models.
+ * @public
+ */
+declare type GeminiThinkingModelNames = 'gemini-2.5-pro' | 'gemini-2.5-flash' | 'gemini-2.5-flash-lite';
+
 /**
  * Calls {@link AiAssist.callProviderCompletion}, then runs the response text
  * through a tolerant JSON converter (default:
@@ -972,6 +1016,18 @@ declare function getProviderDescriptor(id: string): Result<IAiProviderDescriptor
  */
 declare function getProviderDescriptors(): ReadonlyArray<IAiProviderDescriptor>;
 
+/** Model names in the GPT Image family. @public */
+declare type GptImageModelNames = 'gpt-image-1';
+
+/** Quality values for gpt-image-1. @public */
+declare type GptImageQuality = 'low' | 'medium' | 'high' | 'auto';
+
+/** Pixel dimension sizes accepted by gpt-image-1. @public */
+declare type GptImageSize = '1024x1024' | '1536x1024' | '1024x1536' | 'auto';
+
+/** Model names in the xAI Grok Imagine family. @public */
+declare type GrokImagineModelNames = 'grok-imagine-image' | 'grok-imagine-image-quality';
+
 declare namespace Hash {
     export {
         Md5Normalizer
@@ -1205,39 +1261,46 @@ declare interface IAiImageData {
  * 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.
+ * Uses a layered architecture:
+ * 1. Generic top-level options (size, count, quality, seed) apply across providers
+ *    via the resolved model's registry mapping.
+ * 2. Optional `models` array contains model-family-scoped blocks; the resolver
+ *    picks applicable blocks based on the resolved model and applies them in
+ *    declaration order.
+ *
+ * **Merge precedence (later wins):**
+ * 1. Generic top-level options (lowest precedence)
+ * 2. Family-generic blocks (matching family, models field omitted)
+ * 3. Model-specific blocks (models array includes resolved model name)
+ * 4. Other blocks (provider: 'other', models array includes resolved model name)
+ *
+ * Provider-mismatch: blocks whose provider doesn't match the dispatcher's
+ * provider lineage are silently skipped.
  *
  * @public
  */
 declare 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.
+     * Image dimensions for OpenAI models (mapped to `size` field).
+     * For xAI aspect ratio or Imagen aspect ratio, use the corresponding `models` family block.
      */
-    readonly size?: '1024x1024' | '1024x1792' | '1792x1024' | 'auto';
+    readonly size?: AiImageSize;
+    /** Number of images. Default 1. Some models enforce a maximum. */
+    readonly count?: number;
     /**
-     * Number of images to generate. Default 1.
-     *
-     * Note: `dall-e-3` rejects `count > 1`.
+     * Quality tier. Accepted values differ per model:
+     * - dall-e-3: 'standard' | 'hd'
+     * - gpt-image-1: 'low' | 'medium' | 'high' | 'auto'
+     * Other models ignore this field.
      */
-    readonly count?: number;
-    /** Generation quality hint where supported. */
-    readonly quality?: 'standard' | 'high';
-    /** Random seed for reproducibility, where supported. */
+    readonly quality?: AiImageQuality;
+    /** Reproducibility seed, where supported. */
     readonly seed?: number;
     /**
-     * Imagen-specific options. Ignored by other providers.
+     * Optional precision via model-family-scoped blocks. The resolver picks
+     * applicable blocks dynamically based on the resolved model.
      */
-    readonly imagen?: {
-        readonly negativePrompt?: string;
-        readonly aspectRatio?: '1:1' | '3:4' | '4:3' | '9:16' | '16:9';
-    };
+    readonly models?: ReadonlyArray<IModelFamilyConfig>;
 }
 
 /**
@@ -1290,13 +1353,25 @@ declare interface IAiImageModelCapability {
      * Whether matching models accept reference images via
      * {@link AiAssist.IAiImageGenerationParams.referenceImages}. When false or
      * undefined, calls that include reference images are rejected up front.
-     *
-     * @remarks
-     * Per-model constraints beyond ref support (e.g. dall-e-3 ignores edits)
-     * are not validated here and surface as provider 400s, consistent with the
-     * existing image-generation policy.
      */
     readonly acceptsImageReferenceInput?: boolean;
+    /** Accepted size strings. When present, dispatcher pre-validates. */
+    readonly acceptedSizes?: ReadonlyArray<string>;
+    /** When true, quality param is sent. When false/undefined, don't send quality. */
+    readonly supportsQualityParam?: boolean;
+    /** Accepted quality values when supportsQualityParam is true. */
+    readonly acceptedQualities?: ReadonlyArray<string>;
+    /** Maximum count (n). When present, dispatcher pre-validates. */
+    readonly maxCount?: number;
+    /**
+     * How to encode the output format on the wire:
+     * - 'response-format': send response_format: 'b64_json' (dall-e-2, dall-e-3)
+     * - 'output-format': send output_format (gpt-image-1)
+     * - 'none': send neither (Imagen, Gemini Flash)
+     */
+    readonly outputParamStyle?: 'response-format' | 'output-format' | 'none';
+    /** Default MIME type for response images. */
+    readonly defaultOutputMimeType?: string;
 }
 
 /**
@@ -1386,6 +1461,13 @@ declare interface IAiProviderDescriptor {
      * `prompt.attachments` are rejected up front.
      */
     readonly acceptsImageInput: boolean;
+    /**
+     * Whether this provider supports thinking/reasoning mode.
+     * - 'optional': thinking can be enabled but is not required
+     * - 'required': thinking is always active (e.g. o-series models)
+     * - 'unsupported': thinking is not supported
+     */
+    readonly thinkingMode: AiThinkingMode;
     /**
      * Image-generation capabilities, scoped to model id prefixes. Empty or
      * undefined means the provider does not support image generation.
@@ -1510,6 +1592,29 @@ declare interface IAiWebSearchToolConfig {
     readonly enableImageUnderstanding?: boolean;
 }
 
+/**
+ * Anthropic-specific thinking configuration.
+ * @public
+ */
+declare interface IAnthropicThinkingConfig {
+    /**
+     * Anthropic effort level. Maps 1:1 to `output_config.effort` on the wire.
+     * - 'low' | 'medium' | 'high': all thinking-capable models
+     * - 'max': Opus 4.6 only
+     */
+    readonly effort?: 'low' | 'medium' | 'high' | 'max';
+}
+
+/**
+ * Anthropic-specific thinking options block.
+ * @public
+ */
+declare interface IAnthropicThinkingOptions {
+    readonly provider: 'anthropic';
+    readonly models?: ReadonlyArray<AnthropicThinkingModelNames>;
+    readonly config: IAnthropicThinkingConfig;
+}
+
 /**
  * A single chat message in OpenAI format.
  * @public
@@ -1742,6 +1847,36 @@ declare interface ICryptoProvider {
     unwrapBytes(wrapped: IWrappedBytes, recipientPrivateKey: CryptoKey, options: IWrapBytesOptions): Promise<Result<Uint8Array>>;
 }
 
+/**
+ * Provider-specific config for DALL-E models (dall-e-2, dall-e-3).
+ * @remarks
+ * style is only valid for dall-e-3; the runtime validator rejects it for dall-e-2.
+ * @public
+ */
+declare interface IDallEImageGenerationConfig {
+    /** Image dimensions (dall-e-2: 256x256|512x512|1024x1024; dall-e-3: 1024x1024|1792x1024|1024x1792). */
+    readonly size?: DallE2Size | DallE3Size;
+    /** dall-e-3 only. Quality tier. */
+    readonly quality?: DallE3Quality;
+    /** dall-e-3 only. Visual style. */
+    readonly style?: 'vivid' | 'natural';
+}
+
+/**
+ * Options block scoped to DALL-E family models.
+ * @public
+ */
+declare interface IDallEModelOptions extends INamedModelFamilyConfig {
+    /** Discriminator: openai provider lineage. */
+    readonly provider: 'openai';
+    /** Family identifier. */
+    readonly family: 'dall-e';
+    /** Optional model names this block applies to. Omit = applies to all DALL-E models. */
+    readonly models?: DallEModelNames[];
+    /** Family-specific config. */
+    readonly config: IDallEImageGenerationConfig;
+}
+
 /**
  * Parameters for creating a {@link DirectEncryptionProvider}.
  * @public
@@ -1902,6 +2037,58 @@ declare interface IFencedStringifiedJsonOptions<T> extends IFencedStringifiedJso
     readonly inner: Converter<T> | Validator<T>;
 }
 
+/**
+ * Provider-specific config for Gemini Flash Image.
+ * @public
+ */
+declare interface IGeminiFlashImageGenerationConfig {
+    /** Aspect ratio string. */
+    readonly aspectRatio?: string;
+}
+
+/**
+ * Options block scoped to Gemini Flash Image models.
+ * @public
+ */
+declare interface IGeminiFlashImageModelOptions extends INamedModelFamilyConfig {
+    readonly provider: 'google';
+    readonly family: 'gemini-flash-image';
+    readonly models?: GeminiFlashImageModelNames[];
+    readonly config: IGeminiFlashImageGenerationConfig;
+}
+
+/**
+ * Google Gemini-specific thinking configuration.
+ * @public
+ */
+declare interface IGeminiThinkingConfig {
+    /**
+     * Token budget for thinking. Maps 1:1 to `thinkingBudget` on the wire.
+     * - 0: disable thinking (Flash and Flash-Lite only; error on Pro)
+     * - positive integer: soft token cap
+     * - -1: dynamic
+     * - omitted: model default
+     */
+    readonly thinkingBudget?: number;
+    /**
+     * Whether to include thought summaries in the response.
+     * @remarks
+     * INERT in phase B. Adapters never send `includeThoughts: true`.
+     * Wired up by the followup stream `ai-assist-thinking-events`.
+     */
+    readonly includeThoughts?: boolean;
+}
+
+/**
+ * Google Gemini-specific thinking options block.
+ * @public
+ */
+declare interface IGeminiThinkingOptions {
+    readonly provider: 'google';
+    readonly models?: ReadonlyArray<GeminiThinkingModelNames>;
+    readonly config: IGeminiThinkingConfig;
+}
+
 /**
  * Parameters for {@link AiAssist.generateJsonCompletion}. Extends
  * {@link AiAssist.IProviderCompletionParams} with JSON-validation knobs.
@@ -1942,6 +2129,90 @@ declare interface IGenerateJsonCompletionResult<T> {
     readonly response: IAiCompletionResponse;
 }
 
+/**
+ * Provider-specific config for gpt-image-1.
+ * @public
+ */
+declare interface IGptImageGenerationConfig {
+    /** Image dimensions. */
+    readonly size?: GptImageSize;
+    /** Quality tier. */
+    readonly quality?: GptImageQuality;
+    /** Output format (replaces response_format for this model). */
+    readonly outputFormat?: 'png' | 'jpeg' | 'webp';
+    /** JPEG/WebP compression level 0–100. */
+    readonly outputCompression?: number;
+    /** Background transparency control. */
+    readonly background?: 'transparent' | 'opaque' | 'auto';
+    /** Content moderation strictness. */
+    readonly moderation?: 'low' | 'auto';
+}
+
+/**
+ * Options block scoped to GPT Image family models.
+ * @public
+ */
+declare interface IGptImageModelOptions extends INamedModelFamilyConfig {
+    readonly provider: 'openai';
+    readonly family: 'gpt-image';
+    readonly models?: GptImageModelNames[];
+    readonly config: IGptImageGenerationConfig;
+}
+
+/**
+ * Provider-specific config for xAI Grok Imagine models.
+ * @public
+ */
+declare interface IGrokImagineImageGenerationConfig {
+    /** Aspect ratio string (xAI uses aspect ratios, not pixel dimensions). */
+    readonly aspectRatio?: string;
+    /** Resolution hint. */
+    readonly resolution?: string;
+}
+
+/**
+ * Options block scoped to xAI Grok Imagine family models.
+ * @public
+ */
+declare interface IGrokImagineModelOptions extends INamedModelFamilyConfig {
+    readonly provider: 'xai';
+    readonly family: 'grok-imagine';
+    readonly models?: GrokImagineModelNames[];
+    readonly config: IGrokImagineImageGenerationConfig;
+}
+
+/**
+ * Provider-specific config for Google Imagen 4 models.
+ * @public
+ */
+declare interface IImagen4GenerationConfig {
+    /** Aspect ratio string. */
+    readonly aspectRatio?: '1:1' | '3:4' | '4:3' | '9:16' | '16:9';
+    /** Output resolution. */
+    readonly imageSize?: '1K' | '2K';
+    /** Whether to add SynthID watermark. Must be false to use seed. */
+    readonly addWatermark?: boolean;
+    /** LLM-based prompt rewriting. */
+    readonly enhancePrompt?: boolean;
+    /** Output MIME type. */
+    readonly outputMimeType?: 'image/jpeg' | 'image/png';
+    /** JPEG compression quality. */
+    readonly outputCompressionQuality?: number;
+    /** Person generation policy. */
+    readonly personGeneration?: 'allow_all' | 'allow_adult' | 'dont_allow';
+}
+
+/**
+ * Options block scoped to Google Imagen 4 models.
+ * @public
+ */
+declare interface IImagen4ModelOptions extends INamedModelFamilyConfig {
+    readonly provider: 'google';
+    readonly family: 'imagen-4';
+    readonly models?: Imagen4ModelNames[];
+    readonly config: IImagen4GenerationConfig;
+}
+
 /**
  * Options for importing raw key material via {@link KeyStore.importSecret}.
  * Extends {@link IImportSecretOptions} with a type classification.
@@ -2297,6 +2568,9 @@ declare interface IKeyStoreVaultContents {
     readonly secrets: Record<string, IKeyStoreEntryJson>;
 }
 
+/** Model names in the Imagen 4 family. @public */
+declare type Imagen4ModelNames = 'imagen-4.0-generate-001' | 'imagen-4.0-ultra-generate-001' | 'imagen-4.0-fast-generate-001';
+
 /**
  * Details about a missing variable in context validation.
  * @public
@@ -2317,6 +2591,13 @@ declare interface IMissingVariableDetail {
     readonly existingPath: readonly string[];
 }
 
+/**
+ * Discriminated union of all model-family option blocks.
+ * Discriminated on `provider` + `family` fields.
+ * @public
+ */
+declare type IModelFamilyConfig = IDallEModelOptions | IGptImageModelOptions | IGrokImagineModelOptions | IImagen4ModelOptions | IGeminiFlashImageModelOptions | IOtherModelOptions;
+
 /**
  * A model specification: either a simple model string or a record mapping
  * context keys to nested model specs.
@@ -2329,10 +2610,10 @@ declare interface IMissingVariableDetail {
  * @example
  * ```typescript
  * // Simple — same model for all contexts:
- * const simple: ModelSpec = 'grok-4-1-fast';
+ * const simple: ModelSpec = 'grok-4.3';
  *
- * // Context-aware — reasoning model when tools are active:
- * const split: ModelSpec = { base: 'grok-4-1-fast', tools: 'grok-4-1-fast-reasoning' };
+ * // Context-aware — different model for tools and thinking:
+ * const split: ModelSpec = { base: 'grok-4.3', tools: 'grok-4.3', thinking: 'grok-4.3' };
  *
  * // Future nested — per-tool model selection:
  * const nested: ModelSpec = { base: 'grok-fast', tools: { base: 'grok-r', image: 'grok-v' } };
@@ -2377,6 +2658,15 @@ declare interface IMustacheTemplateOptions {
     readonly includePartials?: boolean;
 }
 
+/**
+ * Base shape shared by all named family option blocks.
+ * Provides a typed `models` field for applicability filtering without unsafe casts.
+ * @internal
+ */
+declare interface INamedModelFamilyConfig {
+    readonly models?: readonly string[];
+}
+
 /**
  * Named secret for encryption/decryption.
  * @public
@@ -2392,6 +2682,67 @@ declare interface INamedSecret {
     readonly key: Uint8Array;
 }
 
+/**
+ * OpenAI-specific thinking configuration.
+ * @remarks
+ * Maps to `reasoning_effort` (Chat Completions path) or `reasoning.effort`
+ * (Responses API path) on the wire. The adapter selects the correct field.
+ * @public
+ */
+declare interface IOpenAiThinkingConfig {
+    /**
+     * OpenAI reasoning effort. Maps 1:1 to the wire field.
+     * - 'none': disables reasoning (gpt-5.x only; rejected by o-series)
+     * - 'minimal': fastest (gpt-5.x)
+     * - 'low' | 'medium' | 'high': standard tiers
+     * - 'xhigh': highest (select gpt-5.x models only)
+     *
+     * @remarks
+     * When effective effort is 'none', reasoning is disabled and temperature is
+     * accepted by gpt-5.x models. This is the only case where temperature and
+     * thinking config co-exist without a Result.fail.
+     */
+    readonly effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+}
+
+/**
+ * OpenAI-specific thinking options block.
+ * @public
+ */
+declare interface IOpenAiThinkingOptions {
+    readonly provider: 'openai';
+    readonly models?: ReadonlyArray<OpenAiThinkingModelNames>;
+    readonly config: IOpenAiThinkingConfig;
+}
+
+/**
+ * Escape-hatch options block for models not covered by a named family.
+ * @remarks
+ * `models` is required — there is no implicit "all" for unknown model families.
+ * `config` is `JsonObject` — passed verbatim to the wire request with no validation.
+ * This is the "trust me, I know what I'm doing" path for callers who need to send
+ * wire params our typed configs don't yet expose.
+ * @public
+ */
+declare interface IOtherModelOptions {
+    readonly provider: 'other';
+    readonly models: string[];
+    readonly config: JsonObject;
+}
+
+/**
+ * Escape-hatch options block for providers not covered by typed configs.
+ * @remarks
+ * `models` is required — no implicit "all" for unknown providers.
+ * `config` fields are merged verbatim into the wire request.
+ * @public
+ */
+declare interface IOtherThinkingOptions {
+    readonly provider: 'other';
+    readonly models: ReadonlyArray<string>;
+    readonly config: JsonObject;
+}
+
 /**
  * Pluggable backend that persists raw asymmetric private keys outside of the
  * encrypted keystore vault. Concrete implementations live in platform-specific
@@ -2452,10 +2803,7 @@ declare interface IProviderCompletionParams {
     readonly apiKey: string;
     /** The structured prompt to send */
     readonly prompt: AiPrompt;
-    /**
-     * Additional messages to append after system+user (e.g. for correction retries).
-     * These are appended in order after the initial system and user messages.
-     */
+    /** Additional messages to append after system+user in order (e.g. for correction retries). */
     readonly additionalMessages?: ReadonlyArray<IChatMessage>;
     /** Sampling temperature (default: 0.7) */
     readonly temperature?: number;
@@ -2468,20 +2816,17 @@ declare interface IProviderCompletionParams {
     /** Optional abort signal for cancelling the in-flight request. */
     readonly signal?: AbortSignal;
     /**
-     * Optional override of the descriptor's default base URL. When set, the
-     * dispatcher uses this URL (scheme + host + optional port + optional path
-     * prefix) and appends the descriptor's per-route suffix (e.g.
-     * `/chat/completions`) the same way it composes against the default.
-     *
-     * Must be a well-formed `http`/`https` URL string. Used to dispatch the same
-     * provider descriptor against a self-hosted or local endpoint (e.g.
-     * `http://localhost:11434/v1` for Ollama, or LAN-hosted OpenAI-compatible
-     * servers).
-     *
-     * Setting `endpoint` does not change the auth shape: providers with
-     * `needsSecret === true` still require an API key.
+     * Optional override of the descriptor's default base URL (scheme + host +
+     * optional port + path prefix). The per-route suffix (e.g. `/chat/completions`)
+     * is appended unchanged. Must be a well-formed `http`/`https` URL. Auth shape
+     * is unchanged: `needsSecret` providers still require an API key.
      */
     readonly endpoint?: string;
+    /**
+     * Optional thinking/reasoning config. Anthropic, OpenAI, and xAI reject `temperature` when
+     * the effective merged effort is non-`'none'`; Gemini always accepts both.
+     */
+    readonly thinking?: IThinkingConfig;
 }
 
 /**
@@ -2523,6 +2868,10 @@ declare interface IProviderCompletionStreamParams {
      * dispatcher; auth shape is unaffected.
      */
     readonly endpoint?: string;
+    /**
+     * Optional thinking/reasoning mode configuration.
+     */
+    readonly thinking?: IThinkingConfig;
 }
 
 /**
@@ -2542,13 +2891,7 @@ declare interface IProviderImageGenerationParams {
     readonly logger?: Logging.ILogger;
     /** Optional abort signal for cancelling the in-flight request. */
     readonly signal?: AbortSignal;
-    /**
-     * Optional override of the descriptor's default base URL. Same semantics as
-     * the non-streaming completion path's endpoint: a well-formed `http`/`https`
-     * URL substituted for `descriptor.baseUrl` when composing the request, with
-     * the per-route suffix (e.g. `/images/generations`, `:predict`) appended
-     * unchanged.
-     */
+    /** Optional override of the descriptor's base URL; per-route suffix is appended unchanged. */
     readonly endpoint?: string;
 }
 
@@ -2569,11 +2912,7 @@ declare interface IProviderListModelsParams {
     readonly logger?: Logging.ILogger;
     /** Optional abort signal for cancelling the in-flight request. */
     readonly signal?: AbortSignal;
-    /**
-     * Optional override of the descriptor's default base URL — a well-formed
-     * `http`/`https` URL substituted for `descriptor.baseUrl`, with the
-     * per-format `/models` route appended unchanged.
-     */
+    /** Optional override of the descriptor's base URL; per-format `/models` route is appended unchanged. */
     readonly endpoint?: string;
 }
 
@@ -2605,6 +2944,38 @@ declare interface IRequiredMustacheTemplateOptions {
     readonly includePartials: boolean;
 }
 
+/**
+ * The resolved, merged wire parameters for an image generation request.
+ * Built from the layered options and ready for provider-specific encoding.
+ * @public
+ */
+declare interface IResolvedImageOptions {
+    /** Number of images to generate. */
+    readonly n: number;
+    /** Image size (OpenAI-style pixel strings). */
+    readonly size?: string;
+    /** Quality tier. */
+    readonly quality?: string;
+    /** Seed for reproducibility. */
+    readonly seed?: number;
+    readonly style?: string;
+    readonly outputFormat?: string;
+    readonly outputCompression?: number;
+    readonly background?: string;
+    readonly moderation?: string;
+    readonly aspectRatio?: string;
+    readonly resolution?: string;
+    readonly imagenAspectRatio?: string;
+    readonly imageSize?: string;
+    readonly addWatermark?: boolean;
+    readonly enhancePrompt?: boolean;
+    readonly imagenOutputMimeType?: string;
+    readonly imagenOutputCompressionQuality?: number;
+    readonly personGeneration?: string;
+    readonly geminiAspectRatio?: string;
+    readonly otherParams?: JsonObject;
+}
+
 /**
  * Checks if a JSON object appears to be an encrypted file.
  * Uses the format field as a discriminator.
@@ -2637,6 +3008,39 @@ declare const isoDate: Converter<Date, unknown>;
  */
 declare const isoDateTime: Converter<DateTime, unknown>;
 
+/**
+ * Thinking/reasoning mode configuration for a completion request.
+ *
+ * @remarks
+ * The generic `effort` field covers the common-subset cross-provider vocabulary.
+ * For provider-specific precision (Anthropic 'max', OpenAI 'xhigh', Gemini token
+ * budgets, xAI effort-level tuning), use the `providers` array.
+ *
+ * Absence (or undefined) means "no thinking mode" — existing callers are unaffected.
+ *
+ * @public
+ */
+declare interface IThinkingConfig {
+    /**
+     * Cross-provider effort level. Common-subset mapping:
+     * - 'low': Anthropic effort:low | OpenAI effort:low | Gemini thinkingBudget:1024 | xAI reasoning_effort:low
+     * - 'medium': effort:medium | effort:medium | thinkingBudget:4096 | reasoning_effort:medium
+     * - 'high': effort:high | effort:high | thinkingBudget:8192 | reasoning_effort:high
+     */
+    readonly effort?: 'low' | 'medium' | 'high';
+    /**
+     * Optional per-provider precision blocks. Blocks for providers that don't
+     * match the resolved model's provider are silently skipped.
+     */
+    readonly providers?: ReadonlyArray<IThinkingProviderConfig>;
+}
+
+/**
+ * Discriminated union of per-provider thinking config blocks.
+ * @public
+ */
+declare type IThinkingProviderConfig = IAnthropicThinkingOptions | IOpenAiThinkingOptions | IGeminiThinkingOptions | IXAiThinkingOptions | IOtherThinkingOptions;
+
 /**
  * Represents a variable reference extracted from a Mustache template.
  * @public
@@ -2714,6 +3118,29 @@ declare interface IWrappedBytes {
     readonly ciphertext: string;
 }
 
+/**
+ * xAI-specific thinking configuration.
+ * @public
+ */
+declare interface IXAiThinkingConfig {
+    /**
+     * xAI reasoning effort. Maps 1:1 to `reasoning_effort` on the wire.
+     * For grok-4, the adapter omits this field (grok-4 always reasons and
+     * rejects the parameter).
+     */
+    readonly effort?: 'none' | 'low' | 'medium' | 'high';
+}
+
+/**
+ * xAI-specific thinking options block.
+ * @public
+ */
+declare interface IXAiThinkingOptions {
+    readonly provider: 'xai';
+    readonly models?: ReadonlyArray<XAiThinkingModelNames>;
+    readonly config: IXAiThinkingConfig;
+}
+
 /**
  * Options for YAML serialization, mirroring commonly-used `js-yaml` `DumpOptions`.
  * @public
@@ -3467,7 +3894,7 @@ declare const modelSpec: Converter<ModelSpec>;
  * Known context keys for model specification maps.
  * @public
  */
-declare type ModelSpecKey = 'base' | 'tools' | 'image';
+declare type ModelSpecKey = 'base' | 'tools' | 'image' | 'thinking';
 
 /**
  * Converter for {@link ModelSpecKey}.
@@ -3729,6 +4156,12 @@ declare class NodeCryptoProvider implements ICryptoProvider {
  */
 declare const nodeCryptoProvider: NodeCryptoProvider;
 
+/**
+ * Model IDs for OpenAI thinking-capable models.
+ * @public
+ */
+declare type OpenAiThinkingModelNames = 'o3' | 'o4-mini' | 'o3-deep-research' | 'o4-mini-deep-research' | 'gpt-5' | 'gpt-5.1' | 'gpt-5.2' | 'gpt-5.5' | 'gpt-5-pro';
+
 /**
  * Parses CSV data from a string.
  * @param body - The CSV string to parse.
@@ -3966,6 +4399,28 @@ declare function resolveEffectiveTools(descriptor: IAiProviderDescriptor, settin
  */
 declare function resolveImageCapability(descriptor: IAiProviderDescriptor, modelId: string): IAiImageModelCapability | undefined;
 
+/**
+ * Resolves the merged image options for a given model and capability.
+ *
+ * @remarks
+ * **Merge precedence (later wins):**
+ * 1. Generic top-level options (size, count, quality, seed)
+ * 2. Family-generic blocks (models field omitted, provider matches)
+ * 3. Model-specific blocks (models array includes the resolved model name)
+ * 4. Other blocks (provider: 'other', models array includes model name)
+ *
+ * Provider-mismatch blocks are silently skipped.
+ *
+ * Within each tier, declaration order — later declaration wins.
+ *
+ * @param modelId - The resolved model string
+ * @param capability - The resolved IAiImageModelCapability for this model
+ * @param options - Caller-supplied options
+ * @returns The merged wire parameters
+ * @public
+ */
+declare function resolveImageOptions(modelId: string, capability: IAiImageModelCapability, options: IAiImageGenerationOptions | undefined): IResolvedImageOptions;
+
 /**
  * Resolves a {@link ModelSpec} to a concrete model string given an optional context key.
  *
@@ -4055,6 +4510,27 @@ declare function tryDecryptFile<TPayload extends JsonValue = JsonValue, TMetadat
  */
 declare const uint8ArrayFromBase64: Converter<Uint8Array>;
 
+/**
+ * Validates the resolved options against per-model registry constraints.
+ *
+ * @remarks
+ * Fails fast on the first violation. Error format:
+ * `model "${model}": ${field} "${value}" is not accepted; accepted values: ${JSON.stringify(accepted)}`
+ *
+ * @param modelId - The resolved model string
+ * @param capability - The resolved capability entry from the registry
+ * @param resolved - The merged options from resolveImageOptions
+ * @returns The same resolved options on success, or a failure with a contextual message
+ * @public
+ */
+declare function validateResolvedOptions(modelId: string, capability: IAiImageModelCapability, resolved: IResolvedImageOptions): Result<IResolvedImageOptions>;
+
+/**
+ * Model IDs for xAI thinking-capable models.
+ * @public
+ */
+declare type XAiThinkingModelNames = 'grok-3-mini' | 'grok-4.3' | 'grok-4';
+
 declare namespace Yaml {
     export {
         yamlConverter,