@fgv/ts-extras 5.1.0-2 → 5.1.0-20

package/dist/ts-extras.d.ts

@@ -1,5 +1,6 @@
 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 { JsonValue } from '@fgv/ts-json-base';
@@ -22,6 +23,7 @@ declare type AiApiFormat = 'openai' | 'anthropic' | 'gemini';
 declare namespace AiAssist {
     export {
         AiPrompt,
+        AiModelCapability,
         AiProviderId,
         AiServerToolType,
         AiServerToolConfig,
@@ -30,23 +32,52 @@ declare namespace AiAssist {
         IAiCompletionResponse,
         IChatMessage,
         AiApiFormat,
+        AiImageApiFormat,
+        IAiImageModelCapability,
         IAiProviderDescriptor,
         IAiAssistProviderConfig,
         IAiAssistSettings,
         DEFAULT_AI_ASSIST,
         IAiAssistKeyStore,
+        IAiImageAttachment,
+        IAiImageData,
+        IAiImageGenerationOptions,
+        IAiImageGenerationParams,
+        IAiGeneratedImage,
+        IAiImageGenerationResponse,
+        IAiModelCapabilityRule,
+        IAiModelCapabilityConfig,
+        IAiModelInfo,
+        IAiStreamEvent,
+        IAiStreamTextDelta,
+        IAiStreamToolEvent,
+        IAiStreamDone,
+        IAiStreamError,
         ModelSpec,
         ModelSpecKey,
         IModelSpecMap,
         allModelSpecKeys,
         MODEL_SPEC_BASE_KEY,
         resolveModel,
+        toDataUrl,
         allProviderIds,
         getProviderDescriptors,
         getProviderDescriptor,
+        resolveImageCapability,
+        supportsImageGeneration,
+        DEFAULT_MODEL_CAPABILITY_CONFIG,
         callProviderCompletion,
         callProxiedCompletion,
+        callProviderImageGeneration,
+        callProxiedImageGeneration,
+        callProviderListModels,
+        callProxiedListModels,
         IProviderCompletionParams,
+        IProviderImageGenerationParams,
+        IProviderListModelsParams,
+        callProviderCompletionStream,
+        callProxiedCompletionStream,
+        IProviderCompletionStreamParams,
         aiProviderId,
         aiServerToolType,
         aiWebSearchToolConfig,
@@ -73,6 +104,36 @@ declare const aiAssistProviderConfig: Converter<IAiAssistProviderConfig>;
  */
 declare const aiAssistSettings: Converter<IAiAssistSettings>;
 
+/**
+ * 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. Same wire shape as OpenAI but text-only;
+ *   no reference-image support on grok-2-image.
+ * - `'gemini-imagen'` — Google Imagen `:predict` endpoint. Text-only.
+ * - `'gemini-image-out'` — Google Gemini chat-style `:generateContent`
+ *   endpoint that returns image parts (Gemini 2.5 Flash Image / "Nano
+ *   Banana"). Accepts reference images.
+ *
+ * @public
+ */
+declare type AiImageApiFormat = 'openai-images' | 'gemini-imagen' | 'xai-images' | 'gemini-image-out';
+
+/**
+ * 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';
+
 /**
  * A structured AI prompt with system/user split for direct API calls,
  * and a lazily-constructed combined version for copy/paste workflows.
@@ -83,8 +144,18 @@ 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;
 }
 
@@ -136,12 +207,30 @@ 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 {@link ModelSpecKey} values.
  * @public
@@ -179,6 +268,60 @@ declare const base64String: Converter<string>;
  */
 declare function callProviderCompletion(params: IProviderCompletionParams): Promise<Result<IAiCompletionResponse>>;
 
+/**
+ * Calls the appropriate streaming chat completion API for a given provider.
+ *
+ * @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.
+ *
+ * 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 A streaming iterable of unified events, or a Result.fail
+ * @public
+ */
+declare function callProviderCompletionStream(params: IProviderCompletionStreamParams): Promise<Result<AsyncIterable<IAiStreamEvent>>>;
+
+/**
+ * Calls the appropriate image-generation API for a given provider.
+ *
+ * Resolves a {@link IAiImageModelCapability} from
+ * {@link IAiProviderDescriptor.imageGeneration} for the requested model and
+ * routes by its `format`:
+ * - `'openai-images'` for OpenAI (DALL-E, gpt-image-1)
+ * - `'xai-images'` for xAI Grok image models
+ * - `'gemini-imagen'` for Google Imagen `:predict`
+ * - `'gemini-image-out'` for Gemini chat-style image output (Nano Banana)
+ *
+ * Image-model selection reuses the existing `'image'` {@link ModelSpecKey}.
+ * When `request.referenceImages` is non-empty, the call is rejected up front
+ * unless the resolved capability declares `acceptsImageReferenceInput`.
+ *
+ * @param params - Request parameters including descriptor, API key, and prompt
+ * @returns The generated images, or a failure
+ * @public
+ */
+declare function callProviderImageGeneration(params: IProviderImageGenerationParams): Promise<Result<IAiImageGenerationResponse>>;
+
+/**
+ * Lists models available from a provider, with capabilities resolved from
+ * native provider info (where supplied) and a configurable rule set.
+ *
+ * Routes based on `descriptor.apiFormat` — listing reuses the existing
+ * format dispatch and does not require a separate descriptor field.
+ *
+ * @param params - Request parameters including descriptor, API key, and optional capability filter
+ * @returns The resolved model list, or a failure
+ * @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.
@@ -194,6 +337,71 @@ declare function callProviderCompletion(params: IProviderCompletionParams): Prom
  */
 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 image-generation endpoint on a proxy server instead of calling
+ * the provider API directly from the browser.
+ *
+ * @remarks
+ * The proxy contract:
+ * - Endpoint: `POST ${proxyUrl}/api/ai/image-generation`
+ * - Request body: `{providerId, apiKey, params, modelOverride?}`
+ * - Success response body: an {@link IAiImageGenerationResponse}
+ * - Error response body: `{error: string}` (surfaced as `proxy: ${error}`)
+ *
+ * The proxy server is responsible for descriptor lookup, model resolution,
+ * provider dispatch, and response normalization. When `params.referenceImages`
+ * is present, the proxy is also responsible for repackaging it into the
+ * upstream wire format (e.g. multipart/form-data for OpenAI `/images/edits`,
+ * `inlineData` parts for Gemini `:generateContent`).
+ *
+ * @param proxyUrl - Base URL of the proxy server (e.g. `http://localhost:3001`)
+ * @param params - Same parameters as {@link callProviderImageGeneration}
+ * @returns The generated images, or a failure
+ * @public
+ */
+declare function callProxiedImageGeneration(proxyUrl: string, params: IProviderImageGenerationParams): Promise<Result<IAiImageGenerationResponse>>;
+
+/**
+ * Calls the model-listing endpoint on a proxy server.
+ *
+ * @remarks
+ * Proxy contract:
+ * - Endpoint: `POST ${proxyUrl}/api/ai/list-models`
+ * - Request body: `{providerId, apiKey, capability?}`. Capability config is
+ *   not forwarded — the proxy applies its own (typically the same default
+ *   the library ships).
+ * - Success response body: an `IAiModelInfo[]` (under key `models`) where
+ *   `capabilities` is serialized as a string array (not Set, which doesn't
+ *   round-trip through JSON).
+ * - Error response body: `{error: string}`, surfaced as `proxy: ${error}`.
+ *
+ * @public
+ */
+declare function callProxiedListModels(proxyUrl: string, params: IProviderListModelsParams): Promise<Result<ReadonlyArray<IAiModelInfo>>>;
+
 declare namespace Constants {
     export {
         ENCRYPTED_FILE_FORMAT,
@@ -210,7 +418,8 @@ declare namespace Converters {
         extendedArrayOf,
         rangeTypeOf,
         rangeOf,
-        isoDate
+        isoDate,
+        isoDateTime
     }
 }
 export { Converters }
@@ -219,6 +428,12 @@ declare namespace Converters_2 {
     export {
         keystoreFormat,
         keystoreSecretType,
+        keystoreSymmetricSecretType,
+        keystoreAsymmetricSecretType,
+        keyPairAlgorithm,
+        jsonWebKeyShape,
+        keystoreSymmetricEntryJson,
+        keystoreAsymmetricEntryJson,
         keystoreSecretEntryJson,
         keystoreVaultContents,
         keystoreFile
@@ -271,6 +486,8 @@ declare namespace CryptoUtils {
         Converters_3 as Converters,
         DirectEncryptionProvider,
         IDirectEncryptionProviderParams,
+        IKeyPairAlgorithmParams,
+        keyPairAlgorithmParams,
         NodeCryptoProvider,
         nodeCryptoProvider,
         createEncryptedFile,
@@ -284,6 +501,10 @@ declare namespace CryptoUtils {
         EncryptedFileFormat,
         INamedSecret,
         IEncryptionResult,
+        KeyPairAlgorithm,
+        IWrapBytesOptions,
+        IWrappedBytes,
+        allKeyPairAlgorithms,
         KeyDerivationFunction,
         IKeyDerivationParams,
         IEncryptedFile,
@@ -345,6 +566,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>}.
@@ -532,7 +763,7 @@ 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>;
@@ -650,6 +881,50 @@ declare namespace Hash {
 }
 export { Hash }
 
+/**
+ * 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;
+}
+
+/**
+ * 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 a secret derived from a password.
  * @public
@@ -700,11 +975,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;
 }
 
 /**
@@ -762,6 +1045,201 @@ declare interface IAiCompletionResponse {
     readonly truncated: boolean;
 }
 
+/**
+ * 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
+ * Provider compatibility is documented per field. The library does not
+ * pre-validate against per-model constraints (e.g. `dall-e-3` rejects
+ * `count > 1`); provider 400 errors surface through the failure path.
+ *
+ * @public
+ */
+declare interface IAiImageGenerationOptions {
+    /**
+     * Image dimensions. Used by openai-format providers (mapped to the
+     * provider's `size` field). Ignored by Imagen — use
+     * {@link IAiImageGenerationOptions.imagen} `aspectRatio` instead.
+     *
+     * Note: each model has its own accepted set; `dall-e-3` only accepts the
+     * values listed here.
+     */
+    readonly size?: '1024x1024' | '1024x1792' | '1792x1024' | 'auto';
+    /**
+     * Number of images to generate. Default 1.
+     *
+     * Note: `dall-e-3` rejects `count > 1`.
+     */
+    readonly count?: number;
+    /** Generation quality hint where supported. */
+    readonly quality?: 'standard' | 'high';
+    /** Random seed for reproducibility, where supported. */
+    readonly seed?: number;
+    /**
+     * Imagen-specific options. Ignored by other providers.
+     */
+    readonly imagen?: {
+        readonly negativePrompt?: string;
+        readonly aspectRatio?: '1:1' | '3:4' | '4:3' | '9:16' | '16:9';
+    };
+}
+
+/**
+ * Parameters for an image-generation request.
+ * @public
+ */
+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.
+     *
+     * @remarks
+     * Per-model constraints beyond ref support (e.g. dall-e-3 ignores edits)
+     * are not validated here and surface as provider 400s, consistent with the
+     * existing image-generation policy.
+     */
+    readonly acceptsImageReferenceInput?: boolean;
+}
+
+/**
+ * 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
@@ -785,6 +1263,111 @@ declare interface IAiProviderDescriptor {
     readonly supportedTools: ReadonlyArray<AiServerToolType>;
     /** Whether this provider's API enforces CORS restrictions that prevent direct browser calls. */
     readonly corsRestricted: boolean;
+    /**
+     * Whether this provider's streaming completion endpoint requires a proxy
+     * for direct browser calls. Some providers gate streaming separately from
+     * non-streaming (rare), so this is tracked independently from
+     * {@link IAiProviderDescriptor.corsRestricted}.
+     *
+     * @remarks
+     * When `true`, `callProviderCompletionStream` rejects up front unless the
+     * call is being routed through a proxy.
+     */
+    readonly streamingCorsRestricted: boolean;
+    /**
+     * Whether this provider's chat completions API accepts image input
+     * (i.e. supports vision prompts). When false, calls with
+     * `prompt.attachments` are rejected up front.
+     */
+    readonly acceptsImageInput: boolean;
+    /**
+     * 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. Google Gemini is the canonical case: the
+     * `imagen-*` family is predict-only via `:predict`, while
+     * `gemini-2.5-flash-image` uses chat-style `:generateContent` and accepts
+     * reference images. Listing both lets callers pick the right model and the
+     * dispatcher routes accordingly.
+     *
+     * Image-model selection reuses the existing `image` {@link ModelSpecKey}.
+     * Providers that declare `imageGeneration` should declare a model in
+     * `defaultModel.image`, e.g. `{ base: 'gpt-4o', image: 'dall-e-3' }`.
+     */
+    readonly imageGeneration?: ReadonlyArray<IAiImageModelCapability>;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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.
+ * @public
+ */
+declare type IAiStreamEvent = IAiStreamTextDelta | IAiStreamToolEvent | 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;
 }
 
 /**
@@ -937,6 +1520,12 @@ 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
@@ -955,6 +1544,73 @@ 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>>;
+    /**
+     * 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>>;
 }
 
 /**
@@ -1093,6 +1749,19 @@ declare interface IEncryptionResult {
     readonly encryptedData: 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
@@ -1113,15 +1782,120 @@ declare interface IKeyDerivationParams {
     /**
      * Key derivation function used.
      */
-    readonly kdf: KeyDerivationFunction;
+    readonly kdf: KeyDerivationFunction;
+    /**
+     * Base64-encoded salt used for key derivation.
+     */
+    readonly salt: string;
+    /**
+     * Number of iterations used for key derivation.
+     */
+    readonly iterations: number;
+}
+
+/**
+ * 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 IKeyPairAlgorithmParams {
+    /**
+     * Algorithm parameters for `crypto.subtle.generateKey`. Always an asymmetric
+     * variant — these algorithms produce a `CryptoKeyPair`, not a single key.
+     */
+    readonly generateKey: RsaHashedKeyGenParams | EcKeyGenParams;
+    /**
+     * Algorithm parameters for `crypto.subtle.importKey('jwk', ...)` when
+     * importing the public half of a keypair.
+     */
+    readonly importPublicKey: RsaHashedImportParams | EcKeyImportParams;
+    /**
+     * Default key usages for the generated `CryptoKeyPair`. Both halves receive
+     * the usages WebCrypto considers valid for their role; the platform filters.
+     */
+    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;
     /**
-     * Base64-encoded salt used for key derivation.
+     * Optional description.
      */
-    readonly salt: string;
+    readonly description?: string;
     /**
-     * Number of iterations used for key derivation.
+     * When this entry was added (ISO 8601).
      */
-    readonly iterations: number;
+    readonly createdAt: string;
 }
 
 /**
@@ -1137,8 +1911,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
@@ -1183,22 +1975,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 interface IKeyStoreSecretEntry {
+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 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 +2032,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 +2075,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 +2084,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>;
 }
 
 /**
@@ -1338,6 +2169,55 @@ declare interface INamedSecret {
     readonly key: Uint8Array;
 }
 
+/**
+ * Pluggable backend that persists raw asymmetric private keys outside of the
+ * encrypted keystore vault. Concrete implementations live in platform-specific
+ * packages (e.g. an IndexedDB-backed implementation in `@fgv/ts-web-extras` or
+ * an encrypted-file implementation in `@fgv/ts-chocolate`).
+ *
+ * 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.
  * @public
@@ -1362,6 +2242,97 @@ declare interface IProviderCompletionParams {
     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;
+}
+
+/**
+ * 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.
+ *
+ * @public
+ */
+declare interface IProviderCompletionStreamParams {
+    /** The provider descriptor */
+    readonly descriptor: IAiProviderDescriptor;
+    /** API key for authentication */
+    readonly apiKey: string;
+    /** The structured prompt to send */
+    readonly prompt: AiPrompt;
+    /**
+     * Prior conversation history to insert between the system prompt and the
+     * prompt's user message. The new user turn (carried by `prompt.user`) is
+     * always sent last, so the wire shape becomes
+     * `[system, ...messagesBefore, user=prompt.user]`.
+     */
+    readonly messagesBefore?: ReadonlyArray<IChatMessage>;
+    /** Sampling temperature (default: 0.7) */
+    readonly temperature?: number;
+    /** Optional model override — string or context-aware map. */
+    readonly modelOverride?: ModelSpec;
+    /** 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
 }
 
 /**
@@ -1399,6 +2370,13 @@ 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>;
+
 /**
  * Represents a variable reference extracted from a Mustache template.
  * @public
@@ -1423,6 +2401,95 @@ 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;
+}
+
+/**
+ * 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,6 +2519,24 @@ declare interface JarRecordParserOptions {
     readonly fixedContinuationSize?: number;
 }
 
+/**
+ * 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
@@ -1470,18 +2555,58 @@ declare const keyDerivationFunction: Converter<KeyDerivationFunction>;
  */
 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}).
+ * @public
+ */
+declare type KeyPairAlgorithm = 'ecdsa-p256' | 'rsa-oaep-2048' | 'ecdh-p256';
+
+/**
+ * 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,
         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 +2616,14 @@ declare namespace KeyStore {
         IAddSecretResult,
         IAddSecretOptions,
         IImportSecretOptions,
+        IImportKeyOptions,
         IAddSecretFromPasswordOptions,
         DEFAULT_SECRET_ITERATIONS,
-        IAddSecretFromPasswordResult
+        IAddSecretFromPasswordResult,
+        IAddKeyPairOptions,
+        IAddKeyPairResult,
+        IRemoveSecretResult,
+        IPrivateKeyStorage
     }
 }
 
@@ -1530,6 +2660,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 +2702,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 +2759,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 +2792,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 +2822,16 @@ declare class KeyStore_2 implements IEncryptionProvider {
      */
     addSecretFromPassword(name: string, password: string, options?: IAddSecretFromPasswordOptions): Promise<Result<IAddSecretFromPasswordResult>>;
     /**
-     * Removes a secret by name.
+     * 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 +2841,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 +2850,41 @@ 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.
+     *
+     * @param name - Unique name for the entry
+     * @param options - Algorithm, optional description, replace flag
+     * @returns Success with the new entry, Failure if locked, no provider, or storage write failed
+     * @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 +2899,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 +2908,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 +2946,33 @@ 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;
+    /**
+     * 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 +2981,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 +3031,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<IKeyStoreEntryJson>;
+
+/**
+ * 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 keystoreSecretEntryJson: Converter<IKeyStoreSecretEntryJson>;
+declare const keystoreSymmetricEntryJson: Converter<IKeyStoreSymmetricEntryJson>;
 
 /**
- * Discriminator for secret types stored in the vault.
+ * 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).
@@ -1971,6 +3273,12 @@ 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
@@ -1989,6 +3297,50 @@ 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>>;
+    /**
+     * 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>>;
 }
 
 /**
@@ -2218,6 +3570,22 @@ export { RecordJar }
  */
 declare function resolveEffectiveTools(descriptor: IAiProviderDescriptor, settingsTools?: ReadonlyArray<IAiToolEnablement>, perCallTools?: ReadonlyArray<AiServerToolConfig>): ReadonlyArray<AiServerToolConfig>;
 
+/**
+ * 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 a {@link ModelSpec} to a concrete model string given an optional context key.
  *
@@ -2241,6 +3609,16 @@ declare function resolveModel(spec: ModelSpec, context?: string): string;
  */
 declare type SecretProvider = (secretName: string) => Promise<Result<Uint8Array>>;
 
+/**
+ * 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 +3639,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
@@ -2283,7 +3669,9 @@ declare const uint8ArrayFromBase64: Converter<Uint8Array>;
 
 declare namespace Yaml {
     export {
-        yamlConverter
+        yamlConverter,
+        yamlStringify,
+        IYamlSerializeOptions
     }
 }
 export { Yaml }
@@ -2296,6 +3684,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 +3846,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`.