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

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,31 @@ 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';
+
+/**
+ * Recommended OWASP 2023 minimum Argon2id parameters.
+ * Suitable for recovery-row key derivation (high-entropy inputs).
+ * @public
+ */
+declare const ARGON2ID_OWASP_MIN: IArgon2idParams;
+
+/**
+ * Stronger Argon2id parameters suitable for user-typed passphrases.
+ * @public
+ */
+declare const ARGON2ID_PASSPHRASE: IArgon2idParams;
+
+/**
+ * Converter for {@link CryptoUtils.IArgon2idKeyDerivationParams | Argon2id key derivation parameters}.
+ * @public
+ */
+declare const argon2idKeyDerivationParams: Converter<IArgon2idKeyDerivationParams>;
+
 /**
  * Converter for base64 strings (validates format).
  * @public
@@ -262,17 +344,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 +374,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 +385,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 +434,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 +448,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>>>;
@@ -458,6 +500,8 @@ declare namespace Converters_3 {
         encryptedFileFormat,
         encryptedFileErrorMode,
         keyDerivationFunction,
+        pbkdf2KeyDerivationParams,
+        argon2idKeyDerivationParams,
         keyDerivationParams,
         base64String,
         uint8ArrayFromBase64,
@@ -511,6 +555,8 @@ declare namespace CryptoUtils {
         importPublicKeyFromMultibaseSpki,
         multibaseBase64UrlDecode,
         multibaseBase64UrlEncode,
+        HpkeProvider,
+        IHpkeSealResult,
         isEncryptedFile,
         EncryptionAlgorithm,
         EncryptedFileFormat,
@@ -521,7 +567,13 @@ declare namespace CryptoUtils {
         IWrappedBytes,
         allKeyPairAlgorithms,
         KeyDerivationFunction,
+        IPbkdf2KeyDerivationParams,
+        IArgon2idKeyDerivationParams,
         IKeyDerivationParams,
+        IArgon2idParams,
+        ARGON2ID_OWASP_MIN,
+        ARGON2ID_PASSPHRASE,
+        IArgon2idProvider,
         IEncryptedFile,
         ICryptoProvider,
         IEncryptionProvider,
@@ -550,6 +602,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 +1000,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 +1045,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
@@ -979,6 +1064,128 @@ declare namespace Hash {
 }
 export { Hash }
 
+/**
+ * HPKE base mode (RFC 9180) — `DHKEM(X25519, HKDF-SHA256) + HKDF-SHA256 + AES-256-GCM`.
+ *
+ * Class-based provider that captures a `SubtleCrypto` instance at construction,
+ * matching the existing `NodeCryptoProvider` / `BrowserCryptoProvider` / `KeyStore`
+ * factory pattern used throughout `@fgv/ts-extras/crypto-utils`.
+ *
+ * **Node.js usage:**
+ * ```typescript
+ * import * as crypto from 'crypto';
+ * const hpke = HpkeProvider.create(crypto.webcrypto.subtle).orThrow();
+ * ```
+ *
+ * **Browser usage:**
+ * ```typescript
+ * const hpke = HpkeProvider.create(globalThis.crypto.subtle).orThrow();
+ * ```
+ *
+ * **Runtime requirements:** Node.js 20+ (X25519 in `crypto.webcrypto`);
+ * Chrome 113+, Safari 16.4+, Firefox 118+ (X25519 added to Web Crypto in 2023).
+ * @public
+ */
+declare class HpkeProvider {
+    private readonly _subtle;
+    private constructor();
+    /**
+     * Creates an `HpkeProvider` bound to the given `SubtleCrypto` instance.
+     *
+     * @param subtle - Web Crypto SubtleCrypto instance.
+     *   Node.js: `(await import('crypto')).webcrypto.subtle`.
+     *   Browser: `globalThis.crypto.subtle`.
+     * @returns `Success` with the provider, or `Failure` if construction fails.
+     */
+    static create(subtle: SubtleCrypto): Result<HpkeProvider>;
+    /**
+     * HPKE base-mode seal (sender side). RFC 9180 §6.1.
+     *
+     * Generates a fresh ephemeral X25519 keypair, runs DHKEM Encap to produce a
+     * shared secret and `enc` (32-byte raw ephemeral public key), derives the AEAD
+     * key and nonce deterministically via the RFC 9180 key schedule, then encrypts
+     * `plaintext` with AES-256-GCM.
+     *
+     * @param recipientPublicKey - Recipient's X25519 public `CryptoKey`
+     *   (`algorithm.name === 'X25519'`, `type === 'public'`, **`extractable: true`**).
+     *   Must be extractable — DHKEM Encap calls `exportKey('raw', ...)` on this key to
+     *   build the KEM shared-secret context. Keys imported with `extractable: false` will
+     *   cause this method to return a `Failure`.
+     * @param info - Context-binding bytes. **Load-bearing — no default.**
+     *   Binds this ciphertext to a specific application context, preventing replay
+     *   across different contexts sharing the same recipient keypair.
+     *   Use `new TextEncoder().encode('myapp/v1/use-case\x00' + contextId)` pattern.
+     *   Never pass an empty array in production: empty `info` provides no context binding.
+     * @param aad - Additional authenticated data. Integrity-protected but not encrypted.
+     *   `new Uint8Array(0)` is valid when no AAD is needed.
+     * @param plaintext - Bytes to encrypt. `new Uint8Array(0)` is valid.
+     * @returns `Success` with `{ enc, ciphertext }`, or `Failure` with error context.
+     */
+    sealBase(recipientPublicKey: CryptoKey, info: Uint8Array, aad: Uint8Array, plaintext: Uint8Array): Promise<Result<IHpkeSealResult>>;
+    /**
+     * HPKE base-mode open (recipient side). RFC 9180 §6.1.
+     *
+     * Decapsulates `enc` using the recipient's X25519 private key, derives the same
+     * AEAD key and nonce from the shared secret and `info`, then authenticates and
+     * decrypts `ciphertext` with AES-256-GCM.
+     *
+     * Returns `Failure` on any of:
+     * - Wrong private key (different DH output → different key derivation)
+     * - Wrong `info` (different key schedule context → different AEAD key)
+     * - Wrong `aad` (AES-GCM authentication fails)
+     * - Tampered `ciphertext` or `enc` (authentication fails or DH fails)
+     * - `enc` not exactly 32 bytes
+     * - `ciphertext` shorter than 16 bytes (no room for authentication tag)
+     *
+     * @param recipientPrivateKey - Recipient's X25519 private `CryptoKey`
+     *   (`algorithm.name === 'X25519'`, `type === 'private'`, `usages` includes `'deriveBits'`).
+     *   **Must be extractable** (`extractable: true`) — the recipient's public key bytes
+     *   are recovered from the JWK `x` field during Decap.
+     * @param info - Context-binding bytes. Must exactly match `info` from `sealBase`.
+     * @param aad - Must exactly match `aad` from `sealBase`.
+     * @param enc - The encapsulated key from `sealBase` — exactly 32 bytes.
+     * @param ciphertext - The ciphertext from `sealBase` — `plaintext.length + 16` bytes.
+     * @returns `Success` with decrypted plaintext bytes, or `Failure` with error context.
+     */
+    openBase(recipientPrivateKey: CryptoKey, info: Uint8Array, aad: Uint8Array, enc: Uint8Array, ciphertext: Uint8Array): Promise<Result<Uint8Array>>;
+    /**
+     * HKDF-SHA256 key derivation (RFC 5869). Extract-then-Expand using SHA-256.
+     *
+     * This is raw RFC 5869 HKDF — it does **not** use RFC 9180's labeled variants.
+     * The HPKE key schedule internally uses labeled HKDF; this method is the unlabeled
+     * version for callers that need standalone key derivation.
+     *
+     * @param secret - Input keying material (IKM). Any length.
+     * @param salt - Optional salt. Use `new Uint8Array(0)` if no salt is available
+     *   (RFC 5869: 32 zero bytes are used internally when salt is empty).
+     * @param info - Context / application-binding bytes. Any length.
+     * @param length - Number of output bytes to derive. Maximum 8160 bytes (255 × 32).
+     * @returns `Success` with derived bytes, or `Failure` with error context.
+     */
+    hkdf(secret: Uint8Array, salt: Uint8Array, info: Uint8Array, length: number): Promise<Result<Uint8Array>>;
+    /**
+     * Encodes an {@link IHpkeSealResult} as a single contiguous byte array for wire transport.
+     *
+     * Format: `enc` (32 bytes, fixed) || `ciphertext` (variable length).
+     * The 32-byte `enc` length is fixed for X25519; the split point is unambiguous.
+     *
+     * @param result - The output of {@link HpkeProvider.sealBase}.
+     * @returns Concatenated bytes: `enc || ciphertext`.
+     */
+    static encodeEnvelope(result: IHpkeSealResult): Uint8Array;
+    /**
+     * Decodes an envelope produced by {@link HpkeProvider.encodeEnvelope}.
+     *
+     * Validates that the buffer is at least 48 bytes (32-byte enc + 16-byte minimum
+     * ciphertext containing the AES-GCM auth tag; zero-length plaintext is the minimum
+     * meaningful case).
+     *
+     * @param envelope - Envelope bytes from `encodeEnvelope`.
+     * @returns `Success` with `{ enc, ciphertext }`, or `Failure` if malformed.
+     */
+    static decodeEnvelope(envelope: Uint8Array): Result<IHpkeSealResult>;
+}
+
 /**
  * Options for adding an asymmetric keypair to the key store.
  * @public
@@ -1023,6 +1230,25 @@ declare interface IAddKeyPairResult {
     readonly warning?: string;
 }
 
+/**
+ * Options for adding an Argon2id password-derived secret.
+ * @public
+ */
+declare interface IAddSecretFromPasswordArgon2idOptions {
+    /**
+     * Argon2id parameters. Defaults to {@link CryptoUtils.ARGON2ID_OWASP_MIN}.
+     */
+    readonly params?: IArgon2idParams;
+    /**
+     * Optional description for the secret.
+     */
+    readonly description?: string;
+    /**
+     * Whether to replace an existing secret with the same name.
+     */
+    readonly replace?: boolean;
+}
+
 /**
  * Options for adding a secret derived from a password.
  * @public
@@ -1205,39 +1431,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 +1523,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 +1631,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 +1762,104 @@ 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;
+}
+
+/**
+ * Argon2id key derivation parameters (RFC 9106).
+ * @public
+ */
+declare interface IArgon2idKeyDerivationParams {
+    /** Key derivation function discriminator. */
+    readonly kdf: 'argon2id';
+    /** Base64-encoded salt used for key derivation. */
+    readonly salt: string;
+    /** Memory cost in kibibytes. */
+    readonly memoryKiB: number;
+    /** Number of passes (time cost). */
+    readonly iterations: number;
+    /** Degree of parallelism. */
+    readonly parallelism: number;
+}
+
+/**
+ * Parameters for Argon2id key derivation (RFC 9106).
+ * All fields are required; fgv does not pick defaults silently.
+ * @public
+ */
+declare interface IArgon2idParams {
+    /**
+     * Memory cost in kibibytes (KiB).
+     * OWASP 2023 minimum: 19456 (19 MiB). Stronger: 65536 (64 MiB).
+     * Constraint: \>= 8.
+     */
+    readonly memoryKiB: number;
+    /**
+     * Number of passes (iterations / time cost).
+     * OWASP 2023 minimum: 2. Range: \>= 1.
+     */
+    readonly iterations: number;
+    /**
+     * Degree of parallelism (threads).
+     * Note: WASM-based implementations compute sequentially regardless of this value,
+     * but the value is wired into the algorithm and AFFECTS the output hash bytes.
+     * Callers must use the same parallelism value consistently for a given secret.
+     * Range: 1–255.
+     */
+    readonly parallelism: number;
+    /**
+     * Number of output bytes (hash length).
+     * Typical values: 16 (128-bit), 32 (256-bit, AES-256 key), 64 (512-bit).
+     * Constraint: \>= 4.
+     */
+    readonly outputBytes: number;
+}
+
+/**
+ * Argon2id key derivation provider (RFC 9106).
+ *
+ * Implementations are in separate packages to avoid WASM bundle costs for
+ * consumers who don't need Argon2id:
+ * - Node: `@fgv/ts-extras-argon2` (`NodeArgon2Provider`)
+ * - Browser: `@fgv/ts-web-extras-argon2` (`BrowserArgon2Provider`)
+ *
+ * @public
+ */
+declare interface IArgon2idProvider {
+    /**
+     * Derives key material from a password using Argon2id (RFC 9106 §3.1).
+     *
+     * Returns the raw derived bytes as a `Uint8Array`. Both Node and browser
+     * implementations produce bit-identical output for identical inputs.
+     *
+     * @param password - Password or passphrase. Accepts string (UTF-8) or raw bytes.
+     * @param salt - Salt bytes. Must be random and unique per credential (\>= 16 bytes recommended).
+     * @param params - Argon2id parameters. Use `ARGON2ID_OWASP_MIN` as a starting point.
+     * @returns Success with derived bytes, Failure with error context.
+     */
+    argon2id(password: Uint8Array | string, salt: Uint8Array, params: IArgon2idParams): Promise<Result<Uint8Array>>;
+}
+
 /**
  * A single chat message in OpenAI format.
  * @public
@@ -1740,6 +2090,110 @@ declare interface ICryptoProvider {
      * @returns `Success` with the original `plaintext`, or `Failure` with error context.
      */
     unwrapBytes(wrapped: IWrappedBytes, recipientPrivateKey: CryptoKey, options: IWrapBytesOptions): Promise<Result<Uint8Array>>;
