@fgv/ts-extras 5.1.0-36 → 5.1.0-39

package/dist/ts-extras.d.ts

@@ -1,3 +1,4 @@
+import { Brand } from '@fgv/ts-utils';
 import { Conversion } from '@fgv/ts-utils';
 import { Converter } from '@fgv/ts-utils';
 import { DateTime } from 'luxon';
@@ -34,6 +35,7 @@ declare namespace AiAssist {
         AiToolConfig,
         IAiWebSearchToolConfig,
         IAiClientToolConfig,
+        IAiToolAnnotations,
         IAiClientTool,
         IAiClientToolCallSummary,
         IAiClientToolContinuation,
@@ -60,25 +62,16 @@ declare namespace AiAssist {
         IAiImageData,
         AiImageSize,
         AiImageQuality,
-        DallE2Size,
-        DallE3Size,
         GptImageSize,
-        DallE3Quality,
         GptImageQuality,
-        DallEModelNames,
         GptImageModelNames,
         GrokImagineModelNames,
-        Imagen4ModelNames,
         GeminiFlashImageModelNames,
-        IDallEImageGenerationConfig,
         IGptImageGenerationConfig,
         IGrokImagineImageGenerationConfig,
-        IImagen4GenerationConfig,
         IGeminiFlashImageGenerationConfig,
-        IDallEModelOptions,
         IGptImageModelOptions,
         IGrokImagineModelOptions,
-        IImagen4ModelOptions,
         IGeminiFlashImageModelOptions,
         IOtherModelOptions,
         IModelFamilyConfig,
@@ -103,6 +96,11 @@ declare namespace AiAssist {
         allModelSpecKeys,
         MODEL_SPEC_BASE_KEY,
         resolveModel,
+        IModelAliasMap,
+        MODEL_ALIAS_SIGIL,
+        resolveModelAlias,
+        resolveProviderModel,
+        isResponsesOnlyModel,
         toDataUrl,
         AiThinkingMode,
         IThinkingConfig,
@@ -149,10 +147,12 @@ declare namespace AiAssist {
         executeClientToolTurn,
         IExecuteClientToolTurnParams,
         IExecuteClientToolTurnResult,
+        IToolExecutionDecision,
         aiProviderId,
         aiServerToolType,
         aiWebSearchToolConfig,
         aiServerToolConfig,
+        aiToolAnnotations,
         aiClientToolConfig,
         aiToolEnablement,
         aiAssistProviderConfig,
@@ -190,7 +190,8 @@ declare const aiAssistSettings: Converter<IAiAssistSettings>;
 
 /**
  * Converter for {@link AiAssist.IAiClientToolConfig}. Validates the wrapper shape: `type`,
- * `name`, `description`, and the presence of a usable `parametersSchema`.
+ * `name`, `description`, the presence of a usable `parametersSchema`, and optional
+ * host-advisory `annotations`.
  * Does not inspect the inner JSON Schema structure — `JsonSchema.object(...)` already
  * guarantees the schema is valid.
  * @public
@@ -240,20 +241,19 @@ declare type AiEmbeddingTaskType = 'retrieval-query' | 'retrieval-document' | 's
  * - `'xai-images'` — xAI Images API. Text-only JSON generation request.
  * - `'xai-images-edits'` — xAI Images API for Grok Imagine models. Uses JSON
  *   body with `{ type: "image_url" }` objects (not multipart).
- * - `'gemini-imagen'` — Google Imagen `:predict` endpoint. Text-only.
  * - `'gemini-image-out'` — Google Gemini chat-style `:generateContent`
- *   endpoint that returns image parts (Gemini 2.5 Flash Image / "Nano
+ *   endpoint that returns image parts (Gemini Flash Image / "Nano
  *   Banana"). Accepts reference images.
  *
  * @public
  */
-declare type AiImageApiFormat = 'openai-images' | 'gemini-imagen' | 'xai-images' | 'xai-images-edits' | 'gemini-image-out';
+declare type AiImageApiFormat = 'openai-images' | 'xai-images' | 'xai-images-edits' | 'gemini-image-out';
 
 /** All accepted quality strings across all providers. @public */
-declare type AiImageQuality = DallE3Quality | GptImageQuality;
+declare type AiImageQuality = GptImageQuality;
 
 /** All accepted image size strings across all providers. @public */
-declare type AiImageSize = DallE2Size | DallE3Size | GptImageSize;
+declare type AiImageSize = GptImageSize;
 
 /**
  * Capability vocabulary used to describe what a model can do. Used as both
@@ -344,6 +344,12 @@ declare const aiServerToolType: Converter<AiServerToolType>;
  */
 declare type AiThinkingMode = 'optional' | 'required' | 'unsupported';
 
+/**
+ * Converter for {@link AiAssist.IAiToolAnnotations} — the five optional host-advisory hints.
+ * @public
+ */
+declare const aiToolAnnotations: Converter<IAiToolAnnotations>;
+
 /**
  * Union of all tool configurations: server-side or client-defined.
  * Discriminated on `type`.
@@ -421,9 +427,14 @@ declare function anthropicEffortToBudgetTokens(effort: NonNullable<IAnthropicThi
 
 /**
  * Model IDs for Anthropic thinking-capable models.
+ *
+ * @remarks
+ * Only thinking-capable lines are listed. The non-tier `@anthropic:haiku` / `@anthropic:fable`
+ * aliases (reachable via `modelOverride` only) are deliberately omitted — they are not
+ * documented as thinking-capable, so naming them in a thinking-model filter would be misleading.
  * @public
  */
-declare type AnthropicThinkingModelNames = 'claude-sonnet-4-5' | 'claude-sonnet-4-6' | 'claude-opus-4-6' | 'claude-opus-4-7';
+declare type AnthropicThinkingModelNames = 'claude-sonnet-4-5' | 'claude-sonnet-4-6' | 'claude-sonnet-5' | 'claude-opus-4-6' | 'claude-opus-4-7' | 'claude-opus-4-8';
 
 /**
  * Recommended OWASP 2023 minimum Argon2id parameters.
@@ -450,6 +461,31 @@ declare const argon2idKeyDerivationParams: Converter<IArgon2idKeyDerivationParam
  */
 declare const base64String: Converter<string>;
 
+/**
+ * Decodes a base64url (no-padding) string (RFC 4648 §5) back to a `Uint8Array`.
+ *
+ * This is the bare primitive with no multibase prefix; use
+ * {@link CryptoUtils.multibaseBase64UrlDecode} to decode a multibase-`'m'`-prefixed value.
+ *
+ * @param encoded - The base64url-no-pad body to decode.
+ * @returns `Success` with the decoded bytes, or `Failure` with error context.
+ * @public
+ */
+declare function base64UrlNoPadDecode(encoded: string): Result<Uint8Array>;
+
+/**
+ * Encodes a `Uint8Array` as a base64url (no-padding) string (RFC 4648 §5).
+ *
+ * The body uses the base64url alphabet (`+` → `-`, `/` → `_`) and trailing `=`
+ * padding is stripped. This is the bare primitive with no multibase prefix; use
+ * {@link CryptoUtils.multibaseBase64UrlEncode} when a multibase-`'m'`-prefixed value is required.
+ *
+ * @param data - The binary data to encode.
+ * @returns The base64url-no-pad string.
+ * @public
+ */
+declare function base64UrlNoPadEncode(data: Uint8Array): string;
+
 /**
  * Calls the appropriate chat completion API for a given provider. Routes by
  * `apiFormat`: `'openai'` (xAI/OpenAI/Groq/Mistral — switches to Responses API
@@ -501,7 +537,7 @@ declare function callProviderEmbedding(params: IProviderEmbeddingParams): Promis
 /**
  * Calls the appropriate image-generation API for a given provider. Routes by the
  * `format` field of the resolved {@link IAiImageModelCapability}:
- * `'openai-images'`, `'xai-images'`, `'xai-images-edits'`, `'gemini-imagen'`, or
+ * `'openai-images'`, `'xai-images'`, `'xai-images-edits'`, or
  * `'gemini-image-out'`. Rejects up front if `referenceImages` is set but the
  * capability does not declare `acceptsImageReferenceInput`.
  * @param params - Request parameters including descriptor, API key, and prompt
@@ -638,6 +674,7 @@ declare namespace Converters_3 {
         argon2idKeyDerivationParams,
         keyDerivationParams,
         base64String,
+        multibaseSpkiPublicKey,
         uint8ArrayFromBase64,
         namedSecret,
         encryptedFile
@@ -685,13 +722,18 @@ declare namespace CryptoUtils {
         ICreateEncryptedFileParams,
         toBase64,
         tryDecryptFile,
+        base64UrlNoPadDecode,
+        base64UrlNoPadEncode,
         exportPublicKeyAsMultibaseSpki,
         importPublicKeyFromMultibaseSpki,
+        isValidMultibaseSpkiPublicKey,
+        MultibaseSpkiPublicKeyRegExp,
         multibaseBase64UrlDecode,
         multibaseBase64UrlEncode,
         HpkeProvider,
         IHpkeSealResult,
         isEncryptedFile,
+        MultibaseSpkiPublicKey,
         EncryptionAlgorithm,
         EncryptedFileFormat,
         INamedSecret,
@@ -736,18 +778,6 @@ declare interface CsvOptions {
     delimiter?: string;
 }
 
-/** Pixel dimension sizes accepted by dall-e-2. @public */
-declare type DallE2Size = '256x256' | '512x512' | '1024x1024';
-
-/** Quality values for dall-e-3. @public */
-declare type DallE3Quality = 'standard' | 'hd';
-
-/** Pixel dimension sizes accepted by dall-e-3. @public */
-declare type DallE3Size = '1024x1024' | '1792x1024' | '1024x1792';
-
-/** Model names in the DALL-E family. @public */
-declare type DallEModelNames = 'dall-e-2' | 'dall-e-3';
-
 /**
  * Decrypts an {@link CryptoUtils.IEncryptedFile | encrypted file} and returns the JSON content.
  * @typeParam TPayload - Expected type of decrypted content
@@ -1059,7 +1089,7 @@ export { Experimental }
  * @returns `Success` with the multibase SPKI string, or `Failure` with error context.
  * @public
  */
-declare function exportPublicKeyAsMultibaseSpki(key: CryptoKey, provider: ICryptoProvider): Promise<Result<string>>;
+declare function exportPublicKeyAsMultibaseSpki(key: CryptoKey, provider: ICryptoProvider): Promise<Result<MultibaseSpkiPublicKey>>;
 
 /**
  * An experimental array template which extend built-in `Array` to include a handful
@@ -1267,13 +1297,13 @@ declare const GCM_AUTH_TAG_SIZE: number;
 declare const GCM_IV_SIZE: number;
 
 /** Model names in the Gemini Flash Image family. @public */
-declare type GeminiFlashImageModelNames = 'gemini-2.5-flash-image';
+declare type GeminiFlashImageModelNames = 'gemini-3.1-flash-image-preview';
 
 /**
  * Model IDs for Google Gemini thinking-capable models.
  * @public
  */
-declare type GeminiThinkingModelNames = 'gemini-2.5-pro' | 'gemini-2.5-flash' | 'gemini-2.5-flash-lite';
+declare type GeminiThinkingModelNames = 'gemini-3.1-pro-preview' | 'gemini-3.5-flash' | 'gemini-3.1-flash-lite';
 
 /**
  * Calls {@link AiAssist.callProviderCompletion}, then runs the response text
@@ -1312,7 +1342,7 @@ declare function getProviderDescriptor(id: string): Result<IAiProviderDescriptor
 declare function getProviderDescriptors(): ReadonlyArray<IAiProviderDescriptor>;
 
 /** Model names in the GPT Image family. @public */
-declare type GptImageModelNames = 'gpt-image-1';
+declare type GptImageModelNames = 'gpt-image-1' | 'gpt-image-1.5';
 
 /** Quality values for gpt-image-1. @public */
 declare type GptImageQuality = 'low' | 'medium' | 'high' | 'auto';
@@ -1471,6 +1501,13 @@ declare interface IAddKeyPairOptions {
      * displaced storage blob; see the keystore design doc for details.
      */
     readonly replace?: boolean;
+    /**
+     * Overrides the storage-backend-derived extractability for this key only.
+     * Omit to keep the default (`!privateKeyStorage.supportsNonExtractable`).
+     * A value the backend cannot honor fails loudly rather than silently
+     * downgrading.
+     */
+    readonly extractable?: boolean;
 }
 
 /**
@@ -1696,6 +1733,12 @@ declare interface IAiClientToolConfig<TParams = unknown> {
      * `.toJson()` and validates model-returned args via `.validate(rawArgs)`.
      */
     readonly parametersSchema: JsonSchema.ISchemaValidator<TParams>;
+    /**
+     * Optional host-advisory behavior annotations (read-only / destructive /
+     * idempotent / open-world hints + display title). Consumed by the host's
+     * tool loop; never serialized to the model. See {@link IAiToolAnnotations}.
+     */
+    readonly annotations?: IAiToolAnnotations;
 }
 
 /**
@@ -1949,14 +1992,13 @@ declare interface IAiImageData {
 declare interface IAiImageGenerationOptions {
     /**
      * Image dimensions for OpenAI models (mapped to `size` field).
-     * For xAI aspect ratio or Imagen aspect ratio, use the corresponding `models` family block.
+     * For xAI or Gemini Flash aspect ratio, use the corresponding `models` family block.
      */
     readonly size?: AiImageSize;
     /** Number of images. Default 1. Some models enforce a maximum. */
     readonly count?: number;
     /**
      * Quality tier. Accepted values differ per model:
-     * - dall-e-3: 'standard' | 'hd'
      * - gpt-image-1: 'low' | 'medium' | 'high' | 'auto'
      * Other models ignore this field.
      */
@@ -2032,9 +2074,9 @@ declare interface IAiImageModelCapability {
     readonly maxCount?: number;
     /**
      * How to encode the output format on the wire:
-     * - 'response-format': send response_format: 'b64_json' (dall-e-2, dall-e-3)
+     * - 'response-format': send response_format: 'b64_json' (openai-images catch-all)
      * - 'output-format': send output_format (gpt-image-1)
-     * - 'none': send neither (Imagen, Gemini Flash)
+     * - 'none': send neither (Gemini Flash)
      */
     readonly outputParamStyle?: 'response-format' | 'output-format' | 'none';
     /** Default MIME type for response images. */
@@ -2107,6 +2149,19 @@ declare interface IAiProviderDescriptor {
     readonly baseUrl: string;
     /** Default model specification — string or context-aware map. */
     readonly defaultModel: ModelSpec;
+    /**
+     * Canonical fgv alias → concrete model map for this provider. Absent means the
+     * provider defines no aliases and every model string passes through verbatim.
+     *
+     * @remarks
+     * Keys are full fgv aliases (`@<providerId>:<role>`); values are the current
+     * concrete model id (or a provider-native alias). Consulted by
+     * {@link resolveModelAlias} / {@link resolveProviderModel} at each call-time
+     * resolution chokepoint, downstream of the {@link ModelSpecKey} walk. Additive
+     * and optional — composes with the existing per-descriptor `imageGeneration` /
+     * `embedding` capability arrays.
+     */
+    readonly aliases?: IModelAliasMap;
     /** Which server-side tools this provider supports (empty = none). */
     readonly supportedTools: ReadonlyArray<AiServerToolType>;
     /** Whether this provider's API enforces CORS restrictions that prevent direct browser calls. */
@@ -2146,15 +2201,13 @@ declare interface IAiProviderDescriptor {
      * 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.
+     * surface under one baseUrl. The dispatcher selects the longest-matching
+     * prefix, so a provider can list a specific-prefix surface alongside an
+     * empty-prefix catch-all and the right model routes to the right API.
      *
      * Image-model selection reuses the existing `image` {@link ModelSpecKey}.
      * Providers that declare `imageGeneration` should declare a model in
-     * `defaultModel.image`, e.g. `{ base: 'gpt-4o', image: 'dall-e-3' }`.
+     * `defaultModel.image`, e.g. `{ base: '@openai:mini', image: '@openai:image' }`.
      */
     readonly imageGeneration?: ReadonlyArray<IAiImageModelCapability>;
     /**
@@ -2169,11 +2222,27 @@ declare interface IAiProviderDescriptor {
      *
      * Embedding-model selection uses the `embedding` {@link ModelSpecKey}.
      * Providers that declare `embedding` should declare a model in
-     * `defaultModel.embedding`, e.g. `{ base: 'gpt-4o', embedding: 'text-embedding-3-small' }`.
+     * `defaultModel.embedding`, e.g. `{ base: '@openai:mini', embedding: '@openai:embedding' }`.
      * Self-hosted providers (`ollama`, `openai-compat`) leave it unset — the
      * caller supplies the embedding model via `modelOverride`.
      */
     readonly embedding?: ReadonlyArray<IAiEmbeddingModelCapability>;
+    /**
+     * Concrete model ids (prefix-matched) that must be invoked via the OpenAI
+     * Responses API rather than chat completions — e.g. `gpt-5.5-pro`. Non-OpenAI
+     * `apiFormat`s ignore this.
+     *
+     * @remarks
+     * Some current-generation OpenAI models (the `-pro` tier) are Responses-API-only
+     * and 400 on `/chat/completions`. The completion and streaming dispatch consult
+     * this list (via the sibling predicate {@link AiAssist.isResponsesOnlyModel})
+     * and route a matching model to the Responses path
+     * even when no tools are requested. Mirrors the prefix-matching shape of the
+     * `imageGeneration` / `embedding` capability arrays; adding a new Responses-only
+     * line is a one-entry descriptor edit. Empty or undefined means no model is
+     * Responses-only.
+     */
+    readonly responsesOnlyModelPrefixes?: ReadonlyArray<string>;
 }
 
 /**
@@ -2311,6 +2380,35 @@ declare interface IAiStreamToolUseStart {
     readonly callId?: string;
 }
 
+/**
+ * Behavior annotations for a client-defined tool.
+ *
+ * @remarks
+ * These are **host-advisory-only hints** describing a tool's side-effect profile.
+ * They are consumed by the host's tool loop (e.g. a before-execute gate) and are
+ * **never serialized to the model** — the provider wire tool-schemas whitelist
+ * `{name, description, parameters}` and ignore this field.
+ *
+ * Field names mirror MCP's `ToolAnnotations` (`@modelcontextprotocol/sdk`) 1:1 so
+ * an MCP tool's annotations pass through unchanged. Per the MCP spec, all fields
+ * are hints — a host should never make tool-use decisions based on annotations
+ * received from an untrusted server without its own validation.
+ *
+ * @public
+ */
+declare interface IAiToolAnnotations {
+    /** Optional human-readable display title for the tool. */
+    readonly title?: string;
+    /** Hint: the tool does not modify its environment (read-only). */
+    readonly readOnlyHint?: boolean;
+    /** Hint: the tool may perform destructive updates (only meaningful when not read-only). */
+    readonly destructiveHint?: boolean;
+    /** Hint: repeated calls with the same arguments have no additional effect. */
+    readonly idempotentHint?: boolean;
+    /** Hint: the tool interacts with an open world of external entities. */
+    readonly openWorldHint?: boolean;
+}
+
 /**
  * Declares a tool as enabled/disabled in provider settings.
  * Tools are disabled by default — consuming apps must opt in explicitly.
@@ -2786,36 +2884,6 @@ declare interface ICryptoProvider {
     verifyHmacSha256(key: CryptoKey, signature: Uint8Array, data: Uint8Array): Promise<Result<boolean>>;
 }
 
-/**
- * Provider-specific config for DALL-E models (dall-e-2, dall-e-3).
- * @remarks
- * style is only valid for dall-e-3; the runtime validator rejects it for dall-e-2.
- * @public
- */
-declare interface IDallEImageGenerationConfig {
-    /** Image dimensions (dall-e-2: 256x256|512x512|1024x1024; dall-e-3: 1024x1024|1792x1024|1024x1792). */
-    readonly size?: DallE2Size | DallE3Size;
-    /** dall-e-3 only. Quality tier. */
-    readonly quality?: DallE3Quality;
-    /** dall-e-3 only. Visual style. */
-    readonly style?: 'vivid' | 'natural';
-}
-
-/**
- * Options block scoped to DALL-E family models.
- * @public
- */
-declare interface IDallEModelOptions extends INamedModelFamilyConfig {
-    /** Discriminator: openai provider lineage. */
-    readonly provider: 'openai';
-    /** Family identifier. */
-    readonly family: 'dall-e';
-    /** Optional model names this block applies to. Omit = applies to all DALL-E models. */
-    readonly models?: DallEModelNames[];
-    /** Family-specific config. */
-    readonly config: IDallEImageGenerationConfig;
-}
-
 /**
  * Parameters for creating a {@link DirectEncryptionProvider}.
  * @public
@@ -3030,7 +3098,10 @@ declare interface IExecuteClientToolTurnParams extends IChatRequest {
      * normalized-message path strips provider-native fields.
      */
     readonly continuationMessages?: ReadonlyArray<JsonObject>;
-    /** Temperature (default: 0.7). */
+    /**
+     * Sampling temperature. Sent to the provider only when explicitly provided; omitted otherwise
+     * so the provider's own default applies (current-gen models reject a caller-supplied default).
+     */
     readonly temperature?: number;
     /** Server-side tools to include. */
     readonly tools?: ReadonlyArray<AiServerToolConfig>;
@@ -3054,6 +3125,22 @@ declare interface IExecuteClientToolTurnParams extends IChatRequest {
     readonly resolvedThinking?: IResolvedThinkingConfig;
     /** Resolved model string (pre-resolved by the caller). When omitted, uses the descriptor's default model. */
     readonly model?: string;
+    /**
+     * Optional host gate invoked for each client-tool call **after** the model's raw
+     * args have been validated against the tool's `parametersSchema` and **before**
+     * `tool.execute(...)` runs. The full `tool` (including `tool.config.annotations`)
+     * and the validated `args` are passed so gate logic can key off a tool's behavior
+     * annotations (e.g. deny a `destructiveHint` call pending confirmation).
+     *
+     * Returning `{ action: 'proceed' }` (or omitting the callback) runs `execute`
+     * normally. Returning `{ action: 'deny', reason }` skips `execute` and synthesizes
+     * a denial tool-result carrying `reason` into the continuation (the model sees the
+     * denial and can react); **the turn continues**. A callback that returns `Result.fail`
+     * or rejects is a hard error that **terminates the turn** (fails `nextTurn` + emits an
+     * inline `error` event) — distinct from a `tool.execute` failure, which continues the
+     * turn with an `isError` result. A deny must therefore be explicit.
+     */
+    readonly onBeforeToolExecute?: (tool: IAiClientTool, args: unknown) => Promise<Result<IToolExecutionDecision>>;
 }
 
 /**
@@ -3263,38 +3350,6 @@ declare interface IHpkeSealResult {
     readonly ciphertext: Uint8Array;
 }
 
-/**
- * Provider-specific config for Google Imagen 4 models.
- * @public
- */
-declare interface IImagen4GenerationConfig {
-    /** Aspect ratio string. */
-    readonly aspectRatio?: '1:1' | '3:4' | '4:3' | '9:16' | '16:9';
-    /** Output resolution. */
-    readonly imageSize?: '1K' | '2K';
-    /** Whether to add SynthID watermark. Must be false to use seed. */
-    readonly addWatermark?: boolean;
-    /** LLM-based prompt rewriting. */
-    readonly enhancePrompt?: boolean;
-    /** Output MIME type. */
-    readonly outputMimeType?: 'image/jpeg' | 'image/png';
-    /** JPEG compression quality. */
-    readonly outputCompressionQuality?: number;
-    /** Person generation policy. */
-    readonly personGeneration?: 'allow_all' | 'allow_adult' | 'dont_allow';
-}
-
-/**
- * Options block scoped to Google Imagen 4 models.
- * @public
- */
-declare interface IImagen4ModelOptions extends INamedModelFamilyConfig {
-    readonly provider: 'google';
-    readonly family: 'imagen-4';
-    readonly models?: Imagen4ModelNames[];
-    readonly config: IImagen4GenerationConfig;
-}
-
 /**
  * Options for importing raw key material via {@link KeyStore.importSecret}.
  * Extends {@link IImportSecretOptions} with a type classification.
@@ -3637,9 +3692,6 @@ declare interface IKeyStoreVaultContents {
     readonly secrets: Record<string, IKeyStoreEntryJson>;
 }
 
-/** Model names in the Imagen 4 family. @public */
-declare type Imagen4ModelNames = 'imagen-4.0-generate-001' | 'imagen-4.0-ultra-generate-001' | 'imagen-4.0-fast-generate-001';
-
 /**
  * Details about a missing variable in context validation.
  * @public
@@ -3660,12 +3712,27 @@ declare interface IMissingVariableDetail {
     readonly existingPath: readonly string[];
 }
 
+/**
+ * Canonical fgv alias → concrete provider model map.
+ *
+ * @remarks
+ * Keys are full fgv aliases (`@<providerId>:<role>`, e.g. `@google-gemini:flash`);
+ * values are the current concrete provider model id (or a provider-native alias,
+ * which is resolved with one further indirection hop). Additive; absence of an
+ * `aliases` field on a descriptor means "this provider defines no aliases" and
+ * every model string passes through verbatim.
+ * @public
+ */
+declare interface IModelAliasMap {
+    readonly [alias: string]: string;
+}
+
 /**
  * Discriminated union of all model-family option blocks.
  * Discriminated on `provider` + `family` fields.
  * @public
  */
-declare type IModelFamilyConfig = IDallEModelOptions | IGptImageModelOptions | IGrokImagineModelOptions | IImagen4ModelOptions | IGeminiFlashImageModelOptions | IOtherModelOptions;
+declare type IModelFamilyConfig = IGptImageModelOptions | IGrokImagineModelOptions | IGeminiFlashImageModelOptions | IOtherModelOptions;
 
 /**
  * A model specification: either a simple model string or a record mapping
@@ -3674,18 +3741,18 @@ declare type IModelFamilyConfig = IDallEModelOptions | IGptImageModelOptions | I
  * @remarks
  * A bare string is equivalent to `{ base: string }`. This keeps the simple
  * case simple while allowing context-aware model selection (e.g. different
- * models for tool-augmented vs. base completions).
+ * models for different quality tiers).
  *
  * @example
  * ```typescript
  * // Simple — same model for all contexts:
  * const simple: ModelSpec = 'grok-4.3';
  *
- * // Context-aware — different model for tools and thinking:
- * const split: ModelSpec = { base: 'grok-4.3', tools: 'grok-4.3', thinking: 'grok-4.3' };
+ * // Context-aware — different model per quality tier:
+ * const split: ModelSpec = { base: 'gpt-5.4-mini', advanced: 'gpt-5.5', frontier: 'gpt-5.5-pro' };
  *
- * // Future nested — per-tool model selection:
- * const nested: ModelSpec = { base: 'grok-fast', tools: { base: 'grok-r', image: 'grok-v' } };
+ * // Nested — a tier branch is itself a spec:
+ * const nested: ModelSpec = { base: 'grok-fast', advanced: { base: 'grok-r', image: 'grok-v' } };
  * ```
  * @public
  */
@@ -3700,6 +3767,10 @@ declare interface IModelSpecMap {
  * the provider to import the key with the algorithm parameters from
  * {@link CryptoUtils.keyPairAlgorithmParams}.
  *
+ * Accepts a plain `string` (not only a branded {@link CryptoUtils.MultibaseSpkiPublicKey}),
+ * so callers holding an unbranded value read from storage or the wire can import
+ * it directly; a malformed value fails with error context rather than throwing.
+ *
  * @param encoded - A multibase SPKI string produced by {@link CryptoUtils.exportPublicKeyAsMultibaseSpki}.
  * @param algorithm - The {@link CryptoUtils.KeyPairAlgorithm} the key was generated for.
  * @param provider - The {@link CryptoUtils.ICryptoProvider} to use for the import operation.
@@ -3905,10 +3976,20 @@ declare interface IProviderCompletionParams extends IChatRequest {
     readonly descriptor: IAiProviderDescriptor;
     /** API key for authentication */
     readonly apiKey: string;
-    /** Sampling temperature (default: 0.7) */
+    /**
+     * Sampling temperature. Sent to the provider only when explicitly provided; omitted otherwise
+     * so the provider's own default applies (current-gen models reject a caller-supplied default).
+     */
     readonly temperature?: number;
     /** Optional model override — string or context-aware map (uses descriptor.defaultModel otherwise) */
     readonly modelOverride?: ModelSpec;
+    /**
+     * Optional quality tier selecting which completion model to use. `undefined`
+     * selects the `base` tier; `'frontier'` cascades to `advanced` then `base`
+     * when a tier is unset for a provider. Orthogonal to `thinking` and `tools`,
+     * which never select a model.
+     */
+    readonly tier?: 'advanced' | 'frontier';
     /** Optional logger for request/response observability. */
     readonly logger?: Logging.ILogger;
     /** Server-side tools to include in the request. Overrides settings-level tool config when provided. */
@@ -3947,10 +4028,20 @@ declare interface IProviderCompletionStreamParams extends IChatRequest {
     readonly descriptor: IAiProviderDescriptor;
     /** API key for authentication */
     readonly apiKey: string;
-    /** Sampling temperature (default: 0.7) */
+    /**
+     * Sampling temperature. Sent to the provider only when explicitly provided; omitted otherwise
+     * so the provider's own default applies (current-gen models reject a caller-supplied default).
+     */
     readonly temperature?: number;
     /** Optional model override — string or context-aware map. */
     readonly modelOverride?: ModelSpec;
+    /**
+     * Optional quality tier selecting which completion model to use. `undefined`
+     * selects the `base` tier; `'frontier'` cascades to `advanced` then `base`
+     * when a tier is unset for a provider. Orthogonal to `thinking` and `tools`,
+     * which never select a model.
+     */
+    readonly tier?: 'advanced' | 'frontier';
     /** Optional logger for request/response observability. */
     readonly logger?: Logging.ILogger;
     /** Server-side tools to include in the request. */
@@ -4082,20 +4173,12 @@ declare interface IResolvedImageOptions {
     readonly quality?: string;
     /** Seed for reproducibility. */
     readonly seed?: number;
-    readonly style?: string;
     readonly outputFormat?: string;
     readonly outputCompression?: number;
     readonly background?: string;
     readonly moderation?: string;
     readonly aspectRatio?: string;
     readonly resolution?: string;
-    readonly imagenAspectRatio?: string;
-    readonly imageSize?: string;
-    readonly addWatermark?: boolean;
-    readonly enhancePrompt?: boolean;
-    readonly imagenOutputMimeType?: string;
-    readonly imagenOutputCompressionQuality?: number;
-    readonly personGeneration?: string;
     readonly geminiAspectRatio?: string;
     readonly otherParams?: JsonObject;
 }
@@ -4154,6 +4237,40 @@ declare const isoDate: Converter<Date, unknown>;
  */
 declare const isoDateTime: Converter<DateTime, unknown>;
 
+/**
+ * Determines whether a concrete (already-resolved) model id must be invoked via
+ * the OpenAI Responses API rather than chat completions.
+ *
+ * @remarks
+ * Matches `modelId` against the descriptor's
+ * {@link IAiProviderDescriptor.responsesOnlyModelPrefixes} by prefix. A provider
+ * that declares no list (the common case) always returns `false`. Consulted by
+ * both the completion (`callProviderCompletion`) and streaming
+ * (`callProviderCompletionStream`) OpenAI dispatch branches so a Responses-only
+ * model (e.g. `gpt-5.5-pro`) routes correctly even with no tools requested.
+ *
+ * @param descriptor - The provider descriptor supplying the prefix list.
+ * @param modelId - The resolved concrete model id to test.
+ * @returns `true` when `modelId` starts with any declared Responses-only prefix.
+ * @public
+ */
+declare function isResponsesOnlyModel(descriptor: IAiProviderDescriptor, modelId: string): boolean;
+
+/**
+ * Type guard for {@link CryptoUtils.MultibaseSpkiPublicKey}: a string matching
+ * {@link CryptoUtils.MultibaseSpkiPublicKeyRegExp} (multibase `'m'` prefix + a
+ * non-empty base64url-no-pad body) whose body also satisfies the base64url-no-pad
+ * length rule shared with {@link CryptoUtils.base64UrlNoPadDecode}. This is a
+ * structural *shape* check, not full validation — it does not decode the DER SPKI
+ * or verify the key material/algorithm (a malformed-but-well-shaped string fails
+ * later, with clear context, in {@link CryptoUtils.importPublicKeyFromMultibaseSpki}).
+ *
+ * @param value - The value to test.
+ * @returns `true` if `value` is a well-formed multibase SPKI public key string.
+ * @public
+ */
+declare function isValidMultibaseSpkiPublicKey(value: unknown): value is MultibaseSpkiPublicKey;
+
 /**
  * Thinking/reasoning mode configuration for a completion request.
  *
@@ -4187,6 +4304,32 @@ declare interface IThinkingConfig {
  */
 declare type IThinkingProviderConfig = IAnthropicThinkingOptions | IOpenAiThinkingOptions | IGeminiThinkingOptions | IXAiThinkingOptions | IOtherThinkingOptions;
 
+/**
+ * Decision returned by an {@link IExecuteClientToolTurnParams.onBeforeToolExecute}
+ * gate for a single client-tool call.
+ *
+ * @remarks
+ * - `{ action: 'proceed' }` — run the tool's `execute` normally.
+ * - `{ action: 'deny', reason }` — do NOT run `execute`; a synthesized tool-result
+ *   carrying `reason` is fed into the continuation exactly like a normal result so
+ *   the model can react, and a `client-tool-result` event is emitted for the call.
+ *   The turn continues.
+ *
+ * A gate that wants to signal a hard error (as opposed to a deliberate deny) should
+ * return `Result.fail` (or reject) from the callback. Note this is NOT the same as a
+ * `tool.execute` failure: an `execute` failure yields an `isError` tool-result and the
+ * **turn continues**, whereas a gate `fail`/reject **terminates the turn** — it fails
+ * `nextTurn` (and emits an inline `error` event) rather than synthesizing a deny.
+ *
+ * @public
+ */
+declare type IToolExecutionDecision = {
+    readonly action: 'proceed';
+} | {
+    readonly action: 'deny';
+    readonly reason: string;
+};
+
 /**
  * Represents a variable reference extracted from a Mustache template.
  * @public
@@ -4800,9 +4943,16 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * Requires a {@link CryptoUtils.KeyStore.IPrivateKeyStorage} backend
      * supplied at construction.
      *
+     * Extractability of the generated private key defaults to the storage
+     * backend's {@link CryptoUtils.KeyStore.IPrivateKeyStorage.supportsNonExtractable}.
+     * `options.extractable` overrides that default for this key only; requesting
+     * `extractable: false` against a backend that cannot store non-extractable
+     * keys fails loudly rather than silently generating an extractable key.
+     *
      * @param name - Unique name for the entry
-     * @param options - Algorithm, optional description, replace flag
-     * @returns Success with the new entry, Failure if locked, no provider, or storage write failed
+     * @param options - Algorithm, optional description, replace flag, extractable override
+     * @returns Success with the new entry, Failure if locked, no provider, storage write failed,
+     * or the requested extractability cannot be honored by the backend
      * @public
      */
     addKeyPair(name: string, options: IAddKeyPairOptions): Promise<Result<IAddKeyPairResult>>;
@@ -5050,6 +5200,18 @@ declare class Md5Normalizer extends Hash_2.HashingNormalizer {
  */
 declare const MIN_SALT_LENGTH: number;
 
+/**
+ * Marker prefix for an fgv model alias.
+ *
+ * @remarks
+ * A model string is an fgv alias **iff** it begins with this sigil. Everything
+ * else is a raw provider model id and passes through {@link resolveModelAlias}
+ * untouched — this is what keeps the alias layer back-compatible (no current
+ * `defaultModel`, `modelOverride`, or self-hosted `model:tag` id starts with `@`).
+ * @public
+ */
+declare const MODEL_ALIAS_SIGIL: '@';
+
 /**
  * Default context key used as fallback when resolving a {@link ModelSpec}.
  * @public
@@ -5074,7 +5236,7 @@ declare const modelSpec: Converter<ModelSpec>;
  * Known context keys for model specification maps.
  * @public
  */
-declare type ModelSpecKey = 'base' | 'tools' | 'image' | 'thinking' | 'embedding';
+declare type ModelSpecKey = 'base' | 'advanced' | 'frontier' | 'image' | 'embedding';
 
 /**
  * Converter for {@link ModelSpecKey}.
@@ -5107,6 +5269,43 @@ declare function multibaseBase64UrlDecode(encoded: string): Result<Uint8Array>;
  */
 declare function multibaseBase64UrlEncode(data: Uint8Array): string;
 
+/**
+ * A multibase base64url-encoded SPKI (SubjectPublicKeyInfo) public key string —
+ * a `'m'` multibase prefix followed by a base64url-no-pad body. Produced by
+ * {@link CryptoUtils.exportPublicKeyAsMultibaseSpki} and consumed by
+ * {@link CryptoUtils.importPublicKeyFromMultibaseSpki}. Obtain the brand at a
+ * boundary via {@link CryptoUtils.isValidMultibaseSpkiPublicKey} or the
+ * {@link CryptoUtils.Converters.multibaseSpkiPublicKey} converter.
+ * @public
+ */
+declare type MultibaseSpkiPublicKey = Brand<string, 'MultibaseSpkiPublicKey'>;
+
+/**
+ * Converter for {@link CryptoUtils.MultibaseSpkiPublicKey | multibase SPKI public key} strings.
+ * Validates that the value is a string with the `'m'` multibase prefix and a well-formed
+ * base64url-no-pad body, and yields the branded value. Fails with context on a non-string,
+ * bad-prefix, or malformed-body input.
+ * @public
+ */
+declare const multibaseSpkiPublicKey: Converter<MultibaseSpkiPublicKey>;
+
+/**
+ * The structural *shape* of a {@link CryptoUtils.MultibaseSpkiPublicKey}: the
+ * multibase `'m'` prefix followed by a non-empty base64url-no-pad body
+ * (`A-Z`, `a-z`, `0-9`, `-`, `_`).
+ *
+ * This is a shape prefilter, not full validation: it does not decode the DER
+ * SPKI or verify the key material or algorithm (that happens in
+ * {@link CryptoUtils.importPublicKeyFromMultibaseSpki}). The authoritative guard
+ * is {@link CryptoUtils.isValidMultibaseSpkiPublicKey}, which enforces this
+ * pattern **and** additionally rejects a body whose length is an impossible
+ * base64 remainder. Exposed for callers that need the pattern directly (e.g. a
+ * JSON-schema `pattern` field); prefer the guard/converter for validation.
+ *
+ * @public
+ */
+declare const MultibaseSpkiPublicKeyRegExp: RegExp;
+
 declare namespace Mustache {
     export {
         IContextValidationResult,
@@ -5399,7 +5598,7 @@ declare const nodeCryptoProvider: NodeCryptoProvider;
  * Model IDs for OpenAI thinking-capable models.
  * @public
  */
-declare type OpenAiThinkingModelNames = 'o3' | 'o4-mini' | 'o3-deep-research' | 'o4-mini-deep-research' | 'gpt-5' | 'gpt-5.1' | 'gpt-5.2' | 'gpt-5.5' | 'gpt-5-pro';
+declare type OpenAiThinkingModelNames = 'o3' | 'o4-mini' | 'o3-deep-research' | 'o4-mini-deep-research' | 'gpt-5' | 'gpt-5.1' | 'gpt-5.2' | 'gpt-5.4-mini' | 'gpt-5.5' | 'gpt-5.5-pro' | 'gpt-5-pro';
 
 /**
  * Parses CSV data from a string.
@@ -5686,17 +5885,63 @@ declare function resolveImageOptions(modelId: string, capability: IAiImageModelC
  * @remarks
  * Resolution rules:
  * 1. If the spec is a string, return it directly (context is irrelevant).
- * 2. If the spec is an object and the context key exists, recurse into that branch.
+ * 2. If the spec is an object, walk the ordered candidate keys for the context:
+ *    a quality-tier context (`advanced`/`frontier`) cascades through the
+ *    tier-fallback table (`frontier → advanced → base`, `advanced → base`);
+ *    every other context resolves flat (`[context]`); `undefined` resolves to
+ *    the shared `base` fallback. The first present key wins.
  * 3. Otherwise, fall back to the {@link MODEL_SPEC_BASE_KEY | 'base'} key.
  * 4. If neither context nor `'base'` exists, use the first available value.
  *
  * @param spec - The model specification to resolve
- * @param context - Optional context key (e.g. `'tools'`)
+ * @param context - Optional context key (e.g. `'advanced'`)
  * @returns The resolved model string
  * @public
  */
 declare function resolveModel(spec: ModelSpec, context?: string): string;
 
+/**
+ * Resolves a single (possibly-aliased) model string against a provider descriptor.
+ *
+ * @remarks
+ * Resolution rules:
+ * 1. No leading {@link MODEL_ALIAS_SIGIL} → raw provider id, returned verbatim.
+ * 2. Leading sigil + registered in `descriptor.aliases` → the registered target,
+ *    which is itself resolved — so a chain of `@` aliases is followed until a
+ *    non-`@` (concrete provider) id is reached. The canonical case is a single
+ *    hop (an fgv alias targeting a provider-native alias), but longer chains
+ *    resolve too.
+ * 3. Leading sigil + unregistered → fails loudly, naming the provider and alias.
+ *
+ * An `@`→`@` cycle is guarded by a visited-set and fails rather than exhausting
+ * the stack.
+ *
+ * @param descriptor - The provider descriptor whose `aliases` map is consulted.
+ * @param model - The (possibly-aliased) model string to resolve.
+ * @returns `Result` with the concrete provider model id, or a failure.
+ * @public
+ */
+declare function resolveModelAlias(descriptor: IAiProviderDescriptor, model: string): Result<string>;
+
+/**
+ * The full provider model-resolution chokepoint: the {@link ModelSpecKey} walk
+ * (via {@link resolveModel}) THEN {@link resolveModelAlias}.
+ *
+ * @remarks
+ * Replaces the bare `resolveModel(modelOverride ?? descriptor.defaultModel, context)`
+ * call plus the duplicated empty-result check at each call-time chokepoint. The
+ * `ModelSpec` branch is selected first; the resulting string — which may itself
+ * be an fgv alias — is then resolved to a concrete id.
+ *
+ * @param descriptor - The provider descriptor (supplies `defaultModel` and `aliases`).
+ * @param modelOverride - An optional caller-supplied `ModelSpec` that takes precedence
+ * over `descriptor.defaultModel`. May itself contain or be an alias.
+ * @param context - Optional {@link ModelSpecKey} selecting the spec branch.
+ * @returns `Result` with the concrete provider model id, or a failure.
+ * @public
+ */
+declare function resolveProviderModel(descriptor: IAiProviderDescriptor, modelOverride: ModelSpec | undefined, context?: ModelSpecKey): Result<string>;
+
 /**
  * Function type for dynamic secret retrieval.
  * @public