@fgv/ts-extras 5.1.0-4 → 5.1.0-40

package/dist/ts-extras.d.ts

@@ -1,10 +1,15 @@
+import { Brand } from '@fgv/ts-utils';
 import { Conversion } from '@fgv/ts-utils';
 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 { JsonSchema } from '@fgv/ts-json-base';
 import { JsonValue } from '@fgv/ts-json-base';
 import { Logging } from '@fgv/ts-utils';
 import { Result } from '@fgv/ts-utils';
+import { Uuid } from '@fgv/ts-utils';
 import { Validator } from '@fgv/ts-utils';
 
 /**
@@ -22,41 +27,151 @@ declare type AiApiFormat = 'openai' | 'anthropic' | 'gemini';
 declare namespace AiAssist {
     export {
         AiPrompt,
+        AiModelCapability,
+        allModelCapabilities,
         AiProviderId,
         AiServerToolType,
         AiServerToolConfig,
+        AiToolConfig,
         IAiWebSearchToolConfig,
+        IAiClientToolConfig,
+        IAiToolAnnotations,
+        IAiClientTool,
+        IAiClientToolCallSummary,
+        IAiClientToolContinuation,
+        IAiClientToolTurnResult,
         IAiToolEnablement,
         IAiCompletionResponse,
         IChatMessage,
+        IChatRequest,
         AiApiFormat,
+        AiImageApiFormat,
+        AiEmbeddingApiFormat,
+        AiEmbeddingTaskType,
+        IAiEmbeddingModelCapability,
+        IAiEmbeddingParams,
+        IAiEmbeddingUsage,
+        IAiEmbeddingResult,
+        IAiImageModelCapability,
         IAiProviderDescriptor,
         IAiAssistProviderConfig,
         IAiAssistSettings,
         DEFAULT_AI_ASSIST,
         IAiAssistKeyStore,
+        IAiImageAttachment,
+        IAiImageData,
+        AiImageSize,
+        AiImageQuality,
+        GptImageSize,
+        GptImageQuality,
+        GptImageModelNames,
+        GrokImagineModelNames,
+        GeminiFlashImageModelNames,
+        IGptImageGenerationConfig,
+        IGrokImagineImageGenerationConfig,
+        IGeminiFlashImageGenerationConfig,
+        IGptImageModelOptions,
+        IGrokImagineModelOptions,
+        IGeminiFlashImageModelOptions,
+        IOtherModelOptions,
+        IModelFamilyConfig,
+        IAiImageGenerationOptions,
+        IAiImageGenerationParams,
+        IAiGeneratedImage,
+        IAiImageGenerationResponse,
+        IAiModelCapabilityRule,
+        IAiModelCapabilityConfig,
+        IAiModelInfo,
+        IAiStreamEvent,
+        IAiStreamTextDelta,
+        IAiStreamToolEvent,
+        IAiStreamToolUseStart,
+        IAiStreamToolUseDelta,
+        IAiStreamToolUseComplete,
+        IAiStreamDone,
+        IAiStreamError,
         ModelSpec,
         ModelSpecKey,
         IModelSpecMap,
         allModelSpecKeys,
         MODEL_SPEC_BASE_KEY,
         resolveModel,
+        IModelAliasMap,
+        MODEL_ALIAS_SIGIL,
+        resolveModelAlias,
+        resolveProviderModel,
+        isResponsesOnlyModel,
+        toDataUrl,
+        AiThinkingMode,
+        IThinkingConfig,
+        IThinkingProviderConfig,
+        IAnthropicThinkingOptions,
+        IOpenAiThinkingOptions,
+        IGeminiThinkingOptions,
+        IXAiThinkingOptions,
+        IOtherThinkingOptions,
+        IAnthropicThinkingConfig,
+        IOpenAiThinkingConfig,
+        IGeminiThinkingConfig,
+        IXAiThinkingConfig,
+        AnthropicThinkingModelNames,
+        OpenAiThinkingModelNames,
+        GeminiThinkingModelNames,
+        XAiThinkingModelNames,
+        IResolvedImageOptions,
+        resolveImageOptions,
+        validateResolvedOptions,
         allProviderIds,
         getProviderDescriptors,
         getProviderDescriptor,
+        resolveImageCapability,
+        supportsImageGeneration,
+        resolveEmbeddingCapability,
+        supportsEmbedding,
+        DEFAULT_MODEL_CAPABILITY_CONFIG,
         callProviderCompletion,
         callProxiedCompletion,
+        callProviderImageGeneration,
+        callProxiedImageGeneration,
+        callProviderListModels,
+        callProxiedListModels,
         IProviderCompletionParams,
+        IProviderImageGenerationParams,
+        IProviderListModelsParams,
+        callProviderEmbedding,
+        callProxiedEmbedding,
+        IProviderEmbeddingParams,
+        callProviderCompletionStream,
+        callProxiedCompletionStream,
+        IProviderCompletionStreamParams,
+        executeClientToolTurn,
+        IExecuteClientToolTurnParams,
+        IExecuteClientToolTurnResult,
+        IToolExecutionDecision,
         aiProviderId,
         aiServerToolType,
         aiWebSearchToolConfig,
         aiServerToolConfig,
+        aiToolAnnotations,
+        aiClientToolConfig,
         aiToolEnablement,
         aiAssistProviderConfig,
         aiAssistSettings,
         modelSpecKey,
         modelSpec,
-        resolveEffectiveTools
+        resolveEffectiveTools,
+        extractJsonText,
+        fencedStringifiedJson,
+        IFencedStringifiedJsonExtractorOptions,
+        IFencedStringifiedJsonOptions,
+        JsonTextExtractor,
+        generateJsonCompletion,
+        SMART_JSON_PROMPT_HINT,
+        IGenerateJsonCompletionParams,
+        IGenerateJsonCompletionResult,
+        JsonPromptHint,
+        anthropicEffortToBudgetTokens,
+        IResolvedThinkingConfig
     }
 }
 export { AiAssist }
@@ -73,6 +188,86 @@ declare const aiAssistProviderConfig: Converter<IAiAssistProviderConfig>;
  */
 declare const aiAssistSettings: Converter<IAiAssistSettings>;
 
+/**
+ * Converter for {@link AiAssist.IAiClientToolConfig}. Validates the wrapper shape: `type`,
+ * `name`, `description`, the presence of a usable `parametersSchema`, and optional
+ * host-advisory `annotations`.
+ * Does not inspect the inner JSON Schema structure — `JsonSchema.object(...)` already
+ * guarantees the schema is valid.
+ * @public
+ */
+declare const aiClientToolConfig: Converter<IAiClientToolConfig>;
+
+/**
+ * API format categories for embedding provider routing.
+ *
+ * @remarks
+ * - `'openai-embeddings'` — OpenAI `/v1/embeddings` shape. Serves OpenAI,
+ *   Ollama (via `/v1`), openai-compat self-hosted servers (vLLM, LM Studio,
+ *   llama.cpp's openai-server), and Mistral (`mistral-embed`) — all of which
+ *   speak the same request/response shape.
+ * - `'gemini-embeddings'` — Google Gemini `:batchEmbedContents` endpoint. A
+ *   genuinely divergent shape (different route, auth header, request body, and
+ *   the `taskType` retrieval-asymmetry knob that has no OpenAI analog).
+ *
+ * Named with the `ApiFormat` suffix for symmetry with `AiApiFormat` and
+ * `AiImageApiFormat`.
+ *
+ * @public
+ */
+declare type AiEmbeddingApiFormat = 'openai-embeddings' | 'gemini-embeddings';
+
+/**
+ * A single embedding task-type hint (Gemini-style). Cross-provider; providers
+ * that don't support task typing ignore it (logged, not failed). Open string
+ * union so new Gemini task types don't force a churn, with the known set
+ * enumerated for ergonomics.
+ *
+ * @remarks
+ * Values are the kebab-case cross-provider form; the Gemini adapter maps them to
+ * `SCREAMING_SNAKE_CASE` on the wire (e.g. `'retrieval-document'` →
+ * `RETRIEVAL_DOCUMENT`).
+ *
+ * @public
+ */
+declare type AiEmbeddingTaskType = 'retrieval-query' | 'retrieval-document' | 'semantic-similarity' | 'classification' | 'clustering' | 'code-retrieval-query' | 'question-answering' | 'fact-verification' | (string & {});
+
+/**
+ * API format categories for image-generation provider routing.
+ *
+ * @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. 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-image-out'` — Google Gemini chat-style `:generateContent`
+ *   endpoint that returns image parts (Gemini Flash Image / "Nano
+ *   Banana"). Accepts reference images.
+ *
+ * @public
+ */
+declare type AiImageApiFormat = 'openai-images' | 'xai-images' | 'xai-images-edits' | 'gemini-image-out';
+
+/** All accepted quality strings across all providers. @public */
+declare type AiImageQuality = GptImageQuality;
+
+/** All accepted image size strings across all providers. @public */
+declare type AiImageSize = GptImageSize;
+
+/**
+ * Capability vocabulary used to describe what a model can do. Used as both
+ * a filter and as a tag in {@link AiAssist.IAiModelInfo.capabilities}.
+ *
+ * @remarks
+ * Adding a new capability is cheap; adding the *first* one after consumers
+ * already exist forces churn. The initial vocabulary is intentionally broad
+ * even though only `image-generation` is fully exercised today.
+ *
+ * @public
+ */
+declare type AiModelCapability = 'chat' | 'tools' | 'vision' | 'image-generation' | 'thinking' | 'embedding';
+
 /**
  * A structured AI prompt with system/user split for direct API calls,
  * and a lazily-constructed combined version for copy/paste workflows.
@@ -83,16 +278,35 @@ declare class AiPrompt {
     readonly system: string;
     /** User request: the specific entity generation request. */
     readonly user: string;
-    constructor(user: string, system: string);
-    /** Combined single-string version (user + system joined) for copy/paste. */
+    /**
+     * Optional image attachments. When present, vision-capable providers will
+     * include them in the user message; non-vision providers will reject the
+     * call up front (see {@link AiAssist.IAiProviderDescriptor.acceptsImageInput}).
+     */
+    readonly attachments: ReadonlyArray<IAiImageAttachment>;
+    constructor(user: string, system: string, attachments?: ReadonlyArray<IAiImageAttachment>);
+    /**
+     * Combined single-string version (user + system joined) for copy/paste.
+     * When attachments are present, includes a sentinel noting they aren't
+     * part of the copied text.
+     */
     get combined(): string;
+    /**
+     * Lowers this prompt to the unified {@link AiAssist.IChatRequest} shape consumed
+     * by the turn entry points (`callProviderCompletion`,
+     * `callProviderCompletionStream`, `generateJsonCompletion`,
+     * `executeClientToolTurn`). The prompt becomes a single current `user` turn
+     * (carrying any attachments) with the system instructions in the distinct
+     * `system` field.
+     */
+    toRequest(): IChatRequest;
 }
 
 /**
  * All known AI provider identifiers.
  * @public
  */
-declare type AiProviderId = 'copy-paste' | 'xai-grok' | 'openai' | 'anthropic' | 'google-gemini' | 'groq' | 'mistral';
+declare type AiProviderId = 'copy-paste' | 'xai-grok' | 'openai' | 'openai-compat' | 'anthropic' | 'google-gemini' | 'groq' | 'mistral' | 'ollama';
 
 /**
  * Converter for {@link AiProviderId}.
@@ -124,6 +338,25 @@ 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 AiAssist.IAiToolAnnotations} — the five optional host-advisory hints.
+ * @public
+ */
+declare const aiToolAnnotations: Converter<IAiToolAnnotations>;
+
+/**
+ * Union of all tool configurations: server-side or client-defined.
+ * Discriminated on `type`.
+ * @public
+ */
+declare type AiToolConfig = AiServerToolConfig | IAiClientToolConfig;
+
 /**
  * Converter for {@link IAiToolEnablement}.
  * @public
@@ -136,12 +369,37 @@ declare const aiToolEnablement: Converter<IAiToolEnablement>;
  */
 declare const aiWebSearchToolConfig: Converter<IAiWebSearchToolConfig>;
 
+/**
+ * All valid key pair algorithms.
+ * @public
+ */
+declare const allKeyPairAlgorithms: ReadonlyArray<KeyPairAlgorithm>;
+
+/**
+ * All valid asymmetric secret types.
+ * @public
+ */
+declare const allKeyStoreAsymmetricSecretTypes: ReadonlyArray<KeyStoreAsymmetricSecretType>;
+
 /**
  * All valid key store secret types.
  * @public
  */
 declare const allKeyStoreSecretTypes: ReadonlyArray<KeyStoreSecretType>;
 
+/**
+ * All valid symmetric secret types.
+ * @public
+ */
+declare const allKeyStoreSymmetricSecretTypes: ReadonlyArray<KeyStoreSymmetricSecretType>;
+
+/**
+ * All valid `AiModelCapability` values — the single source of truth for
+ * the capability vocabulary (used by validators and capability filters).
+ * @public
+ */
+declare const allModelCapabilities: ReadonlyArray<AiModelCapability>;
+
 /**
  * All valid {@link ModelSpecKey} values.
  * @public
@@ -154,6 +412,49 @@ declare const allModelSpecKeys: ReadonlyArray<ModelSpecKey>;
  */
 declare const allProviderIds: ReadonlyArray<AiProviderId>;
 
+/**
+ * Maps Anthropic effort level to the `thinking.budget_tokens` integer that the
+ * Anthropic API requires when `thinking.type === 'enabled'`.
+ *
+ * Policy: low = 2048, medium = 8192, high = 24000, max = 32000. The lower three
+ * align with the Anthropic-published minimum-meaningful budget, a mid-range
+ * default, and a "deep thinking" allotment respectively. `max` targets Opus 4.6's
+ * deepest budget and stays within typical model limits.
+ *
+ * @public
+ */
+declare function anthropicEffortToBudgetTokens(effort: NonNullable<IAnthropicThinkingConfig['effort']>): number;
+
+/**
+ * Model IDs for Anthropic thinking-capable models.
+ *
+ * @remarks
+ * Only thinking-capable lines are listed. The non-tier `@anthropic:haiku` / `@anthropic:fable`
+ * aliases (reachable via `modelOverride` only) are deliberately omitted — they are not
+ * documented as thinking-capable, so naming them in a thinking-model filter would be misleading.
+ * @public
+ */
+declare type AnthropicThinkingModelNames = 'claude-sonnet-4-5' | 'claude-sonnet-4-6' | 'claude-sonnet-5' | 'claude-opus-4-6' | 'claude-opus-4-7' | 'claude-opus-4-8';
+
+/**
+ * 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
@@ -161,39 +462,169 @@ declare const allProviderIds: ReadonlyArray<AiProviderId>;
 declare const base64String: Converter<string>;
 
 /**
- * Calls the appropriate chat completion API for a given provider.
+ * Decodes a base64url (no-padding) string (RFC 4648 §5) back to a `Uint8Array`.
+ *
+ * This is the bare primitive with no multibase prefix; use
+ * {@link CryptoUtils.multibaseBase64UrlDecode} to decode a multibase-`'m'`-prefixed value.
+ *
+ * @param encoded - The base64url-no-pad body to decode.
+ * @returns `Success` with the decoded bytes, or `Failure` with error context.
+ * @public
+ */
+declare function base64UrlNoPadDecode(encoded: string): Result<Uint8Array>;
+
+/**
+ * Encodes a `Uint8Array` as a base64url (no-padding) string (RFC 4648 §5).
+ *
+ * The body uses the base64url alphabet (`+` → `-`, `/` → `_`) and trailing `=`
+ * padding is stripped. This is the bare primitive with no multibase prefix; use
+ * {@link CryptoUtils.multibaseBase64UrlEncode} when a multibase-`'m'`-prefixed value is required.
+ *
+ * @param data - The binary data to encode.
+ * @returns The base64url-no-pad string.
+ * @public
+ */
+declare function base64UrlNoPadEncode(data: Uint8Array): string;
+
+/**
+ * Calls the appropriate chat completion API for a given provider. Routes by
+ * `apiFormat`: `'openai'` (xAI/OpenAI/Groq/Mistral — switches to Responses API
+ * when tools are set), `'anthropic'`, or `'gemini'`.
+ * @public
+ */
+declare function callProviderCompletion(params: IProviderCompletionParams): Promise<Result<IAiCompletionResponse>>;
+
+/**
+ * Calls the appropriate streaming 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
+ * @remarks
+ * Pre-flight rejection: when `descriptor.streamingCorsRestricted === true`
+ * and the call isn't being routed through a proxy, this returns
+ * `Result.fail` before fetch is invoked. Callers should route through
+ * {@link AiAssist.callProxiedCompletionStream} or surface the failure to the user.
  *
- * 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
+ * Connection-time failures (auth, network, non-2xx) surface as the outer
+ * `Result.fail`. Once iteration begins, errors mid-stream surface as a
+ * terminal error event ({@link AiAssist.IAiStreamError}) followed by the iterable
+ * ending. The final successful event is {@link AiAssist.IAiStreamDone}.
  *
  * @param params - Request parameters including descriptor, API key, prompt, and optional tools
- * @returns The completion response with content and truncation status, or a failure
+ * @returns A streaming iterable of unified events, or a Result.fail
  * @public
  */
-declare function callProviderCompletion(params: IProviderCompletionParams): Promise<Result<IAiCompletionResponse>>;
+declare function callProviderCompletionStream(params: IProviderCompletionStreamParams): Promise<Result<AsyncIterable<IAiStreamEvent>>>;
 
 /**
- * Calls the AI completion endpoint on a proxy server instead of calling
- * the provider API directly from the browser.
+ * Calls the appropriate embedding API for a given provider. Routes by the
+ * `format` of the resolved {@link AiAssist.IAiEmbeddingModelCapability}:
+ * `'openai-embeddings'` or `'gemini-embeddings'`.
  *
- * The proxy server handles provider dispatch, CORS, and API key forwarding.
- * The request shape mirrors {@link IProviderCompletionParams} but is serialized
- * as JSON for the proxy endpoint.
+ * @remarks
+ * - Rejects up front when the provider declares no embedding capability, when no
+ *   embedding model resolves, or when the batch exceeds the capability's
+ *   `maxBatchSize` (no auto-chunking).
+ * - An empty `input` array short-circuits to an empty result with no wire call
+ *   (most providers HTTP-400 on empty input).
+ * - Caller-supplied `dimensions`/`taskType` that the model doesn't support are a
+ *   no-op (logged), not a failure (design §7).
  *
- * @param proxyUrl - Base URL of the proxy server (e.g. `http://localhost:3001`)
+ * @param params - Request parameters including descriptor, API key, and input.
+ * @returns The embedding vectors aligned to input order, or a failure.
+ * @public
+ */
+declare function callProviderEmbedding(params: IProviderEmbeddingParams): Promise<Result<IAiEmbeddingResult>>;
+
+/**
+ * Calls the appropriate image-generation API for a given provider. Routes by the
+ * `format` field of the resolved {@link IAiImageModelCapability}:
+ * `'openai-images'`, `'xai-images'`, `'xai-images-edits'`, 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
+ * @public
+ */
+declare function callProviderImageGeneration(params: IProviderImageGenerationParams): Promise<Result<IAiImageGenerationResponse>>;
+
+/**
+ * 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 (descriptor, API key, optional capability filter)
+ * @public
+ */
+declare function callProviderListModels(params: IProviderListModelsParams): Promise<Result<ReadonlyArray<IAiModelInfo>>>;
+
+/**
+ * Calls the AI completion endpoint on a proxy server instead of calling the
+ * provider API directly from the browser. The proxy handles provider dispatch,
+ * CORS, and API key forwarding. The request body serializes the unified
+ * {@link AiAssist.IChatRequest} shape (`system?` + `messages`). Enforces the same
+ * non-empty / trailing-user-turn and image-input invariants as the direct path.
+ * @param proxyUrl - Base URL of the proxy server
  * @param params - Same parameters as {@link callProviderCompletion}
- * @returns The completion response, or a failure
  * @public
  */
 declare function callProxiedCompletion(proxyUrl: string, params: IProviderCompletionParams): Promise<Result<IAiCompletionResponse>>;
 