+    /**
+     * Signs `data` with `privateKey` using the algorithm inferred from the key.
+     * Delegates to `crypto.subtle.sign`; the algorithm is derived from
+     * `privateKey.algorithm.name` — ECDSA keys are augmented with
+     * `hash: 'SHA-256'` at sign time (the hash is not stored in the key);
+     * all other algorithm names are passed through as-is.
+     * Intended for Ed25519 and ECDSA-P256 asymmetric private keys; for
+     * HMAC-SHA256 authentication codes use {@link ICryptoProvider.hmacSha256} instead.
+     * @param privateKey - A `CryptoKey` with `'sign'` usage (e.g. generated by
+     * {@link CryptoUtils.ICryptoProvider.generateKeyPair | generateKeyPair} with
+     * `'ecdsa-p256'` or `'ed25519'`).
+     * @param data - The bytes to sign.
+     * @returns `Success` with the raw signature bytes, or `Failure` with error context.
+     */
+    sign(privateKey: CryptoKey, data: Uint8Array): Promise<Result<Uint8Array>>;
+    /**
+     * Verifies a signature produced by {@link ICryptoProvider.sign}.
+     * Delegates to `crypto.subtle.verify`; the algorithm is derived from
+     * `publicKey.algorithm.name` — ECDSA keys are augmented with
+     * `hash: 'SHA-256'`; all other algorithm names are passed through as-is.
+     * Intended for Ed25519 and ECDSA-P256 asymmetric public keys; for
+     * HMAC-SHA256 verification use {@link ICryptoProvider.verifyHmacSha256} instead.
+     * @param publicKey - A `CryptoKey` with `'verify'` usage (e.g. the public
+     * half of a keypair generated by
+     * {@link CryptoUtils.ICryptoProvider.generateKeyPair | generateKeyPair} with
+     * `'ecdsa-p256'` or `'ed25519'`).
+     * @param signature - The raw signature bytes produced by `sign`.
+     * @param data - The original data that was signed.
+     * @returns `Success` with `true` if the signature is valid, `false` if it is
+     * not, or `Failure` with error context if the operation itself failed.
+     */
+    verify(publicKey: CryptoKey, signature: Uint8Array, data: Uint8Array): Promise<Result<boolean>>;
+    /**
+     * Compares two byte arrays in constant time.
+     *
+     * The comparison visits all bytes of `a` and `b` regardless of where they
+     * diverge, accumulating XOR differences with bitwise-OR. No early-return is
+     * possible once the length check passes, making timing independent of the
+     * byte values. This prevents timing side-channels when comparing MAC outputs,
+     * signed-token bytes, or any secret-derived byte sequences.
+     *
+     * Returns `false` immediately (before the loop) when `a.length !== b.length`;
+     * the length mismatch itself is not secret in normal use.
+     * @param a - First byte array.
+     * @param b - Second byte array.
+     * @returns `true` if the arrays have the same length and identical contents,
+     * `false` otherwise.
+     */
+    timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;
+    /**
+     * Computes an HMAC-SHA256 authentication code for `data` using `key`.
+     *
+     * The key must be a `CryptoKey` with `'sign'` usage and algorithm name
+     * `'HMAC'` (e.g. derived via PBKDF2 or imported with
+     * `crypto.subtle.importKey`). Use {@link ICryptoProvider.verifyHmacSha256}
+     * for constant-time verification of the output.
+     * @param key - An HMAC `CryptoKey` with `'sign'` usage.
+     * @param data - The bytes to authenticate.
+     * @returns `Success` with the 32-byte MAC, or `Failure` with error context.
+     */
+    hmacSha256(key: CryptoKey, data: Uint8Array): Promise<Result<Uint8Array>>;
+    /**
+     * Verifies an HMAC-SHA256 authentication code in constant time.
+     *
+     * Computes the expected MAC over `data` with `key`, then compares it to
+     * `signature` using {@link ICryptoProvider.timingSafeEqual} so that
+     * mismatches do not leak information through timing.
+     * @param key - An HMAC `CryptoKey` with `'sign'` usage.
+     * @param signature - The MAC bytes to verify (typically 32 bytes).
+     * @param data - The original data that was authenticated.
+     * @returns `Success` with `true` if the MAC is valid, `false` if it is not,
+     * or `Failure` with error context if the MAC computation itself failed.
+     */
+    verifyHmacSha256(key: CryptoKey, signature: Uint8Array, data: Uint8Array): Promise<Result<boolean>>;
+}
+
+/**
+ * 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;
 }
 
 /**
@@ -1902,6 +2356,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 +2448,110 @@ 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;
+}
+
+/**
+ * Output of {@link HpkeProvider.sealBase}.
+ *
+ * The `ciphertext` field includes the 16-byte AES-256-GCM authentication tag
+ * appended by Web Crypto's `encrypt()` operation: `length = plaintext.length + 16`.
+ * @public
+ */
+declare interface IHpkeSealResult {
+    /**
+     * Encapsulated key — 32-byte raw X25519 ephemeral public key (`enc` in RFC 9180).
+     * Must be transmitted to the recipient alongside `ciphertext`.
+     */
+    readonly enc: Uint8Array;
+    /**
+     * AES-256-GCM ciphertext with the 16-byte authentication tag appended.
+     * Length = `plaintext.length + 16`.
+     */
+    readonly ciphertext: Uint8Array;
+}
+
+/**
+ * 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.
@@ -1968,23 +2578,10 @@ declare interface IImportSecretOptions extends IAddSecretOptions {
 
 /**
  * Key derivation parameters stored in encrypted files.
- * Allows decryption with password without needing to know the original salt/iterations.
+ * Discriminated union on `kdf` field: `'pbkdf2'` or `'argon2id'`.
  * @public
  */
