@fgv/ts-extras 5.1.0-44 → 5.1.0-46

package/dist/ts-extras.d.ts

@@ -42,6 +42,7 @@ declare namespace AiAssist {
         IAiClientToolTurnResult,
         IAiToolEnablement,
         IAiCompletionResponse,
+        DEFAULT_ANTHROPIC_MAX_TOKENS,
         IChatMessage,
         IChatRequest,
         AiApiFormat,
@@ -58,6 +59,7 @@ declare namespace AiAssist {
         IAiAssistSettings,
         DEFAULT_AI_ASSIST,
         IAiAssistKeyStore,
+        providerApiKeySecretName,
         IAiImageAttachment,
         IAiImageData,
         AiImageSize,
@@ -101,6 +103,8 @@ declare namespace AiAssist {
         resolveModelAlias,
         resolveProviderModel,
         isResponsesOnlyModel,
+        isAdaptiveThinkingModel,
+        usesMaxCompletionTokensField,
         toDataUrl,
         AiThinkingMode,
         IThinkingConfig,
@@ -160,10 +164,12 @@ declare namespace AiAssist {
         modelSpecKey,
         modelSpec,
         resolveEffectiveTools,
+        classifyJsonParseFailure,
         extractJsonText,
         fencedStringifiedJson,
         IFencedStringifiedJsonExtractorOptions,
         IFencedStringifiedJsonOptions,
+        JsonParseFailureReason,
         JsonTextExtractor,
         generateJsonCompletion,
         SMART_JSON_PROMPT_HINT,
@@ -632,6 +638,53 @@ declare function callProxiedImageGeneration(proxyUrl: string, params: IProviderI
  */
 declare function callProxiedListModels(proxyUrl: string, params: IProviderListModelsParams): Promise<Result<ReadonlyArray<IAiModelInfo>>>;
 
+/**
+ * Classifies why a JSON-shaped LLM response would not parse, returning a
+ * {@link AiAssist.JsonParseFailureReason} a caller can branch on — repair the
+ * cheap cases, re-prompt the expensive ones, fail outright on the rest —
+ * instead of regex-matching an engine-specific `JSON.parse` message.
+ *
+ * Pass the same raw model text you handed
+ * {@link AiAssist.fencedStringifiedJson} or {@link AiAssist.extractJsonText};
+ * this applies the same BOM / whitespace / fence / preamble handling before
+ * scanning, and reports `offset` against that original text.
+ *
+ * Classification is **structural and deliberately conservative**. The scan
+ * walks the JSON grammar itself rather than reading the engine's error string,
+ * so its verdicts are stable across Node versions — and any fault it cannot
+ * name with confidence comes back as `'unknown'` rather than a guess. In
+ * particular an input that opened a structure and never closed it (the
+ * truncated-response shape {@link AiAssist.extractJsonText} already diagnoses)
+ * classifies as `'unknown'` here; the two diagnostics are complementary, not
+ * competing.
+ *
+ * This never fails and never repairs — it only names the fault. It is a
+ * diagnostic on the failure path, so calling it on text that parses fine is
+ * harmless but pointless: it returns `'unknown'`.
+ *
+ * @example
+ * ```ts
+ * const parsed = fencedStringifiedJson({ inner }).convert(raw);
+ * if (parsed.isFailure()) {
+ *   const reason = classifyJsonParseFailure(raw);
+ *   switch (reason.kind) {
+ *     case 'unquoted-property-name': // cheap to repair
+ *     case 'single-quoted-property-name':
+ *       break;
+ *     case 'elided-member':
+ *     case 'unterminated-property-name': // worth a re-prompt
+ *       break;
+ *     default: // 'unknown' — fail outright
+ *   }
+ * }
+ * ```
+ *
+ * @param text - Raw model output (the same string handed to the extractor).
+ * @returns A {@link AiAssist.JsonParseFailureReason}.
+ * @public
+ */
+declare function classifyJsonParseFailure(text: string): JsonParseFailureReason;
+
 declare namespace Constants {
     export {
         ENCRYPTED_FILE_FORMAT,
@@ -706,8 +759,22 @@ declare function createEncryptedFile<TMetadata = JsonValue>(params: ICreateEncry
  */
 declare function createEncryptedFileConverter<TMetadata = JsonValue>(metadataConverter?: Converter<TMetadata>): Converter<IEncryptedFile<TMetadata>>;
 
+/**
+ * Creates a zip file from an array of files whose contents are either text or raw bytes.
+ *
+ * @remarks
+ * String contents are encoded as UTF-8; `Uint8Array` contents are stored verbatim, so
+ * arbitrary binary payloads round-trip through the archive unchanged.
+ * @public
+ */
+declare function createZipFromFiles(files: ReadonlyArray<IZipFile>, options?: ICreateZipOptions): Result<Uint8Array>;
+
 /**
  * Creates a zip file from an array of text files.
+ *
+ * @remarks
+ * Contents are encoded as UTF-8. Use `createZipFromFiles` to write entries whose
+ * contents are raw bytes.
  * @public
  */
 declare function createZipFromTextFiles(files: ReadonlyArray<IZipTextFile>, options?: ICreateZipOptions): Result<Uint8Array>;
@@ -816,6 +883,28 @@ declare const DEFAULT_AI_ASSIST: IAiAssistSettings;
  */
 declare const DEFAULT_ALGORITHM: "AES-256-GCM";
 
+/**
+ * Default `max_tokens` sent to the Anthropic Messages API when the caller does
+ * not supply an explicit `maxTokens` override.
+ *
+ * @remarks
+ * Anthropic's Messages API requires `max_tokens` on every request — there is
+ * no provider-side default the way there is for OpenAI Chat/Responses,
+ * Gemini, or xAI, all of which accept a request with no cap and apply their
+ * own default. Anthropic is therefore the only provider that needs — or
+ * gets — a library-supplied fallback; every other provider omits the field
+ * entirely when the caller doesn't set `maxTokens` (see
+ * `IProviderCompletionParams.maxTokens`).
+ *
+ * Callers whose structured/JSON output scales with input size and hits this
+ * ceiling see a silent truncation that often surfaces downstream as a
+ * confusing `extractJsonText` parse failure rather than an obvious "too
+ * short" error — pass `maxTokens` explicitly to raise the cap for those
+ * requests.
+ * @public
+ */
+declare const DEFAULT_ANTHROPIC_MAX_TOKENS: number;
+
 /**
  * Default PBKDF2 iterations for key store encryption.
  * Higher than regular files since this protects the master key vault.
@@ -1221,6 +1310,13 @@ declare function extendedArrayOf<T, TC = undefined>(label: string, converter: Co
  *
  * Out of scope: repairing malformed JSON, handling smart quotes, etc.
  *
+ * When an object or array opens but never closes before the end of input —
+ * the shape a response truncated by a token cap leaves behind — the failure
+ * names that specifically (distinct from the generic "no JSON-shaped
+ * substring found" for input that never looked like JSON at all) and points
+ * at `IAiCompletionResponse.truncated` and the `maxTokens` request option as
+ * the likely cause and fix.
+ *
  * @param text - Raw model output.
  * @returns A `Result<string>` containing the JSON-shaped substring, or a
  * `Failure` if no JSON-shaped substring was found.
@@ -2355,6 +2451,27 @@ declare interface IAiProviderDescriptor {
      * Responses-only.
      */
     readonly responsesOnlyModelPrefixes?: ReadonlyArray<string>;
+    /**
+     * Concrete Anthropic model ids (exact-or-dash-bounded-prefix-matched) that require the
+     * adaptive thinking wire shape (`thinking: { type: 'adaptive' }` + top-level
+     * `output_config: { effort }`) rather than the legacy manual-budget shape
+     * (`thinking: { type: 'enabled', budget_tokens }`). Non-Anthropic `apiFormat`s ignore this.
+     *
+     * @remarks
+     * The Claude 5 family (`claude-sonnet-5`, `claude-opus-5`, `claude-fable-5`, including their
+     * dated snapshots) rejects `thinking.type: 'enabled'` with an HTTP 400 and requires the
+     * adaptive shape; older models (`claude-sonnet-4-6`, `claude-opus-4-8`, `claude-haiku-4-5`,
+     * etc.) keep the legacy shape. The completion (`callProviderCompletion`), streaming
+     * (`callProviderCompletionStream`), and client-tool (`executeClientToolTurn`) Anthropic
+     * dispatch sites consult this list (via the sibling predicate
+     * `isAdaptiveThinkingModel`) to pick the correct wire shape for the resolved
+     * model. Mirrors the prefix-matching shape of `responsesOnlyModelPrefixes`, but with
+     * exact-or-dash-bounded matching (an entry matches a resolved model that equals it or starts
+     * with it followed by `-`) rather than a plain prefix, since Anthropic model families share
+     * numeric leading characters (`claude-sonnet-5` vs. a hypothetical `claude-sonnet-50`).
+     * Empty or undefined means no model uses the adaptive shape.
+     */
+    readonly adaptiveThinkingModelPrefixes?: ReadonlyArray<string>;
 }
 
 /**
@@ -3404,6 +3521,15 @@ declare interface IExecuteClientToolTurnParams extends IChatRequest {
      * turn with an `isError` result. A deny must therefore be explicit.
      */
     readonly onBeforeToolExecute?: (tool: IAiClientTool, args: unknown) => Promise<Result<IToolExecutionDecision>>;
+    /**
+     * Optional cap on generated output tokens, mapped to each provider's native field:
+     * Anthropic `max_tokens`, OpenAI/xAI Responses `max_output_tokens` (client-tool turns always
+     * route OpenAI through the Responses API), Gemini `generationConfig.maxOutputTokens`. When
+     * unset, every provider except Anthropic omits the field and applies its own default;
+     * Anthropic's Messages API requires the field, so it falls back to
+     * `DEFAULT_ANTHROPIC_MAX_TOKENS`.
+     */
+    readonly maxTokens?: number;
 }
 
 /**
@@ -4357,6 +4483,15 @@ declare interface IProviderCompletionParams extends IChatRequest {
      * the effective merged effort is non-`'none'`; Gemini always accepts both.
      */
     readonly thinking?: IThinkingConfig;
+    /**
+     * Optional cap on generated output tokens, mapped to each provider's native field:
+     * Anthropic `max_tokens`, OpenAI Chat Completions `max_completion_tokens`, OpenAI/xAI
+     * Responses `max_output_tokens`, Gemini `generationConfig.maxOutputTokens`, and the
+     * xAI/Groq/Mistral/Ollama/`openai-compat` chat-completions path `max_tokens`. When unset,
+     * every provider except Anthropic omits the field and applies its own default; Anthropic's
+     * Messages API requires the field, so it falls back to `DEFAULT_ANTHROPIC_MAX_TOKENS`.
+     */
+    readonly maxTokens?: number;
 }
 
 /**
@@ -4409,6 +4544,15 @@ declare interface IProviderCompletionStreamParams extends IChatRequest {
      * Optional thinking/reasoning mode configuration.
      */
     readonly thinking?: IThinkingConfig;
+    /**
+     * Optional cap on generated output tokens, mapped to each provider's native field:
+     * Anthropic `max_tokens`, OpenAI Chat Completions `max_completion_tokens`, OpenAI/xAI
+     * Responses `max_output_tokens`, Gemini `generationConfig.maxOutputTokens`, and the
+     * xAI/Groq/Mistral/Ollama/`openai-compat` chat-completions path `max_tokens`. When unset,
+     * every provider except Anthropic omits the field and applies its own default; Anthropic's
+     * Messages API requires the field, so it falls back to `DEFAULT_ANTHROPIC_MAX_TOKENS`.
+     */
+    readonly maxTokens?: number;
 }
 
 /**
@@ -4554,6 +4698,32 @@ declare interface IResolvedThinkingConfig {
     readonly otherParams?: JsonObject;
 }
 
+/**
+ * Determines whether a concrete (already-resolved) Anthropic model id uses the adaptive
+ * thinking wire shape (`thinking: { type: 'adaptive' }` + top-level `output_config.effort`)
+ * rather than the legacy manual-budget shape (`thinking: { type: 'enabled', budget_tokens }`).
+ *
+ * @remarks
+ * Matches `modelId` against the descriptor's
+ * {@link IAiProviderDescriptor.adaptiveThinkingModelPrefixes} using the same
+ * exact-or-dash-bounded matcher semantics as the model-specific blocks in
+ * `mergeThinkingConfig` (an entry matches when it equals the resolved model or when the
+ * resolved model starts with the entry followed by a `-`) — a plain prefix match would risk a
+ * false positive against an unrelated model sharing the same leading characters. A provider
+ * that declares no list (the common case — this is Anthropic-specific) always returns `false`.
+ * Consulted by the completion (`callProviderCompletion`), streaming
+ * (`callProviderCompletionStream`), and client-tool (`executeClientToolTurn`) Anthropic
+ * dispatch sites so every Anthropic wire-request path picks the correct thinking shape for the
+ * resolved model.
+ *
+ * @param descriptor - The provider descriptor supplying the prefix list.
+ * @param modelId - The resolved concrete model id to test.
+ * @returns `true` when `modelId` exactly matches or is dash-bounded-prefixed by any declared
+ * adaptive-thinking prefix.
+ * @public
+ */
+declare function isAdaptiveThinkingModel(descriptor: IAiProviderDescriptor, modelId: string): boolean;
+
 /**
  * Checks if a JSON object appears to be an encrypted file.
  * Uses the format field as a discriminator.
@@ -4816,7 +4986,20 @@ declare interface IYamlSerializeOptions {
 }
 
 /**
- * Simple interface for a file to be added to a zip file.
+ * Interface for a file to be added to a zip file, whose contents are either text or
+ * raw bytes.
+ *
+ * @remarks
+ * String contents are encoded as UTF-8; `Uint8Array` contents are stored verbatim.
+ * @public
+ */
+declare interface IZipFile {
+    readonly path: string;
+    readonly contents: string | Uint8Array;
+}
+
+/**
+ * Simple interface for a text file to be added to a zip file.
  * @public
  */
 declare interface IZipTextFile {
@@ -4844,6 +5027,57 @@ declare interface JarRecordParserOptions {
     readonly fixedContinuationSize?: number;
 }
 
+/**
+ * Typed reason a JSON-shaped LLM response failed to parse, so a caller can
+ * branch on the failure class instead of regex-matching the engine's
+ * `JSON.parse` message (whose wording varies across V8 / Node versions).
+ *
+ * Every classified arm describes a fault at an **object property-name
+ * position** — the position an LLM most often gets wrong, and the one whose
+ * repair strategy differs most by case:
+ *
+ * - `'unquoted-property-name'`: a bare identifier where a quoted name belongs
+ *   (`{ key: 1 }`). `token` is the identifier run, `offset` its first
+ *   character. Identifier recognition is ASCII-only, so a non-ASCII bare name
+ *   (`{ ключ: 1 }`) reports `'unknown'` rather than being named.
+ * - `'single-quoted-property-name'`: a single-quoted name (`{ 'key': 1 }`).
+ *   `token` is the quoted literal (or just `'` if it never closes), `offset`
+ *   the opening quote.
+ * - `'unterminated-property-name'`: a name whose closing `"` is missing, and
+ *   whose body swallowed structural text (`{ "key: 1 }`). `token` is the
+ *   unterminated fragment, `offset` the opening quote.
+ * - `'elided-member'`: a `,` where a member is expected — a leading or doubled
+ *   comma in an object (`{ , "a": 1 }`, `{ "a":1, , "b":2 }`) or an array
+ *   (`[1, , 2]`). `token` is `','`, `offset` its position.
+ * - `'unknown'`: the catch-all. The scan reached the end of the text, or hit a
+ *   fault it cannot name with confidence, and reports nothing rather than
+ *   guessing. Truncated responses, missing colons, trailing commas, bad number
+ *   literals, and anything else not listed above land here.
+ *
+ * `offset` is a 0-based index into the `text` passed to
+ * {@link AiAssist.classifyJsonParseFailure}, not into the extracted substring.
+ * @public
+ */
+declare type JsonParseFailureReason = {
+    readonly kind: 'unquoted-property-name';
+    readonly token: string;
+    readonly offset: number;
+} | {
+    readonly kind: 'single-quoted-property-name';
+    readonly token: string;
+    readonly offset: number;
+} | {
+    readonly kind: 'unterminated-property-name';
+    readonly token: string;
+    readonly offset: number;
+} | {
+    readonly kind: 'elided-member';
+    readonly token: string;
+    readonly offset: number;
+} | {
+    readonly kind: 'unknown';
+};
+
 /**
  * Controls the optional system-prompt augmentation applied by
  * {@link AiAssist.generateJsonCompletion}.
@@ -5710,6 +5944,35 @@ declare const modelSpec: Converter<ModelSpec>;
 
 /**
  * Known context keys for model specification maps.
+ *
+ * @remarks
+ * Two axes live here and nothing else: the **quality tier** (`base` / `advanced`
+ * / `frontier`) selects the *completion* model, and `image` / `embedding` select
+ * the non-completion modalities.
+ *
+ * There is deliberately **no `tools` or `thinking` key**. Both existed before the
+ * quality-tier axis landed and were removed with it: server-side tools and
+ * reasoning effort are orthogonal *request* params that ride on top of whatever
+ * model the tier already selected — they never select a model. A tool-using or
+ * thinking-enabled call passes a tier like any other call (omit → `base`, or
+ * `'advanced'` / `'frontier'`) and sets the tools / thinking request params
+ * independently. Thinking composes with any tier without a tier-level capability
+ * check — but that is a statement about the tier axis, not a claim that every
+ * provider supports thinking: several descriptors declare
+ * `thinkingMode: 'unsupported'` (e.g. `copy-paste`, `groq`, `mistral`, `ollama`,
+ * `openai-compat`).
+ *
+ * Thinking availability is declared **per provider**, on the descriptor's
+ * `thinkingMode`; the descriptor does not encode per-model thinking availability at
+ * all, so a provider that declares support may still have individual models its own
+ * API rejects thinking on. (`adaptiveThinkingModelPrefixes` is per-model but selects
+ * a wire *shape*, not availability.) What the tier axis guarantees is therefore
+ * narrow and exact: a tier selects a model within one provider and never changes the
+ * provider, so it never changes `thinkingMode`.
+ *
+ * Do not add a `'tools'` or `'thinking'` key here, and do not hand-roll a
+ * `resolveModel` + `resolveModelAlias` walk to emulate one — call
+ * `resolveProviderModel` with the tier you want.
  * @public
  */
 declare type ModelSpecKey = 'base' | 'advanced' | 'frontier' | 'image' | 'embedding';
@@ -6133,6 +6396,18 @@ declare function parseRecordJarLines(lines: string[], options?: JarRecordParserO
  */
 declare const pbkdf2KeyDerivationParams: Converter<IPbkdf2KeyDerivationParams>;
 
+/**
+ * Returns the canonical `CryptoUtils.KeyStore.KeyStore` secret name for a provider's API key,
+ * of the form `provider:<providerId>`. Apps that store provider API keys in a `KeyStore`
+ * should use this name (rather than inventing their own) so that a single keystore vault
+ * works consistently across every fgv app.
+ *
+ * @param providerId - The provider whose API key secret name is requested.
+ * @returns The canonical keystore secret name, e.g. `'provider:openai'`.
+ * @public
+ */
+declare function providerApiKeySecretName(providerId: AiProviderId): string;
+
 /**
  * Simple implementation of a possibly open-ended range of some comparable
  * type `<T>` with test and formatting.
@@ -6341,10 +6616,20 @@ declare function resolveEffectiveTools(descriptor: IAiProviderDescriptor, settin
  * `modelPrefix` is the longest prefix of `modelId`. Ties are broken by
  * first-encountered.
  *
+ * @remarks
+ * `modelId` may be either a concrete provider model id or an fgv model alias
+ * (`@<provider>:<role>`, see `MODEL_ALIAS_SIGIL`) — it is resolved via
+ * `resolveModelAlias` against `descriptor.aliases` before prefix matching,
+ * so both forms select the same capability. A raw provider id passes through
+ * unchanged. An alias that is not registered on `descriptor` (or is cyclic)
+ * names no model and yields `undefined` rather than falling through to the
+ * `modelPrefix: ''` catch-all.
+ *
  * @param descriptor - The provider descriptor
- * @param modelId - The resolved embedding model id
- * @returns The matching capability, or `undefined` when no rule matches or the
- *   provider declares no embedding capabilities.
+ * @param modelId - The embedding model id — concrete or an fgv alias
+ * @returns The matching capability, or `undefined` when no rule matches, the
+ *   provider declares no embedding capabilities, or `modelId` is an
+ *   unresolvable alias.
  * @public
  */
 declare function resolveEmbeddingCapability(descriptor: IAiProviderDescriptor, modelId: string): IAiEmbeddingModelCapability | undefined;
@@ -6357,10 +6642,20 @@ declare function resolveEmbeddingCapability(descriptor: IAiProviderDescriptor, m
  * order does not matter for correctness — only for tie-breaking among rules
  * with identical-length prefixes (an unusual case).
  *
+ * @remarks
+ * `modelId` may be either a concrete provider model id or an fgv model alias
+ * (`@<provider>:<role>`, see `MODEL_ALIAS_SIGIL`) — it is resolved via
+ * `resolveModelAlias` against `descriptor.aliases` before prefix matching,
+ * so both forms select the same capability. A raw provider id passes through
+ * unchanged. An alias that is not registered on `descriptor` (or is cyclic)
+ * names no model and yields `undefined` rather than falling through to the
+ * `modelPrefix: ''` catch-all.
+ *
  * @param descriptor - The provider descriptor
- * @param modelId - The resolved image model id
- * @returns The matching capability, or `undefined` when no rule matches or
- *   the provider declares no image-generation capabilities.
+ * @param modelId - The image model id — concrete or an fgv alias
+ * @returns The matching capability, or `undefined` when no rule matches, the
+ *   provider declares no image-generation capabilities, or `modelId` is an
+ *   unresolvable alias.
  * @public
  */
 declare function resolveImageCapability(descriptor: IAiProviderDescriptor, modelId: string): IAiImageModelCapability | undefined;
@@ -6441,6 +6736,20 @@ declare function resolveModelAlias(descriptor: IAiProviderDescriptor, model: str
  * `ModelSpec` branch is selected first; the resulting string — which may itself
  * be an fgv alias — is then resolved to a concrete id.
  *
+ * **This is the whole model-selection surface — do not hand-roll the walk.**
+ * Callers should pass the `ModelSpecKey` they want and use the concrete id
+ * this returns; a manual `resolveModel` + `resolveModelAlias` sequence is
+ * both redundant and easy to get wrong (it is how alias-form ids leak into
+ * capability lookups such as `resolveImageCapability`).
+ *
+ * **`context` carries the quality tier and the modality — never tools or
+ * thinking.** `ModelSpecKey` has no `tools` / `thinking` key: server-side
+ * tools and reasoning effort are orthogonal request params that ride on top of
+ * whatever model the tier selected, and never select a model. A tool-path caller
+ * passes a tier like any other caller — omit `context` for `base`, or pass
+ * `'advanced'` / `'frontier'` — and sets the tools / thinking request params
+ * separately.
+ *
  * @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.
@@ -6570,6 +6879,29 @@ declare function tryDecryptFile<TPayload extends JsonValue = JsonValue, TMetadat
  */
 declare const uint8ArrayFromBase64: Converter<Uint8Array>;
 
+/**
+ * Determines whether a provider's OpenAI-compatible Chat Completions request
+ * should use the modern `max_completion_tokens` field instead of the legacy
+ * `max_tokens` field for capping output length.
+ *
+ * @remarks
+ * OpenAI's Chat Completions API deprecated `max_tokens` in favor of
+ * `max_completion_tokens`. Every other provider routed through the shared
+ * OpenAI-compatible chat-completions adapter (xAI Grok, Groq, Mistral, Ollama,
+ * self-hosted `openai-compat` servers) still expects the legacy `max_tokens`
+ * field, so this returns `true` only for the `'openai'` provider id. Consulted
+ * by both the completion (`callProviderCompletion`) and streaming
+ * (`callProviderCompletionStream`) chat-completions dispatch branches. Not
+ * consulted on the Responses API path — `max_output_tokens` applies uniformly
+ * there for both OpenAI and xAI (see `isResponsesOnlyModel`) —
+ * nor by any non-`'openai'`-format provider (Anthropic, Gemini).
+ *
+ * @param descriptor - The provider descriptor.
+ * @returns `true` only for the `'openai'` provider id.
+ * @public
+ */
+declare function usesMaxCompletionTokensField(descriptor: IAiProviderDescriptor): boolean;
+
 /**
  * Validates the resolved options against per-model registry constraints.
  *
@@ -6589,7 +6921,7 @@ declare function validateResolvedOptions(modelId: string, capability: IAiImageMo
  * Model IDs for xAI thinking-capable models.
  * @public
  */
-declare type XAiThinkingModelNames = 'grok-3-mini' | 'grok-4.3' | 'grok-4';
+declare type XAiThinkingModelNames = 'grok-3-mini' | 'grok-4.3' | 'grok-4' | 'grok-4.5';
 
 declare namespace Yaml {
     export {
@@ -6660,9 +6992,15 @@ 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.
+ *
+ * @remarks
+ * ZIP entries are byte-native, so this item also implements the read half of the
+ * optional binary capability (`FileTree.IBinaryFileTreeFileItem`) — use
+ * `FileTree.isBinaryFileItem` to narrow and `getRawBytes()` to read the entry's
+ * undecoded bytes.
  * @public
  */
-declare class ZipFileItem<TCT extends string = string> implements FileTree.IFileTreeFileItem<TCT> {
+declare class ZipFileItem<TCT extends string = string> implements FileTree.IBinaryFileTreeFileItem<TCT> {
     /**
      * Indicates that this `FileTree.FileTreeItem` is a file.
      */
@@ -6688,9 +7026,13 @@ declare class ZipFileItem<TCT extends string = string> implements FileTree.IFile
      */
     get contentType(): TCT | undefined;
     /**
-     * The pre-loaded contents of the file.
+     * The pre-loaded raw bytes of the ZIP entry.
      */
-    private readonly _contents;
+    private readonly _bytes;
+    /**
+     * Text form of the entry, decoded lazily from the raw bytes on first text read.
+     */
+    private _contents;
     /**
      * The ZIP file tree accessors that created this item.
      */
@@ -6706,10 +7048,12 @@ declare class ZipFileItem<TCT extends string = string> implements FileTree.IFile
     /**
      * Constructor for ZipFileItem.
      * @param zipFilePath - The path of the file within the ZIP.
-     * @param contents - The pre-loaded contents of the file.
+     * @param contents - The pre-loaded contents of the entry, either as raw bytes or as
+     * already-decoded text. Text is encoded as UTF-8 for the byte accessor and is also
+     * retained verbatim, so supplying text never round-trips through a decode.
      * @param accessors - The ZIP file tree accessors.
      */
-    constructor(zipFilePath: string, contents: string, accessors: ZipFileTreeAccessors<TCT>);
+    constructor(zipFilePath: string, contents: string | Uint8Array, accessors: ZipFileTreeAccessors<TCT>);
     /**
      * Sets the content type of the file.
      * @param contentType - The content type of the file.
@@ -6722,8 +7066,21 @@ declare class ZipFileItem<TCT extends string = string> implements FileTree.IFile
     getContents<T>(converter: Validator<T> | Converter<T>): Result<T>;
     /**
      * Gets the raw contents of the file as a string.
+     *
+     * @remarks
+     * The entry's bytes are decoded as UTF-8 with the lenient WHATWG default, so
+     * malformed input is silently replaced with U+FFFD. Use `getRawBytes()` for the
+     * undecoded bytes — and `new TextDecoder('utf-8', { fatal: true }).decode(bytes)`
+     * for a decode that fails loudly instead.
      */
     getRawContents(): Result<string>;
+    /**
+     * Gets the raw bytes of the ZIP entry, with no text decoding applied.
+     *
+     * @remarks
+     * The returned array is the item's internal buffer and must not be modified.
+     */
+    getRawBytes(): Result<Uint8Array>;
 }
 
 declare namespace ZipFileTree {
@@ -6732,7 +7089,9 @@ declare namespace ZipFileTree {
         ZipFileItem,
         ZipDirectoryItem,
         createZipFromTextFiles,
+        createZipFromFiles,
         IZipTextFile,
+        IZipFile,
         ZipCompressionLevel,
         ICreateZipOptions
     }
@@ -6743,9 +7102,15 @@ export { ZipFileTree }
  * 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.
+ *
+ * @remarks
+ * ZIP entries are byte-native, so these accessors also implement the read half of the
+ * optional binary capability (`FileTree.IBinaryFileTreeAccessors`) — use
+ * `FileTree.isBinaryAccessors` to narrow and `getFileBytes()` to read an entry's
+ * undecoded bytes.
  * @public
  */
-declare class ZipFileTreeAccessors<TCT extends string = string> implements FileTree.IFileTreeAccessors<TCT> {
+declare class ZipFileTreeAccessors<TCT extends string = string> implements FileTree.IBinaryFileTreeAccessors<TCT> {
     /**
      * The unzipped file data.
      */
@@ -6839,8 +7204,25 @@ declare class ZipFileTreeAccessors<TCT extends string = string> implements FileT
     getItem(path: string): Result<FileTree.FileTreeItem<TCT>>;
     /**
      * Gets the contents of a file in the file tree.
+     *
+     * @remarks
+     * The entry's bytes are decoded as UTF-8 with the lenient WHATWG default. Use
+     * `getFileBytes()` for the undecoded bytes.
      */
     getFileContents(path: string): Result<string>;
+    /**
+     * Gets the raw bytes of a ZIP entry, with no text decoding applied.
+     *
+     * @remarks
+     * The returned array is the archive's internal buffer and must not be modified.
+     */
+    getFileBytes(path: string): Result<Uint8Array>;
+    /**
+     * Resolves a path to the ZIP file item it names.
+     * @param path - Path of the entry to look up.
+     * @returns `Success` with the item, or `Failure` if it is missing or is a directory.
+     */
+    private _getFileItem;
     /**
      * Gets the content type of a file in the file tree.
      */

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

@@ -43,6 +43,15 @@ export interface IProviderCompletionParams extends IChatRequest {
      * the effective merged effort is non-`'none'`; Gemini always accepts both.
      */
     readonly thinking?: IThinkingConfig;
+    /**
+     * Optional cap on generated output tokens, mapped to each provider's native field:
+     * Anthropic `max_tokens`, OpenAI Chat Completions `max_completion_tokens`, OpenAI/xAI
+     * Responses `max_output_tokens`, Gemini `generationConfig.maxOutputTokens`, and the
+     * xAI/Groq/Mistral/Ollama/`openai-compat` chat-completions path `max_tokens`. When unset,
+     * every provider except Anthropic omits the field and applies its own default; Anthropic's
+     * Messages API requires the field, so it falls back to `DEFAULT_ANTHROPIC_MAX_TOKENS`.
+     */
+    readonly maxTokens?: number;
 }
 /**
  * Calls the appropriate chat completion API for a given provider. Routes by

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

@@ -1 +1 @@
-{"version":3,"file":"apiClient.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/apiClient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"apiClient.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/apiClient.ts"],"names":[],"mappings":"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"}