+/**
+ * Calls the streaming chat endpoint on a proxy server instead of calling
+ * the provider directly from the browser.
+ *
+ * @remarks
+ * Proxy contract:
+ * - Endpoint: `POST ${proxyUrl}/api/ai/completion-stream`
+ * - Request body: same JSON as `/api/ai/completion` plus `"stream": true`
+ * - Response: `Content-Type: text/event-stream`; body is the unified
+ *   {@link AiAssist.IAiStreamEvent} JSON-serialized one event per SSE `data:` line
+ *   (no `event:` line needed since the type discriminator is in the JSON).
+ * - Error response (when the proxy can't even start): JSON `{error: string}`
+ *   with a non-2xx status, surfaced as `proxy: ${error}`.
+ *
+ * The proxy server is responsible for opening the upstream SSE connection,
+ * translating provider-native events to the unified vocabulary, and
+ * forwarding events as they arrive (no buffering). The library does not
+ * ship a proxy implementation.
+ *
+ * @public
+ */
+declare function callProxiedCompletionStream(proxyUrl: string, params: IProviderCompletionStreamParams): Promise<Result<AsyncIterable<IAiStreamEvent>>>;
+
+/**
+ * Calls the embedding endpoint on a proxy server instead of calling the provider
+ * API directly from the browser. Endpoint: `POST ${proxyUrl}/api/ai/embedding`.
+ * Request body: `{ providerId, apiKey, params, modelOverride? }`. The proxy
+ * handles descriptor lookup, model/capability resolution, and provider dispatch.
+ * 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 AiAssist.callProviderEmbedding}.
+ * @returns The embedding result, or a failure.
+ * @public
+ */
+declare function callProxiedEmbedding(proxyUrl: string, params: IProviderEmbeddingParams): Promise<Result<IAiEmbeddingResult>>;
+
+/**
+ * Calls the image-generation endpoint on a proxy server instead of calling
+ * the provider API directly from the browser.
+ * 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
+ * @param params - Same parameters as {@link callProviderImageGeneration}
+ * @public
+ */
+declare function callProxiedImageGeneration(proxyUrl: string, params: IProviderImageGenerationParams): Promise<Result<IAiImageGenerationResponse>>;
+
+/**
+ * Calls the model-listing endpoint on a proxy server. 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>>>;
+
 declare namespace Constants {
     export {
         ENCRYPTED_FILE_FORMAT,
@@ -210,7 +641,8 @@ declare namespace Converters {
         extendedArrayOf,
         rangeTypeOf,
         rangeOf,
-        isoDate
+        isoDate,
+        isoDateTime
     }
 }
 export { Converters }
@@ -219,6 +651,12 @@ declare namespace Converters_2 {
     export {
         keystoreFormat,
         keystoreSecretType,
+        keystoreSymmetricSecretType,
+        keystoreAsymmetricSecretType,
+        keyPairAlgorithm,
+        jsonWebKeyShape,
+        keystoreSymmetricEntryJson,
+        keystoreAsymmetricEntryJson,
         keystoreSecretEntryJson,
         keystoreVaultContents,
         keystoreFile
@@ -232,8 +670,11 @@ declare namespace Converters_3 {
         encryptedFileFormat,
         encryptedFileErrorMode,
         keyDerivationFunction,
+        pbkdf2KeyDerivationParams,
+        argon2idKeyDerivationParams,
         keyDerivationParams,
         base64String,
+        multibaseSpkiPublicKey,
         uint8ArrayFromBase64,
         namedSecret,
         encryptedFile
@@ -271,6 +712,8 @@ declare namespace CryptoUtils {
         Converters_3 as Converters,
         DirectEncryptionProvider,
         IDirectEncryptionProviderParams,
+        IKeyPairAlgorithmParams,
+        keyPairAlgorithmParams,
         NodeCryptoProvider,
         nodeCryptoProvider,
         createEncryptedFile,
@@ -279,13 +722,34 @@ declare namespace CryptoUtils {
         ICreateEncryptedFileParams,
         toBase64,
         tryDecryptFile,
+        base64UrlNoPadDecode,
+        base64UrlNoPadEncode,
+        exportPublicKeyAsMultibaseSpki,
+        importPublicKeyFromMultibaseSpki,
+        isValidMultibaseSpkiPublicKey,
+        MultibaseSpkiPublicKeyRegExp,
+        multibaseBase64UrlDecode,
+        multibaseBase64UrlEncode,
+        HpkeProvider,
+        IHpkeSealResult,
         isEncryptedFile,
+        MultibaseSpkiPublicKey,
         EncryptionAlgorithm,
         EncryptedFileFormat,
         INamedSecret,
         IEncryptionResult,
+        KeyPairAlgorithm,
+        IWrapBytesOptions,
+        IWrappedBytes,
+        allKeyPairAlgorithms,
         KeyDerivationFunction,
+        IPbkdf2KeyDerivationParams,
+        IArgon2idKeyDerivationParams,
         IKeyDerivationParams,
+        IArgon2idParams,
+        ARGON2ID_OWASP_MIN,
+        ARGON2ID_PASSPHRASE,
+        IArgon2idProvider,
         IEncryptedFile,
         ICryptoProvider,
         IEncryptionProvider,
@@ -299,9 +763,9 @@ export { CryptoUtils }
 declare namespace Csv {
     export {
         parseCsvString,
+        readCsvFromTree,
         CsvOptions,
-        readCsvFileSync,
-        readCsvFromTree
+        readCsvFileSync
     }
 }
 export { Csv }
@@ -345,6 +809,16 @@ declare const DEFAULT_ALGORITHM: "AES-256-GCM";
  */
 declare const DEFAULT_KEYSTORE_ITERATIONS: number;
 
+/**
+ * Default capability config used by `callProviderListModels` when callers
+ * don't supply their own. Patterns are intentionally narrow — false
+ * positives are worse than missing a model. Caller can override per call
+ * via {@link IProviderListModelsParams.capabilityConfig}.
+ *
+ * @public
+ */
+declare const DEFAULT_MODEL_CAPABILITY_CONFIG: IAiModelCapabilityConfig;
+
 /**
  * Default {@link Experimental.RangeOfFormats | formats} to use for both
  * open-ended and complete {@link Experimental.RangeOf | RangeOf<T>}.
@@ -441,6 +915,115 @@ declare type EncryptedFileFormat = typeof Constants.ENCRYPTED_FILE_FORMAT;
  */
 declare const encryptedFileFormat: Converter<EncryptedFileFormat>;
 
+/**
+ * {@link CryptoUtils.KeyStore.IPrivateKeyStorage | IPrivateKeyStorage}
+ * implementation that persists each private key as its own AES-256-GCM-encrypted
+ * file in a directory. The file content is the key's JWK, encrypted with a
+ * consumer-supplied 32-byte key via the supplied
+ * {@link CryptoUtils.ICryptoProvider | crypto provider}.
+ *
+ * `supportsNonExtractable` is `false`: persisting to disk requires exporting the
+ * private key to JWK, which only works for `extractable: true` keys. The
+ * keystore generates extractable keys when a backend reports `false` here.
+ *
+ * I/O goes through the {@link FileTree.FileTree | FileTree} abstraction (default
+ * `FsTree`), so the same implementation works against an in-memory tree (tests)
+ * or any other Node-compatible backend.
+ *
+ * This backend is **Node-only**: it round-trips private keys through
+ * `node:crypto` (`crypto.webcrypto.subtle`), so it is intentionally excluded
+ * from the browser entry point. Browser consumers should use
+ * `IdbPrivateKeyStorage` from `@fgv/ts-web-extras` instead.
+ *
+ * Single-process assumption: there is no inter-process locking. Concurrent
+ * writers to the same directory may race.
+ *
+ * @public
+ */
+declare class EncryptedFilePrivateKeyStorage implements IPrivateKeyStorage {
+    /**
+     * `false` — disk persistence round-trips via JWK, which requires extractable
+     * keys.
+     */
+    readonly supportsNonExtractable: false;
+    private readonly _directory;
+    private readonly _encryptionKey;
+    private readonly _cryptoProvider;
+    private constructor();
+    /**
+     * Creates a new {@link CryptoUtils.KeyStore.EncryptedFilePrivateKeyStorage}.
+     * @param params - {@link CryptoUtils.KeyStore.IEncryptedFilePrivateKeyStorageCreateParams}.
+     * @returns `Success` with the new instance, or `Failure` if the encryption
+     * key is the wrong size or the storage directory cannot be opened.
+     */
+    static create(params: IEncryptedFilePrivateKeyStorageCreateParams): Result<EncryptedFilePrivateKeyStorage>;
+    /**
+     * Stores `key` under `id` as an encrypted JWK file.
+     * @param id - Storage handle. Must be a safe filename token
+     * (`[A-Za-z0-9._-]+`, not `.`/`..`).
+     * @param key - The extractable private `CryptoKey` to persist.
+     */
+    store(id: string, key: CryptoKey): Promise<Result<string>>;
+    /**
+     * Loads the private key stored under `id`, decrypting and re-importing it from
+     * JWK.
+     * @param id - Storage handle.
+     */
+    load(id: string): Promise<Result<CryptoKey>>;
+    /**
+     * Deletes the entry stored under `id`. Missing ids fail (the read path is
+     * keystore-driven and never asks to delete an id it did not store).
+     * @param id - Storage handle.
+     */
+    delete(id: string): Promise<Result<string>>;
+    /**
+     * Lists every stored id.
+     */
+    list(): Promise<Result<readonly string[]>>;
+    private _fileNameFor;
+    /**
+     * Validates the synchronous preconditions for a store: the id is filename-safe,
+     * the key is actually a private key, and its algorithm is one we support.
+     * Returns the resolved filename and algorithm so the async pipeline can run
+     * without re-deriving them.
+     */
+    private _validateKeyToStore;
+    /**
+     * Exports `key` to JWK, wraps it in the stored envelope, encrypts it with
+     * AES-256-GCM, and writes the resulting file as serialized JSON to `fileName`.
+     * Returns the stored `id` on success.
+     */
+    private _encryptAndWrite;
+    private _algorithmOf;
+    private _findFile;
+    private _writeFile;
+    /**
+     * Reads `file`, decrypts the AES-256-GCM envelope, and validates it into the
+     * typed `IStoredPrivateKeyEnvelope`. Read, decrypt, and shape failures
+     * all surface as a decrypt failure for `id`.
+     */
+    private _decryptEnvelope;
+    /**
+     * Parses and shape-validates the stored JWK, then re-imports it as a private
+     * `CryptoKey` for the envelope's algorithm. The WebCrypto JWK-import algorithm
+     * descriptor is shared between public and private keys for every supported
+     * algorithm, so `IKeyPairAlgorithmParams.importPublicKey` is reused here;
+     * the public/private distinction is carried by the requested `usages`.
+     */
+    private _importPrivateKey;
+    /**
+     * Computes the key usages to request when re-importing a stored private key.
+     * WebCrypto rejects `importKey` if the requested usages include operations
+     * absent from the JWK's `key_ops`, so a key originally created with a narrower
+     * usage set than the algorithm default (e.g. an ECDH key with only
+     * `deriveBits`) would fail to load against the algorithm-wide defaults.
+     * Intersect the algorithm's private usages with the JWK's recorded `key_ops`
+     * so we request exactly the operations the stored key actually supports;
+     * fall back to the algorithm's private usages when `key_ops` is absent.
+     */
+    private _importUsagesFor;
+}
+
 /**
  * Supported encryption algorithms.
  * @public
@@ -453,6 +1036,29 @@ declare type EncryptionAlgorithm = typeof Constants.DEFAULT_ALGORITHM;
  */
 declare const encryptionAlgorithm: Converter<EncryptionAlgorithm>;
 