-declare interface IKeyDerivationParams {
-    /**
-     * Key derivation function used.
-     */
-    readonly kdf: KeyDerivationFunction;
-    /**
-     * Base64-encoded salt used for key derivation.
-     */
-    readonly salt: string;
-    /**
-     * Number of iterations used for key derivation.
-     */
-    readonly iterations: number;
-}
+declare type IKeyDerivationParams = IPbkdf2KeyDerivationParams | IArgon2idKeyDerivationParams;
 
 /**
  * WebCrypto parameters for a single {@link CryptoUtils.KeyPairAlgorithm}.
@@ -2165,9 +2762,9 @@ declare interface IKeyStoreFile {
      */
     readonly encryptedData: string;
     /**
-     * Key derivation parameters (required for key store - always password-derived).
+     * Key derivation parameters for the vault master key (always PBKDF2).
      */
-    readonly keyDerivation: IKeyDerivationParams;
+    readonly keyDerivation: IPbkdf2KeyDerivationParams;
 }
 
 /**
@@ -2297,6 +2894,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 +2917,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 +2936,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 +2984,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 +3008,80 @@ 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;
+}
+
+/**
+ * PBKDF2 key derivation parameters.
+ * @public
+ */
+declare interface IPbkdf2KeyDerivationParams {
+    /** Key derivation function discriminator. */
+    readonly kdf: 'pbkdf2';
+    /** Base64-encoded salt used for key derivation. */
+    readonly salt: string;
+    /** Number of iterations used for key derivation. */
+    readonly iterations: number;
+}
+
 /**
  * Pluggable backend that persists raw asymmetric private keys outside of the
  * encrypted keystore vault. Concrete implementations live in platform-specific
@@ -2452,10 +3142,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 +3155,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 +3207,10 @@ declare interface IProviderCompletionStreamParams {
      * dispatcher; auth shape is unaffected.
      */
     readonly endpoint?: string;
