@fgv/ts-extras 5.0.2 → 5.1.0-1

package/dist/ts-extras.d.ts

@@ -3,9 +3,207 @@ import { Converter } from '@fgv/ts-utils';
 import { FileTree } from '@fgv/ts-json-base';
 import { Hash as Hash_2 } from '@fgv/ts-utils';
 import { JsonValue } from '@fgv/ts-json-base';
+import { Logging } from '@fgv/ts-utils';
 import { Result } from '@fgv/ts-utils';
 import { Validator } from '@fgv/ts-utils';
 
+/**
+ * Key size in bytes for AES-256.
+ * @public
+ */
+declare const AES_256_KEY_SIZE: number;
+
+/**
+ * API format categories for provider routing.
+ * @public
+ */
+declare type AiApiFormat = 'openai' | 'anthropic' | 'gemini';
+
+declare namespace AiAssist {
+    export {
+        AiPrompt,
+        AiProviderId,
+        AiServerToolType,
+        AiServerToolConfig,
+        IAiWebSearchToolConfig,
+        IAiToolEnablement,
+        IAiCompletionResponse,
+        IChatMessage,
+        AiApiFormat,
+        IAiProviderDescriptor,
+        IAiAssistProviderConfig,
+        IAiAssistSettings,
+        DEFAULT_AI_ASSIST,
+        IAiAssistKeyStore,
+        ModelSpec,
+        ModelSpecKey,
+        IModelSpecMap,
+        allModelSpecKeys,
+        MODEL_SPEC_BASE_KEY,
+        resolveModel,
+        allProviderIds,
+        getProviderDescriptors,
+        getProviderDescriptor,
+        callProviderCompletion,
+        callProxiedCompletion,
+        IProviderCompletionParams,
+        aiProviderId,
+        aiServerToolType,
+        aiWebSearchToolConfig,
+        aiServerToolConfig,
+        aiToolEnablement,
+        aiAssistProviderConfig,
+        aiAssistSettings,
+        modelSpecKey,
+        modelSpec,
+        resolveEffectiveTools
+    }
+}
+export { AiAssist }
+
+/**
+ * Converter for {@link IAiAssistProviderConfig}.
+ * @public
+ */
+declare const aiAssistProviderConfig: Converter<IAiAssistProviderConfig>;
+
+/**
+ * Converter for {@link IAiAssistSettings}.
+ * @public
+ */
+declare const aiAssistSettings: Converter<IAiAssistSettings>;
+
+/**
+ * A structured AI prompt with system/user split for direct API calls,
+ * and a lazily-constructed combined version for copy/paste workflows.
+ * @public
+ */
+declare class AiPrompt {
+    /** System instructions: schema documentation, format rules, general guidance. */
+    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. */
+    get combined(): string;
+}
+
+/**
+ * All known AI provider identifiers.
+ * @public
+ */
+declare type AiProviderId = 'copy-paste' | 'xai-grok' | 'openai' | 'anthropic' | 'google-gemini' | 'groq' | 'mistral';
+
+/**
+ * Converter for {@link AiProviderId}.
+ * @public
+ */
+declare const aiProviderId: Converter<AiProviderId>;
+
+/**
+ * Union of all server-side tool configurations. Discriminated on `type`.
+ * @public
+ */
+declare type AiServerToolConfig = IAiWebSearchToolConfig;
+
+/**
+ * Converter for {@link AiServerToolConfig} (discriminated union on `type`).
+ * @public
+ */
+declare const aiServerToolConfig: Converter<AiServerToolConfig>;
+
+/**
+ * Built-in server-side tool types supported across providers.
+ * @public
+ */
+declare type AiServerToolType = 'web_search';
+
+/**
+ * Converter for {@link AiServerToolType}.
+ * @public
+ */
+declare const aiServerToolType: Converter<AiServerToolType>;
+
+/**
+ * Converter for {@link IAiToolEnablement}.
+ * @public
+ */
+declare const aiToolEnablement: Converter<IAiToolEnablement>;
+
+/**
+ * Converter for {@link IAiWebSearchToolConfig}.
+ * @public
+ */
+declare const aiWebSearchToolConfig: Converter<IAiWebSearchToolConfig>;
+
+/**
+ * All valid key store secret types.
+ * @public
+ */
+declare const allKeyStoreSecretTypes: ReadonlyArray<KeyStoreSecretType>;
+
+/**
+ * All valid {@link ModelSpecKey} values.
+ * @public
+ */
+declare const allModelSpecKeys: ReadonlyArray<ModelSpecKey>;
+
+/**
+ * All valid provider ID values, in the same order as the registry.
+ * @public
+ */
+declare const allProviderIds: ReadonlyArray<AiProviderId>;
+
+/**
+ * Converter for base64 strings (validates format).
+ * @public
+ */
+declare const base64String: Converter<string>;
+
+/**
+ * Calls the appropriate chat completion API for a given provider.
+ *
+ * Routes based on the provider descriptor's `apiFormat` field:
+ * - `'openai'` for xAI, OpenAI, Groq, Mistral
+ * - `'anthropic'` for Anthropic Claude
+ * - `'gemini'` for Google Gemini
+ *
+ * When tools are provided and the provider supports them:
+ * - OpenAI-format providers switch to the Responses API
+ * - Anthropic includes tools in the Messages API request
+ * - Gemini includes Google Search grounding
+ *
+ * @param params - Request parameters including descriptor, API key, prompt, and optional tools
+ * @returns The completion response with content and truncation status, or a failure
+ * @public
+ */
+declare function callProviderCompletion(params: IProviderCompletionParams): Promise<Result<IAiCompletionResponse>>;
+
+/**
+ * Calls the AI completion endpoint on a proxy server instead of calling
+ * the provider API directly from the browser.
+ *
+ * The proxy server handles provider dispatch, CORS, and API key forwarding.
+ * The request shape mirrors {@link IProviderCompletionParams} but is serialized
+ * as JSON for the proxy endpoint.
+ *
+ * @param proxyUrl - Base URL of the proxy server (e.g. `http://localhost:3001`)
+ * @param params - Same parameters as {@link callProviderCompletion}
+ * @returns The completion response, or a failure
+ * @public
+ */
+declare function callProxiedCompletion(proxyUrl: string, params: IProviderCompletionParams): Promise<Result<IAiCompletionResponse>>;
+
+declare namespace Constants {
+    export {
+        ENCRYPTED_FILE_FORMAT,
+        DEFAULT_ALGORITHM,
+        AES_256_KEY_SIZE,
+        GCM_IV_SIZE,
+        GCM_AUTH_TAG_SIZE
+    }
+}
+
 declare namespace Converters {
     export {
         templateString,
@@ -17,6 +215,87 @@ declare namespace Converters {
 }
 export { Converters }
 
+declare namespace Converters_2 {
+    export {
+        keystoreFormat,
+        keystoreSecretType,
+        keystoreSecretEntryJson,
+        keystoreVaultContents,
+        keystoreFile
+    }
+}
+
+declare namespace Converters_3 {
+    export {
+        createEncryptedFileConverter,
+        encryptionAlgorithm,
+        encryptedFileFormat,
+        encryptedFileErrorMode,
+        keyDerivationFunction,
+        keyDerivationParams,
+        base64String,
+        uint8ArrayFromBase64,
+        namedSecret,
+        encryptedFile
+    }
+}
+
+/**
+ * Creates an {@link CryptoUtils.IEncryptedFile | encrypted file} from JSON content.
+ * @typeParam TMetadata - Type of optional unencrypted metadata
+ * @param params - Encryption parameters
+ * @returns `Success` with encrypted file structure, or `Failure` with an error.
+ * @public
+ */
+declare function createEncryptedFile<TMetadata = JsonValue>(params: ICreateEncryptedFileParams<TMetadata>): Promise<Result<IEncryptedFile<TMetadata>>>;
+
+/**
+ * Creates a converter for {@link CryptoUtils.IEncryptedFile | encrypted files} with optional typed metadata.
+ * @typeParam TMetadata - Type of optional unencrypted metadata
+ * @param metadataConverter - Optional converter for validating metadata field
+ * @returns A converter that validates and converts encrypted file structures
+ * @public
+ */
+declare function createEncryptedFileConverter<TMetadata = JsonValue>(metadataConverter?: Converter<TMetadata>): Converter<IEncryptedFile<TMetadata>>;
+
+/**
+ * Creates a zip file from an array of text files.
+ * @public
+ */
+declare function createZipFromTextFiles(files: ReadonlyArray<IZipTextFile>, options?: ICreateZipOptions): Result<Uint8Array>;
+
+declare namespace CryptoUtils {
+    export {
+        Constants,
+        KeyStore,
+        Converters_3 as Converters,
+        DirectEncryptionProvider,
+        IDirectEncryptionProviderParams,
+        NodeCryptoProvider,
+        nodeCryptoProvider,
+        createEncryptedFile,
+        decryptFile,
+        fromBase64,
+        ICreateEncryptedFileParams,
+        toBase64,
+        tryDecryptFile,
+        isEncryptedFile,
+        EncryptionAlgorithm,
+        EncryptedFileFormat,
+        INamedSecret,
+        IEncryptionResult,
+        KeyDerivationFunction,
+        IKeyDerivationParams,
+        IEncryptedFile,
+        ICryptoProvider,
+        IEncryptionProvider,
+        EncryptedFileErrorMode,
+        SecretProvider,
+        IEncryptionConfig
+    }
+}
+export { CryptoUtils }
+
 declare namespace Csv {
     export {
         parseCsvString,
@@ -35,6 +314,37 @@ declare interface CsvOptions {
     delimiter?: string;
 }
 
+/**
+ * Decrypts an {@link CryptoUtils.IEncryptedFile | encrypted file} and returns the JSON content.
+ * @typeParam TPayload - Expected type of decrypted content
+ * @param file - The encrypted file structure
+ * @param key - The decryption key (32 bytes for AES-256)
+ * @param cryptoProvider - {@link CryptoUtils.ICryptoProvider | Crypto provider} to use for decryption
+ * @param payloadConverter - Optional converter to validate and convert decrypted content
+ * @returns `Success` with decrypted content, or `Failure` with an error.
+ * @public
+ */
+declare function decryptFile<TPayload extends JsonValue = JsonValue>(file: IEncryptedFile<unknown>, key: Uint8Array, cryptoProvider: ICryptoProvider, payloadConverter?: Converter<TPayload>): Promise<Result<TPayload>>;
+
+/**
+ * Default AI assist settings (copy-paste only).
+ * @public
+ */
+declare const DEFAULT_AI_ASSIST: IAiAssistSettings;
+
+/**
+ * Default encryption algorithm.
+ * @public
+ */
+declare const DEFAULT_ALGORITHM: "AES-256-GCM";
+
+/**
+ * Default PBKDF2 iterations for key store encryption.
+ * Higher than regular files since this protects the master key vault.
+ * @public
+ */
+declare const DEFAULT_KEYSTORE_ITERATIONS: number;
+
 /**
  * Default {@link Experimental.RangeOfFormats | formats} to use for both
  * open-ended and complete {@link Experimental.RangeOf | RangeOf<T>}.
@@ -42,6 +352,107 @@ declare interface CsvOptions {
  */
 declare const DEFAULT_RANGEOF_FORMATS: RangeOfFormats;
 
+/**
+ * Default PBKDF2 iterations for secret-level key derivation.
+ * Lower than keystore encryption since these are used more frequently.
+ * @public
+ */
+declare const DEFAULT_SECRET_ITERATIONS: number;
+
+/**
+ * An {@link IEncryptionProvider} that uses a pre-supplied key and crypto provider.
+ *
+ * This is useful when you have the raw encryption key from an external source
+ * (e.g. a `SecretProvider` callback, password derivation, or a one-shot
+ * operation) and don't want to open a full KeyStore.
+ *
+ * Optionally bound to a specific secret name for safety: if a `boundSecretName`
+ * is provided, calls to `encryptByName` with a different name will fail.
+ *
+ * @example
+ * ```typescript
+ * const provider = DirectEncryptionProvider.create({
+ *   cryptoProvider: nodeCryptoProvider,
+ *   key: myKey,
+ *   boundSecretName: 'my-collection'
+ * }).orThrow();
+ *
+ * const encrypted = await provider.encryptByName('my-collection', jsonContent);
+ * ```
+ *
+ * @public
+ */
+declare class DirectEncryptionProvider implements IEncryptionProvider {
+    private readonly _cryptoProvider;
+    private readonly _key;
+    private readonly _boundSecretName;
+    private constructor();
+    /**
+     * Creates a new DirectEncryptionProvider.
+     * @param params - Provider configuration
+     * @returns Success with provider, or Failure if parameters are invalid
+     * @public
+     */
+    static create(params: IDirectEncryptionProviderParams): Result<DirectEncryptionProvider>;
+    /**
+     * The secret name this provider is bound to, if any.
+     * @public
+     */
+    get boundSecretName(): string | undefined;
+    /**
+     * {@inheritDoc IEncryptionProvider.encryptByName}
+     */
+    encryptByName<TMetadata = JsonValue>(secretName: string, content: JsonValue, metadata?: TMetadata): Promise<Result<IEncryptedFile<TMetadata>>>;
+}
+
+/**
+ * Current format version for encrypted files.
+ * @public
+ */
+declare const ENCRYPTED_FILE_FORMAT: "encrypted-collection-v1";
+
+/**
+ * Default converter for encrypted files without typed metadata.
+ * @public
+ */
+declare const encryptedFile: Converter<IEncryptedFile>;
+
+/**
+ * Behavior when an encrypted file cannot be decrypted.
+ * @public
+ */
+declare type EncryptedFileErrorMode = 'fail' | 'skip' | 'warn';
+
+/**
+ * Converter for {@link CryptoUtils.EncryptedFileErrorMode | encrypted file error mode}.
+ * @public
+ */
+declare const encryptedFileErrorMode: Converter<EncryptedFileErrorMode>;
+
+/**
+ * Format version for encrypted files.
+ * @public
+ */
+declare type EncryptedFileFormat = typeof Constants.ENCRYPTED_FILE_FORMAT;
+
+/**
+ * Converter for {@link CryptoUtils.EncryptedFileFormat | encrypted file format} version.
+ * @public
+ */
+declare const encryptedFileFormat: Converter<EncryptedFileFormat>;
+
+/**
+ * Supported encryption algorithms.
+ * @public
+ */
+declare type EncryptionAlgorithm = typeof Constants.DEFAULT_ALGORITHM;
+
+/**
+ * Converter for {@link CryptoUtils.EncryptionAlgorithm | encryption algorithm} values.
+ * @public
+ */
+declare const encryptionAlgorithm: Converter<EncryptionAlgorithm>;
+
 declare namespace Experimental {
     export {
         ExtendedArray,
@@ -68,178 +479,1523 @@ export { Experimental }
 declare class ExtendedArray<T> extends Array<T> {
     readonly itemDescription: string;
     /**
-     * Constructs an {@link Experimental.ExtendedArray | ExtendedArray}.
-     * @param itemDescription - Brief description of the type of each item in this array.
-     * @param items - The initial contents of the array.
+     * Constructs an {@link Experimental.ExtendedArray | ExtendedArray}.
+     * @param itemDescription - Brief description of the type of each item in this array.
+     * @param items - The initial contents of the array.
+     */
+    constructor(itemDescription: string, ...items: T[]);
+    /**
+     * Type guard to determine if some arbitrary array is an
+     * {@link Experimental.ExtendedArray}
+     * @param a - The `Array` to be tested.
+     * @returns Returns `true` if `a` is an {@link Experimental.ExtendedArray | ExtendedArray},
+     * `false` otherwise.
+     */
+    static isExtendedArray<T>(a?: T[]): a is ExtendedArray<T>;
+    /**
+     * Determines if this array contains exactly one element which matches
+     * a supplied predicate.
+     * @param predicate - The predicate function to be applied.
+     * @returns Returns `Success<T>` with the single matching
+     * result if exactly one item matches `predicate`.  Returns `Failure<T>`
+     * with an error message if there are no matches or more than one match.
+     */
+    single(predicate?: (item: T) => boolean): Result<T>;
+    /**
+     * Returns the first element of an {@link Experimental.ExtendedArray | ExtendedArray}. Fails with an
+     * error message if the array is empty.
+     * @param failMessage - Optional message to be displayed in the event of failure.
+     * @returns Returns `Success<T>` with the value of the first element
+     * in the array, or `Failure<T>` with an error message if the array is empty.
+     */
+    first(failMessage?: string): Result<T>;
+    /**
+     * Returns an array containing all elements of an {@link Experimental.ExtendedArray | ExtendedArray}.
+     * Fails with an error message if the array is empty.
+     * @param failMessage - Optional message to be displayed in the event of failure.
+     * @returns Returns `Success<T>` with a new (non-extended) `Array`
+     * containing the elements of this array, or `Failure<T>` with an error message
+     * if the array is empty.
+     */
+    atLeastOne(failMessage?: string): Result<T[]>;
+    /**
+     * Gets a new (non-extended) `Array` containing all of the elements from this
+     * {@link Experimental.ExtendedArray | ExtendedArray}.
+     * @returns A new (non-extended) `Array<T>`.
+     */
+    all(): T[];
+}
+
+/**
+ * A helper function to create a `Converter` which converts `unknown` to {@link Experimental.ExtendedArray | ExtendedArray<T>}.
+ * @remarks
+ * 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
+ * @beta
+ */
+declare function extendedArrayOf<T, TC = undefined>(label: string, converter: Converter<T, TC>, onError?: Conversion.OnError): Converter<ExtendedArray<T>, TC>;
+
+/**
+ * Formats a list of items using the supplied template and formatter, one result
+ * per output line.
+ * @param format - A mustache template used to format each item.
+ * @param items - The items to be formatted.
+ * @param itemFormatter - The {@link Experimental.Formatter | Formatter<T>} used to format each item.
+ * @returns The resulting string.
+ * @beta
+ */
+declare function formatList<T>(format: string, items: T[], itemFormatter: Formatter<T>): Result<string>;
+
+/**
+ * Interface for an object that can be formatted.
+ * @beta
+ */
+declare interface Formattable {
+    /**
+     * Formats an object using the supplied mustache template.
+     * @param format - A mustache template used to format the object.
+     * @returns `Success<string>` with the resulting string, or `Failure<string>`
+     * with an error message if an error occurs.
+     */
+    format(format: string): Result<string>;
+}
+
+/**
+ * Base class which adds common formatting.
+ * @beta
+ */
+declare class FormattableBase {
+    /**
+     * Helper enables derived classes to add named details to a formatted presentation.
+     * @param details - An array of detail description strings.
+     * @param label - Label to use for the new detail.
+     * @param value - Value to use for the new detail.
+     * @internal
+     */
+    protected static _tryAddDetail(details: string[], label: string, value: string | undefined): void;
+    /**
+     * {@inheritDoc Experimental.Formattable.format}
+     */
+    format(template: string): Result<string>;
+}
+
+/**
+ * Destination format for some formatted string.
+ * @beta
+ */
+declare type FormatTargets = 'text' | 'markdown' | 'embed';
+
+/**
+ * Type definition for a formatting function, which takes a `string` and an
+ * item and returns `Result<string>`.
+ * @beta
+ */
+declare type Formatter<T> = (format: string, item: T) => Result<string>;
+
+/**
+ * A collection of {@link Experimental.Formatter | formatters} indexed by target name, to enable
+ * different format methods per output target.
+ * @beta
+ */
+declare type FormattersByExtendedTarget<TFT extends FormatTargets, T> = Record<TFT, Formatter<T>>;
+
+/**
+ * A collection of {@link Experimental.Formatter | formatters} indexed by the
+ * {@link Experimental.FormatTargets | default supported target formats}.
+ * @beta
+ */
+declare type FormattersByTarget<T> = FormattersByExtendedTarget<FormatTargets, T>;
+
+/**
+ * Decodes a base64 string to a `Uint8Array`.
+ * @param base64 - Base64 string to decode
+ * @returns Decoded bytes
+ * @public
+ */
+declare function fromBase64(base64: string): Uint8Array;
+
+/**
+ * Auth tag size in bytes for GCM mode.
+ * @public
+ */
+declare const GCM_AUTH_TAG_SIZE: number;
+
+/**
+ * IV size in bytes for GCM mode.
+ * @public
+ */
+declare const GCM_IV_SIZE: number;
+
+/**
+ * Get a provider descriptor by id.
+ * @param id - The provider identifier
+ * @returns The descriptor, or a failure if the provider is unknown
+ * @public
+ */
+declare function getProviderDescriptor(id: string): Result<IAiProviderDescriptor>;
+
+/**
+ * Get all known provider descriptors. Copy-paste first, then alphabetical.
+ * @returns All built-in provider descriptors
+ * @public
+ */
+declare function getProviderDescriptors(): ReadonlyArray<IAiProviderDescriptor>;
+
+declare namespace Hash {
+    export {
+        Md5Normalizer
+    }
+}
+export { Hash }
+
+/**
+ * Options for adding a secret derived from a password.
+ * @public
+ */
+declare interface IAddSecretFromPasswordOptions extends IAddSecretOptions {
+    /**
+     * Whether to replace an existing secret with the same name.
+     */
+    readonly replace?: boolean;
+    /**
+     * PBKDF2 iterations for key derivation.
+     * @defaultValue DEFAULT_SECRET_ITERATIONS (350000)
+     */
+    readonly iterations?: number;
+}
+
+/**
+ * Result of adding a password-derived secret.
+ * Extends {@link IAddSecretResult} with key derivation parameters
+ * needed to store alongside encrypted files.
+ * @public
+ */
+declare interface IAddSecretFromPasswordResult extends IAddSecretResult {
+    /**
+     * Key derivation parameters used to derive the secret key.
+     * Store these in encrypted file metadata so the password alone
+     * can re-derive the same key for decryption.
+     */
+    readonly keyDerivation: IKeyDerivationParams;
+}
+
+/**
+ * Options for adding a secret.
+ * @public
+ */
+declare interface IAddSecretOptions {
+    /**
+     * Optional description for the secret.
+     */
+    readonly description?: string;
+}
+
+/**
+ * Result of adding a secret to the key store.
+ * @public
+ */
+declare interface IAddSecretResult {
+    /**
+     * The secret entry that was added.
+     */
+    readonly entry: IKeyStoreSecretEntry;
+    /**
+     * Whether this replaced an existing secret.
+     */
+    readonly replaced: boolean;
+}
+
+/**
+ * Minimal keystore interface for AI assist API key resolution.
+ * Satisfied structurally by the concrete `KeyStore` class from `@fgv/ts-extras`.
+ * @public
+ */
+declare interface IAiAssistKeyStore {
+    /** Whether the keystore is currently unlocked */
+    readonly isUnlocked: boolean;
+    /** Check if a named secret exists */
+    hasSecret(name: string): Result<boolean>;
+    /** Get an API key by secret name */
+    getApiKey(name: string): Result<string>;
+}
+
+/**
+ * Configuration for a single AI assist provider.
+ * @public
+ */
+declare interface IAiAssistProviderConfig {
+    /** Which provider this configures */
+    readonly provider: AiProviderId;
+    /** For API-based providers: the keystore secret name holding the API key */
+    readonly secretName?: string;
+    /** Optional model override — string or context-aware map. */
+    readonly model?: ModelSpec;
+    /** Tool enablement/configuration. Tools are disabled unless explicitly enabled. */
+    readonly tools?: ReadonlyArray<IAiToolEnablement>;
+}
+
+/**
+ * AI assist settings — which providers are enabled and their configuration.
+ * @public
+ */
+declare interface IAiAssistSettings {
+    /** Enabled providers and their configuration. */
+    readonly providers: ReadonlyArray<IAiAssistProviderConfig>;
+    /** Which enabled provider is the default for the main button. Falls back to first in list. */
+    readonly defaultProvider?: AiProviderId;
+    /** Optional proxy URL for routing API requests through a backend server (e.g. `http://localhost:3002`). */
+    readonly proxyUrl?: string;
+    /** When true, route all providers through the proxy. When false (default), only CORS-restricted providers use the proxy. */
+    readonly proxyAllProviders?: boolean;
+}
+
+/**
+ * Result of an AI provider completion call.
+ * @public
+ */
+declare interface IAiCompletionResponse {
+    /** The generated text content */
+    readonly content: string;
+    /** Whether the response was truncated due to token limits */
+    readonly truncated: boolean;
+}
+
+/**
+ * Describes a single AI provider — single source of truth for all metadata.
+ * @public
+ */
+declare interface IAiProviderDescriptor {
+    /** Provider identifier (e.g. 'xai-grok', 'anthropic') */
+    readonly id: AiProviderId;
+    /** Human-readable label (e.g. "xAI Grok") */
+    readonly label: string;
+    /** Button label for action buttons (e.g. "AI Assist | Grok") */
+    readonly buttonLabel: string;
+    /** Whether this provider requires an API key secret */
+    readonly needsSecret: boolean;
+    /** Which API adapter format to use */
+    readonly apiFormat: AiApiFormat;
+    /** Base URL for the API (e.g. 'https://api.x.ai/v1') */
+    readonly baseUrl: string;
+    /** Default model specification — string or context-aware map. */
+    readonly defaultModel: ModelSpec;
+    /** Which server-side tools this provider supports (empty = none). */
+    readonly supportedTools: ReadonlyArray<AiServerToolType>;
+    /** Whether this provider's API enforces CORS restrictions that prevent direct browser calls. */
+    readonly corsRestricted: boolean;
+}
+
+/**
+ * Declares a tool as enabled/disabled in provider settings.
+ * Tools are disabled by default — consuming apps must opt in explicitly.
+ * @public
+ */
+declare interface IAiToolEnablement {
+    /** Which tool type. */
+    readonly type: AiServerToolType;
+    /** Whether this tool is enabled by default for this provider. */
+    readonly enabled: boolean;
+    /** Optional tool-specific configuration. */
+    readonly config?: AiServerToolConfig;
+}
+
+/**
+ * Configuration specific to web search tools.
+ * @public
+ */
+declare interface IAiWebSearchToolConfig {
+    readonly type: 'web_search';
+    /** Optional: restrict search to these domains. */
+    readonly allowedDomains?: ReadonlyArray<string>;
+    /** Optional: exclude these domains from search. */
+    readonly blockedDomains?: ReadonlyArray<string>;
+    /** Optional: max number of searches per request. */
+    readonly maxUses?: number;
+    /**
+     * Optional: enable image understanding during web search.
+     * When true, the model can view and analyze images found during search.
+     * Currently supported by xAI only; ignored by other providers.
+     */
+    readonly enableImageUnderstanding?: boolean;
+}
+
+/**
+ * A single chat message in OpenAI format.
+ * @public
+ */
+declare interface IChatMessage {
+    /** Message role */
+    readonly role: 'system' | 'user' | 'assistant';
+    /** Message content */
+    readonly content: string;
+}
+
+/**
+ * Result of context validation, containing details about missing variables.
+ * @public
+ */
+declare interface IContextValidationResult {
+    /**
+     * Whether the context is valid (has all required variables)
+     */
+    readonly isValid: boolean;
+    /**
+     * Variables that are present in the context
+     */
+    readonly presentVariables: readonly string[];
+    /**
+     * Variables that are missing from the context
+     */
+    readonly missingVariables: readonly string[];
+    /**
+     * Detailed information about each missing variable
+     */
+    readonly missingDetails: readonly IMissingVariableDetail[];
+}
+
+/**
+ * Parameters for creating an {@link CryptoUtils.IEncryptedFile | encrypted file}.
+ * @typeParam TMetadata - Type of optional unencrypted metadata
+ * @public
+ */
+declare interface ICreateEncryptedFileParams<TMetadata = JsonValue> {
+    /**
+     * The JSON content to encrypt.
+     */
+    readonly content: JsonValue;
+    /**
+     * Name of the secret used for encryption.
+     */
+    readonly secretName: string;
+    /**
+     * The encryption key (32 bytes for AES-256).
+     */
+    readonly key: Uint8Array;
+    /**
+     * {@link CryptoUtils.ICryptoProvider | Crypto provider} to use for encryption.
+     */
+    readonly cryptoProvider: ICryptoProvider;
+    /**
+     * Optional metadata to include unencrypted.
+     */
+    readonly metadata?: TMetadata;
+    /**
+     * Optional converter to validate metadata before including.
+     * If provided, metadata will be validated before encryption.
+     */
+    readonly metadataConverter?: Converter<TMetadata>;
+    /**
+     * Optional {@link CryptoUtils.IKeyDerivationParams | key derivation parameters}.
+     * If provided, stores the salt and iterations used to derive the key from a password.
+     * This allows decryption using only a password (the salt/iterations are read from the file).
+     */
+    readonly keyDerivation?: IKeyDerivationParams;
+}
+
+/**
+ * Options for creating a zip file from text files.
+ * @public
+ */
+declare interface ICreateZipOptions {
+    readonly level?: ZipCompressionLevel;
+}
+
+/**
+ * Crypto provider interface for cross-platform encryption.
+ * Implementations provided for Node.js (crypto module) and browser (Web Crypto API).
+ * @public
+ */
+declare interface ICryptoProvider {
+    /**
+     * Encrypts plaintext using AES-256-GCM.
+     * @param plaintext - UTF-8 string to encrypt
+     * @param key - 32-byte encryption key
+     * @returns Success with encryption result, or Failure with error
+     */
+    encrypt(plaintext: string, key: Uint8Array): Promise<Result<IEncryptionResult>>;
+    /**
+     * Decrypts ciphertext using AES-256-GCM.
+     * @param encryptedData - Encrypted bytes
+     * @param key - 32-byte decryption key
+     * @param iv - Initialization vector (12 bytes)
+     * @param authTag - GCM authentication tag (16 bytes)
+     * @returns Success with decrypted UTF-8 string, or Failure with error
+     */
+    decrypt(encryptedData: Uint8Array, key: Uint8Array, iv: Uint8Array, authTag: Uint8Array): Promise<Result<string>>;
+    /**
+     * Generates a random 32-byte key suitable for AES-256.
+     * @returns Success with generated key, or Failure with error
+     */
+    generateKey(): Promise<Result<Uint8Array>>;
+    /**
+     * Derives a key from a password using PBKDF2.
+     * @param password - Password string
+     * @param salt - Salt bytes (should be at least 16 bytes)
+     * @param iterations - Number of iterations (recommend 100000+)
+     * @returns Success with derived 32-byte key, or Failure with error
+     */
+    deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<Result<Uint8Array>>;
+    /**
+     * Generates cryptographically secure random bytes.
+     * @param length - Number of bytes to generate
+     * @returns Success with random bytes, or Failure with error
+     */
+    generateRandomBytes(length: number): Result<Uint8Array>;
+    /**
+     * Encodes binary data to base64 string.
+     * @param data - Binary data to encode
+     * @returns Base64-encoded string
+     */
+    toBase64(data: Uint8Array): string;
+    /**
+     * Decodes base64 string to binary data.
+     * @param base64 - Base64-encoded string
+     * @returns Success with decoded bytes, or Failure if invalid base64
+     */
+    fromBase64(base64: string): Result<Uint8Array>;
+}
+
+/**
+ * Parameters for creating a {@link DirectEncryptionProvider}.
+ * @public
+ */
+declare interface IDirectEncryptionProviderParams {
+    /**
+     * The crypto provider to use for encryption operations.
+     */
+    readonly cryptoProvider: ICryptoProvider;
+    /**
+     * The encryption key (32 bytes for AES-256).
+     */
+    readonly key: Uint8Array;
+    /**
+     * Optional bound secret name.
+     * When set, `encryptByName` will fail if called with a different name.
+     * When unset, any secret name is accepted.
+     */
+    readonly boundSecretName?: string;
+}
+
+/**
+ * Generic encrypted file format.
+ * This is the JSON structure stored in encrypted files.
+ * @typeParam TMetadata - Type of optional unencrypted metadata
+ * @public
+ */
+declare interface IEncryptedFile<TMetadata = JsonValue> {
+    /**
+     * Format identifier for versioning.
+     */
+    readonly format: EncryptedFileFormat;
+    /**
+     * Name of the secret required to decrypt (references INamedSecret.name).
+     */
+    readonly secretName: string;
+    /**
+     * Algorithm used for encryption.
+     */
+    readonly algorithm: EncryptionAlgorithm;
+    /**
+     * Base64-encoded initialization vector.
+     */
+    readonly iv: string;
+    /**
+     * Base64-encoded authentication tag (for GCM mode).
+     */
+    readonly authTag: string;
+    /**
+     * Base64-encoded encrypted data (JSON string when decrypted).
+     */
+    readonly encryptedData: string;
+    /**
+     * Optional unencrypted metadata for display/filtering.
+     */
+    readonly metadata?: TMetadata;
+    /**
+     * Optional key derivation parameters.
+     * If present, allows decryption using a password with these parameters.
+     * If absent, a pre-derived key must be provided.
+     */
+    readonly keyDerivation?: IKeyDerivationParams;
+}
+
+/**
+ * Configuration for encrypted file handling during loading.
+ * @public
+ */
+declare interface IEncryptionConfig {
+    /**
+     * Named secrets available for decryption.
+     */
+    readonly secrets?: ReadonlyArray<INamedSecret>;
+    /**
+     * Alternative: dynamic secret provider function.
+     * Called when a secret is not found in the secrets array.
+     */
+    readonly secretProvider?: SecretProvider;
+    /**
+     * Crypto provider implementation (Node.js or browser).
+     */
+    readonly cryptoProvider: ICryptoProvider;
+    /**
+     * Behavior when decryption key is missing (default: 'fail').
+     */
+    readonly onMissingKey?: EncryptedFileErrorMode;
+    /**
+     * Behavior when decryption fails (default: 'fail').
+     */
+    readonly onDecryptionError?: EncryptedFileErrorMode;
+}
+
+/**
+ * High-level interface for encrypting JSON content by secret name.
+ *
+ * This abstraction unifies two common encryption workflows:
+ * - **KeyStore**: looks up the named secret and crypto provider from the vault
+ * - **DirectEncryptionProvider**: uses a pre-supplied key and crypto provider,
+ *   optionally bound to a specific secret name for safety
+ *
+ * Callers that need to encrypt (e.g. `EditableCollection.save()`) depend on
+ * this interface rather than on `KeyStore` directly, allowing mix-and-match.
+ *
+ * @public
+ */
+declare interface IEncryptionProvider {
+    /**
+     * Encrypts JSON content under a named secret.
+     *
+     * @param secretName - Name of the secret to encrypt with
+     * @param content - JSON-safe content to encrypt
+     * @param metadata - Optional unencrypted metadata to include in the encrypted file
+     * @returns Success with encrypted file structure, or Failure with error context
+     */
+    encryptByName<TMetadata = JsonValue>(secretName: string, content: JsonValue, metadata?: TMetadata): Promise<Result<IEncryptedFile<TMetadata>>>;
+}
+
+/**
+ * Result of an encryption operation.
+ * @public
+ */
+declare interface IEncryptionResult {
+    /**
+     * Initialization vector used for encryption (12 bytes for GCM).
+     */
+    readonly iv: Uint8Array;
+    /**
+     * Authentication tag from GCM mode (16 bytes).
+     */
+    readonly authTag: Uint8Array;
+    /**
+     * The encrypted data.
+     */
+    readonly encryptedData: Uint8Array;
+}
+
+/**
+ * Options for importing a secret.
+ * @public
+ */
+declare interface IImportSecretOptions extends IAddSecretOptions {
+    /**
+     * Whether to replace an existing secret with the same name.
+     */
+    readonly replace?: boolean;
+}
+
+/**
+ * Key derivation parameters stored in encrypted files.
+ * Allows decryption with password without needing to know the original salt/iterations.
+ * @public
+ */
+declare interface IKeyDerivationParams {
+    /**
+     * Key derivation function used.
+     */
+    readonly kdf: KeyDerivationFunction;
+    /**
+     * Base64-encoded salt used for key derivation.
+     */
+    readonly salt: string;
+    /**
+     * Number of iterations used for key derivation.
+     */
+    readonly iterations: number;
+}
+
+/**
+ * Parameters for creating a new key store.
+ * @public
+ */
+declare interface IKeyStoreCreateParams {
+    /**
+     * Crypto provider to use.
+     */
+    readonly cryptoProvider: ICryptoProvider;
+    /**
+     * PBKDF2 iterations (defaults to DEFAULT_KEYSTORE_ITERATIONS).
+     */
+    readonly iterations?: number;
+}
+
+/**
+ * The encrypted key store file format.
+ * @public
+ */
+declare interface IKeyStoreFile {
+    /**
+     * Format identifier.
+     */
+    readonly format: KeyStoreFormat;
+    /**
+     * Algorithm used for encryption.
+     */
+    readonly algorithm: EncryptionAlgorithm;
+    /**
+     * Base64-encoded initialization vector.
+     */
+    readonly iv: string;
+    /**
+     * Base64-encoded authentication tag.
+     */
+    readonly authTag: string;
+    /**
+     * Base64-encoded encrypted vault contents.
+     */
+    readonly encryptedData: string;
+    /**
+     * Key derivation parameters (required for key store - always password-derived).
+     */
+    readonly keyDerivation: IKeyDerivationParams;
+}
+
+/**
+ * Parameters for opening an existing key store.
+ * @public
+ */
+declare interface IKeyStoreOpenParams {
+    /**
+     * Crypto provider to use.
+     */
+    readonly cryptoProvider: ICryptoProvider;
+    /**
+     * The encrypted key store file content.
+     */
+    readonly keystoreFile: IKeyStoreFile;
+}
+
+/**
+ * A secret entry stored in the vault (in-memory representation).
+ * @public
+ */
+declare interface IKeyStoreSecretEntry {
+    /**
+     * Unique name for this secret (used as lookup key).
+     */
+    readonly name: string;
+    /**
+     * Secret type discriminator.
+     * Defaults to `'encryption-key'` for backwards compatibility.
+     */
+    readonly type: KeyStoreSecretType;
+    /**
+     * The secret data.
+     * - For `'encryption-key'`: 32-byte AES-256 key.
+     * - For `'api-key'`: UTF-8 encoded API key string (arbitrary length).
+     */
+    readonly key: Uint8Array;
+    /**
+     * Optional description for this secret.
+     */
+    readonly description?: string;
+    /**
+     * When this secret was added (ISO 8601).
+     */
+    readonly createdAt: string;
+}
+
+/**
+ * JSON-serializable version of secret entry (for storage).
+ * @public
+ */
+declare interface IKeyStoreSecretEntryJson {
+    /**
+     * Unique name for this secret.
+     */
+    readonly name: string;
+    /**
+     * Secret type discriminator.
+     * Optional for backwards compatibility — missing means `'encryption-key'`.
+     */
+    readonly type?: KeyStoreSecretType;
+    /**
+     * Base64-encoded secret data.
+     */
+    readonly key: string;
+    /**
+     * Optional description.
+     */
+    readonly description?: string;
+    /**
+     * When this secret was added (ISO 8601).
+     */
+    readonly createdAt: string;
+}
+
+/**
+ * The decrypted vault contents - a versioned map of secrets.
+ * @public
+ */
+declare interface IKeyStoreVaultContents {
+    /**
+     * Format version for vault contents.
+     */
+    readonly version: KeyStoreFormat;
+    /**
+     * Map of secret name to secret entry.
+     */
+    readonly secrets: Record<string, IKeyStoreSecretEntryJson>;
+}
+
+/**
+ * Details about a missing variable in context validation.
+ * @public
+ */
+declare interface IMissingVariableDetail {
+    /**
+     * The variable reference that is missing
+     */
+    readonly variable: IVariableRef;
+    /**
+     * The path segment where the lookup failed
+     * (e.g., for 'user.profile.name' if 'profile' is missing, this would be 'profile')
+     */
+    readonly failedAtSegment?: string;
+    /**
+     * The parent path that exists (e.g., ['user'] if 'user' exists but 'user.profile' does not)
+     */
+    readonly existingPath: readonly string[];
+}
+
+/**
+ * A model specification: either a simple model string or a record mapping
+ * context keys to nested model specs.
+ *
+ * @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).
+ *
+ * @example
+ * ```typescript
+ * // Simple — same model for all contexts:
+ * const simple: ModelSpec = 'grok-4-1-fast';
+ *
+ * // Context-aware — reasoning model when tools are active:
+ * const split: ModelSpec = { base: 'grok-4-1-fast', tools: 'grok-4-1-fast-reasoning' };
+ *
+ * // Future nested — per-tool model selection:
+ * const nested: ModelSpec = { base: 'grok-fast', tools: { base: 'grok-r', image: 'grok-v' } };
+ * ```
+ * @public
+ */
+declare interface IModelSpecMap {
+    readonly [key: string]: ModelSpec;
+}
+
+/**
+ * Options for template parsing and validation.
+ * @public
+ */
+declare interface IMustacheTemplateOptions {
+    /**
+     * Custom opening and closing tags (default: `['{{', '}}']`)
+     */
+    readonly tags?: readonly [string, string];
+    /**
+     * Whether to include comment tokens in variable extraction (default: false)
+     */
+    readonly includeComments?: boolean;
+    /**
+     * Whether to include partial references in variable extraction (default: false)
+     */
+    readonly includePartials?: boolean;
+}
+
+/**
+ * Named secret for encryption/decryption.
+ * @public
+ */
+declare interface INamedSecret {
+    /**
+     * Unique name for this secret (referenced in encrypted files).
+     */
+    readonly name: string;
+    /**
+     * The actual secret key (32 bytes for AES-256).
+     */
+    readonly key: Uint8Array;
+}
+
+/**
+ * Parameters for a provider completion request.
+ * @public
+ */
+declare interface IProviderCompletionParams {
+    /** The provider descriptor */
+    readonly descriptor: IAiProviderDescriptor;
+    /** API key for authentication */
+    readonly apiKey: string;
+    /** The structured prompt to send */
+    readonly prompt: AiPrompt;
+    /**
+     * Additional messages to append after system+user (e.g. for correction retries).
+     * These are appended in order after the initial system and user messages.
+     */
+    readonly additionalMessages?: ReadonlyArray<IChatMessage>;
+    /** Sampling temperature (default: 0.7) */
+    readonly temperature?: number;
+    /** Optional model override — string or context-aware map (uses descriptor.defaultModel otherwise) */
+    readonly modelOverride?: ModelSpec;
+    /** Optional logger for request/response observability. */
+    readonly logger?: Logging.ILogger;
+    /** Server-side tools to include in the request. Overrides settings-level tool config when provided. */
+    readonly tools?: ReadonlyArray<AiServerToolConfig>;
+}
+
+/**
+ * Required version of options with all fields populated.
+ * @internal
+ */
+declare interface IRequiredMustacheTemplateOptions {
+    readonly tags: [string, string];
+    readonly includeComments: boolean;
+    readonly includePartials: boolean;
+}
+
+/**
+ * Checks if a JSON object appears to be an encrypted file.
+ * Uses the format field as a discriminator.
+ * @param json - JSON object to check
+ * @returns true if the object has the encrypted file format field
+ * @public
+ */
+declare function isEncryptedFile(json: unknown): boolean;
+
+/**
+ * Checks if a JSON object appears to be a key store file.
+ * Uses the format field as a discriminator.
+ * @param json - JSON object to check
+ * @returns true if the object has the key store format field
+ * @public
+ */
+declare function isKeyStoreFile(json: unknown): boolean;
+
+/**
+ * A `Converter` which converts an iso formatted string, a number or a `Date` object to
+ * a `Date` object.
+ * @public
+ */
+declare const isoDate: Converter<Date, unknown>;
+
+/**
+ * Represents a variable reference extracted from a Mustache template.
+ * @public
+ */
+declare interface IVariableRef {
+    /**
+     * The raw variable name as it appears in the template (e.g., 'user.name')
+     */
+    readonly name: string;
+    /**
+     * The path segments parsed from the variable name (e.g., ['user', 'name'])
+     */
+    readonly path: readonly string[];
+    /**
+     * The type of token this variable was extracted from
+     */
+    readonly tokenType: MustacheTokenType;
+    /**
+     * Whether this variable is used in a section context (# or ^)
+     * Section variables may reference arrays/objects for iteration
+     */
+    readonly isSection: boolean;
+}
+
+/**
+ * Simple interface for a file to be added to a zip file.
+ * @public
+ */
+declare interface IZipTextFile {
+    readonly path: string;
+    readonly contents: string;
+}
+
+/**
+ * @public
+ */
+declare type JarFieldPicker<T extends JarRecord = JarRecord> = (record: T) => (keyof T)[];
+
+/**
+ * Represents a single record in a JAR file
+ * @public
+ */
+declare type JarRecord = Record<string, string | string[]>;
+
+/**
+ * Options for a JAR record parser.
+ * @public
+ */
+declare interface JarRecordParserOptions {
+    readonly arrayFields?: string[] | JarFieldPicker;
+    readonly fixedContinuationSize?: number;
+}
+
+/**
+ * Supported key derivation functions.
+ * @public
+ */
+declare type KeyDerivationFunction = 'pbkdf2';
+
+/**
+ * Converter for {@link CryptoUtils.KeyDerivationFunction | key derivation function} type.
+ * @public
+ */
+declare const keyDerivationFunction: Converter<KeyDerivationFunction>;
+
+/**
+ * Converter for {@link CryptoUtils.IKeyDerivationParams | key derivation parameters}.
+ * @public
+ */
+declare const keyDerivationParams: Converter<IKeyDerivationParams>;
+
+declare namespace KeyStore {
+    export {
+        Converters_2 as Converters,
+        KeyStore_2 as KeyStore,
+        isKeyStoreFile,
+        KeyStoreFormat,
+        KEYSTORE_FORMAT,
+        DEFAULT_KEYSTORE_ITERATIONS,
+        MIN_SALT_LENGTH,
+        KeyStoreSecretType,
+        allKeyStoreSecretTypes,
+        IKeyStoreSecretEntry,
+        IKeyStoreSecretEntryJson,
+        IKeyStoreVaultContents,
+        IKeyStoreFile,
+        KeyStoreLockState,
+        IKeyStoreCreateParams,
+        IKeyStoreOpenParams,
+        IAddSecretResult,
+        IAddSecretOptions,
+        IImportSecretOptions,
+        IAddSecretFromPasswordOptions,
+        DEFAULT_SECRET_ITERATIONS,
+        IAddSecretFromPasswordResult
+    }
+}
+
+/**
+ * Password-protected key store for managing encryption secrets.
+ *
+ * The KeyStore provides a secure vault for storing named encryption keys.
+ * The vault is encrypted at rest using a master password via PBKDF2 key derivation.
+ *
+ * @example
+ * ```typescript
+ * // Create new key store
+ * const keystore = KeyStore.create({ cryptoProvider: nodeCryptoProvider }).orThrow();
+ * await keystore.initialize('master-password');
+ *
+ * // Add secrets
+ * await keystore.addSecret('my-key', { description: 'Production key' });
+ *
+ * // Save to file
+ * const fileContent = await keystore.save();
+ *
+ * // Later: Open existing key store
+ * const keystore2 = KeyStore.open({
+ *   cryptoProvider: nodeCryptoProvider,
+ *   keystoreFile: fileContent.value
+ * }).orThrow();
+ * await keystore2.unlock('master-password');
+ *
+ * // Use as secret provider for encrypted file loading
+ * const encryptionConfig = keystore2.getEncryptionConfig().orThrow();
+ * ```
+ *
+ * @public
+ */
+declare class KeyStore_2 implements IEncryptionProvider {
+    private readonly _cryptoProvider;
+    private readonly _iterations;
+    private _keystoreFile;
+    private _salt;
+    private _secrets;
+    private _state;
+    private _dirty;
+    private _isNew;
+    private constructor();
+    /**
+     * Creates a new, empty key store.
+     * Call `initialize(password)` to set the master password.
+     * @param params - Creation parameters
+     * @returns Success with new KeyStore instance, or Failure if parameters invalid
+     * @public
+     */
+    static create(params: IKeyStoreCreateParams): Result<KeyStore_2>;
+    /**
+     * Opens an existing encrypted key store.
+     * Call `unlock(password)` to decrypt and access secrets.
+     * @param params - Open parameters including the encrypted file
+     * @returns Success with KeyStore instance, or Failure if file format invalid
+     * @public
+     */
+    static open(params: IKeyStoreOpenParams): Result<KeyStore_2>;
+    /**
+     * Initializes a new key store with the master password.
+     * Generates a random salt for key derivation.
+     * Only valid for newly created (not opened) key stores.
+     * @param password - The master password
+     * @returns Success with this instance when initialized, Failure if already initialized or opened
+     * @public
+     */
+    initialize(password: string): Promise<Result<KeyStore_2>>;
+    /**
+     * Unlocks an existing key store with the master password.
+     * Decrypts the vault and loads secrets into memory.
+     * @param password - The master password
+     * @returns Success with this instance when unlocked, Failure if password incorrect
+     * @public
+     */
+    unlock(password: string): Promise<Result<KeyStore_2>>;
+    /**
+     * Locks the key store, clearing all secrets from memory.
+     * @param force - If true, discards unsaved changes
+     * @returns Success when locked, Failure if unsaved changes and !force
+     * @public
+     */
+    lock(force?: boolean): Result<KeyStore_2>;
+    /**
+     * Checks if the key store is unlocked.
+     * @public
+     */
+    get isUnlocked(): boolean;
+    /**
+     * Checks if there are unsaved changes.
+     * @public
+     */
+    get isDirty(): boolean;
+    /**
+     * Whether this is a newly created key store (not opened from a file).
+     * A new key store must be initialized with a password before use.
+     * An opened key store must be unlocked with the existing password.
+     * @public
+     */
+    get isNew(): boolean;
+    /**
+     * Gets the current lock state.
+     * @public
+     */
+    get state(): KeyStoreLockState;
+    /**
+     * Gets the crypto provider used by this key store.
+     * Available regardless of lock state.
+     * @public
+     */
+    get cryptoProvider(): ICryptoProvider;
+    /**
+     * Lists all secret names in the key store.
+     * @returns Success with array of secret names, Failure if locked
+     * @public
+     */
+    listSecrets(): Result<readonly string[]>;
+    /**
+     * Gets a secret by name.
+     * @param name - Name of the secret
+     * @returns Success with secret entry, Failure if not found or locked
+     * @public
+     */
+    getSecret(name: string): Result<IKeyStoreSecretEntry>;
+    /**
+     * Checks if a secret exists.
+     * @param name - Name of the secret
+     * @returns Success with boolean, Failure if locked
+     * @public
      */
-    constructor(itemDescription: string, ...items: T[]);
+    hasSecret(name: string): Result<boolean>;
     /**
-     * Type guard to determine if some arbitrary array is an
-     * {@link Experimental.ExtendedArray}
-     * @param a - The `Array` to be tested.
-     * @returns Returns `true` if `a` is an {@link Experimental.ExtendedArray | ExtendedArray},
-     * `false` otherwise.
+     * Adds a new secret with a randomly generated key.
+     * @param name - Unique name for the secret
+     * @param options - Optional description
+     * @returns Success with the generated entry, Failure if locked or name invalid
+     * @public
      */
-    static isExtendedArray<T>(a?: T[]): a is ExtendedArray<T>;
+    addSecret(name: string, options?: IAddSecretOptions): Promise<Result<IAddSecretResult>>;
     /**
-     * Determines if this array contains exactly one element which matches
-     * a supplied predicate.
-     * @param predicate - The predicate function to be applied.
-     * @returns Returns `Success<T>` with the single matching
-     * result if exactly one item matches `predicate`.  Returns `Failure<T>`
-     * with an error message if there are no matches or more than one match.
+     * Imports an existing secret key.
+     * @param name - Unique name for the secret
+     * @param key - The 32-byte AES-256 key
+     * @param options - Optional description, whether to replace existing
+     * @returns Success with entry, Failure if locked, key invalid, or exists and !replace
+     * @public
      */
-    single(predicate?: (item: T) => boolean): Result<T>;
+    importSecret(name: string, key: Uint8Array, options?: IImportSecretOptions): Result<IAddSecretResult>;
     /**
-     * Returns the first element of an {@link Experimental.ExtendedArray | ExtendedArray}. Fails with an
-     * error message if the array is empty.
-     * @param failMessage - Optional message to be displayed in the event of failure.
-     * @returns Returns `Success<T>` with the value of the first element
-     * in the array, or `Failure<T>` with an error message if the array is empty.
+     * Adds a secret derived from a password using PBKDF2.
+     *
+     * Generates a random salt, derives a 32-byte AES-256 key from the password,
+     * and stores it in the vault. Returns the key derivation parameters so they
+     * can be stored alongside encrypted files, enabling decryption with just the
+     * password (without unlocking the keystore).
+     *
+     * @param name - Unique name for the secret
+     * @param password - Password to derive the key from
+     * @param options - Optional description, iterations, replace flag
+     * @returns Success with entry and keyDerivation params, Failure if locked or invalid
+     * @public
      */
-    first(failMessage?: string): Result<T>;
+    addSecretFromPassword(name: string, password: string, options?: IAddSecretFromPasswordOptions): Promise<Result<IAddSecretFromPasswordResult>>;
     /**
-     * Returns an array containing all elements of an {@link Experimental.ExtendedArray | ExtendedArray}.
-     * Fails with an error message if the array is empty.
-     * @param failMessage - Optional message to be displayed in the event of failure.
-     * @returns Returns `Success<T>` with a new (non-extended) `Array`
-     * containing the elements of this array, or `Failure<T>` with an error message
-     * if the array is empty.
+     * Removes a secret by name.
+     * @param name - Name of the secret to remove
+     * @returns Success with removed entry, Failure if not found or locked
+     * @public
      */
-    atLeastOne(failMessage?: string): Result<T[]>;
+    removeSecret(name: string): Result<IKeyStoreSecretEntry>;
     /**
-     * Gets a new (non-extended) `Array` containing all of the elements from this
-     * {@link Experimental.ExtendedArray | ExtendedArray}.
-     * @returns A new (non-extended) `Array<T>`.
+     * Imports an API key string into the vault.
+     * The string is UTF-8 encoded and stored with type `'api-key'`.
+     * @param name - Unique name for the secret
+     * @param apiKey - The API key string
+     * @param options - Optional description, whether to replace existing
+     * @returns Success with entry, Failure if locked, empty, or exists and !replace
+     * @public
      */
-    all(): T[];
+    importApiKey(name: string, apiKey: string, options?: IImportSecretOptions): Result<IAddSecretResult>;
+    /**
+     * Retrieves an API key string by name.
+     * Only works for secrets with type `'api-key'`.
+     * @param name - Name of the secret
+     * @returns Success with the API key string, Failure if not found, locked, or wrong type
+     * @public
+     */
+    getApiKey(name: string): Result<string>;
+    /**
+     * Lists secret names filtered by type.
+     * @param type - The secret type to filter by
+     * @returns Success with array of matching secret names, Failure if locked
+     * @public
+     */
+    listSecretsByType(type: KeyStoreSecretType): Result<readonly string[]>;
+    /**
+     * Renames a secret.
+     * @param oldName - Current name
+     * @param newName - New name
+     * @returns Success with updated entry, Failure if source not found, target exists, or locked
+     * @public
+     */
+    renameSecret(oldName: string, newName: string): Result<IKeyStoreSecretEntry>;
+    /**
+     * Saves the key store, returning the encrypted file content.
+     * Requires the master password to encrypt.
+     * @param password - The master password
+     * @returns Success with IKeyStoreFile, Failure if locked
+     * @public
+     */
+    save(password: string): Promise<Result<IKeyStoreFile>>;
+    /**
+     * Changes the master password.
+     * Re-encrypts the vault with the new password-derived key.
+     * @param currentPassword - Current master password (for verification)
+     * @param newPassword - New master password
+     * @returns Success when password changed, Failure if locked or current password incorrect
+     * @public
+     */
+    changePassword(currentPassword: string, newPassword: string): Promise<Result<KeyStore_2>>;
+    /** {@inheritDoc IEncryptionProvider.encryptByName} */
+    encryptByName<TMetadata = JsonValue>(secretName: string, content: JsonValue, metadata?: TMetadata): Promise<Result<IEncryptedFile<TMetadata>>>;
+    /**
+     * Creates a SecretProvider function for use with IEncryptionConfig.
+     * The returned function looks up secrets from this key store.
+     * @returns Success with SecretProvider, Failure if locked
+     * @public
+     */
+    getSecretProvider(): Result<SecretProvider>;
+    /**
+     * Creates a partial IEncryptionConfig using this key store as the secret source.
+     * @returns Partial config that can be spread into a full IEncryptionConfig
+     * @public
+     */
+    getEncryptionConfig(): Result<Pick<IEncryptionConfig, 'secretProvider' | 'cryptoProvider'>>;
 }
 
 /**
- * A helper function to create a `Converter` which converts `unknown` to {@link Experimental.ExtendedArray | ExtendedArray<T>}.
- * @remarks
- * 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
- * @beta
+ * Current format version constant.
+ * @public
  */
-declare function extendedArrayOf<T, TC = undefined>(label: string, converter: Converter<T, TC>, onError?: Conversion.OnError): Converter<ExtendedArray<T>, TC>;
+declare const KEYSTORE_FORMAT: KeyStoreFormat;
 
 /**
- * Formats a list of items using the supplied template and formatter, one result
- * per output line.
- * @param format - A mustache template used to format each item.
- * @param items - The items to be formatted.
- * @param itemFormatter - The {@link Experimental.Formatter | Formatter<T>} used to format each item.
- * @returns The resulting string.
- * @beta
+ * Converter for {@link CryptoUtils.KeyStore.IKeyStoreFile | encrypted key store file}.
+ * @public
  */
-declare function formatList<T>(format: string, items: T[], itemFormatter: Formatter<T>): Result<string>;
+declare const keystoreFile: Converter<IKeyStoreFile>;
 
 /**
- * Interface for an object that can be formatted.
- * @beta
+ * Format version for key store files.
+ * @public
  */
-declare interface Formattable {
-    /**
-     * Formats an object using the supplied mustache template.
-     * @param format - A mustache template used to format the object.
-     * @returns `Success<string>` with the resulting string, or `Failure<string>`
-     * with an error message if an error occurs.
-     */
-    format(format: string): Result<string>;
-}
+declare type KeyStoreFormat = 'keystore-v1';
 
 /**
- * Base class which adds common formatting.
- * @beta
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreFormat | key store format} version.
+ * @public
  */
-declare class FormattableBase {
-    /**
-     * Helper enables derived classes to add named details to a formatted presentation.
-     * @param details - An array of detail description strings.
-     * @param label - Label to use for the new detail.
-     * @param value - Value to use for the new detail.
-     * @internal
-     */
-    protected static _tryAddDetail(details: string[], label: string, value: string | undefined): void;
-    /**
-     * {@inheritdoc Experimental.Formattable.format}
-     */
-    format(template: string): Result<string>;
+declare const keystoreFormat: Converter<KeyStoreFormat>;
+
+/**
+ * Key store lock state.
+ * @public
+ */
+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'`.
+ * @public
+ */
+declare const keystoreSecretEntryJson: Converter<IKeyStoreSecretEntryJson>;
+
+/**
+ * Discriminator for 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';
+
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreSecretType | key store secret type} discriminator.
+ * @public
+ */
+declare const keystoreSecretType: Converter<KeyStoreSecretType>;
+
+/**
+ * Converter for {@link CryptoUtils.KeyStore.IKeyStoreVaultContents | key store vault contents} (decrypted state).
+ * @public
+ */
+declare const keystoreVaultContents: Converter<IKeyStoreVaultContents>;
+
+/**
+ * A hashing normalizer which computes object
+ * hash using the MD5 algorithm.
+ * @public
+ */
+declare class Md5Normalizer extends Hash_2.HashingNormalizer {
+    constructor();
+    static md5Hash(parts: string[]): string;
 }
 
 /**
- * Destination format for some formatted string.
- * @beta
+ * Minimum salt length for key derivation.
+ * @public
  */
-declare type FormatTargets = 'text' | 'markdown' | 'embed';
+declare const MIN_SALT_LENGTH: number;
 
 /**
- * Type definition for a formatting function, which takes a `string` and an
- * item and returns `Result<string>`.
- * @beta
+ * Default context key used as fallback when resolving a {@link ModelSpec}.
+ * @public
  */
-declare type Formatter<T> = (format: string, item: T) => Result<string>;
+declare const MODEL_SPEC_BASE_KEY: ModelSpecKey;
 
 /**
- * A collection of {@link Experimental.Formatter | formatters} indexed by target name, to enable
- * different format methods per output target.
- * @beta
+ * @public
  */
-declare type FormattersByExtendedTarget<TFT extends FormatTargets, T> = Record<TFT, Formatter<T>>;
+declare type ModelSpec = string | IModelSpecMap;
 
 /**
- * A collection of {@link Experimental.Formatter | formatters} indexed by the
- * {@link Experimental.FormatTargets | default supported target formats}.
- * @beta
+ * Recursive converter for {@link ModelSpec}.
+ * Accepts a string or an object whose values are themselves ModelSpec values,
+ * with keys constrained to known {@link ModelSpecKey} values.
+ * Uses the `self` parameter from `Converters.generic` for recursion.
+ * @public
  */
-declare type FormattersByTarget<T> = FormattersByExtendedTarget<FormatTargets, T>;
+declare const modelSpec: Converter<ModelSpec>;
 
-declare namespace Hash {
+/**
+ * Known context keys for model specification maps.
+ * @public
+ */
+declare type ModelSpecKey = 'base' | 'tools' | 'image';
+
+/**
+ * Converter for {@link ModelSpecKey}.
+ * @public
+ */
+declare const modelSpecKey: Converter<ModelSpecKey>;
+
+declare namespace Mustache {
     export {
-        Md5Normalizer
+        IContextValidationResult,
+        IMissingVariableDetail,
+        IMustacheTemplateOptions,
+        IVariableRef,
+        MustacheTokenType,
+        MustacheTemplate
     }
 }
-export { Hash }
+export { Mustache }
 
 /**
- * A `Converter` which converts an iso formatted string, a number or a `Date` object to
- * a `Date` object.
+ * A helper class for working with Mustache templates that provides
+ * validation, variable extraction, and context validation utilities.
  * @public
  */
-declare const isoDate: Converter<Date, unknown>;
+declare class MustacheTemplate {
+    /**
+     * The original template string
+     */
+    readonly template: string;
+    /**
+     * The options used for parsing this template
+     */
+    readonly options: Readonly<IRequiredMustacheTemplateOptions>;
+    private readonly _tokens;
+    private _variables?;
+    private constructor();
+    /**
+     * Creates a new MustacheTemplate instance.
+     * @param template - The Mustache template string to parse
+     * @param options - Optional parsing options
+     * @returns Success with the template instance, or Failure if parsing fails
+     */
+    static create(template: string, options?: IMustacheTemplateOptions): Result<MustacheTemplate>;
+    /**
+     * Validates that a template string has valid Mustache syntax.
+     * @param template - The template string to validate
+     * @param options - Optional parsing options
+     * @returns Success with true if valid, or Failure with a descriptive error message
+     */
+    static validate(template: string, options?: IMustacheTemplateOptions): Result<true>;
+    /**
+     * Checks if this template instance has valid syntax.
+     * Always returns Success(true) since parsing succeeded in create().
+     * @returns Success with true
+     */
+    validate(): Result<true>;
+    /**
+     * Extracts all variable references from the template.
+     * @returns An array of variable references found in the template
+     */
+    extractVariables(): readonly IVariableRef[];
+    /**
+     * Extracts unique variable names from the template.
+     * @returns An array of unique variable name strings (e.g., ['user.name', 'items'])
+     */
+    extractVariableNames(): readonly string[];
+    /**
+     * Validates that a context object has all required variables.
+     * @param context - The context object to validate
+     * @returns Success with validation result containing details about present/missing variables
+     */
+    validateContext(context: unknown): Result<IContextValidationResult>;
+    /**
+     * Renders the template with the given context.
+     * Use this for pre-validated contexts where you've already checked
+     * that all required variables are present.
+     * @param context - The context object for template rendering
+     * @returns Success with the rendered string, or Failure if rendering fails
+     */
+    render(context: unknown): Result<string>;
+    /**
+     * Validates the context and renders the template if validation passes.
+     * @param context - The context object to validate and render with
+     * @returns Success with the rendered string, or Failure with validation or render errors
+     */
+    validateAndRender(context: unknown): Result<string>;
+    private static _resolveOptions;
+    private static _parseTokens;
+    private _extractVariablesFromTokens;
+    private _parsePath;
+    private _lookupPath;
+}
 
 /**
+ * Type of a Mustache token as returned by Mustache.parse()
  * @public
  */
-declare type JarFieldPicker<T extends JarRecord = JarRecord> = (record: T) => (keyof T)[];
+declare type MustacheTokenType = 'text' | 'name' | '&' | '#' | '^' | '!' | '>' | '=';
 
 /**
- * Represents a single record in a JAR file
+ * Converter for {@link CryptoUtils.INamedSecret | named secret} from JSON representation.
+ * Expects key as base64 string in JSON, converts to Uint8Array.
  * @public
  */
-declare type JarRecord = Record<string, string | string[]>;
+declare const namedSecret: Converter<INamedSecret>;
 
 /**
- * Options for a JAR record parser.
+ * Node.js implementation of {@link CryptoUtils.ICryptoProvider} using the built-in crypto module.
+ * Uses AES-256-GCM for authenticated encryption.
  * @public
  */
-declare interface JarRecordParserOptions {
-    readonly arrayFields?: string[] | JarFieldPicker;
-    readonly fixedContinuationSize?: number;
+declare class NodeCryptoProvider implements ICryptoProvider {
+    /**
+     * Encrypts plaintext using AES-256-GCM.
+     * @param plaintext - UTF-8 string to encrypt
+     * @param key - 32-byte encryption key
+     * @returns `Success` with encryption result, or `Failure` with an error.
+     */
+    encrypt(plaintext: string, key: Uint8Array): Promise<Result<IEncryptionResult>>;
+    /**
+     * Decrypts ciphertext using AES-256-GCM.
+     * @param encryptedData - Encrypted bytes
+     * @param key - 32-byte decryption key
+     * @param iv - Initialization vector (12 bytes)
+     * @param authTag - GCM authentication tag (16 bytes)
+     * @returns `Success` with decrypted UTF-8 string, or `Failure` with an error.
+     */
+    decrypt(encryptedData: Uint8Array, key: Uint8Array, iv: Uint8Array, authTag: Uint8Array): Promise<Result<string>>;
+    /**
+     * Generates a random 32-byte key suitable for AES-256.
+     * @returns `Success` with generated key, or `Failure` with an error.
+     */
+    generateKey(): Promise<Result<Uint8Array>>;
+    /**
+     * Derives a key from a password using PBKDF2.
+     * @param password - Password string
+     * @param salt - Salt bytes (should be at least 16 bytes)
+     * @param iterations - Number of iterations (recommend 100000+)
+     * @returns `Success` with derived 32-byte key, or `Failure` with an error.
+     */
+    deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<Result<Uint8Array>>;
+    /**
+     * Generates cryptographically secure random bytes.
+     * @param length - Number of bytes to generate
+     * @returns Success with random bytes, or Failure with error
+     */
+    generateRandomBytes(length: number): Result<Uint8Array>;
+    /**
+     * Encodes binary data to base64 string.
+     * @param data - Binary data to encode
+     * @returns Base64-encoded string
+     */
+    toBase64(data: Uint8Array): string;
+    /**
+     * Decodes base64 string to binary data.
+     * @param base64 - Base64-encoded string
+     * @returns Success with decoded bytes, or Failure if invalid base64
+     */
+    fromBase64(base64: string): Result<Uint8Array>;
 }
 
 /**
- * A hashing normalizer which computes object
- * hash using the MD5 algorithm.
+ * Singleton instance of {@link CryptoUtils.NodeCryptoProvider}.
  * @public
  */
-declare class Md5Normalizer extends Hash_2.HashingNormalizer {
-    constructor();
-    static md5Hash(parts: string[]): string;
-}
+declare const nodeCryptoProvider: NodeCryptoProvider;
 
 /**
  * Parses CSV data from a string.
@@ -446,6 +2202,45 @@ declare namespace RecordJar {
 }
 export { RecordJar }
 
+/**
+ * Resolves the effective tools for a completion call.
+ *
+ * - If per-call tools are provided, they override settings-level tools entirely.
+ * - Otherwise, settings-level enabled tools are used.
+ * - Only tools supported by the provider are included.
+ * - Returns an empty array if no tools are enabled (= no tools sent).
+ *
+ * @param descriptor - The provider descriptor (used to filter by supported tools)
+ * @param settingsTools - Tool enablement from provider settings (optional)
+ * @param perCallTools - Per-call tool override (optional)
+ * @returns The resolved list of tool configs to include in the request
+ * @public
+ */
+declare function resolveEffectiveTools(descriptor: IAiProviderDescriptor, settingsTools?: ReadonlyArray<IAiToolEnablement>, perCallTools?: ReadonlyArray<AiServerToolConfig>): ReadonlyArray<AiServerToolConfig>;
+
+/**
+ * Resolves a {@link ModelSpec} to a concrete model string given an optional context key.
+ *
+ * @remarks
+ * Resolution rules:
+ * 1. If the spec is a string, return it directly (context is irrelevant).
+ * 2. If the spec is an object and the context key exists, recurse into that branch.
+ * 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'`)
+ * @returns The resolved model string
+ * @public
+ */
+declare function resolveModel(spec: ModelSpec, context?: string): string;
+
+/**
+ * Function type for dynamic secret retrieval.
+ * @public
+ */
+declare type SecretProvider = (secretName: string) => Promise<Result<Uint8Array>>;
+
 /**
  * Helper function to create a `StringConverter` which converts
  * `unknown` to `string`, applying template conversions supplied at construction time or at
@@ -458,6 +2253,55 @@ export { RecordJar }
  */
 declare function templateString(defaultContext?: unknown): Conversion.StringConverter<string, unknown>;
 
+/**
+ * Encodes a `Uint8Array` to a base64 string.
+ * @param bytes - Bytes to encode
+ * @returns Base64 string
+ * @public
+ */
+declare function toBase64(bytes: Uint8Array): string;
+
+/**
+ * Attempts to parse and decrypt a JSON object as an {@link CryptoUtils.IEncryptedFile | encrypted file}.
+ * @typeParam TPayload - Expected type of decrypted content
+ * @typeParam TMetadata - Type of optional unencrypted metadata
+ * @param json - JSON object that may be an encrypted file
+ * @param key - The decryption key (32 bytes for AES-256)
+ * @param cryptoProvider - {@link CryptoUtils.ICryptoProvider | Crypto provider} to use for decryption
+ * @param payloadConverter - Optional converter to validate and convert decrypted content
+ * @param metadataConverter - Optional converter to validate metadata before decryption
+ * @returns `Success` with decrypted content, or `Failure` with an error (including if not encrypted)
+ * @public
+ */
+declare function tryDecryptFile<TPayload extends JsonValue = JsonValue, TMetadata = JsonValue>(json: JsonValue, key: Uint8Array, cryptoProvider: ICryptoProvider, payloadConverter?: Converter<TPayload>, metadataConverter?: Converter<TMetadata>): Promise<Result<TPayload>>;
+
+/**
+ * Converter which converts a base64 string to a Uint8Array.
+ * @public
+ */
+declare const uint8ArrayFromBase64: Converter<Uint8Array>;
+
+declare namespace Yaml {
+    export {
+        yamlConverter
+    }
+}
+export { Yaml }
+
+/**
+ * Creates a converter that parses YAML string content and then applies the supplied converter.
+ * @param converter - Converter to apply to the parsed YAML
+ * @returns Converter that parses YAML then validates
+ * @public
+ */
+declare function yamlConverter<T>(converter: Converter<T>): Converter<T>;
+
+/**
+ * Supported compression levels for zip files.
+ * @public
+ */
+declare type ZipCompressionLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+
 /**
  * Implementation of `IFileTreeDirectoryItem` for directories in a ZIP archive.
  * @public
@@ -493,6 +2337,8 @@ declare class ZipDirectoryItem<TCT extends string = string> implements FileTree.
 
 /**
  * Implementation of `FileTree.IFileTreeFileItem` for files in a ZIP archive.
+ * ZIP files are read-only, so this item does not support mutation.
+ * Use {@link FileTree.isMutableFileItem | isMutableFileItem} to check before attempting mutations.
  * @public
  */
 declare class ZipFileItem<TCT extends string = string> implements FileTree.IFileTreeFileItem<TCT> {
@@ -563,13 +2409,19 @@ declare namespace ZipFileTree {
     export {
         ZipFileTreeAccessors,
         ZipFileItem,
-        ZipDirectoryItem
+        ZipDirectoryItem,
+        createZipFromTextFiles,
+        IZipTextFile,
+        ZipCompressionLevel,
+        ICreateZipOptions
     }
 }
 export { ZipFileTree }
 
 /**
- * File tree accessors for ZIP archives.
+ * Read-only file tree accessors for ZIP archives.
+ * ZIP archives are read-only by design — use {@link FileTree.isMutableAccessors | isMutableAccessors}
+ * to check before attempting mutations.
  * @public
  */
 declare class ZipFileTreeAccessors<TCT extends string = string> implements FileTree.IFileTreeAccessors<TCT> {