+/**
+ * Orchestrates a single client-tool streaming turn for any supported provider.
+ *
+ * Starts a streaming request, iterates the underlying provider stream, and:
+ * - Forwards `text-delta`, `tool-event`, `client-tool-call-start`, and
+ *   `client-tool-call-done` events through to the consumer.
+ * - For each `client-tool-call-done` event: validates the raw args against the
+ *   tool's `parametersSchema`, invokes `execute(typedArgs)`, and emits a
+ *   `client-tool-result` event.
+ * - After stream completion: builds the per-provider continuation (or
+ *   `{ continuation: undefined }` when no tool calls occurred) and resolves
+ *   `nextTurn`.
+ *
+ * **Anthropic constraint (E3):** The continuation for Anthropic does not set
+ * a forced `tool_choice`. Only `tool_choice: 'auto'` (the default, i.e.
+ * omitted) is compatible with extended thinking.
+ *
+ * @param params - Turn parameters
+ * @returns `{ events, nextTurn }` — stream iterable + completion promise
+ * @public
+ */
+declare function executeClientToolTurn(params: IExecuteClientToolTurnParams): Result<IExecuteClientToolTurnResult>;
+
 declare namespace Experimental {
     export {
         ExtendedArray,
@@ -471,6 +1077,20 @@ declare namespace Experimental {
 }
 export { Experimental }
 
+/**
+ * Exports a public `CryptoKey` as a multibase base64url-encoded SPKI blob.
+ *
+ * The SPKI (SubjectPublicKeyInfo) format is the standard DER-encoded structure
+ * for public keys defined in RFC 5280, RFC 5480, and RFC 8410. It is
+ * algorithm-agnostic and suitable for storage and transmission.
+ *
+ * @param key - The `CryptoKey` to export. Must have `key.type === 'public'`.
+ * @param provider - The {@link CryptoUtils.ICryptoProvider} to use for the export operation.
+ * @returns `Success` with the multibase SPKI string, or `Failure` with error context.
+ * @public
+ */
+declare function exportPublicKeyAsMultibaseSpki(key: CryptoKey, provider: ICryptoProvider): Promise<Result<MultibaseSpkiPublicKey>>;
+
 /**
  * An experimental array template which extend built-in `Array` to include a handful
  * of predicates which return `Result<T>`.
@@ -532,11 +1152,59 @@ declare class ExtendedArray<T> extends Array<T> {
  * If `onError` is `'failOnError'` (default), then the entire conversion fails if any element cannot
  * be converted.  If `onError` is `'ignoreErrors'`, then failing elements are silently ignored.
  * @param converter - `Converter` used to convert each item in the array
- * @param ignoreErrors - Specifies treatment of unconvertible elements
+ * @param onError - Specifies treatment of unconvertible elements
  * @beta
  */
 declare function extendedArrayOf<T, TC = undefined>(label: string, converter: Converter<T, TC>, onError?: Conversion.OnError): Converter<ExtendedArray<T>, TC>;
 
+/**
+ * Default {@link AiAssist.JsonTextExtractor | extractor} for LLM responses. Tolerates:
+ *
+ * - Leading/trailing whitespace and a leading byte-order mark.
+ * - Markdown code fences (with or without a language tag).
+ * - Conversational preamble before the first `{` or `[`.
+ * - Trailing prose after the matched closing `}` or `]`.
+ *
+ * Out of scope: repairing malformed JSON, handling smart quotes, etc.
+ *
+ * @param text - Raw model output.
+ * @returns A `Result<string>` containing the JSON-shaped substring, or a
+ * `Failure` if no JSON-shaped substring was found.
+ * @public
+ */
+declare const extractJsonText: JsonTextExtractor;
+
+/**
+ * Creates a `Converter` that accepts raw LLM response text, runs it through a
+ * tolerant extractor (default: {@link AiAssist.extractJsonText}), parses the
+ * extracted substring as JSON, and applies an optional inner converter or
+ * validator.
+ *
+ * @example
+ * ```ts
+ * const converter = fencedStringifiedJson({ inner: myShapeConverter });
+ * const result = converter.convert(llmText); // Result<MyShape>
+ * ```
+ *
+ * @param options - Optional extractor; omit to keep the default. Without an
+ * `inner` step, the converter resolves to the parsed `JsonValue`.
+ * @returns A `Converter<JsonValue>`.
+ * @public
+ */
+declare function fencedStringifiedJson(options?: IFencedStringifiedJsonExtractorOptions): Converter<JsonValue>;
+
+/**
+ * Creates a `Converter` that accepts raw LLM response text, runs it through a
+ * tolerant extractor (default: {@link AiAssist.extractJsonText}), parses the
+ * extracted substring as JSON, and applies the supplied inner converter or
+ * validator.
+ *
+ * @param options - Required `inner` converter/validator and optional extractor.
+ * @returns A `Converter<T>`.
+ * @public
+ */
+declare function fencedStringifiedJson<T>(options: IFencedStringifiedJsonOptions<T>): Converter<T>;
+
 /**
  * Formats a list of items using the supplied template and formatter, one result
  * per output line.
@@ -628,6 +1296,36 @@ 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-3.1-flash-image-preview';
+
+/**
+ * Model IDs for Google Gemini thinking-capable models.
+ * @public
+ */
+declare type GeminiThinkingModelNames = 'gemini-3.1-pro-preview' | 'gemini-3.5-flash' | 'gemini-3.1-flash-lite';
+
+/**
+ * Calls {@link AiAssist.callProviderCompletion}, then runs the response text
+ * through a tolerant JSON converter (default:
+ * {@link AiAssist.fencedStringifiedJson}) and the caller's
+ * `converter`/`validator`. Returns the validated value plus the raw text and
+ * underlying completion response for diagnostics.
+ *
+ * @remarks
+ * The default smart prompt hint asks the model to emit raw JSON. The read-side
+ * extractor still tolerates fences and prose, so models that ignore the hint
+ * are still handled.
+ *
+ * Either `converter` or `jsonConverter` must be provided; passing both lets
+ * `jsonConverter` win.
+ *
+ * @param params - Provider parameters plus JSON validation options.
+ * @returns The validated value, the raw text, and the underlying response.
+ * @public
+ */
+declare function generateJsonCompletion<T>(params: IGenerateJsonCompletionParams<T>): Promise<Result<IGenerateJsonCompletionResult<T>>>;
+
 /**
  * Get a provider descriptor by id.
  * @param id - The provider identifier
@@ -643,6 +1341,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' | 'gpt-image-1.5';
+
+/** 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
@@ -651,20 +1361,212 @@ declare namespace Hash {
 export { Hash }
 
 /**
- * Options for adding a secret derived from a password.
+ * 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 interface IAddSecretFromPasswordOptions extends IAddSecretOptions {
+declare class HpkeProvider {
+    private readonly _subtle;
+    private constructor();
     /**
-     * Whether to replace an existing secret with the same name.
+     * 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.
      */
-    readonly replace?: boolean;
+    static create(subtle: SubtleCrypto): Result<HpkeProvider>;
     /**
-     * PBKDF2 iterations for key derivation.
-     * @defaultValue DEFAULT_SECRET_ITERATIONS (350000)
-     */
-    readonly iterations?: number;
-}
+     * 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
+ */
+declare interface IAddKeyPairOptions {
+    /**
+     * Algorithm to use for the new keypair.
+     */
+    readonly algorithm: KeyPairAlgorithm;
+    /**
+     * Optional description for the entry.
+     */
+    readonly description?: string;
+    /**
+     * Whether to replace an existing entry with the same name.
+     * Replacement mints a fresh storage `id` and best-effort deletes the
+     * displaced storage blob; see the keystore design doc for details.
+     */
+    readonly replace?: boolean;
+    /**
+     * Overrides the storage-backend-derived extractability for this key only.
+     * Omit to keep the default (`!privateKeyStorage.supportsNonExtractable`).
+     * A value the backend cannot honor fails loudly rather than silently
+     * downgrading.
+     */
+    readonly extractable?: boolean;
+}
+
+/**
+ * Result of adding an asymmetric keypair to the key store.
+ * @public
+ */
+declare interface IAddKeyPairResult {
+    /**
+     * The asymmetric entry that was added.
+     */
+    readonly entry: IKeyStoreAsymmetricEntry;
+    /**
+     * Whether this replaced an existing entry.
+     */
+    readonly replaced: boolean;
+    /**
+     * Best-effort warning from displaced-resource cleanup. Set when this call
+     * replaced a prior entry but the corresponding
+     * {@link CryptoUtils.KeyStore.IPrivateKeyStorage}.delete failed; the new
+     * keypair is still committed and the orphaned blob is left for consumer-side
+     * GC to reconcile.
+     */
+    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
+ */
+declare interface IAddSecretFromPasswordOptions extends IAddSecretOptions {
+    /**
+     * Whether to replace an existing secret with the same name.
+     */
+    readonly replace?: boolean;
+    /**
+     * PBKDF2 iterations for key derivation.
+     * @defaultValue DEFAULT_SECRET_ITERATIONS (350000)
+     */
+    readonly iterations?: number;
+}
 
 /**
  * Result of adding a password-derived secret.
@@ -700,11 +1602,19 @@ declare interface IAddSecretResult {
     /**
      * The secret entry that was added.
      */
-    readonly entry: IKeyStoreSecretEntry;
+    readonly entry: IKeyStoreSymmetricEntry;
     /**
      * Whether this replaced an existing secret.
      */
     readonly replaced: boolean;
+    /**
+     * Best-effort warning from displaced-resource cleanup. Set when this call
+     * replaced an asymmetric-keypair entry but the corresponding
+     * {@link CryptoUtils.KeyStore.IPrivateKeyStorage}.delete failed; the new
+     * entry is still committed and the orphaned blob is left for consumer-side
+     * GC to reconcile.
+     */
+    readonly warning?: string;
 }
 
 /**
@@ -734,6 +1644,14 @@ declare interface IAiAssistProviderConfig {
     readonly model?: ModelSpec;
     /** Tool enablement/configuration. Tools are disabled unless explicitly enabled. */
     readonly tools?: ReadonlyArray<IAiToolEnablement>;
+    /**
+     * Optional caller-supplied endpoint URL (http/https). Overrides
+     * `descriptor.baseUrl` for this provider. Used to point a provider at a
+     * self-hosted server (Ollama, LM Studio, llama.cpp's openai-server) or a
+     * local proxy. Validation lives in `@fgv/ts-extras` — query strings,
+     * fragments, and userinfo are rejected.
+     */
+    readonly endpoint?: string;
 }
 
 /**
@@ -751,6 +1669,145 @@ declare interface IAiAssistSettings {
     readonly proxyAllProviders?: boolean;
 }
 
+/**
+ * A client-defined tool: configuration + execution callback pair.
+ *
+ * @remarks
+ * The `execute` callback receives typed `TParams` (already validated by
+ * `config.parametersSchema.validate()`) and returns a `Promise<Result<unknown>>`.
+ * Thrown errors are caught via `captureAsyncResult` in the round-trip helper.
+ *
+ * @public
+ */
+declare interface IAiClientTool<TParams = unknown> {
+    /** The tool's configuration (name, description, parameters schema). */
+    readonly config: IAiClientToolConfig<TParams>;
+    /**
+     * Execute the tool with validated parameters.
+     * @param args - Typed arguments, already validated against `config.parametersSchema`.
+     * @returns A `Promise<Result<unknown>>` — the result is stringified and sent back to the model.
+     */
+    readonly execute: (args: TParams) => Promise<Result<unknown>>;
+}
+
+/**
+ * Summary of a single client tool call within a turn: the tool name, call ID,
+ * raw arguments, execution result, and whether the execution was an error.
+ * @public
+ */
+declare interface IAiClientToolCallSummary {
+    /** The name of the tool that was called. */
+    readonly toolName: string;
+    /** Provider-assigned call identifier (absent for Gemini). */
+    readonly callId?: string;
+    /** The fully accumulated raw arguments object as parsed JSON. */
+    readonly args: JsonObject;
+    /** The stringified result (success value or error message). */
+    readonly result: string;
+    /** Whether execution failed (schema validation failure, execute error, or unknown tool). */
+    readonly isError: boolean;
+}
+
+/**
+ * Configuration for a client-defined (harness-supplied) tool.
+ *
+ * @remarks
+ * The `parametersSchema` is the single source of truth for both the wire-format
+ * JSON Schema sent to the provider (via `.toJson()`) and the runtime argument
+ * validation (via `.validate(rawArgs)`). Use `JsonSchema.object(...)` from
+ * `@fgv/ts-json-base` to author the schema as a const (e.g. `const mySchema = JsonSchema.object({...})`);
+ * the static type `TParams` is then derived via `JsonSchema.Static<typeof mySchema>` —
+ * no drift between wire schema and runtime validation.
+ *
+ * @public
+ */
+declare interface IAiClientToolConfig<TParams = unknown> {
+    /** Discriminator — always `'client_tool'`. */
+    readonly type: 'client_tool';
+    /** Tool name sent to the model (must be unique within a call). */
+    readonly name: string;
+    /** Human-readable description of what the tool does, shown to the model. */
+    readonly description: string;
+    /**
+     * JSON Schema validator for the tool's parameters. Emits wire format via
+     * `.toJson()` and validates model-returned args via `.validate(rawArgs)`.
+     */
+    readonly parametersSchema: JsonSchema.ISchemaValidator<TParams>;
+    /**
+     * Optional host-advisory behavior annotations (read-only / destructive /
+     * idempotent / open-world hints + display title). Consumed by the host's
+     * tool loop; never serialized to the model. See {@link IAiToolAnnotations}.
+     */
+    readonly annotations?: IAiToolAnnotations;
+}
+
+/**
+ * The provider-specific continuation data needed to build the follow-up request
+ * for the next round of the conversation.
+ *
+ * @remarks
+ * `messages` are provider-native request objects (Anthropic: content-block arrays,
+ * OpenAI Responses API: input items, Gemini: content parts). The continuation
+ * builder in `clientToolContinuationBuilder.ts` populates this.
+ *
+ * @public
+ */
+declare interface IAiClientToolContinuation {
+    /**
+     * **Cumulative** provider-native wire-format message objects covering all
+     * tool rounds so far. On each turn, `executeClientToolTurn` prepends the
+     * inbound `continuationMessages` so that this array always contains the
+     * complete wire tail from round 1 through the current round.
+     *
+     * To drive a multi-round loop, simply **replace** `continuationMessages`
+     * with this value — do not manually concatenate:
+     *
+     * ```ts
+     * let tail: JsonObject[] | undefined;
+     * while (true) {
+     *   const { events, nextTurn } = executeClientToolTurn({
+     *     ..., continuationMessages: tail
+     *   }).orThrow();
+     *   for await (const e of events) { /* observe *\/ }
+     *   const outcome = (await nextTurn).orThrow();
+     *   if (!outcome.continuation) break;
+     *   tail = [...outcome.continuation.messages]; // replace — already cumulative
+     * }
+     * ```
+     *
+     * The exact shape is provider-native and may include provider-specific
+     * blocks (e.g. Anthropic thinking/redacted_thinking/tool_use, OpenAI
+     * function_call/function_call_output items, Gemini functionCall/functionResponse
+     * parts). These are NOT `IChatMessage[]` and must NOT be placed in the
+     * `messages` parameter — the normalized-message path strips provider-native
+     * fields (thinking signatures, redacted_thinking data) that the server
+     * requires for continuation validation.
+     *
+     * `toolCallsSummary` is per-round only (the calls executed in the current
+     * turn). Only `messages` is cumulative.
+     */
+    readonly messages: ReadonlyArray<JsonObject>;
+    /** Summary of each tool call executed in this turn (per-round, not cumulative). */
+    readonly toolCallsSummary: ReadonlyArray<IAiClientToolCallSummary>;
+}
+
+/**
+ * The result of a single client-tool turn: the optional continuation for the next
+ * call (absent when no tool calls occurred) and whether the stream was truncated.
+ * @public
+ */
+declare interface IAiClientToolTurnResult {
+    /**
+     * The continuation data for the next round-trip. `undefined` when the model
+     * completed without invoking any client tools.
+     */
+    readonly continuation: IAiClientToolContinuation | undefined;
+    /** Whether the stream was truncated (token limit or stop reason). */
+    readonly truncated: boolean;
+    /** The full concatenated text from all `text-delta` events in this turn. */
+    readonly fullText: string;
+}
+
 /**
  * Result of an AI provider completion call.
  * @public
@@ -762,6 +1819,317 @@ declare interface IAiCompletionResponse {
     readonly truncated: boolean;
 }
 
+/**
+ * Embedding capability for a model family within a provider. Used as an entry
+ * in {@link IAiProviderDescriptor.embedding}.
+ *
+ * @public
+ */
+declare interface IAiEmbeddingModelCapability {
+    /**
+     * Prefix matched against the resolved embedding model id. The empty string is
+     * the catch-all and matches every model. When multiple rules' prefixes match
+     * a model id, the longest prefix wins; ties are broken by first-encountered.
+     */
+    readonly modelPrefix: string;
+    /** API format used to dispatch requests for matching models. */
+    readonly format: AiEmbeddingApiFormat;
+    /**
+     * Whether matching models honor a requested output `dimensions`
+     * (OpenAI `text-embedding-3-*`, Gemini `gemini-embedding-001` via MRL
+     * truncation). When false/undefined, a caller-supplied `dimensions` is a
+     * no-op (logged, not failed — see {@link AiAssist.IAiEmbeddingParams}).
+     */
+    readonly supportsDimensions?: boolean;
+    /**
+     * Whether matching models honor a `taskType` hint (Gemini only today). When
+     * false/undefined, a caller-supplied `taskType` is a no-op (logged, not
+     * failed).
+     */
+    readonly supportsTaskType?: boolean;
+    /** Native fixed output dimension, when the model has one (metadata only). */
+    readonly defaultDimensions?: number;
+    /**
+     * Maximum number of inputs accepted per request. When present, the dispatcher
+     * rejects batches larger than this up front (no auto-chunking in v1).
+     */
+    readonly maxBatchSize?: number;
+}
+
+/**
+ * Parameters for an embedding request. Batch is the norm: `input` accepts a
+ * single string or an array; the result always exposes a vector array aligned
+ * by index to the input.
+ *
+ * @public
+ */
+declare interface IAiEmbeddingParams {
+    /** One or more input strings. A bare string is treated as a single-element batch. */
+    readonly input: string | ReadonlyArray<string>;
+    /**
+     * Requested output dimensionality. Honored only by models whose capability
+     * declares `supportsDimensions` (OpenAI `text-embedding-3-*`, Gemini
+     * `gemini-embedding-001` via MRL truncation). Ignored — with a `logger.info`
+     * note — by models that don't.
+     */
+    readonly dimensions?: number;
+    /**
+     * Task-type hint. Mapped to Gemini `taskType`; a no-op (with a `logger.info`
+     * note) on OpenAI/Ollama/compat/Mistral. Preserves Gemini's
+     * query-vs-document retrieval asymmetry.
+     */
+    readonly taskType?: AiEmbeddingTaskType;
+}
+
+/**
+ * Result of an embedding call. `vectors[i]` is the embedding for `input[i]`,
+ * in request order.
+ *
+ * @remarks
+ * Vectors are plain `number[]` (not `Float32Array`) for JSON-wire fidelity and
+ * validator-friendliness — consumers who want a typed array call
+ * `Float32Array.from(vector)` at the vector-store / WebGPU boundary. The
+ * library does not L2-normalize; Gemini's MRL truncation (when
+ * `dimensions < native`) returns un-normalized vectors that the consumer should
+ * normalize if their similarity metric requires it.
+ *
+ * @public
+ */
+declare interface IAiEmbeddingResult {
+    /** One vector per input, aligned by index to the request order. */
+    readonly vectors: ReadonlyArray<ReadonlyArray<number>>;
+    /** The resolved provider-native model id that produced the vectors. */
+    readonly model: string;
+    /** Dimensionality of each returned vector (`vectors[0].length`; `0` for empty input). */
+    readonly dimensions: number;
+    /** Token usage, when the provider reports it (OpenAI-format; absent for Gemini). */
+    readonly usage?: IAiEmbeddingUsage;
+}
+
+/**
+ * Token-usage accounting for an embedding call, when the provider reports it.
+ * @public
+ */
+declare interface IAiEmbeddingUsage {
+    /** Tokens consumed by the input(s). */
+    readonly promptTokens?: number;
+    /** Total tokens billed. */
+    readonly totalTokens?: number;
+}
+
+/**
+ * A single generated image.
+ * @public
+ */
+declare interface IAiGeneratedImage extends IAiImageData {
+    /**
+     * The prompt as rewritten by the provider, if any. OpenAI's image models
+     * commonly rewrite prompts; other providers do not.
+     */
+    readonly revisedPrompt?: string;
+}
+
+/**
+ * Image attachment for a vision (image-input) prompt.
+ *
+ * @remarks
+ * Extends {@link IAiImageData} with an OpenAI-specific `detail` hint that is
+ * silently ignored by Anthropic, Gemini, and other providers.
+ *
+ * @public
+ */
+declare interface IAiImageAttachment extends IAiImageData {
+    /**
+     * OpenAI vision detail hint:
+     * - `'low'`: faster, cheaper, lower fidelity
+     * - `'high'`: slower, more expensive, higher fidelity
+     * - `'auto'` (default): provider chooses
+     *
+     * Ignored by providers other than OpenAI.
+     */
+    readonly detail?: 'low' | 'high' | 'auto';
+}
+
+/**
+ * Universal image representation used for both image input (vision prompts)
+ * and image output (generation responses).
+ *
+ * @remarks
+ * The base64 string is raw — no `data:` URL prefix. Use {@link AiAssist.toDataUrl} to
+ * format it for browser-display contexts.
+ *
+ * @public
+ */
+declare interface IAiImageData {
+    /** MIME type, e.g. `'image/png'`, `'image/jpeg'`, `'image/webp'`. */
+    readonly mimeType: string;
+    /** Base64-encoded image bytes (no `data:` prefix). */
+    readonly base64: string;
+}
+
+/**
+ * Options for image generation requests.
+ *
+ * @remarks
+ * 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 for OpenAI models (mapped to `size` field).
+     * For xAI or Gemini Flash aspect ratio, use the corresponding `models` family block.
+     */
+    readonly size?: AiImageSize;
+    /** Number of images. Default 1. Some models enforce a maximum. */
+    readonly count?: number;
+    /**
+     * Quality tier. Accepted values differ per model:
+     * - gpt-image-1: 'low' | 'medium' | 'high' | 'auto'
+     * Other models ignore this field.
+     */
+    readonly quality?: AiImageQuality;
+    /** Reproducibility seed, where supported. */
+    readonly seed?: number;
+    /**
+     * Optional precision via model-family-scoped blocks. The resolver picks
+     * applicable blocks dynamically based on the resolved model.
+     */
+    readonly models?: ReadonlyArray<IModelFamilyConfig>;
+}
+
+/**
+ * Parameters for an image-generation request.
+ * @public
+ */
+declare interface IAiImageGenerationParams {
+    /** The text prompt describing the desired image. */
+    readonly prompt: string;
+    /** Optional generation options. */
+    readonly options?: IAiImageGenerationOptions;
+    /**
+     * Optional reference images. When present, the provider will use them as
+     * visual context (e.g. to preserve a character's appearance across multiple
+     * generations). The dispatcher resolves the
+     * {@link AiAssist.IAiImageModelCapability} for the requested model and
+     * rejects the call up front if `acceptsImageReferenceInput` is not set on
+     * the matching capability. An empty array is treated identically to
+     * `undefined`.
+     */
+    readonly referenceImages?: ReadonlyArray<IAiImageAttachment>;
+}
+
+/**
+ * Result of an image-generation call.
+ * @public
+ */
+declare interface IAiImageGenerationResponse {
+    /** The generated images, in provider-returned order. */
+    readonly images: ReadonlyArray<IAiGeneratedImage>;
+}
+
+/**
+ * Image-generation capability for a model family within a provider. Used as
+ * an entry in {@link IAiProviderDescriptor.imageGeneration}.
+ *
+ * @public
+ */
+declare interface IAiImageModelCapability {
+    /**
+     * Prefix matched against the resolved image model id. The empty string is
+     * the catch-all and matches every model. When multiple rules' prefixes
+     * match a model id, the longest prefix wins; ties are broken by
+     * first-encountered.
+     */
+    readonly modelPrefix: string;
+    /** API format used to dispatch requests for matching models. */
+    readonly format: AiImageApiFormat;
+    /**
+     * Whether matching models accept reference images via
+     * {@link AiAssist.IAiImageGenerationParams.referenceImages}. When false or
+     * undefined, calls that include reference images are rejected up front.
+     */
+    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' (openai-images catch-all)
+     * - 'output-format': send output_format (gpt-image-1)
+     * - 'none': send neither (Gemini Flash)
+     */
+    readonly outputParamStyle?: 'response-format' | 'output-format' | 'none';
+    /** Default MIME type for response images. */
+    readonly defaultOutputMimeType?: string;
+}
+
+/**
+ * Configuration that maps model id patterns to capabilities. Used to
+ * augment (or, where the provider supplies no capability info, fully
+ * derive) the capability set for each listed model.
+ * @public
+ */
+declare interface IAiModelCapabilityConfig {
+    /** Per-provider rules. Tried before {@link AiAssist.IAiModelCapabilityConfig.global}. */
+    readonly perProvider?: {
+        readonly [P in AiProviderId]?: ReadonlyArray<IAiModelCapabilityRule>;
+    };
+    /** Cross-provider fallback rules. */
+    readonly global?: ReadonlyArray<IAiModelCapabilityRule>;
+}
+
+/**
+ * One rule in an {@link IAiModelCapabilityConfig}. Multiple rules can match
+ * a single model — their capability arrays are unioned.
+ * @public
+ */
+declare interface IAiModelCapabilityRule {
+    /** RegExp tested against the model id (using `.test`). */
+    readonly idPattern: RegExp;
+    /** Capabilities this rule attributes to matching models. */
+    readonly capabilities: ReadonlyArray<AiModelCapability>;
+    /**
+     * Friendly display-name override for matching models. The function form
+     * lets one rule format many ids (e.g. `(id) => id.toUpperCase()`).
+     * If multiple matching rules supply `displayName`, the first match wins.
+     */
+    readonly displayName?: string | ((id: string) => string);
+}
+
+/**
+ * Information about a single model returned by a provider's list endpoint,
+ * with capabilities already resolved (native + config rules).
+ * @public
+ */
+declare interface IAiModelInfo {
+    /** Provider-native model identifier. */
+    readonly id: string;
+    /** Resolved capability set — union of native declarations and config rules. */
+    readonly capabilities: ReadonlySet<AiModelCapability>;
+    /** Friendly name for display, when known. */
+    readonly displayName?: string;
+}
+
 /**
  * Describes a single AI provider — single source of truth for all metadata.
  * @public
@@ -781,10 +2149,264 @@ declare interface IAiProviderDescriptor {
     readonly baseUrl: string;
     /** Default model specification — string or context-aware map. */
     readonly defaultModel: ModelSpec;
+    /**
+     * Canonical fgv alias → concrete model map for this provider. Absent means the
+     * provider defines no aliases and every model string passes through verbatim.
+     *
+     * @remarks
+     * Keys are full fgv aliases (`@<providerId>:<role>`); values are the current
+     * concrete model id (or a provider-native alias). Consulted by
+     * {@link resolveModelAlias} / {@link resolveProviderModel} at each call-time
+     * resolution chokepoint, downstream of the {@link ModelSpecKey} walk. Additive
+     * and optional — composes with the existing per-descriptor `imageGeneration` /
+     * `embedding` capability arrays.
+     */
+    readonly aliases?: IModelAliasMap;
     /** Which server-side tools this provider supports (empty = none). */
     readonly supportedTools: ReadonlyArray<AiServerToolType>;
     /** Whether this provider's API enforces CORS restrictions that prevent direct browser calls. */
     readonly corsRestricted: boolean;