+    /**
+     * Optional thinking/reasoning mode configuration.
+     */
+    readonly thinking?: IThinkingConfig;
 }
 
 /**
@@ -2542,13 +3230,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 +3251,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 +3283,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 +3347,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 +3457,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
@@ -2826,7 +3592,7 @@ declare const jsonWebKeyShape: Validator<JsonWebKey>;
  * Supported key derivation functions.
  * @public
  */
-declare type KeyDerivationFunction = 'pbkdf2';
+declare type KeyDerivationFunction = 'pbkdf2' | 'argon2id';
 
 /**
  * Converter for {@link CryptoUtils.KeyDerivationFunction | key derivation function} type.
@@ -2836,6 +3602,7 @@ declare const keyDerivationFunction: Converter<KeyDerivationFunction>;
 
 /**
  * Converter for {@link CryptoUtils.IKeyDerivationParams | key derivation parameters}.
+ * Handles both PBKDF2 and Argon2id discriminated union arms.
  * @public
  */
 declare const keyDerivationParams: Converter<IKeyDerivationParams>;
@@ -2914,6 +3681,7 @@ declare namespace KeyStore {
         IAddSecretFromPasswordOptions,
         DEFAULT_SECRET_ITERATIONS,
         IAddSecretFromPasswordResult,
+        IAddSecretFromPasswordArgon2idOptions,
         IAddKeyPairOptions,
         IAddKeyPairResult,
         IRemoveSecretResult,
@@ -3150,6 +3918,36 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * @public
      */
     verifySecretFromPassword(name: string, password: string, keyDerivation: IKeyDerivationParams): Promise<Result<boolean>>;
+    /**
+     * Adds a secret derived from a password using Argon2id (RFC 9106).
+     *
+     * The Argon2id provider must be supplied explicitly; the KeyStore does not
+     * hold one by default (consumers opt in by depending on the argon2 package).
+     *
+     * Returns the key derivation parameters so callers can store them alongside
+     * encrypted artifacts, enabling future re-derivation and verification.
+     *
+     * @param name - Unique name for the secret
+     * @param password - Password or passphrase
+     * @param argon2idProvider - Argon2id provider (Node or Browser implementation)
+     * @param options - Optional: Argon2id params (defaults to ARGON2ID_OWASP_MIN), description, replace flag
+     * @returns Success with entry and keyDerivation params, Failure if locked or invalid
+     * @public
+     */
+    addSecretFromPasswordArgon2id(name: string, password: string, argon2idProvider: IArgon2idProvider, options?: IAddSecretFromPasswordArgon2idOptions): Promise<Result<IAddSecretFromPasswordResult>>;
+    /**
+     * Verifies a candidate password against an Argon2id-derived entry using the
+     * supplied key derivation parameters. Constant-time comparison.
+     *
+     * @param name - Name of the secret to verify against
+     * @param password - Candidate password to test
+     * @param argon2idProvider - Argon2id provider (must produce bit-identical output for identical inputs)
+     * @param keyDerivation - The Argon2id key derivation parameters returned by `addSecretFromPasswordArgon2id`
+     * @returns Success(true) if candidate matches stored key, Success(false) if not,
+     * Failure if locked, secret missing, wrong type, or derivation fails
+     * @public
+     */
+    verifySecretFromPasswordArgon2id(name: string, password: string, argon2idProvider: IArgon2idProvider, keyDerivation: IArgon2idKeyDerivationParams): Promise<Result<boolean>>;
     /**
      * Removes a secret by name. Vault-first: the in-memory vault entry is dropped
      * before any storage cleanup runs. For asymmetric-keypair entries, best-effort
@@ -3467,7 +4265,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}.
@@ -3702,6 +4500,45 @@ declare class NodeCryptoProvider implements ICryptoProvider {
      * @returns `Success` with the imported public `CryptoKey`, or `Failure` with error context.
      */
     importPublicKeySpki(spkiBytes: Uint8Array, algorithm: KeyPairAlgorithm): Promise<Result<CryptoKey>>;
+    /**
+     * Signs `data` with `privateKey` using the algorithm inferred from the key.
+     * @param privateKey - A signing `CryptoKey` (`'ecdsa-p256'` or `'ed25519'`).
+     * @param data - The bytes to sign.
+     * @returns `Success` with the raw signature bytes, or `Failure` with error context.
+     */
+    sign(privateKey: CryptoKey, data: Uint8Array): Promise<Result<Uint8Array>>;
+    /**
+     * Verifies a signature produced by {@link NodeCryptoProvider.sign}.
+     * @param publicKey - A verify `CryptoKey` (`'ecdsa-p256'` or `'ed25519'`).
+     * @param signature - The raw signature bytes.
+     * @param data - The original data that was signed.
+     * @returns `Success` with `true` if valid, `false` if not, or `Failure` with error context.
+     */
+    verify(publicKey: CryptoKey, signature: Uint8Array, data: Uint8Array): Promise<Result<boolean>>;
+    /**
+     * Compares two byte arrays in constant time using Node's native
+     * `crypto.timingSafeEqual`. Returns `false` for mismatched lengths
+     * rather than throwing (Node's native throws on length mismatch).
+     * @param a - First byte array.
+     * @param b - Second byte array.
+     * @returns `true` if lengths match and all bytes are equal, `false` otherwise.
+     */
+    timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;
+    /**
+     * Computes an HMAC-SHA256 MAC for `data` using `key`.
+     * @param key - An HMAC `CryptoKey` with `'sign'` usage.
+     * @param data - The bytes to authenticate.
+     * @returns `Success` with the 32-byte MAC, or `Failure` with error context.
+     */
+    hmacSha256(key: CryptoKey, data: Uint8Array): Promise<Result<Uint8Array>>;
+    /**
+     * Verifies an HMAC-SHA256 MAC in constant time.
+     * @param key - An HMAC `CryptoKey` with `'sign'` usage.
+     * @param signature - The MAC bytes to verify.
+     * @param data - The original data that was authenticated.
+     * @returns `Success` with `true` if valid, `false` if not, or `Failure` with error context.
+     */
+    verifyHmacSha256(key: CryptoKey, signature: Uint8Array, data: Uint8Array): Promise<Result<boolean>>;
     /**
      * Wraps `plaintext` for the holder of `recipientPublicKey` using
      * ECIES (ECDH P-256 + HKDF-SHA256 + AES-GCM-256). See
@@ -3729,6 +4566,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.
@@ -3748,6 +4591,12 @@ declare function parseCsvString(body: string, options?: CsvOptions): Result<unkn
  */
 declare function parseRecordJarLines(lines: string[], options?: JarRecordParserOptions): Result<JarRecord[]>;
 
+/**
+ * Converter for {@link CryptoUtils.IPbkdf2KeyDerivationParams | PBKDF2 key derivation parameters}.
+ * @public
+ */
+declare const pbkdf2KeyDerivationParams: Converter<IPbkdf2KeyDerivationParams>;
+
 /**
  * Simple implementation of a possibly open-ended range of some comparable
  * type `<T>` with test and formatting.
@@ -3966,6 +4815,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 +4926,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,