@fgv/ts-extras 5.1.0-18 → 5.1.0-19

package/dist/ts-extras.d.ts

@@ -33,6 +33,7 @@ declare namespace AiAssist {
         IChatMessage,
         AiApiFormat,
         AiImageApiFormat,
+        IAiImageModelCapability,
         IAiProviderDescriptor,
         IAiAssistProviderConfig,
         IAiAssistSettings,
@@ -62,6 +63,8 @@ declare namespace AiAssist {
         allProviderIds,
         getProviderDescriptors,
         getProviderDescriptor,
+        resolveImageCapability,
+        supportsImageGeneration,
         DEFAULT_MODEL_CAPABILITY_CONFIG,
         callProviderCompletion,
         callProxiedCompletion,
@@ -103,9 +106,20 @@ 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';
+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
@@ -277,12 +291,17 @@ declare function callProviderCompletionStream(params: IProviderCompletionStreamP
 /**
  * Calls the appropriate image-generation API for a given provider.
  *
- * Routes based on `descriptor.imageApiFormat`:
+ * 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
+ * - `'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
@@ -353,7 +372,10 @@ declare function callProxiedCompletionStream(proxyUrl: string, params: IProvider
  * - Error response body: `{error: string}` (surfaced as `proxy: ${error}`)
  *
  * The proxy server is responsible for descriptor lookup, model resolution,
- * provider dispatch, and response normalization.
+ * 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}
@@ -480,6 +502,8 @@ declare namespace CryptoUtils {
         INamedSecret,
         IEncryptionResult,
         KeyPairAlgorithm,
+        IWrapBytesOptions,
+        IWrappedBytes,
         allKeyPairAlgorithms,
         KeyDerivationFunction,
         IKeyDerivationParams,
@@ -1119,6 +1143,16 @@ declare interface IAiImageGenerationParams {
     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>;
 }
 
 /**
@@ -1130,6 +1164,35 @@ declare interface IAiImageGenerationResponse {
     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
@@ -1218,15 +1281,27 @@ declare interface IAiProviderDescriptor {
      */
     readonly acceptsImageInput: boolean;
     /**
-     * Which image-generation API format this provider uses, or undefined if it
-     * does not support image generation.
+     * 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 with `imageApiFormat` set should declare a model in
+     * Providers that declare `imageGeneration` should declare a model in
      * `defaultModel.image`, e.g. `{ base: 'gpt-4o', image: 'dall-e-3' }`.
      */
-    readonly imageApiFormat?: AiImageApiFormat;
+    readonly imageGeneration?: ReadonlyArray<IAiImageModelCapability>;
 }
 
 /**
@@ -1495,6 +1570,47 @@ declare interface ICryptoProvider {
      * @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>>;
 }
 
 /**
@@ -2285,6 +2401,59 @@ 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
@@ -3149,6 +3318,25 @@ declare class NodeCryptoProvider implements ICryptoProvider {
      * @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>>;
 }
 
 /**
@@ -3378,6 +3566,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.
  *
@@ -3401,6 +3605,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

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

@@ -66,12 +66,17 @@ export interface IProviderImageGenerationParams {
 /**
  * Calls the appropriate image-generation API for a given provider.
  *
- * Routes based on `descriptor.imageApiFormat`:
+ * 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
+ * - `'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
@@ -151,7 +156,10 @@ export declare function callProxiedCompletion(proxyUrl: string, params: IProvide
  * - Error response body: `{error: string}` (surfaced as `proxy: ${error}`)
  *
  * The proxy server is responsible for descriptor lookup, model resolution,
- * provider dispatch, and response normalization.
+ * 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}