+    /**
+     * Whether this provider's streaming completion endpoint requires a proxy
+     * for direct browser calls. Some providers gate streaming separately from
+     * non-streaming (rare), so this is tracked independently from
+     * {@link IAiProviderDescriptor.corsRestricted}.
+     *
+     * @remarks
+     * When `true`, `callProviderCompletionStream` rejects up front unless the
+     * call is being routed through a proxy.
+     */
+    readonly streamingCorsRestricted: boolean;
+    /**
+     * Whether this provider's chat completions API accepts image input
+     * (i.e. supports vision prompts). When false, calls with
+     * `prompt.attachments` are rejected up front.
+     */
+    readonly acceptsImageInput: boolean;
+    /**
+     * 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.
+     *
+     * @remarks
+     * The dispatcher matches the resolved model id against each rule's
+     * `modelPrefix` and selects the longest match (see
+     * {@link AiAssist.resolveImageCapability}). An empty `modelPrefix` is the
+     * catch-all and matches every model id.
+     *
+     * Multiple entries support providers that host more than one image-API
+     * surface under one baseUrl. The dispatcher selects the longest-matching
+     * prefix, so a provider can list a specific-prefix surface alongside an
+     * empty-prefix catch-all and the right model routes to the right API.
+     *
+     * Image-model selection reuses the existing `image` {@link ModelSpecKey}.
+     * Providers that declare `imageGeneration` should declare a model in
+     * `defaultModel.image`, e.g. `{ base: '@openai:mini', image: '@openai:image' }`.
+     */
+    readonly imageGeneration?: ReadonlyArray<IAiImageModelCapability>;
+    /**
+     * Embedding capabilities, scoped to model id prefixes. Empty or undefined
+     * means the provider does not support embeddings.
+     *
+     * @remarks
+     * The dispatcher matches the resolved embedding model id against each rule's
+     * `modelPrefix` and selects the longest match (see
+     * {@link AiAssist.resolveEmbeddingCapability}). An empty `modelPrefix` is the
+     * catch-all and matches every model id.
+     *
+     * Embedding-model selection uses the `embedding` {@link ModelSpecKey}.
+     * Providers that declare `embedding` should declare a model in
+     * `defaultModel.embedding`, e.g. `{ base: '@openai:mini', embedding: '@openai:embedding' }`.
+     * Self-hosted providers (`ollama`, `openai-compat`) leave it unset — the
+     * caller supplies the embedding model via `modelOverride`.
+     */
+    readonly embedding?: ReadonlyArray<IAiEmbeddingModelCapability>;
+    /**
+     * Concrete model ids (prefix-matched) that must be invoked via the OpenAI
+     * Responses API rather than chat completions — e.g. `gpt-5.5-pro`. Non-OpenAI
+     * `apiFormat`s ignore this.
+     *
+     * @remarks
+     * Some current-generation OpenAI models (the `-pro` tier) are Responses-API-only
+     * and 400 on `/chat/completions`. The completion and streaming dispatch consult
+     * this list (via the sibling predicate {@link AiAssist.isResponsesOnlyModel})
+     * and route a matching model to the Responses path
+     * even when no tools are requested. Mirrors the prefix-matching shape of the
+     * `imageGeneration` / `embedding` capability arrays; adding a new Responses-only
+     * line is a one-entry descriptor edit. Empty or undefined means no model is
+     * Responses-only.
+     */
+    readonly responsesOnlyModelPrefixes?: ReadonlyArray<string>;
+}
+
+/**
+ * Terminal success event for a streaming completion. Carries the aggregated
+ * full text and truncation status for callers that want both the progressive
+ * UI and the complete result.
+ * @public
+ */
+declare interface IAiStreamDone {
+    readonly type: 'done';
+    /** Whether the response was truncated due to token limits. */
+    readonly truncated: boolean;
+    /** The full concatenated text from all `text-delta` events. */
+    readonly fullText: string;
+    /**
+     * Provider-reported reason a truncated response was cut short (e.g.
+     * `'max_output_tokens'`, `'content_filter'`), when the provider supplies one.
+     * Currently populated only by the OpenAI / xAI Responses adapter, from the
+     * completed payload's `incomplete_details.reason`. Meaningful only when
+     * `truncated === true`; `undefined` otherwise (and whenever the provider
+     * reports truncation without a reason).
+     */
+    readonly incompleteReason?: string;
+}
+
+/**
+ * Terminal failure event for a streaming completion. After this event no
+ * further events are emitted.
+ *
+ * @remarks
+ * Connection-time failures (auth, network, pre-flight CORS rejection) are
+ * surfaced via the outer `Result.fail` returned by
+ * `callProviderCompletionStream` rather than as an `error` event, so callers
+ * can distinguish "didn't start" from "started but errored mid-stream."
+ *
+ * @public
+ */
+declare interface IAiStreamError {
+    readonly type: 'error';
+    readonly message: string;
+}
+
+/**
+ * Discriminated union of events emitted by a streaming completion.
+ *
+ * @remarks
+ * **Exhaustive-switch consumers must handle all variants.** The three
+ * `client-tool-*` variants were added when client-tool support shipped;
+ * update every exhaustive switch over this union in lockstep.
+ *
+ * @public
+ */
+declare type IAiStreamEvent = IAiStreamTextDelta | IAiStreamToolEvent | IAiStreamToolUseStart | IAiStreamToolUseDelta | IAiStreamToolUseComplete | IAiStreamDone | IAiStreamError;
+
+/**
+ * A text-content delta arriving during a streaming completion.
+ * @public
+ */
+declare interface IAiStreamTextDelta {
+    readonly type: 'text-delta';
+    /** The newly arrived text fragment. */
+    readonly delta: string;
+}
+
+/**
+ * A server-side tool progress event arriving during a streaming completion.
+ * Surfaced for providers that emit explicit tool-progress markers (OpenAI
+ * Responses API, Anthropic). Gemini's grounding doesn't emit these.
+ * @public
+ */
+declare interface IAiStreamToolEvent {
+    readonly type: 'tool-event';
+    /** Which server-side tool this event describes. */
+    readonly toolType: AiServerToolType;
+    /** Tool lifecycle phase. */
+    readonly phase: 'started' | 'completed';
+    /**
+     * Optional provider-specific detail. For web_search this is typically the
+     * search query when available; format varies by provider.
+     */
+    readonly detail?: string;
+}
+
+/**
+ * Emitted after a client-defined tool has been executed and the result is ready
+ * to be fed back to the model in the round-trip continuation.
+ * @public
+ */
+declare interface IAiStreamToolUseComplete {
+    readonly type: 'client-tool-result';
+    /** The name of the client tool that was executed. */
+    readonly toolName: string;
+    /**
+     * Provider-assigned call identifier. Absent for Gemini.
+     */
+    readonly callId?: string;
+    /** The stringified result returned by the tool's execute callback. */
+    readonly result: string;
+    /** Whether the tool execution failed (schema validation failure, execute error, or unknown tool). */
+    readonly isError: boolean;
+}
+
+/**
+ * Emitted when a client-defined tool call is complete and its arguments are fully
+ * accumulated. The `args` object is the fully parsed JSON object — no further
+ * streaming deltas follow for this call.
+ * @public
+ */
+declare interface IAiStreamToolUseDelta {
+    readonly type: 'client-tool-call-done';
+    /** The name of the client tool being called. */
+    readonly toolName: string;
+    /**
+     * Provider-assigned call identifier. Absent for Gemini.
+     */
+    readonly callId?: string;
+    /** The fully accumulated and parsed tool arguments. */
+    readonly args: JsonObject;
+}
+
+/**
+ * Emitted when a client-defined tool call begins streaming. Carries the tool name
+ * and optional provider-assigned call ID (Anthropic / OpenAI Responses API; absent
+ * for Gemini which does not assign call IDs).
+ * @public
+ */
+declare interface IAiStreamToolUseStart {
+    readonly type: 'client-tool-call-start';
+    /** The name of the client tool being called. */
+    readonly toolName: string;
+    /**
+     * Provider-assigned call identifier (Anthropic: `toolu_*`; OpenAI: `call_*`).
+     * Absent for Gemini (correlation by name).
+     */
+    readonly callId?: string;
+}
+
+/**
+ * Behavior annotations for a client-defined tool.
+ *
+ * @remarks
+ * These are **host-advisory-only hints** describing a tool's side-effect profile.
+ * They are consumed by the host's tool loop (e.g. a before-execute gate) and are
+ * **never serialized to the model** — the provider wire tool-schemas whitelist
+ * `{name, description, parameters}` and ignore this field.
+ *
+ * Field names mirror MCP's `ToolAnnotations` (`@modelcontextprotocol/sdk`) 1:1 so
+ * an MCP tool's annotations pass through unchanged. Per the MCP spec, all fields
+ * are hints — a host should never make tool-use decisions based on annotations
+ * received from an untrusted server without its own validation.
+ *
+ * @public
+ */
+declare interface IAiToolAnnotations {
+    /** Optional human-readable display title for the tool. */
+    readonly title?: string;
+    /** Hint: the tool does not modify its environment (read-only). */
+    readonly readOnlyHint?: boolean;
+    /** Hint: the tool may perform destructive updates (only meaningful when not read-only). */
+    readonly destructiveHint?: boolean;
+    /** Hint: repeated calls with the same arguments have no additional effect. */
+    readonly idempotentHint?: boolean;
+    /** Hint: the tool interacts with an open world of external entities. */
+    readonly openWorldHint?: boolean;
 }
 
 /**
@@ -814,11 +2436,111 @@ declare interface IAiWebSearchToolConfig {
     /** Optional: max number of searches per request. */
     readonly maxUses?: number;
     /**
-     * Optional: enable image understanding during web search.
-     * When true, the model can view and analyze images found during search.
-     * Currently supported by xAI only; ignored by other providers.
+     * Optional: enable image understanding during web search.
+     * When true, the model can view and analyze images found during search.
+     * Currently supported by xAI only; ignored by other providers.
+     */
+    readonly enableImageUnderstanding?: boolean;
+}
+
+/**
+ * Anthropic-specific thinking configuration.
+ * @public
+ */
+declare interface IAnthropicThinkingConfig {
+    /**
+     * Anthropic effort level. The emit-site converts to `thinking.budget_tokens`
+     * (the integer budget the Anthropic API requires). Mapping policy: low = 2048,
+     * medium = 8192, high = 24000, max = 32000.
+     * - '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.
      */
-    readonly enableImageUnderstanding?: boolean;
+    argon2id(password: Uint8Array | string, salt: Uint8Array, params: IArgon2idParams): Promise<Result<Uint8Array>>;
 }
 
 /**
@@ -830,6 +2552,41 @@ declare interface IChatMessage {
     readonly role: 'system' | 'user' | 'assistant';
     /** Message content */
     readonly content: string;
+    /**
+     * Optional image attachments. Only honoured on the **current turn** (the last
+     * message of an {@link AiAssist.IChatRequest}); vision-capable providers include
+     * them in that user message, non-vision providers reject the call up front (see
+     * {@link AiAssist.IAiProviderDescriptor.acceptsImageInput}). Attachments on
+     * history (non-final) messages are ignored.
+     */
+    readonly attachments?: ReadonlyArray<IAiImageAttachment>;
+}
+
+/**
+ * An ordered chat request: optional system instructions plus the conversation
+ * turns. The **last** entry in `messages` is the current turn (always a `user`
+ * turn); everything before it is prior conversation history.
+ *
+ * @remarks
+ * This is the unified shape accepted by every turn entry point. Both the
+ * completion path and the client-tool turn path linearize it identically:
+ * `[system, ...history, current user turn, ...continuation]`. Keeping `system`
+ * as a distinct field (rather than a `system`-role message) matches how the
+ * per-provider request builders already separate system from the turn list
+ * (Anthropic top-level `system`, Gemini `systemInstruction`, OpenAI a leading
+ * `system`-role message). `messages` should therefore carry only `user` /
+ * `assistant` turns.
+ *
+ * @public
+ */
+declare interface IChatRequest {
+    /** System instructions (schema docs, format rules, general guidance). */
+    readonly system?: string;
+    /**
+     * The ordered conversation turns. Must be non-empty; the last entry is the
+     * current `user` turn and the preceding entries are history.
+     */
+    readonly messages: ReadonlyArray<IChatMessage>;
 }
 
 /**
@@ -937,12 +2694,27 @@ declare interface ICryptoProvider {
      * @returns Success with derived 32-byte key, or Failure with error
      */
     deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<Result<Uint8Array>>;
+    /**
+     * Computes a SHA-256 hash of the given data.
+     * @param data - UTF-8 string to hash
+     * @returns Success with hex-encoded hash string, or Failure with error
+     */
+    sha256(data: string): Promise<Result<string>>;
     /**
      * Generates cryptographically secure random bytes.
      * @param length - Number of bytes to generate
      * @returns Success with random bytes, or Failure with error
      */
     generateRandomBytes(length: number): Result<Uint8Array>;
+    /**
+     * Generates a cryptographically random UUIDv4 using the provider's
+     * underlying source of randomness. The default Node and browser
+     * implementations delegate to `globalThis.crypto.randomUUID`;
+     * deterministic providers (e.g. test stubs) may override to produce
+     * reproducible values.
+     * @returns Success with a canonical UUID, or Failure with error.
+     */
+    generateUuid(): Result<Uuid>;
     /**
      * Encodes binary data to base64 string.
      * @param data - Binary data to encode
@@ -955,6 +2727,161 @@ declare interface ICryptoProvider {
      * @returns Success with decoded bytes, or Failure if invalid base64
      */
     fromBase64(base64: string): Result<Uint8Array>;
+    /**
+     * Generates a new asymmetric keypair for the requested algorithm.
+     * @param algorithm - The {@link CryptoUtils.KeyPairAlgorithm | algorithm} to use.
+     * @param extractable - Whether the resulting `CryptoKey` objects may be exported.
+     * Set `false` on backends that store `CryptoKey` references directly (e.g.
+     * IndexedDB). Set `true` when the private key must round-trip through JWK or
+     * PKCS#8 (e.g. encrypted-file backends).
+     * @returns Success with the generated `CryptoKeyPair`, or Failure with error context.
+     */
+    generateKeyPair(algorithm: KeyPairAlgorithm, extractable: boolean): Promise<Result<CryptoKeyPair>>;
+    /**
+     * Exports the public half of a keypair as a JSON Web Key.
+     * @param publicKey - The public `CryptoKey` to export. Must be an `extractable`
+     * key generated for an asymmetric algorithm.
+     * @returns Success with the JWK, or Failure with error context.
+     */
+    exportPublicKeyJwk(publicKey: CryptoKey): Promise<Result<JsonWebKey>>;
+    /**
+     * Re-imports a public-key JWK as a `CryptoKey` usable for verification or
+     * encryption (depending on algorithm).
+     * @param jwk - The JSON Web Key produced by {@link CryptoUtils.ICryptoProvider.exportPublicKeyJwk | exportPublicKeyJwk}.
+     * @param algorithm - The {@link CryptoUtils.KeyPairAlgorithm | algorithm} the
+     * key was generated for. Determines the import parameters and key usages.
+     * @returns Success with the imported public `CryptoKey`, or Failure with error context.
+     */
+    importPublicKeyJwk(jwk: JsonWebKey, algorithm: KeyPairAlgorithm): Promise<Result<CryptoKey>>;
+    /**
+     * Exports a public `CryptoKey` as a DER-encoded SPKI (SubjectPublicKeyInfo) blob.
+     * SPKI is the standard algorithm-agnostic format for public key storage and transport.
+     * @param publicKey - The `CryptoKey` to export. Must have `key.type === 'public'`.
+     * @returns `Success` with the raw SPKI bytes, or `Failure` with error context.
+     */
+    exportPublicKeySpki(publicKey: CryptoKey): Promise<Result<Uint8Array>>;
+    /**
+     * Imports a public key from a DER-encoded SPKI blob.
+     * @param spkiBytes - The raw SPKI bytes produced by {@link CryptoUtils.ICryptoProvider.exportPublicKeySpki | exportPublicKeySpki}.
+     * @param algorithm - The {@link CryptoUtils.KeyPairAlgorithm | algorithm} the key was generated for.
+     * @returns `Success` with the imported public `CryptoKey`, or `Failure` with error context.
+     */
+    importPublicKeySpki(spkiBytes: Uint8Array, algorithm: KeyPairAlgorithm): Promise<Result<CryptoKey>>;
+    /**
+     * Wraps `plaintext` for delivery to the holder of the private key paired
+     * with `recipientPublicKey`. Uses ECIES with ECDH P-256, HKDF-SHA256, and
+     * AES-GCM-256.
+     *
+     * Generates a fresh ephemeral keypair per call; the ephemeral private key
+     * is discarded after the shared-secret derive. Only the recipient (with the
+     * matching private key) and the same HKDF parameters can recover
+     * `plaintext`.
+     *
+     * Empty `plaintext` is permitted; the resulting wrap contains only the
+     * 16-byte GCM authentication tag and round-trips back to an empty
+     * `Uint8Array`.
+     * @param plaintext - The bytes to wrap. Any length supported by AES-GCM
+     * (in practice, well below 2^39 - 256 bits).
+     * @param recipientPublicKey - The recipient's ECDH P-256 public `CryptoKey`.
+     * Must have algorithm name `'ECDH'` and named curve `'P-256'`; mismatched
+     * algorithm or curve yields a `Failure` with error context.
+     * @param options - HKDF parameters; see {@link CryptoUtils.IWrapBytesOptions | IWrapBytesOptions}.
+     * @returns `Success` with the wrapped payload, or `Failure` with error context.
+     */
+    wrapBytes(plaintext: Uint8Array, recipientPublicKey: CryptoKey, options: IWrapBytesOptions): Promise<Result<IWrappedBytes>>;
+    /**
+     * Inverse of {@link CryptoUtils.ICryptoProvider.wrapBytes | wrapBytes}.
+     * Recovers the original `plaintext` from a wrapped payload using the
+     * recipient's private key.
+     *
+     * Returns a `Failure` (never throws) on any of:
+     * - Tampered nonce or ciphertext (AES-GCM authentication fails)
+     * - Wrong private key (different shared secret derives a different wrap key)
+     * - Wrong HKDF parameters (different wrap key)
+     * - Malformed `ephemeralPublicKey` JWK
+     * - Malformed base64 in `nonce` or `ciphertext`
+     * @param wrapped - The wrapped payload produced by `wrapBytes`.
+     * @param recipientPrivateKey - The recipient's ECDH P-256 private
+     * `CryptoKey`. Must have algorithm name `'ECDH'` and named curve `'P-256'`,
+     * and key usages including `'deriveKey'` or `'deriveBits'`.
+     * @param options - The same HKDF parameters used at wrap time.
+     * @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>>;
 }
 
 /**
@@ -1021,6 +2948,42 @@ declare interface IEncryptedFile<TMetadata = JsonValue> {
     readonly keyDerivation?: IKeyDerivationParams;
 }
 
+/**
+ * Parameters for {@link CryptoUtils.KeyStore.EncryptedFilePrivateKeyStorage.create}.
+ * @public
+ */
+declare interface IEncryptedFilePrivateKeyStorageCreateParams {
+    /**
+     * Filesystem path to the directory that holds the encrypted private-key
+     * files. Used only when {@link CryptoUtils.KeyStore.IEncryptedFilePrivateKeyStorageCreateParams.tree}
+     * is omitted (the default `FsTree` backing). The directory must already
+     * exist.
+     */
+    readonly directory: string;
+    /**
+     * Raw AES-256-GCM key (32 bytes) used to encrypt each file's JWK content.
+     * Consumer-supplied and decoupled from the keystore's password lifecycle —
+     * derive it however the application sees fit (typically the same
+     * password-derived key material the keystore vault uses).
+     */
+    readonly encryptionKey: Uint8Array;
+    /**
+     * {@link CryptoUtils.ICryptoProvider | Crypto provider} used for the
+     * AES-256-GCM encrypt/decrypt of each file's contents.
+     */
+    readonly cryptoProvider: ICryptoProvider;
+    /**
+     * Optional {@link FileTree.IFileTreeDirectoryItem | FileTree directory}
+     * override. When supplied it is used as the storage directory directly and
+     * {@link CryptoUtils.KeyStore.IEncryptedFilePrivateKeyStorageCreateParams.directory} is ignored —
+     * pass an in-memory tree for tests, or another Node-compatible backend. When
+     * omitted, a mutable `FsTree` rooted at `directory` is used. (This backend is
+     * Node-only — it round-trips keys through `node:crypto` — so a browser file
+     * tree is not a supported target.)
+     */
+    readonly tree?: FileTree.IFileTreeDirectoryItem;
+}
+
 /**
  * Configuration for encrypted file handling during loading.
  * @public
@@ -1093,6 +3056,313 @@ declare interface IEncryptionResult {
     readonly encryptedData: Uint8Array;
 }
 
+/**
+ * Parameters for {@link AiAssist.executeClientToolTurn}.
+ *
+ * @remarks
+ * Carries the unified {@link AiAssist.IChatRequest} shape (`system?` + ordered
+ * `messages`): the last message is the current user turn and the preceding
+ * messages are history, linearized before the current turn — identically to the
+ * completion and streaming paths. {@link IExecuteClientToolTurnParams.continuationMessages}
+ * remains a distinct post-current-turn axis (see below).
+ *
+ * @public
+ */
+declare interface IExecuteClientToolTurnParams extends IChatRequest {
+    /** The provider descriptor for routing (Anthropic / OpenAI / Gemini). */
+    readonly descriptor: IAiProviderDescriptor;
+    /** API key for authentication. */
+    readonly apiKey: string;
+    /**
+     * The cumulative provider-native wire tail from the previous turn's
+     * {@link AiAssist.IAiClientToolContinuation.messages}. Supply this as-is
+     * each round — `messages` is already cumulative, so **replace** rather
+     * than manually concatenate:
+     *
+     * ```ts
+     * tail = outcome.continuation.messages; // replace — already cumulative
+     * ```
+     *
+     * On the first turn this should be `undefined` (or omitted).
+     *
+     * Each provider applies its own shape guard to the supplied wire objects:
+     * - Anthropic: projects each entry to `{ role, content }` (sufficient for
+     *   thinking blocks and `tool_result` arrays).
+     * - OpenAI / xAI Responses: passes each item verbatim (`function_call` /
+     *   `function_call_output` items carry distinct fields per `type`); only
+     *   guards that each entry is a JSON object.
+     * - Gemini: projects each entry to `{ role, parts }`.
+     *
+     * Entries that fail their provider's shape check are silently skipped.
+     * Do NOT place these objects in the `messages` parameter — the
+     * normalized-message path strips provider-native fields.
+     */
+    readonly continuationMessages?: ReadonlyArray<JsonObject>;
+    /**
+     * Sampling temperature. Sent to the provider only when explicitly provided; omitted otherwise
+     * so the provider's own default applies (current-gen models reject a caller-supplied default).
+     */
+    readonly temperature?: number;
+    /** Server-side tools to include. */
+    readonly tools?: ReadonlyArray<AiServerToolConfig>;
+    /** Client-defined tools available for the model to call. */
+    readonly clientTools: ReadonlyArray<IAiClientTool>;
+    /** Optional abort signal. */
+    readonly signal?: AbortSignal;
+    /**
+     * Optional override of the descriptor's default base URL. Same semantics as
+     * the non-streaming completion path and `callProviderCompletionStream`: a
+     * well-formed `http`/`https` URL is substituted for `descriptor.baseUrl`
+     * when composing the per-format request, with the per-format suffix appended
+     * unchanged. Validated at the dispatcher; auth shape is unaffected. Use this
+     * to point a client-tool turn at a local / LAN OpenAI-compatible server
+     * (Ollama, LM Studio, llama.cpp).
+     */
+    readonly endpoint?: string;
+    /** Optional logger for diagnostics. */
+    readonly logger?: Logging.ILogger;
+    /** Optional resolved thinking config (pre-resolved by the caller). */
+    readonly resolvedThinking?: IResolvedThinkingConfig;
+    /** Resolved model string (pre-resolved by the caller). When omitted, uses the descriptor's default model. */
+    readonly model?: string;
+    /**
+     * Optional host gate invoked for each client-tool call **after** the model's raw
+     * args have been validated against the tool's `parametersSchema` and **before**
+     * `tool.execute(...)` runs. The full `tool` (including `tool.config.annotations`)
+     * and the validated `args` are passed so gate logic can key off a tool's behavior
+     * annotations (e.g. deny a `destructiveHint` call pending confirmation).
+     *
+     * Returning `{ action: 'proceed' }` (or omitting the callback) runs `execute`
+     * normally. Returning `{ action: 'deny', reason }` skips `execute` and synthesizes
+     * a denial tool-result carrying `reason` into the continuation (the model sees the
+     * denial and can react); **the turn continues**. A callback that returns `Result.fail`
+     * or rejects is a hard error that **terminates the turn** (fails `nextTurn` + emits an
+     * inline `error` event) — distinct from a `tool.execute` failure, which continues the
+     * turn with an `isError` result. A deny must therefore be explicit.
+     */
+    readonly onBeforeToolExecute?: (tool: IAiClientTool, args: unknown) => Promise<Result<IToolExecutionDecision>>;
+}
+
+/**
+ * Return value of {@link AiAssist.executeClientToolTurn}.
+ * @public
+ */
+declare interface IExecuteClientToolTurnResult {
+    /**
+     * The unified-event iterable. Callers iterate this to drive the streaming UI.
+     * The iterable forwards `text-delta`, `tool-event`, `client-tool-call-start`,
+     * `client-tool-call-done`, and `client-tool-result` events through.
+     */
+    readonly events: AsyncIterable<IAiStreamEvent>;
+    /**
+     * Resolves when the stream terminates. On success, carries the
+     * {@link AiAssist.IAiClientToolTurnResult} with the optional continuation for the
+     * next round. On failure, carries the error message.
+     */
+    readonly nextTurn: Promise<Result<IAiClientToolTurnResult>>;
+}
+
+/**
+ * Options shared by every {@link AiAssist.fencedStringifiedJson} call.
+ * @public
+ */
+declare interface IFencedStringifiedJsonExtractorOptions {
+    /**
+     * Optional pre-parse extractor. Defaults to {@link AiAssist.extractJsonText}.
+     * Provide a custom extractor to handle response shapes the default does not
+     * understand.
+     */
+    readonly extractor?: JsonTextExtractor;
+}
+
+/**
+ * Options for the validating overload of {@link AiAssist.fencedStringifiedJson}.
+ * `inner` is required so the typed `Converter<T>` return value can never lie
+ * about the runtime shape.
+ * @public
+ */
+declare interface IFencedStringifiedJsonOptions<T> extends IFencedStringifiedJsonExtractorOptions {
+    /** Inner converter or validator applied to the parsed JSON value. */
+    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.
+ * @public
+ */
+declare interface IGenerateJsonCompletionParams<T> extends IProviderCompletionParams {
+    /**
+     * Caller-supplied `Converter<T>` or `Validator<T>` applied to the parsed
+     * JSON value. Wrapped internally in {@link AiAssist.fencedStringifiedJson}
+     * unless {@link AiAssist.IGenerateJsonCompletionParams.jsonConverter} is
+     * provided.
+     */
+    readonly converter?: Converter<T> | Validator<T>;
+    /**
+     * Full string-to-`T` pipeline override. When supplied, takes precedence over
+     * {@link AiAssist.IGenerateJsonCompletionParams.converter} and lets the
+     * caller plug in a custom extractor or skip the default fence tolerance
+     * entirely.
+     */
+    readonly jsonConverter?: Converter<T>;
+    /**
+     * Controls the optional system-prompt augmentation. Defaults to `'smart'`.
+     * Pass `'none'` to disable, or a string to append custom guidance.
+     */
+    readonly promptHint?: JsonPromptHint;
+}
+
+/**
+ * Successful result of {@link AiAssist.generateJsonCompletion}.
+ * @public
+ */
+declare interface IGenerateJsonCompletionResult<T> {
+    /** The validated JSON value. */
+    readonly value: T;
+    /** The raw response text returned by the provider. */
+    readonly raw: string;
+    /** The full underlying completion response. */
+    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;
+}
+
+/**
+ * Options for importing raw key material via {@link KeyStore.importSecret}.
+ * Extends {@link IImportSecretOptions} with a type classification.
+ * @public
+ */
+declare interface IImportKeyOptions extends IImportSecretOptions {
+    /**
+     * Symmetric secret type classification for the imported key material.
+     * @defaultValue 'encryption-key'
+     */
+    readonly type?: KeyStoreSymmetricSecretType;
+}
+
 /**
  * Options for importing a secret.
  * @public
@@ -1106,22 +3376,129 @@ 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 type IKeyDerivationParams = IPbkdf2KeyDerivationParams | IArgon2idKeyDerivationParams;
+
+/**
+ * WebCrypto parameters for a single {@link CryptoUtils.KeyPairAlgorithm}.
+ * Implementations of {@link CryptoUtils.ICryptoProvider} use this table to
+ * translate the small public algorithm enum into the WebCrypto algorithm
+ * objects and key-usage arrays expected by `crypto.subtle`.
  * @public
  */
-declare interface IKeyDerivationParams {
+declare interface IKeyPairAlgorithmParams {
     /**
-     * Key derivation function used.
+     * Algorithm parameters for `crypto.subtle.generateKey`. Always an asymmetric
+     * variant — these algorithms produce a `CryptoKeyPair`, not a single key.
+     * The literal `{ name: 'Ed25519' }` member covers WebCrypto's Secure-Curves
+     * Ed25519 algorithm; `{ name: 'X25519' }` covers the X25519 key-agreement
+     * algorithm. Both take only a `name`; using literals rather than the base
+     * `Algorithm` keeps the union closed to the algorithms this table supports.
      */
-    readonly kdf: KeyDerivationFunction;
+    readonly generateKey: RsaHashedKeyGenParams | EcKeyGenParams | {
+        readonly name: 'Ed25519';
+    } | {
+        readonly name: 'X25519';
+    };
     /**
-     * Base64-encoded salt used for key derivation.
+     * Algorithm parameters for `crypto.subtle.importKey('jwk', ...)` when
+     * importing the public half of a keypair. The literal `{ name: 'Ed25519' }`
+     * member covers Ed25519 imports; `{ name: 'X25519' }` covers X25519 imports.
+     * Both take only a `name`; using literals rather than the base `Algorithm`
+     * keeps the union closed to the algorithms this table supports.
      */
-    readonly salt: string;
+    readonly importPublicKey: RsaHashedImportParams | EcKeyImportParams | {
+        readonly name: 'Ed25519';
+    } | {
+        readonly name: 'X25519';
+    };
     /**
-     * Number of iterations used for key derivation.
+     * Default key usages for the generated `CryptoKeyPair`. Both halves receive
+     * the usages WebCrypto considers valid for their role; the platform filters.
      */
-    readonly iterations: number;
+    readonly keyPairUsages: ReadonlyArray<KeyUsage>;
+    /**
+     * Key usages applied when re-importing only the public key.
+     */
+    readonly publicKeyUsages: ReadonlyArray<KeyUsage>;
+}
+
+/**
+ * An asymmetric keypair entry stored in the vault (in-memory representation).
+ * Holds only the public key (as a JWK) and a stable handle (`id`) the
+ * {@link CryptoUtils.KeyStore.IPrivateKeyStorage} provider uses to fetch the private key.
+ * @public
+ */
+declare interface IKeyStoreAsymmetricEntry {
+    /**
+     * Unique name for this entry (used as vault lookup key, renameable).
+     */
+    readonly name: string;
+    /**
+     * Asymmetric secret type discriminator.
+     */
+    readonly type: KeyStoreAsymmetricSecretType;
+    /**
+     * Immutable handle used by {@link CryptoUtils.KeyStore.IPrivateKeyStorage} to address the
+     * private key. Independent of `name`; survives renames.
+     */
+    readonly id: string;
+    /**
+     * Algorithm used to generate this keypair.
+     */
+    readonly algorithm: KeyPairAlgorithm;
+    /**
+     * The public key as a JSON Web Key.
+     */
+    readonly publicKeyJwk: JsonWebKey;
+    /**
+     * Optional description for this entry.
+     */
+    readonly description?: string;
+    /**
+     * When this entry was added (ISO 8601).
+     */
+    readonly createdAt: string;
+}
+
+/**
+ * JSON-serializable representation of an asymmetric keypair entry.
+ * The private key is not present here — it lives in the
+ * {@link CryptoUtils.KeyStore.IPrivateKeyStorage} provider, addressed by `id`.
+ * @public
+ */
+declare interface IKeyStoreAsymmetricEntryJson {
+    /**
+     * Unique name for this entry.
+     */
+    readonly name: string;
+    /**
+     * Asymmetric secret type discriminator.
+     */
+    readonly type: KeyStoreAsymmetricSecretType;
+    /**
+     * Immutable handle used by {@link CryptoUtils.KeyStore.IPrivateKeyStorage} to address the
+     * private key.
+     */
+    readonly id: string;
+    /**
+     * Algorithm used to generate this keypair.
+     */
+    readonly algorithm: KeyPairAlgorithm;
+    /**
+     * The public key as a JSON Web Key.
+     */
+    readonly publicKeyJwk: JsonWebKey;
+    /**
+     * Optional description.
+     */
+    readonly description?: string;
+    /**
+     * When this entry was added (ISO 8601).
+     */
+    readonly createdAt: string;
 }
 
 /**
@@ -1137,8 +3514,26 @@ declare interface IKeyStoreCreateParams {
      * PBKDF2 iterations (defaults to DEFAULT_KEYSTORE_ITERATIONS).
      */
     readonly iterations?: number;
+    /**
+     * Optional private-key storage backend. Required to use `addKeyPair` /
+     * `getKeyPair`; absent backends still permit opening, listing, and reading
+     * public-key metadata for asymmetric entries.
+     */
+    readonly privateKeyStorage?: IPrivateKeyStorage;
 }
 
+/**
+ * Any vault entry, discriminated by `type`.
+ * @public
+ */
+declare type IKeyStoreEntry = IKeyStoreSymmetricEntry | IKeyStoreAsymmetricEntry;
+
+/**
+ * Any JSON vault entry, discriminated by `type`.
+ * @public
+ */
+declare type IKeyStoreEntryJson = IKeyStoreSymmetricEntryJson | IKeyStoreAsymmetricEntryJson;
+
 /**
  * The encrypted key store file format.
  * @public
@@ -1165,9 +3560,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;
 }
 
 /**
@@ -1183,22 +3578,46 @@ declare interface IKeyStoreOpenParams {
      * The encrypted key store file content.
      */
     readonly keystoreFile: IKeyStoreFile;
+    /**
+     * Optional private-key storage backend. Required to use `addKeyPair` /
+     * `getKeyPair`; absent backends still permit opening, listing, and reading
+     * public-key metadata for asymmetric entries.
+     */
+    readonly privateKeyStorage?: IPrivateKeyStorage;
 }
 
 /**
- * A secret entry stored in the vault (in-memory representation).
+ * Backwards-compatible alias for {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntry}.
+ * @deprecated Use {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntry} for symmetric
+ * entries or {@link CryptoUtils.KeyStore.IKeyStoreEntry} for the discriminated union.
+ * @public
+ */
+declare type IKeyStoreSecretEntry = IKeyStoreSymmetricEntry;
+
+/**
+ * Backwards-compatible alias for {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntryJson}.
+ * @deprecated Use {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntryJson} for
+ * symmetric entries or {@link CryptoUtils.KeyStore.IKeyStoreEntryJson} for the
+ * discriminated union.
+ * @public
+ */
+declare type IKeyStoreSecretEntryJson = IKeyStoreSymmetricEntryJson;
+
+/**
+ * A symmetric secret entry stored in the vault (in-memory representation).
+ * Holds the raw key material directly — for `'encryption-key'` it is a 32-byte
+ * AES-256 key; for `'api-key'` it is the UTF-8 encoded API key string.
  * @public
  */
-declare interface IKeyStoreSecretEntry {
+declare interface IKeyStoreSymmetricEntry {
     /**
      * Unique name for this secret (used as lookup key).
      */
     readonly name: string;
     /**
-     * Secret type discriminator.
-     * Defaults to `'encryption-key'` for backwards compatibility.
+     * Symmetric secret type discriminator.
      */
-    readonly type: KeyStoreSecretType;
+    readonly type: KeyStoreSymmetricSecretType;
     /**
      * The secret data.
      * - For `'encryption-key'`: 32-byte AES-256 key.
@@ -1216,19 +3635,34 @@ declare interface IKeyStoreSecretEntry {
 }
 
 /**
- * JSON-serializable version of secret entry (for storage).
+ * JSON-serializable representation of a symmetric secret entry.
+ *
+ * @remarks
+ * Describes the *normalized* shape after parsing. `type` is required here
+ * because the converter (see
+ * {@link CryptoUtils.KeyStore.Converters.keystoreSymmetricEntryJson | keystoreSymmetricEntryJson})
+ * injects the default `'encryption-key'` when reading vaults written before
+ * asymmetric-keypair support added the discriminator. Raw on-wire bytes from
+ * a legacy vault may therefore omit `type`; downstream code only ever sees
+ * the post-conversion shape declared here.
+ *
  * @public
  */
-declare interface IKeyStoreSecretEntryJson {
+declare interface IKeyStoreSymmetricEntryJson {
     /**
      * Unique name for this secret.
      */
     readonly name: string;
     /**
-     * Secret type discriminator.
-     * Optional for backwards compatibility — missing means `'encryption-key'`.
+     * Symmetric secret type discriminator.
+     *
+     * Required on this normalized model type. Vaults written prior to the
+     * asymmetric-keypair support may omit this field on the wire; the
+     * converter injects `'encryption-key'` when missing for backwards
+     * compatibility, so by the time a value of this type is observed the
+     * discriminator is always present.
      */
-    readonly type?: KeyStoreSecretType;
+    readonly type: KeyStoreSymmetricSecretType;
     /**
      * Base64-encoded secret data.
      */
@@ -1244,7 +3678,7 @@ declare interface IKeyStoreSecretEntryJson {
 }
 
 /**
- * The decrypted vault contents - a versioned map of secrets.
+ * The decrypted vault contents - a versioned map of entries.
  * @public
  */
 declare interface IKeyStoreVaultContents {
@@ -1253,9 +3687,9 @@ declare interface IKeyStoreVaultContents {
      */
     readonly version: KeyStoreFormat;
     /**
-     * Map of secret name to secret entry.
+     * Map of entry name to entry (symmetric or asymmetric).
      */
-    readonly secrets: Record<string, IKeyStoreSecretEntryJson>;
+    readonly secrets: Record<string, IKeyStoreEntryJson>;
 }
 
 /**
@@ -1278,6 +3712,28 @@ declare interface IMissingVariableDetail {
     readonly existingPath: readonly string[];
 }
 
+/**
+ * Canonical fgv alias → concrete provider model map.
+ *
+ * @remarks
+ * Keys are full fgv aliases (`@<providerId>:<role>`, e.g. `@google-gemini:flash`);
+ * values are the current concrete provider model id (or a provider-native alias,
+ * which is resolved with one further indirection hop). Additive; absence of an
+ * `aliases` field on a descriptor means "this provider defines no aliases" and
+ * every model string passes through verbatim.
+ * @public
+ */
+declare interface IModelAliasMap {
+    readonly [alias: string]: string;
+}
+
+/**
+ * Discriminated union of all model-family option blocks.
+ * Discriminated on `provider` + `family` fields.
+ * @public
+ */
+declare type IModelFamilyConfig = IGptImageModelOptions | IGrokImagineModelOptions | IGeminiFlashImageModelOptions | IOtherModelOptions;
+
 /**
  * A model specification: either a simple model string or a record mapping
  * context keys to nested model specs.
@@ -1285,18 +3741,18 @@ declare interface IMissingVariableDetail {
  * @remarks
  * A bare string is equivalent to `{ base: string }`. This keeps the simple
  * case simple while allowing context-aware model selection (e.g. different
- * models for tool-augmented vs. base completions).
+ * models for different quality tiers).
  *
  * @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 per quality tier:
+ * const split: ModelSpec = { base: 'gpt-5.4-mini', advanced: 'gpt-5.5', frontier: 'gpt-5.5-pro' };
  *
- * // Future nested — per-tool model selection:
- * const nested: ModelSpec = { base: 'grok-fast', tools: { base: 'grok-r', image: 'grok-v' } };
+ * // Nested — a tier branch is itself a spec:
+ * const nested: ModelSpec = { base: 'grok-fast', advanced: { base: 'grok-r', image: 'grok-v' } };
  * ```
  * @public
  */
@@ -1304,6 +3760,25 @@ declare interface IModelSpecMap {
     readonly [key: string]: ModelSpec;
 }
 
+/**
+ * Imports a public key from a multibase base64url-encoded SPKI blob.
+ *
+ * Decodes the multibase prefix, decodes the base64url body, then uses
+ * the provider to import the key with the algorithm parameters from
+ * {@link CryptoUtils.keyPairAlgorithmParams}.
+ *
+ * Accepts a plain `string` (not only a branded {@link CryptoUtils.MultibaseSpkiPublicKey}),
+ * so callers holding an unbranded value read from storage or the wire can import
+ * it directly; a malformed value fails with error context rather than throwing.
+ *
+ * @param encoded - A multibase SPKI string produced by {@link CryptoUtils.exportPublicKeyAsMultibaseSpki}.
+ * @param algorithm - The {@link CryptoUtils.KeyPairAlgorithm} the key was generated for.
+ * @param provider - The {@link CryptoUtils.ICryptoProvider} to use for the import operation.
+ * @returns `Success` with the imported public `CryptoKey`, or `Failure` with error context.
+ * @public
+ */
+declare function importPublicKeyFromMultibaseSpki(encoded: string, algorithm: KeyPairAlgorithm, provider: ICryptoProvider): Promise<Result<CryptoKey>>;
+
 /**
  * Options for template parsing and validation.
  * @public
@@ -1321,6 +3796,32 @@ declare interface IMustacheTemplateOptions {
      * Whether to include partial references in variable extraction (default: false)
      */
     readonly includePartials?: boolean;
+    /**
+     * Escape strategy applied to double-brace `{{name}}` tokens at render
+     * time. Default `'html'` preserves the existing mustache.js behavior
+     * (back-compat).
+     *
+     * Pass `'none'` for LLM-prompt or other non-HTML targets where the
+     * default `& → &amp;` escape would corrupt the output. Pass a custom
+     * function for any other escape policy.
+     *
+     * The strategy is applied per-template via a private `Mustache.Writer`
+     * instance; no global state on the `mustache` module is mutated, so
+     * concurrent templates with different strategies are safe.
+     *
+     * Note: triple-brace `{{{name}}}` tokens are always rendered unescaped
+     * regardless of strategy (standard mustache.js semantics).
+     */
+    readonly escape?: MustacheEscapeStrategy;
+}
+
+/**
+ * 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[];
 }
 
 /**
@@ -1339,29 +3840,312 @@ declare interface INamedSecret {
 }
 
 /**
- * Parameters for a provider completion request.
+ * 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:
+ * - {@link CryptoUtils.KeyStore.EncryptedFilePrivateKeyStorage} in
+ *   `@fgv/ts-extras` — directory-on-disk, AES-256-GCM-encrypted JWK per key
+ *   (Node; `supportsNonExtractable: false`).
+ * - `IdbPrivateKeyStorage` in `@fgv/ts-web-extras` — IndexedDB-backed, stores
+ *   `CryptoKey` objects directly (browser; `supportsNonExtractable: true`).
+ *
+ * The keystore writes storage-first: a private key is always stored here
+ * before the corresponding public-key vault entry is committed. Conversely,
+ * deletes hit the vault first and then this storage best-effort. As a result,
+ * crashes or skipped saves can leave orphaned blobs here; callers are expected
+ * to reconcile via {@link CryptoUtils.KeyStore.IPrivateKeyStorage.list} cross-referenced
+ * against the keystore's asymmetric entries.
+ *
+ * @public
+ */
+declare interface IPrivateKeyStorage {
+    /**
+     * Whether keys generated for this backend may be marked
+     * `extractable: false`. `true` on backends that store `CryptoKey`
+     * objects directly (e.g. IndexedDB). `false` on backends that must
+     * round-trip via JWK (e.g. encrypted-file backends).
+     */
+    readonly supportsNonExtractable: boolean;
+    /**
+     * Stores `key` under `id`. Returns the stored `id` on success so the
+     * call can compose into a Result chain.
+     * @param id - Storage handle to write under.
+     * @param key - The private `CryptoKey` to persist.
+     */
+    store(id: string, key: CryptoKey): Promise<Result<string>>;
+    /**
+     * Loads the private key previously stored under `id`.
+     * @param id - Storage handle to look up.
+     */
+    load(id: string): Promise<Result<CryptoKey>>;
+    /**
+     * Deletes the entry stored under `id`. Returns the deleted `id` on
+     * success so the call can compose into a Result chain.
+     * @param id - Storage handle to remove.
+     */
+    delete(id: string): Promise<Result<string>>;
+    /**
+     * Lists every `id` currently held by the backend. Used by consumers to
+     * garbage-collect orphans left by crashes or aborted sessions; the
+     * keystore itself does not invoke this automatically.
+     */
+    list(): Promise<Result<readonly string[]>>;
+}
+
+/**
+ * Parameters for a provider completion request. Carries the unified
+ * {@link AiAssist.IChatRequest} shape (`system?` + ordered `messages`, last =
+ * current user turn); history is linearized before the current turn.
  * @public
  */
-declare interface IProviderCompletionParams {
+declare interface IProviderCompletionParams extends IChatRequest {
     /** The provider descriptor */
     readonly descriptor: IAiProviderDescriptor;
     /** API key for authentication */
     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.
+     * Sampling temperature. Sent to the provider only when explicitly provided; omitted otherwise
+     * so the provider's own default applies (current-gen models reject a caller-supplied default).
      */
-    readonly additionalMessages?: ReadonlyArray<IChatMessage>;
-    /** Sampling temperature (default: 0.7) */
     readonly temperature?: number;
     /** Optional model override — string or context-aware map (uses descriptor.defaultModel otherwise) */
     readonly modelOverride?: ModelSpec;
+    /**
+     * Optional quality tier selecting which completion model to use. `undefined`
+     * selects the `base` tier; `'frontier'` cascades to `advanced` then `base`
+     * when a tier is unset for a provider. Orthogonal to `thinking` and `tools`,
+     * which never select a model.
+     */
+    readonly tier?: 'advanced' | 'frontier';
     /** Optional logger for request/response observability. */
     readonly logger?: Logging.ILogger;
     /** Server-side tools to include in the request. Overrides settings-level tool config when provided. */
     readonly tools?: ReadonlyArray<AiServerToolConfig>;
+    /** Optional abort signal for cancelling the in-flight request. */
+    readonly signal?: AbortSignal;
+    /**
+     * 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;
+}
+
+/**
+ * Parameters for a streaming completion request. Structurally identical to
+ * the non-streaming `IProviderCompletionParams`; kept as its own interface
+ * so callers can be explicit about which path they're invoking.
+ *
+ * @remarks
+ * Carries the unified {@link AiAssist.IChatRequest} shape (`system?` + ordered
+ * `messages`): the last message is the current user turn and the preceding
+ * messages are history, linearized before the current turn (identical to the
+ * completion and client-tool turn paths).
+ *
+ * @public
+ */
+declare interface IProviderCompletionStreamParams extends IChatRequest {
+    /** The provider descriptor */
+    readonly descriptor: IAiProviderDescriptor;
+    /** API key for authentication */
+    readonly apiKey: string;
+    /**
+     * Sampling temperature. Sent to the provider only when explicitly provided; omitted otherwise
+     * so the provider's own default applies (current-gen models reject a caller-supplied default).
+     */
+    readonly temperature?: number;
+    /** Optional model override — string or context-aware map. */
+    readonly modelOverride?: ModelSpec;
+    /**
+     * Optional quality tier selecting which completion model to use. `undefined`
+     * selects the `base` tier; `'frontier'` cascades to `advanced` then `base`
+     * when a tier is unset for a provider. Orthogonal to `thinking` and `tools`,
+     * which never select a model.
+     */
+    readonly tier?: 'advanced' | 'frontier';
+    /** Optional logger for request/response observability. */
+    readonly logger?: Logging.ILogger;
+    /** Server-side tools to include in the request. */
+    readonly tools?: ReadonlyArray<AiServerToolConfig>;
+    /** Optional abort signal for cancelling the in-flight stream. */
+    readonly signal?: AbortSignal;
+    /**
+     * Optional override of the descriptor's default base URL. Same semantics as
+     * the non-streaming completion path: a well-formed `http`/`https` URL is
+     * substituted for `descriptor.baseUrl` when composing the streaming
+     * request, with the per-format suffix appended unchanged. Validated at the
+     * dispatcher; auth shape is unaffected.
+     */
+    readonly endpoint?: string;
+    /**
+     * Optional thinking/reasoning mode configuration.
+     */
+    readonly thinking?: IThinkingConfig;
+}
+
+/**
+ * Parameters for a provider embedding request. Mirrors
+ * {@link AiAssist.IProviderImageGenerationParams}.
+ * @public
+ */
+declare interface IProviderEmbeddingParams {
+    /** The provider descriptor. */
+    readonly descriptor: IAiProviderDescriptor;
+    /** API key for authentication (empty string for keyless self-hosted providers). */
+    readonly apiKey: string;
+    /** The embedding request (input + optional knobs). */
+    readonly params: IAiEmbeddingParams;
+    /**
+     * Optional model override — string or context-aware map. Uses
+     * `descriptor.defaultModel.embedding` otherwise. Self-hosted providers
+     * (`ollama`, `openai-compat`) have no default and require this.
+     */
+    readonly modelOverride?: ModelSpec;
+    /** Optional logger for request/response observability. */
+    readonly logger?: Logging.ILogger;
+    /** Optional abort signal for cancelling the in-flight request. */
+    readonly signal?: AbortSignal;
+    /** Optional override of the descriptor's base URL; the `/embeddings` suffix is appended unchanged. */
+    readonly endpoint?: string;
+}
+
+/**
+ * Parameters for an image-generation request.
+ * @public
+ */
+declare interface IProviderImageGenerationParams {
+    /** The provider descriptor */
+    readonly descriptor: IAiProviderDescriptor;
+    /** API key for authentication */
+    readonly apiKey: string;
+    /** The image-generation request */
+    readonly params: IAiImageGenerationParams;
+    /** Optional model override — string or context-aware map (uses descriptor.defaultModel.image otherwise) */
+    readonly modelOverride?: ModelSpec;
+    /** Optional logger for request/response observability. */
+    readonly logger?: Logging.ILogger;
+    /** Optional abort signal for cancelling the in-flight request. */
+    readonly signal?: AbortSignal;
+    /** Optional override of the descriptor's base URL; per-route suffix is appended unchanged. */
+    readonly endpoint?: string;
+}
+
+/**
+ * Parameters for a list-models request.
+ * @public
+ */
+declare interface IProviderListModelsParams {
+    /** The provider descriptor */
+    readonly descriptor: IAiProviderDescriptor;
+    /** API key for authentication */
+    readonly apiKey: string;
+    /** Optional capability filter; when set, only models declaring this capability are returned. */
+    readonly capability?: AiModelCapability;
+    /** Optional capability config override (defaults to {@link DEFAULT_MODEL_CAPABILITY_CONFIG}). */
+    readonly capabilityConfig?: IAiModelCapabilityConfig;
+    /** Optional logger for request/response observability. */
+    readonly logger?: Logging.ILogger;
+    /** Optional abort signal for cancelling the in-flight request. */
+    readonly signal?: AbortSignal;
+    /** Optional override of the descriptor's base URL; per-format `/models` route is appended unchanged. */
+    readonly endpoint?: string;
+}
+
+/**
+ * Result of removing a secret from the key store.
+ * @public
+ */
+declare interface IRemoveSecretResult {
+    /**
+     * The secret entry that was removed from the vault.
+     */
+    readonly entry: IKeyStoreEntry;
+    /**
+     * Best-effort warning from {@link CryptoUtils.KeyStore.IPrivateKeyStorage}.delete
+     * for asymmetric entries when the storage call failed. The vault entry is
+     * still considered removed and the orphaned blob is left for consumer-side
+     * GC to reconcile.
+     */
+    readonly warning?: string;
 }
 
 /**
@@ -1372,6 +4156,53 @@ declare interface IRequiredMustacheTemplateOptions {
     readonly tags: [string, string];
     readonly includeComments: boolean;
     readonly includePartials: boolean;
+    readonly escape: MustacheEscapeStrategy;
+}
+
+/**
+ * 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 outputFormat?: string;
+    readonly outputCompression?: number;
+    readonly background?: string;
+    readonly moderation?: string;
+    readonly aspectRatio?: string;
+    readonly resolution?: string;
+    readonly geminiAspectRatio?: string;
+    readonly otherParams?: JsonObject;
+}
+
+/**
+ * Resolved thinking wire parameters for a specific provider, after merging
+ * all applicable config blocks. Ready for provider-specific wire encoding.
+ *
+ * Callers that pre-resolve thinking config outside of the standard streaming
+ * helpers (e.g. `executeClientToolTurn`) accept this type via the
+ * `resolvedThinking` parameter and pass it directly to the adapter layer.
+ * @public
+ */
+declare interface IResolvedThinkingConfig {
+    /** Anthropic: effort level; emit-site converts to `thinking.budget_tokens` via `anthropicEffortToBudgetTokens`. */
+    readonly anthropicEffort?: IAnthropicThinkingConfig['effort'];
+    /** OpenAI Chat: reasoning_effort value; OpenAI Responses: reasoning.effort */
+    readonly openAiEffort?: IOpenAiThinkingConfig['effort'];
+    /** Gemini: generationConfig.thinkingConfig.thinkingBudget */
+    readonly geminiThinkingBudget?: number;
+    /** xAI: reasoning_effort value (omit for grok-4) */
+    readonly xaiEffort?: IXAiThinkingConfig['effort'];
+    /** Other/passthrough: merged verbatim into wire request */
+    readonly otherParams?: JsonObject;
 }
 
 /**
@@ -1399,6 +4230,106 @@ declare function isKeyStoreFile(json: unknown): boolean;
  */
 declare const isoDate: Converter<Date, unknown>;
 
+/**
+ * A `Converter` which converts an iso formatted string, a number or a `Date` object to
+ * a `DateTime` object.
+ * @public
+ */
+declare const isoDateTime: Converter<DateTime, unknown>;
+
+/**
+ * Determines whether a concrete (already-resolved) model id must be invoked via
+ * the OpenAI Responses API rather than chat completions.
+ *
+ * @remarks
+ * Matches `modelId` against the descriptor's
+ * {@link IAiProviderDescriptor.responsesOnlyModelPrefixes} by prefix. A provider
+ * that declares no list (the common case) always returns `false`. Consulted by
+ * both the completion (`callProviderCompletion`) and streaming
+ * (`callProviderCompletionStream`) OpenAI dispatch branches so a Responses-only
+ * model (e.g. `gpt-5.5-pro`) routes correctly even with no tools requested.
+ *
+ * @param descriptor - The provider descriptor supplying the prefix list.
+ * @param modelId - The resolved concrete model id to test.
+ * @returns `true` when `modelId` starts with any declared Responses-only prefix.
+ * @public
+ */
+declare function isResponsesOnlyModel(descriptor: IAiProviderDescriptor, modelId: string): boolean;
+
+/**
+ * Type guard for {@link CryptoUtils.MultibaseSpkiPublicKey}: a string matching
+ * {@link CryptoUtils.MultibaseSpkiPublicKeyRegExp} (multibase `'m'` prefix + a
+ * non-empty base64url-no-pad body) whose body also satisfies the base64url-no-pad
+ * length rule shared with {@link CryptoUtils.base64UrlNoPadDecode}. This is a
+ * structural *shape* check, not full validation — it does not decode the DER SPKI
+ * or verify the key material/algorithm (a malformed-but-well-shaped string fails
+ * later, with clear context, in {@link CryptoUtils.importPublicKeyFromMultibaseSpki}).
+ *
+ * @param value - The value to test.
+ * @returns `true` if `value` is a well-formed multibase SPKI public key string.
+ * @public
+ */
+declare function isValidMultibaseSpkiPublicKey(value: unknown): value is MultibaseSpkiPublicKey;
+
+/**
+ * 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;
+
+/**
+ * Decision returned by an {@link IExecuteClientToolTurnParams.onBeforeToolExecute}
+ * gate for a single client-tool call.
+ *
+ * @remarks
+ * - `{ action: 'proceed' }` — run the tool's `execute` normally.
+ * - `{ action: 'deny', reason }` — do NOT run `execute`; a synthesized tool-result
+ *   carrying `reason` is fed into the continuation exactly like a normal result so
+ *   the model can react, and a `client-tool-result` event is emitted for the call.
+ *   The turn continues.
+ *
+ * A gate that wants to signal a hard error (as opposed to a deliberate deny) should
+ * return `Result.fail` (or reject) from the callback. Note this is NOT the same as a
+ * `tool.execute` failure: an `execute` failure yields an `isError` tool-result and the
+ * **turn continues**, whereas a gate `fail`/reject **terminates the turn** — it fails
+ * `nextTurn` (and emits an inline `error` event) rather than synthesizing a deny.
+ *
+ * @public
+ */
+declare type IToolExecutionDecision = {
+    readonly action: 'proceed';
+} | {
+    readonly action: 'deny';
+    readonly reason: string;
+};
+
 /**
  * Represents a variable reference extracted from a Mustache template.
  * @public
@@ -1423,6 +4354,118 @@ declare interface IVariableRef {
     readonly isSection: boolean;
 }
 
+/**
+ * Caller-supplied HKDF parameters that domain-separate one
+ * {@link CryptoUtils.ICryptoProvider.wrapBytes | wrapBytes} call from another.
+ * Two wraps that share recipient but differ on `salt` or `info` derive distinct
+ * wrap keys, so callers should pick values that bind the wrap to its
+ * application context (e.g. a content hash for `salt` and a secret name for
+ * `info`).
+ *
+ * Both fields are required; pass an empty `Uint8Array` if the caller has no
+ * value to bind on a given axis. Silent defaulting would hide protocol
+ * mistakes, so the API does not pick defaults.
+ * @public
+ */
+declare interface IWrapBytesOptions {
+    /**
+     * HKDF salt. Domain-separates this wrap from others in different contexts.
+     * Caller picks; common choices include a content hash, document id, channel
+     * id, etc.
+     */
+    readonly salt: Uint8Array;
+    /**
+     * HKDF info. Further binds the derived key to a specific use within the
+     * calling application. Caller picks; common choices include a secret name,
+     * message type, or version tag.
+     */
+    readonly info: Uint8Array;
+}
+
+/**
+ * Output of {@link CryptoUtils.ICryptoProvider.wrapBytes | wrapBytes}. The
+ * shape is JSON-serializable so it can travel directly over the wire or be
+ * persisted as-is.
+ * @public
+ */
+declare interface IWrappedBytes {
+    /**
+     * Sender's ephemeral ECDH P-256 public key as a JSON Web Key. The matching
+     * ephemeral private key is dropped after the shared-secret derive.
+     */
+    readonly ephemeralPublicKey: JsonWebKey;
+    /**
+     * AES-GCM nonce, base64-encoded. 12 bytes (96 bits) — the standard AES-GCM
+     * nonce length.
+     */
+    readonly nonce: string;
+    /**
+     * AES-GCM ciphertext concatenated with the 16-byte authentication tag,
+     * base64-encoded. Tampering with either the nonce or the ciphertext causes
+     * unwrap to fail GCM authentication.
+     */
+    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
+ */
+declare interface IYamlSerializeOptions {
+    /**
+     * Indentation width in spaces (default: 2).
+     */
+    readonly indent?: number;
+    /**
+     * Nesting level at which to switch from block to flow style.
+     * -1 means block style everywhere (default: -1).
+     */
+    readonly flowLevel?: number;
+    /**
+     * If true, sort keys when dumping (default: false).
+     */
+    readonly sortKeys?: boolean;
+    /**
+     * Maximum line width (default: 80).
+     */
+    readonly lineWidth?: number;
+    /**
+     * If true, don't convert duplicate objects into references (default: false).
+     */
+    readonly noRefs?: boolean;
+    /**
+     * If true, don't add an indentation level to array elements (default: false).
+     */
+    readonly noArrayIndent?: boolean;
+    /**
+     * If true, all non-key strings will be quoted (default: false).
+     */
+    readonly forceQuotes?: boolean;
+}
+
 /**
  * Simple interface for a file to be added to a zip file.
  * @public
@@ -1452,11 +4495,54 @@ declare interface JarRecordParserOptions {
     readonly fixedContinuationSize?: number;
 }
 
+/**
+ * Controls the optional system-prompt augmentation applied by
+ * {@link AiAssist.generateJsonCompletion}.
+ *
+ * - `'smart'` (default): append {@link AiAssist.SMART_JSON_PROMPT_HINT}.
+ * - `'none'`: do not modify the prompt.
+ * - A string: append the supplied text verbatim.
+ *
+ * @remarks
+ * The `string & {}` branch is the standard TypeScript trick that prevents
+ * the literal members from being widened away — callers still get
+ * autocomplete for `'smart'` and `'none'` while accepting any string.
+ *
+ * @public
+ */
+declare type JsonPromptHint = 'smart' | 'none' | (string & {});
+
+/**
+ * A function that pulls a JSON-shaped substring out of arbitrary model text.
+ * Implementations strip whatever wrappers the model added (fences, preamble,
+ * trailing prose) and return the JSON-shaped substring ready for `JSON.parse`.
+ * @public
+ */
+declare type JsonTextExtractor = (text: string) => Result<string>;
+
+/**
+ * In-place shape check for a JSON Web Key. Asserts only that the input is a
+ * non-array object whose `kty` discriminator is a string; every other JWK
+ * field passes through untouched. This is intentionally **not** a true JWK
+ * validator — per-algorithm correctness (RSA `n`/`e`, EC `crv`/`x`/`y`,
+ * key-size constraints, etc.) is delegated to `crypto.subtle.importKey` at
+ * first use, which is the authoritative checker. The "shape" suffix in the
+ * name is the warning sign for readers expecting full validation.
+ * @remarks
+ * Built with `Validators.object` (in-place, non-strict) so unknown JWK fields
+ * survive the round-trip; the cast to `FieldValidators<JsonWebKey>` is required
+ * only because TypeScript's mapped type demands an entry for every key in
+ * `JsonWebKey`. At runtime the `ObjectValidator` only inspects keys present in
+ * the field-validators map.
+ * @public
+ */
+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.
@@ -1466,22 +4552,74 @@ 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>;
 
+/**
+ * Asymmetric keypair algorithms supported by the crypto provider.
+ * - `'ecdsa-p256'`: ECDSA over the P-256 curve, for signing.
+ * - `'rsa-oaep-2048'`: RSA-OAEP, 2048-bit modulus with SHA-256, for encryption.
+ * - `'ecdh-p256'`: ECDH over the P-256 curve, for key agreement
+ *   (e.g. as the recipient keypair in
+ *   {@link CryptoUtils.ICryptoProvider.wrapBytes | wrapBytes} /
+ *   {@link CryptoUtils.ICryptoProvider.unwrapBytes | unwrapBytes}).
+ * - `'ed25519'`: EdDSA over the Edwards25519 curve, for signing.
+ *   Deterministic — the per-signature nonce is derived from the private key
+ *   and message rather than sampled randomly, eliminating the random-nonce
+ *   reuse risk that ECDSA carries. Distinct from X25519 (key agreement over
+ *   the Montgomery form, Curve25519).
+ * - `'x25519'`: Diffie-Hellman key agreement over the Montgomery form of
+ *   Curve25519. Key-agreement only — use `deriveBits`/`deriveKey` to produce
+ *   a shared secret from one party's private key and the peer's public key.
+ *   Distinct from Ed25519 (which uses the twisted-Edwards form for signing).
+ * @public
+ */
+declare type KeyPairAlgorithm = 'ecdsa-p256' | 'rsa-oaep-2048' | 'ecdh-p256' | 'ed25519' | 'x25519';
+
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyPairAlgorithm | key pair algorithm}.
+ * @public
+ */
+declare const keyPairAlgorithm: Converter<KeyPairAlgorithm>;
+
+/**
+ * Lookup table from {@link CryptoUtils.KeyPairAlgorithm} to the WebCrypto
+ * parameters needed to drive `crypto.subtle`. Shared between every
+ * {@link CryptoUtils.ICryptoProvider} implementation since both Node and
+ * browser providers speak the same WebCrypto API. Exposed for downstream
+ * provider implementations (e.g. browser-side providers in `@fgv/ts-web-extras`).
+ * @public
+ */
+declare const keyPairAlgorithmParams: Readonly<Record<KeyPairAlgorithm, IKeyPairAlgorithmParams>>;
+
 declare namespace KeyStore {
     export {
         Converters_2 as Converters,
         KeyStore_2 as KeyStore,
+        EncryptedFilePrivateKeyStorage,
+        IEncryptedFilePrivateKeyStorageCreateParams,
         isKeyStoreFile,
+        allKeyPairAlgorithms,
+        KeyPairAlgorithm,
         KeyStoreFormat,
         KEYSTORE_FORMAT,
         DEFAULT_KEYSTORE_ITERATIONS,
         MIN_SALT_LENGTH,
+        KeyStoreSymmetricSecretType,
+        allKeyStoreSymmetricSecretTypes,
+        KeyStoreAsymmetricSecretType,
+        allKeyStoreAsymmetricSecretTypes,
         KeyStoreSecretType,
         allKeyStoreSecretTypes,
+        IKeyStoreSymmetricEntry,
+        IKeyStoreAsymmetricEntry,
+        IKeyStoreEntry,
         IKeyStoreSecretEntry,
+        IKeyStoreSymmetricEntryJson,
+        IKeyStoreAsymmetricEntryJson,
+        IKeyStoreEntryJson,
         IKeyStoreSecretEntryJson,
         IKeyStoreVaultContents,
         IKeyStoreFile,
@@ -1491,9 +4629,15 @@ declare namespace KeyStore {
         IAddSecretResult,
         IAddSecretOptions,
         IImportSecretOptions,
+        IImportKeyOptions,
         IAddSecretFromPasswordOptions,
         DEFAULT_SECRET_ITERATIONS,
-        IAddSecretFromPasswordResult
+        IAddSecretFromPasswordResult,
+        IAddSecretFromPasswordArgon2idOptions,
+        IAddKeyPairOptions,
+        IAddKeyPairResult,
+        IRemoveSecretResult,
+        IPrivateKeyStorage
     }
 }
 
@@ -1530,6 +4674,7 @@ declare namespace KeyStore {
  */
 declare class KeyStore_2 implements IEncryptionProvider {
     private readonly _cryptoProvider;
+    private readonly _privateKeyStorage;
     private readonly _iterations;
     private _keystoreFile;
     private _salt;
@@ -1571,6 +4716,21 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * @public
      */
     unlock(password: string): Promise<Result<KeyStore_2>>;
+    /**
+     * Unlocks an existing key store with a pre-derived key, bypassing
+     * PBKDF2 key derivation. Use this when the derived key has been
+     * stored externally (e.g., in another key store) and the original
+     * password is no longer available.
+     *
+     * The supplied key must have been derived from the correct password
+     * using the key store file's own PBKDF2 parameters (salt and
+     * iteration count).
+     *
+     * @param derivedKey - The pre-derived master key (32 bytes for AES-256)
+     * @returns Success with this instance when unlocked, Failure if key is incorrect
+     * @public
+     */
+    unlockWithKey(derivedKey: Uint8Array): Promise<Result<KeyStore_2>>;
     /**
      * Locks the key store, clearing all secrets from memory.
      * @param force - If true, discards unsaved changes
@@ -1613,12 +4773,23 @@ declare class KeyStore_2 implements IEncryptionProvider {
      */
     listSecrets(): Result<readonly string[]>;
     /**
-     * Gets a secret by name.
+     * Gets a secret by name. Returns the {@link CryptoUtils.KeyStore.IKeyStoreEntry | discriminated union}
+     * — callers must check `entry.type` before accessing `key`/`id` since asymmetric
+     * entries carry no raw key material.
      * @param name - Name of the secret
      * @returns Success with secret entry, Failure if not found or locked
      * @public
      */
-    getSecret(name: string): Result<IKeyStoreSecretEntry>;
+    getSecret(name: string): Result<IKeyStoreEntry>;
+    /**
+     * Returns the public-key JWK for an asymmetric-keypair entry.
+     * Available without {@link CryptoUtils.KeyStore.IPrivateKeyStorage} since the
+     * public key lives in the vault metadata directly.
+     * @param name - Name of the entry
+     * @returns Success with the JWK, Failure if not found, locked, or wrong type
+     * @public
+     */
+    getPublicKeyJwk(name: string): Result<JsonWebKey>;
     /**
      * Checks if a secret exists.
      * @param name - Name of the secret
@@ -1635,14 +4806,20 @@ declare class KeyStore_2 implements IEncryptionProvider {
      */
     addSecret(name: string, options?: IAddSecretOptions): Promise<Result<IAddSecretResult>>;
     /**
-     * Imports an existing secret key.
+     * Imports raw 32-byte key material into the vault.
+     *
+     * Always validates that the key is exactly 32 bytes (AES-256). The optional
+     * `type` field is a classification label stored with the entry; it does not
+     * change the validation rules.  For importing UTF-8 API key strings (variable
+     * length), use {@link KeyStore.importApiKey} instead.
+     *
      * @param name - Unique name for the secret
-     * @param key - The 32-byte AES-256 key
-     * @param options - Optional description, whether to replace existing
+     * @param key - The 32-byte AES-256 key material
+     * @param options - Optional type classification, description, whether to replace existing
      * @returns Success with entry, Failure if locked, key invalid, or exists and !replace
      * @public
      */
-    importSecret(name: string, key: Uint8Array, options?: IImportSecretOptions): Result<IAddSecretResult>;
+    importSecret(name: string, key: Uint8Array, options?: IImportKeyOptions): Promise<Result<IAddSecretResult>>;
     /**
      * Adds a secret derived from a password using PBKDF2.
      *
@@ -1659,12 +4836,81 @@ declare class KeyStore_2 implements IEncryptionProvider {
      */
     addSecretFromPassword(name: string, password: string, options?: IAddSecretFromPasswordOptions): Promise<Result<IAddSecretFromPasswordResult>>;
     /**
-     * Removes a secret by name.
+     * Verifies that a candidate password derives the same key material currently
+     * stored under `name`, using the supplied
+     * {@link CryptoUtils.IKeyDerivationParams | key derivation parameters}.
+     *
+     * The keystore does not persist per-slot key derivation parameters with the
+     * entry — callers receive them from `addSecretFromPassword` and store them
+     * alongside the encrypted artifact (or wherever else makes sense). Pass
+     * those same parameters here for verification.
+     *
+     * Re-derives a key from `password` + `keyDerivation`, then compares it to
+     * the stored key material in constant time. Restricted to entries of type
+     * `'encryption-key'` — the type produced by `addSecretFromPassword`. Other
+     * symmetric types (`'api-key'`) and asymmetric entries are rejected so
+     * the boolean result reflects "this slot accepts this password" rather
+     * than an incidental byte-equality match against unrelated material.
+     *
+     * Note: the keystore does not currently flag whether an `'encryption-key'`
+     * entry was actually password-derived (vs. random via `addSecret` or raw
+     * via `importSecret`). A `true` result therefore means "the candidate
+     * password produces the same 32 bytes currently stored", which is what
+     * the equivalent consumer-side helper (`verifyGatePassword`) already
+     * implies for entries it manages.
+     *
+     * @param name - Name of the secret to verify against
+     * @param password - Candidate password to test
+     * @param keyDerivation - The key derivation parameters returned by
+     * `addSecretFromPassword` when the secret was created. Only
+     * `kdf: 'pbkdf2'` is supported.
+     * @returns Success(true) when the candidate matches the stored key,
+     * Success(false) when it does not, Failure if locked, secret missing,
+     * wrong type, unsupported `kdf`, or key derivation fails
+     * @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
+     * calls {@link CryptoUtils.KeyStore.IPrivateKeyStorage}.delete on the entry's
+     * `id`; a failure is reported via `warning` on the result but does not roll
+     * back the vault removal.
      * @param name - Name of the secret to remove
-     * @returns Success with removed entry, Failure if not found or locked
+     * @returns Success with removed entry (and optional warning), Failure if not found or locked
      * @public
      */
-    removeSecret(name: string): Result<IKeyStoreSecretEntry>;
+    removeSecret(name: string): Promise<Result<IRemoveSecretResult>>;
     /**
      * Imports an API key string into the vault.
      * The string is UTF-8 encoded and stored with type `'api-key'`.
@@ -1674,7 +4920,7 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * @returns Success with entry, Failure if locked, empty, or exists and !replace
      * @public
      */
-    importApiKey(name: string, apiKey: string, options?: IImportSecretOptions): Result<IAddSecretResult>;
+    importApiKey(name: string, apiKey: string, options?: IImportSecretOptions): Promise<Result<IAddSecretResult>>;
     /**
      * Retrieves an API key string by name.
      * Only works for secrets with type `'api-key'`.
@@ -1683,6 +4929,48 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * @public
      */
     getApiKey(name: string): Result<string>;
+    /**
+     * Adds a new asymmetric keypair to the vault. Storage-first: the private key
+     * is stored under a freshly-minted `id` before the public-key vault entry is
+     * committed. If the storage call fails, no vault entry is written and the
+     * operation returns Failure.
+     *
+     * When `replace: true` displaces an existing entry (asymmetric or symmetric),
+     * a fresh `id` is minted; the displaced entry's resources are released
+     * best-effort. Failure of the storage delete is reported via `warning` on the
+     * result but does not roll back the replacement.
+     *
+     * Requires a {@link CryptoUtils.KeyStore.IPrivateKeyStorage} backend
+     * supplied at construction.
+     *
+     * Extractability of the generated private key defaults to the storage
+     * backend's {@link CryptoUtils.KeyStore.IPrivateKeyStorage.supportsNonExtractable}.
+     * `options.extractable` overrides that default for this key only; requesting
+     * `extractable: false` against a backend that cannot store non-extractable
+     * keys fails loudly rather than silently generating an extractable key.
+     *
+     * @param name - Unique name for the entry
+     * @param options - Algorithm, optional description, replace flag, extractable override
+     * @returns Success with the new entry, Failure if locked, no provider, storage write failed,
+     * or the requested extractability cannot be honored by the backend
+     * @public
+     */
+    addKeyPair(name: string, options: IAddKeyPairOptions): Promise<Result<IAddKeyPairResult>>;
+    /**
+     * Retrieves the keypair for an asymmetric-keypair entry. The private key is
+     * loaded from {@link CryptoUtils.KeyStore.IPrivateKeyStorage} on every call —
+     * the keystore never caches private `CryptoKey` references between calls.
+     * The public key is re-imported from the vault's JWK so callers always
+     * receive a `CryptoKey` rather than the JWK form.
+     * @param name - Name of the entry
+     * @returns Success with `{ publicKey, privateKey }`, Failure if not found,
+     * locked, wrong type, no provider, or storage load failed.
+     * @public
+     */
+    getKeyPair(name: string): Promise<Result<{
+        publicKey: CryptoKey;
+        privateKey: CryptoKey;
+    }>>;
     /**
      * Lists secret names filtered by type.
      * @param type - The secret type to filter by
@@ -1697,7 +4985,7 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * @returns Success with updated entry, Failure if source not found, target exists, or locked
      * @public
      */
-    renameSecret(oldName: string, newName: string): Result<IKeyStoreSecretEntry>;
+    renameSecret(oldName: string, newName: string): Result<IKeyStoreEntry>;
     /**
      * Saves the key store, returning the encrypted file content.
      * Requires the master password to encrypt.
@@ -1706,6 +4994,20 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * @public
      */
     save(password: string): Promise<Result<IKeyStoreFile>>;
+    /**
+     * Saves the key store using a pre-derived key, bypassing PBKDF2 key
+     * derivation. Use this when the derived key has been stored externally
+     * (e.g., in another key store) and the original password is no longer
+     * available.
+     *
+     * The supplied key must be the same key that was (or would be) derived
+     * from the master password using the key store's PBKDF2 parameters.
+     *
+     * @param derivedKey - The pre-derived master key (32 bytes for AES-256)
+     * @returns Success with IKeyStoreFile, Failure if locked or key invalid
+     * @public
+     */
+    saveWithKey(derivedKey: Uint8Array): Promise<Result<IKeyStoreFile>>;
     /**
      * Changes the master password.
      * Re-encrypts the vault with the new password-derived key.
@@ -1730,6 +5032,40 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * @public
      */
     getEncryptionConfig(): Result<Pick<IEncryptionConfig, 'secretProvider' | 'cryptoProvider'>>;
+    /**
+     * Encrypts the vault with a derived key and returns the key store file.
+     * Shared by `save()` and `saveWithKey()`.
+     */
+    private _encryptVault;
+    /**
+     * Decrypts the vault with a derived key and loads secrets into memory.
+     * Shared by `unlock()` and `unlockWithKey()`.
+     */
+    private _decryptVault;
+    /**
+     * Releases the resources held by an entry being displaced from the vault.
+     * Symmetric entries get their key buffer zeroed in place. Asymmetric entries
+     * have their private-key blob best-effort deleted from
+     * {@link CryptoUtils.KeyStore.IPrivateKeyStorage}; if the storage call fails,
+     * a warning string is returned but the displacement still proceeds — the
+     * orphaned blob is left for consumer-side GC. Without a configured provider,
+     * asymmetric cleanup is silently skipped.
+     * @returns A warning string if storage cleanup failed, otherwise undefined.
+     */
+    private _releaseEntryResources;
+    /**
+     * Constant-time byte comparison. Returns false immediately for length
+     * mismatch (length is not secret); for equal-length inputs, walks the full
+     * buffer accumulating differences via XOR so the running time does not leak
+     * the position of the first differing byte.
+     */
+    private static _timingSafeEqual;
+    /**
+     * Mints a fresh UUID v4 storage handle using the crypto provider's
+     * {@link CryptoUtils.ICryptoProvider.generateRandomBytes | generateRandomBytes}.
+     * Random-bytes failures propagate as Failure.
+     */
+    private _generateId;
 }
 
 /**
@@ -1738,6 +5074,31 @@ declare class KeyStore_2 implements IEncryptionProvider {
  */
 declare const KEYSTORE_FORMAT: KeyStoreFormat;
 
+/**
+ * Converter for {@link CryptoUtils.KeyStore.IKeyStoreAsymmetricEntryJson | asymmetric keypair entry} in JSON form.
+ * The `publicKeyJwk` field passes through {@link CryptoUtils.KeyStore.Converters.jsonWebKeyShape | jsonWebKeyShape}
+ * (shape check only — see its docs); cryptographic correctness is enforced by
+ * `crypto.subtle.importKey` at use.
+ * @public
+ */
+declare const keystoreAsymmetricEntryJson: Converter<IKeyStoreAsymmetricEntryJson>;
+
+/**
+ * Discriminator for asymmetric secret types stored in the vault.
+ * - `'asymmetric-keypair'`: A public/private key pair. The public key is held in
+ *   the vault as a JWK; the private key lives in the supplied
+ *   {@link CryptoUtils.KeyStore.IPrivateKeyStorage} provider.
+ * @public
+ */
+declare type KeyStoreAsymmetricSecretType = 'asymmetric-keypair';
+
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreAsymmetricSecretType | asymmetric secret type} discriminator.
+ * Accepts only `'asymmetric-keypair'`.
+ * @public
+ */
+declare const keystoreAsymmetricSecretType: Converter<KeyStoreAsymmetricSecretType>;
+
 /**
  * Converter for {@link CryptoUtils.KeyStore.IKeyStoreFile | encrypted key store file}.
  * @public
@@ -1763,25 +5124,59 @@ declare const keystoreFormat: Converter<KeyStoreFormat>;
 declare type KeyStoreLockState = 'locked' | 'unlocked';
 
 /**
- * Converter for {@link CryptoUtils.KeyStore.IKeyStoreSecretEntryJson | key store secret entry} in JSON format.
- * The `type` field is optional for backwards compatibility — missing means `'encryption-key'`.
+ * Discriminated-union converter for any {@link CryptoUtils.KeyStore.IKeyStoreEntryJson | key store entry} in JSON form.
+ * Routes by the `type` field: `'asymmetric-keypair'` is parsed by
+ * {@link CryptoUtils.KeyStore.Converters.keystoreAsymmetricEntryJson | keystoreAsymmetricEntryJson},
+ * anything else (including a missing `type` field for backwards compatibility) by
+ * {@link CryptoUtils.KeyStore.Converters.keystoreSymmetricEntryJson | keystoreSymmetricEntryJson}.
  * @public
  */
-declare const keystoreSecretEntryJson: Converter<IKeyStoreSecretEntryJson>;
+declare const keystoreSecretEntryJson: Converter<IKeyStoreEntryJson>;
 
 /**
- * Discriminator for secret types stored in the vault.
+ * Discriminator for any secret type stored in the vault.
+ * @public
+ */
+declare type KeyStoreSecretType = KeyStoreSymmetricSecretType | KeyStoreAsymmetricSecretType;
+
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreSecretType | any key store secret type} discriminator.
+ * Accepts both symmetric and asymmetric type values.
+ * @public
+ */
+declare const keystoreSecretType: Converter<KeyStoreSecretType>;
+
+/**
+ * Converter for {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntryJson | symmetric secret entry} in JSON form.
+ *
+ * @remarks
+ * Backwards compatibility with vaults written before asymmetric-keypair
+ * support: those entries may lack the `type` discriminator on the wire. To
+ * keep the model type honest (`type` is required on
+ * {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntryJson}, see its docs),
+ * we declare `type` in `optionalFields` so the inner `Converters.object` will
+ * accept input without it, then `.map()` injects the default
+ * `'encryption-key'` when missing. The output therefore always carries the
+ * discriminator and downstream code never sees the legacy missing-type form.
+ *
+ * @public
+ */
+declare const keystoreSymmetricEntryJson: Converter<IKeyStoreSymmetricEntryJson>;
+
+/**
+ * Discriminator for symmetric secret types stored in the vault.
  * - `'encryption-key'`: A 32-byte AES-256 encryption key.
  * - `'api-key'`: An arbitrary-length API key string (UTF-8 encoded).
  * @public
  */
-declare type KeyStoreSecretType = 'encryption-key' | 'api-key';
+declare type KeyStoreSymmetricSecretType = 'encryption-key' | 'api-key';
 
 /**
- * Converter for {@link CryptoUtils.KeyStore.KeyStoreSecretType | key store secret type} discriminator.
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreSymmetricSecretType | symmetric secret type} discriminator.
+ * Accepts only `'encryption-key'` and `'api-key'`.
  * @public
  */
-declare const keystoreSecretType: Converter<KeyStoreSecretType>;
+declare const keystoreSymmetricSecretType: Converter<KeyStoreSymmetricSecretType>;
 
 /**
  * Converter for {@link CryptoUtils.KeyStore.IKeyStoreVaultContents | key store vault contents} (decrypted state).
@@ -1805,6 +5200,18 @@ declare class Md5Normalizer extends Hash_2.HashingNormalizer {
  */
 declare const MIN_SALT_LENGTH: number;
 
+/**
+ * Marker prefix for an fgv model alias.
+ *
+ * @remarks
+ * A model string is an fgv alias **iff** it begins with this sigil. Everything
+ * else is a raw provider model id and passes through {@link resolveModelAlias}
+ * untouched — this is what keeps the alias layer back-compatible (no current
+ * `defaultModel`, `modelOverride`, or self-hosted `model:tag` id starts with `@`).
+ * @public
+ */
+declare const MODEL_ALIAS_SIGIL: '@';
+
 /**
  * Default context key used as fallback when resolving a {@link ModelSpec}.
  * @public
@@ -1829,7 +5236,7 @@ declare const modelSpec: Converter<ModelSpec>;
  * Known context keys for model specification maps.
  * @public
  */
-declare type ModelSpecKey = 'base' | 'tools' | 'image';
+declare type ModelSpecKey = 'base' | 'advanced' | 'frontier' | 'image' | 'embedding';
 
 /**
  * Converter for {@link ModelSpecKey}.
@@ -1837,18 +5244,98 @@ declare type ModelSpecKey = 'base' | 'tools' | 'image';
  */
 declare const modelSpecKey: Converter<ModelSpecKey>;
 
+/**
+ * Decodes a multibase base64url (no-padding) string back to a `Uint8Array`.
+ *
+ * Validates that the first character is `'m'` (the multibase prefix for
+ * RFC 4648 base64url without padding), then decodes the remaining body.
+ *
+ * @param encoded - A multibase-prefixed base64url string.
+ * @returns `Success` with the decoded bytes, or `Failure` with error context.
+ * @public
+ */
+declare function multibaseBase64UrlDecode(encoded: string): Result<Uint8Array>;
+
+/**
+ * Encodes a `Uint8Array` as a multibase base64url (no-padding) string.
+ *
+ * The multibase prefix `'m'` identifies the encoding as RFC 4648 base64url
+ * without padding. The body uses base64url alphabet: `+` → `-`, `/` → `_`,
+ * and trailing `=` padding is stripped.
+ *
+ * @param data - The binary data to encode.
+ * @returns A multibase-prefixed base64url string (`'m' + base64url-no-pad`).
+ * @public
+ */
+declare function multibaseBase64UrlEncode(data: Uint8Array): string;
+
+/**
+ * A multibase base64url-encoded SPKI (SubjectPublicKeyInfo) public key string —
+ * a `'m'` multibase prefix followed by a base64url-no-pad body. Produced by
+ * {@link CryptoUtils.exportPublicKeyAsMultibaseSpki} and consumed by
+ * {@link CryptoUtils.importPublicKeyFromMultibaseSpki}. Obtain the brand at a
+ * boundary via {@link CryptoUtils.isValidMultibaseSpkiPublicKey} or the
+ * {@link CryptoUtils.Converters.multibaseSpkiPublicKey} converter.
+ * @public
+ */
+declare type MultibaseSpkiPublicKey = Brand<string, 'MultibaseSpkiPublicKey'>;
+
+/**
+ * Converter for {@link CryptoUtils.MultibaseSpkiPublicKey | multibase SPKI public key} strings.
+ * Validates that the value is a string with the `'m'` multibase prefix and a well-formed
+ * base64url-no-pad body, and yields the branded value. Fails with context on a non-string,
+ * bad-prefix, or malformed-body input.
+ * @public
+ */
+declare const multibaseSpkiPublicKey: Converter<MultibaseSpkiPublicKey>;
+
+/**
+ * The structural *shape* of a {@link CryptoUtils.MultibaseSpkiPublicKey}: the
+ * multibase `'m'` prefix followed by a non-empty base64url-no-pad body
+ * (`A-Z`, `a-z`, `0-9`, `-`, `_`).
+ *
+ * This is a shape prefilter, not full validation: it does not decode the DER
+ * SPKI or verify the key material or algorithm (that happens in
+ * {@link CryptoUtils.importPublicKeyFromMultibaseSpki}). The authoritative guard
+ * is {@link CryptoUtils.isValidMultibaseSpkiPublicKey}, which enforces this
+ * pattern **and** additionally rejects a body whose length is an impossible
+ * base64 remainder. Exposed for callers that need the pattern directly (e.g. a
+ * JSON-schema `pattern` field); prefer the guard/converter for validation.
+ *
+ * @public
+ */
+declare const MultibaseSpkiPublicKeyRegExp: RegExp;
+
 declare namespace Mustache {
     export {
         IContextValidationResult,
         IMissingVariableDetail,
         IMustacheTemplateOptions,
         IVariableRef,
+        MustacheEscapeStrategy,
         MustacheTokenType,
         MustacheTemplate
     }
 }
 export { Mustache }
 
+/**
+ * Strategy applied to double-brace `{{name}}` tokens at render time.
+ *
+ * - `'html'`: the standard mustache.js HTML escape (back-compat default).
+ * - `'none'`: verbatim passthrough — values are interpolated as-is
+ *   (coerced to `String`). Suitable for LLM-prompt rendering and other
+ *   non-HTML targets where `& → &amp;` corrupts the output.
+ * - `(value) => string`: caller-supplied escape function.
+ *
+ * Note: triple-brace `{{{name}}}` (and `{{&name}}`) tokens are always
+ * rendered unescaped regardless of this strategy — that is the standard
+ * mustache.js semantics and is not affected by this option.
+ *
+ * @public
+ */
+declare type MustacheEscapeStrategy = 'html' | 'none' | ((value: string) => string);
+
 /**
  * A helper class for working with Mustache templates that provides
  * validation, variable extraction, and context validation utilities.
@@ -1864,6 +5351,8 @@ declare class MustacheTemplate {
      */
     readonly options: Readonly<IRequiredMustacheTemplateOptions>;
     private readonly _tokens;
+    private readonly _writer;
+    private readonly _escapeFn;
     private _variables?;
     private constructor();
     /**
@@ -1971,12 +5460,24 @@ declare class NodeCryptoProvider implements ICryptoProvider {
      * @returns `Success` with derived 32-byte key, or `Failure` with an error.
      */
     deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<Result<Uint8Array>>;
+    /**
+     * Computes a SHA-256 hash of the given data.
+     * @param data - UTF-8 string to hash
+     * @returns `Success` with hex-encoded hash string, or `Failure` with an error.
+     */
+    sha256(data: string): Promise<Result<string>>;
     /**
      * Generates cryptographically secure random bytes.
      * @param length - Number of bytes to generate
      * @returns Success with random bytes, or Failure with error
      */
     generateRandomBytes(length: number): Result<Uint8Array>;
+    /**
+     * Generates a cryptographically random UUIDv4 via the platform Web Crypto API.
+     * @returns `Success` with the generated UUID, or `Failure` if the runtime
+     * does not expose `globalThis.crypto.randomUUID`.
+     */
+    generateUuid(): Result<Uuid>;
     /**
      * Encodes binary data to base64 string.
      * @param data - Binary data to encode
@@ -1989,6 +5490,102 @@ declare class NodeCryptoProvider implements ICryptoProvider {
      * @returns Success with decoded bytes, or Failure if invalid base64
      */
     fromBase64(base64: string): Result<Uint8Array>;
+    /**
+     * Generates a new asymmetric keypair using Node's WebCrypto.
+     * @param algorithm - The {@link CryptoUtils.KeyPairAlgorithm | algorithm} to use.
+     * @param extractable - Whether the resulting keys may be exported.
+     * @returns `Success` with the generated `CryptoKeyPair`, or `Failure` with an error.
+     */
+    generateKeyPair(algorithm: KeyPairAlgorithm, extractable: boolean): Promise<Result<CryptoKeyPair>>;
+    /**
+     * Exports a public `CryptoKey` as a JSON Web Key.
+     * @remarks
+     * Rejects non-public keys at runtime. WebCrypto's `exportKey('jwk', ...)`
+     * does not enforce public-vs-private; without this guard a caller that
+     * passed an extractable private key would receive its private fields
+     * (`d`, `p`, `q`, ...) as JWK, defeating the method's name.
+     * @param publicKey - Extractable public key to export.
+     * @returns `Success` with the JWK, or `Failure` if not a public key or if export fails.
+     */
+    exportPublicKeyJwk(publicKey: CryptoKey): Promise<Result<JsonWebKey>>;
+    /**
+     * Imports a public-key JWK as a `CryptoKey` for the requested algorithm.
+     * @param jwk - The JSON Web Key produced by a prior export.
+     * @param algorithm - The algorithm the key was generated for.
+     * @returns `Success` with the imported public `CryptoKey`, or `Failure` with an error.
+     */
+    importPublicKeyJwk(jwk: JsonWebKey, algorithm: KeyPairAlgorithm): Promise<Result<CryptoKey>>;
+    /**
+     * Exports a public `CryptoKey` as a DER-encoded SPKI blob.
+     * @param publicKey - The public `CryptoKey` to export.
+     * @returns `Success` with the raw SPKI bytes, or `Failure` with error context.
+     */
+    exportPublicKeySpki(publicKey: CryptoKey): Promise<Result<Uint8Array>>;
+    /**
+     * Imports a public key from a DER-encoded SPKI blob.
+     * @param spkiBytes - The raw SPKI bytes.
+     * @param algorithm - The algorithm the key was generated for.
+     * @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
+     * {@link CryptoUtils.ICryptoProvider.wrapBytes | ICryptoProvider.wrapBytes}.
+     * @param plaintext - The bytes to wrap.
+     * @param recipientPublicKey - The recipient's ECDH P-256 public `CryptoKey`.
+     * @param options - HKDF salt and info; see {@link CryptoUtils.IWrapBytesOptions | IWrapBytesOptions}.
+     * @returns `Success` with the wrapped payload, or `Failure` with an error.
+     */
+    wrapBytes(plaintext: Uint8Array, recipientPublicKey: CryptoKey, options: IWrapBytesOptions): Promise<Result<IWrappedBytes>>;
+    /**
+     * Unwraps a payload produced by `wrapBytes` using the recipient's private
+     * key. See {@link CryptoUtils.ICryptoProvider.unwrapBytes | ICryptoProvider.unwrapBytes}.
+     * @param wrapped - The wrapped payload.
+     * @param recipientPrivateKey - The recipient's ECDH P-256 private `CryptoKey`.
+     * @param options - HKDF salt and info matching the wrap call.
+     * @returns `Success` with the original `plaintext`, or `Failure` with an error.
+     */
+    unwrapBytes(wrapped: IWrappedBytes, recipientPrivateKey: CryptoKey, options: IWrapBytesOptions): Promise<Result<Uint8Array>>;
 }
 
 /**
@@ -1997,6 +5594,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.4-mini' | 'gpt-5.5' | 'gpt-5.5-pro' | 'gpt-5-pro';
+
 /**
  * Parses CSV data from a string.
  * @param body - The CSV string to parse.
@@ -2016,6 +5619,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.
@@ -2193,11 +5802,11 @@ declare function readRecordJarFromTree(fileTree: FileTree.FileTree, filePath: st
 declare namespace RecordJar {
     export {
         parseRecordJarLines,
+        readRecordJarFromTree,
         JarRecord,
         JarFieldPicker,
         JarRecordParserOptions,
-        readRecordJarFileSync,
-        readRecordJarFromTree
+        readRecordJarFileSync
     }
 }
 export { RecordJar }
@@ -2218,29 +5827,155 @@ export { RecordJar }
  */
 declare function resolveEffectiveTools(descriptor: IAiProviderDescriptor, settingsTools?: ReadonlyArray<IAiToolEnablement>, perCallTools?: ReadonlyArray<AiServerToolConfig>): ReadonlyArray<AiServerToolConfig>;
 
+/**
+ * Resolve the embedding capability that applies to a given model id for a
+ * provider. Returns the entry from {@link IAiProviderDescriptor.embedding} whose
+ * `modelPrefix` is the longest prefix of `modelId`. Ties are broken by
+ * first-encountered.
+ *
+ * @param descriptor - The provider descriptor
+ * @param modelId - The resolved embedding model id
+ * @returns The matching capability, or `undefined` when no rule matches or the
+ *   provider declares no embedding capabilities.
+ * @public
+ */
+declare function resolveEmbeddingCapability(descriptor: IAiProviderDescriptor, modelId: string): IAiEmbeddingModelCapability | undefined;
+
+/**
+ * Resolve the image-generation capability that applies to a given model id
+ * for a provider. Returns the entry from
+ * {@link IAiProviderDescriptor.imageGeneration} whose `modelPrefix` is the
+ * longest prefix of `modelId`. Ties are broken by first-encountered, so rule
+ * order does not matter for correctness — only for tie-breaking among rules
+ * with identical-length prefixes (an unusual case).
+ *
+ * @param descriptor - The provider descriptor
+ * @param modelId - The resolved image model id
+ * @returns The matching capability, or `undefined` when no rule matches or
+ *   the provider declares no image-generation capabilities.
+ * @public
+ */
+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.
  *
  * @remarks
  * Resolution rules:
  * 1. If the spec is a string, return it directly (context is irrelevant).
- * 2. If the spec is an object and the context key exists, recurse into that branch.
+ * 2. If the spec is an object, walk the ordered candidate keys for the context:
+ *    a quality-tier context (`advanced`/`frontier`) cascades through the
+ *    tier-fallback table (`frontier → advanced → base`, `advanced → base`);
+ *    every other context resolves flat (`[context]`); `undefined` resolves to
+ *    the shared `base` fallback. The first present key wins.
  * 3. Otherwise, fall back to the {@link MODEL_SPEC_BASE_KEY | 'base'} key.
  * 4. If neither context nor `'base'` exists, use the first available value.
  *
  * @param spec - The model specification to resolve
- * @param context - Optional context key (e.g. `'tools'`)
+ * @param context - Optional context key (e.g. `'advanced'`)
  * @returns The resolved model string
  * @public
  */
 declare function resolveModel(spec: ModelSpec, context?: string): string;
 
+/**
+ * Resolves a single (possibly-aliased) model string against a provider descriptor.
+ *
+ * @remarks
+ * Resolution rules:
+ * 1. No leading {@link MODEL_ALIAS_SIGIL} → raw provider id, returned verbatim.
+ * 2. Leading sigil + registered in `descriptor.aliases` → the registered target,
+ *    which is itself resolved — so a chain of `@` aliases is followed until a
+ *    non-`@` (concrete provider) id is reached. The canonical case is a single
+ *    hop (an fgv alias targeting a provider-native alias), but longer chains
+ *    resolve too.
+ * 3. Leading sigil + unregistered → fails loudly, naming the provider and alias.
+ *
+ * An `@`→`@` cycle is guarded by a visited-set and fails rather than exhausting
+ * the stack.
+ *
+ * @param descriptor - The provider descriptor whose `aliases` map is consulted.
+ * @param model - The (possibly-aliased) model string to resolve.
+ * @returns `Result` with the concrete provider model id, or a failure.
+ * @public
+ */
+declare function resolveModelAlias(descriptor: IAiProviderDescriptor, model: string): Result<string>;
+
+/**
+ * The full provider model-resolution chokepoint: the {@link ModelSpecKey} walk
+ * (via {@link resolveModel}) THEN {@link resolveModelAlias}.
+ *
+ * @remarks
+ * Replaces the bare `resolveModel(modelOverride ?? descriptor.defaultModel, context)`
+ * call plus the duplicated empty-result check at each call-time chokepoint. The
+ * `ModelSpec` branch is selected first; the resulting string — which may itself
+ * be an fgv alias — is then resolved to a concrete id.
+ *
+ * @param descriptor - The provider descriptor (supplies `defaultModel` and `aliases`).
+ * @param modelOverride - An optional caller-supplied `ModelSpec` that takes precedence
+ * over `descriptor.defaultModel`. May itself contain or be an alias.
+ * @param context - Optional {@link ModelSpecKey} selecting the spec branch.
+ * @returns `Result` with the concrete provider model id, or a failure.
+ * @public
+ */
+declare function resolveProviderModel(descriptor: IAiProviderDescriptor, modelOverride: ModelSpec | undefined, context?: ModelSpecKey): Result<string>;
+
 /**
  * Function type for dynamic secret retrieval.
  * @public
  */
 declare type SecretProvider = (secretName: string) => Promise<Result<Uint8Array>>;
 
+/**
+ * Default system-prompt suffix appended when {@link AiAssist.IGenerateJsonCompletionParams.promptHint}
+ * is `'smart'` (the default). Designed to discourage code fences and prose in
+ * the model's response while still tolerating them via the read-side extractor.
+ * @public
+ */
+declare const SMART_JSON_PROMPT_HINT: string;
+
+/**
+ * Whether a provider declares any embedding capability at all.
+ *
+ * @param descriptor - The provider descriptor
+ * @returns `true` when {@link IAiProviderDescriptor.embedding} has at least one
+ *   entry; `false` otherwise.
+ * @public
+ */
+declare function supportsEmbedding(descriptor: IAiProviderDescriptor): boolean;
+
+/**
+ * Whether a provider declares any image-generation capability at all.
+ *
+ * @param descriptor - The provider descriptor
+ * @returns `true` when {@link IAiProviderDescriptor.imageGeneration} has at
+ *   least one entry; `false` otherwise.
+ * @public
+ */
+declare function supportsImageGeneration(descriptor: IAiProviderDescriptor): boolean;
+
 /**
  * Helper function to create a `StringConverter` which converts
  * `unknown` to `string`, applying template conversions supplied at construction time or at
@@ -2261,6 +5996,14 @@ declare function templateString(defaultContext?: unknown): Conversion.StringConv
  */
 declare function toBase64(bytes: Uint8Array): string;
 
+/**
+ * Formats an {@link IAiImageData} as a `data:` URL suitable for browser display.
+ * @param image - The image to format
+ * @returns A `data:<mime>;base64,<data>` URL string
+ * @public
+ */
+declare function toDataUrl(image: IAiImageData): string;
+
 /**
  * Attempts to parse and decrypt a JSON object as an {@link CryptoUtils.IEncryptedFile | encrypted file}.
  * @typeParam TPayload - Expected type of decrypted content
@@ -2281,9 +6024,32 @@ 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
+        yamlConverter,
+        yamlStringify,
+        IYamlSerializeOptions
     }
 }
 export { Yaml }
@@ -2296,6 +6062,15 @@ export { Yaml }
  */
 declare function yamlConverter<T>(converter: Converter<T>): Converter<T>;
 
+/**
+ * Serializes a value to a YAML string.
+ * @param value - The value to serialize (must be an object or array)
+ * @param options - Optional serialization options
+ * @returns `Success` with YAML string, or `Failure` with error
+ * @public
+ */
+declare function yamlStringify(value: unknown, options?: IYamlSerializeOptions): Result<string>;
+
 /**
  * Supported compression levels for zip files.
  * @public
@@ -2449,8 +6224,8 @@ declare class ZipFileTreeAccessors<TCT extends string = string> implements FileT
     private constructor();
     /**
      * Default function to infer the content type of a file.
-     * @param filePath - The path of the file.
-     * @param provided - Optional supplied content type.
+     * @param __filePath - The path of the file.
+     * @param __provided - Optional supplied content type.
      * @returns `Success` with the content type of the file if successful, or
      * `Failure` with an error message otherwise.
      * @remarks This default implementation always returns `Success` with `undefined`.